# carrier Specification

## Purpose
管理运营商(Carrier)实体，支持四大固定运营商（中国移动、中国联通、中国电信、广电）的 CRUD 操作。

## Requirements

### Requirement: 运营商实体定义

系统 SHALL 定义运营商(Carrier)实体，管理四大固定运营商（中国移动、中国联通、中国电信、广电）。

**四大运营商固定枚举**：
- **CMCC**：中国移动
- **CUCC**：中国联通
- **CTCC**：中国电信
- **CBN**：广电

**实体字段**：
- `id`：运营商 ID（主键，BIGINT）
- `carrier_code`：运营商编码（VARCHAR(50)，唯一约束）
- `carrier_name`：运营商名称（VARCHAR(100)，如"中国移动"）
- `carrier_type`：运营商类型（VARCHAR(20)，枚举值："CMCC" | "CUCC" | "CTCC" | "CBN"）
- `description`：运营商描述（VARCHAR(500)，可选）
- `status`：状态（INT，1-启用 0-禁用）
- `creator`：创建人 ID（BIGINT）
- `updater`：更新人 ID（BIGINT）
- `created_at`：创建时间（TIMESTAMP，自动填充）
- `updated_at`：更新时间（TIMESTAMP，自动填充）
- `deleted_at`：删除时间（TIMESTAMP，可空，软删除）

**唯一约束**：`carrier_code` 在 `deleted_at IS NULL` 条件下唯一

---

### Requirement: 创建运营商

系统 SHALL 允许管理员创建新的运营商记录。创建时必须指定 carrier_code（唯一编码）、carrier_name（显示名称）、carrier_type（运营商类型，枚举值）。description 为选填字段。创建成功后默认状态为启用（status=1）。

#### Scenario: 成功创建运营商
- **WHEN** 管理员提交有效的创建请求，carrier_code 不重复，carrier_type 为有效枚举值
- **THEN** 系统创建运营商记录，返回完整的运营商信息

#### Scenario: carrier_code 重复
- **WHEN** 管理员提交的 carrier_code 已存在
- **THEN** 系统返回错误"运营商编码已存在"

#### Scenario: carrier_type 无效
- **WHEN** 管理员提交的 carrier_type 不是 CMCC/CUCC/CTCC/CBN 之一
- **THEN** 系统返回参数校验错误

---

### Requirement: 查询运营商列表

系统 SHALL 提供分页查询运营商列表的接口，支持按 carrier_type、status、carrier_name（模糊搜索）筛选。

#### Scenario: 无筛选条件查询
- **WHEN** 管理员请求列表，不带筛选条件
- **THEN** 系统返回所有运营商的分页列表，按 ID 降序排列

#### Scenario: 按运营商类型筛选
- **WHEN** 管理员指定 carrier_type=CMCC
- **THEN** 系统仅返回 carrier_type 为 CMCC 的记录

#### Scenario: 按名称模糊搜索
- **WHEN** 管理员指定 carrier_name=移动
- **THEN** 系统返回 carrier_name 包含"移动"的记录

---

### Requirement: 获取运营商详情

系统 SHALL 允许管理员通过 ID 获取单个运营商的详细信息。

#### Scenario: 成功获取详情
- **WHEN** 管理员请求存在的运营商 ID
- **THEN** 系统返回该运营商的完整信息

#### Scenario: 运营商不存在
- **WHEN** 管理员请求不存在的运营商 ID
- **THEN** 系统返回错误"运营商不存在"

---

### Requirement: 更新运营商

系统 SHALL 允许管理员更新运营商的 carrier_name 和 description 字段。carrier_code 和 carrier_type 创建后不可修改。

#### Scenario: 成功更新运营商
- **WHEN** 管理员提交有效的更新请求
- **THEN** 系统更新运营商信息，返回更新后的完整信息

#### Scenario: 尝试修改 carrier_code
- **WHEN** 管理员尝试修改 carrier_code
- **THEN** 系统忽略该字段（不报错，但不修改）

---

### Requirement: 删除运营商

系统 SHALL 允许管理员软删除运营商记录。

#### Scenario: 成功删除运营商
- **WHEN** 管理员请求删除存在的运营商
- **THEN** 系统软删除该记录（设置 deleted_at）

#### Scenario: 删除不存在的运营商
- **WHEN** 管理员请求删除不存在的运营商 ID
- **THEN** 系统返回错误"运营商不存在"

---

### Requirement: 更新运营商状态

系统 SHALL 允许管理员启用或禁用运营商。状态值：1=启用，0=禁用。

#### Scenario: 启用运营商
- **WHEN** 管理员将状态设置为 1
- **THEN** 系统更新运营商状态为启用

#### Scenario: 禁用运营商
- **WHEN** 管理员将状态设置为 0
- **THEN** 系统更新运营商状态为禁用

#### Scenario: 无效状态值
- **WHEN** 管理员提交的状态值不是 0 或 1
- **THEN** 系统返回参数校验错误

---

### Requirement: 运营商数据校验

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

**校验规则**：
- `carrier_type`：必填，枚举值 "CMCC" | "CUCC" | "CTCC" | "CBN"
- `carrier_name`：必填，长度 1-100 字符
- `carrier_code`：必填，长度 1-50 字符
- `description`：可选，长度 0-500 字符
- `status`：必填，枚举值 0 或 1

#### Scenario: 创建运营商时 carrier_type 无效

- **WHEN** 创建运营商，`carrier_type` 为 "INVALID"
- **THEN** 系统拒绝创建，返回错误信息"运营商类型无效"

#### Scenario: 创建运营商时 carrier_name 为空

- **WHEN** 创建运营商，`carrier_name` 为空
- **THEN** 系统拒绝创建，返回错误信息"运营商名称不能为空"