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>
2026-08-06 16:33:45 +08:00
parent 0d38eedee1
commit 799ee33045
23 changed files with 1910 additions and 17 deletions
@@ -0,0 +1,52 @@
+{{define "client/list"}}
+{{template "header" .}}
+
+<div class="toolbar">
+  <form class="inline grow" method="get" action="/clients">
+    <label for="q">名称</label>
+    <input id="q" type="text" name="name" value="{{.Keyword}}" placeholder="客户端名称">
+    <button type="submit">搜索</button>
+  </form>
+
+  <form class="inline" method="post" action="/clients/delete" data-confirm-delete>
+    <button type="submit" class="danger" data-need-checked>删除</button>
+  </form>
+</div>
+
+<div class="table-wrap">
+<table>
+  <thead>
+    <tr>
+      <th class="col-check"><input type="checkbox" data-check-all></th>
+      <th>名称</th>
+      <th>序列号</th>
+      <th>状态</th>
+      <th>最近活动</th>
+      <th>更新时间</th>
+    </tr>
+  </thead>
+  <tbody>
+    {{range .Rows}}
+    {{/* TODO(骨架): 行渲染。
+         「状态」是算出来的：最近活动在 N 分钟内为在线，否则离线。
+         数据库里没有 status 字段，存成字段会和真实情况不同步。
+         名称可以人工改成好记的，改过之后客户端上报的名称不再覆盖它。 */}}
+    {{else}}
+    <tr class="empty">
+      <td colspan="6">
+        还没有客户端。<br>
+        <small>客户端第一次调用领取接口时会自动登记到这里，不需要手工添加。</small>
+      </td>
+    </tr>
+    {{end}}
+  </tbody>
+</table>
+</div>
+
+<p class="hint">
+  客户端执行长任务期间不会调领取接口，可能显示为「离线」，属正常现象——
+  本项目有意不做心跳，见 docs/admin/04-client-api.md §3。
+</p>
+
+{{template "footer" .}}
+{{end}}
@@ -0,0 +1,21 @@
+{{define "partials/error"}}<!DOCTYPE html>
+<html lang="zh-CN">
+<head>
+<meta charset="utf-8">
+<title>{{.Title}} · 采集采购管理端</title>
+<link rel="stylesheet" href="/static/css/app.css">
+</head>
+<body>
+<nav class="nav"><span class="nav-brand">采集采购管理端</span></nav>
+<main class="page">
+  <div class="error-box">
+    <h2>出错了</h2>
+    {{/* 错误信息要说清：发生了什么、保住了什么、下一步做什么。
+         Go 的错误堆栈只写日志，不要贴到这里。 */}}
+    <p>{{.Message}}</p>
+    <p><a href="javascript:history.back()">返回上一页</a></p>
+  </div>
+</main>
+</body>
+</html>
+{{end}}
@@ -0,0 +1,10 @@
+{{define "footer"}}
+</main>
+
+{{/* 底部状态条：三段式布局的第三段，四个页面都有 */}}
+<footer class="statusbar">{{.Status}}</footer>
+
+<script src="/static/js/app.js"></script>
+</body>
+</html>
+{{end}}
@@ -0,0 +1,20 @@
+{{define "header"}}<!DOCTYPE html>
+<html lang="zh-CN">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>{{.Title}} · 采集采购管理端</title>
+<link rel="stylesheet" href="/static/css/app.css">
+</head>
+<body>
+
+<nav class="nav">
+  <span class="nav-brand">采集采购管理端</span>
+  <a href="/shopee"  class="{{if eq .Active "shopee"}}active{{end}}">蝦皮数据</a>
+  <a href="/syb"     class="{{if eq .Active "syb"}}active{{end}}">顺运宝数据</a>
+  <a href="/tasks"   class="{{if eq .Active "tasks"}}active{{end}}">采购任务</a>
+  <a href="/clients" class="{{if eq .Active "clients"}}active{{end}}">客户端列表</a>
+</nav>
+
+<main class="page">
+{{end}}
@@ -0,0 +1,65 @@
+{{define "shopee/list"}}
+{{template "header" .}}
+
+{{/* ── 第一段：顶部工具条 ────────────────────────────── */}}
+<div class="toolbar">
+  <form class="inline" method="post" action="/shopee/import" enctype="multipart/form-data">
+    <input type="file" name="file" accept=".xlsx" required>
+    <button type="submit">导入 Excel</button>
+  </form>
+
+  <form class="inline" method="post" action="/shopee/collect">
+    <button type="submit" data-need-checked>批量采集</button>
+  </form>
+
+  <form class="inline grow" method="get" action="/shopee">
+    <label for="q">商品 ID</label>
+    <input id="q" type="text" name="goods_id" value="{{.Keyword}}" placeholder="商品 ID">
+    <button type="submit">搜索</button>
+  </form>
+
+  <form class="inline" method="post" action="/shopee/delete"
+        data-confirm-delete>
+    <button type="submit" class="danger" data-need-checked>删除</button>
+  </form>
+</div>
+
+{{/* ── 第二段：带勾选的表格 ──────────────────────────── */}}
+<div class="table-wrap">
+<table>
+  <thead>
+    <tr>
+      <th class="col-check"><input type="checkbox" data-check-all></th>
+      <th>商品 ID</th>
+      <th>商品名称</th>
+      <th>颜色</th>
+      <th>尺码</th>
+      <th>建议</th>
+      <th>PDD 链接</th>
+      <th>采集状态</th>
+      <th>更新时间</th>
+    </tr>
+  </thead>
+  <tbody>
+    {{range .Rows}}
+    {{/* TODO(骨架): 行渲染。解析失败的行整行标黄（class="row-warn"），
+         PDD 链接为空的显示"未填写"并标红。双击行打开编辑弹窗。 */}}
+    {{else}}
+    <tr class="empty">
+      <td colspan="9">
+        还没有数据，点左上角「导入 Excel」开始。<br>
+        <small>样本文件不在仓库里，需向项目负责人索取，放到 raw_data/ 下。</small>
+      </td>
+    </tr>
+    {{end}}
+  </tbody>
+</table>
+</div>
+
+{{/* TODO(骨架): 编辑弹窗 templates/shopee/edit_modal.html
+     这是 PDD 链接唯一的录入口，采集按钮也只出现在这里——
+     不要放到表格每一行，一个商品有 N 个 SKU 行，
+     放行上就是 N 个按钮干同一件事，还会建出 N 个重复任务。 */}}
+
+{{template "footer" .}}
+{{end}}
@@ -0,0 +1,67 @@
+{{define "syb/list"}}
+{{template "header" .}}
+
+<div class="toolbar">
+  <form class="inline" method="post" action="/syb/sync">
+    <button type="submit">同步</button>
+  </form>
+
+  <form class="inline" method="post" action="/syb/create-task">
+    <button type="submit" data-need-checked>创建采购任务</button>
+  </form>
+
+  <form class="inline grow" method="get" action="/syb">
+    <label for="q">订单号</label>
+    <input id="q" type="text" name="order_no" value="{{.Keyword}}" placeholder="订单号">
+    <button type="submit">搜索</button>
+  </form>
+
+  <form class="inline" method="post" action="/syb/delete" data-confirm-delete>
+    <button type="submit" class="danger" data-need-checked>删除</button>
+  </form>
+</div>
+
+<div class="table-wrap">
+<table>
+  <thead>
+    <tr>
+      <th class="col-check"><input type="checkbox" data-check-all></th>
+      <th>货运单 ID</th>
+      <th>订单号</th>
+      <th>商品标题</th>
+      <th>蝦皮商品 ID</th>
+      <th>规格 SKU</th>
+      <th>数量</th>
+      <th>价格</th>
+      <th>图片</th>
+      <th>匹配状态</th>
+      <th>更新时间</th>
+    </tr>
+  </thead>
+  <tbody>
+    {{range .Rows}}
+    {{/* TODO(骨架): 行渲染。价格是台币，显示成 NT$xx.xx，
+         要和人民币一眼分得清。图片显示小缩略图，存的是 URL。
+         双击行打开匹配弹窗。 */}}
+    {{else}}
+    <tr class="empty">
+      <td colspan="11">
+        还没有货运单。<br>
+        <small>顺运宝同步方式尚未确定，当前可先手工录入用于联调。</small>
+      </td>
+    </tr>
+    {{end}}
+  </tbody>
+</table>
+</div>
+
+{{/* TODO(骨架): 匹配弹窗 templates/syb/match_modal.html
+     左边蝦皮规格，右边该商品 pdd_data 里的 PDD 规格下拉。
+     三条硬规则：
+       1. 右侧下拉选项来自 pdd_data.dimensions，不要写死"颜色/尺码"两个维度；
+       2. 打开时先查 sku_mappings，有记录就自动带出并提示"已自动带出"；
+       3. 该商品还没采集时，直接提示"请先到蝦皮数据模块采集"并给跳转链接，
+          不要显示一个空下拉让人困惑。 */}}
+
+{{template "footer" .}}
+{{end}}
@@ -0,0 +1,53 @@
+{{define "task/list"}}
+{{template "header" .}}
+
+<div class="toolbar">
+  <form class="inline grow" method="get" action="/tasks">
+    <label for="q">订单号</label>
+    <input id="q" type="text" name="order_no" value="{{.Keyword}}" placeholder="订单号">
+    <button type="submit">搜索</button>
+  </form>
+
+  <form class="inline" method="post" action="/tasks/delete" data-confirm-delete>
+    <button type="submit" class="danger" data-need-checked>删除</button>
+  </form>
+</div>
+
+<div class="table-wrap">
+<table>
+  <thead>
+    <tr>
+      <th class="col-check"><input type="checkbox" data-check-all></th>
+      <th>订单号</th>
+      <th>商品标题</th>
+      <th>颜色</th>
+      <th>尺码</th>
+      <th>数量</th>
+      <th>价格上限</th>
+      <th>蝦皮 ID</th>
+      <th>分配客户端</th>
+      <th>状态</th>
+      <th>更新时间</th>
+    </tr>
+  </thead>
+  <tbody>
+    {{range .Rows}}
+    {{/* TODO(骨架): 行渲染。
+         颜色尺码显示的是 **PDD 侧**的规格（实际要买的），不是蝦皮的。
+         价格上限显示成 ¥42.00，底层存的是整数分。
+         状态不能只靠颜色区分，必须有文字。
+         建议提供「改派」操作——没有心跳，客户端挂了要靠人工改派。 */}}
+    {{else}}
+    <tr class="empty">
+      <td colspan="11">
+        还没有采购任务。<br>
+        <small>到「顺运宝数据」勾选货运单，点「创建采购任务」。</small>
+      </td>
+    </tr>
+    {{end}}
+  </tbody>
+</table>
+</div>
+
+{{template "footer" .}}
+{{end}}