huang
d104d297ca
All checks were successful
构建并部署到测试环境（无 SSH） / build-and-deploy (push) Successful in 5m16s
主要变更： - 新增 Carrier CRUD API（创建、列表、详情、更新、删除、状态更新） - IotCard/IotCardImportTask 添加 carrier_type/carrier_name 冗余字段 - 移除 Carrier 表的 channel_name/channel_code 字段 - 查询时直接使用冗余字段，避免 JOIN Carrier 表 - 添加数据库迁移脚本（000021-000023） - 添加单元测试和集成测试 - 同步更新 OpenAPI 文档和 specs
152 lines
5.2 KiB
Markdown
152 lines
5.2 KiB
Markdown
# 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** 系统拒绝创建，返回错误信息"运营商名称不能为空"
|
||
|