feat: 顺运宝货运单同步 (#46)

顺运宝模块此前是骨架，「同步」点了提示"待接入"。5195 个蝦皮商品已经进系统，但货运单（真实订单）一条都没有，后面的规格匹配无从谈起。按接口契约（docs/admin/08，从 4 份 HAR 还原）实现：配置、登录（界面手工输验证码）、会话缓存到 SQLite、按日期范围增量同步、落 syb_orders。 shopee_sku_id 绝不被同步覆盖。它是规格匹配的结果，顺运宝那边根本没有这个值（只给 11 位商品ID，蝦皮規格ID 是 12 位）。同步写进去就是写空，把人工攒的匹配成果洗掉且不报错。它只出现在 INSERT 列清单里，不在 DO UPDATE SET 里；repository 层和 service 端到端各有一个测试守着。增量从「上次同步日期当天」重拉，不是第二天。created 筛选粒度是日期而 last_synced_at 精确到秒，从第二天拉会漏掉当天晚些时候创建的单且不报错。宁可重复拉（upsert 幂等）也不能漏。中途失败不更新 last_synced_at，否则下次跳过这段区间，漏的单永远补不回来。日期运算用 UTC+8，不是 UTC。审查时从 HAR 确认 created 是当地时间：抓包于 2026-07-28T03:31:45Z（= 11:31 UTC+8），同一响应里 created 是 "2026-07-28 10:37:59"；若它是 UTC 则等于 18:37 UTC+8，比抓包晚 7 小时，订单创建于未来，不成立。用 UTC 算会在本地 00:00-08:00 把"今天"算成昨天，当天早晨的单这轮拉不到。用 time.FixedZone 写死，不用 LoadLocation—— 那要读系统 tzdata，Windows 默认没有，打包成 exe 会失败。金额一律取 detail/listByStock 的值：08 §5.1 实测同一响应里 amtOrder 在列表接口是分、escrowAmount 却不是，单位不统一，取错差 100 倍。迁移 v5 纯追加（syb_session、syb_sync_state、syb_orders.product_spec）， v1-v4 逐字未动，CheckSchema 覆盖新表新列。会话有效性判断把「网络故障」和「明确未登录」的分类集中在 Client.do() 一处——网络抖一下就判定登出的话，验证码会弹个不停，还会丢掉有效会话。测试全部用 httptest 假服务端，不打真实站点。 Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-09 11:49:13 +08:00
parent 7fb137f685
commit 5e426cacf6
22 changed files with 3659 additions and 49 deletions
@@ -543,6 +543,149 @@ func TestMigrate_v2新结构库只更新版本号不打误导性日志(t *testin
 	}
 }

+// ── v5：顺运宝会话表、同步状态表、product_spec 列 ──────
+
+// TestMigrate_不同起点最终schema一致（上面已有）用的是全量 dumpSchema 对比，
+// v5 的新表/新列不需要改那个测试就已经被覆盖——这里再加行为断言，
+// 专门锁住 v5 引入的三样东西，即使将来有人改坏了三起点收敛测试本身，
+// 这几个测试仍然能单独发现问题。
+func TestMigrate_v5新增会话表同步状态表和product_spec列(t *testing.T) {
+	for _, c := range []struct {
+		name string
+		db   *sql.DB
+	}{
+		{"全新库", newFreshDB(t)},
+		{"v2 老结构库", newV2DB(t)},
+		{"v2 新结构库", newV2NewStructureDB(t)},
+	} {
+		if c.name != "全新库" {
+			if err := Migrate(c.db); err != nil {
+				t.Fatalf("%s 迁移失败: %v", c.name, err)
+			}
+		}
+
+		var version int
+		if err := c.db.QueryRow("PRAGMA user_version").Scan(&version); err != nil {
+			t.Fatalf("%s 读取 user_version 失败: %v", c.name, err)
+		}
+		if version != schemaVersion {
+			t.Fatalf("%s user_version = %d，期望 %d", c.name, version, schemaVersion)
+		}
+
+		tables := existingTableSet(t, c.db)
+		for _, table := range []string{"syb_session", "syb_sync_state"} {
+			if !tables[table] {
+				t.Errorf("%s：迁移后应该有表 %s", c.name, table)
+			}
+		}
+
+		cols, err := tableColumnSet(c.db, "syb_orders")
+		if err != nil {
+			t.Fatalf("%s 读取 syb_orders 列失败: %v", c.name, err)
+		}
+		if !cols["product_spec"] {
+			t.Errorf("%s：syb_orders 迁移后应该有 product_spec 列", c.name)
+		}
+
+		if err := CheckSchema(c.db); err != nil {
+			t.Errorf("%s：迁移后应该通过自检: %v", c.name, err)
+		}
+	}
+}
+
+// existingTableSet 返回库里当前存在的表名集合。
+func existingTableSet(t *testing.T, db *sql.DB) map[string]bool {
+	t.Helper()
+	rows, err := db.Query(`SELECT name FROM sqlite_master WHERE type = 'table'`)
+	if err != nil {
+		t.Fatalf("读取表清单失败: %v", err)
+	}
+	defer rows.Close()
+	set := map[string]bool{}
+	for rows.Next() {
+		var name string
+		if err := rows.Scan(&name); err != nil {
+			t.Fatalf("读取表清单失败: %v", err)
+		}
+		set[name] = true
+	}
+	return set
+}
+
+// TestMigrate_v5会话表主键只允许一个用户名一行 验证 syb_session 的主键约束：
+// 同一个用户名重复写入应该走 upsert（由 repository 层保证），底层主键必须
+// 拒绝真正的重复插入，防止同一账号在表里出现两行、读的时候不知道信哪行。
+func TestMigrate_v5会话表主键约束(t *testing.T) {
+	db := newFreshDB(t)
+	const now = "2026-08-09T00:00:00Z"
+	insert := func() error {
+		_, err := db.Exec(`
+			INSERT INTO syb_session (username, cookies, expires_at, updated_at)
+			VALUES (?, ?, ?, ?)`, "tester", `[]`, now, now)
+		return err
+	}
+	if err := insert(); err != nil {
+		t.Fatalf("插入第一条会话失败: %v", err)
+	}
+	if err := insert(); err == nil {
+		t.Fatal("同一 username 重复插入应该被主键约束拒绝")
+	}
+}
+
+// TestMigrate_v5同步状态表只允许一行 验证 CHECK (id = 1) 确实生效——
+// 这张表按设计只应该有一行（全局的"上次同步到哪"），如果这条 CHECK
+// 被误删或写错，程序里到处用 id=1 查询的代码会开始读到错误的行。
+func TestMigrate_v5同步状态表只允许id为1(t *testing.T) {
+	db := newFreshDB(t)
+	const now = "2026-08-09T00:00:00Z"
+	if _, err := db.Exec(`
+		INSERT INTO syb_sync_state (id, last_synced_at, updated_at)
+		VALUES (1, NULL, ?)`, now); err != nil {
+		t.Fatalf("插入 id=1 失败: %v", err)
+	}
+	_, err := db.Exec(`
+		INSERT INTO syb_sync_state (id, last_synced_at, updated_at)
+		VALUES (2, NULL, ?)`, now)
+	if err == nil {
+		t.Fatal("id != 1 应该被 CHECK 约束拒绝")
+	}
+}
+
+func TestCheckSchema_缺少syb_session表时拒绝(t *testing.T) {
+	db := newFreshDB(t)
+	if _, err := db.Exec(`DROP TABLE syb_session`); err != nil {
+		t.Fatalf("删表失败: %v", err)
+	}
+	err := CheckSchema(db)
+	if err == nil || !strings.Contains(err.Error(), "syb_session") {
+		t.Fatalf("缺 syb_session 表时应该拒绝启动并指出表名，实际 %v", err)
+	}
+}
+
+func TestCheckSchema_缺少syb_sync_state表时拒绝(t *testing.T) {
+	db := newFreshDB(t)
+	if _, err := db.Exec(`DROP TABLE syb_sync_state`); err != nil {
+		t.Fatalf("删表失败: %v", err)
+	}
+	err := CheckSchema(db)
+	if err == nil || !strings.Contains(err.Error(), "syb_sync_state") {
+		t.Fatalf("缺 syb_sync_state 表时应该拒绝启动并指出表名，实际 %v", err)
+	}
+}
+
+func TestCheckSchema_缺少product_spec列时拒绝(t *testing.T) {
+	db := newFreshDB(t)
+	// modernc.org/sqlite 支持 DROP COLUMN（SQLite ≥ 3.35），
+	// 用它来模拟"迁移没有完整落地、只有旧列"的库。
+	if _, err := db.Exec(`ALTER TABLE syb_orders DROP COLUMN product_spec`); err != nil {
+		t.Fatalf("模拟缺列失败: %v", err)
+	}
+	err := CheckSchema(db)
+	if err == nil || !strings.Contains(err.Error(), "product_spec") {
+		t.Fatalf("缺 product_spec 列时应该拒绝启动并指出列名，实际 %v", err)
+	}
+}
+
 // ── 最终 schema 的硬约束：不依赖路径比对 ──────────────
 //
 // TestMigrate_不同起点最终schema一致 证明的是"全新库"和"v2 老库"两条路径
@@ -884,6 +1027,11 @@ func TestCheckSchema_缺少v4关键列时拒绝(t *testing.T) {
 	if err := migrateV3(db); err != nil {
 		t.Fatalf("准备 v3 数据库失败: %v", err)
 	}
+	// 故意跳过 v4（不加 shop_name），但把 v5 补上——否则 CheckSchema 会先
+	// 因为缺 v5 的表报错，测不到本测试真正要覆盖的"缺 shop_name"这条路径。
+	if err := runSQLMigration(db, 5, migrationV5); err != nil {
+		t.Fatalf("准备 v5 数据库失败: %v", err)
+	}

 	err := CheckSchema(db)
 	if err == nil || !strings.Contains(err.Error(), "shop_name") {