TodoBoard（Spring Boot + FreeMarker）

一个“够漂亮、够稳健、够可读”的待办清单示例项目：极光背景、玻璃拟态卡片、Bento 布局，并提供完整的待办能力（优先级 / 截止日期 / 完成归档 / 搜索 / 编辑 / 持久化）。

---

目录

• 功能特性
• 快速开始
• 路由一览
• 配置说明
• 数据持久化
• 架构与分层
• 原子级审查清单
• 更多文档

功能特性

类别	内容
体验	单滚动条、空状态插画、Toast 提示、键盘快捷键（/、Ctrl+K）
领域	待办创建/完成/恢复/删除、编辑、搜索、清空已完成
规则	待办列表排序：截止日期优先（越近越靠前）→ 优先级 → 创建时间
持久化	H2 文件数据库（默认 ./data），重启不丢数据；测试使用内存数据库
安全	模板输出对用户输入做 HTML 转义，避免 XSS；错误页不裸露堆栈
工程	GitHub Actions CI（自动跑 ./mvnw test）

快速开始

Windows（PowerShell 7+）

pwsh -NoLogo -NoProfile -Command 'Set-Location "C:\wooK\K"; .\mvnw.cmd test'
pwsh -NoLogo -NoProfile -Command 'Set-Location "C:\wooK\K"; .\mvnw.cmd spring-boot:run'

启动后访问：

• http://localhost:8080/

路由一览

说明：当前为纯服务端渲染（FreeMarker）+ 轻量 JS 增强。

• GET /：首页（新建 + 待办/已完成列表 + 搜索）
• GET /?q=xxx：按关键词搜索
• POST /todos：创建待办
• POST /todos/{id}/complete：标记完成
• POST /todos/{id}/undo：恢复为待办
• POST /todos/{id}/delete：删除
• POST /todos/clear-done：清空已完成
• POST /todos/seed：生成示例数据
• GET /todos/{id}/edit：编辑页
• POST /todos/{id}/update：保存编辑

配置说明

配置文件：

• src/main/resources/application.properties

关键配置：

• app.assets.version
  • 用于静态资源版本化（Cache Busting）
  • 修改 app.css/app.js 或模板引用后请同步更新，避免浏览器缓存造成“修改未生效”
• spring.datasource.url
  • 默认：jdbc:h2:file:./data/todoboard
  • 测试：src/test/resources/application.properties 会切换到 jdbc:h2:mem:...

数据持久化

默认使用 H2 文件数据库，数据文件会落到项目根目录的 ./data/ 下：

• 该目录已加入 .gitignore，不会污染仓库
• 适合本地演示/学习；如需接入 MySQL/PostgreSQL，可以保留 JPA 分层直接替换数据源

架构与分层

flowchart LR
  B[Browser] -->|HTTP| C[TodoController]
  C -->|Model| V[FreeMarker templates]
  V -->|CSS/JS| B
  C --> S[TodoService]
  S --> R[TodoRepository (JPA)]
  R --> D[(H2 DB)]

Loading

• Controller：HTTP/视图模型组织（com.example.todo.controller）
• Service：领域规则与排序（com.example.todo.service）
• Repository：数据访问（com.example.todo.repository）
• View：src/main/resources/templates/*.ftl
• Assets：src/main/resources/static/assets/*（带 ?v= 版本号）

原子级审查清单

提交/推送前建议按这个清单走一遍：

1. .\mvnw.cmd test 通过
2. .\mvnw.cmd -DskipTests package 通过
3. git grep -n "<<<<<<<\\|=======\\|>>>>>>>" -- src 必须无输出（无合并冲突残留）
4. 模板所有“用户可控字段”输出必须 ?html 转义（例如 todo.description / flash.message）
5. 修改静态资源或模板引用后，app.assets.version 必须递增（避免缓存鬼影）

更多文档

• docs/ARCHITECTURE.md：更详细的结构说明、排序策略、持久化细节
• CHANGELOG.md：变更记录（按日期/版本追踪）
• CONTRIBUTING.md：贡献指南（开发约定、审查清单）