# todo-list

**Repository Path**: bopha/todo-list

## Basic Information

- **Project Name**: todo-list
- **Description**: 这是一个 Windows 11 单体备忘录/代办应用，技术栈是 Tauri 2 + React + TypeScript + SQLite。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-10
- **Last Updated**: 2026-06-10

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 备忘录代办 memo-todo

`memo-todo` 是一个本地优先的桌面备忘录/代办应用，窗口标题为 **备忘录代办**。项目基于 **Tauri 2 + React 19 + TypeScript + Rust + SQLite** 构建，适合用于管理当天任务、标签分组、月度完成情况和本地待办数据。

应用重点面向 Windows 桌面环境：前端负责交互界面，Tauri/Rust 后端负责本地 SQLite 数据持久化。为了方便单独调试前端，项目也支持在普通浏览器 Vite 开发模式下运行，此时会自动回退到 `localStorage` 模拟数据接口。

## 项目功能

### 今日待办

- 查看今日未完成任务。
- 查看今日已完成任务。
- 新建任务。
- 编辑任务标题、描述、日期和标签。
- 完成任务与取消完成。
- 删除任务，删除采用软删除方式，不直接物理移除数据。

### 标签管理

- 创建、编辑、删除标签。
- 任务支持绑定单个标签。
- 今日待办可按标签分组展示。
- 默认初始化四个常用标签：
  - 重要且紧急
  - 重要不紧急
  - 不重要但紧急
  - 不重要不紧急

### 月总览

- 按月份查看每天已完成任务数量。
- 点击具体日期查看当天完成清单。
- 月总览使用更宽的窗口布局，便于展示日历和任务列表。

### 自动延期

- 应用启动或刷新数据时会触发过期任务检查。
- 所有 `active` 状态且 `due_date < today` 的任务会自动延期到今天。
- 延期记录会写入 `postponements` 表，便于后续追踪。

### 设置页

- 自动延期相关设置。
- 主题设置：`system`、`light`、`dark`。
- 查看本地数据库路径。

### 本地数据存储

- Tauri 桌面模式使用 SQLite 数据库。
- 浏览器开发模式使用 `localStorage` 模拟数据。
- SQLite 运行时数据库文件不应提交到 Git 仓库。

## 技术栈

### 桌面端与后端

- [Tauri 2](https://tauri.app/)：桌面应用容器。
- Rust 2021 edition：本地后端逻辑。
- SQLite：本地数据库。
- `rusqlite`：Rust SQLite 访问库，启用 `bundled` 特性。
- `serde` / `serde_json`：前后端数据序列化。
- `chrono`：日期时间处理。
- `uuid`：ID 生成。
- `tauri-plugin-log`：日志插件。

### 前端

- React 19：前端 UI 框架。
- TypeScript：类型系统。
- Vite 8：开发服务器与构建工具。
- Tailwind CSS 4：样式能力接入；当前界面主要使用项目内 CSS class。
- `date-fns`：日期处理。
- `lucide-react`：图标。
- `zod`：数据校验能力。
- `zustand`：状态管理依赖。
- ESLint：代码检查。

## 目录结构

```text
.
├── package.json                  # 前端脚本、依赖与 Tauri CLI 命令
├── package-lock.json             # npm 锁文件，建议提交
├── README.md                     # 项目说明文档
├── CLAUDE.md                     # 给 Claude Code 的项目开发说明
├── vite.config.ts                # Vite 配置
├── eslint.config.js              # ESLint 配置
├── tsconfig.json                 # TypeScript 配置入口
├── public/                       # 静态资源
├── src/                          # React 前端源码
│   ├── main.tsx                  # 前端入口
│   ├── App.tsx                   # 应用主界面、视图切换、窗口尺寸控制
│   ├── App.css                   # 主要界面样式
│   ├── index.css                 # 全局样式与 Tailwind 接入
│   ├── components/               # 通用组件
│   ├── routes/                   # 页面视图
│   └── lib/
│       ├── api.ts                # 前端 API 门面：Tauri invoke 与浏览器回退
│       ├── localApi.ts           # 浏览器模式 localStorage 模拟实现
│       ├── date.ts               # 日期工具
│       └── types.ts              # 前端共享类型
└── src-tauri/                    # Tauri / Rust 后端
    ├── Cargo.toml                # Rust 依赖与包配置
    ├── Cargo.lock                # Rust 锁文件，应用项目建议提交
    ├── tauri.conf.json           # Tauri 应用配置
    ├── build.rs                  # Tauri 构建脚本
    └── src/
        ├── main.rs               # Tauri 程序入口
        ├── lib.rs                # Tauri 初始化、插件、状态和命令注册
        ├── db.rs                 # SQLite 初始化、查询和业务规则
        ├── models.rs             # Rust 数据结构和 serde 模型
        ├── commands/             # Tauri command 层
        └── migrations/
            └── 001_init.sql      # SQLite 初始化 schema
```

## 开发与编译基础环境

建议在 Windows 10/11 或 Windows 11 环境下开发和打包。

### 必需环境

1. **Node.js LTS**
   - 用于运行 Vite、React、TypeScript 和 Tauri CLI。
   - 建议使用当前 LTS 版本。

2. **npm**
   - 项目当前使用 `package-lock.json`，推荐使用 npm 安装依赖。

3. **Rust stable 与 Cargo**
   - 用于编译 Tauri 后端和 Rust 依赖。
   - `src-tauri/Cargo.toml` 当前声明 `rust-version = "1.77.2"`。

4. **Visual Studio Build Tools / Visual Studio C++ 工具链**
   - Windows 上编译 Rust/Tauri 需要 MSVC C++ 构建工具。
   - 需要安装 Windows SDK。

5. **WebView2 Runtime**
   - Tauri 在 Windows 上依赖 WebView2。
   - Windows 11 通常已经内置；如果缺失，需要从 Microsoft 官方安装。

### 环境检查命令

```bash
node -v
npm -v
rustc -V
cargo -V
npm run tauri -- info
```

如果 `npm run tauri -- info` 报告缺少 MSVC、Windows SDK 或 WebView2，请先补齐系统依赖后再运行 Tauri 开发或打包命令。

## 前置知识

如果你希望继续开发这个项目，建议具备以下基础知识：

- TypeScript 基础：类型、接口、泛型、模块导入导出。
- React 基础：组件、props、state、事件处理、条件渲染。
- Vite 基础：开发服务器、生产构建、环境差异。
- Tauri 基础：前端通过 `invoke()` 调用 Rust commands。
- Rust 基础：结构体、枚举、Result、错误处理、模块系统。
- SQLite 基础：表结构、索引、增删改查、外键关系。
- Git 基础：初始化仓库、提交、分支、远程仓库、推送。

## 安装依赖

```bash
npm install
```

## 本地开发

### 仅运行前端浏览器模式

```bash
npm run dev
```

浏览器模式适合调试 UI，不需要启动 Rust/Tauri 后端。此模式下：

- `src/lib/api.ts` 会检测当前不在 Tauri 环境中。
- API 会自动回退到 `src/lib/localApi.ts`。
- 数据保存在浏览器 `localStorage` 中。
- localStorage key 为 `memo-todo-local-dev`。

### 运行 Tauri 桌面开发模式

```bash
npm run tauri:dev
```

此模式会启动真实桌面应用：

- 前端由 Vite 提供开发服务。
- 桌面窗口由 Tauri 打开。
- 数据通过 Rust 后端写入本地 SQLite。
- 窗口标题为 `备忘录代办`。

## 构建与打包

### 构建前端

```bash
npm run build
```

该命令会执行：

```bash
tsc -b && vite build
```

用于检查 TypeScript 并生成前端生产构建产物。

### 打包桌面应用

```bash
npm run tauri:build
```

该命令会执行 Tauri 打包流程。Tauri 配置位于：

```text
src-tauri/tauri.conf.json
```

当前关键配置：

- `productName`: `memo-todo`
- `identifier`: `com.bopha.memotodo`
- `devUrl`: `http://localhost:5173`
- `frontendDist`: `../dist`
- 窗口标题：`备忘录代办`
- 默认窗口尺寸：`520 x 760`

打包产物通常位于 `src-tauri/target/`，该目录属于构建产物，不应提交到 Git。

## 代码检查

```bash
npm run lint
```

当前项目未配置单元测试脚本，请不要假设存在 `npm test`。

## 数据库说明

桌面模式使用 SQLite 本地数据库。

- 数据库文件名：`memo-todo.sqlite3`
- 数据库创建位置：Tauri app data 目录
- 初始化 schema：`src-tauri/src/migrations/001_init.sql`
- 数据访问与业务规则：`src-tauri/src/db.rs`

主要表：

- `tasks`：任务主表。
- `tags`：标签表。
- `task_tags`：任务与标签关系表；当前每个任务最多绑定一个标签。
- `postponements`：延期记录表。
- `settings`：设置表。

运行时数据库、SQLite WAL/SHM 文件、本地 `.db` 文件都不应提交到 Git。数据库结构应通过迁移 SQL 文件提交。

## Git 初始化与推送

首次推送前建议先确认 `.gitignore` 生效。

```bash
git init
git status
git status --ignored
```

确认以下内容不会被提交：

- `node_modules/`
- `dist/`
- `src-tauri/target/`
- `memo-todo.sqlite3`
- `*.sqlite` / `*.sqlite3` / `*.db`
- `.env` / `.env.*`
- 日志文件和编辑器缓存

首次提交示例：

```bash
git add .
git commit -m "chore: initialize memo todo project"
git branch -M main
git remote add origin <你的远程仓库地址>
git push -u origin main
```

> 注意：`package-lock.json` 和 `src-tauri/Cargo.lock` 是锁文件，应用类项目建议提交，以保证不同环境构建依赖一致。

## AI 辅助开发提示词示例

下面的提示词可以用于 Claude Code、ChatGPT 或其他 AI 编程助手。使用时请把具体需求、错误日志或目标文件补充进去。

### 1. 新功能开发

```text
你是一个熟悉 Tauri 2、React 19、TypeScript、Rust 和 SQLite 的桌面应用开发助手。
当前项目是一个 Windows 桌面备忘录/代办应用，应用名为 memo-todo，窗口标题为“备忘录代办”。
前端入口是 src/App.tsx，前端 API 门面是 src/lib/api.ts；Tauri 环境通过 invoke 调用 Rust commands，浏览器模式回退到 src/lib/localApi.ts。
Rust 数据库逻辑主要在 src-tauri/src/db.rs，数据库 schema 在 src-tauri/src/migrations/001_init.sql。
请在保持现有项目结构和代码风格的基础上，帮我实现以下功能：

【在这里描述功能】

要求：
1. 先说明会修改哪些文件。
2. 尽量复用现有类型、组件和 API。
3. 如果需要修改数据库，请说明迁移方案和兼容旧数据的方式。
4. 修改后给出验证步骤。
```

### 2. 错误修复

```text
请根据以下错误日志分析问题原因，并给出最小修改方案。
项目技术栈是 Tauri 2 + React 19 + TypeScript + Rust + SQLite。
注意：前端通过 src/lib/api.ts 调用 Tauri 后端；浏览器开发模式会回退到 src/lib/localApi.ts。
Rust 后端初始化在 src-tauri/src/lib.rs，数据库逻辑在 src-tauri/src/db.rs。

错误日志：
【粘贴完整错误日志】

请输出：
1. 错误原因。
2. 需要修改的文件。
3. 修改方案。
4. 如何验证修复是否成功。
```

### 3. 数据库变更

```text
请基于当前 SQLite schema 设计一个兼容性良好的数据库变更方案。
项目 schema 位于 src-tauri/src/migrations/001_init.sql，数据库访问逻辑位于 src-tauri/src/db.rs。

我想实现的变化是：
【描述字段、表或业务规则变化】

要求：
1. 说明新增/修改的表和字段含义。
2. 说明默认值和旧数据兼容方式。
3. 说明 Rust models、db.rs 和 commands 需要同步调整的位置。
4. 给出验证 SQL 或功能验证步骤。
```

### 4. 代码审查

```text
请审查当前变更，重点关注：
1. Tauri invoke 命令名称和前端调用是否一致。
2. TypeScript 类型和 Rust serde 模型是否匹配。
3. SQLite 查询是否正确处理空值、日期和软删除状态。
4. 浏览器 localStorage 回退逻辑是否与真实 Tauri 后端行为一致。
5. 是否误提交 node_modules、dist、src-tauri/target 或本地数据库文件。

请按“问题 / 影响 / 建议修复方式”的格式输出。
```

### 5. README 或文档维护

```text
请根据当前项目代码更新 README.md。
要求使用中文，内容包括：项目功能、技术栈、目录结构、开发环境、安装依赖、本地运行、构建打包、数据库说明、Git 提交流程和常见问题。
请不要编造不存在的测试脚本；如果 package.json 中没有 test，请明确说明当前未配置测试脚本。
```

## 常见问题

### 1. 为什么浏览器模式和桌面模式的数据不一样？

浏览器模式使用 `localStorage` mock 数据，桌面模式使用 Tauri + Rust + SQLite。两者用于不同开发场景，因此数据不会自动同步。

### 2. 为什么不能使用 `com.tauri.dev` 作为 identifier？

`com.tauri.dev` 是 Tauri 默认模板值，打包时不允许使用。当前项目已改为：

```json
"identifier": "com.bopha.memotodo"
```

### 3. Rust 编译提示找不到 `app.manage(state)` 怎么办？

`manage` 方法由 Tauri 的 `Manager` trait 提供，需要在 `src-tauri/src/lib.rs` 中引入：

```rust
use tauri::Manager;
```

### 4. 哪些文件不应该提交到 Git？

不要提交：

- `node_modules/`
- `dist/`
- `src-tauri/target/`
- 本地 SQLite 数据库文件
- `.env` 环境变量文件
- 日志文件
- 编辑器缓存和系统临时文件

应该提交：

- 源代码
- `package.json`
- `package-lock.json`
- `src-tauri/Cargo.toml`
- `src-tauri/Cargo.lock`
- `src-tauri/tauri.conf.json`
- `src-tauri/src/migrations/*.sql`
- README 和其他项目文档

## 许可证

当前项目尚未声明开源许可证。如需公开发布，请根据实际需求补充 LICENSE 文件。