Claude 快速上手（5分钟）

本文档帮助 Claude Code 快速了解项目并开始工作。

🔴 新机器/新 clone：先做这三步

本目录 2026-08-28 并入 RB 仓（~/reading-browser/rvh/）。分析和跑测试只需要补 .env； 用 rvh-debug MCP 调试要先把 rvh-debug-mcp/ 装一次（产物 gitignored，clone 里没有）； 构建 Android APK 还需要本机那份 opencv_dart（见下一节）。

缺什么	症状	怎么补
`.env`	运行期读不到 `ENVIRONMENT` / `SUPABASE_URL` 等；`flutter analyze` 报 warning `The asset file '.env' doesn't exist` ⇒ 退出码 1	`cp .env.example .env` 后填值（别提交，`.gitignore` 已挡）
`assets/icons/`（空目录）	`analyze` 报 `asset_directory_does_not_exist`	已由 `assets/icons/.gitkeep` 兜住，不用管
`rvh-debug-mcp/dist/` + `node_modules/`	会话启动时 `rvh-debug (CONNECTION_CLOSED)`，`mcp__rvh-debug__*` 工具全部不可用	`pnpm --dir rvh/rvh-debug-mcp install`（`postinstall: tsc`，装完即构建出 `dist/index.js`）。⚠️ 装完要重启 MCP 才连得上，当前会话内验不到
预装库（仅 Windows clone）	`assets/databases/lampio_dict.db` 是个 40 字节文本而不是 65MB 的 db ⇒ app 起来后预装词一个都没有	那个路径自 2026-08-29（T4-5）起是指向 `src-tauri/assets/lampio_dict.db` 的 symlink（红线 #10：双端只有一份）。git 在 `core.symlinks=false` 的 Windows clone 上会把它落成路径文本 —— `git config --global core.symlinks true` 后重新 clone。macOS / Linux 无此问题

bash

cp .env.example .env && $EDITOR .env
flutter pub get          # 干净 clone 也能过；opencv_dart 从 pub.dev 解析
flutter analyze --no-fatal-infos && flutter test
pnpm --dir rvh-debug-mcp install   # 仓根跑则是 pnpm --dir rvh/rvh-debug-mcp install；之后重启 MCP

构建 Android APK 才需要：本机 opencv_dart + `pubspec_overrides.yaml`

opencv_dart 走的是本机手工改过的版本（src/CMakeLists.txt 关掉 OpenCV 下载、改从本机 dartcv 源码构建；android/build.gradle 只留 arm64-v8a / armeabi-v7a）。这份包按设计不进 git （local_packages/opencv_dart/ 约 100MB，其中 87M 是 CMake 构建缓存、13M 是构建产出的 .so），而且它里面写死了一条本机绝对路径（/Users/larry/Downloads/dartcv-main），原样拷给别人也不能用。

bash

# 源：另一台配好的机器上的 <rvh>/local_packages/opencv_dart（连同那份 dartcv 源码）
mkdir -p local_packages && cp -R <来源>/local_packages/opencv_dart local_packages/
cat > pubspec_overrides.yaml <<'EOF'
dependency_overrides:
  opencv_dart:
    path: local_packages/opencv_dart
EOF
flutter pub get

🔴 2026-08-29（T4-10）之前，那条 override 写在 pubspec.yaml 里，于是整个仓都依赖一个只存在于某台机器上的目录：ci-rvh.yml 的 flutter pub get 因此 exit 66 恒红（自建立起 4 次运行无一绿），干净 clone 也装不起来。现已移进 pubspec_overrides.yaml （本机专属、.gitignore 已挡）。
为什么 analyze / test 不需要它：本地那份与 pub.dev 的 1.4.5 只差上面两个 native 构建文件， pubspec.yaml 与 lib/** 字节相同，Dart API 全部来自共同的 dartcv4: 1.1.8（2026-08-29 逐文件实测）。
⚠️ 装了 pubspec_overrides.yaml 之后，flutter pub get 会把 pubspec.lock 里 opencv_dart 那条从 hosted 改回 path。仓里提交的是 hosted 那版（= CI 与干净 clone 的解析结果），本机这次改写属预期噪音，别提交回去。
🔴 老仓一旦归档（并入计划 T4-9），那份手工改过的 opencv_dart 就只剩你本机这一份了。换机器前先把它连同 dartcv 源码拷出来，或考虑改成可复现的获取方式。

项目状态

版本：v0.5.0-alpha
当前阶段：Phase 4 图像优化
最近完成：背景移除、透视矫正、图像增强、内存管理优化

关键文件位置

核心业务逻辑

OCR 识别流程：

主用例：lib/shared/domain/usecases/recognize_and_filter_usecase.dart
OCR 服务：lib/features/photo_recognition/data/datasources/ocr_local_datasource.dart

图像处理：

裁剪后处理：lib/core/services/post_crop_image_processor.dart
图像增强：lib/core/services/image_quality_enhancer.dart
背景移除：lib/core/services/background_removal_service.dart
边缘检测：lib/core/services/document_edge_detector.dart

词汇过滤：

过滤逻辑：lib/features/vocabulary_filtering/data/repositories/vocabulary_filtering_repository_impl.dart
预装词库：assets/databases/lampio_dict.db（18,916 个词条；导入逻辑在 lib/shared/data/database/app_database.dart）

学习系统：

SM-2 算法：lib/core/algorithms/sm2_algorithm.dart
笔记本管理：lib/features/vocabulary_notebook/data/repositories/notebook_repository_impl.dart

数据库

数据库定义：

Schema 定义：lib/shared/data/database/app_database.dart
迁移脚本：lib/shared/data/database/migrations/

关键表：

vocabulary：词汇表（预置 18,916 词）
notebook_entries：笔记本条目（含 SM-2 算法字段）

UI 页面

主要页面：

拍照识词：lib/features/photo_recognition/presentation/pages/photo_recognition_page.dart
测试入口：lib/features/photo_recognition/presentation/pages/recognize_and_filter_test_page.dart
词汇笔记本：lib/features/vocabulary_notebook/presentation/pages/
学习会话：lib/features/learning_system/presentation/pages/

常用命令

bash

# 运行应用（指定设备）
flutter run -d 24094RAD4C

# 代码检查
flutter analyze

# 运行测试
flutter test

# 清理重建
flutter clean && flutter pub get

# 生成代码（Riverpod、Freezed）
dart run build_runner build --delete-conflicting-outputs

文档导航

只有 6 个核心文档，按需查阅：

文档	内容	何时查看
product.md	指针 → 真相源在仓根 `docs/product.md`	了解产品方向和优先级
design.md	架构+数据模型+UI流程	理解系统设计和数据结构
decisions.md	技术决策记录（4个ADR）	了解为什么选择某项技术
development.md	代码规范+常见问题	开发时遵循规范和解决问题

项目结构速览

lib/
├── main.dart                    # 应用入口
├── core/                        # 核心层
│   ├── algorithms/              # SM-2 算法
│   ├── services/                # 图像处理服务
│   └── utils/                   # 工具类
├── features/                    # 功能模块（7个）
│   ├── photo_recognition/       # 拍照识别
│   ├── vocabulary_filtering/    # 词汇过滤
│   ├── vocabulary_notebook/     # 词汇笔记本
│   ├── reading_tracking/        # 阅读追踪
│   ├── translation/             # 翻译
│   ├── statistics/              # 统计
│   └── settings/                # 设置
└── shared/                      # 共享层
    ├── data/database/           # 数据库
    ├── domain/                  # 共享实体
    └── presentation/            # 共享组件

每个功能模块的标准结构：

features/[module]/
├── domain/
│   ├── entities/               # 业务实体
│   └── repositories/           # 仓储接口
├── data/
│   ├── datasources/            # 数据源实现
│   └── models/                 # 数据模型
└── presentation/
    ├── pages/                  # 页面
    ├── widgets/                # 组件
    └── providers/              # Riverpod Providers

当前待办

查看 docs/plans/backlog.md 了解当前待办与优先级。

技术栈速查

架构：Clean Architecture（Domain/Data/Presentation）
状态管理：Riverpod + riverpod_generator
数据库：SQLite（sqflite，详见 schema.md）
OCR：Google ML Kit（本地） + 百度 OCR（云端）
图像处理：OpenCV Dart（本地修改版）
序列化：Freezed + json_serializable
测试：flutter_test + mockito

快速调试

查看日志：

bash

# Android
adb logcat | grep flutter

# iOS
xcrun simctl spawn booted log stream --predicate 'process == "Runner"'

常见问题快速查询：

OCR 识别问题 → development.md
数据库问题 → development.md
内存泄漏 → development.md
性能优化 → 数据库性能优化

开发流程

新功能开发

查看 product.md 确认功能优先级
参考 design.md 了解架构
遵循 development.md 的代码规范
更新 backlog.md（留下的待办）和 CHANGELOG.md（as-built）

架构变更

在 decisions.md 中记录决策
更新 design.md

性能优化

参考数据库性能优化的基准
优化后更新性能数据

重要提醒

代码规范：

文件命名：小写蛇形（ocr_repository.dart）
类名：大驼峰（VocabularyNotebookPage）
变量：小驼峰（vocabularyName）
私有成员：前缀下划线（_privateMethod）

Git 提交格式：

feat(ocr): 添加百度 OCR 支持

- 集成百度 OCR API
- 添加 API 配置管理

测试要求：

Domain 层覆盖率 100%
Data 层覆盖率 80%
Presentation 层覆盖率 50%

需要帮助？ 查看 development.md 的常见问题章节。

最后更新：2025-12-28

Claude 快速上手（5分钟） ​

🔴 新机器/新 clone：先做这三步 ​

构建 Android APK 才需要：本机 opencv_dart + pubspec_overrides.yaml ​

项目状态 ​

关键文件位置 ​

核心业务逻辑 ​

数据库 ​

UI 页面 ​

常用命令 ​

文档导航 ​

项目结构速览 ​

当前待办 ​

技术栈速查 ​

快速调试 ​

开发流程 ​

新功能开发 ​

架构变更 ​

性能优化 ​

重要提醒 ​

Claude 快速上手（5分钟）

🔴 新机器/新 clone：先做这三步

构建 Android APK 才需要：本机 opencv_dart + `pubspec_overrides.yaml`

项目状态

关键文件位置

核心业务逻辑

数据库

UI 页面

常用命令

文档导航

项目结构速览

当前待办

技术栈速查

快速调试

开发流程

新功能开发

架构变更

性能优化

重要提醒