ljwx-shiti/README.md

WrongBook - 智能错题本

基于 AI 的智能错题管理系统，支持拍照识别、自动分析、智能复习。

📚 文档导航

• CLAUDE.md - Agent 指令和项目规范
• 构建指令 - 完整的 10 阶段构建指南
• 系统架构 - 技术架构和设计文档
• 风险验证 - 风险点及验证清单
• API 文档 - API 接口文档
• 部署指南 - 部署配置和运维指南

项目结构

ljwx-shiti/
├── backend/          # Python FastAPI 后端
├── app/              # Flutter 客户端
├── miniprogram/      # uni-app 微信小程序
├── infra/            # 基础设施配置
└── docs/             # 文档

技术栈

后端

• Python 3.11
• FastAPI
• SQLAlchemy 2.0 (async)
• PostgreSQL 16
• Redis 7
• Celery
• Claude Sonnet API (vision)
• PaddleOCR (可选)

客户端

• Flutter 3.22+
• Dart 3.4+
• Riverpod
• Dio

小程序

• uni-app
• Vue 3
• TypeScript

快速开始

环境要求

• Docker & Docker Compose
• Python 3.11+
• Flutter 3.22+ (可选，用于客户端开发)
• Node.js 18+ (可选，用于小程序开发)

启动服务

1. 克隆仓库

git clone <repository-url>
cd ljwx-shiti

2. 配置环境变量

cp .env.example .env
# 编辑 .env 文件，填入必要的配置

3. 启动所有服务

docker-compose up -d

4. 运行数据库迁移

cd backend
alembic upgrade head

5. 访问服务

• 后端 API: http://localhost:8000
• API 文档: http://localhost:8000/docs
• MinIO 控制台: http://localhost:49001

开发模式

后端开发

cd backend

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

# 运行测试
pytest -x -v

# 启动开发服务器
uvicorn app.main:app --reload

# 代码检查
ruff check .

Flutter 客户端开发

cd app

# 安装依赖
flutter pub get

# 代码生成
flutter pub run build_runner build --delete-conflicting-outputs

# 运行
flutter run

# 代码检查
flutter analyze

微信小程序开发

cd miniprogram

# 安装依赖
npm install

# 运行开发环境
npm run dev:mp-weixin

核心功能

1. 拍照录题

   • 支持拍照或相册选择
   • 自动去除手写笔迹
   • AI 识别题目内容

2. 智能分析

   • Claude Sonnet 视觉分析
   • 自动提取知识点
   • 难度评估

3. 题目管理

   • 分类浏览
   • 全文搜索
   • 标签管理

4. 智能复习

   • 复习记录
   • 个人笔记
   • 学习统计

API 文档

启动服务后访问 http://localhost:8000/docs 查看完整 API 文档。

主要端点

• POST /api/v1/auth/login - 用户登录
• POST /api/v1/auth/register - 用户注册
• POST /api/v1/questions/ - 创建题目
• GET /api/v1/questions/ - 获取题目列表
• GET /api/v1/questions/{id} - 获取题目详情
• PUT /api/v1/questions/{id} - 更新题目
• DELETE /api/v1/questions/{id} - 删除题目
• GET /api/v1/questions/search - 搜索题目

部署

生产环境部署

1. 更新环境变量

# 设置生产环境配置
export ENV=production
export SECRET_KEY=<your-secret-key>
export DATABASE_URL=<your-database-url>

2. 构建并启动

docker-compose -f docker-compose.prod.yml up -d

3. 配置反向代理 (Nginx)

server {
    listen 80;
    server_name your-domain.com;

    location / {
        proxy_pass http://localhost:8000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

测试

# 后端测试
cd backend
pytest -x -v

# 覆盖率报告
pytest --cov=app --cov-report=html

代码规范

• Python: 使用 ruff 格式化，必须写 type hints
• Dart: 遵循 flutter_lints，优先使用 const 构造函数
• 所有 API 返回统一格式: {"code": 0, "data": {}, "message": ""}
• 数据库操作一律使用 async
• 所有日志使用 structlog，每条日志带 request_id

贡献指南

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

许可证

MIT License

联系方式

• 项目主页:
• 问题反馈: /issues