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/` 下的脱敏小样本。

admin/config/config.go

@@ -23,6 +23,66 @@ import (
 // 本项目有意不做心跳，见 docs/admin/04-client-api.md §3。
 const OnlineThreshold = 10 * time.Minute
 
+const (
+	databaseHostEnv     = "CMAUTOBUY_DB_HOST"
+	databasePortEnv     = "CMAUTOBUY_DB_PORT"
+	databaseNameEnv     = "CMAUTOBUY_DB_NAME"
+	databaseUserEnv     = "CMAUTOBUY_DB_USER"
+	databasePasswordEnv = "CMAUTOBUY_DB_PASSWORD"
+)
+
+// DatabaseConfig 是生产 MySQL 8 的连接配置。
+// 密码只从环境变量读取，不能写进 config.yaml、日志或工单。
+type DatabaseConfig struct {
+	Host     string
+	Port     string
+	Name     string
+	User     string
+	Password string
+}
+
+// String 永远隐藏密码，防止排错时用 %v 把凭据写进日志。
+func (c DatabaseConfig) String() string {
+	password := "(空)"
+	if c.Password != "" {
+		password = "****"
+	}
+	return fmt.Sprintf("DatabaseConfig{Host:%s Port:%s Name:%s User:%s Password:%s}",
+		c.Host, c.Port, c.Name, c.User, password)
+}
+
+// LoadDatabaseFromEnv 读取生产数据库配置。
+// Host/Port 使用线上同机部署的安全默认值；库名、账号和密码必须显式提供。
+func LoadDatabaseFromEnv() (DatabaseConfig, error) {
+	cfg := DatabaseConfig{
+		Host:     strings.TrimSpace(os.Getenv(databaseHostEnv)),
+		Port:     strings.TrimSpace(os.Getenv(databasePortEnv)),
+		Name:     strings.TrimSpace(os.Getenv(databaseNameEnv)),
+		User:     strings.TrimSpace(os.Getenv(databaseUserEnv)),
+		Password: os.Getenv(databasePasswordEnv),
+	}
+	if cfg.Host == "" {
+		cfg.Host = "127.0.0.1"
+	}
+	if cfg.Port == "" {
+		cfg.Port = "3307"
+	}
+	var missing []string
+	if cfg.Name == "" {
+		missing = append(missing, databaseNameEnv)
+	}
+	if cfg.User == "" {
+		missing = append(missing, databaseUserEnv)
+	}
+	if cfg.Password == "" {
+		missing = append(missing, databasePasswordEnv)
+	}
+	if len(missing) > 0 {
+		return DatabaseConfig{}, fmt.Errorf("缺少 MySQL 配置环境变量：%s", strings.Join(missing, "、"))
+	}
+	return cfg, nil
+}
+
 // DataDir 返回可写数据目录，不存在就创建。
 //
 // 打包成 exe 后 = exe 旁边的 data/

admin/config/config_test.go

@@ -7,6 +7,35 @@ import (
 	"testing"
 )
 
+func TestLoadDatabaseFromEnv_默认只连接本机3307且密码不泄露(t *testing.T) {
+	t.Setenv(databaseHostEnv, "")
+	t.Setenv(databasePortEnv, "")
+	t.Setenv(databaseNameEnv, "cmautobuy_test")
+	t.Setenv(databaseUserEnv, "cmautobuy_test")
+	t.Setenv(databasePasswordEnv, "secret-do-not-print")
+
+	cfg, err := LoadDatabaseFromEnv()
+	if err != nil {
+		t.Fatal(err)
+	}
+	if cfg.Host != "127.0.0.1" || cfg.Port != "3307" {
+		t.Fatalf("默认地址应为线上同机 MySQL 8，实际 %s:%s", cfg.Host, cfg.Port)
+	}
+	if got := cfg.String(); strings.Contains(got, cfg.Password) || !strings.Contains(got, "****") {
+		t.Fatalf("配置字符串泄露密码或没有打码：%s", got)
+	}
+}
+
+func TestLoadDatabaseFromEnv_缺少必填项时只报变量名(t *testing.T) {
+	t.Setenv(databaseNameEnv, "")
+	t.Setenv(databaseUserEnv, "")
+	t.Setenv(databasePasswordEnv, "")
+	_, err := LoadDatabaseFromEnv()
+	if err == nil || !strings.Contains(err.Error(), databasePasswordEnv) {
+		t.Fatalf("应明确列出缺失变量，实际 %v", err)
+	}
+}
+
 // loadFrom 是测试专用的小工具：把一段 YAML 文本写到临时目录里的
 // config.yaml，绕开 ConfigPath()（它依赖 os.Executable，测试环境里
 // 不可控），直接测 Load 里"读文件 + 解析"这段逻辑。

admin/go.mod

@@ -5,7 +5,8 @@ go 1.23.0
 // 依赖用 go get 添加后会自动写到下面，连同 go.sum 一起提交。
 // 本项目固定使用（理由见 admin/AGENTS.md 技术栈一节）：
 //   github.com/gin-gonic/gin      Web 框架
-//   modernc.org/sqlite            SQLite 驱动，纯 Go，不需要 cgo
+//   github.com/go-sql-driver/mysql 生产 MySQL 8 驱动，纯 Go
+//   modernc.org/sqlite            只读历史 SQLite 迁移驱动，纯 Go
 //   github.com/xuri/excelize/v2   读蝦皮 Excel 报表
 //
 // 不得改用 github.com/mattn/go-sqlite3（需要 cgo，Windows 上要装 gcc，
@@ -13,6 +14,7 @@ go 1.23.0
 
 require (
 	github.com/gin-gonic/gin v1.11.0
+	github.com/go-sql-driver/mysql v1.9.2
 	github.com/goccy/go-yaml v1.18.0
 	github.com/xuri/excelize/v2 v2.9.1
 	golang.org/x/crypto v0.40.0
@@ -20,6 +22,7 @@ require (
 )
 
 require (
+	filippo.io/edwards25519 v1.1.0 // indirect
 	github.com/bytedance/sonic v1.14.0 // indirect
 	github.com/bytedance/sonic/loader v0.3.0 // indirect
 	github.com/cloudwego/base64x v0.1.6 // indirect

admin/go.sum

@@ -1,3 +1,5 @@
+filippo.io/edwards25519 v1.1.0 h1:FNf4tywRC1HmFuKW5xopWpigGjJKiJSV0Cqo0cJWDaA=
+filippo.io/edwards25519 v1.1.0/go.mod h1:BxyFTGdWcka3PhytdK4V28tE5sGfRvvvRV7EaN4VDT4=
 github.com/bytedance/sonic v1.14.0 h1:/OfKt8HFw0kh2rj8N0F6C/qPGRESq0BbaNZgcNXXzQQ=
 github.com/bytedance/sonic v1.14.0/go.mod h1:WoEbx8WTcFJfzCe0hbmyTGrfjt8PzNEBdxlNUO24NhA=
 github.com/bytedance/sonic/loader v0.3.0 h1:dskwH8edlzNMctoruo8FPTJDF3vLtDT0sXZwvZJyqeA=
@@ -23,6 +25,8 @@ github.com/go-playground/universal-translator v0.18.1 h1:Bcnm0ZwsGyWbCzImXv+pAJn
 github.com/go-playground/universal-translator v0.18.1/go.mod h1:xekY+UJKNuX9WP91TpwSH2VMlDf28Uj24BCp08ZFTUY=
 github.com/go-playground/validator/v10 v10.27.0 h1:w8+XrWVMhGkxOaaowyKH35gFydVHOvC0/uWoy2Fzwn4=
 github.com/go-playground/validator/v10 v10.27.0/go.mod h1:I5QpIEbmr8On7W0TktmJAumgzX4CA1XNl4ZmDuVHKKo=
+github.com/go-sql-driver/mysql v1.9.2 h1:4cNKDYQ1I84SXslGddlsrMhc8k4LeDVj6Ad6WRjiHuU=
+github.com/go-sql-driver/mysql v1.9.2/go.mod h1:qn46aNg1333BRMNU69Lq93t8du/dwxI64Gl8i5p1WMU=
 github.com/goccy/go-json v0.10.2 h1:CrxCmQqYDkv1z7lO7Wbh2HN93uovUHgrECaO5ZrCXAU=
 github.com/goccy/go-json v0.10.2/go.mod h1:6MelG93GURQebXPDq3khkgXZkazVtN9CRI+MGFi0w8I=
 github.com/goccy/go-yaml v1.18.0 h1:8W7wMFS12Pcas7KU+VVkaiCng+kG8QiFeFwzFb+rwuw=

admin/repository/mysql_db.go

@@ -0,0 +1,375 @@
+package repository
+
+import (
+	"context"
+	"database/sql"
+	"fmt"
+	"net"
+	"strings"
+	"time"
+
+	"github.com/go-sql-driver/mysql"
+
+	"cmautobuy/admin/config"
+)
+
+const mysqlSchemaVersion = 1
+
+// OpenMySQL 打开生产 MySQL 8 数据库。错误信息绝不包含完整 DSN 或密码。
+func OpenMySQL(cfg config.DatabaseConfig) (*sql.DB, error) {
+	driverConfig := mysql.NewConfig()
+	driverConfig.User = cfg.User
+	driverConfig.Passwd = cfg.Password
+	driverConfig.Net = "tcp"
+	driverConfig.Addr = net.JoinHostPort(cfg.Host, cfg.Port)
+	driverConfig.DBName = cfg.Name
+	driverConfig.Collation = "utf8mb4_0900_ai_ci"
+	driverConfig.Loc = time.UTC
+	driverConfig.Timeout = 5 * time.Second
+	driverConfig.ReadTimeout = 30 * time.Second
+	driverConfig.WriteTimeout = 30 * time.Second
+	driverConfig.RejectReadOnly = true
+	driverConfig.Params = map[string]string{
+		"time_zone": "'+00:00'",
+		"sql_mode":  "'STRICT_TRANS_TABLES,ERROR_FOR_DIVISION_BY_ZERO,NO_ENGINE_SUBSTITUTION'",
+	}
+
+	db, err := sql.Open("mysql", driverConfig.FormatDSN())
+	if err != nil {
+		return nil, fmt.Errorf("准备 MySQL 连接失败: %w", err)
+	}
+	db.SetMaxOpenConns(10)
+	db.SetMaxIdleConns(10)
+	db.SetConnMaxLifetime(3 * time.Minute)
+	db.SetConnMaxIdleTime(time.Minute)
+
+	ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
+	defer cancel()
+	if err := db.PingContext(ctx); err != nil {
+		db.Close()
+		return nil, fmt.Errorf("连接 MySQL 失败，请检查服务、库名和环境变量: %w", err)
+	}
+	if err := CheckMySQLServer(db, cfg.Name); err != nil {
+		db.Close()
+		return nil, err
+	}
+	return db, nil
+}
+
+// CheckMySQLServer 拒绝错误版本、错误库、非 UTC 或非 utf8mb4 的连接。
+func CheckMySQLServer(db *sql.DB, expectedDatabase string) error {
+	var version, databaseName, timeZone, charset, collation string
+	if err := db.QueryRow(`SELECT VERSION(), DATABASE(), @@session.time_zone,
+		@@character_set_connection, @@collation_connection`).Scan(
+		&version, &databaseName, &timeZone, &charset, &collation); err != nil {
+		return fmt.Errorf("读取 MySQL 运行参数失败: %w", err)
+	}
+	if !strings.HasPrefix(version, "8.") {
+		return fmt.Errorf("MySQL 版本不兼容：需要 8.x，实际 %s", version)
+	}
+	if databaseName != expectedDatabase {
+		return fmt.Errorf("连接到了错误的 MySQL 数据库：期望 %s，实际 %s", expectedDatabase, databaseName)
+	}
+	if timeZone != "+00:00" {
+		return fmt.Errorf("MySQL 会话时区必须是 +00:00，实际 %s", timeZone)
+	}
+	if charset != "utf8mb4" || !strings.HasPrefix(collation, "utf8mb4_") {
+		return fmt.Errorf("MySQL 连接字符集必须是 utf8mb4，实际 %s/%s", charset, collation)
+	}
+	return nil
+}
+
+// mysqlSchemaV1 是当前 SQLite v8 最终业务结构在 MySQL 8 上的等价定义。
+// 每条 CREATE TABLE 都可重复执行；全部完成并通过自检后才记录版本。
+var mysqlSchemaV1 = []string{
+	`CREATE TABLE IF NOT EXISTS shopee_products (
+		goods_id VARCHAR(191) COLLATE utf8mb4_bin PRIMARY KEY,
+		title TEXT NOT NULL,
+		shopee_status VARCHAR(191),
+		main_sku_code VARCHAR(191),
+		pdd_goods_url TEXT,
+		pdd_goods_id VARCHAR(191) COLLATE utf8mb4_bin,
+		created_at VARCHAR(35) NOT NULL,
+		updated_at VARCHAR(35) NOT NULL,
+		KEY idx_shopee_products_pdd (pdd_goods_id)
+	) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_0900_ai_ci`,
+	`CREATE TABLE IF NOT EXISTS shopee_skus (
+		sku_id VARCHAR(191) COLLATE utf8mb4_bin PRIMARY KEY,
+		goods_id VARCHAR(191) COLLATE utf8mb4_bin NOT NULL,
+		spec_raw TEXT NOT NULL,
+		color TEXT,
+		size TEXT,
+		advice TEXT,
+		parse_ok TINYINT NOT NULL DEFAULT 0,
+		sku_code VARCHAR(191),
+		is_manual TINYINT NOT NULL DEFAULT 0,
+		created_at VARCHAR(35) NOT NULL,
+		updated_at VARCHAR(35) NOT NULL,
+		KEY idx_shopee_skus_goods (goods_id),
+		KEY idx_shopee_skus_parse (parse_ok),
+		CONSTRAINT fk_shopee_skus_product FOREIGN KEY (goods_id)
+			REFERENCES shopee_products(goods_id) ON DELETE CASCADE,
+		CHECK (parse_ok IN (0, 1)),
+		CHECK (is_manual IN (0, 1))
+	) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_0900_ai_ci`,
+	`CREATE TABLE IF NOT EXISTS pdd_products (
+		id BIGINT PRIMARY KEY AUTO_INCREMENT,
+		goods_id VARCHAR(191) COLLATE utf8mb4_bin NOT NULL UNIQUE,
+		url TEXT NOT NULL,
+		title TEXT,
+		shop_name TEXT,
+		skus_json LONGTEXT,
+		collect_status VARCHAR(20) NOT NULL DEFAULT 'pending',
+		collect_msg TEXT,
+		artifact_ref TEXT,
+		collected_at VARCHAR(35),
+		deleted_at VARCHAR(35),
+		created_at VARCHAR(35) NOT NULL,
+		updated_at VARCHAR(35) NOT NULL,
+		KEY idx_pdd_products_status (collect_status),
+		CHECK (collect_status IN ('pending', 'collecting', 'collected', 'failed'))
+	) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_0900_ai_ci`,
+	`CREATE TABLE IF NOT EXISTS syb_orders (
+		syb_id VARCHAR(191) COLLATE utf8mb4_bin PRIMARY KEY,
+		order_no VARCHAR(191) COLLATE utf8mb4_bin NOT NULL,
+		title TEXT,
+		shopee_goods_id VARCHAR(191) COLLATE utf8mb4_bin,
+		shopee_sku_id VARCHAR(191) COLLATE utf8mb4_bin,
+		product_spec TEXT,
+		quantity BIGINT NOT NULL,
+		price_twd_cent BIGINT,
+		image_url TEXT,
+		syb_data LONGTEXT NOT NULL DEFAULT ('{}'),
+		created_at VARCHAR(35) NOT NULL,
+		updated_at VARCHAR(35) NOT NULL,
+		KEY idx_syb_orders_order (order_no),
+		KEY idx_syb_orders_goods (shopee_goods_id),
+		KEY idx_syb_orders_list (updated_at DESC, syb_id DESC),
+		CHECK (quantity > 0),
+		CHECK (price_twd_cent IS NULL OR price_twd_cent >= 0)
+	) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_0900_ai_ci`,
+	`CREATE TABLE IF NOT EXISTS sku_mappings (
+		shopee_sku_id VARCHAR(191) COLLATE utf8mb4_bin NOT NULL,
+		pdd_goods_id VARCHAR(191) COLLATE utf8mb4_bin NOT NULL,
+		pdd_option_key VARCHAR(191) COLLATE utf8mb4_bin NOT NULL,
+		pdd_options LONGTEXT NOT NULL,
+		goods_id VARCHAR(191) COLLATE utf8mb4_bin NOT NULL,
+		mapped_at VARCHAR(35) NOT NULL,
+		mapped_by VARCHAR(191),
+		PRIMARY KEY (shopee_sku_id, pdd_goods_id),
+		KEY idx_sku_mappings_goods (goods_id),
+		KEY idx_sku_mappings_pdd (pdd_goods_id),
+		CONSTRAINT fk_sku_mappings_sku FOREIGN KEY (shopee_sku_id)
+			REFERENCES shopee_skus(sku_id) ON DELETE CASCADE
+	) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_0900_ai_ci`,
+	`CREATE TABLE IF NOT EXISTS tasks (
+		task_id VARCHAR(191) COLLATE utf8mb4_bin PRIMARY KEY,
+		task_type VARCHAR(20) NOT NULL,
+		status VARCHAR(20) NOT NULL DEFAULT 'pending',
+		version BIGINT NOT NULL DEFAULT 1,
+		priority BIGINT NOT NULL DEFAULT 0,
+		assigned_client VARCHAR(191) COLLATE utf8mb4_bin,
+		claimed_at VARCHAR(35),
+		syb_id VARCHAR(191) COLLATE utf8mb4_bin,
+		order_no VARCHAR(191) COLLATE utf8mb4_bin,
+		goods_id VARCHAR(191) COLLATE utf8mb4_bin,
+		shopee_sku_id VARCHAR(191) COLLATE utf8mb4_bin,
+		pdd_goods_url TEXT NOT NULL,
+		pdd_goods_id VARCHAR(191) COLLATE utf8mb4_bin,
+		pdd_options LONGTEXT,
+		quantity BIGINT,
+		max_price_cent BIGINT,
+		result_data LONGTEXT,
+		error_code VARCHAR(191),
+		error_message TEXT,
+		finished_at VARCHAR(35),
+		created_at VARCHAR(35) NOT NULL,
+		updated_at VARCHAR(35) NOT NULL,
+		KEY idx_tasks_claim (assigned_client, status, priority DESC, created_at),
+		KEY idx_tasks_list (updated_at DESC, task_id DESC),
+		KEY idx_tasks_order (order_no),
+		CHECK (task_type IN ('collect', 'purchase')),
+		CHECK (status IN ('pending', 'assigned', 'claimed', 'succeeded', 'manual_review', 'failed', 'cancelled')),
+		CHECK (version > 0),
+		CHECK (quantity IS NULL OR quantity > 0),
+		CHECK (max_price_cent IS NULL OR max_price_cent > 0)
+	) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_0900_ai_ci`,
+	`CREATE TABLE IF NOT EXISTS clients (
+		client_id VARCHAR(191) COLLATE utf8mb4_bin PRIMARY KEY,
+		name TEXT,
+		device_address TEXT,
+		platform VARCHAR(191),
+		pdd_package VARCHAR(191),
+		capabilities LONGTEXT,
+		last_seen_at VARCHAR(35) NOT NULL,
+		created_at VARCHAR(35) NOT NULL,
+		updated_at VARCHAR(35) NOT NULL
+	) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_0900_ai_ci`,
+	`CREATE TABLE IF NOT EXISTS idempotency_keys (
+		` + "`key`" + ` VARCHAR(191) COLLATE utf8mb4_bin PRIMARY KEY,
+		request_hash VARCHAR(191) COLLATE utf8mb4_bin NOT NULL,
+		response_body LONGTEXT NOT NULL,
+		created_at VARCHAR(35) NOT NULL
+	) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_0900_ai_ci`,
+	`CREATE TABLE IF NOT EXISTS task_claims (
+		task_id VARCHAR(191) COLLATE utf8mb4_bin NOT NULL,
+		client_id VARCHAR(191) COLLATE utf8mb4_bin NOT NULL,
+		claimed_at VARCHAR(35) NOT NULL,
+		PRIMARY KEY (task_id, client_id),
+		KEY idx_task_claims_client (client_id)
+	) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_0900_ai_ci`,
+	`CREATE TABLE IF NOT EXISTS syb_session (
+		username VARCHAR(191) COLLATE utf8mb4_bin PRIMARY KEY,
+		cookies LONGTEXT NOT NULL,
+		expires_at VARCHAR(35) NOT NULL,
+		updated_at VARCHAR(35) NOT NULL
+	) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_0900_ai_ci`,
+	`CREATE TABLE IF NOT EXISTS syb_sync_state (
+		id TINYINT PRIMARY KEY,
+		last_synced_at VARCHAR(35),
+		updated_at VARCHAR(35) NOT NULL,
+		CHECK (id = 1)
+	) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_0900_ai_ci`,
+	`CREATE TABLE IF NOT EXISTS users (
+		user_id VARCHAR(191) COLLATE utf8mb4_bin PRIMARY KEY,
+		username VARCHAR(191) COLLATE utf8mb4_0900_ai_ci NOT NULL UNIQUE,
+		password_hash VARCHAR(255) COLLATE utf8mb4_bin NOT NULL,
+		role VARCHAR(20) NOT NULL,
+		status VARCHAR(20) NOT NULL,
+		last_login_at VARCHAR(35),
+		password_changed_at VARCHAR(35) NOT NULL,
+		created_at VARCHAR(35) NOT NULL,
+		updated_at VARCHAR(35) NOT NULL,
+		CHECK (role IN ('admin', 'purchaser')),
+		CHECK (status IN ('active', 'disabled'))
+	) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_0900_ai_ci`,
+	`CREATE TABLE IF NOT EXISTS web_sessions (
+		session_hash VARCHAR(191) COLLATE utf8mb4_bin PRIMARY KEY,
+		user_id VARCHAR(191) COLLATE utf8mb4_bin NOT NULL,
+		expires_at VARCHAR(35) NOT NULL,
+		created_at VARCHAR(35) NOT NULL,
+		last_seen_at VARCHAR(35) NOT NULL,
+		KEY idx_web_sessions_user (user_id),
+		KEY idx_web_sessions_expiry (expires_at),
+		CONSTRAINT fk_web_sessions_user FOREIGN KEY (user_id) REFERENCES users(user_id)
+	) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_0900_ai_ci`,
+	`CREATE TABLE IF NOT EXISTS client_user_assignments (
+		assignment_id VARCHAR(191) COLLATE utf8mb4_bin PRIMARY KEY,
+		client_id VARCHAR(191) COLLATE utf8mb4_bin NOT NULL,
+		user_id VARCHAR(191) COLLATE utf8mb4_bin NOT NULL,
+		started_at VARCHAR(35) NOT NULL,
+		ended_at VARCHAR(35),
+		assigned_by_user_id VARCHAR(191) COLLATE utf8mb4_bin NOT NULL,
+		ended_by_user_id VARCHAR(191) COLLATE utf8mb4_bin,
+		end_reason VARCHAR(20),
+		current_client_id VARCHAR(191) COLLATE utf8mb4_bin
+			GENERATED ALWAYS AS (IF(ended_at IS NULL, client_id, NULL)) STORED,
+		UNIQUE KEY idx_client_assignment_current (current_client_id),
+		KEY idx_client_assignment_user (user_id, ended_at, client_id),
+		KEY idx_client_assignment_history (client_id, started_at DESC),
+		CONSTRAINT fk_client_assignment_user FOREIGN KEY (user_id) REFERENCES users(user_id),
+		CONSTRAINT fk_client_assignment_assigned_by FOREIGN KEY (assigned_by_user_id) REFERENCES users(user_id),
+		CONSTRAINT fk_client_assignment_ended_by FOREIGN KEY (ended_by_user_id) REFERENCES users(user_id),
+		CHECK (end_reason IS NULL OR end_reason IN ('unbind', 'transfer')),
+		CHECK ((ended_at IS NULL AND ended_by_user_id IS NULL AND end_reason IS NULL)
+			OR (ended_at IS NOT NULL AND ended_by_user_id IS NOT NULL AND end_reason IS NOT NULL))
+	) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_0900_ai_ci`,
+	`CREATE TABLE IF NOT EXISTS syb_sync_runs (
+		run_id VARCHAR(191) COLLATE utf8mb4_bin PRIMARY KEY,
+		user_id VARCHAR(191) COLLATE utf8mb4_bin NOT NULL,
+		date_from VARCHAR(10) NOT NULL,
+		date_to VARCHAR(10) NOT NULL,
+		status VARCHAR(20) NOT NULL,
+		stock_count BIGINT NOT NULL DEFAULT 0,
+		detail_count BIGINT NOT NULL DEFAULT 0,
+		created_count BIGINT NOT NULL DEFAULT 0,
+		updated_count BIGINT NOT NULL DEFAULT 0,
+		skipped_count BIGINT NOT NULL DEFAULT 0,
+		error_message TEXT,
+		cursor_advanced TINYINT NOT NULL DEFAULT 0,
+		started_at VARCHAR(35) NOT NULL,
+		finished_at VARCHAR(35),
+		KEY idx_syb_sync_runs_started (started_at DESC, run_id DESC),
+		CONSTRAINT fk_syb_sync_runs_user FOREIGN KEY (user_id) REFERENCES users(user_id),
+		CHECK (status IN ('running', 'succeeded', 'failed', 'interrupted')),
+		CHECK (cursor_advanced IN (0, 1)),
+		CHECK ((status = 'running' AND finished_at IS NULL)
+			OR (status <> 'running' AND finished_at IS NOT NULL))
+	) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_0900_ai_ci`,
+}
+
+// MigrateMySQL 建立或升级 MySQL schema。生产迁移只能在这里追加新版本。
+func MigrateMySQL(db *sql.DB) error {
+	if _, err := db.Exec(`CREATE TABLE IF NOT EXISTS schema_migrations (
+		version INT PRIMARY KEY,
+		applied_at VARCHAR(35) NOT NULL
+	) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_0900_ai_ci`); err != nil {
+		return fmt.Errorf("建立 MySQL 迁移版本表失败: %w", err)
+	}
+	var current int
+	if err := db.QueryRow(`SELECT COALESCE(MAX(version), 0) FROM schema_migrations`).Scan(&current); err != nil {
+		return fmt.Errorf("读取 MySQL schema 版本失败: %w", err)
+	}
+	if current > mysqlSchemaVersion {
+		return fmt.Errorf("MySQL schema 版本 %d 高于程序支持的 %d，请升级程序", current, mysqlSchemaVersion)
+	}
+	if current < 1 {
+		for i, statement := range mysqlSchemaV1 {
+			if _, err := db.Exec(statement); err != nil {
+				return fmt.Errorf("执行 MySQL schema v1 第 %d 条失败: %w", i+1, err)
+			}
+		}
+		if err := CheckMySQLSchema(db); err != nil {
+			return fmt.Errorf("MySQL schema v1 自检失败，未记录版本: %w", err)
+		}
+		if _, err := db.Exec(`INSERT INTO schema_migrations (version, applied_at) VALUES (?, ?)`,
+			1, time.Now().UTC().Format(time.RFC3339Nano)); err != nil {
+			return fmt.Errorf("记录 MySQL schema v1 失败: %w", err)
+		}
+	}
+	return CheckMySQLSchema(db)
+}
+
+// CheckMySQLSchema 确认所有业务表和关键追加列存在。
+func CheckMySQLSchema(db *sql.DB) error {
+	rows, err := db.Query(`SELECT table_name FROM information_schema.tables
+		WHERE table_schema = DATABASE() AND table_type = 'BASE TABLE'`)
+	if err != nil {
+		return fmt.Errorf("读取 MySQL 数据表清单失败: %w", err)
+	}
+	defer rows.Close()
+	existing := map[string]bool{}
+	for rows.Next() {
+		var name string
+		if err := rows.Scan(&name); err != nil {
+			return fmt.Errorf("读取 MySQL 数据表清单失败: %w", err)
+		}
+		existing[name] = true
+	}
+	if err := rows.Err(); err != nil {
+		return err
+	}
+	var missing []string
+	for _, table := range requiredTables {
+		if !existing[table] {
+			missing = append(missing, table)
+		}
+	}
+	if len(missing) > 0 {
+		return fmt.Errorf("MySQL schema 不完整，缺少表 %s", strings.Join(missing, "、"))
+	}
+	for table, columns := range requiredColumns {
+		for _, column := range columns {
+			var count int
+			if err := db.QueryRow(`SELECT COUNT(*) FROM information_schema.columns
+				WHERE table_schema = DATABASE() AND table_name = ? AND column_name = ?`,
+				table, column).Scan(&count); err != nil {
+				return fmt.Errorf("检查 MySQL 数据表 %s 的列失败: %w", table, err)
+			}
+			if count != 1 {
+				return fmt.Errorf("MySQL 数据表 %s 缺少列 %s", table, column)
+			}
+		}
+	}
+	return nil
+}

admin/repository/mysql_db_integration_test.go

@@ -0,0 +1,79 @@
+package repository
+
+import (
+	"database/sql"
+	"fmt"
+	"os"
+	"strings"
+	"testing"
+
+	"cmautobuy/admin/config"
+)
+
+// TestMySQLMigrate_真实MySQL8 只在显式提供隔离测试库时运行。
+// 库名必须以 _test 结尾，防止测试清理误碰生产库。
+func TestMySQLMigrate_真实MySQL8(t *testing.T) {
+	if os.Getenv("CMAUTOBUY_MYSQL_TEST") != "1" {
+		t.Skip("未启用真实 MySQL 8 集成测试")
+	}
+	cfg, err := config.LoadDatabaseFromEnv()
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !strings.HasSuffix(cfg.Name, "_test") {
+		t.Fatalf("拒绝清理非测试数据库 %q：库名必须以 _test 结尾", cfg.Name)
+	}
+	db, err := OpenMySQL(cfg)
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer db.Close()
+
+	cleanMySQLTestSchema(t, db)
+	defer cleanMySQLTestSchema(t, db)
+	if err := MigrateMySQL(db); err != nil {
+		t.Fatalf("首次建立 MySQL schema 失败: %v", err)
+	}
+	if err := MigrateMySQL(db); err != nil {
+		t.Fatalf("重复迁移应该无副作用: %v", err)
+	}
+	var version int
+	if err := db.QueryRow(`SELECT MAX(version) FROM schema_migrations`).Scan(&version); err != nil {
+		t.Fatal(err)
+	}
+	if version != mysqlSchemaVersion {
+		t.Fatalf("schema 版本=%d，期望 %d", version, mysqlSchemaVersion)
+	}
+}
+
+func cleanMySQLTestSchema(t *testing.T, db *sql.DB) {
+	t.Helper()
+	rows, err := db.Query(`SELECT table_name FROM information_schema.tables
+		WHERE table_schema = DATABASE() AND table_type = 'BASE TABLE'`)
+	if err != nil {
+		t.Fatal(err)
+	}
+	var tables []string
+	for rows.Next() {
+		var table string
+		if err := rows.Scan(&table); err != nil {
+			rows.Close()
+			t.Fatal(err)
+		}
+		tables = append(tables, table)
+	}
+	if err := rows.Close(); err != nil {
+		t.Fatal(err)
+	}
+	if _, err := db.Exec(`SET FOREIGN_KEY_CHECKS = 0`); err != nil {
+		t.Fatal(err)
+	}
+	defer db.Exec(`SET FOREIGN_KEY_CHECKS = 1`)
+	for _, table := range tables {
+		// 表名只来自当前 _test 数据库的 information_schema，并对反引号转义。
+		quoted := "`" + strings.ReplaceAll(table, "`", "``") + "`"
+		if _, err := db.Exec("DROP TABLE " + quoted); err != nil {
+			t.Fatal(fmt.Errorf("清理 MySQL 测试表 %s 失败: %w", table, err))
+		}
+	}
+}

docs/admin/00-getting-started.md

@@ -13,13 +13,12 @@
 |---|---|---|
 | Go | **1.23.0** | `go version` 输出 `go version go1.23.0 windows/amd64` |
 | Git | 任意较新版本 | `git --version` 有输出 |
-| DB Browser for SQLite | 任意 | 用来看数据库，可选但强烈建议装 |
+| MySQL Client | 8.4 | 用于连接独立的 MySQL 8.4 开发/测试库 |
 
 版本已定为 **go1.23.0**，写在 `admin/go.mod` 里。低于这个版本可能编译不过。
 
-**不需要装 gcc。** 本项目的 SQLite 驱动是纯 Go 实现的
-（`modernc.org/sqlite`），不依赖 cgo，这也是选它的原因——
-`go build` 直接出单个 exe，不用配 C 编译器。
+**不需要装 gcc。** 生产 MySQL 驱动和历史 SQLite 迁移驱动都是纯 Go；
+`go build` 不依赖 C 编译器。
 
 ## 2. 拉依赖
 
@@ -47,6 +46,7 @@ go mod download
 ```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
 ```
 
@@ -57,13 +57,13 @@ go mod tidy
 go get github.com/xuri/excelize/v2@v2.9.1
 ```
 
-这三个是**在 Go 1.23.0 下实测能编译通过的最高版本**，
+这些是在 Go 1.23.0 下实测能编译通过的固定版本，
 为什么不能更高见 [admin/AGENTS.md](../../admin/AGENTS.md) 技术栈一节。
 
 `[必须]` `go.mod` 和 `go.sum` 都要提交 Git，否则别人拉下来版本对不上。
 
-> SQLite 驱动**不要**换成 `mattn/go-sqlite3`，那个需要 cgo，
-> 得装 gcc，还会让 `go build` 出不了单文件 exe。
+> `go-sql-driver/mysql` v1.9.3 起要求 Go 1.24，本项目固定 v1.9.2。
+> SQLite 驱动只用于历史库迁移，仍不要换成需要 cgo 的 `mattn/go-sqlite3`。
 
 ## 3. 跑起来
 
@@ -157,21 +157,34 @@ syb:
 | `database is locked` | 有别的程序占着数据库 | 关掉 DB Browser 再试；程序运行时只读打开是可以的 |
 | 导入 Excel 报错但没说哪一行 | 解析器没带行号 | 这是 bug，报错必须带行号，见 [06](06-quality-security.md) §2 |
 
-## 6. 数据库在哪、怎么看
+## 6. 数据库在哪里、怎样配置
 
-跟 Client 一样是**便携模式**——数据都在程序旁边的 `data/` 里：
+生产数据在 MySQL 8.4 中。Admin 从环境变量读取连接信息：
+
+```text
+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 只读备份：
 
 ```text
 admin/data/
-├── admin.db        数据库
+├── backup/         迁移前的 admin.db 只读备份
 ├── logs/           运行日志
 └── uploads/        上传的 Excel 原件
 ```
 
 跑源码时在 `admin\data\`；将来打包成 exe 后，在 exe 旁边。
 
-用 **DB Browser for SQLite** 打开 `admin.db` 就能看数据。
-每张表什么意思见 [03 数据模型](03-data-model.md)。
+每张表什么意思见 [03 数据模型](03-data-model.md)。旧 `admin.db` 只能通过
+单向迁移命令读取，生产 Admin 不再直接打开它。
 
 > 写代码时**不要自己拼这个路径**，用统一的 `DataDir()` 函数，
 > 见 [02 架构](02-architecture.md) §6。

docs/admin/01-requirements.md

@@ -2,7 +2,7 @@
 
 - 文档状态：基线草案，待需求评审
 - 适用范围：`admin/`
-- 产品类型：本地运行的 Web 管理端（Go + Gin + HTML 模板）
+- 产品类型：集中部署的 Web 管理端（Go + Gin + HTML 模板 + MySQL 8.4）
 
 本文档中 `[必须]` / `[建议]` / `[待定]` 的含义见 [文档索引](../README.md#文档标注说明)。
 没有标注的默认是 `[必须]`。看不懂的词查 [术语表](00-glossary.md)。
@@ -410,7 +410,7 @@ PDD 商品之所以单独一个模块，是因为它在数据上就是**独立
 MVP 包含：
 
 - 五模块页面框架和统一的三段式布局；
-- SQLite 建库与迁移；
+- MySQL 8.4 建库与追加式迁移；SQLite 仅作为一次性历史数据迁移来源；
 - 蝦皮 Excel 导入（upsert）、搜索、批量删除、手动新增、编辑弹窗；
 - PDD 链接录入与发起采集；
 - 顺运宝数据的**手工录入或造数**（同步按钮占位）；
@@ -441,7 +441,7 @@ MVP 之后：
 
 ## 10. 非功能需求
 
-- 单机运行，操作人员规模是个位数，不追求高并发。
+- 集中部署，操作人员规模是个位数；不追求大规模并发，但任务领取必须保证并发唯一。
 - 页面在 1366×768 上可正常使用。
 - 导入 1 万行 Excel 应在可接受时间内完成，并显示进度或结果统计。
 - 所有写操作有 CSRF 防护，所有 SQL 参数化。

docs/admin/02-architecture.md

@@ -29,7 +29,7 @@
 └───────────────────────┬──────────────────────┘
                         │
 ┌───────────────────────▼──────────────────────┐
-│ repository       SQLite 读写                  │
+│ repository       MySQL 8 读写                 │
 │                  只有这一层能写 SQL           │
 └───────────────────────┬──────────────────────┘
                         │
@@ -162,7 +162,7 @@ templates/
 
 ```text
 data/
-├── admin.db        SQLite 数据库
+├── backup/         迁移前 SQLite 只读备份
 ├── logs/           运行日志
 └── uploads/        上传的 Excel 原件
 ```
@@ -212,7 +212,8 @@ func DataDir() (string, error) {
 | 直接用 `os.Getwd()` | 双击 exe 和命令行启动，当前目录不一样 |
 | 往 exe 所在目录写日志但不建 `data/` | 打包后和程序文件混在一起，升级时会被删 |
 
-`[必须]` 升级方式：换掉 exe，**`data/` 原样保留**。所以数据库必须支持迁移，见 [03](03-data-model.md) §2。
+`[必须]` 升级时保留 `data/`，并先备份 MySQL。数据库结构通过 MySQL
+`schema_migrations` 只追加升级，见 [03](03-data-model.md) §2。
 
 ## 7. 请求流程示例
 

docs/admin/03-data-model.md

@@ -1,8 +1,9 @@
 # 03 Admin 数据模型
 
 - 文档状态：基线草案，待数据评审
-- 数据库：SQLite（驱动 `modernc.org/sqlite`，纯 Go 免 cgo）
-- 位置：`data/admin.db`，见 [02 架构](02-architecture.md) §6
+- 生产数据库：MySQL 8.4（驱动 `go-sql-driver/mysql` v1.9.2）
+- 位置：与 Admin 同机的 `127.0.0.1:3307`，使用独立数据库和最小权限账号
+- 历史数据库：`data/admin.db` 只作为 SQLite → MySQL 单向迁移来源和回退备份
 
 本文档中 `[必须]` / `[建议]` / `[待定]` 的含义见 [文档索引](../README.md#文档标注说明)。
 没有标注的默认是 `[必须]`。看不懂的词查 [术语表](00-glossary.md)。
@@ -19,6 +20,13 @@
 
 ## 2. 建库与迁移
 
+生产 MySQL 使用 `schema_migrations` 记录追加版本。MySQL DDL 会隐式提交，
+因此每条 DDL 必须可重放；整版全部执行、通过表和关键列自检后才记录版本。
+连接会话固定 UTC，字符集固定 `utf8mb4`，业务 ID 使用二进制排序规则保持大小写精确。
+
+下面的 PRAGMA 和 `user_version` 章节是历史 SQLite 迁移规则，只供单向迁移工具维护，
+不得重新接入生产运行时。
+
 ### 2.1 PRAGMA 必须写在 DSN 里
 
 `[必须]` 三条设置通过**连接串**传入，**不要**用 `db.Exec("PRAGMA ...")`：
@@ -444,7 +452,7 @@ CREATE INDEX idx_syb_orders_list   ON syb_orders(updated_at DESC, syb_id DESC);
 
 - `price_twd_cent` 是**台币分**，是蝦皮那边的售价，
   和采购任务的人民币价格上限**没有换算关系**，不要互相赋值。
-- `image_url` 存 URL。`[必须]` 不要把图片二进制存进 SQLite。
+- `image_url` 存 URL。`[必须]` 不要把图片二进制存进数据库。
 - `shopee_sku_id` **直接对应 `shopee_skus.sku_id`**，编号格式一致，不需要额外转换。
 
 `[必须]` 但**不要加外键约束**。理由：蝦皮报表不是全量目录（样本里平均每商品仅 1.17 个 SKU），
@@ -713,7 +721,7 @@ users（采购员）──1:N 当前归属──────────┘
 
 ## 11. 与 Client 数据模型的关系
 
-Admin 和 Client **各有一个 SQLite，互不相通**，只通过接口交换数据。
+Admin 使用集中 MySQL 8.4，Client 仍使用各自的本地 SQLite；两者只通过接口交换数据。
 
 | 概念 | Admin 这边 | Client 那边 |
 |---|---|---|
@@ -744,7 +752,7 @@ CREATE TABLE users (
 
 - `password_hash` 只保存成熟密码哈希算法的结果，绝不保存或记录明文密码。
 - 用户不做物理删除；离职或停用改为 `disabled`，保留任务和操作记录的可追溯性。
-- 首次初始化必须在写事务中再次确认 `users` 为空；SQLite 同一时刻只有一个写事务，
+- 首次初始化必须在 InnoDB 写事务中锁定初始化保护记录并再次确认 `users` 为空，
   并发提交最多一个成功。即使所有账号都被禁用，初始化入口也不能重新开放。
 - 系统不能禁用最后一个有效管理员。
 

docs/admin/06-quality-security.md

@@ -48,7 +48,7 @@
 
 ### 2.2 集成测试
 
-用临时 SQLite 覆盖：
+用独立、库名以 `_test` 结尾的真实 MySQL 8.4 测试库覆盖：
 
 - 完整导入 → 建采集任务 → 模拟 Client 提交结果 → `collect_status` 变 `collected`；
 - 并发 `claim`：两个客户端同时领，只有一个拿到；
@@ -93,7 +93,8 @@
 | 迁移前备份或用可回滚步骤 | `data/` 在升级时保留，迁移失败会毁掉全部历史 |
 | **不得在启动时删库重建** | 同上 |
 
-`[建议]` 导入前自动把 `admin.db` 复制一份到 `data/backup/`，保留最近几份。
+`[必须]` 生产变更前执行 MySQL 备份；SQLite 最终迁移前把 `admin.db` 复制到
+`data/backup/` 并保持只读，至少保留到生产验收完成。
 
 ## 4. Web 安全
 
@@ -166,7 +167,7 @@
 
 ## 7. 性能
 
-规模很小（个位数操作员、单机运行），不要提前优化。但下面几条是基本功：
+规模很小（个位数操作员、集中部署），不要提前优化。但下面几条是基本功：
 
 - `[必须]` 搜索、排序、分页走**数据库查询**，不要一次查全量再在内存里过滤。
 - `[必须]` 常用查询有索引（见 [03 数据模型](03-data-model.md) 里的 `CREATE INDEX`）。
@@ -182,7 +183,7 @@
 | 3 | `go test ./...` 全绿 | 不允许有跳过而未说明的用例 | 开发者 |
 | 4 | 五个页面能正常打开 | 起服务跑一遍 | 开发者 |
 | 5 | 样本导入条数正确 | 导入参考样本（需向项目负责人索取，放 `raw_data/`），应得 5195 商品 + 6092 SKU | 开发者 |
-| 6 | 数据库从上一版本迁移成功 | 拿旧 `admin.db` 副本启动新版本，人工数据不丢 | 开发者 |
+| 6 | 数据库升级和 SQLite 单向迁移成功 | 隔离 MySQL 升级通过；旧 `admin.db` 迁移后逐表核对一致 | 开发者 |
 | 7 | 契约测试通过 | [04 §9 清单](04-client-api.md)逐条 | 开发者 |
 | 8 | 干净环境启动 | 没装过本项目的机器上 `go run .` 或跑 exe | 开发者 |
 | 9 | 日志和页面无敏感信息 | 翻一遍 `data/logs/` | 开发者 |
@@ -194,6 +195,9 @@
 
 第 10 项开发者**不要自己判断放行**，把包名和许可证类型报给项目负责人。
 
+当前新增生产数据库驱动：`github.com/go-sql-driver/mysql` v1.9.2，许可证
+**MPL-2.0**。技术验证通过不代表许可证已获发布批准，仍需项目负责人确认门禁 10。
+
 ## 9. 打包
 
 `[待定]` 打包动作属于 MVP 之后，但策略现在定下来：
@@ -203,7 +207,7 @@
 - 模板和静态文件用 `//go:embed` 打进 exe，**不要散在外面**，
   否则用户可能改坏或删掉；
 - `data/` 留在 exe 旁边，**升级时保留**，见 [02 架构](02-architecture.md) §6；
-- 升级方式：换掉 exe，`data/` 不动，靠 `PRAGMA user_version` 自动迁移。
+- 升级方式：替换服务程序，先备份 MySQL，再由 `schema_migrations` 追加升级。
 
 产出目录：
 
@@ -211,7 +215,7 @@
 CMAutoBuyAdmin/
 ├── admin.exe        单文件，模板和静态资源都在里面
 └── data/            数据，升级时保留
-    ├── admin.db
+    ├── backup/         迁移前 SQLite 只读备份
     ├── logs/
     └── uploads/
 ```