chengmaandClaude Opus 5
e40ce5a13c
MarkCollecting 原本只在 pending/failed 时成功，而全库只有客户端提交结果 才会把 collecting 改走。客户端离线、崩溃、任务被删都是常态——一旦发生， 这个商品就永久报废，界面上没有任何入口能救，只能改数据库。 改成 collecting 超过 15 分钟视为已超时，允许重新创建采集任务。 判定在读取那一刻现算，仍是同一条原子 UPDATE，不加后台清理协程： 后台扫要处理"扫到一半客户端正好提交了"的竞态，本项目已经在并发上 栽过两次，能不引入并发就不引入。 15 分钟写成有名字的常量并注明理由：采集本身几十秒到两分钟，加上排队 等客户端来领。宁可短也不要长——采集是只读的，多采一次没有副作用， 而卡死的代价是商品永久报废。 已知取舍：超时后老任务还在队列里，客户端上线可能两个都领走、采两次。 可接受（只读，后一次覆盖前一次），已写进代码注释和 03-data-model.md， 免得后来人当成 bug 去"修"成加锁或加租约——租约和心跳是被明确移除的设计。 时间比较用字符串，依赖 NowISO 产出定宽 UTC。已在 NowISO 上加注释： 改成带时区偏移的本地时间会让这个比较静默失效，不报错但判断全错。 界面两处：超时的显示「采集中（超时）」，否则操作员盯着「采集中」 不知道它已经死了；跳过原因按正在采集/已采集/已删除分类计数， 一个都没建成时告诉操作员还要等多久。 Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
283 lines
9.6 KiB
Go
283 lines
9.6 KiB
Go
// Package model 只放数据结构，不导入 Gin，也不导入数据库驱动。
|
||
//
|
||
// 这样领域概念才能被单元测试直接使用，不用起服务器、不用连数据库。
|
||
// 字段含义的权威定义在 docs/admin/03-data-model.md。
|
||
package model
|
||
|
||
import "time"
|
||
|
||
// ---------- 时间 ----------
|
||
|
||
// TimeLayout 是全项目统一的时间格式：带时区的 ISO 8601。
|
||
// 库里存 UTC，页面上再转本地时区显示。
|
||
const TimeLayout = time.RFC3339
|
||
|
||
// NowISO 返回当前 UTC 时间的字符串形式。
|
||
// 所有写库的时间戳都要用它，不要各写各的格式。
|
||
//
|
||
// `[必须]` 有代码依赖它产出**定宽 UTC 格式**（如 "2026-08-07T06:10:19Z"）：
|
||
// repository.MarkCollecting 和 service 里判断"采集是否超时"，
|
||
// 靠的是直接用字符串比较 `updated_at < ?`，不解析成时间再比。
|
||
// 定宽 + 同一时区（UTC）+ 补零，字符串的字典序才等于时间先后顺序。
|
||
// 改成带时区偏移的本地时间（比如 "+08:00"）之后，这个比较会**静默失效**
|
||
// ——不会报错，但超时判断会全错，见 #24。
|
||
func NowISO() string {
|
||
return time.Now().UTC().Format(TimeLayout)
|
||
}
|
||
|
||
// CollectStaleAfter 是采集任务多久没动静就当它死了。
|
||
//
|
||
// 采集本身几十秒到两分钟；加上排队等客户端来领，15 分钟足够宽裕。
|
||
// 宁可短也不要长：采集是**只读**操作，多采一次没有任何副作用，
|
||
// 而卡死的代价是这个商品永久报废、只能改数据库救，见 #24。
|
||
//
|
||
// 定义成有名字的常量，不要把 15 分钟当魔数散落在各处判断里。
|
||
const CollectStaleAfter = 15 * time.Minute
|
||
|
||
// ParseISO 解析库里存的时间字符串。解析不了返回零值和 false。
|
||
func ParseISO(s string) (time.Time, bool) {
|
||
if s == "" {
|
||
return time.Time{}, false
|
||
}
|
||
ts, err := time.Parse(TimeLayout, s)
|
||
if err != nil {
|
||
return time.Time{}, false
|
||
}
|
||
return ts, true
|
||
}
|
||
|
||
// ---------- 蝦皮 ----------
|
||
|
||
// CollectStatus 是一个 **PDD 商品**的采集进度。
|
||
//
|
||
// 注意它挂在 PddProduct 上，不在 ShopeeProduct 上——被采集的是 PDD 商品。
|
||
// 两个蝦皮商品指向同一个 PDD 链接时，状态只有一份，不会各记一份还对不上。
|
||
//
|
||
// 这里**没有"未填链接"**：pdd_products 里有这一行，就说明链接已经填了。
|
||
// "未填链接"是蝦皮侧的状态（ShopeeProduct.PddGoodsID 为空）。
|
||
// 界面上仍然显示 5 种，只是数据来源不同，见 docs/admin/01-requirements.md §6.1。
|
||
type CollectStatus string
|
||
|
||
const (
|
||
CollectPending CollectStatus = "pending" // 已填链接，未发起采集
|
||
CollectCollecting CollectStatus = "collecting" // 采集中，不允许再建任务
|
||
CollectCollected CollectStatus = "collected" // 已采集
|
||
CollectFailed CollectStatus = "failed" // 采集失败，可重新采集
|
||
)
|
||
|
||
// PddProduct 是一个拼多多商品。
|
||
//
|
||
// 它和蝦皮商品是**两个独立的东西**：蝦皮链接相对稳定，
|
||
// 而 PDD 商品下架换代很频繁——A 买不到了就得换 B。
|
||
// 所以两者的对应关系放在 ShopeeProduct.PddGoodsID 上，随时可改。
|
||
type PddProduct struct {
|
||
ID int64
|
||
GoodsID string // 从 URL 解析，UNIQUE，防重靠它
|
||
URL string // 操作员填的链接原文
|
||
Title string // 采集回来，人工核对用
|
||
SkusJSON string // schema_version + dimensions + skus
|
||
|
||
CollectStatus CollectStatus
|
||
CollectMsg string // 失败原因
|
||
ArtifactRef string // 诊断产物位置，例如 client-001:artifacts/PDD-0001/xxx/
|
||
CollectedAt string
|
||
|
||
DeletedAt string // 软删除；非空表示已删除，但记录还在
|
||
CreatedAt string
|
||
UpdatedAt string
|
||
}
|
||
|
||
// IsDeleted 判断这条记录是不是已经被软删除了。
|
||
func (p PddProduct) IsDeleted() bool {
|
||
return p.DeletedAt != ""
|
||
}
|
||
|
||
// ShopeeProduct 是蝦皮商品（商品级）。
|
||
//
|
||
// PddGoodsURL 和 PddGoodsID 是我们自己维护的，蝦皮报表里没有，
|
||
// Excel 导入时**绝不能覆盖**，见 docs/admin/03-data-model.md §3.3。
|
||
//
|
||
// 采集结果和采集状态**不在这里**——它们属于 PDD 商品，见 PddProduct。
|
||
type ShopeeProduct struct {
|
||
GoodsID string
|
||
Title string
|
||
ShopeeStatus string
|
||
MainSKUCode string
|
||
PddGoodsURL string
|
||
PddGoodsID string // 指向 PddProduct.GoodsID，为空表示还没填链接
|
||
CreatedAt string
|
||
UpdatedAt string
|
||
}
|
||
|
||
// ShopeeSKU 是蝦皮的一个规格（SKU 级）。
|
||
//
|
||
// SpecRaw 是报表里的规格原文，例如「黑色,M【建議40-50公斤】」，
|
||
// **永远原样保留**。Color/Size/Advice 是尽力解析的结果，
|
||
// 解析失败时留空并把 ParseOK 置 false，不要瞎猜。
|
||
type ShopeeSKU struct {
|
||
SKUID string
|
||
GoodsID string
|
||
SpecRaw string
|
||
Color string
|
||
Size string
|
||
Advice string // 建议体重，如「40-50公斤」
|
||
ParseOK bool
|
||
SKUCode string
|
||
IsManual bool // 人工新增的，后续导入不得删除
|
||
CreatedAt string
|
||
UpdatedAt string
|
||
}
|
||
|
||
// ---------- 顺运宝 ----------
|
||
|
||
// SybOrder 是一张顺运宝货运单。
|
||
//
|
||
// PriceTwdCent 是**台币分**，跟采购任务的人民币价格上限没有换算关系，
|
||
// 不要互相赋值，见 docs/admin/01-requirements.md §7。
|
||
type SybOrder struct {
|
||
SybID string
|
||
OrderNo string
|
||
Title string
|
||
ShopeeGoodsID string
|
||
ShopeeSKUID string
|
||
Quantity int
|
||
PriceTwdCent int64
|
||
ImageURL string
|
||
SybData string // 完整货运单 JSON，原样保留
|
||
CreatedAt string
|
||
UpdatedAt string
|
||
}
|
||
|
||
// SKUMapping 是「蝦皮的这个规格 = 拼多多的那个规格」。
|
||
//
|
||
// # 为什么主键要带上 PddGoodsID
|
||
//
|
||
// PDD 商品下架换代很频繁。假设蝦皮商品 X 原来对应 PDD 商品 A，
|
||
// 操作员匹配好了"黑色/M → 黑色/M码"；后来 A 下架，换成了 B。
|
||
//
|
||
// 如果映射只按 ShopeeSKUID 存，那条旧映射还在，但它描述的是 **A 的规格**：
|
||
//
|
||
// - 运气好：B 没有"黑色/M码"，建任务时找不到会报错，还算安全；
|
||
// - 运气坏：B 恰好也有"黑色/M码"，但完全是另一件衣服
|
||
// —— **静默买错，而且事后查不出来**。
|
||
//
|
||
// 把 PddGoodsID 放进主键后，查映射永远带上"当前对应的 PDD 商品"这个条件，
|
||
// 换成 B 就自然查不到 A 的映射，界面显示"待匹配"。
|
||
// 不需要在换商品时记得去删旧数据——靠查询条件天然隔离，忘不了。
|
||
//
|
||
// 附带好处：A 的映射还留着。A 补货换回去时，之前的匹配成果直接复用。
|
||
type SKUMapping struct {
|
||
ShopeeSKUID string
|
||
PddGoodsID string // 这条映射属于哪个 PDD 商品
|
||
PddOptionKey string // 规范化后的组合键，见 service.OptionKey
|
||
PddOptions string // 原始 options 对象 JSON，显示用
|
||
GoodsID string // 蝦皮商品 ID，方便按商品批量查
|
||
MappedAt string
|
||
MappedBy string
|
||
}
|
||
|
||
// ---------- 任务 ----------
|
||
|
||
// TaskType 区分采集任务和采购任务。
|
||
type TaskType string
|
||
|
||
const (
|
||
TaskCollect TaskType = "collect"
|
||
TaskPurchase TaskType = "purchase"
|
||
)
|
||
|
||
// TaskStatus 是 **Admin 侧**的任务状态。
|
||
//
|
||
// 注意它和 Client 本地的 8 个状态是两套，不要混。
|
||
// Admin 看不到客户端执行到哪一步（没有心跳，是有意的），
|
||
// claimed 之后就只能等结果。
|
||
type TaskStatus string
|
||
|
||
const (
|
||
TaskPending TaskStatus = "pending" // 待分配
|
||
TaskAssigned TaskStatus = "assigned" // 待领取
|
||
TaskClaimed TaskStatus = "claimed" // 已领取，正在执行
|
||
TaskSucceeded TaskStatus = "succeeded" // 成功
|
||
TaskManualReview TaskStatus = "manual_review" // 需人工
|
||
TaskFailed TaskStatus = "failed" // 失败
|
||
TaskCancelled TaskStatus = "cancelled" // 已取消
|
||
)
|
||
|
||
// Task 是发给 Client 执行的一个任务。
|
||
//
|
||
// PddGoodsURL 必填——Client 那边是 NOT NULL，空了它执行不了。
|
||
// 采购任务的 Quantity 和 MaxPriceCent 也必填，这是价格保护，
|
||
// 见 docs/client/04-admin-api-contract.md §4。
|
||
type Task struct {
|
||
TaskID string
|
||
TaskType TaskType
|
||
Status TaskStatus
|
||
Version int
|
||
Priority int
|
||
|
||
AssignedClient string
|
||
ClaimedAt string
|
||
|
||
SybID string
|
||
OrderNo string
|
||
GoodsID string
|
||
ShopeeSKUID string
|
||
|
||
PddGoodsURL string
|
||
PddGoodsID string
|
||
PddOptions string // JSON，采购任务的目标规格
|
||
Quantity int
|
||
MaxPriceCent int64 // 人民币分
|
||
|
||
ResultData string
|
||
ErrorCode string
|
||
ErrorMessage string
|
||
FinishedAt string
|
||
|
||
CreatedAt string
|
||
UpdatedAt string
|
||
}
|
||
|
||
// ---------- 客户端 ----------
|
||
|
||
// Client 是一台执行任务的客户端。
|
||
//
|
||
// 注意**没有 Status 字段**：在线状态是算出来的（见 IsOnline），
|
||
// 存成字段会和真实情况不同步。
|
||
type Client struct {
|
||
ClientID string
|
||
Name string
|
||
DeviceAddress string
|
||
Platform string
|
||
PddPackage string
|
||
Capabilities string
|
||
LastSeenAt string
|
||
CreatedAt string
|
||
UpdatedAt string
|
||
}
|
||
|
||
// IsOnline 判断客户端此刻算不算在线。
|
||
//
|
||
// 规则很简单：最近活动时间在 threshold 之内就算在线。
|
||
// **没有心跳是有意的**，所以客户端执行长任务期间不调接口，
|
||
// 可能显示成离线——这是已知且接受的取舍，
|
||
// 见 docs/admin/04-client-api.md §3。
|
||
//
|
||
// LastSeenAt 解析不了时一律当离线，不要当在线。
|
||
func (c Client) IsOnline(now time.Time, threshold time.Duration) bool {
|
||
seen, ok := ParseISO(c.LastSeenAt)
|
||
if !ok {
|
||
return false
|
||
}
|
||
return now.Sub(seen) < threshold
|
||
}
|
||
|
||
// StatusText 返回给页面显示的中文状态。
|
||
// 状态不能只靠颜色区分，必须有文字。
|
||
func (c Client) StatusText(now time.Time, threshold time.Duration) string {
|
||
if c.IsOnline(now, threshold) {
|
||
return "在线"
|
||
}
|
||
return "离线"
|
||
}
|