1
0

feat: 前端适配后端新接口

适配后端统一模型 ID、协议字段、UUID 自动生成和结构化错误响应:

- 类型定义:Provider 新增 protocol 字段,Model 新增 unifiedId,CreateModelInput 移除 id
- API 客户端:提取结构化错误响应中的错误码
- 供应商管理:添加协议选择下拉框和表格列
- 模型管理:移除 ID 输入,显示统一模型 ID(只读)
- Hooks:错误码映射为友好中文消息
- 测试:所有组件测试通过,mock 数据适配新字段
- 文档:更新 README 说明协议字段和统一模型 ID
This commit is contained in:
2026-04-21 20:49:37 +08:00
parent 24f03595a7
commit feff97acbd
28 changed files with 547 additions and 78 deletions

View File

@@ -23,6 +23,48 @@
- **THEN** `error` 字段 SHALL 包含人类可读的错误描述
- **THEN** `code` 字段 SHALL 包含机器可读的错误代码(可选)
### Requirement: 前端提取并处理错误码
前端 SHALL 提取后端结构化错误响应中的错误码并用于错误处理。
#### Scenario: API 客户端解析结构化错误
- **WHEN** 后端返回错误响应
- **THEN** API 客户端 SHALL 尝试解析 JSON 格式 `{error: string, code?: string}`
- **THEN** 如解析成功且包含 code 字段SHALL 创建包含 code 的 ApiError
- **THEN** 如解析失败或不包含 codeSHALL 创建不包含 code 的 ApiError
#### Scenario: ApiError 包含错误码
- **WHEN** 创建 ApiError 对象
- **THEN** ApiError 类 SHALL 包含可选的 code 字段
- **THEN** code 字段类型 SHALL 为 `string | undefined`
- **THEN** 构造函数 SHALL 接受可选的 code 参数
#### Scenario: Hooks 使用错误码映射友好消息
- **WHEN** useMutation 或其他 Hook 处理错误
- **THEN** SHALL 检查 error.code 是否存在
- **THEN** 如存在SHALL 使用映射表转换为友好中文消息
- **THEN** 如不存在或未定义映射SHALL 使用 error.message
#### Scenario: 错误码映射表定义
- **WHEN** 定义错误码映射表
- **THEN** 映射表 SHALL 包含以下键值对:
- `duplicate_model` → "同一供应商下模型名称已存在"
- `invalid_provider_id` → "供应商 ID 仅允许字母、数字、下划线,长度 1-64"
- `immutable_field` → "供应商 ID 不允许修改"
- `provider_not_found` → "供应商不存在"
- **THEN** 映射表 SHALL 使用 TypeScript Record 类型确保类型安全
#### Scenario: 错误码映射降级处理
- **WHEN** 后端返回新的错误码(映射表未定义)
- **THEN** 前端 SHALL 降级使用 error.message
- **THEN** 前端 SHALL NOT 抛出错误或崩溃
- **THEN** 用户 SHALL 仍能看到原始错误消息
### Requirement: provider_id 校验错误
系统 SHALL 对 provider_id 校验错误返回明确的错误信息。