87 lines
4.4 KiB
Markdown
87 lines
4.4 KiB
Markdown
# 50 Admin：实现首次管理员初始化与网页登录
|
||
|
||
- 类型：需求
|
||
- 父级大工单：#14
|
||
- 所属 MVP / 版本：#15 / MVP
|
||
- 状态：已完成
|
||
- 日期：2026-08-09
|
||
- Gitea 工单：<http://ilaer.eicp.net:8418/chengma/cmautobuy/issues/50>
|
||
|
||
## 背景与目标
|
||
|
||
Admin 原有全部网页都可匿名访问，也没有管理员初始化、登录或退出能力。本任务
|
||
建立最小且完整的网页登录边界：首次运行由操作员创建唯一的首位管理员，随后
|
||
所有业务网页必须凭服务端 Session 访问，同时保持 Client API 的现有调用方式不变。
|
||
|
||
## 最终方案
|
||
|
||
- 新增 v6 迁移，在末尾追加 `users` 和 `web_sessions`，未改写 v1–v5；用户名
|
||
使用不区分大小写的唯一约束，角色和状态使用固定值约束。
|
||
- `/setup` 仅在用户表为空时开放；创建管理员前在写事务内再次检查，两个并发
|
||
初始化请求最多一个成功。入口一旦关闭，即使账号以后禁用也不会重新开放。
|
||
- 密码使用 bcrypt 默认成本哈希，服务层校验至少 8 个字符和 bcrypt 的 72 字节
|
||
上限；数据库、页面及日志均不保存或回显明文密码。
|
||
- 登录成功生成 32 字节密码学随机 Token，浏览器 Cookie 保存原文，数据库只保存
|
||
SHA-256。Session 固定 12 小时有效，退出和账号禁用会使旧 Session 失效。
|
||
- 认证 Cookie 使用 `HttpOnly`、`SameSite=Lax`、`Path=/`，HTTPS 请求自动增加
|
||
`Secure`；登录后的 `next` 只接受本站绝对路径，阻止开放重定向。
|
||
- Web 公开页和业务页都经过 CSRF；认证中间件只挂业务网页路由组。Client API
|
||
继续注册在独立路由组，不要求网页登录 Cookie，也不经过浏览器 CSRF。
|
||
- 增加独立初始化页和登录页；业务导航显示当前用户名，并用 POST 表单退出。
|
||
|
||
实际实现与工单确认方案一致。采购员管理、密码重置和登录限速留给 #51，Client
|
||
API Key 认证留给 #52，本任务没有扩大范围。
|
||
|
||
## 改了哪些
|
||
|
||
- `admin/repository/db.go`、`admin/model/model.go`、`admin/repository/user.go`：
|
||
v6 数据结构、用户与 Session 数据访问及初始化事务。
|
||
- `admin/service/auth.go`：首次初始化、bcrypt 密码校验、登录认证、Session 哈希与退出。
|
||
- `admin/handler/web/auth.go`、`admin/handler/web/web.go`：公开认证页、业务页中间件、
|
||
Cookie、本站回跳和退出路由。
|
||
- `admin/templates/auth/`、`admin/templates/partials/header.html`、
|
||
`admin/static/css/app.css`：初始化、登录和已登录导航界面。
|
||
- `admin/auth_integration_test.go`、`admin/handler/web/auth_test.go`、
|
||
`admin/service/auth_test.go`、`admin/repository/migrate_test.go`、`admin/main_test.go`：
|
||
迁移、并发、安全属性、HTTP 完整流程和回归测试。
|
||
- `docs/admin/03-data-model.md`：将 v6 用户与 Session 模型从规划更新为已实现。
|
||
|
||
## 验收结果
|
||
|
||
| 验收标准 | 结果 |
|
||
|---|---|
|
||
| v6 可从全新库和历史结构升级，且未改写旧迁移 | 通过 |
|
||
| 首次初始化并发请求最多创建一个管理员 | 通过 |
|
||
| 初始化完成后 `/setup` 永久关闭 | 通过 |
|
||
| 密码只保存 bcrypt 哈希，错误凭据统一提示 | 通过 |
|
||
| Session 原文不入库，固定 12 小时过期 | 通过 |
|
||
| 退出、过期和账号禁用后旧 Session 失效 | 通过 |
|
||
| Cookie 具备 HttpOnly、SameSite、Path 和 HTTPS Secure 属性 | 通过 |
|
||
| 登录回跳不能跳往外部网站 | 通过 |
|
||
| 所有 Web POST 均经过 CSRF | 通过 |
|
||
| Client API 不经过网页登录与浏览器 CSRF | 通过 |
|
||
| 1366×768 初始化、登录及已登录导航布局 | 通过 |
|
||
| Go 1.23.0 全量检查 | 通过 |
|
||
|
||
## 测试
|
||
|
||
- 执行的命令：
|
||
|
||
```powershell
|
||
cd D:\chengma\cmautobuy\admin
|
||
gofmt -l .
|
||
go vet ./...
|
||
go build ./...
|
||
go test ./... -count=1
|
||
```
|
||
|
||
- 结果：Go 版本为 `go1.23.0 windows/amd64`；全部通过，`gofmt -l .` 无输出。
|
||
- 浏览器验证：使用隔离的临时数据库，在 1366×768 完成 `/setup` 初始化、`/login`
|
||
登录并进入 `/shopee`；表单标签、密码框、提示、用户名和退出按钮均正常。
|
||
- **没验证到的部分**：没有在真实 HTTPS 服务上手工检查浏览器 Cookie，`Secure`
|
||
属性由带 TLS 请求的单元测试覆盖；没有触发真实采集或采购。
|
||
|
||
## 相关提交
|
||
|
||
- `0a7db40` feat: 实现 Admin 首次初始化与网页登录 (#50)
|