Skip to content

DEVELOPMENT.md

Latest commit

 

History

History
291 lines (225 loc) · 7.95 KB

DEVELOPMENT.md

File metadata and controls

291 lines (225 loc) · 7.95 KB

🚀 BINGO知识之象 - 开发指南

项目概述

BINGO知识之象是一个商业级AI驱动的知识可视化平台，专注于为教育工作者和自媒体创作者提供绝对美观、准确实用的概念动画生成服务。

🎯 商业目标

  1. 绝对美观 - 生成专业级视觉效果的概念动画
  2. 准确实用 - 确保知识点准确，符合教学和创作需求
  3. 商业可行 - 建立可持续的商业模式和盈利能力

🏗️ 技术架构

后端技术栈

  • 框架: FastAPI (Python 3.9+)
  • 数据库: PostgreSQL + Redis缓存
  • AI集成: Google Gemini, OpenAI GPT, 自定义模型
  • 任务队列: Celery + Redis
  • 部署: Docker + Kubernetes

前端技术栈

  • 核心: HTML5 + CSS3 + Vanilla JavaScript
  • 样式: TailwindCSS + 自定义设计系统
  • 主题: 克莱因蓝 + Apple风格设计
  • 响应式: 移动优先设计

多风格系统

  • 默认风格: 经典教育动画风格
  • 奢华暗黑: 科技感霓虹效果，钻石质感
  • Aurora红黑: 特斯拉红配黑底，Apple官网风格

📋 开发计划

第一阶段：核心架构升级 (2个月)

  • 项目结构重构和现代化
  • 数据库架构设计和实现
  • AI引擎核心优化
  • 多风格视觉系统实现

第二阶段：商业化功能 (1个月)

  • 用户管理和认证系统
  • 内容质量保障系统
  • 高级导出和分享功能
  • 付费功能和用户分级

第三阶段：性能优化 (1个月)

  • 性能优化和扩展性
  • 监控和分析系统
  • 安全性和合规性
  • 部署和运维

🛠️ 开发环境设置

环境要求

  • Python 3.9+
  • Node.js 16+ (用于前端工具)
  • PostgreSQL 13+
  • Redis 6+
  • Docker & Docker Compose

快速开始

# 1. 克隆项目
git clone https://github.com/your-username/bingo-knowledge-visualization.git
cd bingo-knowledge-visualization

# 2. 创建虚拟环境
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

# 3. 安装依赖
pip install -r requirements.txt

# 4. 设置环境变量
cp .env.example .env
# 编辑 .env 文件，配置数据库和API密钥

# 5. 初始化数据库
python scripts/init_db.py

# 6. 启动开发服务器
python start_app.py

Docker 开发环境

# 启动完整开发环境
docker-compose -f docker-compose.dev.yml up -d

# 查看日志
docker-compose -f docker-compose.dev.yml logs -f

# 停止环境
docker-compose -f docker-compose.dev.yml down

📁 项目结构

BINGO知识之象/
├── README.md                    # 项目说明
├── DEVELOPMENT.md               # 开发指南
├── requirements.txt             # Python依赖
├── docker-compose.yml           # Docker配置
├── .env.example                 # 环境变量模板
├── app.py                       # 主应用程序
├── config/                      # 配置管理
│   ├── settings.py              # 设置管理
│   └── database.py              # 数据库配置
├── src/                         # 源代码
│   ├── models/                  # 数据模型
│   ├── services/                # 业务服务
│   ├── api/                     # API路由
│   └── utils/                   # 工具函数
├── static/                      # 静态资源
│   ├── css/                     # 样式文件
│   ├── js/                      # JavaScript
│   └── images/                  # 图片资源
├── templates/                   # HTML模板
├── tests/                       # 测试文件
├── scripts/                     # 脚本工具
└── docs/                        # 文档

🎨 设计系统

色彩系统

:root {
  /* 主色调 - 克莱因蓝 */
  --klein-blue: #002FA7;
  --klein-blue-light: #0051D5;
  --klein-blue-dark: #001A5C;
  
  /* 奢华暗黑风格 */
  --luxury-bg: linear-gradient(135deg, #0a0a0f 0%, #1a1a2e 50%, #16213e 100%);
  --luxury-accent: #00D4FF, #FFD700, #9D4EDD;
  
  /* Aurora红黑风格 */
  --aurora-bg: #000000;
  --aurora-accent: #E31937;
}

组件规范

  • 按钮: 圆角16px，阴影效果，悬停动画
  • 卡片: 圆角24px，微妙阴影，悬停提升
  • 输入框: 圆角12px，聚焦时蓝色边框
  • 动画: 缓动函数 cubic-bezier(0.25, 0.46, 0.45, 0.94)

🧪 测试策略

测试类型

  • 单元测试: 核心业务逻辑测试
  • 集成测试: API接口和数据库测试
  • 端到端测试: 用户场景完整流程测试
  • 性能测试: 负载和压力测试

运行测试

# 运行所有测试
pytest

# 运行特定测试
pytest tests/test_generation.py

# 运行性能测试
pytest tests/performance/ -v

# 生成测试覆盖率报告
pytest --cov=src --cov-report=html

📊 质量标准

代码质量

  • 测试覆盖率: > 80%
  • 代码复杂度: < 10 (McCabe)
  • 类型检查: 使用 mypy
  • 代码格式: 使用 black + isort

性能标准

  • 响应时间: API < 2秒，页面加载 < 3秒
  • 并发支持: 1000+ 并发用户
  • 可用性: > 99.5%
  • 错误率: < 0.1%

安全标准

  • 认证: JWT + 双因子认证
  • 数据加密: 传输和存储加密
  • 访问控制: RBAC权限模型
  • 安全扫描: 定期漏洞扫描

🚀 部署指南

生产环境部署

# 1. 构建Docker镜像
docker build -t bingo-knowledge-viz:latest .

# 2. 部署到Kubernetes
kubectl apply -f k8s/

# 3. 配置域名和SSL
kubectl apply -f k8s/ingress.yml

# 4. 监控部署状态
kubectl get pods -l app=bingo-web

环境配置

  • 开发环境: 本地开发，热重载
  • 测试环境: 自动化测试，CI/CD
  • 预生产环境: 性能测试，用户验收
  • 生产环境: 高可用，监控告警

📈 监控和分析

性能监控

  • 应用性能: New Relic / DataDog
  • 基础设施: Prometheus + Grafana
  • 日志分析: ELK Stack
  • 错误追踪: Sentry

业务指标

  • 用户增长: DAU, MAU, 注册转化率
  • 功能使用: 生成次数，导出次数
  • 收入指标: MRR, ARPU, 付费转化率
  • 质量指标: 用户满意度，内容准确率

🤝 贡献指南

开发流程

  1. Fork项目 到个人仓库
  2. 创建分支 git checkout -b feature/your-feature
  3. 提交代码 遵循提交规范
  4. 运行测试 确保所有测试通过
  5. 发起PR 详细描述变更内容

提交规范

type(scope): description

feat(auth): add user registration
fix(api): resolve generation timeout issue
docs(readme): update installation guide
style(css): improve button hover effects
refactor(db): optimize query performance
test(unit): add generation engine tests

代码审查

  • 功能正确性: 是否实现预期功能
  • 代码质量: 是否遵循编码规范
  • 性能影响: 是否影响系统性能
  • 安全考虑: 是否存在安全风险
  • 测试覆盖: 是否有足够的测试

📚 学习资源

技术文档

设计资源

AI/ML资源

📞 联系方式

让知识在视觉中绽放，让概念在动画中重生 ✨