Skip to content

Commit 60ffe1d

Browse files
AparenciaAparencia
committed
docs: add comprehensive project README with architecture, tech stack and team workflow
1 parent 1f4b9f0 commit 60ffe1d

1 file changed

Lines changed: 295 additions & 40 deletions

File tree

‎README.md‎

Lines changed: 295 additions & 40 deletions
Original file line numberDiff line numberDiff line change
@@ -1,58 +1,313 @@
1-
# 课伴（KeBan）
1+
<p align="center">
2+
<h1 align="center">📚 课伴 KeBan</h1>
3+
<p align="center"><strong>你的 AI 智能学习伙伴 — 让每一分钟网课都高效有价值</strong></p>
4+
<p align="center">
5+
<img src="https://img.shields.io/badge/status-alpha-orange.svg" alt="Status" />
6+
<img src="https://img.shields.io/badge/version-v0.2.0--alpha-blue.svg" alt="Version" />
7+
<img src="https://img.shields.io/badge/build-passing-brightgreen.svg" alt="Build" />
8+
<img src="https://img.shields.io/badge/license-Private-lightgrey.svg" alt="License" />
9+
<img src="https://img.shields.io/badge/React-18-61dafb.svg" alt="React" />
10+
<img src="https://img.shields.io/badge/Tauri-2.0-ffc5c5.svg" alt="Tauri" />
11+
</p>
12+
</p>
213

3-
> 提高网课效率的智能学习工具
14+
---
415

5-
## 项目简介
16+
## 📝 项目简介
617

7-
课伴是一款以"提高网课效率"为核心定位的学习工具软件，提供四大核心学习工具模块：
18+
**课伴（KeBan）** 是一款面向个人的 **本地优先（Local-First）AI 辅助学习桌面应用**，基于费曼学习法等科学方法论，致力于解决网课学习效率低下的核心痛点。
819

9-
- **番茄钟（Pomodoro Timer）**：专注时长管理与统计
10-
- **智能笔记（Notes）**：结构化随堂笔记记录
11-
- **闪卡（Flashcards）**：SM-2 间隔重复记忆
12-
- **费曼学习法（Feynman Technique）**：以教代学深度理解
20+
> 💡 **核心理念：本地优先 + AI 增强可选**
21+
>
22+
> 所有核心功能 **离线完整可用**，无需任何网络依赖；联网时可按需开启 AI 辅助，作为增值能力叠加。你的学习数据，始终掌握在自己手中。
1323
14-
## 架构理念
24+
---
1525

16-
**本地优先 + AI 增强可选**
26+
## ✨ 核心特性
1727

18-
- **本地模式**：所有核心功能可在纯本地离线环境完整运行，不依赖任何网络服务
19-
- **AI 增强模式**：网络可用时可选开启 AI 辅助能力，作为增值功能叠加
28+
课伴围绕 **"学 → 记 → 练 → 悟"** 学习闭环，提供四大核心模块：
2029

21-
## 技术栈
30+
### 🍅 番茄钟（Pomodoro Timer）— 时间管理
2231

23-
| 领域 | 选型 |
32+
- **三段式计时**：工作 / 短休息 / 长休息自动轮转
33+
- **双模式切换**：上课模式（45 分钟静默）与自习模式（25/5 标准节奏）
34+
- **后台不中断**：Web Worker 后台计时，切换标签页不中断
35+
- **数据洞察**：专注时长统计与趋势分析，量化学习投入
36+
37+
### 📝 智能笔记（Smart Notes）— 知识沉淀
38+
39+
- **专业编辑器**：基于 TipTap 3（ProseMirror）的富文本编辑体验
40+
- **多种模板**：大纲式、康奈尔笔记法、思维导图式等结构化模板
41+
- **灵活组织**：3 级嵌套文件夹 + 自由标签系统
42+
- **安全省心**：本地全文搜索，自动保存（≤10 秒间隔）
43+
44+
### 🃏 闪卡（Flashcards）— 记忆巩固
45+
46+
- **科学算法**：SM-2 间隔重复算法（Again / Hard / Good / Easy 四档评分）
47+
- **层级管理**：3 级嵌套牌组（科目 → 章节 → 知识点）
48+
- **学习统计**：复习数 / 新学数 / 正确率 / 遗忘曲线可视化
49+
- **批量导入**：支持 CSV / JSON 格式快速导入
50+
51+
### 🧠 费曼学习法（Feynman Technique）— 深度理解
52+
53+
- **四步流程**：选概念 → 用自己的话解释 → 识别薄弱点 → 简化重述
54+
- **薄弱点追踪**：自动标记与汇总薄弱知识点
55+
- **理解度评估**：1–5 星自评体系，直观衡量掌握程度
56+
57+
### 🤖 AI 增强能力（联网可选开启）
58+
59+
| 能力 | 说明 |
60+
|------|------|
61+
| 笔记智能摘要 | 一键生成课堂笔记摘要与续写润色 |
62+
| AI 自动生成闪卡 | 从笔记内容智能生成记忆卡片 |
63+
| 费曼学习评估 | AI 评估解释质量，给出改进建议 |
64+
| 智能时长推荐 | 根据学习数据推荐最佳番茄钟时长 |
65+
66+
> 基于国产大模型：**通义千问（Qwen）** / **DeepSeek** / **智谱 GLM**，按需选择，灵活切换。
67+
68+
---
69+
70+
## 🛠️ 技术栈
71+
72+
### 前端客户端
73+
74+
| 类别 | 技术 | 说明 |
75+
|------|------|------|
76+
| UI 框架 | React 18 + TypeScript | 类型安全的组件化开发 |
77+
| 构建工具 | Vite 8 | 极速 HMR 与构建 |
78+
| 桌面端 | Tauri 2.0 | 轻量级跨平台桌面应用（5–15 MB 安装包） |
79+
| 样式方案 | Tailwind CSS 3.4 | 原子化 CSS + Design Tokens |
80+
| 状态管理 | Zustand + TanStack Query | 本地状态 + 异步数据缓存 |
81+
| 本地存储 | Dexie.js (IndexedDB) | 本地优先数据存储 |
82+
| 富文本编辑器 | TipTap 3 (ProseMirror) | 智能笔记编辑器 |
83+
| 离线支持 | Workbox + Service Worker | PWA 离线可用 |
84+
| 路由 | React Router 7 | SPA 路由管理 |
85+
| 图标 | Lucide React | 线性风格图标库 |
86+
| 测试 | Vitest + Testing Library | 单元与组件测试 |
87+
| 代码检查 | Oxlint | 高性能 Rust Linter |
88+
89+
### 后端服务
90+
91+
| 服务 | 技术 | 端口 | 说明 |
92+
|------|------|------|------|
93+
| 同步服务 | Go + Gin | `8080` | 数据同步 API（Push / Pull / Resolve） |
94+
| AI 网关 | Python + FastAPI + LangChain | `8000` | AI 增强服务网关 |
95+
| 数据库 | PostgreSQL 16 | `5432` | 主数据存储 |
96+
| 缓存 | Redis 7 | `6379` | 会话 / 缓存 / 限流 |
97+
98+
### 基础设施
99+
100+
| 类别 | 技术 |
24101
|------|------|
25-
| 前端框架 | React 18 + TypeScript + Vite |
26-
| 本地存储 | Dexie.js (IndexedDB) + localStorage |
27-
| 离线缓存 | Service Worker (Workbox) |
28-
| 富文本编辑器 | TipTap (ProseMirror) |
29-
| 后端语言 | Go + Python |
30-
| 数据库 | PostgreSQL 16 + Redis 7 |
31-
| AI 框架 | FastAPI + LangChain |
102+
| 容器化 | Docker + docker-compose |
103+
| AI 模型 | 通义千问 (Qwen) / DeepSeek / 智谱 GLM |
104+
| 服务通信 | gRPC + Protobuf（规划中） |
105+
106+
---
107+
108+
109+
## 📁 项目结构
110+
111+
```
112+
KeBan/
113+
├── client/ # 🖥️ 前端客户端（React + Tauri）
114+
│ ├── src/
115+
│ │ ├── features/ # 📦 业务功能模块
116+
│ │ │ ├── dashboard/ # 仪表盘 & 学习概览
117+
│ │ │ ├── pomodoro/ # 番茄钟模块
118+
│ │ │ ├── notes/ # 智能笔记模块
119+
│ │ │ ├── flashcards/ # 闪卡模块
120+
│ │ │ └── feynman/ # 费曼学习法模块
121+
│ │ ├── lib/ # 📚 核心库
122+
│ │ │ ├── ai/ # AI 服务集成层
123+
│ │ │ ├── auth/ # 认证模块
124+
│ │ │ ├── http/ # HTTP 请求封装
125+
│ │ │ ├── mode/ # 双模式管理（本地/AI）
126+
│ │ │ ├── storage/ # Dexie.js 本地存储层
127+
│ │ │ ├── sync/ # 数据同步客户端
128+
│ │ │ ├── sm2.ts # SM-2 间隔重复算法
129+
│ │ │ └── utils/ # 通用工具函数
130+
│ │ ├── components/ # 🧩 共享 UI 组件
131+
│ │ ├── hooks/ # 🪝 自定义 React Hooks
132+
│ │ ├── pages/ # 📄 页面级组件
133+
│ │ ├── routes/ # 🧭 路由配置
134+
│ │ ├── store/ # 🗄️ Zustand 全局状态
135+
│ │ ├── styles/ # 🎨 全局样式 & Design Tokens
136+
│ │ └── types/ # 📐 TypeScript 类型定义
137+
│ ├── src-tauri/ # 🦀 Tauri Rust 后端
138+
│ └── package.json
139+
├── server/ # ⚙️ 后端服务
140+
│ ├── sync-service/ # Go 数据同步服务（:8080）
141+
│ ├── ai-gateway/ # Python AI 网关服务（:8000）
142+
│ ├── shared/proto/ # gRPC Protobuf 定义
143+
│ └── docker-compose.yml # 容器编排配置
144+
├── docs/ # 📖 项目文档（按阶段组织）
145+
│ ├── phase0/ # 项目立项与启动
146+
│ ├── phase1/ # 需求分析
147+
│ ├── phase2/ # 项目计划与技术预研
148+
│ └── phase3/ # 系统设计
149+
├── .env.example # 🔑 环境变量模板
150+
└── README.md
151+
```
152+
153+
---
154+
155+
## 🏗️ 架构概览
156+
157+
课伴采用 **"本地优先 + AI 增强可选"** 双模式架构：
158+
159+
```
160+
┌──────────────────────────────────────────────────────┐
161+
│ 课伴桌面端 (Tauri 2.0) │
162+
│ ┌────────────────────────────────────────────────┐ │
163+
│ │ React 前端 (Vite + TypeScript) │ │
164+
│ │ │ │
165+
│ │ 🍅 番茄钟 │ 📝 智能笔记 │ 🃏 闪卡 │ 🧠 费曼 │ │
166+
│ │ │ │
167+
│ │ ↕ ↕ │ │
168+
│ │ Dexie.js (IndexedDB) TipTap (ProseMirror) │ │
169+
│ └────────────────────┬───────────────────────────┘ │
170+
└───────────────────────┼──────────────────────────────┘
171+
│ 可选（联网时按需开启）
172+
┌──────────┴──────────┐
173+
│ │
174+
┌──────┴──────┐ ┌──────┴──────┐
175+
│ Sync Service │ │ AI Gateway │
176+
│ (Go/Gin) │ │ (FastAPI) │
177+
│ ↕ │ │ ↕ │
178+
│ PG + Redis │ │ Qwen / DS │
179+
└──────────────┘ │ / GLM │
180+
└─────────────┘
181+
```
182+
183+
> **离线模式**：所有四大模块在纯本地环境完整运行，数据存储在 IndexedDB，零网络依赖。
184+
>
185+
> **AI 增强模式**：联网时可选择开启 AI 能力（笔记摘要、闪卡生成、学习评估等），通过 AI Gateway 对接国产大模型。
186+
187+
---
188+
189+
## 🗺️ 路线图
190+
191+
| 阶段 | 状态 | 核心交付 |
192+
|------|------|----------|
193+
| **MVP-1 Alpha** | ✅ 已完成 | 纯本地核心版 — 四大模块 + PWA 离线 + 本地存储 |
194+
| **MVP-2 Alpha** | 🔧 进行中 | AI 增强 + 云同步 + Tauri 桌面端 + 用户认证 |
195+
| **Beta 公测** | 📋 规划中 | 全功能集成，面向真实用户测试 |
196+
| **正式上线** | 🎯 规划中 | 生产就绪版 |
197+
198+
### 🔮 未来方向
32199

33-
## 项目结构
200+
- **社交协作**：学习小组、闪卡共享、专注排行榜
201+
- **跨端生态**：移动端 App、浏览器插件
202+
- **AI 深度增强**：个性化学习路径、知识图谱、智能复习规划
203+
- **开放平台**：插件系统、第三方模板市场
34204

205+
---
206+
207+
## 📖 项目文档
208+
209+
完整的开发文档存放在 [`docs/`](./docs/) 目录，按项目生命周期组织：
210+
211+
| 阶段 | 目录 | 主要内容 |
212+
|------|------|----------|
213+
| Phase 0 | [`docs/phase0/`](./docs/phase0/) | 项目立项书、可行性评估、风险登记册、团队角色与沟通机制 |
214+
| Phase 1 | [`docs/phase1/`](./docs/phase1/) | PRD 需求文档、用户故事地图、业务流程图、竞品分析 |
215+
| Phase 2 | [`docs/phase2/`](./docs/phase2/) | WBS 工作量估算、SM-2 算法验证、技术预研报告、甘特图 |
216+
| Phase 3 | [`docs/phase3/`](./docs/phase3/) | 系统架构设计、技术选型 ADR、UI 设计规范、API 设计规范 |
217+
218+
---
219+
220+
## 📦 版本与发布管理
221+
222+
### 语义化版本规范
223+
224+
项目遵循 **SemVer**（语义化版本）规范，格式为 `v{MAJOR}.{MINOR}.{PATCH}`：
225+
226+
| 组成部分 | 含义 | 示例 |
227+
|----------|------|------|
228+
| `MAJOR` | 主版本号（不兼容的 API 变更） | `1.0.0` |
229+
| `MINOR` | 次版本号（向后兼容的功能新增） | `0.2.0` |
230+
| `PATCH` | 修订号（向后兼容的缺陷修复） | `0.2.1` |
231+
232+
**当前版本**：`v0.2.0-alpha`（MVP-2 Alpha 阶段）
233+
234+
### Git Tag 发布流程
235+
236+
```bash
237+
# 1. 确保在 master 分支并拉取最新代码
238+
git checkout master
239+
git pull origin master
240+
241+
# 2. 创建语义化版本标签
242+
git tag v0.2.0
243+
244+
# 3. 推送标签到远程仓库
245+
git push origin v0.2.0
35246
```
36-
├── docs/ # 项目文档（按开发流程阶段组织）
37-
│ ├── phase0/ # 阶段零：项目立项与启动
38-
│ ├── phase1/ # 阶段一：需求阶段
39-
│ ├── phase2/ # 阶段二：签约与项目计划
40-
│ ├── phase3/ # 阶段三：设计阶段
41-
│ └── templates/ # 文档模板
42-
├── client/ # 前端客户端代码
43-
├── server/ # 后端服务代码
44-
└── scripts/ # 脚本工具
247+
248+
> ⚠️ 发布 Tag 前请确保：所有测试通过（`npm run test`）、构建成功（`npm run build`）、关键功能手动验证完毕。
249+
250+
### Tauri 安装包构建
251+
252+
桌面端安装包通过 Tauri CLI 构建：
253+
254+
```bash
255+
cd client
256+
npm run build # 前端生产构建
257+
npx tauri build # 生成 NSIS 安装包
45258
```
46259

47-
## 里程碑
260+
- 产物路径：`client/src-tauri/target/release/bundle/nsis/`
261+
- 安装包格式：Windows NSIS（`.exe`），支持简体中文 / English
262+
- 安装模式：当前用户安装（`currentUser`），无需管理员权限
263+
264+
---
265+
266+
## 👥 团队协作
267+
268+
### 开发工作流
269+
270+
```
271+
feature/* ──PR──▶ develop ──▶ master ──tag──▶ release
272+
```
273+
274+
| 分支 | 用途 | 保护规则 |
275+
|------|------|----------|
276+
| `master` | 稳定发布分支 | 仅接受 develop 合并，需 Tag 标记发布 |
277+
| `develop` | 日常开发集成分支 | 功能分支通过 PR 合入 |
278+
| `feature/*` | 功能开发分支 | 从 develop 检出，完成后 PR 回合 |
279+
| `fix/*` | 缺陷修复分支 | 紧急修复可直接 PR 到 master |
280+
281+
### 提交规范
282+
283+
项目使用 **Conventional Commits** 规范：
284+
285+
```
286+
<type>(<scope>): <description>
287+
288+
# 示例
289+
feat(notes): 添加康奈尔笔记模板
290+
fix(pomodoro): 修复切换标签页后计时器暂停的问题
291+
refactor(storage): 优化 Dexie.js 索引策略
292+
docs(phase3): 补充 API 设计规范文档
293+
```
294+
295+
常用类型：`feat` · `fix` · `refactor` · `docs` · `style` · `test` · `chore` · `perf`
296+
297+
### 代码质量
298+
299+
| 工具 | 用途 | 命令 |
300+
|------|------|------|
301+
| Oxlint | 高性能 Rust Linter | `npm run lint` |
302+
| Vitest | 单元与组件测试 | `npm run test` |
303+
| TypeScript | 静态类型检查 | `npm run build`（含 `tsc -b`） |
304+
305+
> 提交 PR 前请确保 `npm run lint` 和 `npm run test` 全部通过。
306+
307+
---
48308

49-
| 里程碑 | 时间节点 | 交付 |
50-
|--------|---------|------|
51-
| MVP-1 Alpha | 第 28 周 | 本地核心版（番茄钟+笔记+闪卡+费曼） |
52-
| MVP-2 Alpha | 第 36 周 | AI 增强版（云同步+AI 功能） |
53-
| Beta 公测 | 第 44 周 | 全功能集成版 |
54-
| 正式上线 | 第 54 周 | 生产就绪版 |
309+
## 📄 许可证
55310

56-
## 许可证
311+
**Private — All Rights Reserved.**
57312

58-
Private - All rights reserved
313+
本项目为私有项目，所有权利保留。未经书面许可，不得复制、修改或分发本项目的任何部分。

0 commit comments

Comments
 (0)