AI广告代投系统是一个专为Facebook广告代理商设计的智能化广告投放管理平台。通过AI技术和自动化流程,帮助代理商提升投放效率、优化ROI、降低运营成本。
- 🤖 AI智能监控 - 账户异常检测、性能预警、寿命预测
- 📊 自动化对账 - 精准的财务对账和差异分析
- 👥 多角色协作 - 投手、运营、财务、管理员协同工作
- 🔒 安全权限控制 - 基于RLS的数据隔离和权限管理
- 📈 实时数据监控 - 消耗、转化、ROI等关键指标实时追踪
- 💰 智能充值管理 - 自动化充值申请和审批流程
- ✅ 日报创建和管理 - 投手每日提交广告投放数据
- ✅ 审核工作流 - 数据员审核确认，支持通过/驳回
- ✅ 批量导入导出 - 支持Excel文件导入导出
- ✅ 数据统计分析 - 实时统计CPA、ROAS等关键指标
- ✅ 审计日志 - 完整的操作记录追踪
- ✅ 项目CRUD管理 - 完整的项目创建、查询、更新、删除
- ✅ 成员管理 - 灵活的团队成员分配和权限控制
- ✅ 费用记录 - 项目成本追踪和费用管理
- ✅ 统计分析 - 项目数据统计和绩效分析
- ✅ 权限控制 - 基于角色的细粒度访问控制
- ✅ 充值申请管理 - 创建、查询、更新充值申请
- ✅ 双重审核机制 - 数据审核 + 财务审批的完整流程
- ✅ 打款凭证管理 - 支付凭证上传和管理
- ✅ 统计分析报表 - 多维度充值数据分析
- ✅ 资金流程控制 - 完整的资金流转管理
Complete documentation baseline (SoT in docs/sot, PRD v5.1):
- 📖 Documentation Index - Navigation & Status
- 📋 MASTER.md v4.9 - System Constitution
- 🧭 PRD v5.1 - Product Requirements
- 🧾 SoT Version Manifest - Version Registry
- 📊 Project Rules - AI Collaboration Rules
- SoT: STATE_MACHINE v2.9, DATA_SCHEMA v5.11, API_SOT v9.7
- Guides: FRONTEND_DEVELOPMENT_GUIDE_v3.0.md, AI_PROGRAMMING_BEST_PRACTICES_v3.1.md
- Design: FRONTEND_PAGE_DESIGN_v2.1.md
- Runbooks: deploy.md, incident-response.md
- Integration: INTEGRATION_SUMMARY.md
- 框架: FastAPI + Pydantic v2
- 数据库: PostgreSQL (Supabase)
- ORM: SQLAlchemy 2.0
- 缓存: Redis
- 认证: Supabase Auth
- 框架: Next.js 16 (App Router)
- 语言: TypeScript
- 样式: Tailwind CSS
- 组件: shadcn/ui
- 状态管理: TanStack Query v5
- 容器化: Docker + Docker Compose
- 监控: Prometheus + Grafana
- 日志: ELK Stack
- CI/CD: GitHub Actions
- Node.js 18+
- Python 3.11+
- Docker Desktop
- PostgreSQL 15+
- Redis 7+
- 克隆项目
git clone https://github.com/wade56754/AI_ad_spend02.git
cd AI_ad_spend02- 配置环境变量
cp .env.example .env
# 编辑 .env 文件，配置必要的环境变量- 安装依赖
# 后端依赖
pip install -r requirements.txt
# 前端依赖
cd frontend && pnpm install
cd ..- 启动数据库
docker-compose up -d postgres redis- 运行数据库迁移
cd backend
alembic upgrade head
cd ..- 启动服务
# 启动后端 (新终端)
cd backend
uvicorn main:app --reload --port 8000
# 启动前端 (新终端)
cd frontend
pnpm run dev- 访问应用
- 前端: http://localhost:3000
- 后端API: http://localhost:8000
- API文档: http://localhost:8000/docs
AI_ad_spend02/
├── backend/ # 后端服务
│ ├── routers/ # API 路由层
│ ├── services/ # 业务逻辑层
│ ├── models/ # SQLAlchemy 模型
│ ├── schemas/ # Pydantic 模式
│ ├── core/ # 核心工具
│ ├── tests/ # 测试文件
│ └── alembic/ # 数据库迁移
├── frontend/ # 前端应用
│ ├── src/app/ # Next.js App Router
│ ├── src/features/ # 功能模块
│ ├── src/components/ # 公共组件
│ └── src/lib/ # 工具函数
├── docs/ # 文档中心
│ ├── sot/ # 真相来源文档 (SoT)
│ ├── 1.overview/ # 系统全局视图
│ ├── 3.dev-guides/ # 开发指南
│ ├── 4.architecture/ # 架构视图
│ ├── 5.infrastructure/ # 基础设施
│ ├── adr/ # 架构决策记录
│ ├── runbooks/ # 运维手册
│ └── archive/ # 历史文档归档
├── .ai-rules/ # AI 质量门禁
├── .claude/ # Claude Code 项目规则
├── scripts/ # 脚本工具
├── tests/ # 集成测试/E2E
│ ├── e2e/ # 端到端测试
│ └── integration/ # 集成测试
└── justfile # 统一命令入口
| 角色 | 核心职责 | 主要功能 |
|---|---|---|
| ceo | 资金安全、公司盈亏 | 最终决策、全局视图、资金审批 |
| project_owner | 项目盈亏、资金效率 | 项目管理、预算控制、ROI 分析 |
| finance | 资金准确、数据真实 | 财务对账、充值审批、资金核算 |
| pitcher | CPL 达标、日报准确 | 投放执行、日报提交、账户操作 |
| account_manager | 账户分配、状态监控 | 账户管理、分配调度、异常处理 |
| admin | 系统配置（不参与业务） | 用户管理、权限配置、系统维护 |
# 运行后端测试
pytest
# 运行前端测试
pnpm test
# 运行E2E测试
pnpm run test:e2e
# 查看测试覆盖率
pytest --cov=backend/app# 构建镜像
docker build -t ai-ad-spend .
# 使用docker-compose部署
docker-compose up -d# 应用配置
kubectl apply -f k8s/
# 查看部署状态
kubectl get pods -n ai-ad-spend详细部署文档请参考 部署指南
我们欢迎所有形式的贡献！请阅读 贡献指南 了解如何参与项目开发。
- Fork 项目
- 创建功能分支 (
git checkout -b feature/AmazingFeature) - 提交更改 (
git commit -m 'Add some AmazingFeature') - 推送到分支 (
git push origin feature/AmazingFeature) - 创建 Pull Request
- 遵循 PEP 8 Python代码规范
- 使用 Black + isort 进行代码格式化
- 编写单元测试，确保测试覆盖率
- TypeScript严格模式，禁止any类型
- 优先使用 shadcn/ui 组件
- 必须通过 ESLint 和 TypeScript 检查
- 提交前检查:
pnpm run lint和pnpm run type-check必须0错误
- 严格遵循 CLAUDE.md 中定义的项目规则
- 所有代码生成必须基于 docs/sot/ 下的 SoT 文档
- 开发前必读 MASTER.md 了解系统架构原则
- 遵循 Phase 1 原则：记录、提示、高亮，不强制阻断
- ✅ Phase 0: 基础架构搭建 (完成)
- ✅ Phase 1: 核心功能开发 (完成)
- 🚧 Phase 2: AI功能集成 (进行中)
- ⏳ Phase 3: 性能优化 (计划中)
本项目采用 MIT 许可证 - 详见 LICENSE 文件
- 📧 Email: support@ai-ad-spend.com
- 💬 Discord: 加入我们的社区
- 🐛 Issues: GitHub Issues
更新日志:
- 🏗️ 重构：文档结构重组 (docs/2.sot → docs/sot)
- 📁 新增：治理目录 (.ai-rules/, docs/adr/, docs/runbooks/, docs/releases/)
- 🔧 新增：justfile 统一命令入口
- 📋 更新：7 角色制权限体系 (MASTER.md v4.4)
- 🧹 清理：根目录临时文件，保持 <15 个核心文件
- 📜 新增：ADR 架构决策记录模板
- 🎯 重构：完成文档体系重构为5层分级架构
- 📚 新增：MASTER_SPEC.md 系统根规范（P0优先级）
- 📖 优化：11个SoT文档统一归档至 docs/sot/
- 🗂️ 归档：历史文档版本统一归档至 docs/archive/
- ✨ 新增：DOCS_README.md 完整文档索引
- 🎯 重构：创建项目规则总纲 (.claude/PROJECT_RULES.md)
- 📚 重构：重新组织文档结构 (保留核心文档，新建6大板块)
- ✨ 新增：AI自检清单和开发强制规范
- 📖 完善：各板块README索引文档
- ✨ 新增：完整的充值管理系统
- ✨ 新增：双重审核机制（数据审核+财务审批）
- ✨ 新增：打款凭证管理功能
- ✨ 新增：充值统计分析报表
- 🔧 优化：权限控制和RLS策略
Made with ❤️ by AI Ad Spend Team