# 技术设计与并行边界

## 共享模型

会话 JSON 新增可选字段：

```json
{
  "taskTracking": {
    "enabled": true,
    "statusId": "in_progress",
    "baseStatus": "in_progress",
    "source": "user",
    "reason": "",
    "summary": "",
    "progress": null,
    "reportingStatus": "reported",
    "version": 1,
    "enabledAt": "ISO-8601",
    "disabledAt": null,
    "statusUpdatedAt": "ISO-8601",
    "completedAt": null,
    "archivedAt": null,
    "archivedBy": null
  }
}
```

状态定义：

```json
{
  "id": "waiting_deploy",
  "label": "等待部署",
  "baseStatus": "waiting_user",
  "description": "实现完成，等待部署环境或发布窗口",
  "color": "#f59e0b",
  "order": 40,
  "system": false,
  "enabled": true
}
```

## 服务契约

MCP 对话负责产出 `lib/task-board-service.js`，导出：

```text
createTaskBoardService(deps)
  .getStatusDefinitions()
  .upsertStatusDefinition(input, actor)
  .removeStatusDefinition(id, migrateTo, actor)
  .listTasks(filters)
  .setTracking(sessionId, enabled, actor)
  .updateStatus(sessionId, update, actor)
  .setArchived(sessionId, archived, actor)
  .recordLifecycleEvent(sessionId, event)
```

服务通过依赖注入读取/保存会话和状态配置，不直接 import `server.js`。所有修改使用版本号和统一校验。

## WebSocket 契约

客户端请求：

- `task_board_query`
- `task_tracking_set`
- `task_status_set`
- `task_status_definition_upsert`
- `task_status_definition_remove`
- `task_archive_set`

服务端响应/广播：

- `task_board_result`
- `task_board_event`
- `task_tracking_result`
- `task_status_result`
- `task_status_definitions_result`
- `task_archive_result`

所有请求携带 `requestId`；所有写响应返回规范化任务、状态定义或稳定错误码。

## MCP 契约

### ccweb_task_status_list

无业务参数；来源会话从 MCP 上下文解析。返回 `trackingEnabled`、当前状态和状态定义。

### ccweb_task_update

```json
{
  "statusId": "in_progress",
  "reason": "可选，最长 2000 字符",
  "summary": "可选，最长 4000 字符",
  "progress": 0
}
```

`progress` 范围 0-100。跟踪关闭返回 `task_tracking_disabled`，未知状态返回 `task_status_unknown`。

## 生命周期契约

Hook 模块只接收事实事件，不自行读写文件：

```json
{
  "type": "turn_completed",
  "turnId": "可选",
  "occurredAt": "ISO-8601",
  "outcome": "completed",
  "pendingUserInput": false,
  "hadTaskStatusUpdate": false,
  "error": null
}
```

规则：

- 未开启跟踪：忽略。
- 用户消息：若归档则取消归档；状态进入 `in_progress`。
- turn started：非终态进入 `in_progress`。
- structured user input：进入 `waiting_user`。
- turn failed：进入 `blocked` 并记录错误。
- turn completed 且本轮无 MCP：保持状态，设置 `reportingStatus=missing`。
- 本轮已有 MCP：不得被 Hook 覆盖。

## 并行文件所有权

### 前端对话（只允许修改）

- `public/task-board.js`
- `public/task-board.css`
- `scripts/task-board-frontend-unit.js`

不得修改：`public/index.html`、`public/app.js`、`public/style.css`、`server.js`、`scripts/regression.js`。

### MCP/状态服务对话（只允许修改）

- `lib/task-board-service.js`
- `lib/task-board-mcp.js`
- `scripts/task-board-service-unit.js`

不得修改：`server.js`、`lib/ccweb-mcp-server.js`、`scripts/regression.js`、任何 `public/*` 现有文件。

### Hook 对话（只允许修改）

- `lib/task-board-lifecycle.js`
- `scripts/task-board-lifecycle-unit.js`

不得修改：`server.js`、`lib/codex-app-runtime.js`、`scripts/regression.js`、任何 `public/*` 文件。

### 集成对话（前三路完成后独占）

可以修改中心文件并调整前三路模块：

- `server.js`
- `lib/ccweb-mcp-server.js`
- `lib/codex-app-runtime.js`（仅必要时）
- `public/index.html`
- `public/app.js`
- `public/style.css`（优先不改，使用独立 CSS）
- `scripts/regression.js`
- 前三路新模块

## 视觉方向

- 视觉论点：延续 cc-web 的安静暗色操作界面，以克制的青色主强调和少量状态色构建密集、清晰的横向看板。
- 内容计划：顶层视图入口与工具条；横向状态工作区；归档视图；状态编辑面板。
- 交互论点：视图切换轻淡入、卡片悬停与状态变化使用短促位移/颜色过渡、窄屏保持流畅横向滚动。

## 验证命令

```bash
node --check lib/task-board-service.js
node --check lib/task-board-mcp.js
node --check lib/task-board-lifecycle.js
node --check public/task-board.js
node scripts/task-board-service-unit.js
node scripts/task-board-lifecycle-unit.js
node scripts/task-board-frontend-unit.js
node --check server.js
timeout 60s npm run regression
```

视觉验收使用隔离端口和临时配置目录启动测试服务，不提前重启 pm2 生产服务。

## 重启门禁

1. 调用 `ccweb_list_conversations(status="running")`。
2. 当前来源对话 ID 固定记录为 `56bb82c6-4fa3-4cb8-bb84-6969e6547d3a`；标题“设计任务看板状态机制”仅作人工交叉核验。
3. 三个实现对话和集成对话必须全部为 idle，且 `ccweb_list_pending_replies` 无 waiting/delivering。
4. 任何其他 conversation 状态为 running 都暂停重启并报告。
5. 满足条件后执行 `pm2 restart ccweb --update-env`，随后检查 pm2 状态和 HTTP/WebSocket 健康。