Skip to content

WORKFLOW.md

Latest commit

 

History

History
276 lines (201 loc) · 5.2 KB

WORKFLOW.md

File metadata and controls

276 lines (201 loc) · 5.2 KB
Raw

CAPI 项目工作流

1. 阶段划分

Phase 0: 产品基线

目标：确定项目边界，避免一开始做成 NewAPI 的重型替代品。

产出：

  • 产品定位
  • MVP 功能清单
  • 页面信息架构
  • 数据模型草案
  • API 兼容范围

验收标准：

  • 能明确回答 CAPI 第一版服务谁、解决什么问题、不做什么。
  • 后端、前端、文档、部署的第一版范围都可执行。

Phase 1: MVP 骨架

目标：跑通最短链路：用户创建 API Key，通过 CAPI 调用一个上游模型。

后端能力：

  • 用户注册和登录
  • 用户管理
  • API Key 创建、禁用、删除
  • 渠道配置
  • OpenAI compatible /v1/chat/completions
  • 请求日志
  • 基础额度扣减

前端能力：

  • 登录页
  • 首页概览
  • 用户管理
  • API Key 管理
  • 渠道管理
  • 调用日志
  • 系统设置

文档能力：

  • 快速开始
  • 本地开发
  • 环境变量
  • OpenAI 兼容接口说明
  • 常见错误排查

验收标准：

  • 新用户可以在 5 分钟内创建 Key 并完成一次模型调用。
  • 管理员可以新增一个渠道并看到请求命中情况。
  • 管理员可以查询用户、调整额度、禁用账号、查看用户调用记录。
  • 文档可以支持开发者独立完成本地启动。

Phase 2: 可用性增强

目标：提升普通用户可理解性和稳定性。

功能：

  • 用户筛选、搜索、封禁、备注
  • 渠道健康检查
  • 渠道权重和优先级
  • 失败重试与故障切换
  • 模型价格配置
  • 用户额度明细
  • 管理员操作日志
  • 深色模式

验收标准：

  • 单个渠道故障时，网关可以自动切换到可用渠道。
  • 用户能看懂额度为什么减少。
  • 管理员能定位一次失败请求的原因。

Phase 3: 商业化基础

目标：为公开运营做准备。

功能：

  • 额度流水
  • 管理员批量调整额度
  • 数据导出
  • 公告系统
  • 邀请码准入
  • 用户封禁与风控规则
  • 服务状态页

验收标准：

  • 可以支持小规模真实用户注册、额度发放、调用和售后排障。
  • 管理后台可以完成常见运营动作。

2. 开发流程

需求进入

每个需求先写清楚：

  • 用户是谁
  • 要完成什么动作
  • 成功后看到什么结果
  • 失败时怎么提示
  • 是否影响计费、权限或安全边界

设计先行

涉及前端页面时，先确认：

  • 页面类型：列表、详情、设置、表单、仪表盘
  • 主操作：用户进入页面最可能点击什么
  • 空状态：没有数据时显示什么
  • 错误状态：请求失败或权限不足时显示什么
  • 移动端布局：窄屏是否可用

实现顺序

推荐顺序：

  1. 数据模型
  2. 后端接口
  3. API 测试
  4. 前端页面
  5. 空状态和错误状态
  6. 文档补充
  7. 回归验证

合并标准

一个功能完成前必须满足：

  • 主要路径可运行
  • 错误路径有明确响应
  • 权限判断明确
  • 日志足够排查问题
  • 文档同步更新
  • 没有无关格式化或重构

3. UI 工作流

视觉约束

  • 主色建议使用系统蓝 #007AFF，但只用于强调和主操作。
  • 背景使用白色、浅灰、分组灰，不使用渐变。
  • 图标使用 SVG，保持线性、等宽、轻量。
  • 圆角克制，按钮和输入框保持 iOS 风格。
  • 页面不做大面积装饰，不使用营销式 Hero。

页面结构

后台页面优先采用：

  • 左侧导航
  • 顶部当前页面标题和主操作
  • 中间内容区
  • 分组设置面板或数据表格

用户管理页面第一版包含：

  • 用户列表
  • 用户详情
  • 额度调整
  • API Key 列表
  • 调用日志
  • 登录记录
  • 封禁和解封
  • 管理员备注

用户侧页面优先采用：

  • 首页概览
  • 快速复制 API Key
  • 用量与余额
  • 调用示例
  • 最近请求

组件规范

首批组件：

  • Button
  • IconButton
  • Input
  • Select
  • Toggle
  • SegmentedControl
  • Table
  • EmptyState
  • Toast
  • Modal
  • SettingsGroup
  • UsageMeter
  • APIKeyField

4. 后端工作流

请求链路

标准网关请求流程：

  1. 接收兼容 OpenAI 的请求。
  2. 校验 API Key。
  3. 校验用户状态和额度。
  4. 选择可用渠道。
  5. 转换请求格式。
  6. 请求上游模型。
  7. 转换响应格式。
  8. 记录日志。
  9. 扣减额度。
  10. 返回结果。

网关设计要求

  • 上游适配器独立，不把供应商逻辑散落在路由里。
  • 请求日志不保存敏感 Key。
  • 错误返回要兼容 OpenAI 风格。
  • 流式响应要作为第一版重点考虑。
  • 额度扣减需要可追踪和可回放。

5. 发布工作流

本地开发

  • 本地数据库
  • 本地环境变量
  • 本地管理员账号
  • 至少一个可用上游渠道

测试环境

  • 独立数据库
  • 独立上游 Key
  • 打开详细日志
  • 可重置测试用户和额度

生产环境

  • 关闭调试日志
  • 使用安全环境变量
  • 启用请求限流
  • 启用备份
  • 启用错误监控

6. 推荐第一版里程碑

Milestone 1: 可调用

  • 项目初始化
  • 用户登录
  • 用户管理
  • API Key 管理
  • 单渠道转发
  • 请求日志

Milestone 2: 可管理

  • 管理员后台
  • 多渠道配置
  • 模型价格
  • 用户额度
  • 错误排查

Milestone 3: 可公开

  • 文档站
  • 部署脚本
  • 管理员手动额度调整
  • 公告
  • 基础风控