chengma/cmautobuy
2
0
Fork 0
Code Issues 89 Pull Requests Actions Packages Projects Releases Wiki Activity

feat: 实现客户端注册与任务领取接口

Browse Source 
Admin 的第一个业务功能。选它打头是因为它是穿透所有层的最薄一条竖切
（HTTP → handler/api → service → repository → SQLite → handler/web → 页面），
一个工单把分层模式立起来，后面四个模块照抄；同时它是与 Client 联调的接口，
能解锁另一条并行的工作线。

实现
- POST /tasks/claim：注册 + 领取。注册就在这里做，没有单独的注册接口，
  也没有心跳（理由见 docs/admin/04-client-api.md §3）
- 领取用条件更新 + 检查影响行数防并发，SQLite 没有 SELECT FOR UPDATE
- 客户端列表页：查询、按名称搜索、批量删除
- 在线状态是**算出来的**（last_seen_at 在 10 分钟内），数据库里没有该字段
- CSRF 中间件：双提交 Cookie，手写 82 行不引依赖。
  **只挂页面路由**，/api/v1/client/* 不能加——Client 不是浏览器、没有 Cookie
- 14 个单元测试

修复一个真 bug：PRAGMA 必须写进 DSN
并发领取测试报 database is locked (SQLITE_BUSY)。根因是
PRAGMA busy_timeout 每连接生效，而 database/sql 是连接池——
db.Exec("PRAGMA ...") 只作用于当时那条连接，池子新开的连接没执行过。
单线程正常、一并发就炸。改成 DSN 传参后并发测试跑 20 次全过。
这个坑已写进 docs/admin/03-data-model.md §2.1。

与工单的两处差异
- 去掉 name_is_custom 列后，"人工改的名字不被覆盖"改用更简单的做法：
  ON CONFLICT DO UPDATE SET 里不含 name，即只在首次注册时写入。
  效果相同，零额外字段、零迁移。已同步 04 §3
- 验收项"不向 dry_run 客户端分配真实下单任务"**未实现**：
  tasks 表没有字段标记任务是否需要真实下单。当前真实下单开关默认关闭、
  MVP 全是演练模式，暂不出问题，但开真实下单前必须补该字段，需另开工单

已验证（Go 1.23.0）
- go vet / gofmt / go test 全过，并发测试重复 20 次稳定通过
- 端到端：无任务 claim 204；插入任务后 claim 200 且 payload 含
  goods_url/goods_id/options/quantity/max_price_cent、无租约无 Admin 状态；
  重复 claim 204；缺 X-Client-Id 400；POST 无 CSRF token 403；
  列表页两台客户端在线状态与统计正确

说明：Gitea 尚未配置，本次无对应工单号。
submit_result / submit_failure 及其幂等处理留给下一个工单。

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
chengma
2026-08-06 16:56:18 +08:00
co-authored by Claude Opus 5
parent 0279ffd60e
commit 6ae768463f
19 changed files with 1069 additions and 79 deletions
Download Patch File Download Diff File Expand all files Collapse all files
admin/service/client_test.go
+358
View File
@@ -0,0 +1,358 @@
package service
import (
"database/sql"
"path/filepath"
"sync"
"testing"
"time"
"cmautobuy/admin/model"
"cmautobuy/admin/repository"
)
// newTestDB 建一个临时库，测试结束自动删。
// 用真实的 migrations，这样表结构变了测试会跟着失败。
func newTestDB(t *testing.T) *sql.DB {
t.Helper()
db, err := repository.Open(t.TempDir())
if err != nil {
t.Fatalf("打开测试库失败: %v", err)
}
if err := repository.Migrate(db); err != nil {
t.Fatalf("迁移失败: %v", err)
}
t.Cleanup(func() { db.Close() })
return db
}
// insertTask 插一条待领取的任务，供领取相关的测试使用。
func insertTask(t *testing.T, db *sql.DB, taskID, client string) {
t.Helper()
now := model.NowISO()
_, err := db.Exec(`
INSERT INTO tasks (task_id, task_type, status, assigned_client,
order_no, pdd_goods_url, pdd_goods_id, pdd_options,
quantity, max_price_cent, created_at, updated_at)
VALUES (?, 'purchase', 'assigned', ?, 'TEST-ORDER',
'https://mobile.yangkeduo.com/goods.html?goods_id=1', '1',
'{"color":"黑色","size":"M码"}', 2, 4200, ?, ?)`,
taskID, client, now, now)
if err != nil {
t.Fatalf("插入测试任务失败: %v", err)
}
}
// ── 注册 ───────────────────────────────────────────────
func TestRegisterClient_新客户端被登记(t *testing.T) {
db := newTestDB(t)
err := RegisterClient(db, model.Client{
ClientID: "client-001", Name: "办公室-01",
DeviceAddress: "192.168.0.173:5555", Platform: "android",
})
if err != nil {
t.Fatalf("注册失败: %v", err)
}
views, err := ListClientViews(db, "", time.Minute)
if err != nil {
t.Fatalf("查询失败: %v", err)
}
if len(views) != 1 {
t.Fatalf("期望 1 台客户端，实际 %d", len(views))
}
if views[0].Name != "办公室-01" {
t.Errorf("名称错误：期望 办公室-01，实际 %s", views[0].Name)
}
if views[0].DeviceAddress != "192.168.0.173:5555" {
t.Errorf("设备地址错误：%s", views[0].DeviceAddress)
}
}
func TestRegisterClient_没上报名称时用编号兜底(t *testing.T) {
db := newTestDB(t)
if err := RegisterClient(db, model.Client{ClientID: "client-002"}); err != nil {
t.Fatalf("注册失败: %v", err)
}
views, _ := ListClientViews(db, "", time.Minute)
if views[0].Name != "client-002" {
t.Errorf("期望用 client-002 兜底，实际 %q", views[0].Name)
}
}
// 这条是本工单的重点：操作员改过名字后，客户端再来注册不能覆盖它。
func TestRegisterClient_人工改过的名称不被覆盖(t *testing.T) {
db := newTestDB(t)
// 客户端第一次注册，上报名字是 "默认名"
if err := RegisterClient(db, model.Client{
ClientID: "client-003", Name: "默认名", Platform: "android",
}); err != nil {
t.Fatalf("首次注册失败: %v", err)
}
// 操作员在界面上改成好记的名字
if _, err := db.Exec(
`UPDATE clients SET name = ? WHERE client_id = ?`,
"仓库那台", "client-003"); err != nil {
t.Fatalf("人工改名失败: %v", err)
}
// 客户端再次 claim，又上报了 "默认名"
if err := RegisterClient(db, model.Client{
ClientID: "client-003", Name: "默认名", Platform: "android",
DeviceAddress: "10.0.0.9:5555",
}); err != nil {
t.Fatalf("再次注册失败: %v", err)
}
views, _ := ListClientViews(db, "", time.Minute)
if views[0].Name != "仓库那台" {
t.Errorf("人工改的名字被覆盖了：期望 仓库那台，实际 %s", views[0].Name)
}
// 但设备信息应该被更新
if views[0].DeviceAddress != "10.0.0.9:5555" {
t.Errorf("设备地址没更新：%s", views[0].DeviceAddress)
}
}
// ── 在线状态 ───────────────────────────────────────────
func TestIsOnline_阈值边界(t *testing.T) {
now := time.Date(2026, 8, 6, 12, 0, 0, 0, time.UTC)
threshold := 10 * time.Minute
cases := []struct {
name string
lastSeen string
want bool
}{
{"刚刚活动", now.Add(-1 * time.Second).Format(model.TimeLayout), true},
{"阈值内", now.Add(-9 * time.Minute).Format(model.TimeLayout), true},
{"刚好到阈值", now.Add(-10 * time.Minute).Format(model.TimeLayout), false},
{"超过阈值", now.Add(-11 * time.Minute).Format(model.TimeLayout), false},
{"时间解析不了一律算离线", "不是时间", false},
{"空值一律算离线", "", false},
}
for _, tc := range cases {
t.Run(tc.name, func(t *testing.T) {
c := model.Client{LastSeenAt: tc.lastSeen}
if got := c.IsOnline(now, threshold); got != tc.want {
t.Errorf("期望 %v，实际 %v", tc.want, got)
}
})
}
}
func TestTouchClient_刷新活动时间(t *testing.T) {
db := newTestDB(t)
// 造一台很久没活动的客户端
if err := RegisterClient(db, model.Client{ClientID: "client-004"}); err != nil {
t.Fatalf("注册失败: %v", err)
}
old := "2020-01-01T00:00:00Z"
if _, err := db.Exec(
`UPDATE clients SET last_seen_at = ? WHERE client_id = ?`,
old, "client-004"); err != nil {
t.Fatalf("改时间失败: %v", err)
}
views, _ := ListClientViews(db, "", 10*time.Minute)
if views[0].Status != "离线" {
t.Fatalf("改时间后应为离线，实际 %s", views[0].Status)
}
if err := TouchClient(db, "client-004"); err != nil {
t.Fatalf("TouchClient 失败: %v", err)
}
views, _ = ListClientViews(db, "", 10*time.Minute)
if views[0].Status != "在线" {
t.Errorf("刷新后应为在线，实际 %s", views[0].Status)
}
}
// ── 搜索与删除 ─────────────────────────────────────────
func TestListClientViews_按名称搜索(t *testing.T) {
db := newTestDB(t)
RegisterClient(db, model.Client{ClientID: "c-1", Name: "办公室-01"})
RegisterClient(db, model.Client{ClientID: "c-2", Name: "仓库-01"})
views, err := ListClientViews(db, "办公室", time.Minute)
if err != nil {
t.Fatalf("搜索失败: %v", err)
}
if len(views) != 1 || views[0].ClientID != "c-1" {
t.Errorf("搜索结果不对：%+v", views)
}
}
func TestDeleteClients_批量删除(t *testing.T) {
db := newTestDB(t)
RegisterClient(db, model.Client{ClientID: "c-1"})
RegisterClient(db, model.Client{ClientID: "c-2"})
RegisterClient(db, model.Client{ClientID: "c-3"})
n, err := DeleteClients(db, []string{"c-1", "c-3"})
if err != nil {
t.Fatalf("删除失败: %v", err)
}
if n != 2 {
t.Errorf("期望删除 2 条，实际 %d", n)
}
views, _ := ListClientViews(db, "", time.Minute)
if len(views) != 1 || views[0].ClientID != "c-2" {
t.Errorf("剩余客户端不对：%+v", views)
}
}
// ── 领取任务 ───────────────────────────────────────────
func TestClaimNextTask_没有任务返回nil(t *testing.T) {
db := newTestDB(t)
RegisterClient(db, model.Client{ClientID: "client-001"})
task, err := ClaimNextTask(db, "client-001", []string{"collect", "purchase"})
if err != nil {
t.Fatalf("领取失败: %v", err)
}
if task != nil {
t.Errorf("没有任务时应返回 nil，实际拿到 %+v", task)
}
}
func TestClaimNextTask_只领分配给自己的(t *testing.T) {
db := newTestDB(t)
insertTask(t, db, "TASK-A", "client-001")
insertTask(t, db, "TASK-B", "client-002")
task, err := ClaimNextTask(db, "client-002", []string{"purchase"})
if err != nil {
t.Fatalf("领取失败: %v", err)
}
if task == nil {
t.Fatal("应该领到 TASK-B，实际没领到")
}
if task.TaskID != "TASK-B" {
t.Errorf("领错了任务：期望 TASK-B，实际 %s", task.TaskID)
}
}
func TestClaimNextTask_同一任务不会被领两次(t *testing.T) {
db := newTestDB(t)
insertTask(t, db, "TASK-A", "client-001")
first, _ := ClaimNextTask(db, "client-001", []string{"purchase"})
if first == nil {
t.Fatal("第一次应该领到任务")
}
second, err := ClaimNextTask(db, "client-001", []string{"purchase"})
if err != nil {
t.Fatalf("第二次领取报错: %v", err)
}
if second != nil {
t.Errorf("同一任务被领了两次：%s", second.TaskID)
}
}
// 并发领取：多个 goroutine 同时抢一条任务，只能有一个拿到。
func TestClaimNextTask_并发只有一个拿到(t *testing.T) {
db := newTestDB(t)
insertTask(t, db, "TASK-ONLY-ONE", "client-001")
const workers = 8
var (
wg sync.WaitGroup
mu sync.Mutex
gotIt int
lastErr error
)
for i := 0; i < workers; i++ {
wg.Add(1)
go func() {
defer wg.Done()
task, err := ClaimNextTask(db, "client-001", []string{"purchase"})
mu.Lock()
defer mu.Unlock()
if err != nil {
lastErr = err
return
}
if task != nil {
gotIt++
}
}()
}
wg.Wait()
if lastErr != nil {
t.Fatalf("并发领取出错: %v", lastErr)
}
if gotIt != 1 {
t.Errorf("同一任务被 %d 个客户端领到，期望正好 1 个", gotIt)
}
}
func TestClaimNextTask_不领不支持的类型(t *testing.T) {
db := newTestDB(t)
insertTask(t, db, "TASK-P", "client-001") // 这是 purchase 类型
task, err := ClaimNextTask(db, "client-001", []string{"collect"})
if err != nil {
t.Fatalf("领取失败: %v", err)
}
if task != nil {
t.Errorf("只支持 collect 的客户端不该拿到 purchase 任务：%s", task.TaskID)
}
}
func TestClaimNextTask_返回的任务带齐必填字段(t *testing.T) {
db := newTestDB(t)
insertTask(t, db, "TASK-A", "client-001")
task, _ := ClaimNextTask(db, "client-001", []string{"purchase"})
if task == nil {
t.Fatal("应该领到任务")
}
// Client 契约要求：goods_url 必有值
if task.PddGoodsURL == "" {
t.Error("pdd_goods_url 为空，Client 无法执行")
}
// 采购任务必须带价格保护
if task.Quantity <= 0 {
t.Errorf("采购任务的数量必须 > 0，实际 %d", task.Quantity)
}
if task.MaxPriceCent <= 0 {
t.Errorf("采购任务的价格上限必须 > 0，实际 %d", task.MaxPriceCent)
}
if task.Status != model.TaskClaimed {
t.Errorf("领取后状态应为 claimed，实际 %s", task.Status)
}
}
// 确认迁移文件路径拼接没问题（顺带覆盖 repository.Open）
func TestOpen_数据库文件落在指定目录(t *testing.T) {
dir := t.TempDir()
db, err := repository.Open(dir)
if err != nil {
t.Fatalf("打开失败: %v", err)
}
defer db.Close()
if _, err := repository.Migrate(db), error(nil); err != nil {
t.Fatal(err)
}
if _, err := filepath.Abs(filepath.Join(dir, "admin.db")); err != nil {
t.Fatal(err)
}
}
admin/service/service.go
+49 -9
View File
@@ -9,6 +9,10 @@ package service
import (
"database/sql"
"errors"
"time"
"cmautobuy/admin/model"
"cmautobuy/admin/repository"
)
// ErrNotImplemented 表示该功能还没实现。
@@ -114,13 +118,11 @@ func CreatePurchaseTasks(db *sql.DB, sybIDs []string, clientID string) (created
// **没有单独的注册接口，也没有心跳**——注册就在 claim 里做，
// 理由见 docs/admin/04-client-api.md §3。
//
// 规则：
// - 新 client_id 就新增，已有就更新 device/capabilities/last_seen_at；
// - name 若已被人工改过，**不要用客户端上报的覆盖**；
// - 客户端没上报 name 时，用 client_id 当显示名。
func RegisterClient(db *sql.DB, clientID, name, address, platform, pddPackage, capabilitiesJSON string) error {
// TODO(骨架): upsert clients
return ErrNotImplemented
// 关于 name：**只在第一次注册时写入，之后不再更新**。
// 这样操作员在界面上改成好记的名字后，客户端每次 claim
// 都不会把它覆盖回去。客户端没上报 name 时用 clientID 当显示名。
func RegisterClient(db *sql.DB, c model.Client) error {
return repository.UpsertClient(db, c)
}
// TouchClient 刷新 last_seen_at。
@@ -129,6 +131,44 @@ func RegisterClient(db *sql.DB, clientID, name, address, platform, pddPackage, c
// 只在 claim 里调的话，客户端执行长任务期间不调 claim，
// 会被误判成离线。
func TouchClient(db *sql.DB, clientID string) error {
// TODO(骨架)
return ErrNotImplemented
return repository.TouchClient(db, clientID)
}
// ClientView 是客户端列表页要显示的一行。
// Status 是**算出来的**，数据库里没有这个字段。
type ClientView struct {
model.Client
Status string
}
// ListClientViews 查客户端列表，并把在线状态算出来。
func ListClientViews(db *sql.DB, keyword string, threshold time.Duration) ([]ClientView, error) {
clients, err := repository.ListClients(db, keyword)
if err != nil {
return nil, err
}
now := time.Now().UTC()
views := make([]ClientView, 0, len(clients))
for _, c := range clients {
views = append(views, ClientView{
Client: c,
Status: c.StatusText(now, threshold),
})
}
return views, nil
}
// DeleteClients 批量删除，返回实际删除条数。
func DeleteClients(db *sql.DB, clientIDs []string) (int64, error) {
return repository.DeleteClients(db, clientIDs)
}
// ---------- 领取任务 ----------
// ClaimNextTask 为客户端领取一个任务，没有可领的返回 (nil, nil)。
//
// 调用方拿到 nil 要返回 204 No Content，**不是 200 加空对象**。
func ClaimNextTask(db *sql.DB, clientID string, supportedTypes []string) (*model.Task, error) {
return repository.ClaimNextTask(db, clientID, supportedTypes)
}