Skip to content
BranchesTags

Repository files navigation

Mistake Manager

Local-first mistake management app for students.
Desktop-first architecture with Tauri + React + TypeScript, with a web fallback for development.

English

1) Overview

Mistake Manager helps students capture, organize, review, and analyze wrong questions:

  • Create / edit / delete mistake records
  • Upload images and run OCR (cloud-first + local fallback)
  • Manage by subject, date, tags, mastery status, and error reason
  • Chat with AI based on current problem context
  • Generate explanation, step-by-step solution, variations, and harder exercises
  • View statistics dashboards (subject/status/trends/error reasons)
  • Work offline with local persistence

2) Tech Stack

  • Desktop: Tauri v2 (Rust backend)
  • Frontend: React + TypeScript + Vite + React Router
  • UI: Tailwind CSS + shadcn-style components + Radix UI
  • State: Zustand
  • Validation: Zod + react-hook-form
  • Formula rendering: KaTeX
  • Charts: Recharts
  • OCR: Cloud model OCR + tesseract.js fallback
  • Local data:
    • Tauri mode: SQLite (Rust commands via invoke)
    • Web dev mode: localStorage fallback

3) Main Features

  • Problem management:
    • title / question / answer / analysis / notes
    • my thoughts / error analysis / correct method summary
    • status (已弄懂, 不懂, 没看, 待复习)
    • tags / error reasons / image paths / OCR raw text / AI explanation
  • AI provider abstraction:
    • OpenAI, Qwen, Doubao, Gemini, Grok, Claude
    • unified interface, timeout/retry, provider switching
  • Study workflow:
    • today review queue
    • review count and last review time
    • batch OCR draft import and manual review before save
  • Data lifecycle:
    • JSON export/import
    • SQLite backup/restore (Tauri mode)
  • Theme:
    • system / light / dark, persisted locally

4) Project Structure

.
├─ src/
│  ├─ app/                # app entry + router
│  ├─ components/         # UI and feature components
│  ├─ pages/              # dashboard/list/detail/stats/settings
│  ├─ services/           # AI layer, data layer, settings, import/export
│  ├─ store/              # Zustand stores
│  ├─ types/              # shared types
│  └─ mocks/              # seed/mock data
├─ src-tauri/             # Tauri + Rust + SQLite commands
├─ .env.example
└─ README.md

5) Prerequisites

  • Node.js >= 20
  • Package manager:
    • Recommended: pnpm
    • Alternative: npm
  • For Tauri desktop mode:
    • Rust toolchain
    • Tauri platform prerequisites for your OS

6) Installation

Option A: pnpm (recommended)

pnpm install

Option B: npm

npm install

If pnpm is not recognized in Windows:

npm install -g pnpm
pnpm -v

Then reopen terminal and run pnpm install.

7) Environment Variables

  1. Copy env template:
cp .env.example .env

On Windows PowerShell:

Copy-Item .env.example .env
  1. Fill API keys in .env (at least one provider):
  • VITE_OPENAI_API_KEY
  • VITE_QWEN_API_KEY
  • VITE_DOUBAO_API_KEY
  • VITE_GEMINI_API_KEY
  • VITE_GROK_API_KEY
  • VITE_CLAUDE_API_KEY

Optional provider settings:

  • VITE_<PROVIDER>_BASE_URL
  • VITE_<PROVIDER>_MODEL
  • VITE_DOUBAO_APP_ID
  • VITE_AI_TIMEOUT_MS

8) Run the App

Web development mode (no Rust required)

pnpm dev
# or
npm run dev

Default URL: http://localhost:1420

Tauri desktop mode

pnpm tauri:dev
# or
npm run tauri:dev

9) Build

Frontend production build

pnpm build
# or
npm run build

Desktop package (Tauri)

pnpm tauri:build
# or
npm run tauri:build

10) Tests and Quality

pnpm check
pnpm lint
pnpm test

Equivalent npm commands:

npm run check
npm run lint
npm run test

11) API Key & Provider Setup in UI

  1. Open app and go to Settings
  2. In Provider API configuration:
    • choose provider
    • input API key
    • configure base URL/model/timeout if needed
  3. Set current active provider
  4. Go to problem detail and test AI explanation/chat

12) Data Storage Notes

  • Tauri mode:
    • Main data in local SQLite
    • Supports DB backup and restore
  • Web mode:
    • localStorage fallback for local-first development
  • Import/export:
    • JSON import/export supported in both modes

13) Common Issues

  • pnpm command not found:
    • install globally via npm install -g pnpm
  • Gemini 429 RESOURCE_EXHAUSTED:
    • your quota is exceeded or unavailable for current model/project
    • switch provider in Settings or check billing/quota
  • OCR cloud fails:
    • app falls back to local Tesseract automatically
  • Tauri startup fails:
    • verify Rust + platform prerequisites are installed

中文

1）项目简介

Mistake Manager 是一个本地优先（local-first）的错题管理程序，面向学生的完整错题学习闭环：

  • 录入 / 编辑 / 删除错题
  • 上传题图并 OCR 识别
  • 按科目、日期、标签、状态、错因筛选
  • 基于当前题目上下文进行 AI 对话与讲解
  • 生成举一反三变式题与难度提升练习
  • 统计分析（科目分布、状态分布、趋势、错因）
  • 支持离线查看与本地持久化

2）技术栈

  • 桌面端：Tauri v2（Rust 后端）
  • 前端：React + TypeScript + Vite + React Router
  • UI：Tailwind CSS + shadcn 风格组件 + Radix UI
  • 状态管理：Zustand
  • 表单校验：Zod + react-hook-form
  • 数学公式渲染：KaTeX
  • 图表：Recharts
  • OCR：云端模型优先，本地 tesseract.js 回退
  • 本地存储：
    • Tauri 模式：SQLite
    • Web 调试模式：localStorage fallback

3）核心能力

  • 错题字段完整：
    • 标题、题干、答案、解析、备注
    • 我的思路、错因分析、正确解法总结
    • 标签、错因、图片路径、OCR 原文、AI 解析
    • 掌握状态（已弄懂/不懂/没看/待复习）
  • 统一模型适配层：
    • OpenAI / Qwen / 豆包 / Gemini / Grok / Claude
    • 统一接口、超时、重试、错误处理
  • 学习流程：
    • 今日待复习
    • 复习次数、最近复习时间
    • 批量 OCR 草稿导入（先审核后入库）
  • 数据能力：
    • JSON 导入导出
    • SQLite 备份恢复（Tauri）
  • 主题能力：
    • system / light / dark，且本地持久化

4）目录结构

.
├─ src/
│  ├─ app/                # 应用入口与路由
│  ├─ components/         # UI 与功能组件
│  ├─ pages/              # 仪表盘/列表/详情/统计/设置
│  ├─ services/           # AI 层、数据层、设置、导入导出
│  ├─ store/              # Zustand 状态
│  ├─ types/              # 共享类型定义
│  └─ mocks/              # 初始化 mock 数据
├─ src-tauri/             # Tauri + Rust + SQLite 命令层
├─ .env.example
└─ README.md

5）环境准备

  • Node.js >= 20
  • 包管理器：
    • 推荐：pnpm
    • 可选：npm
  • 若要运行桌面端（Tauri）：
    • 安装 Rust toolchain
    • 安装 Tauri 对应平台依赖

6）安装依赖

方案 A：pnpm（推荐）

pnpm install

方案 B：npm

npm install

如果 Windows 下提示 'pnpm' 不是内部或外部命令：

npm install -g pnpm
pnpm -v

然后重开终端再执行 pnpm install。

7）环境变量配置

  1. 复制模板：
cp .env.example .env

PowerShell：

Copy-Item .env.example .env
  1. 在 .env 填入至少一个可用模型 Key：
  • VITE_OPENAI_API_KEY
  • VITE_QWEN_API_KEY
  • VITE_DOUBAO_API_KEY
  • VITE_GEMINI_API_KEY
  • VITE_GROK_API_KEY
  • VITE_CLAUDE_API_KEY

可选项：

  • VITE_<PROVIDER>_BASE_URL
  • VITE_<PROVIDER>_MODEL
  • VITE_DOUBAO_APP_ID
  • VITE_AI_TIMEOUT_MS

8）运行项目

Web 开发模式（不依赖 Rust）

pnpm dev
# 或 npm run dev

默认地址：http://localhost:1420

Tauri 桌面模式

pnpm tauri:dev
# 或 npm run tauri:dev

9）打包发布

前端构建：

pnpm build
# 或 npm run build

桌面打包：

pnpm tauri:build
# 或 npm run tauri:build

10）测试与质量检查

pnpm check
pnpm lint
pnpm test

或：

npm run check
npm run lint
npm run test

11）在界面中配置 API

  1. 打开应用进入 设置页
  2. 在 Provider API 配置 中：
    • 选择模型提供商
    • 填写 API Key
    • 按需设置 Base URL / Model / Timeout
  3. 设定当前默认 provider
  4. 到错题详情页测试 AI 讲解 / 对话

12）本地数据说明

  • Tauri 模式：
    • 主数据存储于本地 SQLite
    • 支持数据库备份导出与恢复
  • Web 模式：
    • 使用 localStorage fallback
  • 导入导出：
    • 支持 JSON 导入导出

13）常见问题

  • pnpm 命令找不到：
    • 执行 npm install -g pnpm 并重开终端
  • Gemini 报错 429 RESOURCE_EXHAUSTED：
    • 当前项目配额不足/为 0，或模型限额不足
    • 请在设置中切换其他 provider，或检查 Gemini 配额与计费
  • 云端 OCR 失败：
    • 会自动回退到本地 Tesseract
  • Tauri 启动失败：
    • 优先检查 Rust 与平台依赖是否安装完整

About

a mistake-manager

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages