PLM 协同接口规范（黑盒）

本文档定义 PLM 服务端需要提供的协同接口。

客户端通过这些接口与 PLM 交互，PLM 未实现时降级到本地 SQLite。

本规范是 PLM 服务端开发的需求定义，不是客户端实现。

一、PLM 需创建的 ItemType

1.1 Collaboration Task

ItemType: Collaboration Task
属性:
  task_code        string    任务编号 (CT-xxxx)
  task_type        string    任务类型 (identify/repair/generate/...)
  priority         integer   优先级 1-9
  intent           text      自然语言意图
  state            string    pending/running/completed/failed (映射到 Life Cycle)
  assigned_staff   string    分配的数字员工ID
  session_id       string    所属协同会话ID
  parent_task_id   string    父任务ID (任务分解)
  result_json      text      执行结果 (JSON)
  checkpoint_json  text      最新断点 (JSON)
  created_at       date
  completed_at     date

1.2 Collaboration Session

ItemType: Collaboration Session
属性:
  session_code     string    会话编号
  scenario         string    场景标识
  state            string    active/closed
  member_count     integer   成员数
  task_count       integer   任务数
  metadata_json    text      元数据 (JSON)

1.3 Task Checkpoint

ItemType: Task Checkpoint
属性:
  task_id          string    关联任务ID
  step_number      integer   步骤序号
  step_name        string    步骤名称
  state_json       text      完整执行状态 (JSON)

二、PLM 需创建的 RelationshipType

2.1 任务依赖（DAG边）

RelationshipType: Task Dependency
  source: Collaboration Task
  target: Collaboration Task
  含义: source 依赖 target 完成（target 是 source 的前置条件）

2.2 会话包含任务

RelationshipType: Session Contains Task
  source: Collaboration Session
  target: Collaboration Task

2.3 任务分配

RelationshipType: Task Assigned To
  source: Collaboration Task
  target: Digital Employee (或 User)

2.4 任务的断点

RelationshipType: Task Has Checkpoint
  source: Collaboration Task
  target: Task Checkpoint

三、PLM 需提供的服务端方法（Server Method）

3.1 Get Ready Tasks

方法名: plm_GetReadyTasks
输入: session_id
逻辑: 查询 session 下所有 state=pending 的 Collaboration Task，
      过滤出所有 Task Dependency 前置任务 state=completed 的任务
输出: 就绪任务列表

3.2 Batch Create Tasks

方法名: plm_BatchCreateTasks
输入: tasks[] (数组，含 title/type/priority/dependsOn)
逻辑: 单事务批量创建 Collaboration Task + Task Dependency 关系
输出: 创建结果列表

3.3 Get Task Tree

方法名: plm_GetTaskTree
输入: task_id, max_depth
逻辑: 递归查询 parent_task_id 和 Task Dependency 关系，构建任务树
输出: 嵌套任务树 JSON

3.4 Get Batch Status

方法名: plm_GetBatchStatus
输入: session_id
逻辑: GROUP BY state 统计任务状态
输出: { total, pending, running, completed, failed, ready, progress% }

3.5 Save Checkpoint

方法名: plm_SaveCheckpoint
输入: task_id, step_number, step_name, state_json
逻辑: 创建 Task Checkpoint + 关联到 Task
输出: checkpoint_id

3.6 Resume From Checkpoint

方法名: plm_ResumeFromCheckpoint
输入: task_id
逻辑: 查询最新 Task Checkpoint，恢复任务状态为 running
输出: { resumed, step_number, state_json }

3.7 Notify Task State Change（事件通知）

方法名: plm_NotifyTaskStateChange
触发: Collaboration Task state 变更时
逻辑: 调用配置的 webhook 或写入事件队列
输出: 通知已发送

四、PLM 需提供的 Life Cycle（状态流转）

4.1 Collaboration Task 生命周期

Preliminary → Submitted → In Progress → Completed
                                    ↘ Failed
                                    ↘ Cancelled

映射:

• pending → Preliminary
• running → In Progress
• completed → Completed
• failed → Failed

4.2 状态转换权限

• pending → running: 自动（getReadyTasks 选中后）
• running → completed: 自动（任务执行成功）
• running → failed: 自动（任务执行失败）
• 任意 → cancelled: 手动（人工取消）

五、客户端调用方式

客户端通过 AML 调用 PLM 接口，两种方式:

5.1 直接 AML 操作（CRUD）

<!-- 创建任务 -->
<Item type="Collaboration Task" action="add">
  <task_code>CT-xxxx</task_code>
  <task_type>repair</task_type>
  <title>修复BOM数据</title>
</Item>

<!-- 创建依赖关系 -->
<Item type="Task Dependency" action="add">
  <source_id>CT-A</source_id>
  <related_id>CT-B</related_id>
</Item>

<!-- 查询就绪任务 -->
<Item type="Collaboration Task" action="get">
  <session_id>SESSION-001</session_id>
  <state>pending</state>
</Item>

5.2 调用服务端方法（复杂逻辑）

<!-- 调用 plm_GetReadyTasks -->
<Item type="Collaboration Task" action="plm_GetReadyTasks">
  <session_id>SESSION-001</session_id>
</Item>

<!-- 调用 plm_BatchCreateTasks -->
<Item type="Collaboration Task" action="plm_BatchCreateTasks">
  <tasks_json>[{...},{...}]</tasks_json>
</Item>

六、降级策略

| PLM 能力 | 降级方案 | 说明 |

|----------|----------|------|

| ItemType 不存在 | 本地 SQLite | 客户端检测到 ItemTypeNotFoundException |

| Server Method 不存在 | 客户端模拟 | 用多次 AML 查询模拟复杂逻辑 |

| 关系查询不可用 | 本地 SQLite depends_on | JSON 数组存储依赖 |

| 事件通知不可用 | 轮询查询 | 客户端定时查询任务状态 |

| 批量操作不可用 | 逐条创建 | 降级为循环单条创建 |

七、50×100 场景的 PLM 侧优化建议

1. 关系索引: Task Dependency 的 source_id/related_id 建索引
2. 批量事务: plm_BatchCreateTasks 用单事务创建 5000 条
3. 图查询优化: plm_GetReadyTasks 用 SQL JOIN 而非逐条检查
4. 状态缓存: plm_GetBatchStatus 用物化视图或缓存表
5. 事件推送: plm_NotifyTaskStateChange 用 WebSocket/SSE 推送，避免轮询