Files

T

chengmaandClaude Opus 5 4f920f9d8b docs: 排除蝦皮原始报表，并同步主按钮文案

raw_data 不进 Git
原始报表含逐商品台币销售额等商业数据，进了 Git 就是永久历史。
- .gitignore 排除 raw_data/
- 改掉三处"仓库里有一份样本"的失真表述，改为向项目负责人索取
- 06 §2.1 相应加强：既然大样本不进库，admin/testdata/ 下的脱敏小样本
  就必须提交，否则别人拉下来测试跑不了；并写明脱敏做法

主按钮文案 开始自动获取 → 获取任务 ⇄ 停止获取
只改按钮标签。"自动获取"作为功能名保留（状态栏、Tab 顺序、
协调器开关等处不动），05 §4.1 加了一句说明两者不是一回事。

已知遗留：pdd_ui.py 自身仍不一致——构造时用「获取任务」，
但状态机 485/487 行仍是「开始自动获取」/「停止自动获取」，
会覆盖掉构造时的文字。该文件有未提交改动，本次未触碰，
差异已记入 02 §3.1，需另开工单修。

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

2026-08-06 15:58:09 +08:00

5.8 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. 拿样本数据试一下导入

蝦皮的真实报表不在仓库里——里面有逐商品的台币销售额，属于商业数据，已在 .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（技术栈和红线）。

5.8 KiB Raw Blame History Unescape Escape