️ 项目背景与开发规范
项目状态
- 当前阶段：已上线基础功能（服务商管理、模型管理），功能逐步迭代完善中。
- 访问方式：通过线上平台URL访问，支持枪牙社区登录与Guitarp登录。
- 开发规范：采用DDD架构设计，严格区分领域层与应用层数据传输（实体仅限领域层，API层需转换为DTO）。
开发环境初始化
关键操作步骤
- 环境准备：在新章节或分支开发时，需执行circle目录下的scrap脚本命令，完成环境初始化与配置更新。
- 核心目的：确保开发环境配置一致性，同步最新依赖与数据库结构。
服务商与模型关系设计
核心数据模型
- 关系类型：Provider（服务商）与Model（模型）为一对多关系（1 Provider → N Models）。
- 状态联动机制：服务商禁用时，其下所有模型同步禁用，避免额外状态判断逻辑。
接口设计与功能实现
一、 服务商管理核心接口
接口功能 | HTTP方法 | 关键参数 | 业务规则 |
获取服务商详情 | GET | providerId | 返回聚合数据（含已激活模型列表），遵循RESTful风格 |
获取服务商列表 | GET | type（官方/自定义/全部） | 无分页设计（数据量较小），默认返回全部类型 |
创建服务商 | POST | providerInfo | 用户创建默认为非官方类型（official=false） |
更新服务商 | PUT | providerId, updateData | 仅支持自定义服务商编辑，官方服务商需后台创建 |
修改服务商状态 | PATCH | providerId, status | 状态变更同步影响旗下所有模型可用性 |
删除服务商 | DELETE | providerId | 级联删除旗下所有模型 |
二、 接口实现关键细节
- 查询逻辑优化
- 类型筛选采用三元运算符简化代码：officialType = (type == "官方") ? true : false。
- 多条件拼接时，空类型参数默认返回全部数据，避免冗余判断。
- 状态管理最佳实践
- 禁用状态通过单条SQL更新实现，避免多表操作导致的状态不一致（如前端多Tab页数据同步问题）。
- 模型状态展示采用分级策略：列表页显示概览，详情页展示完整状态。
开发注意事项
- 常量使用规范：禁止魔法值（如直接使用true/false），需定义常量（如IS_OFFICIAL = true）提升可维护性。
- 协议兼容性：前端传入的OpenAPI协议参数需与后端格式对齐，差异部分通过适配器处理。
- 数据聚合查询：因未使用连表查询，通过分步查询（先查服务商，再查关联模型）实现数据组装。
功能迭代计划
- 当前进度：基础功能已上线，可通过Guitarp仓库查看最新开发进展。
- 待优化项：服务商列表分页功能、多协议适配增强、前端状态同步机制。
