267 lines
10 KiB
Markdown
267 lines
10 KiB
Markdown
# 00 Admin 上手指南
|
||
|
||
- 文档状态：基线草案
|
||
- 读者：第一次接手 Admin 的开发者
|
||
- 目标：照着做完，能在自己电脑上把 Admin 跑起来，并知道下一步读哪份文档
|
||
|
||
这份文档只讲"怎么把环境搭好、怎么跑起来"。业务规则不在这里，见 [文档索引](../README.md)。
|
||
遇到不认识的词（货运单、upsert、SKU 映射……），先查 [术语表](00-glossary.md)。
|
||
|
||
## 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. 拉依赖
|
||
|
||
先配国内代理，否则大概率拉不动：
|
||
|
||
```powershell
|
||
go env -w GOPROXY=https://goproxy.cn,direct
|
||
```
|
||
|
||
正常情况下 `go.mod` 和 `go.sum` 已经在仓库里了，直接：
|
||
|
||
```powershell
|
||
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 了。
|
||
|
||
```powershell
|
||
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 的正常行为）：
|
||
|
||
```powershell
|
||
go get github.com/xuri/excelize/v2@v2.9.1
|
||
```
|
||
|
||
这些是在 Go 1.23.0 下实测能编译通过的固定版本，
|
||
为什么不能更高见 [admin/AGENTS.md](../../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. 跑起来
|
||
|
||
推荐在仓库根目录运行热重载脚本：
|
||
|
||
```powershell
|
||
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` 停止。
|
||
|
||
如果只想临时运行一次、不需要热重载，也可以：
|
||
|
||
```powershell
|
||
cd D:\chengma\cmautobuy\admin
|
||
go run .
|
||
```
|
||
|
||
然后浏览器打开 <http://localhost:8080>。
|
||
|
||
**这个命令是安全的**：Admin 只管理数据，不会连手机、不会下单。放心随便跑。
|
||
|
||
### 配置 MySQL 和顺运宝账号
|
||
|
||
顺运宝数据页的「同步」需要读 `admin/config.yaml`。第一次用要自己建这个文件
|
||
（已在 `.gitignore` 里，不会被提交）：
|
||
|
||
```powershell
|
||
cd D:\chengma\cmautobuy\admin
|
||
copy config.example.yaml config.yaml
|
||
```
|
||
|
||
用编辑器打开 `config.yaml`：
|
||
|
||
- `database:` 填 MySQL 8 的地址、数据库名、账号和密码，Admin 启动必须使用；
|
||
- `syb:` 填顺运宝账号密码，只在同步货运单时使用。
|
||
|
||
两个密码都是明文，只允许保存在这份被 Git 忽略的本机文件里，不得提交、打包、
|
||
截图或粘贴到日志和工单。
|
||
|
||
`[必须]` 密码要加引号，纯数字密码不加引号会被 YAML 解析成整数，前导 0 也会丢：
|
||
|
||
```yaml
|
||
password: "0012345" # ✓ 正确
|
||
password: 0012345 # ✗ 解析成整数 12345
|
||
```
|
||
|
||
没有这个文件时，点「同步」会提示"没有找到配置文件……请复制
|
||
config.example.yaml"，不是一句读不出原因的报错。
|
||
|
||
`config.yaml` 里还有两个和验证码自动识别相关的配置（工单 #47）：
|
||
|
||
```yaml
|
||
syb:
|
||
ocr_url: https://ocr.ilapage.cn/ocr # 留空则只用手工输入弹窗，不报错
|
||
ocr_max_attempts: 5 # 识别失败的重试次数上限
|
||
```
|
||
|
||
配了 `ocr_url` 后，会话过期时点「同步」会先自动识别验证码登录，
|
||
无需人在场；识别失败或服务连不上会自动降级到手工输入弹窗，弹窗里
|
||
会说明降级原因。`ocr_url` 留空就和 #46 时一样，一直走手工输入。
|
||
|
||
`[必须]` 验证码图片会被发送到 `ocr_url` 配置的地址，见
|
||
[08 顺运宝接口](08-顺运宝接口.md) §8.1。
|
||
|
||
接口细节和这几个配置项各自的含义见
|
||
[08 顺运宝接口](08-顺运宝接口.md) §8、§8.1。
|
||
|
||
## 4. 你应该看到什么
|
||
|
||
左边（或顶部）是五个模块的导航：
|
||
|
||
| 模块 | 干什么的 |
|
||
|---|---|
|
||
| 蝦皮数据 | 导入蝦皮商品报表，填 PDD 链接，发起采集 |
|
||
| PDD 商品 | 维护拼多多商品档案，发起采集，查看采回来的规格价格。这个页面不依赖蝦皮和顺运宝的任何数据，单独就能跑通"建商品 → 建采集任务 → 领走执行 → 提交结果 → 显示已采集"这条闭环，见 [05 界面规范](05-ui-specification.md) §5 |
|
||
| 顺运宝数据 | 同步货运单（需要先配置 `config.yaml`，见上一节）。规格匹配和生成采购任务是后续工单的范围，本页暂不提供 |
|
||
| 采集采购 | 看采集和采购任务执行到哪一步了 |
|
||
| 客户端列表 | 看哪些客户端在干活 |
|
||
|
||
每个页面都是同一个结构：**上面工具条 / 中间表格 / 下面状态条**。
|
||
五个页面长得像是故意的，见 [05 界面规范](05-ui-specification.md)。
|
||
|
||
## 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](06-quality-security.md) §2 |
|
||
|
||
## 6. 数据库在哪里、怎样配置
|
||
|
||
生产数据在 MySQL 8.4 中。Windows 本地运行可以直接在被 Git 忽略的
|
||
`admin/config.yaml` 中配置：
|
||
|
||
```yaml
|
||
database:
|
||
host: 127.0.0.1
|
||
port: "3307"
|
||
name: autobuy
|
||
user: buy
|
||
tls_mode: disabled
|
||
tls_ca: certs/mysql84-ca.pem
|
||
password: "从安全渠道取得"
|
||
```
|
||
|
||
Admin 本地开发连接线上 MySQL 时优先通过 SSH 隧道，把 `port` 改为隧道的本地
|
||
端口。项目负责人已于 2026-08-11 批准生产 3307 接受所有公网来源；公网直连仍只能
|
||
使用限定 `autobuy` 库权限、`REQUIRE SSL` 的专用业务账号，root 只允许服务器本机
|
||
登录。公网暴露风险高于固定 `/32`，恢复固定出口 IP 后应优先收紧白名单。
|
||
|
||
- 同机或 SSH 隧道：`tls_mode: disabled`；
|
||
- 公网直连：`tls_mode: verify_ca`，`tls_ca` 指向服务器公开 CA。客户端要求 TLS 1.2+
|
||
并校验证书链，失败时不会回退明文。CA 证书可以公开，私钥绝不能复制到客户端。
|
||
|
||
线上 systemd 部署继续使用环境变量：
|
||
|
||
```text
|
||
CMAUTOBUY_DB_HOST=127.0.0.1
|
||
CMAUTOBUY_DB_PORT=3307
|
||
CMAUTOBUY_DB_NAME=<独立数据库名>
|
||
CMAUTOBUY_DB_USER=<最小权限账号>
|
||
CMAUTOBUY_DB_PASSWORD=<从安全渠道取得>
|
||
CMAUTOBUY_DB_TLS_MODE=disabled
|
||
CMAUTOBUY_DB_TLS_CA=<verify_ca 模式下的 CA 路径>
|
||
```
|
||
|
||
环境变量按字段覆盖 `config.yaml`，所以现有线上部署方式不受影响。生产环境文件和
|
||
本地 `config.yaml` 都不得进入仓库、日志或工单；本地自动化测试仍通过 SSH 隧道
|
||
连接独立的 `_test` 数据库，不得对生产 `autobuy` 执行清理测试。
|
||
|
||
程序旁边的 `data/` 只保留日志、上传文件和迁移前的 SQLite 只读备份：
|
||
|
||
```text
|
||
admin/data/
|
||
├── backup/ 迁移前的 admin.db 只读备份
|
||
├── logs/ 运行日志
|
||
└── uploads/ 上传的 Excel 原件
|
||
```
|
||
|
||
跑源码时在 `admin\data\`；将来打包成 exe 后，在 exe 旁边。
|
||
|
||
每张表什么意思见 [03 数据模型](03-data-model.md)。旧 `admin.db` 只能通过
|
||
单向迁移命令读取，生产 Admin 不再直接打开它。具体操作见
|
||
[09 SQLite 单向迁移到 MySQL 8](09-sqlite迁移到mysql.md)。
|
||
|
||
> 写代码时**不要自己拼这个路径**，用统一的 `DataDir()` 函数，
|
||
> 见 [02 架构](02-architecture.md) §6。
|
||
|
||
## 7. 拿样本数据试一下导入
|
||
|
||
蝦皮的真实报表**不在仓库里**——里面有逐商品的台币销售额，属于商业数据，
|
||
已在 `.gitignore` 里排除。
|
||
|
||
需要的话**找项目负责人要一份**，放到仓库根目录的 `raw_data/` 下：
|
||
|
||
```text
|
||
raw_data/蝦皮数据样本.xlsx
|
||
```
|
||
|
||
参考样本是 11287 行 = 5195 商品汇总行 + 6092 SKU 行，
|
||
导入后应得到 **5195 条商品 + 6092 条 SKU**。数字对不上就是解析有问题。
|
||
|
||
> 写自动化测试**不要**用这份大文件，用 `admin/testdata/` 下已脱敏的小样本，
|
||
> 见 [06 质量与安全](06-quality-security.md) §2.1。
|
||
|
||
解析规则见 [03 数据模型](03-data-model.md) §3.3，那里说明了为什么一个文件要拆成两张表。
|
||
|
||
## 8. 提交代码前的自检
|
||
|
||
```powershell
|
||
cd D:\chengma\cmautobuy\admin
|
||
|
||
go vet ./... # 静态检查，有问题会打印出来
|
||
go build ./... # 能编译
|
||
go test ./... # 测试能过
|
||
```
|
||
|
||
三条都没报错就算通过。完整验证要求见 [admin/AGENTS.md](../../admin/AGENTS.md) §验证。
|
||
|
||
## 9. 接下来读什么
|
||
|
||
| 我要做的事 | 读这份 |
|
||
|---|---|
|
||
| 改页面、加表格列 | [05 界面规范](05-ui-specification.md) |
|
||
| 加字段、改表、写 SQL | [03 数据模型](03-data-model.md) |
|
||
| 改给 Client 的接口 | [04 Client 接口实现](04-client-api.md) + [Client 侧契约](../client/04-admin-api-contract.md) |
|
||
| 改 Excel 导入 | [03 数据模型](03-data-model.md) §3.3 |
|
||
| 搞不清这功能要不要做 | [01 产品需求基线](01-requirements.md) |
|
||
|
||
无论做哪一样，都必须先看一遍 [admin/AGENTS.md](../../admin/AGENTS.md)（技术栈和红线）。
|