docs: 归档任务 #54

docs/task/54-客户端采购员归属管理.md

@@ -0,0 +1,75 @@
+# 54 Admin：建立客户端与采购员绑定管理
+
+- 类型：需求
+- 父级大工单：#14
+- 所属 MVP / 版本：#15 Admin 四模块可用闭环
+- 状态：已完成
+- 日期：2026-08-09
+- Gitea 工单：http://ilaer.eicp.net:8418/chengma/cmautobuy/issues/54
+
+## 背景与目标
+
+原有 Admin 用户与客户端互不关联，管理员无法维护客户端负责人，采购员登录后也会
+看到全部客户端。本任务建立可转交、可解绑且保留历史的负责人关系：管理员维护归属，
+采购员只读查看当前绑定给自己的客户端。
+
+## 最终方案
+
+- 数据库升级到 v7，新增 `client_user_assignments` 历史表；部分唯一索引保证
+  一台客户端同一时间最多一个负责人。
+- 首次绑定新增记录；转交在同一事务中结束旧记录并新建记录；解绑只结束当前记录。
+  每次变化记录时间和操作管理员。
+- 归属的 `client_id` 不关联删除：客户端清单被删除后，以同一稳定编号重新登记仍恢复归属。
+- 服务层按网页登录角色过滤客户端：管理员全量，采购员仅自己的客户端；同时提供
+  后续采购任务创建入口可复用的候选查询。
+- 绑定、转交、解绑和删除路由均要求管理员且保留 CSRF；采购员客户端页面没有写入口。
+- 归属关系不参与 Client API 认证或领取判断，也不修改任何既有任务。
+- 页面沿用现有表格和弹窗风格，显示文字负责人状态、明确表单标签、转交说明、
+  解绑二次确认和可被辅助技术读取的操作反馈。
+
+实际实现与建单方案一致。顺运宝采购任务创建仍是原有骨架，本任务只提供可复用的
+客户端候选查询，没有擅自扩大到采购任务创建全流程。
+
+## 改了哪些
+
+- `admin/repository/db.go`：追加 v7 迁移、索引和启动结构自检。
+- `admin/repository/client.go`：增加归属列表、可选采购员和事务化绑定/转交/解绑。
+- `admin/model/model.go`：增加客户端归属历史模型。
+- `admin/service/service.go`：增加角色可见范围、任务候选和管理员归属操作。
+- `admin/handler/web/others.go`、`web.go`、`user.go`：接入列表权限、管理路由和反馈。
+- `admin/templates/client/list.html`、`admin/static/js/app.js`：增加负责人列、只读视图、
+  绑定/转交弹窗和解绑确认。
+- `admin/service/client_test.go`、`admin/client_assignment_integration_test.go`、
+  `admin/repository/migrate_test.go`：覆盖业务约束、HTTP 权限、模板和迁移路径。
+- `docs/admin/01-requirements.md`、`03-data-model.md`、`05-ui-specification.md`、
+  `06-quality-security.md`：同步稳定需求和约束。
+
+## 验收结果
+
+| 验收标准 | 结果 |
+|---|---|
+| 管理员绑定未绑定客户端 | 通过 |
+| A→B 转交只保留 B 为当前负责人，旧记录保留 | 通过 |
+| 管理员确认后解绑，客户端回到未绑定 | 通过 |
+| 一人多客户端且一台客户端唯一当前负责人 | 通过 |
+| 管理员全量可见；采购员只读且只见自己的客户端 | 通过 |
+| 禁用采购员不能成为新绑定目标 | 通过 |
+| 绑定、转交、解绑记录操作管理员和时间 | 通过 |
+| 删除并以同一 `client_id` 重新登记后仍识别归属 | 通过 |
+| 归属变化不修改既有任务 | 通过 |
+| Client 四接口契约保持通过 | 通过 |
+| 1366×768 下表格、弹窗和反馈可用 | 通过 |
+| 格式、静态检查和全量测试通过 | 通过 |
+
+## 测试
+
+- 执行的命令：`cd admin; gofmt -w .; go mod verify; go vet ./...; go test ./...`
+- 结果：模块校验成功，`go vet` 无告警，所有 Go 测试通过。
+- 浏览器验证：使用隔离临时数据库和 Chrome，1366×768 下实际完成初始化管理员、
+  创建两名采购员、登记客户端、绑定、转交和解绑；页面宽度 1366，无整页横向溢出，
+  表格容器无需横向滚动，弹窗完整位于视口内，复查请求无 4xx/5xx。
+- **没验证到的部分**：未拿生产环境 `admin.db` 副本执行升级；未进行用户人工验收。
+
+## 相关提交
+
+- `e0c0dac` feat: 增加客户端采购员归属管理 (#54)