From 5fd8fe808bc93b24e5ead33b456fb7e6e4143d2e Mon Sep 17 00:00:00 2001 From: weichen Date: Fri, 16 Oct 2026 06:31:36 +0000 Subject: [PATCH] Record goal and plan for the admin user create contract fix Why: UI account creation returns 400 (unknown field name) after the backend contract change; task card records root cause, scope and units. Evidence: precheck receipt /tmp/precheck-fix-admin-user-contract-20261016a.json (SELF). Impact: task card only; no product code. Refs: backend 8dfc223, b9c0a34 --- .task/fix-admin-user-create-contract.md | 38 ++++++++++++++----------- 1 file changed, 21 insertions(+), 17 deletions(-) diff --git a/.task/fix-admin-user-create-contract.md b/.task/fix-admin-user-create-contract.md index 58668edc..cfa3770c 100644 --- a/.task/fix-admin-user-create-contract.md +++ b/.task/fix-admin-user-create-contract.md @@ -7,17 +7,19 @@ - 权威仓：ssh://git@git-ssh.u1680832.nyat.app:31411/weichen/Agent-System-Dev.git；目标分支：main；R0（initial_base_sha）= 9edb011e63ab9bf104360379e52c30075bd2f344 - 工作区：/home/weichen/projects/Agent-System-Dev-wt-fix-admin-user-create-contract（worktree）；分支：fix/admin-user-create-contract -- 授权与交付终点：<本次允许的动作与终点；未授权事项写明> +- 授权与交付终点：修复管理员建号页 400（`json: unknown field "name"`）。终点为：frontend 仓契约迁移 PR 合入 → Dev 仓 bump frontend pin 合入 → 共享 dev 重新部署后 UI 建号链路实测可用。部署共享 dev 属已批准验证路径；不授权改后端契约、不做恢复 proposal 完整迁移（独立增量）。 - 交付模式：goal-first（目标、范围和交付终点一次确认；范围内连续推进） - 实施执行：agent-per-unit（配置：AGENT-EXECUTION.md） - 合入执行：agent（已授权交付范围内，Review 通过、冲突解决且当前 HEAD 的 CI 通过后合入） - 人工决策点：仅限目标/范围/验收变更、重大取舍、高后果操作或无法自动判定的业务验收 -- 当前阶段：需求拆解；当前增量：I1（待定义） +- 当前阶段：实施与自检；当前增量：I1（frontend 最小止血单元） - 流程依据：仓库根目录 policy/delivery.md（归档后仍按仓库根目录定位） ## 目标与非目标 -<预期结果、受影响入口/模块/契约；明确不做什么。> +- 背景：backend `8dfc223`（2026-10-14）将 `POST /api/admin/users` 契约从 `{owner,name,password,isAdmin}` 改为 `{owner,profile:{name,phone,email,staffNo,department,notes}}` 且 `decodeStrictJSON` 拒绝未知字段；`POST /api/admin/users/{owner}/login-keys` 被替换为 410 `RECOVERY_CONTRACT_REPLACED`。frontend pin（3bbb918）未跟进，共享 dev（backend 7aa6243 + frontend 3bbb918）上 UI 建号必 400，签发登录 Key 按钮 410。 +- 目标（I1 最小止血）：UsersPanel/api.ts 按新契约迁移——`createAdminUser` 发 `{owner, profile:{name}}`；移除初始密码输入、随机密码按钮与管理员勾选；建号成功提示改为待初始化 + CLI 发放激活 Key 指引；隐藏"生成登录 Key"入口（其 POST 已 410），随之清理仅由该入口使用的死代码；保持 knip/tsconfig/vitest/build 全绿；不新增裸色值/私有动效（DESIGN.md）。 +- 非目标：后端契约与恢复 proposal 前端完整迁移（独立增量）；e2e UI 建号场景（另有在途 fix-e2e-seed-credential-contract 适配 e2e 种子，避免碰撞，记为后续）；`GET/DELETE login-keys` 端点本身仍可用，保留 api 定义。 ## Agent 实施收据 @@ -29,32 +31,34 @@ ## 关联方向与规划 -- 适用状态：待核对（无适用规划时说明原因） -- 主记录路径/版本：待核对（路径按仓库根目录定位，归档后不变；只引用唯一正文） -- 对应里程碑：待核对 +- 适用状态：部分适用——本缺陷源自 IAM/账号管控线（backend 8dfc223 契约重设计）的 frontend 跟进缺口；该线主记录在 RDM 仓 requirements+U0 及 IAM U4 台账，本任务不修改其规划正文，只做交付层跟进。 +- 主记录路径/版本：RDM 仓 requirements（唯一正文）；frontend 完整迁移（recovery-proposals 视图）为其后续增量。 +- 对应里程碑：账号管控交付层可用性修复。 ## 需求分析 | ID | 描述 | 项目符合度及依据 | 优先级 | 验收条件 | 依赖 | 结论 | |---|---|---|---|---|---|---| -| R1 | 待填写 | 待评估 | 待定 | 待定义 | 待确认 | 待评审 | +| R1 | UI 建号请求符合新后端契约（`{owner, profile:{name}}`），不再 400 | 符合：backend accounts.go:321 `createAdminUser` + `decodeStrictJSON`；frontend api.ts:87 现状不符 | P0 | 对 backend 7aa6243 实测 POST /api/admin/users 返回 200 且账号创建成功 | backend pin 不变 | 纳入本增量 | +| R2 | UI 不再暴露已失效入口：初始密码/管理员勾选/签发登录 Key 按钮 | 符合：HTTP 建号不能设密码/授权限（store/account_model.go CreatePendingAccount）；issue 端点 410 | P0 | 界面无密码框、管理员勾选与"生成登录 Key"入口；残留死代码清理，lint/knip 干净 | R1 | 纳入本增量 | +| R3 | 建号后用户可拿到初始凭证并完成登录 | 符合：新契约由本地 CLI `user initialize-account` 发激活 Key，frontend 已有兑换入口 | P0 | 共享 dev 部署后实测：CLI 建号发 Key → 用户兑换设密 → 登录成功 | R1、部署 | 纳入本增量（部署验收） | ## 方案与计划 -- 方案引用：待填写（含对象版本） -- 实施计划引用：待填写（含增量与需求 ID） -- 测试计划引用：待填写（含需求 ID 与验收条件） +- 方案引用：本会话定位报告（2026-10-16，用户已批准）——推荐方案：仅迁移 frontend，不在后端加兼容层（避免削弱 `8dfc223` 的"HTTP 不能设密码/授权限"边界）。 +- 实施计划引用：I1 = U1（frontend 契约迁移单元，改动面：`src/api.ts`、`src/components/adminSections.tsx`，允许清理 `src/passwords.ts` 仅当其因此完全无引用）；随后 host 集成：frontend PR → Dev pin bump → 部署。 +- 测试计划引用：R1/R2 → worker 克隆内 `npm run build`（tsc）+ `npm test`（vitest）+ `npx knip`；host 权威验证 → Dev 仓 `make test`（组合 CI 同套件）+ 部署后真实 UI 链路（R3）。 ## 阶段记录 | 阶段 | 对象版本 | 状态 | 决策/执行者 | 时间 | 依据 | |---|---|---|---|---|---| -| 需求拆解 | 待定 | 待执行 | — | — | — | -| 需求评估 | 待定 | 待执行 | — | — | — | -| 需求表确认 | 待定 | 待执行 | — | — | — | -| 方案设计 | 待定 | 待执行 | — | — | — | -| 实施计划 | 待定 | 待执行 | — | — | — | -| 实施与自检 | 待定 | 待执行 | — | — | — | +| 需求拆解 | Dev 9edb011 + backend ab12fea + frontend 3bbb918 | 完成 | host 主模型 | 2026-10-16 | 本会话定位报告（console 400/410 + 源码对拍） | +| 需求评估 | 同上 | 完成 | host 主模型 | 2026-10-16 | 根因=跨仓契约断裂；CI 未覆盖 UI 建号路径 | +| 需求表确认 | 同上 | 完成 | host 主模型 | 2026-10-16 | R1–R3 见上表 | +| 方案设计 | 同上 | 完成 | 用户批准 | 2026-10-16 | 仅迁 frontend，不加后端兼容层 | +| 实施计划 | 同上 | 完成 | host 主模型 | 2026-10-16 | I1 单元包见收据 | +| 实施与自检 | 待定 | 进行中 | worker（agent-per-unit） | — | — | | 正式测试与验收 | 待定 | 待执行 | — | — | — | | 代码 Review | 待定 | 待执行 | — | — | — | | 合入 | 待定 | 待执行 | — | — | — | @@ -64,7 +68,7 @@ | 增量/试验 | 假设 | 范围 | 判断和停止条件 | 授权/决策依据 | 结果 | 变更影响 | 需重审补测 | |---|---|---|---|---|---|---|---| -| 待定义 | — | — | — | 待核对 | NOT_RUN | 待评估 | 待评估 | +| I1 | frontend 侧迁移即可恢复 UI 建号，无需后端改动 | frontend src/api.ts、adminSections.tsx（及因此无引用的 passwords.ts） | 建号 POST 200、build/vitest/knip 绿；否则回 host 评估 | 用户批准方案 2026-10-16 | NOT_RUN | 待评估 | 待评估 | ## 同步记录