cmautobuy/docs/task/49-admin登录与账号管理基线文档.md

49 Admin：更新登录与账号管理基线文档

• 类型：需求
• 父级大工单：#14
• 所属 MVP / 版本：#15 / MVP
• 状态：已实现，待验收
• 日期：2026-08-09
• Gitea 工单：http://ilaer.eicp.net:8418/chengma/cmautobuy/issues/49

背景与目标

Admin 原基线把用户登录列为 MVP 非范围。经用户确认，MVP 增加首次管理员初始化、网页登录和管理员维护采购员，同时必须保持 Client 四个接口行为不变。本任务先固定稳定方案，避免后续实现工单各自做不同决定。

最终方案

• 账号只有管理员和采购员两种固定角色，不开放公众注册和复杂 RBAC。
• 数据库没有用户时允许首次初始化一个管理员；初始化完成后服务端永久关闭该入口。
• Web 登录只保护 HTML 路由，Client API 路由不使用 Web Session。
• 规划 users 和 web_sessions 两张表；只保存密码哈希和 Session Token 哈希。
• 管理员可以创建、禁用、启用和重置采购员；采购员不能管理用户。
• 退出、密码重置和账号禁用会撤销对应 Session；系统保护最后一个有效管理员。
• 本任务不实现代码、迁移、Client 登录或 API Key。

实际方案与建单方案一致。

改了哪些

• docs/admin/01-requirements.md：更新 MVP 范围、角色和非目标。
• docs/admin/02-architecture.md：定义公开网页、受保护网页和 Client API 的路由边界。
• docs/admin/03-data-model.md：定义 v6 规划及用户、Session 表结构。
• docs/admin/05-ui-specification.md：定义初始化、登录和用户管理页面。
• docs/admin/06-quality-security.md：补充密码、Session、角色和 Client API 回归门禁。

验收结果

验收标准	结果
五份 Admin 基线对登录范围描述一致	通过
不存在固定默认密码和公开注册	通过
首次管理员只能初始化一次，并发最多一个成功	通过
管理员维护采购员，采购员不能管理用户	通过
Web 登录中间件不覆盖 Client API	通过
Session、密码哈希、CSRF、退出和禁用规则明确	通过
Client 四接口没有契约变化	通过

测试

• 执行的命令：
  • rg -n "初始化管理员|采购员|web_sessions|/api/v1/client|公开注册" docs/admin
  • git diff --check -- docs/admin
• 结果：关键规则均可检索；文档差异格式检查通过。
• 没验证到的部分：本任务没有实现 Go 代码和数据库迁移，尚未执行登录、Session、权限及 Client API 回归测试；这些由后续实施工单完成。

相关提交

• fc03388 docs: 定义 Admin 登录与账号管理基线 (#49)