开发与定制入口

二次开发时，先确定功能落在哪条链路，再沿现有分层扩展，避免在 Handler 中直接拼接数据库、Redis、上游请求和计费逻辑。

常见改动对应模块

需求	主要位置	还要同步检查
新增后台字段/功能	Vue View/Component、admin API、Handler、Service	DTO、校验、权限、审计、缓存失效
新增公开 API	server routes、Handler、Service	API Key middleware、限流、错误格式、usage
新增上游平台	domain constants、Account、Scheduler、Gateway	OAuth/API Key、模型、SSE、测试、Ops
新增账号类型	Account domain/service/repository	创建编辑 UI、刷新、调度资格、导入导出
新增模型能力	protocol transform/gateway	白名单、mapping、价格、usage、流事件
修改计费	billing/usage/pricing	requested/upstream/billing model、幂等、报表
修改支付	payment/provider、PaymentService、payment routes	验签、状态机、幂等履约、退款、历史订单
新增前端控制页	router、view、API module、store/composable	后端权限、feature flag、i18n、错误态
新增后台任务	service worker/startup wiring	多实例 leader lock、heartbeat、停止和超时

一次完整功能变更

定义领域行为和不变量
  → 数据库 migration/Ent schema
  → Repository
  → Service
  → Handler/DTO/Route
  → 前端 API/类型/页面
  → 缓存与多实例同步
  → Ops/Usage/Error 可观测性
  → 单元、集成和协议测试
  → 文档与部署配置

不是每个功能都需要每一层，但跳过某层要有明确理由。

新增平台时的最低清单

• 账号凭证结构、脱敏和轮换方式。
• Base URL 与 SSRF/allowlist 校验。
• 模型列表、模型映射和默认模型。
• 非流式请求与响应。
• SSE/WebSocket 生命周期、客户端断开。
• usage 和缓存 Token 解析。
• 429/5xx/认证错误分类、临时摘除和 failover。
• Account Test、后台创建编辑和导入导出。
• requested/upstream/billing model 与价格。
• Ops 错误上下文和 Request ID。

“能转发一条文本请求”不等于完成平台接入。

修改调度器时

调度器同时受 Group、平台、账号状态、模型能力、优先级、负载、并发、粘性、限流和运行时熔断影响。修改排序或过滤时需要覆盖：

• 同优先级多个账号。
• 全部忙碌时等待与直接失败。
• 粘性账号失效后的切换。
• 模型不支持的 404 与临时不可用的 503。
• 多实例缓存和 scheduler outbox。
• API Key/OAuth 类型偏好及 fallback。

修改计费时

计费代码必须保持：同一请求可追踪、重试不重复扣费、流式中断有明确策略、价格缺失可见、模型映射可解释。测试至少断言 Token、倍率、用户费用、账号成本和记录唯一性。

本地验证

源码启动和构建命令见源码开发与构建。如何按改动选择 unit、integration、协议、支付和多实例测试，见测试与变更验证。提交前至少执行受影响包测试、前端类型/测试、生产构建，并用真实 HTTP 请求覆盖非流式和流式链路。

文档同步

改动架构、配置、后台操作或故障行为时分别更新：项目指南、部署指南、运维指南。不要只更新 README 的功能列表。