ljwx-shiti/docs/BUILD_INSTRUCTIONS.md

智能错题本项目 - 完整构建指令（10阶段）

执行说明

这是一份完整的、可自动执行的项目构建指令。严格按照以下 10 个阶段从零构建整个项目。

全局执行规则（贯穿所有阶段）

1. 每个阶段完成后: 运行验证命令 → git add -A → git commit → 输出 "✅ Stage N/10 完成" → 立即进入下一阶段
2. 遇到错误: 自行诊断修复, 修复后继续, 不要停下来问我
3. 遇到依赖安装失败: 降级版本或标记为可选, 确保构建不中断
4. 所有代码必须符合 CLAUDE.md 中的 IMPORTANT 约束
5. 每个 Python 文件写完立即 ruff check --fix
6. 每个 Dart 文件写完立即 dart format
7. 最终目标: 10个阶段全部完成, docker compose up -d 能启动完整服务

---

STAGE 1/10: 项目脚手架 + 基础配置

目标

创建项目基础目录结构、配置文件和核心模块。

目录结构

wrongbook/
├── CLAUDE.md                  (已存在)
├── .gitignore                 (Python + Flutter + Node + Docker + .env)
├── .env.example               (环境变量模板)
├── .env                       (从 .env.example 复制)
├── docker-compose.yml
├── backend/
│   ├── pyproject.toml
│   ├── alembic.ini
│   ├── alembic/
│   │   ├── env.py
│   │   └── versions/         (空目录)
│   ├── app/
│   │   ├── __init__.py
│   │   ├── main.py
│   │   ├── config.py
│   │   ├── database.py
│   │   ├── redis_client.py
│   │   ├── storage.py
│   │   ├── middleware.py      (统一响应+request_id+全局异常)
│   │   ├── dependencies.py   (通用依赖注入)
│   │   ├── logger.py         (structlog 配置)
│   │   ├── models/
│   │   │   ├── __init__.py
│   │   │   └── base.py
│   │   ├── schemas/
│   │   │   ├── __init__.py
│   │   │   └── common.py     (ApiResponse 统一响应模型)
│   │   ├── api/
│   │   │   ├── __init__.py
│   │   │   └── router.py
│   │   ├── services/
│   │   │   └── __init__.py
│   │   ├── prompts/
│   │   │   └── __init__.py
│   │   └── utils/
│   │       └── __init__.py
│   └── tests/
│       ├── __init__.py
│       ├── conftest.py
│       └── fixtures/          (测试用图片等)
├── app/
│   └── .gitkeep
├── miniprogram/
│   └── .gitkeep
├── infra/
│   ├── init.sql
│   └── .gitkeep
└── docs/
    └── architecture.md

docker-compose.yml 要求

services:
  postgres:
    image: postgres:16-alpine
    ports: ["5432:5432"]
    environment:
      POSTGRES_DB: wrongbook
      POSTGRES_USER: wrongbook
      POSTGRES_PASSWORD: wrongbook
    volumes:
      - pgdata:/var/lib/postgresql/data
      - ./infra/init.sql:/docker-entrypoint-initdb.d/init.sql
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U wrongbook"]
      interval: 5s
      timeout: 5s
      retries: 5

  postgres-test:
    image: postgres:16-alpine
    ports: ["5433:5432"]
    environment:
      POSTGRES_DB: wrongbook_test
      POSTGRES_USER: wrongbook
      POSTGRES_PASSWORD: wrongbook
    tmpfs: /var/lib/postgresql/data

  redis:
    image: redis:7-alpine
    ports: ["6379:6379"]
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]

  minio:
    image: minio/minio
    command: server /data --console-address ":9001"
    ports: ["9000:9000", "9001:9001"]
    environment:
      MINIO_ROOT_USER: minioadmin
      MINIO_ROOT_PASSWORD: minioadmin
    volumes:
      - miniodata:/data

volumes:
  pgdata:
  miniodata:

infra/init.sql

-- 启用扩展
CREATE EXTENSION IF NOT EXISTS "pg_trgm";   -- 模糊搜索
CREATE EXTENSION IF NOT EXISTS "ltree";     -- 树形路径

pyproject.toml 核心要求

[project]
name = "wrongbook-backend"
version = "0.1.0"
requires-python = ">=3.11,<3.13"
dependencies = [
    "fastapi>=0.115.0",
    "uvicorn[standard]>=0.30.0",
    "sqlalchemy[asyncio]>=2.0.30",
    "asyncpg>=0.29.0",
    "alembic>=1.13.0",
    "redis>=5.0.0",
    "celery[redis]>=5.4.0",
    "httpx>=0.27.0",
    "pydantic>=2.7.0",
    "pydantic-settings>=2.3.0",
    "python-multipart>=0.0.9",
    "python-jose[cryptography]>=3.3.0",
    "Pillow>=10.3.0",
    "opencv-python-headless>=4.9.0",
    "numpy>=1.26.0",
    "structlog>=24.1.0",
    "minio>=7.2.0",
]

[project.optional-dependencies]
paddle = [
    "paddlepaddle>=2.6.0",
    "paddleocr>=2.7.0",
]
dev = [
    "pytest>=8.2.0",
    "pytest-asyncio>=0.23.0",
    "httpx>=0.27.0",
    "ruff>=0.4.0",
    "testcontainers[postgres]>=4.4.0",
]

验证命令

docker compose up -d postgres postgres-test redis minio
cd backend
pip install -e ".[dev]"
ruff check .
python -c "from app.main import app; print('FastAPI app OK')"
python -c "from app.config import settings; print(f'DB: {settings.DATABASE_URL}')"
git init && git add -A && git commit -m "Stage 1: project scaffold with unified middleware and test DB"

---

STAGE 2/10: 数据库模型 + 迁移

目标

创建所有 ORM 模型和数据库迁移。

模型清单

1. base.py — Base 类 + 通用 Mixin
2. user.py — User
3. subject.py — Subject
4. knowledge_tag.py — KnowledgeTag (树形结构)
5. exam_paper.py — ExamPaper
6. wrong_question.py — WrongQuestion (核心表)
7. review_log.py — ReviewLog
8. question_book.py — QuestionBook + BookQuestion
9. ai_invocation_log.py — AiInvocationLog (AI 可追溯)

关键索引

WrongQuestion 表索引：

• Index('ix_wq_user_subject', user_id, subject_id)
• Index('ix_wq_knowledge', knowledge_tags, postgresql_using='gin')
• Index('ix_wq_custom_tags', custom_tags, postgresql_using='gin')
• Index('ix_wq_review', user_id, next_review_at)
• Index('ix_wq_created', user_id, text('created_at DESC'))

验证命令

cd backend && alembic revision --autogenerate -m "initial_models"
cd backend && alembic upgrade head
cd backend && python -c "from app.models import *; print('All models OK')"
cd backend && ruff check .
git add -A && git commit -m "Stage 2: database models with AI traceability"

---

STAGE 3/10: 用户认证 + 统一响应 + 基础API

目标

实现 JWT 认证、统一响应格式、基础 API 端点。

核心文件

1. schemas/common.py — ApiResponse 统一响应模型
2. auth.py — JWT 认证
3. api/auth.py — 登录/刷新端点
4. api/users.py — 用户信息端点
5. api/subjects.py — 学科列表端点
6. seed.py — 种子数据

API 端点

• POST /api/v1/auth/login
• POST /api/v1/auth/refresh
• GET /api/v1/users/me
• PUT /api/v1/users/me
• GET /api/v1/subjects

验证命令

cd backend && ruff check .
cd backend && pytest tests/test_auth.py -v
git add -A && git commit -m "Stage 3: auth, unified response, base API"

---

STAGE 4/10: Layer 1 题块切分 + Layer 2 错题召回

目标

实现图片预处理、题块切分（规则+PaddleOCR可选）、错题召回评分。

核心服务

1. image_preprocessor.py — 图片预处理（纯 OpenCV）
2. block_cutter.py — 题块切分器（规则降级）
3. error_recaller.py — 错题召回评分

关键特性

• PaddleOCR 为可选依赖
• 必须有纯规则降级路径
• 红色标记检测（HSV）
• 评分信号：✗ 符号、红色面积、负分标注等

验证命令

cd backend && ruff check .
cd backend && pytest tests/test_block_cutter.py tests/test_error_recaller.py -v
git add -A && git commit -m "Stage 4: block cutter (with paddle optional) and error recall"

---

STAGE 5/10: Layer 3 Sonnet 识别 + Layer 4 解析 + AI 可追溯

目标

实现 Claude Sonnet API 调用、题目识别、解析、AI 调用追溯。

核心服务

1. ai_client.py — AI 调用抽象层（可 mock）
2. prompts/recognition_prompt.py — 识别 prompt
3. prompts/analysis_prompt.py — 解析 prompt
4. prompts/verification_prompt.py — 校对 prompt
5. sonnet_recognizer.py — Sonnet 识别器
6. sonnet_analyzer.py — Sonnet 解析器
7. handwriting_cleaner.py — 手写清除
8. ai_trace.py — AI 调用追溯

关键特性

• 所有 AI 调用可 mock
• 双图输入（原图+增强图）
• 两段式调用（校对+解析）
• AI 调用记录到 ai_invocation_logs 表

验证命令

cd backend && ruff check .
cd backend && pytest tests/ -v
git add -A && git commit -m "Stage 5: Sonnet recognition/analysis with AI traceability"

---

STAGE 6/10: 错题管理 API (CRUD + 搜索 + 复习)

目标

实现错题的完整 CRUD、高级搜索、复习功能。

API 端点

papers.py:

• POST /api/v1/papers/upload
• GET /api/v1/papers/{id}
• GET /api/v1/papers/{id}/recall
• POST /api/v1/papers/{id}/confirm

questions.py:

• POST /api/v1/questions/search
• GET /api/v1/questions/{id}
• PUT /api/v1/questions/{id}
• PUT /api/v1/questions/{id}/star
• PUT /api/v1/questions/{id}/archive
• DELETE /api/v1/questions/{id}
• GET /api/v1/questions/stats

books.py:

• CRUD + 添加/移除错题

review.py:

• GET /api/v1/review/today
• POST /api/v1/review/{question_id}

关键特性

• PostgreSQL 全文检索（tsvector）
• ARRAY overlap 查询
• SM-2 改进版复习算法
• presigned URL 返回

验证命令

cd backend && ruff check .
cd backend && pytest tests/ -v
git add -A && git commit -m "Stage 6: question CRUD, search, review API"

---

STAGE 7/10: Celery 异步任务 + WebSocket 通知

目标

实现 Celery 异步任务处理、WebSocket 实时通知（JWT 鉴权）。

核心文件

1. celery_app.py — Celery 配置
2. tasks.py — 异步任务
   • process_paper_stage1（切题+召回）
   • process_paper_stage2（识别+解析+入库）
3. websocket.py — WebSocket 端点（JWT 鉴权）

关键特性

• Celery task 内正确调用 async 代码（asyncio.run()）
• WebSocket 使用 JWT query param 鉴权
• Redis pubsub 通知机制

验证命令

cd backend && ruff check .
cd backend && pytest tests/ -v
git add -A && git commit -m "Stage 7: Celery async-safe tasks + JWT WebSocket"

---

STAGE 8/10: Flutter App

目标

创建 Flutter 客户端骨架和核心页面。

目录结构

app/lib/
├── main.dart
├── app.dart
├── core/
│   ├── config/
│   ├── network/
│   ├── platform/
│   ├── storage/
│   └── theme/
├── features/
│   ├── auth/
│   ├── scan/
│   ├── questions/
│   ├── review/
│   ├── books/
│   ├── stats/
│   └── home/
└── widgets/

关键特性

• 只声明 android + ios 平台
• HarmonyOS 适配作为占位
• PlatformService 抽象层
• LaTeX 渲染（flutter_math_fork）
• WebSocket 实时通知

验证命令

cd app && flutter pub get
cd app && flutter analyze
cd app && flutter test
git add -A && git commit -m "Stage 8: Flutter app skeleton with core pages"

---

STAGE 9/10: uni-app 微信小程序

目标

创建 uni-app 微信小程序轻量版。

目录结构

miniprogram/src/
├── pages/
│   ├── index/
│   ├── login/
│   ├── questions/
│   └── scan/
├── utils/
├── store/
├── App.vue
├── main.ts
├── pages.json
└── manifest.json

关键特性

• Vue 3 + TypeScript
• 微信登录
• 图片上传
• 简化版错题列表和详情

后端新增接口

• POST /api/v1/auth/wx-login
• GET /api/v1/questions/{id}/analysis-image

验证命令

cd miniprogram && npm install
cd miniprogram && npx tsc --noEmit || echo "TS check done"
cd backend && ruff check .
cd backend && pytest tests/ -v
git add -A && git commit -m "Stage 9: uni-app mini program lite version"

---

STAGE 10/10: Docker 部署 + 集成测试 + 文档

目标

完成 Docker 部署配置、集成测试、完整文档。

核心文件

1. backend/Dockerfile
2. backend/Dockerfile.worker
3. docker-compose.yml（更新）
4. tests/test_integration.py
5. docs/api-reference.md
6. README.md
7. docs/architecture.md

验证命令

cd backend && ruff check .
cd backend && pytest tests/ -v
docker compose build
docker compose up -d
sleep 10
curl -s http://localhost:8000/docs | head -5
docker compose down
git add -A && git commit -m "Stage 10: Docker deployment, integration tests, docs"

---

完成标志

全部 10 个阶段完成后，输出：

🎉 智能错题本项目 v2 全部 10 阶段构建完成！

并输出：

1. 最终的完整目录树
2. 全部 API endpoint 汇总
3. 已知的 TODO/限制列表

---

风险验证矩阵

原风险	修订措施	验证方法
Python+PaddleOCR	Python 3.11 + paddle 可选extra	pip install -e "." 不含paddle也能成功
测试DB	docker-compose postgres-test:5433	pytest 连接5433端口运行真实PG测试
Celery+async	sync_wrapper + asyncio.new_event_loop	test_tasks.py 验证 task 能正确调用async
WS鉴权	/ws?token=xxx + JWT校验	test_websocket.py: 无token→拒绝
ES形同虚设	删除ES, 用PG tsvector	keyword搜索测试用tsvector验证
Flutter鸿蒙	鸿蒙占位不阻断	flutter analyze 在 android+ios 通过
AI可追溯	ai_invocation_logs 表	每次AI调用写入log
全局异常	middleware + exception handlers	所有错误返回统一格式
存储安全	object_key + presigned URL	API返回presigned URL而非裸地址