docs(员工代收款): 新增路由前缀修复治理变更并勾选 AUG26-017 门禁
All checks were successful
构建并部署到测试环境(无 SSH) / build-and-deploy (push) Successful in 1m30s

- 新增 OpenSpec Change fix-employee-collection-route-prefix,承载已落地的 ff1362d 路由前缀修复(无规格 delta,skip_specs)
- 记录根因(Register 的 basePath 只服务文档)、影响面(7 条根级残留、15 条同层抢占)、修复方式与验证方式
- AUG26-017 全局健康门禁实际通过后勾选 5.7(tasks 27/27)
This commit is contained in:
2026-09-11 15:38:05 +08:00
parent 7891189712
commit 5ee8e3cb4a
5 changed files with 135 additions and 1 deletions

View File

@@ -0,0 +1,16 @@
## 1. 路由前缀修复(提交 `ff1362d`,已推送 `origin/Iteration/8-11`
- [x] 1.1 三个注册函数各引入 `router.Group("/<资源前缀>")`12 处 `Register` 首参由 admin 根路由组改为该 group`basePath` 与文档路径拼接不变。验证:`git show --numstat ff1362d``internal/routes/employee_collection.go`17 insertions / 12 deletions`grep -c "Register(group"` 为 12。
- [x] 1.2 确认 `/api/admin` 根级不再有员工代收款路由。验证:离线路由表扫描(真实 `RegisterAdminRoutes` + `openapi.BuildDocHandlers`)缺陷版 10 条根级栈条目 / 7 条不同 method+path 全部消失,路由总数 356 → 358。
- [x] 1.3 确认同层抢占候选为 0。验证同方法下先注册的参数路由命中后注册的静态路由缺陷版 29 条原始命中(按「方法 + 被抢占静态路由」去重 15 条),修复后为 0另以最小 Fiber 应用证明匹配按注册顺序(参数路由先注册时命中参数路由)。
- [x] 1.4 确认真实路由可达性。验证:装载真实注册函数与真实 handler 后请求,缺陷版 6 个命名 GET 返回 `400 / 1001 无效的路径ID``/api/admin/statistics` 返回 `503 / 2004`;修复版这些路径命中各自处理器(`403 / 1005` 权限拒绝),`/api/admin/statistics` 返回 `404 / 1006`
- [x] 1.5 确认契约与鉴权未变。验证:缺陷版、修复版与当前工作区三次 `go run cmd/gendocs/main.go` 产物逐字节相同md5 `274f45440597aaafb1e168ac266cbb85`,含路径、方法、鉴权标记与描述文本);`requireEmployeeCollectionConfigAccess``adminOnly` 的包装位置和数量不变。
- [x] 1.6 确认未触碰业务实现。验证:`ff1362d` 不包含 handler、application/service、domain、迁移或配置改动。
## 2. 本 Change 的门禁与归档
- [x] 2.1 变更在无 delta 形态下通过严格校验。验证:在 `/tmp``openspec/` 副本执行 `openspec validate fix-employee-collection-route-prefix --strict` 通过(输出 `Change 'fix-employee-collection-route-prefix' is valid`)。
- [x] 2.2 全量校验与既有条目共存。验证:同一副本 `openspec validate --all` 为 42 passed / 0 failed真实仓库对照为 41 passed / 0 failed差异仅为副本多出的本 Change
- [x] 2.3 变更不破坏上下文健康门禁。验证:把本 Change 放入仓库快照的 `/tmp` 全量副本(含 `e687a26` 的证据链与可达操作索引)后执行 `zsh ./scripts/context-health.sh`输出「Context 健康检查通过」、退出码 0。
- [x] 2.4 落地后在真实仓库运行 `./scripts/context-health.sh` 并确认输出「Context 健康检查通过」;该脚本会重写 `docs/admin-openapi.yaml`,须在并发流水线停止后执行。验证:在真实仓库(`HEAD=7891189`,含 `e687a26` 的证据链与可达操作索引执行输出「Context 健康检查通过」、退出码 0同时 `docs/admin-openapi.yaml` md5 仍为 `274f45440597aaafb1e168ac266cbb85`
- [ ] 2.5 归档本 Change`openspec archive`,不改动 `openspec/specs/**``docs/verification/context-reset/*.json`;归档预演结果见 design 的 Risks