auto-sync: 2026-05-18 10:58:08

docs/design/v2.7-subtask-model.md

@@ -1,10 +1,10 @@
 # v2.7 数据模型设计：Project → Task → SubTask
 
 > 日期：2026-05-18
-> 版本：v2.0（经 08:02 ~ 10:50 讨论定稿）
+> 版本：v2.1（经 08:02 ~ 10:56 讨论 + 评审修正定稿）
 > 作者：庞统
-> 状态：待评审
-> 司马懿意见：Mail #302（背靠背讨论）、Mail #297（结论一致）
+> 状态：评审通过
+> 司马懿评审：Mail #298（2 必修 + 4 OBS，全部采纳）
 
 ---
 
@@ -145,14 +145,23 @@ parent_task TEXT  -- 子 Task 填父 Task 的 id，顶层 Task 为 NULL
 | 父 Task 状态 | 推导规则 |
 |-------------|---------|
 | `pending` | 所有子 Task 都是 pending，或无子 Task |
-| `working` | 有子 Task 在 working/claimed |
+| `working` | 有子 Task 在 claimed / working |
 | `review` | 有子 Task 在 review |
 | `done` | 所有子 Task 都是 done |
 | `failed` | 有子 Task failed 且无 active 子 Task |
 | `blocked` | 有子 Task blocked 且无 active 子 Task |
-| `cancelled` | 用户/AI 取消（手动设置） |
+| `cancelled` | 用户/AI 取消（手动设置，**不参与聚合**） |
 
-**聚合刷新时机**：每次 Ticker tick 时，扫描有子 Task 的父 Task，刷新聚合状态。
+**聚合优先级**（子 Task 同时满足多个条件时）：
+review > working > pending > blocked > failed
+
+**手动状态保护**：父 Task 被手动设为 cancelled 后，聚合不覆盖（与 Card 层的 MANUAL_STATUSES 机制一致）。
+
+**聚合刷新时机**：每次 Ticker tick 时，全量扫描有子 Task 的父 Task，刷新聚合状态。
+
+**边界条件**：
+1. 全量扫描（当前任务量 <100，性能无忧）
+2. 手动状态不覆盖（cancelled 的父 Task 不参与聚合）
 
 ### 2.3 示例数据
 
@@ -196,6 +205,8 @@ async def _tick_project(self, project_id, project_info):
     # 4. 调度 pending 子 Task（不变——和调度普通 Task 一样）
     # 5. 调度审查（不变）
     # 6. 【新增】聚合父 Task 状态
+    #    - 全量扫描所有有子 Task 的父 Task
+    #    - 跳过手动状态（cancelled）的父 Task
     refresh_parent_task_statuses(db_path)
     # 7. 写 daemon_tick 事件（不变）
 ```
@@ -237,12 +248,12 @@ async def _tick_project(self, project_id, project_info):
 | 文件 | 操作 |
 |------|------|
 | `src/blackboard/models.py` | 删除 Card dataclass + CARD_VALID_STATUSES + CARD_TYPE_SET + CARD_MANUAL_STATUSES |
-| `src/blackboard/db.py` | 删除 `_CARDS_SCHEMA`、`_migrate_v27()`；tasks DDL 移除 `card_id`、`stage`；保留其他所有内容 |
+| `src/blackboard/db.py` | 删除 `_CARDS_SCHEMA`、`_migrate_v27()`；tasks DDL 移除 `card_id`（**保留 `stage`**）；保留其他所有内容 |
 | `src/blackboard/operations.py` | 删除 CardOps 类全部方法 |
 | `src/blackboard/queries.py` | 移除 card_id 过滤参数 |
 | `src/api/card_routes.py` | **删除整个文件** |
-| `src/api/mail_routes.py` | **删除整个文件** |
-| `src/daemon/ticker.py` | 移除 per-card 扫描逻辑（`_tick_card`、`CardOps` 引用），恢复 per-project 直扫 |
+| `src/api/mail_routes.py` | **删除整个文件**（Mail Tab 延后，后续重新设计后端 API） |
+| `src/daemon/ticker.py` | 移除 per-card 扫描逻辑（`_tick_card`、`CardOps` 引用、`from ... import CardOps`），恢复 per-project 直扫 |
 | `src/main.py` | 移除 card_routes、mail_routes 注册；移除 v2.7 迁移调用；版本号保持 2.7.0 |
 | `tests/test_v27_cards.py` | **删除整个文件** |
 
@@ -328,3 +339,5 @@ async def _tick_project(self, project_id, project_info):
 | 10:03 | 用户 | 要求背靠背发给司马懿讨论 |
 | 10:10 | 司马懿 | 回复：留父子+依赖，砍引用，补充模板/实例关系 |
 | 10:50 | 用户 | 确认最终方案，要求更新设计文档并统一发评审 |
+| 10:56 | 司马懿 | 评审：2 必修 + 4 OBS，方向正确 |
+| 10:56+ | 庞统 | 全部采纳：claimed 归入 working、聚合优先级、手动状态保护、stage 保留、Mail 延后 |