# 👕 服装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` ### 提交规范 ```bash # 功能开发 git commit -m "feat: 添加用户登录功能" # 问题修复 git commit -m "fix: 修复配额扣减的并发问题" # 文档更新 git commit -m "docs: 更新API文档" # 代码重构 git commit -m "refactor: 优化查询性能" # 部署配置 git commit -m "chore: 添加环境变量配置" ``` --- ## 💰 配额管理核心规则 ### 配额流转逻辑 ``` 任务创建 = 预扣配额 任务成功 = 扣除生效 任务失败 = 自动返还 ``` ### 技术约束 ⚠️ #### 1. 配额操作必须使用事务 ```javascript // ✅ 正确：使用事务和行锁 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. 外部服务查询约束 ```javascript // ✅ 正确：仅在processing时查询 if (task.status === 'processing' && task.type === 'model_pose12') { const rhStatus = await runningHubAPI.getStatus(task.vendorTaskId); // 处理结果并一次性落库 } ``` #### 3. 配额值配置化 ```bash # ✅ 正确：使用环境变量 PLAN_MONTHLY_QUOTA=100 # ❌ 错误：代码硬编码 const QUOTA = 100; // 后续调价需要改代码 ``` --- ## 📚 文档导航 ### 🎯 面向不同角色 #### 👨‍💻 开发工程师 - **[API文档](docs/API_DOCUMENTATION.md)** - 完整接口规范 - **[实施指南](docs/IMPLEMENTATION_GUIDE.md)** - 开发要点和示例 - **[技术栈指南](docs/TECH_STACK_GUIDE.md)** - 技术选型和配置 #### 📊 产品经理/业务分析师 - **[项目总结](docs/PROJECT_SUMMARY.md)** - 项目整体情况 - **[功能PRD](docs/FEATURE_VIDEO_GENERATION_PRD.md)** - 详细功能需求 - **[验收标准](docs/DELIVERY_CHECKLIST.md)** - 功能验收清单 #### 🔍 质量保证/测试 - **[任务卡-测试](docs/TASK_TEST_DEV.md)** - 测试开发任务 - **[交付清单](docs/PROJECT_DELIVERY_CHECKLIST.md)** - 项目验收标准 - **[API文档](docs/API_DOCUMENTATION.md)** - 接口测试依据 #### 🚀 运维/部署 - **[技术栈指南](docs/TECH_STACK_GUIDE.md)** - 环境配置 - **[部署说明](deploy/README.md)** - 部署流程和脚本 - **[环境配置](deploy/README.md#环境变量模板)** - 配置模板 ### 🤖 AI角色技能手册 #### 📋 产品规划师 (product_planner_skill) - **[标准工作流程](skills/product_planner_skill/FLOW.md)** - 9步标准需求拆解流程 - **[自检清单](skills/product_planner_skill/CHECKLIST.md)** - 需求完整性自检 #### 🎨 前端开发工程师 (frontend_dev_skill) - **[标准工作流程](skills/frontend_dev_skill/FLOW.md)** - 7步前端开发流程 - **[自检清单](skills/frontend_dev_skill/CHECKLIST.md)** - 代码质量和用户体验检查 #### ⚙️ 后端开发工程师 (backend_dev_skill) - **[标准工作流程](skills/backend_dev_skill/FLOW.md)** - 8步后端开发流程 - **[自检清单](skills/backend_dev_skill/CHECKLIST.md)** - 安全性和性能检查 #### 🌩️ 云函数处理工程师 (scf_worker_skill) - **[标准工作流程](skills/scf_worker_skill/FLOW.md)** - 6步云函数开发流程 - **[自检清单](skills/scf_worker_skill/CHECKLIST.md)** - 云原生和成本控制检查 #### 💰 计费守卫员 (billing_guard_skill) - **[标准工作流程](skills/billing_guard_skill/FLOW.md)** - 7步配额和计费管理流程 - **[自检清单](skills/billing_guard_skill/CHECKLIST.md)** - 配额原子性和财务安全检查 #### 🔍 QA验收工程师 (qa_acceptance_skill) - **[标准工作流程](skills/qa_acceptance_skill/FLOW.md)** - 6步功能验收测试流程 - **[自检清单](skills/qa_acceptance_skill/CHECKLIST.md)** - 功能完整性和用户体验验收 #### 👀 代码审查专家 (reviewer_skill) - **[标准工作流程](skills/reviewer_skill/FLOW.md)** - 7步代码审查流程 - **[自检清单](skills/reviewer_skill/CHECKLIST.md)** - 代码质量和安全性审查 #### 🚀 CodeBuddy部署专家 (codebuddy_deploy_skill) - **[标准工作流程](skills/codebuddy_deploy_skill/FLOW.md)** - 8步部署流程 - **[自检清单](skills/codebuddy_deploy_skill/CHECKLIST.md)** - 部署安全和生产环境检查 ### 📋 完整文档目录 详细文档请查看 [`docs/`](docs/) 目录，包含： - MVP需求规格 - API约定文档 - 交付记录和验收标准 - 历史开发记录 - 各角色任务卡 - [backend/docs/backend-tech-stack-improvements.md](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分支上的逻辑是唯一准则，不允许绕开配额管理核心规则！