cmautobuy/admin/model/model.go

// Package model 只放数据结构，不导入 Gin，也不导入数据库驱动。
//
// 这样领域概念才能被单元测试直接使用，不用起服务器、不用连数据库。
// 字段含义的权威定义在 docs/admin/03-data-model.md。
package model

import "time"

// ---------- 时间 ----------

// TimeLayout 是全项目统一的时间格式：带时区的 ISO 8601。
// 库里存 UTC，页面上再转本地时区显示。
const TimeLayout = time.RFC3339

// NowISO 返回当前 UTC 时间的字符串形式。
// 所有写库的时间戳都要用它，不要各写各的格式。
func NowISO() string {
	return time.Now().UTC().Format(TimeLayout)
}

// 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 商品数据采到没有。
// 取值见 docs/admin/01-requirements.md §6.1。
type CollectStatus string

const (
	CollectNoLink     CollectStatus = "no_link"    // 未填 PDD 链接
	CollectPending    CollectStatus = "pending"    // 已填链接，未发起采集
	CollectCollecting CollectStatus = "collecting" // 采集中，不允许再建任务
	CollectCollected  CollectStatus = "collected"  // 已采集
	CollectFailed     CollectStatus = "failed"     // 采集失败，可重新采集
)

// ShopeeProduct 是蝦皮商品（商品级）。
//
// PddGoodsURL 和 PddData 是我们自己维护的，蝦皮报表里没有，
// Excel 导入时**绝不能覆盖**，见 docs/admin/03-data-model.md §3.3。
type ShopeeProduct struct {
	GoodsID       string
	Title         string
	ShopeeStatus  string
	MainSKUCode   string
	PddGoodsURL   string
	PddGoodsID    string
	PddData       string // 采集回来的 PDD 商品 JSON
	CollectStatus CollectStatus
	CollectError  string
	CollectedAt   string
	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 是「蝦皮的这个规格 = 拼多多的那个规格」。
//
// 匹配一次以后可以复用：下次遇到同一个蝦皮 SKU 自动带出，
// 操作员只需确认。这是省人工的关键。
type SKUMapping struct {
	ShopeeSKUID string
	GoodsID     string
	PddOptions  string // JSON，如 {"color":"黑色","size":"M码"}
	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 "离线"
}