项目8 · 个人 React 与 AI 学习空间

• 提交需求验收表：把学习台、课程笔记、练习记录、AI 问答、进度统计五个页面与 notes / progress / ask 三类接口拆成可逐条勾选的验收项，写清完成标准与不做什么
• 独立完成关键决策：在 SQLite 持久化、LIKE 检索加片段引用、mock / 真实模型双通道、JSON 接口与纯 CSS 图表之间做取舍，并在架构说明里给出理由与代价
• 用 Next.js 16 App Router 组织五个页面，划清 Server Component 直接读库、Client Component 负责交互、Route Handler 负责写入的渲染边界
• 用 node:sqlite 建 notes / progress / chat 三张表，写基于 PRAGMA user_version 的迁移与可重复执行的 seed，不依赖外部数据库服务
• 完成笔记 CRUD、关键词搜索、标签筛选与搜索评分排序，搜索命中后能截取可读片段
• 完成练习记录的列表、状态流转与进度聚合，把 react / nextjs / ai / python 四条学习线放进同一张进度视图
• 实现基于笔记检索的 AI 问答：无 key 走本地 mock，有 key 走 OpenAI 兼容接口；回答附编号引用，无命中时明确说笔记不足而不是编造
• 写架构说明与运行脚本：记录渲染边界、数据流、关键决策和失败兜底，用一条 verify 命令跑通单测与结构检查，solution 构建通过、starter 保留缺口

• 01学习台 /：今日继续、笔记与练习统计、今日投入、四条学习线进度、最近笔记
• 02课程笔记 /notes：笔记列表、新建、编辑、删除、关键词搜索、标签筛选、课程编号标记
• 03练习记录 /practice：练习列表、状态筛选、todo / doing / done 状态流转、新增练习记录、投入分钟数
• 04AI 问答 /ask：基于笔记检索的问答、mock / 真实模型模式标识、编号引用与片段摘录、历史问答、无命中提示
• 05进度统计 /progress：完成率、累计与今日投入、按学习线完成度、状态分布、最近 7 天投入，全部用纯 CSS 条形
• 06接口 /api/notes 与 /api/notes/[id]：列表 / 搜索 / 标签过滤、新建、更新、删除
• 07接口 /api/progress 与 /api/progress/[id]：列表与聚合摘要、新增、状态更新
• 08接口 /api/ask：POST 问题，返回 answer / mode / citations，并写入 chat 历史；采用 JSON 响应而非 SSE

# 个人 React 与 AI 学习空间（p8-capstone）

八个项目里的最后一个：用 Next.js 16 + React 19 + `node:sqlite` 做一个单用户的个人学习空间。学习台、课程笔记、练习记录、AI 问答、进度统计五个页面都接真实数据；AI 问答先用笔记检索，再把片段编号交给 mock 或 OpenAI 兼容接口。

这个项目的重点不是堆功能，而是独立完成一次「需求 → 数据 → 页面 → 验收 → 交付」的闭环：写需求验收表、做关键决策、写架构说明、留下能一条命令跑通的运行脚本。

## 学习目标

- 用 App Router 组织五个页面，划清 Server Component 读库、Client Component 交互、Route Handler 写入的边界。
- 用 `node:sqlite` 建 `notes` / `progress` / `chat` 三张表，写 `PRAGMA user_version` 迁移与可重复执行的 seed。
- 完成笔记 CRUD、LIKE 检索、评分排序、标签筛选与片段截取。
- 完成练习状态流转与进度聚合，把 react / nextjs / ai / python 四条学习线放进同一张视图。
- 实现基于笔记检索的 AI 问答：无 key 走本地 mock，有 key 走 OpenAI 兼容接口，回答附 `[n]` 引用。
- 用纯 CSS 条形做统计图表，不引入图表库。
- 写需求验收表、架构说明和运行脚本，完成毕业作品交付。

## 环境要求

- Node.js **24+**（`node:sqlite` 在此版本稳定；不需要安装数据库服务）
- npm 10+
- 不依赖 Google Fonts，构建不需要访问外网字体

## 快速开始

### 运行参考实现（solution）

```bash
cd solution
npm install --no-audit --no-fund
npm run seed
npm run dev
```

打开 `http://localhost:3000`。一条命令版本：

```bash
cd solution && npm install --no-audit --no-fund && npm run seed && npm run dev
```

**AI key 说明**：不配置 `AI_API_KEY` 也能完整走通问答，`/api/ask` 会返回基于笔记片段的本地 mock 回答。要接真实模型：

```bash
cp .env.example .env.local
# 填入 AI_API_KEY，必要时改 AI_BASE_URL / AI_MODEL
```

配置后调用 `{AI_BASE_URL}/chat/completions`，默认 `https://api.openai.com/v1` 与 `gpt-4o-mini`。模型失败会自动回退到 mock，并在响应里带 `warning`。

### 运行起点（starter）

```bash
cd starter
npm install --no-audit --no-fund
npm run seed
npm run dev
```

起点只有静态学习台、导航外观和 `TODO.md`。`npm run seed` 只打印提示，不会写数据库；按 `TODO.md` 的 m1–m10 逐项补。

### 常用命令

| 命令 | 作用 |
| --- | --- |
| `npm run dev` | 启动开发服务器 |
| `npm run seed` | 建库、迁移并导入 `../fixtures/seed-notes.json` 与 `seed-progress.json`，已存在则跳过 |
| `npm run seed:reset` | 清空 notes / progress / chat 后重新导入 |
| `npm run build` | 生产构建 |
| `npm run start` | 启动生产服务器 |
| `npm run typecheck` | TypeScript 检查（solution） |
| `npm run verify` | 一条命令跑纯函数单测 + 结构检查（solution） |

## 目录结构

```text
p8-capstone/
├── README.md
├── starter/                         # 可启动起点：静态学习台 + TODO.md
│   ├── app/
│   │   ├── layout.tsx
│   │   ├── page.tsx                 # 静态壳 + 里程碑清单
│   │   └── globals.css
│   ├── scripts/seed.mjs             # 只打印提示，等 m3 替换
│   ├── TODO.md                      # m1–m10 逐项缺口
│   ├── next.config.ts
│   └── package.json
├── solution/                        # 完整参考实现
│   ├── app/
│   │   ├── page.tsx                 # 学习台：统计 + 今日继续 + 最近笔记
│   │   ├── notes/page.tsx           # 笔记：CRUD + 搜索 + 标签
│   │   ├── practice/page.tsx        # 练习：列表 + 状态流转
│   │   ├── ask/page.tsx             # AI 问答：mock / 模型 + 引用
│   │   ├── progress/page.tsx        # 统计：纯 CSS 条形
│   │   ├── api/
│   │   │   ├── notes/route.ts       # GET / POST
│   │   │   ├── notes/[id]/route.ts  # GET / PATCH / DELETE
│   │   │   ├── progress/route.ts    # GET / POST
│   │   │   ├── progress/[id]/route.ts
│   │   │   └── ask/route.ts         # POST，JSON 响应
│   │   └── globals.css
│   ├── components/
│   │   ├── site-nav.tsx
│   │   ├── page-head.tsx
│   │   ├── stat-card.tsx
│   │   ├── progress-charts.tsx      # 纯 CSS 条形
│   │   ├── notes-workbench.tsx
│   │   ├── practice-board.tsx
│   │   └── ask-workbench.tsx
│   ├── lib/
│   │   ├── db.ts                    # node:sqlite + 迁移 + seed
│   │   ├── notes.ts                 # 笔记 SQL / LIKE 搜索
│   │   ├── practice.ts              # 练习 SQL
│   │   ├── chats.ts                 # 问答历史
│   │   ├── search.ts                # 评分 / 片段（纯函数）
│   │   ├── progress.ts              # 聚合 / 按日（纯函数）
│   │   ├── citations.ts             # 引用 / mock（纯函数）
│   │   ├── ask.ts                   # 问答编排 / 模型调用
│   │   ├── api.ts                   # 请求体与错误映射
│   │   ├── errors.ts
│   │   ├── format.ts
│   │   ├── study.ts
│   │   └── types.ts
│   ├── scripts/
│   │   ├── seed.ts
│   │   └── verify.mjs               # 一条命令验收
│   ├── .env.example
│   ├── next.config.ts
│   └── package.json
├── tests/
│   ├── check.mjs                    # 结构 / API 特征 + 临时数据库检查
│   └── unit-study.test.mjs          # 搜索 / 进度 / 引用纯函数单测
├── docs/
│   ├── requirements.md              # 需求验收表
│   └── architecture.md              # 渲染边界 / 数据流 / 关键决策
└── fixtures/
    ├── seed-notes.json              # 6 条示例笔记
    └── seed-progress.json           # 10 条示例练习
```

`node_modules/`、`.next/`、`data/*.db` 是运行产物，不提交。

## 验收流程

### 自动检查

```bash
# 在 p8-capstone 根目录
node tests/unit-study.test.mjs   # 纯函数单测，node 直跑
node tests/check.mjs             # solution 全过，starter 保留缺口
```

或者从 solution 目录：

```bash
npm run verify
```

### 手动走查

1. **m1 需求验收表**：打开 `docs/requirements.md`，确认五个页面、三类接口、十条里程碑、四类边界都在。
2. **m2 页面骨架**：依次访问 `/`、`/notes`、`/practice`、`/ask`、`/progress`，导航高亮正确，随便输一个未知路径进 404。
3. **m3 数据层**：删掉 `solution/data/study.db`，跑两次 `npm run seed`；第一次新增 6 条笔记 / 10 条练习，第二次全部跳过。
4. **m4 学习台**：统计卡与数据库一致；「今日继续」显示最近笔记和 doing 练习；四条学习线条形有数据。
5. **m5 笔记**：新建一条带标签的笔记；搜索「状态」看排序；点标签筛选；编辑后刷新；删除并确认。
6. **m6 练习**：新增一条练习；在 todo / doing / done 之间切换；刷新页面状态仍在。
7. **m7 AI 问答**：不配 key 问「渲染边界怎么记的」看 mock + 引用；再问「火星天气」看「笔记不足」；刷新看历史还在。
8. **m8 统计**：检查完成率、状态分布、7 天柱状图；空数据不出现 `NaN`。
9. **m9 架构说明**：打开 `docs/architecture.md`，能按文档找到一条请求从点击到落库的路径。
10. **m10 运行脚本**：`npm run build`、`npm run verify` 通过；starter 的 `npm run build` 也能通过但检查有缺口。

逐项验收标准见 `docs/requirements.md`。

## 实现要点

- **渲染边界**：页面 Server Component 直接读 SQLite，首屏就是完整 HTML；只有表单、搜索、状态切换和问答走 Route Handler。页面统一 `dynamic = "force-dynamic"`，避免构建时把某一次数据库结果静态化。
- **搜索**：SQL `LIKE` 先筛候选，`scoreNote` 再按标题 / 标签 / 课程编号 / 正文出现次数评分，`buildSnippet` 截命中片段。
- **AI 问答**：`answerQuestion` 先检索、再装配 `[1]…[4]` 引用；无命中直接说笔记不足，不调用模型；无 key 走 mock，有 key 走 OpenAI 兼容；每次问答写入 `chat`。
- **引用**：`citations` 存的是快照（noteId、标题、摘录、标签、课程编号），笔记删除后历史回答仍可读。
- **进度**：`summarizeProgress` 与 `minutesByDay` 是纯函数，页面、API、单测共用同一口径；图表只用 `div` 的宽度 / 高度。

## 交付物

- `docs/requirements.md`：需求验收表。
- `docs/architecture.md`：架构说明。
- `solution/scripts/verify.mjs`：一条命令跑单测与结构检查。
- `solution`：完整实现，`npm run build` 通过。
- `starter`：可启动起点，保留 m1–m10 缺口。