个人知识站完整实战

学习目标

零件全部就位，本课做总装：把浏览、编辑、归档、导出四条用户旅程完整走通，并对本地数据库、缓存、元数据、移动端做一次系统性体检。这是个人知识站的出厂验收。

问题场景

每块功能单测都绿，拼在一起却总有缝：归档后的笔记还出现在搜索里、导出的备份缺了最新进度、手机上编辑按钮挤到屏幕外。综合验收的意义，就是让这些「缝」在你能控制的环境里暴露出来，而不是在日常使用的第三个月。

核心解释

四条旅程，每条都有明确的起点、动作和终点断言：

旅程	动作链	验收断言
浏览	首页 → 课程 → 课时 → 笔记	标题元数据正确，流式加载有骨架，无控制台报错
编辑	打开笔记 → 修改 → 保存 → 撤销	保存即时生效，刷新一致，冲突被检测
归档	归档笔记 → 检查各入口	列表、搜索、导出三处状态一致
导出	导出备份 → 重建 → 导入	记录数与字段完整，归档状态保留

归档是检验状态一致性的好样板——它同时牵动三处：

-- 归档动作只改一个字段
UPDATE note SET archived = 1 WHERE id = ?;

但归档之后：列表查询要过滤 archived = 0，搜索要排除归档项，导出要保留归档位。任何一处忘了改，「归档了还在」的 bug 就从缝里钻出来。写操作后 revalidate 覆盖所有展示该数据的路由，是最后一道保险。

体检清单四个维度：

• 数据库：迁移台账完整；PRAGMA integrity_check 通过；备份文件可恢复。
• 缓存：每条写操作都绑定了失效调用；build 输出里动态页没有被误标成静态。
• 元数据：主要页面标题唯一、描述准确、无效路径 404。
• 移动端：DevTools 切手机视口走一遍四条旅程，检查触控目标大小、表单可用性与布局溢出。

示例拆解

出厂验收脚本化（可重复执行）：

# 1. 核心路由
for p in / /courses /notes "/search?q=缓存"; do
  echo "$p => $(curl -s -o /dev/null -w '%{http_code}' "localhost:3000$p")"
done

# 2. 导出并核对
curl -s localhost:3000/api/backup/export -o /tmp/b.json
node -e "const b=require('/tmp/b.json');console.log('version:',b.backupVersion,'notes:',b.notes.length)"

# 3. 无效路径必须 404
curl -s -o /dev/null -w '%{http_code}\n' localhost:3000/courses/not-exist

三条全过只是及格线——真正的验收是把每条旅程手动走一遍并记录发现。验收中发现的每个问题都按 N21 的标准留档：复现步骤、现象、修复验证。

动手任务

在本机工程里完成：

1. 跑通「归档 → 列表消失 → 搜索不出现 → 导出保留归档位」全链路。
2. 执行验收脚本，把输出存档；任何非预期状态码都追查到底。
3. 手机视口走一遍编辑旅程，修掉至少一个布局或触控问题。

常见错误

• 验收只测正常路径：归档、空态、冲突这些「不正常路径」才是缝的藏身处。
• 搜索绕过归档过滤直接扫库：两套读取逻辑，一套忘了 WHERE 条件。
• 导出测试只看文件生成：不恢复核对等于没测；roundtrip 才是导出的验收标准。
• 移动端靠缩放模拟：DevTools 视口能抓布局问题，抓不到触控体验；至少真机开一次。

检查与复盘

自查清单：

• 四条旅程各有一次完整走查记录
• 归档状态在列表、搜索、导出三处一致
• 验收脚本可重复执行，输出已存档

参考资料

• Next.js 文档：App Router 入门 —— 本站用到的全部约定总览
• Next.js 文档：缓存指南 —— 一致性问题的排查地图
• Next.js 文档：项目结构 —— 体检时对照的目录约定