# 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.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 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，否则别人拉下来版本对不上。

> SQLite 驱动**不要**换成 `mattn/go-sqlite3`，那个需要 cgo，
> 得装 gcc，还会让 `go build` 出不了单文件 exe。

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

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

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