billing-service/docs/reference/model.md

model 包参考

本文档覆盖 internal/model/types.go。该包只定义结构体，不包含行为函数，是 exporter、repository、service、httpapi 共享的数据契约层。

1. 上游快照模型

Sample

签名：type Sample struct

字段	类型	JSON 字段	含义
UUID	string	uuid	账户 UUID，服务层会校验其为合法 UUID
Email	string	email	上游样本附带的邮箱，当前服务层不使用此字段做计费决策
InboundTag	string	inbound_tag	线路标签，写入分钟桶的 line_code
UplinkBytesTotal	int64	uplink_bytes_total	截止采样时累计上行字节
DownlinkBytesTotal	int64	downlink_bytes_total	截止采样时累计下行字节

Snapshot

签名：type Snapshot struct

字段	类型	JSON 字段	含义
CollectedAt	time.Time	collected_at	快照采集时间，服务层会按分钟截断
NodeID	string	node_id	上游节点标识
Env	string	env	环境标识，例如 prod
Samples	[]Sample	samples	本次快照中的样本列表

SnapshotWindowPage

签名：type SnapshotWindowPage struct

字段	类型	JSON 字段	含义
NodeID	string	node_id	分页级别的节点标识
Env	string	env	分页级别的环境标识
Snapshots	[]Snapshot	snapshots	窗口拉取结果中的快照列表
HasMore	bool	has_more	是否还有下一页
NextCursor	string	next_cursor	下一页游标，当前实现要求其为 RFC3339 时间字符串

2. 持久化实体模型

Checkpoint

签名：type Checkpoint struct

字段	类型	含义
NodeID	string	存储层节点 ID，实际由 env:node_id 组合而成
AccountUUID	string	账户 UUID
LastUplinkTotal	int64	上次记录的累计上行字节
LastDownlinkTotal	int64	上次记录的累计下行字节
LastSeenAt	time.Time	上次成功处理该样本的采样时间
XrayRevision	string	当前写路径版本标识
ResetEpoch	int64	检测到累计值回退后的重置计数

MinuteBucket

签名：type MinuteBucket struct

字段	类型	含义
BucketStart	time.Time	分钟桶起始时间，按 UTC 分钟对齐
NodeID	string	存储层节点 ID
AccountUUID	string	账户 UUID
Region	string	地域代码，当前来自 cfg.DefaultRegion
LineCode	string	线路代码，当前来自 sample.InboundTag
UplinkBytes	int64	当前分钟增量上行字节
DownlinkBytes	int64	当前分钟增量下行字节
TotalBytes	int64	当前分钟总字节数
Multiplier	float64	最终乘数，当前为地域乘数 * 线路乘数
RatingStatus	string	当前实现固定写 rated
SourceRevision	string	写路径版本或计费规则版本

LedgerEntry

签名：type LedgerEntry struct

字段	类型	含义
ID	string	账本主键，基于分钟桶确定性生成
AccountUUID	string	账户 UUID
BucketStart	time.Time	对应分钟桶起始时间
BucketEnd	time.Time	对应分钟桶结束时间，当前实现为 BucketStart + 1 分钟
EntryType	string	当前实现固定为 traffic_charge
RatedBytes	int64	真正参与计费的字节数，已扣除包含流量
AmountDelta	float64	本次金额变化，当前为负值表示扣费
BalanceAfter	float64	扣费后的余额
PricingRuleVersion	string	实际应用的定价规则版本

QuotaState

签名：type QuotaState struct

字段	类型	含义
AccountUUID	string	账户 UUID
RemainingIncludedQuota	int64	剩余包含流量字节数
CurrentBalance	float64	当前余额
Arrears	bool	是否欠费
ThrottleState	string	节流状态，当前实现用 normal / throttled
SuspendState	string	挂起状态，当前新建状态默认 active
LastRatedBucketAt	*time.Time	最近一次成功计费的分钟桶时间
EffectiveAt	time.Time	当前状态生效时间

BillingProfile

签名：type BillingProfile struct

字段	类型	含义
AccountUUID	string	账户 UUID
PackageName	string	套餐名
IncludedQuotaBytes	int64	套餐包含流量
BasePricePerByte	float64	基础单价
RegionMultiplier	float64	地域乘数
LineMultiplier	float64	线路乘数
PeakMultiplier	float64	峰时乘数，当前代码未参与计算
OffPeakMultiplier	float64	非峰时乘数，当前代码未参与计算
PricingRuleVersion	string	计费规则版本号

SourceSyncState

签名：type SourceSyncState struct

字段	类型	含义
SourceID	string	来源 ID
LastCompletedUntil	*time.Time	最近一次成功推进到的窗口终点
LastAttemptedAt	*time.Time	最近一次开始尝试采集的时间
LastSucceededAt	*time.Time	最近一次成功完成采集的时间
LastError	string	最近一次失败信息

3. HTTP 与运行状态模型

SourceStatus

签名：type SourceStatus struct

字段	类型	JSON 字段	含义
SourceID	string	source_id	来源 ID
LastCompletedUntil	*time.Time	last_completed_until	对外暴露的窗口完成位置
LastAttemptedAt	*time.Time	last_attempted_at	对外暴露的最近尝试时间
LastSucceededAt	*time.Time	last_succeeded_at	对外暴露的最近成功时间
LastError	string	last_error	最近错误

JobResult

签名：type JobResult struct

字段	类型	JSON 字段	含义
Job	string	job	作业名，当前为 collect-and-rate 或 reconcile
StartedAt	time.Time	started_at	作业开始时间
FinishedAt	time.Time	finished_at	作业结束时间
ProcessedSamples	int	processed_samples	成功进入处理主路径的样本数
WrittenMinutes	int	written_minutes	新写入的分钟桶数
ReplayedMinutes	int	replayed_minutes	由于回放或重复写命中的分钟数
Status	string	status	ok / partial / error
Error	string	error	汇总错误信息
SourceStatuses	[]SourceStatus	source_statuses	各来源状态摘要

PingInfo

签名：type PingInfo struct

字段	类型	JSON 字段	含义
Image	string	image	原始镜像引用
Tag	string	tag	解析出的镜像 tag
Commit	string	commit	解析出的完整 commit
Version	string	version	当前实现等于 commit

4. 使用约束

• 所有 time.Time 在服务层和仓储层都按 UTC 处理
• Snapshot / Sample 是上游输入契约，不应被仓储层直接修改
• MinuteBucket、LedgerEntry、QuotaState 共同构成计费事实链
• JobResult 和 SourceStatus 只代表最近一次执行的内存快照，不是持久化审计日志