feat: 搭建 Admin 项目骨架（Go + Gin + html/template）
可运行的骨架：四个页面能打开、数据库自动建表、给 Client 的三个接口
按契约响应。业务逻辑留 35 处 TODO(骨架)，每处标明要点和文档章节。
结构（对应 docs/admin/02-architecture.md §2/§3）
- handler/web + handler/api 分开：页面要 CSRF、出错渲染错误页；
接口要认证、出错返回 JSON。混在一起迟早写错
- service 不认识 *gin.Context，方便不起服务器直接单测
- 只有 repository 能写 SQL
- 模板用 {{define "目录/名字"}}，一次全部 ParseFS 进来不冲突
- 模板和静态资源用 //go:embed 打进二进制
已实测（Go 1.23.0，本机验证）
- go build / go vet / gofmt 全部通过
- 单文件产物 34MB，无需 cgo
- 四个页面 + 静态资源均 200，/ 正确 302 到 /shopee
- 建表 7 张 + 索引 10 个，user_version=1，二次启动不重复建表
- claim 带 X-Client-Id 返回 204（无任务可领），
缺 X-Client-Id 返回 400 + 契约格式的 JSON 错误体
依赖版本被 Go 1.23.0 卡死，已钉住并写进文档
- gin v1.11.0 （v1.12.0 起要求 Go >= 1.25.0）
- modernc.org/sqlite v1.38.0（v1.40.0 起要求 >= 1.24.0，v1.48.0 起 >= 1.25.0）
- excelize v2.9.1 （尚未入 go.mod，写导入功能时再加）
直接 go get 不带版本会拉到最新版并报 requires go >= 1.25.0，
所以文档里的命令一律带版本号。要升依赖就得先升 Go。
一处主动调整：迁移语句从「一个字符串装多条 SQL」改成 [][]string 逐条执行。
database/sql 的 Exec 对一次多条语句的支持因驱动而异，拆开最稳妥，
报错还能精确到第几条。
说明：Gitea 尚未配置，本次无对应工单号。
admin/testdata/ 只有 README，脱敏小样本需人工制作。
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
chengma
@@ -0,0 +1,214 @@
|
||||
// Package repository 封装 SQLite 读写。
|
||||
//
|
||||
// 改动本文件前必读 admin/AGENTS.md。三条硬规则：
|
||||
// - 只有本包能写 SQL，handler 和 service 都不许拼 SQL；
|
||||
// - SQL 一律参数化查询（用 ? 占位），禁止字符串拼接；
|
||||
// - 迁移只能往前加，不许在启动时删库重建——data/ 在升级时是保留的，
|
||||
// 里面有人工填了几个月的 PDD 链接和 SKU 映射。
|
||||
//
|
||||
// 表结构的权威定义在 docs/admin/03-data-model.md，改表要先改文档。
|
||||
package repository
|
||||
|
||||
import (
|
||||
"database/sql"
|
||||
"fmt"
|
||||
"path/filepath"
|
||||
|
||||
// 纯 Go 的 SQLite 驱动，注册的驱动名是 "sqlite"（不是 "sqlite3"）。
|
||||
// 不得换成 github.com/mattn/go-sqlite3，那个需要 cgo，
|
||||
// Windows 上要装 gcc，打包 exe 会变麻烦。理由见 admin/AGENTS.md。
|
||||
_ "modernc.org/sqlite"
|
||||
)
|
||||
|
||||
// Open 打开 data/admin.db，并设置必要的 PRAGMA。
|
||||
func Open(dataDir string) (*sql.DB, error) {
|
||||
path := filepath.Join(dataDir, "admin.db")
|
||||
|
||||
db, err := sql.Open("sqlite", path)
|
||||
if err != nil {
|
||||
return nil, fmt.Errorf("打开数据库 %s 失败: %w", path, err)
|
||||
}
|
||||
|
||||
// 这三条见 docs/admin/03-data-model.md §2
|
||||
pragmas := []string{
|
||||
"PRAGMA foreign_keys = ON",
|
||||
"PRAGMA journal_mode = WAL",
|
||||
"PRAGMA busy_timeout = 5000",
|
||||
}
|
||||
for _, p := range pragmas {
|
||||
if _, err := db.Exec(p); err != nil {
|
||||
db.Close()
|
||||
return nil, fmt.Errorf("执行 %s 失败: %w", p, err)
|
||||
}
|
||||
}
|
||||
return db, nil
|
||||
}
|
||||
|
||||
// migrations 按顺序存放每一版的迁移语句。
|
||||
//
|
||||
// 外层一个元素 = 一个版本；内层是该版本要执行的语句，**一条一执行**。
|
||||
// 不把多条语句塞进一个字符串，是因为 database/sql 的 Exec 对
|
||||
// "一次执行多条语句"的支持因驱动而异，拆开最稳妥。
|
||||
//
|
||||
// 加新版本时**只能往末尾追加**，不许改动已有元素——
|
||||
// 已经发布出去的库是按旧语句建的，改了会导致新旧库结构不一致。
|
||||
var migrations = [][]string{
|
||||
// v1: 初始表结构，对应 docs/admin/03-data-model.md
|
||||
{
|
||||
`CREATE TABLE shopee_products (
|
||||
goods_id TEXT PRIMARY KEY,
|
||||
title TEXT NOT NULL,
|
||||
shopee_status TEXT,
|
||||
main_sku_code TEXT,
|
||||
|
||||
-- 下面三个是人工维护的，报表里没有，导入时绝不能覆盖
|
||||
pdd_goods_url TEXT,
|
||||
pdd_goods_id TEXT,
|
||||
pdd_data TEXT,
|
||||
|
||||
collect_status TEXT NOT NULL DEFAULT 'no_link'
|
||||
CHECK (collect_status IN (
|
||||
'no_link', 'pending', 'collecting',
|
||||
'collected', 'failed'
|
||||
)),
|
||||
collect_error TEXT,
|
||||
collected_at TEXT,
|
||||
created_at TEXT NOT NULL,
|
||||
updated_at TEXT NOT NULL
|
||||
);`,
|
||||
`CREATE INDEX idx_shopee_products_status ON shopee_products(collect_status);`,
|
||||
`CREATE TABLE shopee_skus (
|
||||
sku_id TEXT PRIMARY KEY,
|
||||
goods_id TEXT NOT NULL,
|
||||
spec_raw TEXT NOT NULL,
|
||||
color TEXT,
|
||||
size TEXT,
|
||||
advice TEXT,
|
||||
parse_ok INTEGER NOT NULL DEFAULT 0,
|
||||
sku_code TEXT,
|
||||
is_manual INTEGER NOT NULL DEFAULT 0,
|
||||
created_at TEXT NOT NULL,
|
||||
updated_at TEXT NOT NULL,
|
||||
FOREIGN KEY (goods_id) REFERENCES shopee_products(goods_id) ON DELETE CASCADE
|
||||
);`,
|
||||
`CREATE INDEX idx_shopee_skus_goods ON shopee_skus(goods_id);`,
|
||||
`CREATE INDEX idx_shopee_skus_parse ON shopee_skus(parse_ok);`,
|
||||
`CREATE TABLE syb_orders (
|
||||
syb_id TEXT PRIMARY KEY,
|
||||
order_no TEXT NOT NULL,
|
||||
title TEXT,
|
||||
shopee_goods_id TEXT,
|
||||
shopee_sku_id TEXT,
|
||||
quantity INTEGER NOT NULL CHECK (quantity > 0),
|
||||
price_twd_cent INTEGER CHECK (price_twd_cent IS NULL OR price_twd_cent >= 0),
|
||||
image_url TEXT,
|
||||
syb_data TEXT NOT NULL DEFAULT '{}',
|
||||
created_at TEXT NOT NULL,
|
||||
updated_at TEXT NOT NULL
|
||||
);`,
|
||||
`CREATE INDEX idx_syb_orders_order ON syb_orders(order_no);`,
|
||||
`CREATE INDEX idx_syb_orders_goods ON syb_orders(shopee_goods_id);`,
|
||||
`CREATE INDEX idx_syb_orders_list ON syb_orders(updated_at DESC, syb_id DESC);`,
|
||||
`CREATE TABLE sku_mappings (
|
||||
shopee_sku_id TEXT PRIMARY KEY,
|
||||
goods_id TEXT NOT NULL,
|
||||
pdd_options TEXT NOT NULL,
|
||||
mapped_at TEXT NOT NULL,
|
||||
mapped_by TEXT,
|
||||
FOREIGN KEY (shopee_sku_id) REFERENCES shopee_skus(sku_id) ON DELETE CASCADE
|
||||
);`,
|
||||
`CREATE INDEX idx_sku_mappings_goods ON sku_mappings(goods_id);`,
|
||||
`CREATE TABLE tasks (
|
||||
task_id TEXT PRIMARY KEY,
|
||||
task_type TEXT NOT NULL CHECK (task_type IN ('collect', 'purchase')),
|
||||
status TEXT NOT NULL DEFAULT 'pending'
|
||||
CHECK (status IN ('pending', 'assigned', 'claimed',
|
||||
'succeeded', 'manual_review',
|
||||
'failed', 'cancelled')),
|
||||
version INTEGER NOT NULL DEFAULT 1 CHECK (version > 0),
|
||||
priority INTEGER NOT NULL DEFAULT 0,
|
||||
|
||||
assigned_client TEXT,
|
||||
claimed_at TEXT,
|
||||
|
||||
syb_id TEXT,
|
||||
order_no TEXT,
|
||||
goods_id TEXT,
|
||||
shopee_sku_id TEXT,
|
||||
|
||||
-- Client 契约要求：pdd_goods_url 必填；
|
||||
-- 采购任务的 quantity 和 max_price_cent 也必填（价格保护）
|
||||
pdd_goods_url TEXT NOT NULL,
|
||||
pdd_goods_id TEXT,
|
||||
pdd_options TEXT,
|
||||
quantity INTEGER CHECK (quantity IS NULL OR quantity > 0),
|
||||
max_price_cent INTEGER CHECK (max_price_cent IS NULL OR max_price_cent > 0),
|
||||
|
||||
result_data TEXT,
|
||||
error_code TEXT,
|
||||
error_message TEXT,
|
||||
finished_at TEXT,
|
||||
|
||||
created_at TEXT NOT NULL,
|
||||
updated_at TEXT NOT NULL
|
||||
);`,
|
||||
`CREATE INDEX idx_tasks_claim ON tasks(assigned_client, status, priority DESC, created_at);`,
|
||||
`CREATE INDEX idx_tasks_list ON tasks(updated_at DESC, task_id DESC);`,
|
||||
`CREATE INDEX idx_tasks_order ON tasks(order_no);`,
|
||||
`CREATE TABLE clients (
|
||||
client_id TEXT PRIMARY KEY,
|
||||
name TEXT,
|
||||
device_address TEXT,
|
||||
platform TEXT,
|
||||
pdd_package TEXT,
|
||||
capabilities TEXT,
|
||||
last_seen_at TEXT NOT NULL,
|
||||
created_at TEXT NOT NULL,
|
||||
updated_at TEXT NOT NULL
|
||||
);`,
|
||||
`CREATE TABLE idempotency_keys (
|
||||
key TEXT PRIMARY KEY,
|
||||
request_hash TEXT NOT NULL,
|
||||
response_body TEXT NOT NULL,
|
||||
created_at TEXT NOT NULL
|
||||
);`,
|
||||
},
|
||||
}
|
||||
|
||||
// Migrate 把数据库升到最新版本。
|
||||
// 已经是最新的就什么都不做，可以重复调用。
|
||||
func Migrate(db *sql.DB) error {
|
||||
var current int
|
||||
if err := db.QueryRow("PRAGMA user_version").Scan(¤t); err != nil {
|
||||
return fmt.Errorf("读取 user_version 失败: %w", err)
|
||||
}
|
||||
|
||||
if current > len(migrations) {
|
||||
return fmt.Errorf(
|
||||
"数据库版本 %d 高于本程序支持的 %d，"+
|
||||
"说明这个库是更新版本的程序建的，请升级程序而不是降级",
|
||||
current, len(migrations))
|
||||
}
|
||||
|
||||
for v := current; v < len(migrations); v++ {
|
||||
tx, err := db.Begin()
|
||||
if err != nil {
|
||||
return fmt.Errorf("开始迁移 v%d 失败: %w", v+1, err)
|
||||
}
|
||||
for i, stmt := range migrations[v] {
|
||||
if _, err := tx.Exec(stmt); err != nil {
|
||||
tx.Rollback()
|
||||
return fmt.Errorf("执行迁移 v%d 第 %d 条语句失败: %w", v+1, i+1, err)
|
||||
}
|
||||
}
|
||||
// PRAGMA 不支持参数化，这里的值来自循环变量而非外部输入，安全。
|
||||
if _, err := tx.Exec(fmt.Sprintf("PRAGMA user_version = %d", v+1)); err != nil {
|
||||
tx.Rollback()
|
||||
return fmt.Errorf("更新 user_version 到 %d 失败: %w", v+1, err)
|
||||
}
|
||||
if err := tx.Commit(); err != nil {
|
||||
return fmt.Errorf("提交迁移 v%d 失败: %w", v+1, err)
|
||||
}
|
||||
}
|
||||
return nil
|
||||
}
|
||||
Reference in New Issue
Block a user