feat: 建立 MySQL 8 数据库基础 (#78)

admin/AGENTS.md

@@ -25,9 +25,13 @@
 **Go 版本固定 1.23.0。** 依赖版本受它约束，见下面的表。
 
 - 固定使用 **Go + Gin + Go 标准库 `html/template`**。
-- 数据库固定 **SQLite**，驱动固定 `modernc.org/sqlite`。
-  **不得改用 `mattn/go-sqlite3`** —— 那个要 cgo，Windows 上得装 gcc，
-  交叉编译和打包 exe 都会变得很麻烦。
+- 生产数据库固定 **MySQL 8.4**，驱动固定
+  `github.com/go-sql-driver/mysql` **v1.9.2**（纯 Go，兼容 Go 1.23）。
+- Admin 必须与 MySQL 同机或走私有网络；生产默认连接 `127.0.0.1:3307`，
+  **不得为了远程访问开放公网 MySQL 端口**。
+- `modernc.org/sqlite` 只保留给 SQLite → MySQL 单向迁移工具和历史库回归，
+  不得用于生产运行时，也不得做 SQLite/MySQL 双写或自动同步。
+- 仍然**不得改用 `mattn/go-sqlite3`**，避免引入 cgo 和 gcc。
 - Excel 读取固定 `github.com/xuri/excelize/v2`。
 
 ### 依赖版本已钉死，不要随手升
@@ -37,12 +41,13 @@
 | `github.com/gin-gonic/gin` | **v1.11.0** | v1.12.0 起要求 Go ≥ 1.25.0 |
 | `modernc.org/sqlite` | **v1.38.0** | v1.40.0 起要求 Go ≥ 1.24.0，v1.48.0 起要求 ≥ 1.25.0 |
 | `github.com/xuri/excelize/v2` | **v2.9.1** | v2.10.0 要求 Go ≥ 1.24.0，v2.11.0 要求 ≥ 1.25.0 |
+| `github.com/go-sql-driver/mysql` | **v1.9.2** | v1.9.3 起要求 Go ≥ 1.24.0 |
 
 > excelize 目前**还不在 `go.mod` 里**——导入功能还没写，没有代码 import 它，
 > `go mod tidy` 会把它去掉，这是 Go 的正常行为。写导入功能时用
 > `go get github.com/xuri/excelize/v2@v2.9.1` 加进来。
 
-这三个版本是**在 Go 1.23.0 下实测能编译通过的最高版本**。
+这些版本是**在 Go 1.23.0 下实测能编译通过的固定版本**。
 
 `[必须]` 直接跑 `go get <包名>`（不带版本）会拉到最新版，然后报
 `requires go >= 1.25.0`。拉依赖要带版本号，见
@@ -68,7 +73,7 @@
 
 - `handler` 只负责解析请求、调用 service、渲染模板或返回 JSON，**不写业务逻辑，不拼 SQL**。
 - `service` 放业务逻辑（导入解析、创建任务、匹配复用），不认识 Gin 的 `*gin.Context`。
-- `repository` 封装 SQLite，**只有这一层能写 SQL**。
+- `repository` 封装 MySQL 读写，迁移命令中的 SQLite 读取也只能放在 repository/cmd 边界内；**只有这一层能写业务 SQL**。
 - `model` 只放数据结构，不导入 Gin 和数据库驱动。
 - 给 Client 的接口和给浏览器的页面**分开放**（`handler/api/` 和 `handler/web/`），
   两者的错误格式、认证方式都不一样，混在一起迟早出事。
@@ -85,9 +90,9 @@
 - `[必须]` 蝦皮规格原文（`spec_raw`）永远保留，解析不出来就留空，不要瞎猜。
 - `[必须]` Client 提交结果时，**不管任务是否已取消、是否已重派，一律接受**，
   理由见 Client 契约 §6.1。这条最容易被顺手违反。
-- `[必须]` `repository/db.go` 里的 `migrations` 只追加，**不得修改已经发布过的条目**。
-  改了的话，已经建过库的机器 `user_version` 已经越过它，永远不会重跑，
-  程序会拿着对不上的库静默启动（见 #20）。需要改结构就加新的一条。
+- `[必须]` MySQL 的 `schema_migrations` 只追加，已经发布的版本不得改写。
+  MySQL DDL 会隐式提交：每条 DDL 必须可重放，整版完成并通过 schema 自检后
+  才记录版本。历史 SQLite migrations 已冻结，只供迁移工具读取旧库。
 
 ## 界面规则
 
@@ -132,9 +137,10 @@ Remove-Item Env:GOTOOLCHAIN
 新加依赖时尤其要跑——依赖的 `go` 指令高于 1.23.0 的话，只有这条命令能发现。
 
 - `go run .` 启动后访问 `http://localhost:8080`，**不会连手机、不会下单**，可随时运行。
-- 修改数据库时测试首次建库和从上一版本迁移。
-  `[必须]` **不要只测全新库。** 先列出现实中存在哪些 schema 状态
-  （不同版本的程序建过的库都算），一个个迁过来验。见 `docs/task/20-*.md`。
+- 修改数据库时必须使用独立 MySQL 8.4 测试库验证首次建库、重复迁移和上一版本升级。
+  测试库名必须以 `_test` 结尾，禁止测试清理连接生产库。
+- 修改 SQLite 单向迁移时，同时用各历史 SQLite schema 状态演练；源库只读，
+  目标库必须为空，逐表计数和关键业务关系必须核对。
 - 修改给 Client 的接口时，跑契约测试，确认仍满足 Client 侧 §6.1 的无条件接受。
 - 修改 Excel 导入时用 `raw_data/` 下的样本跑一遍，核对导入条数。
   该样本含商业数据、**不在仓库里**，需向项目负责人索取；自动化测试用 `testdata/` 下的脱敏小样本。