手帐 Blog

主题

10 · 迷你笔记板小项目落地 ​

目标：两周内交付一个可 pnpm dev、可演示的本地笔记板——串联 02～09。
前置：本系列 02～09；官方 App Router · Server Actions · Project Structure

1. 范围（刻意做小） ​

做 ​

路由行为
/笔记列表（标题 + 链到详情）；顶部可新建
/notes/[id]详情（标题 + 正文）；可删除并回列表
共享 layout站点名 + 导航
  • 持久化：项目内 JSON 文件（如 data/notes.json），零外部 DB。
  • 读：Server Component；写：Server Actions + revalidatePath。
  • 至少一处 'use client'：列表页搜索过滤（对已加载数据客户端过滤即可）。

不做（本版禁止） ​

  • 登录 / JWT / 云数据库 / Prisma
  • Redux / React Query / 重 UI 套件
  • 把 Journal 整站搬到 Next
  • Pages Router

验收（打勾即本系列「期望」达标） ​

  • [ ] pnpm dev 可演示：增、查、删
  • [ ] 刷新后数据仍在（JSON 持久化）
  • [ ] 能讲清：哪些文件 Server、哪一处 Client、Action 在哪
  • [ ] README 十行内说明如何运行 + 3 条对照官方文档链接
  • [ ] 用第 09 篇清单自审过一轮

2. 建议目录 ​

text
notes-board/
  app/
    layout.tsx
    page.tsx                 # 列表 + 新建表单 + 挂载 SearchBox
    notes/[id]/page.tsx     # 详情 + 删除
    actions/notes.ts         # 'use server'
  components/
    search-box.tsx           # 'use client' 过滤 UI
    note-list.tsx            # 可 Server：接收 notes + query 由父处理，或 Client 包一层
  lib/
    notes-fs.ts              # 读写 data/notes.json
    validate-title.ts
  data/
    notes.json               # [{ id, title, body, createdAt }]
  README.md

可在 02 的 notes-board-lab 上改建，或新建干净项目。

3. 设计要点（串起前几篇） ​

主题落点
工具链create-next-app + TS（02）
组件 / state搜索框 Client（03）
少用 Effect过滤用派生，不 effect 同步（04）
路由layout / page / [id]（05）
RSC列表页默认 Server；仅 Search 叶子 Client（06）
读数据Server 里 listNotes() 读文件（07 心智；本地 fs 代替 fetch）
写操作Actions + revalidatePath（08）
AI / 测试清单 + validateTitle 单测（09）

lib/notes-fs.ts 要点 ​

  • 仅在 Server / 'use server' 模块调用 fs。
  • 路径用 path.join(process.cwd(), 'data', 'notes.json')。
  • 读写注意：开发热更新与并发不是本项目目标；简单 readFile / writeFile 即可。
  • 可用 import 'server-only'（若已安装）防止被 Client 误导入。

搜索（Client）建议 ​

Server 把完整列表作为 props 传给 Client 列表壳，或：

  • Server 渲染「新建表单 + 全量列表」；
  • Client SearchBox 只管理 query，过滤后展示——注意：若列表很大再改架构；本项目几十条足够。

更干净的拆法：NoteListClient({ notes }) 内部 useState(query) + notes.filter(...)。

4. 里程碑（周末友好） ​

日交付
Day 1项目骨架 + notes.json + listNotes 在 / 渲染
Day 2createNoteAction；表单新增后列表更新且刷新仍在
Day 3/notes/[id] 详情；deleteNoteAction
Day 4Client 搜索过滤；validateTitle + 测试
Day 5README、09 清单自审、删掉实验路由（/practice 等可留可删）

5. README 最小模板 ​

markdown
# notes-board

## Run
pnpm install
pnpm dev

## 对照官方
1. Server/Client: https://nextjs.org/docs/app/getting-started/server-and-client-components
2. Server Actions: https://nextjs.org/docs/app/building-your-application/data-fetching/server-actions-and-mutations
3. Routing: https://nextjs.org/docs/app/building-your-application/routing

6. AI 使用约定（本项目） ​

text
每轮只改一个里程碑。
禁止新增依赖，除非我点名。
提交前对照 blog/react进阶/20260716-09 审查清单。
文件 JSON 持久化，不要引入数据库。

7. 做完之后 ​

  • [ ] 在暑假计划 / 个人笔记里勾选「React 支线小交付」
  • [ ] （可选）另写一篇「笔记板复盘」挂到 blog 后续规划
  • [ ] 若求职需要 Next：用本项目讲 Server/Client 边界比背名词有用

8. 系列收束 ​

← 上一篇：09 · 审查清单与轻量测试
↑ 目录：系列 README

官方入口 ​