ljwx-pages/README.md

错题集应用 (Wrong Question Bank Application)

一个功能强大的错题管理系统，支持OCR识别、手写去除、多维度搜索等高级功能。

✨ 核心功能

• 📸 批量拍照导入 - 支持相机拍照、相册批量选择、PDF导入
• 🔍 智能OCR识别 - 使用PaddleOCR识别中文文字和数学公式
• ✏️ 手写去除 - 自动去除手写笔迹，保留印刷体，方便打印复习
• 🔎 多维度搜索 - 按学科、知识点、难度、题型、来源、错误次数等多维度筛选
• 📊 错误追踪 - 自动记录每道题的错误次数和时间，重点关注高频错题
• 📱 跨平台支持 - iOS、Android、Web、桌面端全平台支持

🚀 快速开始

方式一：一键启动（推荐）

macOS/Linux

./start-dev.sh

Windows

start-dev.bat

方式二：手动启动

1. 启动基础服务

# 启动Docker服务（PostgreSQL, Elasticsearch, MinIO, Redis）
docker-compose up -d

# 等待服务启动
sleep 30

2. 启动后端

cd backend

# 创建虚拟环境（首次）
python3 -m venv venv

# 激活虚拟环境
# macOS/Linux:
source venv/bin/activate
# Windows:
venv\Scripts\activate

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

# 启动后端服务
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

3. 启动前端

cd frontend

# 安装依赖
flutter pub get

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

# 运行应用
flutter run  # 自动选择可用设备

# 或指定平台
flutter run -d ios      # iOS
flutter run -d android  # Android
flutter run -d chrome   # Web浏览器
flutter run -d macos    # macOS桌面

📖 项目结构

ljwx-pages/
├── backend/                      # FastAPI后端
│   ├── app/
│   │   ├── main.py              # 主应用
│   │   ├── config.py            # 配置
│   │   ├── models/              # 数据库模型
│   │   │   └── question_models.py
│   │   ├── schemas/             # Pydantic模型
│   │   │   └── question_schemas.py
│   │   ├── services/            # 业务逻辑
│   │   │   ├── image_pipeline.py    # 图片处理管线
│   │   │   ├── db_service.py        # 数据库服务
│   │   │   ├── search_service.py    # 搜索服务
│   │   │   └── storage_service.py   # 存储服务
│   │   ├── routes/              # API路由
│   │   └── database/            # 数据库配置
│   └── requirements.txt
├── frontend/                     # Flutter前端
│   ├── lib/
│   │   ├── main.dart
│   │   ├── models/              # 数据模型
│   │   │   └── question.dart
│   │   ├── services/            # 服务层
│   │   │   └── api_service.dart
│   │   ├── providers/           # 状态管理
│   │   │   └── question_provider.dart
│   │   ├── screens/             # 页面
│   │   │   ├── home_screen.dart
│   │   │   ├── search_screen.dart
│   │   │   └── import_screen.dart
│   │   └── widgets/             # 通用组件
│   └── pubspec.yaml
├── docker-compose.yml           # Docker配置
├── start-dev.sh                 # 启动脚本(Unix)
├── start-dev.bat                # 启动脚本(Windows)
├── IMPLEMENTATION_STATUS.md     # 实施进度
└── README.md

🛠 技术栈

后端

• 框架: FastAPI 0.104.1
• 数据库: PostgreSQL 16
• 搜索引擎: Elasticsearch 8.11.0
• 对象存储: MinIO
• 缓存: Redis
• OCR: PaddleOCR 2.7.3
• 图像处理: OpenCV 4.8.1

前端

• 框架: Flutter 3.0+
• 状态管理: Riverpod 2.0
• 数据模型: Freezed 2.0
• HTTP客户端: Dio 5.0
• 图片选择: image_picker 1.0

📝 API文档

启动后端后，访问：

• Swagger UI: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc

🔗 服务访问地址

• 后端API: http://localhost:8000
• API文档: http://localhost:8000/docs
• PostgreSQL: localhost:5432
• Elasticsearch: http://localhost:9200
• MinIO控制台: http://localhost:9001 (minioadmin/minioadmin)
• Redis: localhost:6379

📊 实施进度

查看详细的实施进度和待办事项：IMPLEMENTATION_STATUS.md

当前完成度:

• ✅ 后端核心功能: 85%
• ✅ 图片处理: 100%
• ✅ 前端数据层: 100%
• ⏳ 前端UI: 20%

🐛 常见问题

1. Docker服务无法启动

# 检查Docker是否运行
docker info

# 重启Docker服务
docker-compose down
docker-compose up -d

2. PaddleOCR模型下载慢

首次运行时会自动下载OCR模型，如果网络慢，可以手动下载：

mkdir -p backend/models
# 下载模型文件到 backend/models/

3. Flutter代码生成失败

cd frontend
flutter pub run build_runner clean
flutter pub run build_runner build --delete-conflicting-outputs

4. 后端无法连接数据库

检查PostgreSQL是否正常启动：

docker-compose logs postgres

🤝 贡献指南

欢迎提交Issue和Pull Request！

📄 许可证

MIT License

📞 联系方式

• 项目文档: IMPLEMENTATION_STATUS.md
• API文档: http://localhost:8000/docs