docs: preserve parallel UniDesk updates

2026-06-04 10:21:52 +00:00
parent 85b93d2cba
commit c5d85d5409
7 changed files with 320 additions and 45 deletions
@@ -60,6 +60,10 @@ Code Queue runner 也是分布式开发执行面。runner 镜像必须内置 `tr
 - 代理路径：只允许 `/api/` 前缀；允许方法为 `GET`、`HEAD`、`POST`、`DELETE`，用于保持 Todo Note 原有清单创建/删除、任务增删改、提醒、展开/收起、移动、撤销/重做等功能。
 - **写操作端点形态（2026-06-01 复盘 [#188](https://github.com/pikasTech/unidesk/issues/188) 固化）**：Todo Note 不走 REST 集合（如 `/api/instances/:id/todos`），所有 task 写都走 **action 队列**模式 `POST /api/instances/:id/actions` + body `{action: {type, ...}}`。已注册 action type：`addTodo` / `updateTodoTitle` / `toggleTodoCompleted` / `toggleTodoExpanded` / `setAllTodosExpanded` / `moveTodo` / `deleteTodo` / `renameInstance` / `setTodoReminder`。其他写端点：`POST /api/instances`（body `{name}` 新建清单）、`DELETE /api/instances/:id`、`POST /api/instances/:id/undo`、`POST /api/instances/:id/redo`。
 - **`TODO_NOTE_BACKEND_ONLY=1` 真实语义**：仅关闭 Todo Note 自带 Vite 前端 SPA，不阻挡任何已注册 API 路由（包括所有 POST/DELETE 写）。`/api/health` 暴露的 `backendOnly` 字段是观察用，不是读路径开关。看到 `404 {"error":"Todo Note is running in backend-only mode"}` 时的第一反应是路径写错（用了不存在的 REST 端点被 catch-all 兜底），不是写被 mode 锁。CLI 写操作范式见 `docs/reference/cli.md` 的 `microservice proxy` 段。
+
+- **Catch-all 误导文案 + CLI 改写 / 预检（issue #198 interim）**：上游 `gitee.com/Lyon1998/todo_note` 的 catch-all 把所有未注册路径都回 `404 {"ok":false,"error":"Todo Note is running in backend-only mode"}`，秘书/agent 看到这条第一反应容易误判成 "写被 mode 锁了"。UniDesk CLI 侧在 `microservice proxy todo-note` 检测到该特征 body 时会做就地改写，输出结构化诊断（`writableApiEndpoints`、`actionTypes`、`backendOnly: true`、`method`、`path`、`issueReference`、`upstreamBody` 完整保留原始误导文案用于审计），并把 `bodyRewritten: true` 显式返回；上游 catch-all 修复 PR 合并后改写自动退化为 no-op，CLI 不再覆盖。
+  - 同样在 CLI 侧提供 `--check-path` 预检：未命中时返回同源结构化诊断并**不调用 upstream**；命中时返回 `ok: true, matched: true, endpoint: {...}`。当前 `--check-path` 只支持 `service=todo-note`，对其他服务返回结构化 `unsupported` 错误。命令样例见 `docs/reference/cli.md` 的 `microservice proxy` 段。
+  - 验证门禁走 `scripts/src/e2e.ts` 的 `microservice:todo-note-route-diagnostic`（覆盖错路径 rewrite、命中 / 未命中 check-path、非 todo-note 服务的 unsupported）。该门禁是 CLI 侧 interim 自检，不替代上游 catch-all 修复 PR；上游落地后由 `bun scripts/cli.ts server rebuild todo-note` 拉新 commit 镜像，并继续用 `microservice health todo-note` + `microservice proxy todo-note /api/instances/<id>/actions` 验证。
 - UniDesk 前端：`用户服务 / Todo Note` React 页面负责展示清单列表、树形任务、筛选、提醒、拖放/上移下移、撤销/重做、字号控制和显式原始 JSON 按钮。

 Todo Note 在 UniDesk 语境中按纯后端服务管理：不得继续公开 Todo Note 自身 Vite/Web 前端，也不得把 `4211` 映射为公网端口。浏览器只能通过 UniDesk frontend 的 `/api/microservices/todo-note/...` 同源代理访问 Todo Note 后端。标准 artifact consumer 路径为 `bun scripts/cli.ts deploy apply --env dev|prod --service todo-note`；由于 Todo Note 源码仍在外部 Gitee 仓库，D601 registry 中必须先已有 `127.0.0.1:5000/unidesk/todo-note:<commit>`。Compose 在 recreate 时注入 `UNIDESK_TODO_NOTE_DEPLOY_*`，artifact consumer 的健康探针读取 `/api/health` 并合成 `deploy.commit` 和 `deploy.requestedCommit` 供强校验。