docs(plan): 回写 A1 部门管理补强

背景： - 部门管理已实现（独立页面 /system/departments、只停用不删除、有成员/启用子部门禁止停用），需要同步计划、规范与实施报告。改动： - 开发计划：新增 WBS A1-BE-05（部门接口）与 A1-FE-04（部门管理页）， A1 进度更新为 10/10、测试计数与「补强」说明；附录 C 增加 /system/departments，§7.1 页面/接口清单更新；版本记录增补。 - A1 实施报告：范围表、契约/后端/前端交付物、测试计数与验证表补充部门管理；新增 §2.5 部门管理补强（口径、规则、覆盖范围）与遗留项。 - 11-前端路由与目录规范：管理中心模块表补 /system/departments （pages/system/departments/），版本 V1.1。影响面： - 仅文档；与已提交的代码行为一致，不改变其它批次范围。回滚方式： - 回滚本提交即恢复文档原状；不影响代码。验证证据： - pnpm format:check 通过； - 文档中的测试计数、接口与页面路径与 feat(identity) 提交一致。
2026-11-03 15:02:14 +08:00
1 parent 6661c42e84
commit 981757b76c
@@ -25,6 +25,7 @@
 | V0.1（进度回写） | 2026-11-02 | A0 工程骨架与契约基线完成：批次总览增加状态列、A0 WBS 标注完成、回写执行证据与偏差；不改变原计划范围与验收口径 |
 | V0.1（进度回写 A1） | 2026-11-03 | A1 身份认证与用户管理完成：批次总览更新 A1 状态、A1 WBS 标注完成、回写执行证据与遗留；不改变原计划范围与验收口径 |
 | V0.1（路由规范回写） | 2026-11-03 | 「平台」更名「管理中心」，前端路由统一为 `/<模块>/<功能>`（A1 用户页改为 `/system/users`）；同步附录 C 页面清单与前端目录约定，不改变功能范围与验收口径 |
+| V0.1（A1 部门管理补强） | 2026-11-03 | 补 `/system/departments` 部门管理：WBS 增 A1-BE-05 / A1-FE-04，补页面与接口清单；只停用不删除、有成员/启用子部门禁止停用；不改变其它批次范围 |

 ### 0.2　引用约定

@@ -394,7 +395,7 @@ flowchart LR

 > **A0 进度（2026-11-02）**：✅ 已完成。10/10 项 WBS 通过；本批门禁 `format:check / lint / typecheck / test / build / test:int / openapi:export / openapi:diff / e2e` 与本地 CI `pnpm ci:local` 全绿；`/health`、`/api/docs`、web 布局与登录壳、worker 启动均实测通过。实现记录与偏差见 [A0 实施报告](./灵犀_A0工程骨架与契约基线_实施报告_V0.1.md)。环境适配：本地 PG/Redis 复用已有 Docker、对象存储使用公网 RustFS、种子仅 `system_configs`（`Q-A0-01`）、Gitea 暂无 runner 时以 `pnpm ci:local` 为准。
 >
-> **A1 进度（2026-11-03）**：✅ 已完成。8/8 项 WBS 通过；`format:check / lint / typecheck / test` 全绿（shared 95 / api 60 / web 55），`test:int` 7 项（真实 PG / Redis），A1-QA-01 浏览器 e2e 6/6；登录 → 首次登录强改 → 用户列表 / 新建 / 详情 / 停用启用 / 角色调整 / 客户转交占位全链路实测。实现记录、口径与遗留见 [A1 实施报告](./灵犀_A1身份认证与用户管理_实施报告_V0.1.md)。已知遗留：六类数据范围（A2）、客户转交真实接口（A3）、审计落库（A5）。
+> **A1 进度（2026-11-03）**：✅ 已完成。10/10 项 WBS 通过；`format:check / lint / typecheck / test` 全绿（shared 121 / api 90 / web 120），`test:int` 33 项（真实 PG / Redis），A1-QA-01 浏览器 e2e 6/6；登录 → 首次登录强改 → 用户列表 / 新建 / 详情 / 停用启用 / 角色调整 / 客户转交占位全链路实测。**补强**：`/system/departments` 部门管理（两级组织树、负责人/排序、只停用不删除、停用拦截）已落地并联调。实现记录、口径与遗留见 [A1 实施报告](./灵犀_A1身份认证与用户管理_实施报告_V0.1.md)。已知遗留：客户转交真实接口（A3）、审计落库（A5）。
 >
 > **A2 进度（2026-11-03）**：✅ 已完成。8/8 项 WBS 通过；H1 权限门已确认并记录 [ADR-001](../adr/ADR-001-权限点目录与六类数据范围.md)；UI 门三套原型独立评审 A 8 / B 8 / C 7，用户选定 **B 主从分栏**。`format:check / lint / typecheck / test` 全绿（shared 119 / api 85 / web 102），`test:int` 27 项（真实 PG / Redis），A2-QA-01 浏览器 e2e 1/1（复跑通过）；角色可配、SoD 40304、特殊权限默认关闭、六类范围解析与 `ScopeContext` 全链路、系统角色保护、变更审计与 outbox 均实测。实现记录、口径与遗留见 [A2 实施报告](./灵犀_A2角色权限与数据范围_实施报告_V0.1.md)。已知遗留：A3 前客户目录为空集、A5 审计落库、DP-14 两项特殊权限、导航模块级权限口径。

@@ -541,9 +542,11 @@ PRD §7 把 **M-27（素材元素级拆解）** 与「自动字幕 → TTS 配
 | A1-BE-02 | 认证与会话 | BE | 账号密码登录（Argon2）、JWT access + refresh 旋转、`jti` 吊销、登出、失败次数限制、密码策略；SSO 适配器接口（不实现） | A0-BE-02 | 登录 → 刷新 → 登出全链路；旧 refresh 立即失效；错误码 40101 / 40102 正确 | 1.0 | ✅ |
 | A1-BE-03 | 守卫链与审计拦截 | BE | `JwtGuard` → `PermissionGuard` → `SpecialPermissionGuard` → `ScopeGuard` 骨架 → 业务校验；`@Audit()` 装饰器与请求上下文（用户、客户、trace_id） | A1-BE-02、A0-SH-01 | 无 token 401；无权限点 40301；守卫顺序可单测 | 1.0 | ✅ |
 | A1-BE-04 | `/me` 与权限上下文 | BE | 当前用户、角色、权限点集合、数据范围、可见客户集合；权限变更即时生效（不缓存旧权限） | A1-BE-03 | `/me` 与登录返回一致；角色变更后下一次请求生效 | 0.5 | ✅ |
+| A1-BE-05 | 部门管理补强 | BE | `GET /departments/tree?include_disabled`、`POST/PATCH /departments`、`POST /departments/{id}/disable|enable`；负责人/排序；只停用不删除；有在职成员或启用子部门禁止停用 | A1-BE-01 | 两级/超两级/重名/负责人校验；停用三类拦截；无 DELETE | 0.5 | ✅ |
 | A1-FE-01 | 登录与会话 | FE | 登录页、token 存储与刷新、登出、会话过期跳转、路由回跳 | A0-FE-03 | 登录 → 刷新页面仍在线；token 过期自动刷新一次；刷新失败回登录 | 0.5 | ✅ |
-| A1-FE-02 | 用户管理页 | FE | 用户列表（游标分页 / 筛选）、新建 / 编辑、停用确认、部门树、角色多选、客户转交入口 | A0-FE-02 | 列表可分页筛选；停用需二次确认；页面按 `user:manage` 隐藏写操作 | 1.0 | ✅ |
+| A1-FE-02 | 用户管理页 | FE | 用户列表（游标分页 / 筛选）、新建 / 编辑、停用确认、部门筛选、角色多选、客户转交入口 | A0-FE-02 | 列表可分页筛选；停用需二次确认；页面按 `user:manage` 隐藏写操作 | 1.0 | ✅ |
 | A1-FE-03 | 权限上下文与路由守卫 | FE | `/me` 全局缓存、权限点 Hook（`usePermission`）、路由级与按钮级控制、403 页 | A1-FE-01 | 无权限路由被拦截；按钮级无权限不渲染（非 `removeChild` 式隐藏） | 0.5 | ✅ |
+| A1-FE-04 | 部门管理页 | FE | `/system/departments` 两级组织树 + 详情/内联编辑 + 新建部门/小组 + 停用/启用二次确认；显示已停用、`?id=` 选中可恢复 | A1-FE-01、A1-FE-03 | 无 `user:manage` 只读；停用被拒有明确提示；刷新恢复选中 | 0.5 | ✅ |
 | A1-QA-01 | 账号生命周期用例 | QA | 登录 / 刷新 / 登出 / 停用 / 角色变更 / 越权 6 类用例 | A1-BE-04 | 用例全部通过并进 CI | 0.5 | ✅ |

 **本批门禁**：登录闭环；用户生命周期可演示；权限有 / 无用例通过（范围外 ScopeContext 随 A2 补齐）；审计已记录登录与用户变更（当前为结构化日志，落库随 A5）。
@@ -917,8 +920,8 @@ PRD §7 把 **M-27（素材元素级拆解）** 与「自动字幕 → TTS 配

 | 项 | 内容 |
 | --- | --- |
-| 页面 | `/login`、`/system/users`、`/system/users/new`、`/system/users/:id`、部门树（内嵌用户页） |
-| 接口 | `POST /auth/login`、`/auth/refresh`、`/auth/logout`、`GET /me`、`GET /users`、`POST /users`、`PATCH /users/{id}`（含角色分配）、`POST /users/{id}/transfer-customers` |
+| 页面 | `/login`、`/system/users`、`/system/users/new`、`/system/users/:id`、`/system/departments`（部门管理） |
+| 接口 | `POST /auth/login`、`/auth/refresh`、`/auth/logout`、`GET /me`、`GET /users`、`POST /users`、`PATCH /users/{id}`（含角色分配）、`POST /users/{id}/transfer-customers`；`GET /departments/tree`、`POST/PATCH /departments`、`POST /departments/{id}/disable`、`/enable`（不提供删除） |
 | 关键规则 | 部门最多两级；手机号唯一；一人可多角色；离职**停用不删**，名下客户必须转交；超管建议 ≤ 2 人、授予二次确认并审计；停用即时生效 |
 | 页面状态 | 空态（无用户 / 无搜索结果）、加载骨架、错误重试、无权限 403；停用用户列表默认隐藏、可筛选查看 |
 | 验收 | ① 新建用户 → 分配角色 → 登录成功；② 停用后无法登录且在线会话失效；③ 删除按钮不存在，只有停用；④ 部门超两级被拒；⑤ 用户变更进审计 |
@@ -1374,6 +1377,7 @@ infra/：compose、Nginx、监控、备份脚本占位
 | --- | --- | --- | --- |
 | `/login` | 登录 | 公开 | A1 |
 | `/system/users`、`/system/users/new`、`/system/users/:id` | 用户与部门 | `user:view` / `user:manage` | A1 |
+| `/system/departments` | 部门管理（两级组织树、停用/启用） | `user:view` / `user:manage` | A1 |
 | `/system/roles`、`/system/roles/:id` | 角色管理 | `role:view` / `role:manage` | A2 |
 | `/system/industries` | 行业管理 | `industry_pack:view` / `customer:manage` | A3 |
 | `/system/customers`、`/system/customers/new`、`/system/customers/:id` | 客户管理 | `customer:view` / `customer:manage` | A3 |