okooooooo/team-api
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
104f1de0b354834340d373dfd72cda2caee04446
team-api/CLAUDE.md
T

27 KiB
Raw Blame History

Team-API — 项目开发规范

项目概述

多租户 大模型 API 网关 SaaS 平台。租户注册后获取 API Key，通过统一接口调用 OpenAI/Claude/Gemini 等大模型，平台负责计费、限流、监控。

双控制台架构：管理后台（平台运营）+ 租户控制台（组织使用），两套完全独立的用户体系。

技术栈

  • 后端：Go + GoFrame (v2) + goose（数据库迁移）
  • 数据库：PostgreSQL（唯一，不用 MySQL/SQLite）
  • 缓存：Redis + 内存缓存（双层缓存）
  • 前端：Vue 3 + Vite + TailwindCSS + Naive UI（管理后台）
  • 包管理：bun
  • 对象存储：S3 / OSS / COS / MinIO（禁止纯本地磁盘作为生产存储）

项目结构

项目基于 GoFrame v2 标准项目结构（gf init 生成），在此基础上扩展业务模块。

team-api/
├── api/                        # API 定义（请求/响应结构体 + 路由注解）
│   ├── admin/v1/               #   管理后台 API（gf gen ctrl 源）
│   ├── tenant/v1/              #   租户控制台 API（gf gen ctrl 源）
│   ├── captcha/v1/             #   验证码 API（管理后台 + 租户控制台共用）
│   ├── docs/v1/                #   OpenAPI 文档 API
│   ├── open/v1/                #   开放平台 API
│   ├── payment/v1/             #   支付回调 API
├── hack/
│   └── config.yaml             # gf CLI 脚手架配置（gen dao 等工具的数据库连接和生成规则）
├── internal/
│   ├── cmd/                    # 入口命令、服务启动、路由注册
│   │   ├── cmd.go              #   main 包注册，路由分组定义
│   │   └── cmd_reset_pwd.go    #   密码重置命令
│   ├── consts/                 # 常量定义（业务状态码、枚举等）
│   ├── controller/             # 控制器（由 gf gen ctrl 从 api/ 自动生成，禁止手动修改）
│   │   ├── admin/              #   管理后台控制器
│   │   ├── tenant/             #   租户控制台控制器
│   │   ├── captcha/            #   验证码控制器
│   │   ├── docs/               #   文档控制器
│   │   ├── open/               #   开放平台控制器
│   ├── handler/                # 特殊端点处理器（不走 Controller 链路，见下方说明）
│   │   ├── relay/              #   AI 代理端点处理器
│   │   ├── public/             #   支付回调端点处理器
│   │   └── setup/              #   系统初始化向导处理器
│   ├── logic/                  # 业务逻辑实现（核心代码所在）
│   │   ├── admin/              #   管理后台业务逻辑
│   │   ├── tenant/             #   租户控制台业务逻辑
│   │   ├── billing/            #   计费引擎
│   │   ├── common/             #   公共逻辑（缓存、配置、安全、邮件、验证码、JWT 等）
│   │   ├── docs/               #   OpenAPI 文档生成
│   │   ├── monitor/            #   监控告警引擎
│   │   ├── notification/       #   通知服务
│   │   ├── open/               #   开放平台业务逻辑
│   │   ├── payment/            #   支付逻辑（回调处理、订单履约）
│   │   ├── relay/              #   Relay 业务逻辑（亲和性、健康检查、缓存）
│   │   └── task/               #   异步任务框架
│   ├── model/                  # 数据模型（由 gf gen dao 自动生成，禁止手动修改）
│   │   ├── do/                 #   Domain Objects（查询条件、输入结构体）
│   │   └── entity/             #   Entity（与数据库表 1:1 映射的数据实体）
│   ├── packed/                 # 打包资源（内嵌静态文件、编译时生成）
│   ├── dao/                    # 数据访问对象（由 gf gen dao 自动生成，禁止手动修改）
│   ├── response/               # 统一响应工具包（Success/Error 封装）
│   ├── service/                # 业务接口定义（由 gf gen service 从 logic/ 自动生成，禁止手动修改）
│   ├── middleware/             # 中间件
│   └── utility/                # 工具函数
│       ├── crypto/             #   加密工具
│       ├── export/             #   数据导出
│       ├── totp/               #   TOTP 两步验证
│       └── turnstile/          #   Cloudflare Turnstile 验证
├── relay/                      # AI 模型代理层（顶级模块，独立于 GoFrame 脚手架生成目录）
│   ├── channel/                #   供应商适配器（registry.go + 24 个子目录，每个供应商一个）
│   │   └── openai/ claude/ gemini/ ...
│   ├── common/                 #   Relay 层共享类型和工具
│   ├── constant/               #   Relay 层常量（供应商类型、模式、错误码）
│   ├── dto/                    #   数据传输对象（OpenAI/Claude/Gemini/Realtime/Task 等格式定义）
│   ├── handler/                #   Relay 请求处理器（chat/claude/gemini/audio/rerank/task/realtime 等）
│   ├── helper/                 #   Relay 辅助函数（流式处理、状态码映射、系统提示词、thinking 处理）
│   ├── override/               #   请求/响应覆盖（Header 改写、参数覆盖）
│   ├── scheduler/              #   渠道调度器（调度、亲和性、重试）
│   └── taskchannel/            #   异步任务渠道适配器
│       ├── registry.go         #     任务渠道注册表
│       ├── kling/              #     可灵视频生成
│       ├── midjourney/         #     Midjourney 图像生成
│       ├── sora/               #     Sora 视频生成
│       └── suno/               #     Suno 音乐生成
├── manifest/
│   ├── config/                 # 应用运行时配置（GoFrame 标准路径）
│   ├── deploy/                 # 部署配置（K8s/Compose 等）
│   ├── docker/                 # Docker 构建配置
│   ├── i18n/                   # 国际化资源文件
│   └── protobuf/               # Protobuf 定义文件
├── migrations/                 # goose 数据库迁移脚本（六位序号编号：000001_xxx.sql）
├── web/                        # 前端
│   ├── admin/                  # 管理后台
│   └── tenant/                 # 租户控制台
├── docs/                       # 项目文档
│   ├── 开发计划-v2/            #   分周期开发计划（周期一～六）
│   └── 协议文档/               #   协议相关文档
├── new-api/                    # 参考项目（只读，不修改）
├── sub2api/                    # 参考项目（只读，不修改）
├── main.go                     # 应用入口
├── go.mod
└── Makefile

Relay 层设计说明

Relay 层作为顶级 relay/ 模块独立于 GoFrame 脚手架生成目录（internal/ 下的 controller/service/dao/model），原因：

  • 文件量大：24 个供应商适配器 + 4 个异步任务适配器 + 共享模块，放在 internal/logic/ 下层级过深
  • 职责独立：Relay 是纯粹的代理转发层，不依赖 GoFrame ORM/DAO，与 internal/ 下的业务逻辑解耦
  • 参考对齐：目录结构与 new-api 的 relay/ 保持一致，降低移植和理解成本

internal/logic/ 中的业务逻辑（如计费、渠道调度）通过 Go import 调用 relay/ 包，而非将 relay 嵌入 logic 内部。

GoFrame 代码生成与手动编写分界

目录 生成方式 能否手动修改
api/ 手动编写 是（结构体定义和路由注解）
hack/config.yaml 手动编写 是（CLI 工具配置）
internal/controller/ gf gen ctrl 否（自动生成）
internal/service/ gf gen service 否（自动生成接口）
internal/model/do/ gf gen dao 否（自动生成）
internal/model/entity/ gf gen dao 否（自动生成）
internal/dao/ gf gen dao 否（自动生成）
internal/logic/ 手动编写 是（核心业务逻辑）
internal/cmd/ 手动编写 是（路由注册、服务启动）
internal/consts/ 手动编写 是（常量定义）
internal/handler/ 手动编写 是（特殊端点处理器，见下方说明）
internal/response/ 手动编写 是（统一响应工具包）
internal/middleware/ 手动编写 是（中间件）
internal/utility/ 手动编写 是（工具函数：加密、导出、TOTP、Turnstile）
manifest/config/ 手动编写 是（运行时配置）
relay/ 手动编写 是（AI 模型代理层，独立于 GoFrame 脚手架）

internal/handler/ 目录说明

internal/handler/ 目录包含特殊端点的处理器，这些端点不适合走 GoFrame 的标准 Controller 链路：

子目录 用途
handler/relay/ /v1/* AI 代理端点（OpenAI/Claude/Gemini 兼容格式）- 需要直接操作 http.ResponseWriter 进行流式转发
handler/public/ /api/payment/* 支付回调端点 - 需要返回非 JSON 格式的响应（如支付宝的表单重定向）
handler/setup/ /api/setup/* 系统初始化向导端点 - 首次部署时的系统配置页面和初始化接口

为什么不用 Controller：

  • 流式响应：AI 代理端点需要实时转发上游的 SSE 流，Controller 的响应包装会破坏流式传输
  • 原生格式透传：必须保持与 OpenAI/Claude/Gemini API 完全兼容的请求/响应格式
  • 自定义响应：支付回调需要返回 HTML 表单或文本响应，而非统一的 JSON 格式

与 Controller 的区别：

  • Controller：走 GoFrame 标准链路（api → controller → service → logic → dao），返回统一 JSON 响应
  • Handler：直接处理 HTTP 请求/响应，不走 GoFrame 的 ghttp.Request 包装，用于特殊场景

GoFrame 脚手架生成顺序（重要）

项目 hack/config.yaml 中 gfcli.gen.ctrl 已配置 withService: true，意味着 gf gen ctrl 会尝试自动将控制器连接到 service 方法。但前提是 service 接口中已存在对应方法，否则生成 CodeNotImplemented 桩代码。

新增接口时必须按以下顺序执行，不可颠倒：

  1. 编写 API 定义（api/xxx/v1/xxx.go）— 添加 Req/Res 结构体
  2. 编写 Logic 实现（internal/logic/xxx/xxx.go）— 实现业务逻辑
  3. gf gen service — 从 Logic 方法签名自动生成 Service 接口
  4. gf gen ctrl — 从 API 定义生成 Controller，此时 withService: true 会自动生成 return service.Xxx().Method(ctx, req) 调用

如果先执行 gf gen ctrl 再执行 gf gen service，控制器会是桩代码（返回 501 Not Implemented），需要手动修改。始终遵循 "logic → gen service → gen ctrl" 的顺序可避免此问题。

重要：gf gen ctrl 执行后必须验证。即使顺序正确，withService: true 的自动接线对新方法也可能失败，生成 CodeNotImplemented 桩代码。执行后务必检查：

grep -r "CodeNotImplemented" internal/controller/

如果有匹配，手动将桩代码替换为 return service.Xxx().Method(ctx, req) 调用。切勿假设 gf gen ctrl 的输出一定正确。

GoFrame 请求处理链路

cmd（路由注册）
  → api（请求/响应结构体定义）
    → controller（解析请求、校验参数、调用 service）
      → service（接口定义，自动生成）
        → logic（业务逻辑实现，使用 DO 构造查询）
          → dao（ORM 操作，返回 Entity）
        ← 返回 Entity
      ← controller 格式化响应（Res 结构体）

参考项目（只读，禁止修改）

项目根目录下有 new-api/ 和 sub2api/ 两个参考项目，它们是大模型网关领域的成熟实现。 大多数情况下不需要查看这2个目录下的代码，除非我主动提及或者涉及到大模型相关的实现逻辑。

new-api 重点参考

  • Relay 代理层架构：controller/relay/，适配器模式、请求转发、响应解析
  • 供应商适配器：relay/channel/ 下 40+ 供应商的适配器实现，优先复用
  • 协议转换：OpenAI ↔ Claude ↔ Gemini 消息格式互转
  • 渠道调度：优先级/权重选择、自动重试、Key 轮询
  • 计费模型：预扣/结算/退款、梯度定价、Token 计量

sub2api 重点参考

  • 渠道亲和性：用户+模型→渠道映射缓存策略
  • 运维监控：仪表盘设计、健康监控页面
  • 用户体系：前端布局和组件设计

参考原则

参考不等于照搬。new-api 使用 Gin + GORM，我们需要适配到 GoFrame 框架。接口设计和核心算法可以参考，但代码需要重新组织以符合 GoFrame 标准结构（api → controller → service → logic → dao 分层）和项目的多租户架构。注意 GoFrame 的 model/do/、model/entity/、dao/、service/、controller/ 均由脚手架自动生成，业务代码只写在 api/、logic/、cmd/、handler/、middleware/、response/、utility/、consts/ 和顶级 relay/ 中。

核心架构决策

多租户隔离

行级隔离：所有业务表包含 tenant_id 字段，GoFrame ORM 中间件全局注入 WHERE tenant_id = ?。请求链路通过 Context 传递 tenant_id。

路由前缀

/api/admin/     管理后台（JWT 认证，admin_users 表）
/api/tenant/    租户控制台（JWT 认证，tenant_users 表，RAM 格式 用户名@租户代码）
/api/payment/   支付回调（签名验证，无用户认证）
/api/captcha/   验证码服务（无需认证，管理后台 + 租户控制台共用）
/api/docs/      OpenAPI 文档（无需认证）
/api/open/      开放平台 API（HMAC-SHA256 认证）
/api/setup/     系统初始化向导（首次部署，完成后禁用）
/v1/            AI 代理端点 — OpenAI 兼容格式（API Key 认证，Bearer Token）
/v1beta/        AI 代理端点 — Gemini 兼容格式（API Key 认证，Bearer Token）
/suno/          Suno 音乐生成端点（API Key 认证）

RBAC 权限模型

三层：角色 + 权限点 + 数据范围。公式：is_allowed = has_permission_point AND within_data_scope AND resource_state_allows。

管理后台角色：super_admin（全权限）、admin（可配置权限集）。 租户控制台角色：owner（全权限）、admin（管理权限）、member（个人数据）。

五层额度模型

租户钱包（货币池）→ 套餐额度（资源池）→ 成员额度（控制线）→ 项目预算（控制线）→ Key 额度（控制线）

扣费优先级：先扣套餐资源量，不足部分扣钱包余额。免费版额度耗尽停止服务，钱包余额不兜底。

计费流程

预扣（Redis 原子操作）→ 转发请求 → 结算（实际用量）→ 退款/补扣差额

价格查询优先级：租户独立价 > 套餐价 > 模型基础价 > 硬编码默认。

最终价格公式：最终价格 = 基础价格 × 模型乘数 × 租户乘数。模型乘数根据模型稀有度/成本动态调整；租户乘数根据租户等级/用量等级设置（VIP 折扣等）。双层乘数替代单纯的"租户独立定价"，提供更灵活的定价能力。

钱包冻结余额

wallets 表包含 frozen_balance 字段，用于支付中/退款中的金额冻结，防止并发超扣。可用余额 = balance - frozen_balance。预扣和支付操作需检查可用余额而非总余额。

系统货币规则

平台采用内部统一 USD + 充值入口 CNY策略，系统内除充值/支付外的所有金额均为 USD：

业务场景 货币 说明
大模型价格展示和计费 USD（美元） 模型定价、Token 单价、计费扣费统一使用美元，与上游供应商（OpenAI/Anthropic/Google）报价币种一致
用户钱包余额 USD（美元） 钱包存储 USD 余额，充值时 CNY 按汇率转换为 USD 入账
计费记录 / 交易流水 USD（美元） 所有 bil_records、bil_transactions 金额均为 USD
套餐价格 CNY（人民币） 管理后台创建套餐时设置的价格为人民币，用户购买套餐使用人民币支付
充值/支付 CNY（人民币） 用户通过支付渠道（支付宝/微信/Stripe）充值为人民币，履约时转换为 USD 入账钱包

换算规则：

  • 管理后台支付设置中配置 CNY → USD 兑换比例（payment_exchange_rate_cny_to_usd，默认 0.14）
  • 充值履约时调用 billing.ConvertCNYToUSD(ctx, cnyAmount) 将 CNY 金额转换为 USD 入账钱包
  • 计费引擎全程使用 USD，无需换算
  • 前端展示规则：钱包余额/交易记录/计费用 $（USD），套餐价格/充值金额/订单金额用 ¥（CNY）

数据库表前缀定义

按功能域划分，新建表时必须归入对应前缀，除非加入了新的功能模型，否则不得自行新增前缀。

前缀 功能域 周期 涉及表（示例）
sys_ 平台系统 + 系统配置 一 sys_admin_users sys_admin_role_perms sys_admin_data_scopes sys_sessions sys_email_verify_codes sys_idempotency_records sys_options
tnt_ 租户核心 + 项目管理 一 tnt_tenants tnt_users tnt_invitations tnt_member_imports tnt_member_model_scopes tnt_projects
mdl_ AI 模型 一 mdl_models mdl_pricing_tiers mdl_tenant_models
chn_ 渠道管理 一 chn_channels chn_abilities chn_health_scores chn_channel_keys chn_channel_affinities
api_ API 密钥 一 api_keys api_key_model_scopes
bil_ 计费账单 一 bil_records bil_wallets bil_transactions bil_usage_logs bil_daily_usage_summary bil_daily_revenue_summary bil_monthly_usage_summary bil_monthly_revenue_summary
ord_ 订单支付 + 优惠券 二 ord_orders ord_refunds ord_payment_channels ord_promo_codes ord_promo_code_usages ord_redemptions ord_redemption_usages
pln_ 套餐订阅 二 pln_plans pln_tenant_plans pln_feature_flags
ntf_ 通知消息 三 ntf_templates ntf_send_log ntf_messages ntf_read_status ntf_preferences ntf_announcements
aud_ 审计日志 三 aud_request_logs aud_operation_logs aud_sensitive_access_logs aud_login_history
spt_ 客户支持（工单+帮助+反馈） 三/六 spt_tickets spt_replies spt_attachments spt_categories spt_articles spt_feedbacks
ops_ 运维监控 四 ops_alert_rules ops_alert_events ops_system_metrics
tsk_ 异步任务 四 tsk_tasks tsk_task_logs tsk_model_tasks
fil_ 文件存储 四 fil_files
opn_ 开放平台 + Webhook 五 opn_apps opn_webhook_configs opn_webhook_events opn_webhook_delivery_logs
clg_ 更新日志 六 clg_changelogs

前缀使用规则

  • 新建表必须从上表选择前缀，不允许自行新增前缀
  • 如果一个表明显属于两个域，选择核心归属域的前缀
  • 通用/跨域表（如 sys_options 系统配置）放在最相关的域下
  • 迁移脚本文件名按现有文件顺序递增编号，格式：{序号}_{变更内容描述}.sql，例如 000002_alter_mdl_pricing_cache_fields.sql

开发规范

Go 后端

  • 缩进统一使用 tab：所有 Go 代码的缩进必须使用 tab，与 go fmt 自动格式化保持一致，禁止混用空格和 tab 缩进
  • GoFrame 标准项目结构，不要偏离。框架使用规范（时间处理、错误处理、ORM 模式、日志等）详见 docs/reference/goframe-conventions.md，遇到不确定的 GoFrame 用法时善用 /goframe-v2 skill 查询框架规范
  • 修复 GoFrame 框架使用 bug 时，必须在 docs/reference/goframe-conventions.md 末尾的「已修复的框架使用错误记录」章节追加记录（问题描述、原因、修复方式），防止同类问题重现
  • 数据库迁移用 goose，脚本按六位序号递增编号（migrations/000001_xxx.sql）
  • 所有业务表必须有 id, created_at, updated_at 字段
  • 审计相关表按月分区（audit_logs）
  • 使用量大的写入操作（usage_logs）异步批量写入
  • 错误响应统一格式：{"error": {"type": "...", "message": "...", "code": "...", "request_id": "..."}}
  • 每个 API 请求生成唯一 Request ID，贯穿全链路
  • 敏感字段（密码、API Key 原值）AES-256 加密存储
  • 缓存策略：API Key 60s、用户信息 300s、模型定价 600s、渠道信息 300s

前端

  • Vue 3 Composition API + <script setup> 语法
  • 管理后台：使用 Naive UI 组件库，快速构建数据密集型页面（表格、表单、图表等），可参考 Soybean Admin 的架构设计（路由、权限、布局）
  • 租户控制台：TailwindCSS 原子类 + 自建组件，面向客户，注重品牌调性和视觉差异化
  • TailwindCSS 作为基础样式层，两个控制台共用（Naive UI 的 CSS-in-JS 方案与 TailwindCSS 无冲突）
  • 状态管理用 Pinia
  • HTTP 请求封装 Axios，JWT 自动刷新，统一错误处理
  • 按钮级权限控制：无权限的按钮不渲染（v-if="hasPermission('xxx')"）
  • 前端不用 React，不用 JSX

数据库

  • 只用 PostgreSQL，写 SQL 迁移脚本时使用 PostgreSQL 语法
  • 数据库是远程连接，本地没有 psql 等命令可用，数据库操作只能通过 goose 迁移脚本执行
  • 表名带模块前缀：同一模块/功能/域的表使用统一前缀（见下方《数据库表前缀定义》），提升可维护性
  • 全部小写蛇形命名：表名和字段名一律 snake_case，禁止驼峰或大写
  • 禁止数据库级外键：所有关联都是逻辑关联，不使用 REFERENCES/FOREIGN KEY，在代码层面处理关联关系和级联操作
  • 所有字段必须带注释：建表时每个字段都加 COMMENT '说明'，便于后续维护
  • JSONB 字段用于灵活配置（功能权限、通知偏好等）
  • 字符串字段注意长度限制，不要用 VARCHAR(255) 一刀切
  • 金额字段统一用 NUMERIC(20,10)（PostgreSQL 中 NUMERIC 与 DECIMAL 等价），避免累计计算精度丢失，不用 FLOAT
  • 资金显示精度：系统中所有资金相关数值（钱包余额、交易金额、计费金额、单价等）在 API 响应和前端展示时一律精确到小数点后 6 位（特殊说明除外），与 NUMERIC(20,10) 存储精度对齐，保证前端显示与后端计算结果一致
  • 索引按实际查询场景创建，不过度索引
  • 追加写表使用 BRIN 索引：usage_logs、audit_logs、billing_records 等按时间追加写入的表，在 created_at 字段上使用 BRIN 索引（而非 B-tree），大幅节省存储空间

API 接口

  • URL 路径统一小写蛇形：/api/admin/tenant-plans 而非 /api/admin/tenantPlans
  • GoFrame 有脚手架命令（gf gen），能使用脚手架生成的代码（model/dao/api）就用脚手架生成，不要手写
  • 完整的 JSON 示例、SSE 流式格式、各供应商响应格式、错误类型映射、中间件差异等详见 docs/reference/api-format-reference.md

统一响应格式（/api/* 管理类接口）

所有管理类接口（/api/admin/*、/api/tenant/*、/api/payment/*、/api/open/*）使用统一 JSON 结构：{"code": 0, "message": "ok", "data": ..., "request_id": "..."}。code=0 成功，非 0 错误。HTTP 状态码照常设置，前端以 code 为主。

data 字段规范：分页列表 {list, total, page, page_size}，不分页 {list}，创建 {id}，详情直接返回对象，更新/删除 null。数组字段名统一用 list，list 内部可为空但不能有 null。

后端：统一使用 internal/response 包（response.Success / response.Error），禁止直接拼 g.Map。业务错误码 >= 10000 定义在 internal/consts/consts.go，映射为 HTTP 422。message 必须中文，禁止暴露技术细节。

前端：Axios 拦截器以 code === 0 为唯一成功判据，统一处理错误提示。所有 API 调用 try/catch 包裹。

大模型代理接口（/v1/*、/v1beta/*、/suno/*）

代理端点是 OpenAI/Claude/Gemini 等 AI 服务的反向代理，必须与上游 API 格式完全兼容。核心规则：

  • 禁止使用统一响应格式和 internal/response 包，直接操作 http.ResponseWriter
  • 原生透传：上游响应原样转发，错误也用供应商原生格式
  • 错误处理：WriteRelayError（OpenAI 格式）、WriteClaudeRelayError（Claude 格式）

Definition of Done（功能完成标准）

每个功能模块交付时需满足以下标准：

# 标准 说明
1 功能通过手动测试 核心业务流程端到端可跑通
2 单元测试覆盖率 ≥ 80% 核心计费/调度/权限逻辑必须有单元测试
3 接口文档同步更新 API 端点变更时同步更新 OpenAPI 文档
4 数据库迁移可重复执行 goose up/down 幂等，不破坏已有数据
5 错误码与提示文案完整 所有错误场景有明确错误码和用户可读消息
6 日志记录完整（含 trace_id） 关键业务操作日志贯穿 request_id
7 权限校验覆盖所有端点 新增端点必须配置权限点，无权限返回 403
8 代码审查通过 核心模块需 Code Review 后合入

文档索引

关键文档在 docs/ 下，需要时直接阅读：

文档 路径 用途
产品需求文档 docs/team-api产品需求文档.md 功能需求的最终依据
原始开发计划 docs/team-api开发计划.md S01-S26 迭代拆分
new-api 调研 docs/new-api调研报告.md 参考项目能力盘点
sub2api 调研 docs/sub2api调研报告.md 参考项目能力盘点
对比分析 docs/new-api-vs-sub2api对比分析报告.md 两者差异
大模型实施方案 docs/大模型完整实施方案-v2.1.md 大模型代理层设计
API 格式参考 docs/reference/api-format-reference.md JSON 示例、SSE 格式、错误映射、中间件差异
GoFrame 使用规范 docs/reference/goframe-conventions.md 框架使用规范 + 已修复的框架 bug 记录

开发环境

  • 操作系统：Windows
  • GoFrame CLI：已安装 gf 脚手架，优先使用 CLI 完成以下工作：
命令 用途 何时使用
gf init 初始化项目骨架 项目创建时
gf gen dao 从数据库生成 DAO/DO/Entity 代码 表结构变更后
gf gen service 从 Logic 层生成 Service 接口 业务接口变更后
gf gen ctrl 从 API 定义生成 Controller API 定义变更后
gf gen pb 生成 protobuf 文件 需要时
gf run 热编译运行开发服务器 开发调试
gf build 编译生产二进制 构建部署
Reference in new issue View Git Blame Copy Permalink