cmautobuy/docs/admin/00-getting-started.md

00 Admin 上手指南

• 文档状态：基线草案
• 读者：第一次接手 Admin 的开发者
• 目标：照着做完，能在自己电脑上把 Admin 跑起来，并知道下一步读哪份文档

这份文档只讲"怎么把环境搭好、怎么跑起来"。业务规则不在这里，见 文档索引。 遇到不认识的词（货运单、upsert、SKU 映射……），先查 术语表。

1. 准备电脑环境

需要什么	版本	怎么确认装好了
Go	1.23.0	go version 输出 go version go1.23.0 windows/amd64
Git	任意较新版本	git --version 有输出
MySQL Client	8.4	用于连接独立的 MySQL 8.4 开发/测试库

版本已定为 go1.23.0，写在 admin/go.mod 里。低于这个版本可能编译不过。

不需要装 gcc。 生产 MySQL 驱动和历史 SQLite 迁移驱动都是纯 Go； go build 不依赖 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 get github.com/go-sql-driver/mysql@v1.9.2
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，否则别人拉下来版本对不上。

go-sql-driver/mysql v1.9.3 起要求 Go 1.24，本项目固定 v1.9.2。 SQLite 驱动只用于历史库迁移，仍不要换成需要 cgo 的 mattn/go-sqlite3。

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 只管理数据，不会连手机、不会下单。放心随便跑。

配置 MySQL 和顺运宝账号

顺运宝数据页的「同步」需要读 admin/config.yaml。第一次用要自己建这个文件 （已在 .gitignore 里，不会被提交）：

cd D:\chengma\cmautobuy\admin
copy config.example.yaml config.yaml

用编辑器打开 config.yaml：

• database: 填 MySQL 8 的地址、数据库名、账号和密码，Admin 启动必须使用；
• syb: 填顺运宝账号密码，只在同步货运单时使用。

两个密码都是明文，只允许保存在这份被 Git 忽略的本机文件里，不得提交、打包、 截图或粘贴到日志和工单。

[必须] 密码要加引号，纯数字密码不加引号会被 YAML 解析成整数，前导 0 也会丢：

password: "0012345"    # ✓ 正确
password: 0012345      # ✗ 解析成整数 12345

没有这个文件时，点「同步」会提示"没有找到配置文件……请复制 config.example.yaml"，不是一句读不出原因的报错。

config.yaml 里还有两个和验证码自动识别相关的配置（工单 #47）：

syb:
  ocr_url: https://ocr.ilapage.cn/ocr   # 留空则只用手工输入弹窗，不报错
  ocr_max_attempts: 5                    # 识别失败的重试次数上限

配了 ocr_url 后，会话过期时点「同步」会先自动识别验证码登录， 无需人在场；识别失败或服务连不上会自动降级到手工输入弹窗，弹窗里 会说明降级原因。ocr_url 留空就和 #46 时一样，一直走手工输入。

[必须] 验证码图片会被发送到 ocr_url 配置的地址，见 08 顺运宝接口 §8.1。

接口细节和这几个配置项各自的含义见 08 顺运宝接口 §8、§8.1。

4. 你应该看到什么

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

模块	干什么的
蝦皮数据	导入蝦皮商品报表，填 PDD 链接，发起采集
PDD 商品	维护拼多多商品档案，发起采集，查看采回来的规格价格。这个页面不依赖蝦皮和顺运宝的任何数据，单独就能跑通"建商品 → 建采集任务 → 领走执行 → 提交结果 → 显示已采集"这条闭环，见 05 界面规范 §5
顺运宝数据	同步货运单（需要先配置 config.yaml，见上一节）。规格匹配和生成采购任务是后续工单的范围，本页暂不提供
采集采购	看采集和采购任务执行到哪一步了
客户端列表	看哪些客户端在干活

每个页面都是同一个结构：上面工具条 / 中间表格 / 下面状态条。 五个页面长得像是故意的，见 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. 数据库在哪里、怎样配置

生产数据在 MySQL 8.4 中。Windows 本地运行可以直接在被 Git 忽略的 admin/config.yaml 中配置：

database:
  host: 127.0.0.1
  port: "3307"
  name: autobuy
  user: buy
  password: "从安全渠道取得"

连接线上 MySQL 时仍通过 SSH 隧道，把 port 改为隧道的本地端口；禁止开放线上 MySQL 公网端口。线上 systemd 部署继续使用环境变量：

CMAUTOBUY_DB_HOST=127.0.0.1
CMAUTOBUY_DB_PORT=3307
CMAUTOBUY_DB_NAME=<独立数据库名>
CMAUTOBUY_DB_USER=<最小权限账号>
CMAUTOBUY_DB_PASSWORD=<从安全渠道取得>

环境变量按字段覆盖 config.yaml，所以现有线上部署方式不受影响。生产环境文件和 本地 config.yaml 都不得进入仓库、日志或工单；线上 MySQL 只监听本机，本地开发 通过 SSH 隧道连接独立的 _test 数据库。

程序旁边的 data/ 只保留日志、上传文件和迁移前的 SQLite 只读备份：

admin/data/
├── backup/         迁移前的 admin.db 只读备份
├── logs/           运行日志
└── uploads/        上传的 Excel 原件

跑源码时在 admin\data\；将来打包成 exe 后，在 exe 旁边。

每张表什么意思见 03 数据模型。旧 admin.db 只能通过 单向迁移命令读取，生产 Admin 不再直接打开它。具体操作见 09 SQLite 单向迁移到 MySQL 8。

写代码时不要自己拼这个路径，用统一的 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（技术栈和红线）。