Files

T

chengmaandClaude Opus 5 90379347b4 docs: 建立 Admin 子项目的文档基线

仓库从单子项目变成两个：client（Python + PyQt5 桌面端）和
admin（Go + Gin + HTML 模板 Web 管理端）。两者技术栈完全不同，
规则各自独立，只通过三个 HTTP 接口交互。

新增 admin/AGENTS.md 和 docs/admin/ 共 9 份文档，结构与 docs/client/ 对齐。

关键设计决策（均已与用户确认）
- 四模块：蝦皮数据 / 顺运宝数据 / 采购任务 / 客户端列表，
  统一三段式布局（工具条 / 带勾选的表格 / 状态条）
- 蝦皮数据拆成商品表 + SKU 表：报表本身就是两层结构，
  且 PDD 链接是商品级的，放 SKU 级会重复维护
- pdd_data 存商品级，一个 PDD 商品采一次，所有订单共用
- SKU 映射独立成表且可复用，同一蝦皮 SKU 只需人工匹配一次
- PDD 链接人工填写，采集按钮就放在填链接的编辑弹窗里
- 任务分配给指定客户端；不加心跳，注册在领取时完成，
  在线状态由 last_seen_at 派生
- SQLite 驱动固定 modernc.org/sqlite（纯 Go 免 cgo，go build 直接出 exe）
- 不引入前端框架和 npm 构建，只允许原生 JS 或 htmx

基于样本文件 raw_data/蝦皮数据样本.xlsx 实测得出的约束
- 11287 行 = 5195 商品汇总行 + 6092 SKU 行，导入必须分开处理
- 商品規格ID 零重复，是天然主键
- 规格原文两种格式各占 53.4% / 46.6%，只解析【】会漏掉一半
- 平均每商品仅 1.17 个 SKU，报表不是全量目录，
  因此必须支持手动新增，且货运单外键不能加硬约束

同步更新
- 根 AGENTS.md 开头的指针改为两个子项目对照表
- docs/README.md 重构为双子项目索引
- .gitignore 加 admin/data/、admin.exe、Excel 锁文件

说明：Gitea 尚未配置，本次无对应工单号。
raw_data/ 未提交，含台币销售额等商业数据，待用户决定。

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

2026-08-06 15:49:04 +08:00

5.5 KiB

Raw Blame History

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 版本，依赖靠 go get 添加）：

cd D:\chengma\cmautobuy\admin
go get github.com/gin-gonic/gin
go get modernc.org/sqlite
go get github.com/xuri/excelize/v2
go mod tidy

跑完 go.mod 会多出 require 段，还会生成 go.sum。 [必须] 这两个文件都要提交 Git，否则别人拉下来版本对不上。

之后只需要：

go mod download

预期没有输出——Go 的惯例，成功时不打印东西。

三个依赖是定死的，见 admin/AGENTS.md 技术栈一节。特别注意 SQLite 驱动不要换成 mattn/go-sqlite3，那个需要 cgo。

3. 跑起来

cd D:\chengma\cmautobuy\admin
go run .

然后浏览器打开 http://localhost:8080。

这个命令是安全的：Admin 只管理数据，不会连手机、不会下单。放心随便跑。

改了代码要重启才生效（Go 不像 Python 那样改完就生效）。按 Ctrl+C 停掉再 go run .。

4. 你应该看到什么

左边（或顶部）是四个模块的导航：

模块	干什么的
蝦皮数据	导入蝦皮商品报表，填 PDD 链接，发起采集
顺运宝数据	同步货运单，匹配规格，生成采购任务
采购任务	看任务执行到哪一步了
客户端列表	看哪些客户端在干活

每个页面都是同一个结构：上面工具条 / 中间表格 / 下面状态条。四个页面长得像是故意的，见 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. 拿样本数据试一下导入

仓库里有一份真实的蝦皮导出样本：

raw_data/蝦皮数据样本.xlsx

11287 行，其中 5195 行是商品汇总行、6092 行是 SKU 行。导入后应该得到 5195 条商品 + 6092 条 SKU。数字对不上就是解析有问题。

解析规则见 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（技术栈和红线）。

5.5 KiB Raw Blame History Unescape Escape