AI 原生开放教材

外观

动手学 CS146S 中文版系统课程·中文原文 ↗仓库 ↗

Week 4：开发者指挥中心 ​

这是一个 FastAPI、SQLite 和原生 JavaScript 组成的笔记/行动项应用。后端提供笔记 CRUD、搜索和行动项完成接口；前端可以新增、搜索、编辑、删除笔记，并完成行动项。

目录 ​

  • backend/app/routers/：HTTP 路由
  • backend/app/schemas.py：请求校验和响应结构
  • backend/app/services/extract.py：行动项、标签提取
  • backend/tests/：接口和服务测试
  • frontend/：页面、样式和交互
  • docs/API.md：API 契约
  • .claude/commands/：可复用的 Claude 工作流
  • CLAUDE.md：仓库级开发规则

使用 ​

在 week4/ 目录运行：

bash
conda activate cs146s
make run

打开 http://127.0.0.1:8000。常用检查：

bash
make test
make lint
make format
pre-commit run --all-files

Claude 自定义命令：

text
/tests backend/tests/test_notes.py
/docs-sync http://127.0.0.1:8000
/refactor-module backend/app/services/old.py backend/app/services/new.py

各任务解题思路 ​

1. pre-commit ​

把 Black 和 Ruff 放进提交前钩子。先自动格式化，再检查剩余问题，避免风格错误进入提交。

2. 笔记搜索 ​

固定路由 /notes/search 放在 /{note_id} 前。用 SQLAlchemy ilike 同时匹配标题和正文，查询值用参数绑定，不拼 SQL。前端用 encodeURIComponent 编码关键词。

3. 完成行动项 ​

按 ID 查询；不存在返回 404，存在则把 completed 设为 true。重复调用结果不变，前端完成后重新加载列表。

4. 标签提取 ​

正则只识别独立的 #标签，支持字母、数字、下划线、连字符和 Unicode；按出现顺序去重。行动项提取保持原接口，extract_note 一次返回行动项和标签。

5. 笔记 CRUD ​

PUT 先查记录，再同时替换标题和正文；DELETE 删除后返回 204 空响应。前端按钮调用对应接口，成功后刷新列表。

6. 校验和错误处理 ​

Pydantic 在入口限制长度并拒绝纯空白字符串。资源不存在统一返回清楚的 404；纯空白搜索返回 400；JSON 结构错误保留 FastAPI 的 422。

7. API 文档同步 ​

docs/API.md 记录路径、方法、载荷、状态码和错误。/docs-sync 对照运行中的 /openapi.json，只更新文档并列出差异。

8. 测试工作流 ​

/tests 先快速运行并在首个失败处停止；通过后再统计覆盖率。这样失败信息短，成功时又能看到未覆盖行。

9. 重构工作流 ​

/refactor-module 先找全部引用，再移动文件、更新调用方，最后检查旧路径并运行 Ruff、Black 和测试。一次完成切换，不留无用兼容层。