chengmaandClaude Opus 5
f0d7da37cf
原来的采购任务页是骨架：var rows []gin.H 从不查库，页面永远为空； TODO 写的还是只查 task_type = 'purchase'。所以 #18 建出来的采集任务 在界面上哪儿都看不到——用户点完「创建采集任务」只能盯着 collect_status 猜。 模块名定为「采集采购」（用户指定），直接点出这页装的是哪两类任务， 比泛称「任务」更能让人一眼知道点进去看什么。路由 /tasks 不变， 改路由会让已有书签和文档链接全失效，没有收益。 列不按类型并列——两种任务字段完全不同，并列会让采集任务行一半是空列。 改成固定列 + 一列「目标」把业务信息概括成一句话： 采集 PDD 737116531267 采购 SO-001 · M/黑色 · 2件 · ≤¥42.00 拼接逻辑在 service 层，模板只负责显示。 统计和列表共用同一个筛选条件拼装函数。分开写的话总有一天会忘了 给统计也加条件，数字和表格对不上，操作员会以为页面坏了。 无主任务的客户端列显示「—」。#17 之后采集任务默认无主，这列会大量为空。 详情弹窗只读，采购专有字段（数量、价格上限、目标规格）在采集任务里 整段不出现，不显示空行。复用 #18 的弹窗机制，app.js 无需改动。 顺带清掉 PDD 页加进来之后一直没跟上的模块计数：多处「四个模块/四个页面」 改成五个。其中 06-quality-security.md 那两处是验证清单， 照着做的人只会测四个页面，PDD 页永远不在回归范围里。 Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
6.9 KiB
00 Admin 上手指南
- 文档状态：基线草案
- 读者：第一次接手 Admin 的开发者
- 目标：照着做完，能在自己电脑上把 Admin 跑起来，并知道下一步读哪份文档
这份文档只讲"怎么把环境搭好、怎么跑起来"。业务规则不在这里，见 文档索引。 遇到不认识的词（货运单、upsert、SKU 映射……），先查 术语表。
1. 准备电脑环境
| 需要什么 | 版本 | 怎么确认装好了 |
|---|---|---|
| Go | 1.23.0 | go version 输出 go version go1.23.0 windows/amd64 |
| Git | 任意较新版本 | git --version 有输出 |
| DB Browser for SQLite | 任意 | 用来看数据库，可选但强烈建议装 |
版本已定为 go1.23.0，写在 admin/go.mod 里。低于这个版本可能编译不过。
不需要装 gcc。 本项目的 SQLite 驱动是纯 Go 实现的
（modernc.org/sqlite），不依赖 cgo，这也是选它的原因——
go build 直接出单个 exe，不用配 C 编译器。
2. 拉依赖
先配国内代理，否则大概率拉不动：
go env -w GOPROXY=https://goproxy.cn,direct
正常情况下 go.mod 和 go.sum 已经在仓库里了，直接：
cd D:\chengma\cmautobuy\admin
go mod download
预期没有输出——Go 的惯例，成功时不打印东西。
万一需要重新拉依赖
[必须] 命令必须带版本号。 直接 go get github.com/gin-gonic/gin
会拉到最新版，然后报 requires go >= 1.25.0——因为这几个库的新版本
都已经不支持 Go 1.23.0 了。
go get github.com/gin-gonic/gin@v1.11.0
go get modernc.org/sqlite@v1.38.0
go mod tidy
写 Excel 导入功能时再把 excelize 加进来（现在没有代码 import 它，
go mod tidy 会把它去掉，这是 Go 的正常行为）：
go get github.com/xuri/excelize/v2@v2.9.1
这三个是在 Go 1.23.0 下实测能编译通过的最高版本， 为什么不能更高见 admin/AGENTS.md 技术栈一节。
[必须] go.mod 和 go.sum 都要提交 Git，否则别人拉下来版本对不上。
SQLite 驱动不要换成
mattn/go-sqlite3，那个需要 cgo， 得装 gcc，还会让go build出不了单文件 exe。
3. 跑起来
推荐在仓库根目录运行热重载脚本：
cd D:\chengma\cmautobuy
.\run_admin.bat
脚本第一次运行时会自动安装与 Go 1.23 兼容的
github.com/air-verse/air@v1.61.7，以后会直接使用已安装的固定版本。
保存 Go、HTML、CSS 或 JavaScript 文件后，Air 会自动重新编译并重启 Admin；
按 Ctrl+C 停止。
如果只想临时运行一次、不需要热重载，也可以：
cd D:\chengma\cmautobuy\admin
go run .
然后浏览器打开 http://localhost:8080。
这个命令是安全的：Admin 只管理数据，不会连手机、不会下单。放心随便跑。
4. 你应该看到什么
左边（或顶部）是五个模块的导航：
| 模块 | 干什么的 |
|---|---|
| 蝦皮数据 | 导入蝦皮商品报表，填 PDD 链接，发起采集 |
| PDD 商品 | 维护拼多多商品档案，发起采集，查看采回来的规格价格。这个页面不依赖蝦皮和顺运宝的任何数据，单独就能跑通"建商品 → 建采集任务 → 领走执行 → 提交结果 → 显示已采集"这条闭环，见 05 界面规范 §5 |
| 顺运宝数据 | 同步货运单，匹配规格，生成采购任务 |
| 采集采购 | 看采集和采购任务执行到哪一步了 |
| 客户端列表 | 看哪些客户端在干活 |
每个页面都是同一个结构：上面工具条 / 中间表格 / 下面状态条。 五个页面长得像是故意的，见 05 界面规范。
5. 常见报错
| 报错 | 原因 | 怎么办 |
|---|---|---|
go: command not found |
Go 没装或不在 PATH | 装 Go，重开 PowerShell |
dial tcp ... i/o timeout |
拉不到模块 | 配 GOPROXY，见第 2 步 |
no required module provides package |
依赖没装 | 回第 2 步跑那三条 go get |
listen tcp :8080: bind: ... |
8080 端口被占了 | 换端口：go run . -port 8081，或关掉占用的程序 |
| 页面全是没样式的白底黑字 | 静态文件没加载到 | 确认是从 admin/ 目录启动的，静态文件路径是相对的 |
database is locked |
有别的程序占着数据库 | 关掉 DB Browser 再试；程序运行时只读打开是可以的 |
| 导入 Excel 报错但没说哪一行 | 解析器没带行号 | 这是 bug，报错必须带行号，见 06 §2 |
6. 数据库在哪、怎么看
跟 Client 一样是便携模式——数据都在程序旁边的 data/ 里：
admin/data/
├── admin.db 数据库
├── logs/ 运行日志
└── uploads/ 上传的 Excel 原件
跑源码时在 admin\data\；将来打包成 exe 后，在 exe 旁边。
用 DB Browser for SQLite 打开 admin.db 就能看数据。
每张表什么意思见 03 数据模型。
写代码时不要自己拼这个路径，用统一的
DataDir()函数， 见 02 架构 §6。
7. 拿样本数据试一下导入
蝦皮的真实报表不在仓库里——里面有逐商品的台币销售额，属于商业数据，
已在 .gitignore 里排除。
需要的话找项目负责人要一份，放到仓库根目录的 raw_data/ 下：
raw_data/蝦皮数据样本.xlsx
参考样本是 11287 行 = 5195 商品汇总行 + 6092 SKU 行， 导入后应得到 5195 条商品 + 6092 条 SKU。数字对不上就是解析有问题。
写自动化测试不要用这份大文件，用
admin/testdata/下已脱敏的小样本， 见 06 质量与安全 §2.1。
解析规则见 03 数据模型 §3.3，那里说明了为什么一个文件要拆成两张表。
8. 提交代码前的自检
cd D:\chengma\cmautobuy\admin
go vet ./... # 静态检查，有问题会打印出来
go build ./... # 能编译
go test ./... # 测试能过
三条都没报错就算通过。完整验证要求见 admin/AGENTS.md §验证。
9. 接下来读什么
| 我要做的事 | 读这份 |
|---|---|
| 改页面、加表格列 | 05 界面规范 |
| 加字段、改表、写 SQL | 03 数据模型 |
| 改给 Client 的接口 | 04 Client 接口实现 + Client 侧契约 |
| 改 Excel 导入 | 03 数据模型 §3.3 |
| 搞不清这功能要不要做 | 01 产品需求基线 |
无论做哪一样，都必须先看一遍 admin/AGENTS.md（技术栈和红线）。