feat: 搭建 Admin 项目骨架(Go + Gin + html/template)

可运行的骨架:四个页面能打开、数据库自动建表、给 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>
This commit is contained in:
chengma
2026-08-06 16:33:45 +08:00
co-authored by Claude Opus 5
parent 0d38eedee1
commit 799ee33045
23 changed files with 1910 additions and 17 deletions
+39
View File
@@ -0,0 +1,39 @@
# testdata
自动化测试用的**脱敏小样本**放这里,**要提交进 Git**。
否则别人拉下仓库跑 `go test ./...` 会失败。
## 需要准备的文件
| 文件 | 用途 | 状态 |
|---|---|---|
| `shopee_sample.xlsx` | Excel 导入测试 | **待制作** |
## 怎么制作 `shopee_sample.xlsx`
从真实报表(`raw_data/蝦皮数据样本.xlsx`,需向项目负责人索取)里裁出来:
1. **只保留几十行**,但要覆盖这几种情况:
- 商品汇总行(`商品規格ID` 是 `-`);
- SKU 行,规格原文用**带【】**的格式,如 `黑色,M【建議40-50公斤】`;
- SKU 行,规格原文用**空格分隔**的格式,如 `卡其色拼黑色,L 建議50-57.5kg`;
- 至少一行**故意写成解析不了的格式**,用来验证 `parse_ok=0` 且不瞎猜。
前两种在真实数据里各占 53.4% 和 46.6%,两种都必须有用例。
2. **删掉全部商业指标列**——销售额、曝光次数、点击数、转化率、
买家数、回购率等等。导入根本用不到这些,留着就是泄露。
只保留:`商品ID`、`商品名稱`、`商品當前狀態`、`商品規格ID`、
`商品規格`、`規格當前狀態`、`商品選項貨號`、`主商品貨號`。
3. **商品名称换成无意义的占位文字**,如 `测试商品A`、`测试商品B`。
4. 记下期望结果,写进测试断言(例如 3 商品 + 8 SKU + 1 行解析失败)。
## 为什么不直接用真实报表
- 1.9MB,每次跑测试都读一遍太慢;
- 含逐商品的台币销售额,属于商业数据,已在 `.gitignore` 里排除。
相关规定见 `docs/admin/06-quality-security.md` §2.1。