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>
This commit is contained in:
chengma
@@ -0,0 +1,149 @@
|
||||
# 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` 有输出 |
|
||||
| DB Browser for SQLite | 任意 | 用来看数据库，可选但强烈建议装 |
|
||||
|
||||
版本已定为 **go1.23.0**，写在 `admin/go.mod` 里。低于这个版本可能编译不过。
|
||||
|
||||
**不需要装 gcc。** 本项目的 SQLite 驱动是纯 Go 实现的
|
||||
（`modernc.org/sqlite`），不依赖 cgo，这也是选它的原因——
|
||||
`go build` 直接出单个 exe，不用配 C 编译器。
|
||||
|
||||
## 2. 拉依赖
|
||||
|
||||
先配国内代理，否则大概率拉不动：
|
||||
|
||||
```powershell
|
||||
go env -w GOPROXY=https://goproxy.cn,direct
|
||||
```
|
||||
|
||||
**第一次**需要把三个依赖装上（`go.mod` 里只有模块名和 Go 版本，依赖靠 `go get` 添加）：
|
||||
|
||||
```powershell
|
||||
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**，否则别人拉下来版本对不上。
|
||||
|
||||
**之后**只需要：
|
||||
|
||||
```powershell
|
||||
go mod download
|
||||
```
|
||||
|
||||
预期没有输出——Go 的惯例，成功时不打印东西。
|
||||
|
||||
> 三个依赖是定死的，见 [admin/AGENTS.md](../../admin/AGENTS.md) 技术栈一节。
|
||||
> 特别注意 SQLite 驱动**不要**换成 `mattn/go-sqlite3`，那个需要 cgo。
|
||||
|
||||
## 3. 跑起来
|
||||
|
||||
```powershell
|
||||
cd D:\chengma\cmautobuy\admin
|
||||
go run .
|
||||
```
|
||||
|
||||
然后浏览器打开 <http://localhost:8080>。
|
||||
|
||||
**这个命令是安全的**：Admin 只管理数据，不会连手机、不会下单。放心随便跑。
|
||||
|
||||
改了代码要重启才生效（Go 不像 Python 那样改完就生效）。按 `Ctrl+C` 停掉再 `go run .`。
|
||||
|
||||
## 4. 你应该看到什么
|
||||
|
||||
左边（或顶部）是四个模块的导航：
|
||||
|
||||
| 模块 | 干什么的 |
|
||||
|---|---|
|
||||
| 蝦皮数据 | 导入蝦皮商品报表，填 PDD 链接，发起采集 |
|
||||
| 顺运宝数据 | 同步货运单，匹配规格，生成采购任务 |
|
||||
| 采购任务 | 看任务执行到哪一步了 |
|
||||
| 客户端列表 | 看哪些客户端在干活 |
|
||||
|
||||
每个页面都是同一个结构：**上面工具条 / 中间表格 / 下面状态条**。
|
||||
四个页面长得像是故意的，见 [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. 数据库在哪、怎么看
|
||||
|
||||
跟 Client 一样是**便携模式**——数据都在程序旁边的 `data/` 里：
|
||||
|
||||
```text
|
||||
admin/data/
|
||||
├── admin.db 数据库
|
||||
├── logs/ 运行日志
|
||||
└── uploads/ 上传的 Excel 原件
|
||||
```
|
||||
|
||||
跑源码时在 `admin\data\`；将来打包成 exe 后，在 exe 旁边。
|
||||
|
||||
用 **DB Browser for SQLite** 打开 `admin.db` 就能看数据。
|
||||
每张表什么意思见 [03 数据模型](03-data-model.md)。
|
||||
|
||||
> 写代码时**不要自己拼这个路径**，用统一的 `DataDir()` 函数，
|
||||
> 见 [02 架构](02-architecture.md) §6。
|
||||
|
||||
## 7. 拿样本数据试一下导入
|
||||
|
||||
仓库里有一份真实的蝦皮导出样本：
|
||||
|
||||
```text
|
||||
raw_data/蝦皮数据样本.xlsx
|
||||
```
|
||||
|
||||
11287 行，其中 5195 行是商品汇总行、6092 行是 SKU 行。
|
||||
导入后应该得到 **5195 条商品 + 6092 条 SKU**。数字对不上就是解析有问题。
|
||||
|
||||
解析规则见 [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)（技术栈和红线）。
|
||||
Reference in New Issue
Block a user