junhong_cmp_fiber/openspec/specs/card-replacement/spec.md

card-replacement Specification

Purpose

TBD - created by archiving change add-wallet-transfer-tag-models. Update Purpose after archive.

Requirements

Requirement: 换卡记录实体定义

系统 SHALL 定义换卡记录(CardReplacementRecord)实体，记录老卡到新卡的完整转移过程，包括套餐权益、代理关系、所有者信息等。

核心概念：

• 换卡场景：老卡损坏、丢失或故障，需要更换新卡
• 权益转移：老卡的套餐（含剩余流量）、代理关系、所有者信息等全部转移到新卡
• 套餐继续生效：转移后套餐不作废，剩余流量继续可用

实体字段：

• id：换卡记录 ID（主键，BIGINT）
• replacement_no：换卡单号（VARCHAR(50)，唯一）
• old_card_id：老卡 ID（BIGINT，关联 tb_iot_card.id）
• old_iccid：老卡 ICCID（VARCHAR(50)，冗余存储，防止老卡被删除后无法追踪）
• new_card_id：新卡 ID（BIGINT，关联 tb_iot_card.id）
• new_iccid：新卡 ICCID（VARCHAR(50)，冗余存储）
• old_owner_type：老卡所有者类型（VARCHAR(20)）
• old_owner_id：老卡所有者 ID（BIGINT）
• old_agent_id：老卡代理 ID（BIGINT，可空）
• new_owner_type：新卡所有者类型（VARCHAR(20)）
• new_owner_id：新卡所有者 ID（BIGINT）
• new_agent_id：新卡代理 ID（BIGINT，可空）
• package_snapshot：套餐快照（JSONB，记录转移时的套餐详情）
• replacement_reason：换卡原因（VARCHAR(20)，枚举值："damaged"-损坏 | "lost"-丢失 | "malfunction"-故障 | "upgrade"-升级 | "other"-其他）
• remark：备注（TEXT）
• status：换卡状态（INT，1-待审批 2-已通过 3-已拒绝 4-已完成）
• approved_by：审批人 ID（BIGINT，可空）
• approved_at：审批时间（TIMESTAMP，可空）
• completed_at：完成时间（TIMESTAMP，可空）
• creator：创建人 ID（BIGINT）
• updater：更新人 ID（BIGINT）
• created_at：创建时间（TIMESTAMP，自动填充）
• updated_at：更新时间（TIMESTAMP，自动填充）
• deleted_at：删除时间（TIMESTAMP，可空，软删除）

套餐快照 JSON 格式示例：

{
  "package_id": 3001,
  "package_name": "月套餐 10GB",
  "package_code": "PKG-M-001",
  "data_limit_mb": 10240,
  "data_usage_mb": 5120,
  "real_data_usage_mb": 4000,
  "virtual_data_usage_mb": 1120,
  "data_remaining_mb": 5120,
  "activated_at": "2026-01-01T00:00:00Z",
  "expires_at": "2026-02-01T00:00:00Z",
  "remaining_days": 15,
  "order_id": 10001
}

Scenario: 创建换卡记录

• WHEN 用户（ID 为 2001）的老卡（ICCID 为 "8986001"）损坏，需要换新卡（ICCID 为 "8986002"）
• THEN 系统创建换卡记录，old_card_id 为老卡 ID，new_card_id 为新卡 ID，replacement_reason 为 "damaged"，status 为 1（待审批）

Scenario: 审批通过换卡

• WHEN 运营人员（ID 为 999）审批通过换卡记录（ID 为 5001）
• THEN 系统将换卡记录状态从 1（待审批）变更为 2（已通过），记录 approved_by 为 999，approved_at 为当前时间

Scenario: 完成换卡

• WHEN 换卡记录（ID 为 5001）状态为 2（已通过），系统执行换卡操作
• THEN 系统将：
  1. 记录老卡和新卡的快照信息（所有者、代理、套餐）
  2. 将老卡的套餐权益转移到新卡（套餐使用记录的 iot_card_id 更新为新卡 ID）
  3. 将新卡的 owner_type 和 owner_id 更新为老卡的值
  4. 将新卡的代理关系更新为老卡的值（如有）
  5. 将换卡记录状态变更为 4（已完成），记录 completed_at 为当前时间

Scenario: 拒绝换卡

• WHEN 运营人员（ID 为 999）拒绝换卡记录（ID 为 5001），原因为"新卡不符合要求"
• THEN 系统将换卡记录状态从 1（待审批）变更为 3（已拒绝），记录 approved_by 为 999，approved_at 为当前时间，remark 为拒绝原因

---

Requirement: 套餐权益转移

系统 SHALL 在换卡完成后，将老卡的套餐权益（包括剩余流量、过期时间等）转移到新卡，套餐继续生效。

转移内容：

• 套餐使用记录（tb_package_usage）
• 剩余流量（data_limit_mb - data_usage_mb）
• 套餐过期时间（expires_at）
• 关联的订单信息

转移规则：

• 老卡的套餐使用记录的 iot_card_id 更新为新卡 ID
• 剩余流量完整保留
• 套餐过期时间不变
• 如果老卡有多个套餐（正式套餐 + 加油包），全部转移

Scenario: 套餐转移

• WHEN 老卡有月套餐（剩余 5120 MB 流量，还有 15 天过期）
• THEN 系统将套餐使用记录的 iot_card_id 从老卡 ID 更新为新卡 ID，流量和过期时间保持不变

Scenario: 多套餐转移

• WHEN 老卡有正式套餐和 2 个加油包
• THEN 系统将所有套餐使用记录的 iot_card_id 更新为新卡 ID，所有套餐继续生效

---

Requirement: 代理关系转移

系统 SHALL 在换卡完成后，将老卡的代理关系转移到新卡。

转移内容：

• 新卡的 owner_type 更新为老卡的 owner_type
• 新卡的 owner_id 更新为老卡的 owner_id
• 如果老卡通过代理销售，新卡继承相同的代理关系

Scenario: 代理关系转移

• WHEN 老卡的 owner_type 为 "agent"，owner_id 为 123
• THEN 系统将新卡的 owner_type 更新为 "agent"，owner_id 更新为 123

---

Requirement: 换卡记录查询

系统 SHALL 支持按老卡 ID、新卡 ID、用户 ID、换卡单号等条件查询换卡记录。

查询条件：

• 换卡单号（精确匹配）
• 老卡 ID（精确匹配）
• 新卡 ID（精确匹配）
• 老卡 ICCID（精确匹配或模糊匹配）
• 新卡 ICCID（精确匹配或模糊匹配）
• 换卡状态（单选或多选）
• 换卡原因（单选或多选）
• 创建时间范围
• 完成时间范围

分页：

• 默认每页 20 条，最大每页 100 条
• 返回总记录数和总页数

Scenario: 按老卡 ICCID 查询换卡记录

• WHEN 查询老卡 ICCID 为 "8986001" 的换卡记录
• THEN 系统返回所有 old_iccid 为 "8986001" 的换卡记录列表

Scenario: 按状态查询换卡记录

• WHEN 查询状态为 1（待审批）的换卡记录
• THEN 系统返回所有 status 为 1 的换卡记录列表，按创建时间倒序排列

---

Requirement: 换卡数据校验

系统 SHALL 对换卡数据进行校验，确保数据完整性和一致性。

校验规则：

• old_card_id：必填，≥ 1，必须是有效的 IoT 卡 ID
• new_card_id：必填，≥ 1，必须是有效的 IoT 卡 ID，不能与 old_card_id 相同
• old_iccid：必填，长度 19-20 字符
• new_iccid：必填，长度 19-20 字符，不能与 old_iccid 相同
• replacement_reason：必填，枚举值 "damaged" | "lost" | "malfunction" | "upgrade" | "other"
• status：必填，枚举值 1-4

Scenario: 换卡时老卡和新卡相同

• WHEN 创建换卡记录，old_card_id 和 new_card_id 都为 1001
• THEN 系统拒绝创建，返回错误信息"新卡不能与老卡相同"

Scenario: 换卡时新卡 ICCID 无效

• WHEN 创建换卡记录，new_iccid 长度为 15（小于 19）
• THEN 系统拒绝创建，返回错误信息"ICCID 长度必须为 19-20 字符"

Scenario: 换卡时老卡不存在

• WHEN 创建换卡记录，old_card_id 为 99999（不存在的 IoT 卡）
• THEN 系统拒绝创建，返回错误信息"老卡不存在"