docs: 固化 TaskTree native 开发验收
This commit is contained in:
Codex
@@ -5,6 +5,8 @@ description: HWLAB v0.3 TaskTree 开发与运维技能，覆盖 native PostgreSQ
|
||||
|
||||
# UniDesk TaskTree
|
||||
|
||||
本技能遵循 Skill(cli-spec)。
|
||||
|
||||
## 核心合同
|
||||
|
||||
- TaskTree 源码位于 HWLAB v0.3：
|
||||
@@ -12,7 +14,8 @@ description: HWLAB v0.3 TaskTree 开发与运维技能，覆盖 native PostgreSQ
|
||||
- `cmd/hwlab-tasktree-worker/main.ts` 与 `cmd/hwlab-tasktree-api/main.ts` 是独立入口；
|
||||
- `tools/src/tasktree-cli.ts` 只选择 transport，不复制业务逻辑；
|
||||
- `web/hwlab-cloud-web/src/views/projects/TaskTreeView.vue` 提供甘特图。
|
||||
- TaskGroup、Task、Subtask 分别对应 MDTODO FILE、ITEM、SUBITEM。
|
||||
- TaskGroup 对应 MDTODO FILE。
|
||||
- Task、Subtask、Subsubtask 对应 MDTODO 的三级任务层级。
|
||||
- Milestone 表达时间节点，ExecutionReport 归属 Task 或 Subtask。
|
||||
- PostgreSQL 唯一真相来自 UniDesk `config/platform-db/postgres-nc01.yaml`。
|
||||
- TaskTree 运行配置来自 UniDesk `config/hwlab-tasktree.yaml`。
|
||||
@@ -34,6 +37,10 @@ description: HWLAB v0.3 TaskTree 开发与运维技能，覆盖 native PostgreSQ
|
||||
|
||||
## Native-first 开发
|
||||
|
||||
- 开发等级遵循 `$unidesk-devlevel`：
|
||||
- 解析器、导入和 dispatcher 领域逻辑使用 L0；
|
||||
- HTTP、Temporal worker、PostgreSQL 和 HMR Web 联调使用 L1；
|
||||
- L1 收口前不得用 L2/L3 CI/CD 滚动代替本地反馈循环。
|
||||
1. 确认共享 Temporal 与 native PostgreSQL 已 ready，并动态解析 Temporal 地址。
|
||||
2. 只启动 worker：
|
||||
|
||||
@@ -66,8 +73,15 @@ HWLAB_TASKTREE_API_URL=http://127.0.0.1:6673 \
|
||||
```
|
||||
|
||||
- `--overapi` 只能切换 transport；命令、参数、DTO、输出 envelope 和错误语义必须保持一致。
|
||||
7. API 合同通过后，独立启动 HWLAB Cloud Web 的 Vite HMR 开发服务：
|
||||
- 前端代理指向 native API；
|
||||
7. API 合同通过后，启动 TaskTree standalone Vite HMR 开发服务：
|
||||
- 只挂载 `TaskTreeView`、最小 Router 和 Pinia；
|
||||
- 只把 `/v1/tasktree` 代理到 native API；
|
||||
- TaskTree API 模块必须通过 `@/api/client` 导入 `fetchJson`：
|
||||
- standalone Vite 将该入口替换为轻量 adapter；
|
||||
- 禁止使用绕过 alias 的相对 `./client`，否则会加载全量 RUM 并产生非 TaskTree 请求；
|
||||
- standalone API adapter 禁止触发 `/v1/web-performance` 等非 TaskTree 请求；
|
||||
- 禁止加载 Cloud Web `App.vue`、完整 router、认证 guard、Workbench 和其他 HWLAB 服务入口；
|
||||
- 浏览器出现 HWLAB 登录页、全量导航或非 TaskTree API 请求时，判定微服务 native 前端启动不合格；
|
||||
- 使用 `$unidesk-webdev` 的 custom/local `web-probe` 入口完成多视口和交互验收；
|
||||
- 修改前端时复用现有 HMR 与 API 进程，不触发镜像构建或 Kubernetes rollout。
|
||||
8. Native worker、CLI、API 和 HMR 前端全部收口后，才进入自动 CI/CD。
|
||||
@@ -79,7 +93,7 @@ HWLAB_TASKTREE_API_URL=http://127.0.0.1:6673 \
|
||||
|
||||
```text
|
||||
tasktree health
|
||||
tasktree group list|get|create|delete
|
||||
tasktree group list|overview|get|create|delete
|
||||
tasktree task create|update|delete
|
||||
tasktree milestone create
|
||||
tasktree report create
|
||||
@@ -88,15 +102,27 @@ tasktree timeline
|
||||
tasktree workflow start
|
||||
```
|
||||
|
||||
- 子任务通过 `task create --parent <task-id>` 建立。
|
||||
- 子任务通过 `task create --parent <task-id>` 建立：
|
||||
- Task 的子级是 Subtask；
|
||||
- Subtask 的子级是 Subsubtask；
|
||||
- Subsubtask 禁止继续创建下级。
|
||||
- 报告正文优先使用 `--body-file`，避免把多行内容放入 shell 参数。
|
||||
- MDTODO 导入规则：
|
||||
- MDTODO FILE 映射为 TaskGroup；
|
||||
- 顶层 R 项映射为 Task；
|
||||
- 更深 R 项映射为对应顶层 Task 的 Subtask，并保留完整 R 编号；
|
||||
- 三级及更深层级因 TaskTree 两级合同而压平，结果必须返回 `nested_task_flattened` warning；
|
||||
- `R2.9` 映射为 `R2` 的 Subtask；
|
||||
- `R2.9.1` 映射为 `R2.9` 的 Subsubtask；
|
||||
- 第四级及更深层级压平到受支持的第三级，并返回 `nested_task_flattened` warning；
|
||||
- 标题内容不得按冒号截断：
|
||||
- Markdown 链接中的 `https:` 必须完整保留；
|
||||
- URL 后面的标题正文也必须完整保留；
|
||||
- 正文中的本地 `任务报告` / `Task_Report` Markdown 链接自动读取并导入 ExecutionReport；
|
||||
- 报告文件缺失时保留任务并返回 `report_file_missing` warning；
|
||||
- CLI 在调用端读取 MDTODO 与报告文件的最后修改时间，并通过同一 import DTO 传给本地 dispatcher 或 API；
|
||||
- 缺少显式任务时间时，以 MDTODO 文件最后修改时间作为截止时间，开始时间为其前一天；
|
||||
- 任务存在报告时，以最新报告文件的最后修改时间替代 MDTODO 文件时间；
|
||||
- 父任务最终取自身与全部子任务时间区间的并集，必须覆盖最早子任务开始和最晚子任务截止；
|
||||
- 导入报告的 `createdAt` 使用报告文件最后修改时间；
|
||||
- 导入前先使用 `--dry-run` 核对 task、subtask、report、missing 和 flattened 计数；
|
||||
- 实际导入必须在单个 PostgreSQL 事务内完成。
|
||||
- `--overapi` 导入时：
|
||||
@@ -147,9 +173,36 @@ bun scripts/cli.ts web-probe console-verify \
|
||||
- group 深链刷新恢复；
|
||||
- 详情弹框边界；
|
||||
- execution report 使用安全 Markdown Viewer，并支持长报告内部滚动；
|
||||
- 未设置时间的任务不得伪造甘特条；
|
||||
- 普通任务未设置时间时不得伪造甘特条，MDTODO 导入任务按上述文件时间规则回填；
|
||||
- 大型 MDTODO 导入后的长标题、深层压平、折叠和纵向滚动；
|
||||
- 无 `pageerror`。
|
||||
- `/projects/tasktree` 默认显示全局 TaskGroup 甘特视图；
|
||||
- 全局概览由 PostgreSQL 单次聚合 API 提供，禁止前端逐组请求 timeline；
|
||||
- TaskGroup 使用比任务更粗的时间条，点击标题或时间条进入 `/projects/tasktree/:groupId`；
|
||||
- 详情页支持 Task、Subtask、Subsubtask 三级缩进和逐级折叠；
|
||||
- 单个父任务的可见后代超过 8 行时：
|
||||
- 左侧标题与右侧时间条分别使用同步的组内滚动视窗；
|
||||
- 初次加载和重新展开默认滚动到底部；
|
||||
- 视窗使用下沉阴影、滚动边缘提示和细窄滚动条；
|
||||
- 左侧任务栏桌面默认按视口比例计算，并继续支持拖拽调整；
|
||||
- 标题必须先占满可用单行宽度，再使用省略号；
|
||||
- 标题中的 Markdown 链接使用成熟 Markdown 渲染器显示为链接，不显示裸语法；
|
||||
- 时间刻度和画布宽度至少填满右侧可用区域，放大后才横向滚动；
|
||||
- 任务说明和执行报告共用一个 Markdown 阅读面板：
|
||||
- 工具栏保持紧凑单行；
|
||||
- 超长正文只能在阅读面板内部滚动；
|
||||
- 前后任务导航、时间和状态共用底部窄状态栏；
|
||||
- 任务详情使用可切换的双模式：
|
||||
- 弹窗模式高度约占视口 90%，底部保留窄状态栏；
|
||||
- 吸附模式形成左侧任务大纲、中间甘特图、右侧任务详情的 bounded 三栏布局；
|
||||
- 两种模式都提供上一个、下一个任务和父节点、当前节点、子节点导航；
|
||||
- 弹窗提供“吸附右侧”按钮，吸附栏提供“切换到弹窗”和关闭按钮；
|
||||
- 详情深链使用 `task=<task-id>` 恢复选中任务：
|
||||
- `detail=docked` 恢复右侧吸附模式；
|
||||
- 刷新后必须保持任务和详情模式；
|
||||
- 关闭详情时清理两个 query 字段；
|
||||
- 三栏模式必须保持 workspace 与详情栏等高、各栏内部滚动且 document 无横向或纵向溢出；
|
||||
- 窄详情栏中的 Markdown 链接、行内代码和长单词必须在阅读面板内换行；
|
||||
- console 不得出现错误，`pageerror`、失败请求和失败响应必须为零。
|
||||
- 临时 ID 只作为 smoke 证据，不得写入 owning YAML 或长期 skill。
|
||||
|
||||
## 配合技能
|
||||
|
||||
Reference in New Issue
Block a user