chengmaandClaude Opus 5
799ee33045
可运行的骨架：四个页面能打开、数据库自动建表、给 Client 的三个接口
按契约响应。业务逻辑留 35 处 TODO(骨架)，每处标明要点和文档章节。
结构（对应 docs/admin/02-architecture.md §2/§3）
- handler/web + handler/api 分开：页面要 CSRF、出错渲染错误页；
接口要认证、出错返回 JSON。混在一起迟早写错
- service 不认识 *gin.Context，方便不起服务器直接单测
- 只有 repository 能写 SQL
- 模板用 {{define "目录/名字"}}，一次全部 ParseFS 进来不冲突
- 模板和静态资源用 //go:embed 打进二进制
已实测（Go 1.23.0，本机验证）
- go build / go vet / gofmt 全部通过
- 单文件产物 34MB，无需 cgo
- 四个页面 + 静态资源均 200，/ 正确 302 到 /shopee
- 建表 7 张 + 索引 10 个，user_version=1，二次启动不重复建表
- claim 带 X-Client-Id 返回 204（无任务可领），
缺 X-Client-Id 返回 400 + 契约格式的 JSON 错误体
依赖版本被 Go 1.23.0 卡死，已钉住并写进文档
- gin v1.11.0 （v1.12.0 起要求 Go >= 1.25.0）
- modernc.org/sqlite v1.38.0（v1.40.0 起要求 >= 1.24.0，v1.48.0 起 >= 1.25.0）
- excelize v2.9.1 （尚未入 go.mod，写导入功能时再加）
直接 go get 不带版本会拉到最新版并报 requires go >= 1.25.0，
所以文档里的命令一律带版本号。要升依赖就得先升 Go。
一处主动调整：迁移语句从「一个字符串装多条 SQL」改成 [][]string 逐条执行。
database/sql 的 Exec 对一次多条语句的支持因驱动而异，拆开最稳妥，
报错还能精确到第几条。
说明：Gitea 尚未配置，本次无对应工单号。
admin/testdata/ 只有 README，脱敏小样本需人工制作。
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
6.5 KiB
6.5 KiB
Admin 子项目规则
本文件适用于 admin/ 下的全部代码、模板和测试，并继承仓库根目录 AGENTS.md 的
红线、工作流、Git、安全、文档和初级程序员维护规则。
开始工作前
- 从仓库根目录执行 Admin 任务时，也必须先读取本文件。
- 第一次接手，先看这两份：
- 只读取与当前任务有关的长期基线，不必每次加载全部文档：
- Admin 提供的接口必须满足 Client 侧契约 docs/client/04-admin-api-contract.md， 两边不一致时以 Client 契约为准，要改先走工单。
技术栈
Go 版本固定 1.23.0。 依赖版本受它约束，见下面的表。
- 固定使用 Go + Gin + Go 标准库
html/template。 - 数据库固定 SQLite，驱动固定
modernc.org/sqlite。 不得改用mattn/go-sqlite3—— 那个要 cgo，Windows 上得装 gcc， 交叉编译和打包 exe 都会变得很麻烦。 - Excel 读取固定
github.com/xuri/excelize/v2。
依赖版本已钉死，不要随手升
| 依赖 | 固定版本 | 为什么不能用更新的 |
|---|---|---|
github.com/gin-gonic/gin |
v1.11.0 | v1.12.0 起要求 Go ≥ 1.25.0 |
modernc.org/sqlite |
v1.38.0 | v1.40.0 起要求 Go ≥ 1.24.0，v1.48.0 起要求 ≥ 1.25.0 |
github.com/xuri/excelize/v2 |
v2.9.1 | v2.10.0 要求 Go ≥ 1.24.0，v2.11.0 要求 ≥ 1.25.0 |
excelize 目前还不在
go.mod里——导入功能还没写，没有代码 import 它，go mod tidy会把它去掉，这是 Go 的正常行为。写导入功能时用go get github.com/xuri/excelize/v2@v2.9.1加进来。
这三个版本是在 Go 1.23.0 下实测能编译通过的最高版本。
[必须] 直接跑 go get <包名>（不带版本）会拉到最新版，然后报
requires go >= 1.25.0。拉依赖要带版本号，见
00 上手指南 §2。
[必须] 要升依赖就得先升 Go，这是一个决定不是两个。
升 Go 属于会影响构建的变更，先过工单。
- 实际版本以
admin/go.mod/go.sum为准，这两个文件都要提交 Git。 - 新增或升级依赖前先过工单。
前端约束
- 不得引入 React、Vue、Angular 等前端框架，不得引入 npm 构建流程。 页面一律服务端渲染。
- 搜索、删除、导入这类操作用普通表单提交，零 JavaScript。
- 勾选、弹窗、导入进度确实需要 JS，只允许两种做法：
- 原生 JavaScript，直接写在模板里或放
static/js/下的独立文件； - htmx（单个 js 文件，无构建步骤）。
- 原生 JavaScript，直接写在模板里或放
- 不得引入打包器（webpack/vite/esbuild）。CSS 手写，放
static/css/。
代码分层
handler只负责解析请求、调用 service、渲染模板或返回 JSON，不写业务逻辑，不拼 SQL。service放业务逻辑（导入解析、创建任务、匹配复用），不认识 Gin 的*gin.Context。repository封装 SQLite，只有这一层能写 SQL。model只放数据结构，不导入 Gin 和数据库驱动。- 给 Client 的接口和给浏览器的页面分开放（
handler/api/和handler/web/）， 两者的错误格式、认证方式都不一样，混在一起迟早出事。
数据与接口
- 表结构以 03 数据模型 为准。
- 给 Client 的接口以 docs/client/04-admin-api-contract.md 为准。
[必须]金额一律用整数存，人民币用分、台币用分，字段名带单位后缀（_cent）。 禁止用 float 存金额。[必须]时间一律带时区 ISO 8601，库里存 UTC，页面上转本地时区显示。[必须]Excel 导入只做 upsert（更新或新增）， 绝不允许先清空再导入 —— 会把人工填的 PDD 链接全洗掉。[必须]蝦皮规格原文（spec_raw）永远保留，解析不出来就留空，不要瞎猜。[必须]Client 提交结果时，不管任务是否已取消、是否已重派，一律接受， 理由见 Client 契约 §6.1。这条最容易被顺手违反。
界面规则
- 四个模块统一使用三段式布局：顶部工具条 / 中间带勾选的表格 / 底部状态条。 第一个页面写完，其余三个照抄结构改字段，不要给某个模块搞特殊。
- 表格行的身份用业务主键，不得用行号。
- 批量删除必须二次确认，并显示"将删除 N 条"。
- 破坏性操作（删除、导入覆盖）用 POST，不得用 GET。
- 页面必须能在 1366×768 上正常使用，表格横向滚动而不是压缩列宽。
安全
- 根目录
AGENTS.md的五条红线同样适用。 [必须]所有写操作（新增/编辑/删除/导入/建任务）加 CSRF 防护。[必须]SQL 一律用参数化查询，禁止字符串拼接 SQL。[必须]模板输出走html/template的自动转义， 禁止用template.HTML包裹用户可控内容。[必须]上传的 Excel 限制大小和扩展名，解析失败要有明确报错，不能让整个进程崩掉。[必须]日志、页面、导出里不得出现 token、密码、Cookie。
验证
全部命令从 admin/ 目录执行。
go vet ./...
go build ./...
go test ./...
go run .
go run .启动后访问http://localhost:8080，不会连手机、不会下单，可随时运行。- 修改数据库时测试首次建库和从上一版本迁移。
- 修改给 Client 的接口时，跑契约测试，确认仍满足 Client 侧 §6.1 的无条件接受。
- 修改 Excel 导入时用
raw_data/下的样本跑一遍，核对导入条数。 该样本含商业数据、不在仓库里，需向项目负责人索取；自动化测试用testdata/下的脱敏小样本。 - 交付时说明已运行的命令、结果和未验证的部分。