2.3 KiB
2.3 KiB
CLAUDE.md — 智能错题本项目 Agent 指令 (v2)
项目信息
- 项目名称: WrongBook (智能错题本)
- 仓库结构: monorepo
backend/— Python FastAPI 后端app/— Flutter 客户端 (MVP: Android + iOS；鸿蒙为占位适配层)miniprogram/— uni-app 微信小程序轻量版infra/— Docker / 部署配置docs/— 设计文档
技术栈 (严格遵守)
- 后端: Python 3.11, FastAPI, SQLAlchemy 2.0 (async), PostgreSQL 16, Redis 7, Celery
- 客户端: Flutter 3.22+, Dart 3.4+, Riverpod, flutter_math_fork, Dio
- 小程序: uni-app (Vue3 + TypeScript)
- AI: Claude Sonnet API (vision), PaddleOCR (可选，缺失时降级规则切分)
- 全文检索: PostgreSQL tsvector (不使用 Elasticsearch)
- 部署: Docker Compose
代码规范
- Python: ruff 格式化, type hints 必须写, docstring 中文
- Dart: flutter_lints, 优先 const 构造函数
- 所有 API 返回统一格式: {"code": 0, "data": {}, "message": ""}
- 错误也走统一格式: {"code": 错误码, "data": null, "message": "描述"}
- 数据库迁移: Alembic
- 环境变量: .env → pydantic Settings
构建/测试命令
- 后端测试:
cd backend && pytest -x -v(需要 Docker 中的 PostgreSQL 可用) - 后端启动:
cd backend && uvicorn app.main:app --reload - 后端 lint:
cd backend && ruff check . - Flutter 构建:
cd app && flutter build apk --debug - Flutter 分析:
cd app && flutter analyze
IMPORTANT 约束 (违反任何一条视为 Bug)
- YOU MUST: 每个文件写完后运行 ruff check (Python) 或 flutter analyze (Dart)
- YOU MUST: 数据库操作一律 async, 禁止同步 ORM
- YOU MUST: Celery task 内调用 async 代码时使用 asyncio.run()
- YOU MUST: 所有外部 API 调用 (Anthropic/RemoveHandwriting) 必须通过接口层+依赖注入, 没有 API key 时测试不能报错
- YOU MUST: 图片存储只存 object_key, 读取时生成 presigned URL, 禁止存裸公开URL
- YOU MUST: WebSocket 连接必须用 JWT 鉴权, 禁止在路径中暴露 user_id
- YOU MUST: Flutter 中平台相关代码必须通过 PlatformService 抽象层
- YOU MUST: AI prompt 模板放在 backend/app/prompts/ 目录, 不硬编码
- YOU MUST: 每完成一个模块立即写单元测试
- YOU MUST: 所有日志使用 structlog, 每条日志带 request_id