4.0 KiB
4.0 KiB
Why
feature-001-traffic-model-refactor：当前项目的流量语义分散在卡同步字段、套餐使用字段和 B/C 端展示字段三套口径中，virtual_ratio、package_total_mb、virtual_limit_mb 等命名也持续放大理解成本。现在业务已经明确新的统一口径：虚总量永远不大于真总量、一个载体同一时刻只有一个生效主套餐但可挂多个加油包、对外必须同时提供真值/虚值/展示换算值，因此需要正式发起一次流量模型重构，而不是继续在旧字段上叠补丁。
What Changes
- 新增统一的流量业务语义，明确
package_usage为套餐流量事实源，对外统一为真总量、真已用、虚总量、虚已用和reduction_pct（缩减比例）字段。 - 明确虚流量约束：
virtual_total_mb必须大于 0 且小于等于real_total_mb；废弃现有允许纯虚流量或虚总量大于真总量的旧约定。 BREAKING - 统一虚已用展示公式，停止在不同接口里混用“除以 ratio”和“乘以 ratio”的实现。 BREAKING
- 将停机判断从“按
data_limit_mb/data_usage_mb的旧直觉口径”收束为“按套餐使用记录上的真值/虚阈值语义”统一判断。 BREAKING - 统一主套餐 / 加油包流量展示模型：
current-package仅表示当前生效主套餐，套餐历史与 C 端套餐列表按package_usage_id逐条展示各套餐用量。 - 清理并替换误导性旧字段，包含但不限于
package_total_mb、package_used_mb、package_remain_mb、virtual_limit_mb、virtual_remain_mb、旧式virtual_ratio展示语义，并在本次变更中一并删除确认废弃的数据库旧列。 BREAKING - 为历史套餐使用记录补充必要快照字段，避免继续依赖
tb_package当前值回放历史流量展示。 - 同步更新 OpenAPI / DTO / 文档 / 手工验收口径，确保 Handler → Service → Store → Model 各层使用相同字段定义。
Capabilities
New Capabilities
traffic-model-semantics: 定义统一的套餐流量事实字段、展示字段、比例字段、停机阈值语义及历史快照规则。
Modified Capabilities
iot-package: 修改套餐真流量/虚流量定义、校验规则、virtual_ratio使用语义及展示说明。asset-resolve: 修改资产解析接口中的套餐流量字段与展示计算规则。asset-queries: 修改后台套餐历史与当前主套餐接口的流量字段、当前主套餐语义与错误处理约定。client-asset-info: 修改 C 端资产信息与套餐历史接口的流量响应结构和展示口径。package-usage-priority: 修改按优先级扣减后的耗尽判断与套餐使用字段语义。auto-stop-resume: 修改自动停复机的流量耗尽判定基础口径。
Impact
- 分层影响：
- Handler：
internal/handler/admin/asset.go、internal/handler/app/client_asset.go等返回结构与错误语义需更新。 - Service：
internal/service/asset/service.go、internal/service/package/usage_service.go、internal/service/iot_card/stop_resume_service.go、internal/task/polling_carddata_handler.go等需统一流量计算口径。 - Store / Model：
internal/model/package.go、相关 DTO、tb_package_usage快照字段与查询语义需要调整。
- Handler：
- API / 文档影响：后台
resolve / current-package / packages、C 端asset/info / package-history及相关 OpenAPI 文档都会产生字段级 breaking change。 - 数据影响：需要为
tb_package_usage做历史回填、快照迁移和旧列删除，避免历史展示继续读取 livetb_package值或继续依赖废弃字段。 - 验证计划：本项目执行阶段以 PostgreSQL 手工核验、接口回放、网关同步链路验收为主，不在本提案内引入新的自动化测试要求。
- 性能考虑：保持现有分页与查询边界，不引入新的重型聚合查询；关键接口仍需满足列表默认 20/最大 100、API P95 < 200ms、数据库查询 < 50ms 的现有约束。