👕 服装AI处理 SaaS 平台

项目定位：为服装电商提供AI图片处理服务的SaaS平台 核心业务：会员制订阅服务（¥99/月 = 100次配额） 技术架构：前后端分离 + 微服务 + 云原生

---

🏗️ 项目结构

fashion-ai-saas/
├── backend/                 # 后端 API 服务
│   ├── src/
│   │   ├── controllers/     # 控制器层
│   │   ├── services/        # 业务逻辑层
│   │   ├── models/          # 数据模型层
│   │   ├── middleware/      # 中间件
│   │   ├── routes/          # 路由定义
│   │   ├── utils/           # 工具函数
│   │   └── config/          # 配置文件
│   ├── migrations/          # 数据库迁移文件
│   └── package.json
├── frontend/                # 网页工作台 (Next.js)
│   ├── src/
│   │   ├── app/            # App Router页面
│   │   ├── components/     # React组件
│   │   ├── hooks/          # 自定义Hooks
│   │   ├── store/          # Zustand状态管理
│   │   ├── services/       # API调用服务
│   │   └── utils/          # 工具函数
│   └── package.json
├── miniapp/                 # 微信小程序前端 (TODO)
├── scf/                     # 云函数 / 大文件异步任务 (TODO)
├── deploy/                  # 部署 / 运维脚本 (TODO)
├── tests/                   # QA / 自动化验收测试 (TODO)
├── skills/                  # 角色/Agent能力说明书
│   ├── product_planner_skill/    # 产品规划师技能包
│   │   ├── FLOW.md               # 标准工作流程
│   │   └── CHECKLIST.md          # 自检清单
│   ├── frontend_dev_skill/       # 前端开发工程师技能包
│   │   ├── FLOW.md               # 标准工作流程
│   │   └── CHECKLIST.md          # 自检清单
│   ├── backend_dev_skill/        # 后端开发工程师技能包
│   │   ├── FLOW.md               # 标准工作流程
│   │   └── CHECKLIST.md          # 自检清单
│   ├── scf_worker_skill/         # 云函数处理工程师技能包
│   │   ├── FLOW.md               # 标准工作流程
│   │   └── CHECKLIST.md          # 自检清单
│   ├── billing_guard_skill/      # 计费守卫员技能包
│   │   ├── FLOW.md               # 标准工作流程
│   │   └── CHECKLIST.md          # 自检清单
│   ├── qa_acceptance_skill/      # QA验收工程师技能包
│   │   ├── FLOW.md               # 标准工作流程
│   │   └── CHECKLIST.md          # 自检清单
│   ├── reviewer_skill/           # 代码审查专家技能包
│   │   ├── FLOW.md               # 标准工作流程
│   │   └── CHECKLIST.md          # 自检清单
│   └── codebuddy_deploy_skill/   # CodeBuddy部署专家技能包
│       ├── FLOW.md               # 标准工作流程
│       └── CHECKLIST.md          # 自检清单
├── docs/                    # 项目规格、验收标准、历史交付记录
├── .gitignore
├── CLAUDE.md               # AI助手工作指南
└── README.md               # 本文档

🎯 核心功能

1. 认证系统

• 手机号 + 验证码登录
• JWT token认证
• 用户session管理

2. 会员管理

• 月费会员购买（¥99/月）
• 配额管理（100次/月）
• 会员状态检查

3. 任务处理

• 基础修图（basic_clean）：腾讯数据万象，同步处理
• AI模特12分镜（model_pose12）：RunningHub AI，异步处理
• 任务状态跟踪和结果管理

4. 配额管理

• 事务级配额扣减和返还
• 防并发竞争（行锁）
• 失败任务自动返还配额

5. 媒体服务

• 腾讯云COS对象存储
• STS临时密钥生成
• 直传支持

6. 支付集成

• 微信支付API v3
• 支付回调处理
• 订单状态管理

---

🔧 开发流程

分支管理

main        ←── 受保护分支，仅用于生产环境
   ↑
develop     ←── 开发分支，所有开发在这里进行
   ↑
feature/*   ←── 功能分支，从develop创建

工作流程

1. 所有开发在 develop 分支进行
2. 完成后提交 Pull Request 到 main 分支
3. 通过代码审查和测试验收后合并
4. 禁止直接向 main 分支推送代码

权限/安全

• 后端使用 Casbin 作为权限引擎，策略存储在 casbin_rule 表。模型定义位于 src/security/casbin-model.conf
• 测试环境默认通过 CASBIN_DISABLED=true 退回静态 RBAC；开发/生产请确保该变量未设置并运行 npm run db:migrate
• SecretVault 统一加载 MASTER_KEY、CREDENTIALS_ENCRYPTION_KEY，缺少配置只允许在 NODE_ENV !== production 下生成临时密钥

迁移规范

• 所有 Knex 迁移脚本统一放在 backend/src/db/migrations/
• 新增迁移前先执行 npm run migrate:audit 确保没有重复命名或野目录
• 提交前至少跑一次 npm run db:migrate && npm run test:unit

提交规范

# 功能开发
git commit -m "feat: 添加用户登录功能"

# 问题修复
git commit -m "fix: 修复配额扣减的并发问题"

# 文档更新
git commit -m "docs: 更新API文档"

# 代码重构
git commit -m "refactor: 优化查询性能"

# 部署配置
git commit -m "chore: 添加环境变量配置"

---

💰 配额管理核心规则

配额流转逻辑

任务创建 = 预扣配额
任务成功 = 扣除生效
任务失败 = 自动返还

技术约束 ⚠️

1. 配额操作必须使用事务

// ✅ 正确：使用事务和行锁
await transaction(async (trx) => {
  const user = await trx('users')
    .where({ id: userId })
    .forUpdate()  // 行锁
    .first();

  if (user.quota_remaining <= 0) {
    throw new Error('配额不足');
  }

  await trx('users')
    .where({ id: userId })
    .decrement('quota_remaining', 1);
});

2. 外部服务查询约束

// ✅ 正确：仅在processing时查询
if (task.status === 'processing' && task.type === 'model_pose12') {
  const rhStatus = await runningHubAPI.getStatus(task.vendorTaskId);
  // 处理结果并一次性落库
}

3. 配额值配置化

# ✅ 正确：使用环境变量
PLAN_MONTHLY_QUOTA=100

# ❌ 错误：代码硬编码
const QUOTA = 100;  // 后续调价需要改代码

---

📚 文档导航

🎯 面向不同角色

👨‍💻 开发工程师

• API文档 - 完整接口规范
• 实施指南 - 开发要点和示例
• 技术栈指南 - 技术选型和配置

📊 产品经理/业务分析师

• 项目总结 - 项目整体情况
• 功能PRD - 详细功能需求
• 验收标准 - 功能验收清单

🔍 质量保证/测试

• 任务卡-测试 - 测试开发任务
• 交付清单 - 项目验收标准
• API文档 - 接口测试依据

🚀 运维/部署

• 技术栈指南 - 环境配置
• 部署说明 - 部署流程和脚本
• 环境配置 - 配置模板

🤖 AI角色技能手册

📋 产品规划师 (product_planner_skill)

• 标准工作流程 - 9步标准需求拆解流程
• 自检清单 - 需求完整性自检

🎨 前端开发工程师 (frontend_dev_skill)

• 标准工作流程 - 7步前端开发流程
• 自检清单 - 代码质量和用户体验检查

⚙️ 后端开发工程师 (backend_dev_skill)

• 标准工作流程 - 8步后端开发流程
• 自检清单 - 安全性和性能检查

🌩️ 云函数处理工程师 (scf_worker_skill)

• 标准工作流程 - 6步云函数开发流程
• 自检清单 - 云原生和成本控制检查

💰 计费守卫员 (billing_guard_skill)

• 标准工作流程 - 7步配额和计费管理流程
• 自检清单 - 配额原子性和财务安全检查

🔍 QA验收工程师 (qa_acceptance_skill)

• 标准工作流程 - 6步功能验收测试流程
• 自检清单 - 功能完整性和用户体验验收

👀 代码审查专家 (reviewer_skill)

• 标准工作流程 - 7步代码审查流程
• 自检清单 - 代码质量和安全性审查

🚀 CodeBuddy部署专家 (codebuddy_deploy_skill)

• 标准工作流程 - 8步部署流程
• 自检清单 - 部署安全和生产环境检查

📋 完整文档目录

详细文档请查看 docs/ 目录，包含：

• MVP需求规格
• API约定文档
• 交付记录和验收标准
• 历史开发记录
• 各角色任务卡
• backend/docs/backend-tech-stack-improvements.md - 后端技术栈治理方案与工具清单

---

🧪 MVP验收标准

功能验收（必须全部通过）

• 用户注册登录（手机号+验证码）
• 会员购买（支付成功→配额到账100次）
• 基础修图功能（上传→生成白底主图→扣1次）
• AI模特生成功能（上传→12张分镜→扣1次）
• 失败处理（配额自动返还）
• 管理后台（用户/任务查询）

性能要求

• 基础修图响应时间: < 5秒（P95）
• AI模特生成时间: < 3分钟（P95）
• 任务列表加载: < 1秒
• API响应时间: < 500ms（P95）

---

🚀 部署信息

• 服务器: 43.139.187.166
• API域名: api.aizhao.icu
• 前端域名: @.aizhao.icu
• 数据库: MySQL 8.0
• 存储: 腾讯云COS（ai-photo-prod-1379020062）

---

🛡️ 安全准则

❌ 严禁操作

• 禁止在仓库中提交真实密钥、token、apiKey
• 禁止直接操作生产环境数据库
• 禁止绕过代码审查流程合并代码

✅ 必须遵守

• 使用环境变量管理敏感配置
• 所有API调用需要身份验证
• 用户数据严格隔离
• 定期安全审查和依赖更新

---

🤝 贡献指南

代码提交前检查

1. 代码符合项目规范
2. 已通过本地测试
3. 已更新相关文档
4. 无敏感信息泄露

Pull Request要求

1. 清晰的标题和描述
2. 说明变更原因和影响范围
3. 关联相关Issue或任务卡
4. 通过所有自动化检查

---

📞 支持与联系

• 技术问题: 查看相关文档或提交Issue
• 业务咨询: 联系产品经理
• 部署运维: 参考部署文档

---

📝 更新日志

版本	日期	更新内容
dev-log	2025-11-14	排查并清理 backend/migrations 冗余脚本，统一迁移目录
v2.0	2025-10-28	仓库结构规范化，技能和文档分类整理
v1.0	2025-10-28	完整MVP设计文档和实施指南

---

🎉 欢迎加入服装AI处理SaaS平台项目！

重要提醒：main分支上的逻辑是唯一准则，不允许绕开配额管理核心规则！