# Relay-SaaS 项目开发指引

## 📌 项目概述

**项目名称：** Relay-SaaS（基于 one-api 的多租户 SaaS 系统）
**代码仓库：** https://git.586vip.cn/oadmin/relay-saas.git
**基础项目：** one-api (https://github.com/songquanpeng/one-api)

## 🎯 核心目标

构建一个多租户 API 中继 SaaS 平台：
- **主系统**：统一管理上游 API 渠道，集中计费
- **代理站点**：独立部署，服务终端用户
- **月套餐系统**：日/周/月额度限制的令牌系统

## 📋 重要提醒

### 开发原则
1. ⚠️ **保持可升级性**
   - 新功能尽量创建新文件
   - 避免大量修改核心代码
   - 使用插件化架构

2. ⚠️ **每次开发前**
   - 更新 `docs/DEVELOPMENT.md` 的开发记录
   - 使用 TodoWrite 工具管理任务
   - 在 Git commit 前确认修改内容

3. ⚠️ **提交代码时**
   - 写清晰的 commit message
   - 格式：`[模块] 功能描述`
   - 例如：`[套餐系统] 添加日限额度检查逻辑`

4. ⚠️ **测试要求**
   - 每个新功能必须手动测试
   - 记录测试结果到开发文档
   - 保证向后兼容

### 文件组织

**关键文档位置：**
- 📄 技术方案：`docs/SAAS-PLAN.md`
- 📝 开发记录：`docs/DEVELOPMENT.md`
- 📋 任务清单：`docs/TODO.md`
- 🔧 配置模板：`docs/DEPLOYMENT.md`

**代码组织：**
- 🆕 新增功能：`common/subscription/`, `model/agent_*.go`
- 🔧 扩展代码：在现有文件添加方法，不破坏原有逻辑
- 🧪 测试代码：`*_test.go` 文件

### Git 工作流

```bash
# 创建功能分支
git checkout -b feature/subscription-system

# 开发完成后提交
git add .
git commit -m "[套餐系统] 实现日/周/月额度限制"

# 推送到远程
git push origin feature/subscription-system

# 合并到 main
git checkout main
git merge feature/subscription-system
git push origin main
```

### 开发流程检查清单

- [ ] 确认需求，明确功能目标
- [ ] 更新 `docs/TODO.md` 任务状态
- [ ] 创建功能分支（可选）
- [ ] 编写代码，遵循现有风格
- [ ] 手动测试功能
- [ ] 更新 `docs/DEVELOPMENT.md` 记录
- [ ] 提交代码，写清晰的 message
- [ ] 推送到远程仓库

## 🔗 相关资源

- **Go 语言**：https://go.dev/doc/
- **Gin 框架**：https://gin-gonic.com/docs/
- **GORM**：https://gorm.io/docs/
- **One-API 文档**：项目 README.md

## 📞 联系方式

- **项目负责人**：huangzhenpc
- **Git 用户**：huangzhenpc
- **Git 仓库**：git.586vip.cn

---

**最后更新：** 2025-12-29
**文档版本：** v1.0