# Number Card Management

## Purpose

Manage number cards (virtual products) for carrier order callbacks, supporting carrier order passthrough, agent promotion, commission processing, and carrier settlement tracking.

This capability supports:
- Number card entity definition as virtual product mapping
- Carrier order callbacks from Gateway project
- Agent promotion via links or offline cards
- Commission processing for number card orders
- Carrier settlement tracking for financial reconciliation
- Integration with existing commission rules (one-time, long-term, combined)

## Requirements
## ADDED Requirements

### Requirement: 号卡实体定义

系统 SHALL 定义号卡(NumberCard)实体,作为运营商订单回传的映射,支持代理分销和分佣。

**实体字段**:
- `id`: 号卡 ID(主键,BIGINT)
- `virtual_product_code`: 虚拟商品编码(VARCHAR(100),唯一,用于对应运营商订单)
- `product_name`: 商品名称(VARCHAR(255))
- `carrier`: 运营商名称(VARCHAR(100),如 "中国移动"、"中国联通"、"中国电信")
- `carrier_product_id`: 运营商商品 ID(VARCHAR(100))
- `package_type`: 套餐类型(VARCHAR(50),如 "月套餐"、"流量包")
- `data_amount_mb`: 流量额度(BIGINT,MB 为单位,可选)
- `voice_minutes`: 语音分钟数(INT,可选)
- `sms_count`: 短信条数(INT,可选)
- `price`: 固定售价(DECIMAL(10,2),由运营商定价)
- `status`: 号卡状态(INT,1-上架 2-下架)
- `created_at`: 创建时间(TIMESTAMP,自动填充)
- `updated_at`: 更新时间(TIMESTAMP,自动填充)

#### Scenario: 创建号卡商品

- **WHEN** 平台创建号卡商品,虚拟商品编码为 "VC-CMCC-001",运营商为"中国移动",固定售价为 30.00 元
- **THEN** 系统创建号卡记录,`virtual_product_code` 为 "VC-CMCC-001",`carrier` 为 "中国移动",`price` 为 30.00,状态为 1(上架)

#### Scenario: 虚拟商品编码唯一性

- **WHEN** 平台创建号卡商品,虚拟商品编码为已存在的 "VC-CMCC-001"
- **THEN** 系统拒绝创建,返回错误信息"虚拟商品编码已存在"

---

### Requirement: 号卡运营商订单回传

系统 SHALL 接收 Gateway 项目转换后的运营商订单回传,通过虚拟商品编码匹配号卡,创建订单和分佣记录。

**订单回传字段**:
- `carrier_order_id`: 运营商订单 ID(VARCHAR(255),唯一)
- `virtual_product_code`: 虚拟商品编码(VARCHAR(100),用于匹配号卡)
- `user_phone`: 用户手机号(VARCHAR(20))
- `amount`: 订单金额(DECIMAL(10,2))
- `order_time`: 订单时间(TIMESTAMP)
- `agent_id`: 代理 ID(BIGINT,可空,如果通过代理推广则有值)
- `carrier_order_data`: 运营商订单原始数据(JSONB)

**回传处理流程**:
1. Gateway 接收运营商订单,统一转换为 JSON 格式
2. Gateway 通过 HTTP POST 回传给 CMP 系统
3. CMP 系统根据 `virtual_product_code` 匹配号卡
4. CMP 系统创建订单记录(`order_type` 为 "number_card")
5. 如果有 `agent_id`,触发代理分佣流程

#### Scenario: 接收运营商订单回传

- **WHEN** Gateway 回传运营商订单,虚拟商品编码为 "VC-CMCC-001",代理 ID 为 123,订单金额为 30.00 元
- **THEN** 系统创建订单记录,`order_type` 为 "number_card",`source_id` 为号卡 ID,`agent_id` 为 123,触发分佣计算

#### Scenario: 虚拟商品编码不存在

- **WHEN** Gateway 回传运营商订单,虚拟商品编码为不存在的 "VC-UNKNOWN"
- **THEN** 系统拒绝创建订单,返回错误信息"虚拟商品编码不存在"并记录到日志

---

### Requirement: 号卡代理分销

系统 SHALL 支持号卡的代理分销,代理通过推广链接或卡板推广号卡给终端用户。

**分销规则**:
- 号卡由运营商定价,平台无权修改价格
- 代理通过推广链接或卡板获取用户激活
- 用户激活充值后,资金直接支付给运营商,不经过平台
- 运营商周期性结算总佣金给平台
- 平台根据代理分佣规则分配佣金给代理

**代理推广方式**:
- **推广链接**: 代理生成带有 `agent_id` 的推广链接,用户点击链接激活
- **卡板**: 代理线下分发印有二维码的卡板,用户扫码激活

#### Scenario: 代理生成推广链接

- **WHEN** 代理商(用户 ID 为 123)为号卡(ID 为 5001)生成推广链接
- **THEN** 系统生成带有 `agent_id=123` 和 `product_id=5001` 的推广链接,如 `https://example.com/activate?agent=123&product=5001`

#### Scenario: 用户通过代理链接激活

- **WHEN** 用户通过代理推广链接激活号卡并充值 30.00 元
- **THEN** 运营商接收用户支付,Gateway 回传订单时包含 `agent_id=123`,系统触发代理分佣流程

---

### Requirement: 号卡分佣处理

系统 SHALL 根据号卡分佣规则计算代理佣金,支持冻结和解冻流程。

**分佣规则**:
- 号卡分佣配置在代理分佣规则表(`commission_rules`)中
- 分佣类型:一次性分佣、长期分佣、组合分佣(参考 iot-agent-commission 规范)
- 号卡订单的分佣需要满足条件:激活(实名) + 达到充值金额 + 在网状态 + 三无校验
- 分佣记录创建时状态为"冻结",满足条件后变为"解冻中",审批通过后变为"已发放"

#### Scenario: 号卡订单触发分佣

- **WHEN** 运营商回传订单,代理 ID 为 123,订单金额为 30.00 元,该代理配置了一次性分佣 5.00 元
- **THEN** 系统创建分佣记录,金额为 5.00 元,状态为"冻结",等待满足解冻条件

#### Scenario: 号卡分佣解冻

- **WHEN** 号卡订单满足解冻条件(激活 + 充值 + 在网 + 三无校验)
- **THEN** 系统将分佣记录状态从"冻结"变更为"解冻中",创建分佣解冻审批记录

---

### Requirement: 号卡运营商结算

系统 SHALL 记录运营商周期性结算的佣金总额,用于财务对账和利润计算。

**结算字段**:
- `settlement_id`: 结算记录 ID(主键,BIGINT)
- `carrier`: 运营商名称(VARCHAR(100))
- `settlement_period`: 结算周期(VARCHAR(50),如 "2025-01")
- `total_commission`: 运营商结算的佣金总额(DECIMAL(18,2))
- `settlement_time`: 结算时间(TIMESTAMP)
- `status`: 结算状态(INT,1-待确认 2-已确认)
- `created_at`: 创建时间(TIMESTAMP,自动填充)
- `updated_at`: 更新时间(TIMESTAMP,自动填充)

#### Scenario: 记录运营商结算

- **WHEN** 运营商"中国移动"结算 2025 年 1 月的佣金总额 50000.00 元
- **THEN** 系统创建结算记录,`carrier` 为 "中国移动",`settlement_period` 为 "2025-01",`total_commission` 为 50000.00,状态为 1(待确认)

#### Scenario: 确认运营商结算

- **WHEN** 财务确认运营商结算记录(ID 为 1001)
- **THEN** 系统将结算记录状态从 1(待确认) 变更为 2(已确认)

---

### Requirement: 号卡数据校验

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

**校验规则**:
- 虚拟商品编码(virtual_product_code):必填,长度 1-100 字符,唯一
- 商品名称(product_name):必填,长度 1-255 字符
- 运营商名称(carrier):必填,长度 1-100 字符
- 固定售价(price):必填,≥ 0,最多 2 位小数
- 状态(status):必填,枚举值 1(上架) | 2(下架)

#### Scenario: 创建号卡时虚拟商品编码为空

- **WHEN** 平台创建号卡,虚拟商品编码为空
- **THEN** 系统拒绝创建,返回错误信息"虚拟商品编码不能为空"

#### Scenario: 创建号卡时固定售价为负数

- **WHEN** 平台创建号卡,固定售价为 -10.00
- **THEN** 系统拒绝创建,返回错误信息"固定售价必须 ≥ 0"