提案

openspec/changes/add-direct-exchange-flow/specs/asset-lifecycle-status/spec.md

@@ -0,0 +1,68 @@
+## MODIFIED Requirements
+
+### Requirement: 资产生命周期状态字段定义
+
+系统 MUST 在 `IotCard` 与 `Device` 数据模型中新增 `asset_status int NOT NULL DEFAULT 1` 字段，用于表达资产生命周期状态。
+
+状态值域 MUST 固定为：`1-在库`、`2-已销售`、`3-已换货`、`4-已停用`。
+
+#### Scenario: 新建资产默认在库
+- **WHEN** 系统创建新的 IoT 卡或设备记录
+- **THEN** `asset_status` MUST 默认为 `1`（在库）
+
+#### Scenario: 非法状态值被拒绝
+- **WHEN** 写入 `asset_status` 为 `0`、`5` 或其他非约定值
+- **THEN** 系统 MUST 拒绝该写入并提示状态值不合法
+
+---
+
+### Requirement: 资产生命周期状态常量定义
+
+系统 MUST 在 `pkg/constants/` 中定义资产生命周期状态常量，并统一由业务层引用，禁止在业务代码中硬编码状态值。
+
+#### Scenario: 业务代码引用常量
+- **WHEN** Service 层执行资产状态判断或赋值
+- **THEN** 代码 MUST 使用 `pkg/constants/` 中定义的资产状态常量而不是硬编码数字
+
+---
+
+### Requirement: 资产状态与网络状态独立
+
+系统 MUST 保证 `asset_status` 与运营商侧 `network_status` 完全独立，二者不互相推导、不互相覆盖。
+
+状态流转逻辑 MUST 至少包括：
+- 导入/建档后：`asset_status=1`（在库）
+- 首次绑定/交付客户后：`asset_status=2`（已销售）
+- 换货完成时：
+  - 旧资产完成前必须为 `asset_status=2`（已销售）
+  - 新资产完成前必须为 `asset_status=1`（在库）
+  - 旧资产 `asset_status -> 3`（已换货）
+  - 新资产 `asset_status -> 2`（已销售）
+- 转新时：
+  - 旧资产 `generation + 1`
+  - 旧资产 `asset_status -> 1`（在库）
+- 手动停用时：`asset_status -> 4`（已停用）
+
+#### Scenario: 网络状态变化不影响资产状态
+- **WHEN** Gateway 同步将 `network_status` 从开机改为停机
+- **THEN** 系统 MUST 保持 `asset_status` 不变
+
+#### Scenario: 资产状态变化不强制修改网络状态
+- **WHEN** 管理端将资产手动停用（`asset_status=4`）
+- **THEN** 系统 MUST 不自动改写 `network_status`
+
+#### Scenario: 换货完成后旧资产标记为已换货
+- **WHEN** 任一换货流程完成成功
+- **THEN** 系统 MUST 将旧资产 `asset_status` 更新为 `3`
+
+#### Scenario: 换货完成后新资产标记为已销售
+- **WHEN** 任一换货流程完成成功
+- **THEN** 系统 MUST 将新资产 `asset_status` 更新为 `2`
+
+#### Scenario: 旧资产非已销售禁止完成换货
+- **WHEN** 旧资产 `asset_status != 2`
+- **THEN** 系统 MUST 拒绝换货完成
+
+#### Scenario: 新资产非在库禁止完成换货
+- **WHEN** 新资产 `asset_status != 1`
+- **THEN** 系统 MUST 拒绝换货完成