chengma/cmautobuy

Fork 0

Files

T

chengma c296feaf74 feat: 实现 SQLite 到 MySQL 单向迁移 (#80 )

2026-08-10 02:40:14 +08:00

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

配置顺运宝账号（同步货运单需要，其余四个模块不需要）

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

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

用编辑器打开 config.yaml，把 username / password 改成真实的顺运宝账号密码。

[必须] 密码要加引号，纯数字密码不加引号会被 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 中。Admin 从环境变量读取连接信息：

CMAUTOBUY_DB_HOST=127.0.0.1
CMAUTOBUY_DB_PORT=3307
CMAUTOBUY_DB_NAME=<独立数据库名>
CMAUTOBUY_DB_USER=<最小权限账号>
CMAUTOBUY_DB_PASSWORD=<只保存在服务器环境文件中的密码>

密码不得写入 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（技术栈和红线）。

9.1 KiB Raw Blame History