修正数据

openspec/changes/refactor-traffic-model-semantics/proposal.md

@@ -0,0 +1,38 @@
+## 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` 快照字段与查询语义需要调整。
+- **API / 文档影响**：后台 `resolve / current-package / packages`、C 端 `asset/info / package-history` 及相关 OpenAPI 文档都会产生字段级 breaking change。
+- **数据影响**：需要为 `tb_package_usage` 做历史回填、快照迁移和旧列删除，避免历史展示继续读取 live `tb_package` 值或继续依赖废弃字段。
+- **验证计划**：本项目执行阶段以 PostgreSQL 手工核验、接口回放、网关同步链路验收为主，不在本提案内引入新的自动化测试要求。
+- **性能考虑**：保持现有分页与查询边界，不引入新的重型聚合查询；关键接口仍需满足列表默认 20/最大 100、API P95 < 200ms、数据库查询 < 50ms 的现有约束。