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>

admin/handler/web/others.go

@@ -0,0 +1,120 @@
+package web
+
+import (
+	"net/http"
+
+	"github.com/gin-gonic/gin"
+)
+
+// ---------- 2. 顺运宝数据 ----------
+
+// SybList 渲染货运单列表页。
+// 「匹配状态」是算出来的（sku_mappings 里有没有记录），不是存的字段。
+func (h *Handler) SybList(c *gin.Context) {
+	keyword := c.Query("order_no")
+
+	// TODO(骨架): 查货运单，并左联 sku_mappings 得出匹配状态
+	var rows []gin.H
+
+	c.HTML(http.StatusOK, "syb/list", page("syb", "顺运宝数据", gin.H{
+		"Keyword": keyword,
+		"Rows":    rows,
+		"Status":  "尚未实现：同步或手工录入后这里显示货运单",
+	}))
+}
+
+// SybSync 从顺运宝同步待处理货运单。
+//
+// MVP 阶段只做占位，见 docs/admin/01-requirements.md §11 待确认 #1。
+func (h *Handler) SybSync(c *gin.Context) {
+	// TODO(等待确认): 顺运宝的同步方式（接口？导出文件？）还没定。
+	//   定了之后在这里实现，注意完整响应要原样存进 syb_data 字段。
+	fail(c, http.StatusNotImplemented,
+		"同步功能待接入。顺运宝的对接方式尚未确定，"+
+			"当前可以先手工录入货运单用于联调。")
+}
+
+// SybMatch 保存规格匹配结果。
+//
+// 关键：保存的是**可复用的 SKU 映射**（写 sku_mappings），
+// 不是这一张订单的临时数据。下次遇到同一个蝦皮 SKU 自动带出，
+// 操作员只需确认。见 docs/admin/03-data-model.md §5。
+func (h *Handler) SybMatch(c *gin.Context) {
+	// TODO(骨架): upsert sku_mappings
+	fail(c, http.StatusNotImplemented, "规格匹配尚未实现。")
+}
+
+// SybCreateTask 由勾选的货运单创建采购任务。
+//
+// 六条校验缺一不可，见 docs/admin/01-requirements.md §5：
+//  1. 已填 PDD 链接
+//  2. 已采集成功（pdd_data 非空）
+//  3. 已有 SKU 映射
+//  4. 数量 > 0
+//  5. **价格上限已填且 > 0**（Client 的价格保护，没有它会拒绝执行）
+//  6. 已选择分配的客户端
+//
+// 校验不过的**不要静默跳过**，要列出来告诉操作员缺什么。
+func (h *Handler) SybCreateTask(c *gin.Context) {
+	// TODO(骨架): 调 service.CreatePurchaseTasks(sybIDs, clientID)
+	fail(c, http.StatusNotImplemented, "创建采购任务尚未实现。")
+}
+
+// SybDelete 批量删除货运单。
+func (h *Handler) SybDelete(c *gin.Context) {
+	// TODO(骨架)
+	fail(c, http.StatusNotImplemented, "删除功能尚未实现。")
+}
+
+// ---------- 3. 采购任务 ----------
+
+// TaskList 渲染采购任务列表页。
+//
+// 注意颜色尺码显示的是 **PDD 侧**的规格（实际要买的），不是蝦皮的。
+// 价格上限显示成 ¥42.00，底层存的是整数分。
+func (h *Handler) TaskList(c *gin.Context) {
+	keyword := c.Query("order_no")
+
+	// TODO(骨架): 查 tasks，task_type = 'purchase'
+	var rows []gin.H
+
+	c.HTML(http.StatusOK, "task/list", page("tasks", "采购任务", gin.H{
+		"Keyword": keyword,
+		"Rows":    rows,
+		"Status":  "尚未实现：创建任务后这里显示执行进度",
+	}))
+}
+
+// TaskDelete 批量删除任务。
+func (h *Handler) TaskDelete(c *gin.Context) {
+	// TODO(骨架)
+	fail(c, http.StatusNotImplemented, "删除功能尚未实现。")
+}
+
+// ---------- 4. 客户端列表 ----------
+
+// ClientList 渲染客户端列表页。
+//
+// 「状态」是**算出来的**：last_seen_at 在 N 分钟内为在线，否则离线。
+// 数据库里没有 status 字段，存成字段会和真实情况不同步。
+//
+// 客户端执行长任务期间不调 claim，可能显示为离线，属正常现象
+// （没有心跳是有意的，见 docs/admin/04-client-api.md §3）。
+func (h *Handler) ClientList(c *gin.Context) {
+	keyword := c.Query("name")
+
+	// TODO(骨架): 查 clients，并按 last_seen_at 算在线状态
+	var rows []gin.H
+
+	c.HTML(http.StatusOK, "client/list", page("clients", "客户端列表", gin.H{
+		"Keyword": keyword,
+		"Rows":    rows,
+		"Status":  "尚未实现：客户端第一次调领取接口后会自动出现在这里",
+	}))
+}
+
+// ClientDelete 批量删除客户端。
+func (h *Handler) ClientDelete(c *gin.Context) {
+	// TODO(骨架)
+	fail(c, http.StatusNotImplemented, "删除功能尚未实现。")
+}

admin/handler/web/shopee.go

@@ -0,0 +1,85 @@
+package web
+
+import (
+	"net/http"
+
+	"github.com/gin-gonic/gin"
+)
+
+// ShopeeList 渲染蝦皮数据列表页。
+//
+// 表格按 SKU 展开显示，数据来自 shopee_products 和 shopee_skus 联查。
+// 列定义见 docs/admin/05-ui-specification.md §4.2。
+func (h *Handler) ShopeeList(c *gin.Context) {
+	keyword := c.Query("goods_id")
+
+	// TODO(骨架): 调 service 查列表
+	//   rows, err := service.ListShopeeSKUs(h.db, keyword, page, size)
+	// 注意：搜索要走数据库查询，不要一次查全量再在内存里过滤。
+	var rows []gin.H
+
+	c.HTML(http.StatusOK, "shopee/list", page("shopee", "蝦皮数据", gin.H{
+		"Keyword": keyword,
+		"Rows":    rows,
+		"Status":  "尚未实现：导入后这里显示商品和规格",
+	}))
+}
+
+// ShopeeImport 处理 Excel 上传导入。
+//
+// 关键规则（写错会丢数据，见 docs/admin/03-data-model.md §3.3）：
+//   - 商品汇总行（商品規格ID 为 "-"）进 shopee_products，
+//     SKU 行进 shopee_skus，两者要分开处理；
+//   - 按列名找索引，不要写死列号；
+//   - 规格原文两种格式各占一半，解析失败留空并把 parse_ok 置 0，不要猜；
+//   - **只能 upsert，绝不允许先清空再导入**，
+//     否则人工填的 PDD 链接会被洗掉；
+//   - upsert 的 DO UPDATE SET 里不得出现 pdd_goods_url / pdd_data / collect_status。
+func (h *Handler) ShopeeImport(c *gin.Context) {
+	file, err := c.FormFile("file")
+	if err != nil {
+		fail(c, http.StatusBadRequest, "没有收到文件，请重新选择 Excel 后再提交。")
+		return
+	}
+
+	// TODO(骨架): 校验大小和扩展名（只允许 .xlsx），
+	//   落盘到 data/uploads/ 时用自己生成的文件名，
+	//   不要直接用 file.Filename 拼路径（路径穿越）。
+	_ = file
+
+	// TODO(骨架): 调 service.ImportShopeeExcel(path)，
+	//   返回 {商品数, SKU数, 解析失败行号列表} 并显示出来。
+	//   失败行不要静默跳过。
+
+	fail(c, http.StatusNotImplemented,
+		"导入功能尚未实现。已保留你选择的文件，未写入数据库。")
+}
+
+// ShopeeSave 保存编辑弹窗里的内容（PDD 链接、颜色、尺码、建议）。
+//
+// 这是 PDD 链接唯一的录入口，见 docs/admin/05-ui-specification.md §4.3。
+func (h *Handler) ShopeeSave(c *gin.Context) {
+	// TODO(骨架): 保存并根据 PDD 链接是否为空更新 collect_status
+	//   （空 -> no_link，非空且未采集 -> pending）
+	fail(c, http.StatusNotImplemented, "保存功能尚未实现。")
+}
+
+// ShopeeDelete 批量删除勾选的行。
+func (h *Handler) ShopeeDelete(c *gin.Context) {
+	// TODO(骨架): 取 ids，二次确认已在前端做过，这里直接删
+	fail(c, http.StatusNotImplemented, "删除功能尚未实现。")
+}
+
+// ShopeeCollect 发起采集任务。
+//
+// 入口在编辑弹窗里，紧挨 PDD 链接输入框——不要放到表格每一行，
+// 一个商品有 N 个 SKU 行，放行上就是 N 个按钮干同一件事。
+//
+// 规则：
+//   - PDD 链接为空不允许发起；
+//   - collect_status 已经是 collecting 的跳过并说明跳过了几个；
+//   - 批量采集要**按商品去重**后再建任务。
+func (h *Handler) ShopeeCollect(c *gin.Context) {
+	// TODO(骨架): 调 service.CreateCollectTasks(goodsIDs, clientID)
+	fail(c, http.StatusNotImplemented, "采集功能尚未实现。")
+}

admin/handler/web/web.go

@@ -0,0 +1,80 @@
+// Package web 是给浏览器用的页面处理器。
+//
+// 和 handler/api 分开是有意的：页面出错要渲染错误页、要 CSRF 防护，
+// 接口出错要返回 JSON、要认证。混在一起迟早写错。
+//
+// 改动本文件前必读 admin/AGENTS.md。两条最容易踩：
+//   - 本层**不写业务逻辑、不拼 SQL**，只做取参数 → 调 service → 渲染；
+//   - 删除、导入这类破坏性操作用 POST，**不得用 GET**，
+//     浏览器和插件会预取 GET 链接。
+package web
+
+import (
+	"database/sql"
+	"net/http"
+
+	"github.com/gin-gonic/gin"
+)
+
+// Handler 持有各页面共用的依赖。
+type Handler struct {
+	db *sql.DB
+}
+
+// Register 把四个模块的页面路由挂上去。
+//
+// 四个模块的页面结构完全一致（顶部工具条 / 中间带勾选的表格 / 底部状态条），
+// 这是有意的，见 docs/admin/05-ui-specification.md §2。
+func Register(r *gin.Engine, db *sql.DB) {
+	h := &Handler{db: db}
+
+	// 打开根路径直接进第一个模块
+	r.GET("/", func(c *gin.Context) {
+		c.Redirect(http.StatusFound, "/shopee")
+	})
+
+	// 1. 蝦皮数据
+	r.GET("/shopee", h.ShopeeList)
+	r.POST("/shopee/import", h.ShopeeImport)
+	r.POST("/shopee/save", h.ShopeeSave)
+	r.POST("/shopee/delete", h.ShopeeDelete)
+	r.POST("/shopee/collect", h.ShopeeCollect)
+
+	// 2. 顺运宝数据
+	r.GET("/syb", h.SybList)
+	r.POST("/syb/sync", h.SybSync)
+	r.POST("/syb/match", h.SybMatch)
+	r.POST("/syb/create-task", h.SybCreateTask)
+	r.POST("/syb/delete", h.SybDelete)
+
+	// 3. 采购任务
+	r.GET("/tasks", h.TaskList)
+	r.POST("/tasks/delete", h.TaskDelete)
+
+	// 4. 客户端列表
+	r.GET("/clients", h.ClientList)
+	r.POST("/clients/delete", h.ClientDelete)
+}
+
+// page 组装每个页面都要的公共数据（导航高亮、标题）。
+func page(active, title string, extra gin.H) gin.H {
+	data := gin.H{
+		"Active": active,
+		"Title":  title,
+	}
+	for k, v := range extra {
+		data[k] = v
+	}
+	return data
+}
+
+// fail 渲染一个错误页。
+//
+// 错误信息要说清三件事：发生了什么、保住了什么、下一步做什么。
+// Go 的错误堆栈只写日志，不要贴到页面上，见 docs/admin/06-quality-security.md §5。
+func fail(c *gin.Context, status int, message string) {
+	c.HTML(status, "partials/error", gin.H{
+		"Title":   "出错了",
+		"Message": message,
+	})
+}