AI广告代投系统

🚀 项目简介

AI广告代投系统是一个专为Facebook广告代理商设计的智能化广告投放管理平台。通过AI技术和自动化流程,帮助代理商提升投放效率、优化ROI、降低运营成本。

核心特性

• 🤖 AI智能监控 - 账户异常检测、性能预警、寿命预测
• 📊 自动化对账 - 精准的财务对账和差异分析
• 👥 多角色协作 - 投手、运营、财务、管理员协同工作
• 🔒 安全权限控制 - 基于RLS的数据隔离和权限管理
• 📈 实时数据监控 - 消耗、转化、ROI等关键指标实时追踪
• 💰 智能充值管理 - 自动化充值申请和审批流程

核心功能模块

日报管理系统（已实现）

• ✅ 日报创建和管理 - 投手每日提交广告投放数据
• ✅ 审核工作流 - 数据员审核确认，支持通过/驳回
• ✅ 批量导入导出 - 支持Excel文件导入导出
• ✅ 数据统计分析 - 实时统计CPA、ROAS等关键指标
• ✅ 审计日志 - 完整的操作记录追踪

项目管理模块（已实现）

• ✅ 项目CRUD管理 - 完整的项目创建、查询、更新、删除
• ✅ 成员管理 - 灵活的团队成员分配和权限控制
• ✅ 费用记录 - 项目成本追踪和费用管理
• ✅ 统计分析 - 项目数据统计和绩效分析
• ✅ 权限控制 - 基于角色的细粒度访问控制

充值管理模块（已实现）

• ✅ 充值申请管理 - 创建、查询、更新充值申请
• ✅ 双重审核机制 - 数据审核 + 财务审批的完整流程
• ✅ 打款凭证管理 - 支付凭证上传和管理
• ✅ 统计分析报表 - 多维度充值数据分析
• ✅ 资金流程控制 - 完整的资金流转管理

📚 Documentation Center

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

Quick Links

• 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+

安装步骤

1. 克隆项目

git clone https://github.com/wade56754/AI_ad_spend02.git
cd AI_ad_spend02

2. 配置环境变量

cp .env.example .env
# 编辑 .env 文件，配置必要的环境变量

3. 安装依赖

# 后端依赖
pip install -r requirements.txt

# 前端依赖
cd frontend && pnpm install
cd ..

4. 启动数据库

docker-compose up -d postgres redis

5. 运行数据库迁移

cd backend
alembic upgrade head
cd ..

6. 启动服务

# 启动后端 (新终端)
cd backend
uvicorn main:app --reload --port 8000

# 启动前端 (新终端)
cd frontend
pnpm run dev

7. 访问应用

• 前端: 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              # 统一命令入口

🎯 角色权限 (6 角色制)

| 角色 | 核心职责 | 主要功能 | |------|----------|----------| | ceo | 资金安全、公司盈亏 | 最终决策、全局视图、资金审批 | | project_owner | 项目盈亏、资金效率 | 项目管理、预算控制、ROI 分析 | | finance | 资金准确、数据真实 | 财务对账、充值审批、资金核算 | | pitcher | CPL 达标、日报准确 | 投放执行、日报提交、账户操作 | | account_manager | 账户分配、状态监控 | 账户管理、分配调度、异常处理 | | admin | 系统配置（不参与业务） | 用户管理、权限配置、系统维护 |

🧪 测试

# 运行后端测试
pytest

# 运行前端测试
pnpm test

# 运行E2E测试
pnpm run test:e2e

# 查看测试覆盖率
pytest --cov=backend/app

🚢 部署

Docker部署

# 构建镜像
docker build -t ai-ad-spend .

# 使用docker-compose部署
docker-compose up -d

Kubernetes部署

# 应用配置
kubectl apply -f k8s/

# 查看部署状态
kubectl get pods -n ai-ad-spend

详细部署文档请参考 部署指南

🤝 贡献指南

我们欢迎所有形式的贡献！请阅读 贡献指南 了解如何参与项目开发。

开发流程

1. Fork 项目
2. 创建功能分支 (git checkout -b feature/AmazingFeature)
3. 提交更改 (git commit -m 'Add some AmazingFeature')
4. 推送到分支 (git push origin feature/AmazingFeature)
5. 创建 Pull Request

代码规范

后端代码规范

• 遵循 PEP 8 Python代码规范
• 使用 Black + isort 进行代码格式化
• 编写单元测试，确保测试覆盖率

前端代码规范

• TypeScript严格模式，禁止any类型
• 优先使用 shadcn/ui 组件
• 必须通过 ESLint 和 TypeScript 检查
• 提交前检查: pnpm run lint 和 pnpm run type-check 必须0错误

AI协作开发

• 严格遵循 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

---

更新日志:

v4.1.0 (2025-12-27)

• 🏗️ 重构：文档结构重组 (docs/2.sot → docs/sot)
• 📁 新增：治理目录 (.ai-rules/, docs/adr/, docs/runbooks/, docs/releases/)
• 🔧 新增：justfile 统一命令入口
• 📋 更新：7 角色制权限体系 (MASTER.md v4.4)
• 🧹 清理：根目录临时文件，保持 <15 个核心文件
• 📜 新增：ADR 架构决策记录模板

v4.0.0 (2025-11-22)

• 🎯 重构：完成文档体系重构为5层分级架构
• 📚 新增：MASTER_SPEC.md 系统根规范（P0优先级）
• 📖 优化：11个SoT文档统一归档至 docs/sot/
• 🗂️ 归档：历史文档版本统一归档至 docs/archive/
• ✨ 新增：DOCS_README.md 完整文档索引

v3.0.0 (2024-11-18)

• 🎯 重构：创建项目规则总纲 (.claude/PROJECT_RULES.md)
• 📚 重构：重新组织文档结构 (保留核心文档，新建6大板块)
• ✨ 新增：AI自检清单和开发强制规范
• 📖 完善：各板块README索引文档

v2.3.0 (2024-11-12)

• ✨ 新增：完整的充值管理系统
• ✨ 新增：双重审核机制（数据审核+财务审批）
• ✨ 新增：打款凭证管理功能
• ✨ 新增：充值统计分析报表
• 🔧 优化：权限控制和RLS策略

---