hw/docs/todo-progress.md

开发 TODO 与进展

本文档用于跟踪项目从方案阶段到开发阶段的推进情况。

1. 当前阶段

当前处于：基础开发已启动，Flask 项目骨架与核心数据模型已落地阶段

已完成：

• 明确项目业务目标
• 明确按“户”为单位管理
• 明确前后端与数据库技术栈
• 明确首页为大表格管理页
• 明确长辈专用搜索与编辑页思路
• 明确 CSV 导入导出需求
• 明确中文 / 拼音 / 首字母搜索需求
• 明确简单账号密码登录需求
• 明确审计日志与长辈专属账号需求
• 完成文档基线建立
• 完成 HappyWedding（hw）Flask 项目骨架初始化
• 完成 SQLAlchemy 扩展与基础配置
• 完成 6 张核心表模型定义
• 完成基础健康检查路由
• 完成 .venv 工作流与本地开发文档
• 完成基础测试并验证通过
• 完成 Flask-Migrate / Alembic 迁移能力接入
• 完成首个 migration 文件生成与本地升级验证
• 完成 seed 初始化命令（管理员账号 + 基础 option_items）
• 完成 SQLite / MySQL 跨库 ID 类型兼容修复
• 完成 seed 命令未建表前置检查与幂等性验证

2. 总体路线图

Phase 0：方案固化

• 梳理业务需求
• 确认技术栈
• 形成页面结构方案
• 补充登录、账号、审计日志需求
• 建立 README 与方案文档

Phase 1：项目初始化

• 初始化 Flask 项目结构
• 初始化配置文件
• 初始化依赖管理
• 初始化数据库连接
• 初始化基础模板与静态资源目录（目录已创建，页面内容待后续填充）

Phase 2：基础能力

• 实现登录 / 登出
• 实现账号模型
• 实现密码加密存储
• 实现角色权限拦截
• 实现审计日志模型与基础写入（已接入认证链路）

Phase 3：业务数据模型

• 实现户模型
• 实现成员模型
• 实现礼金记录模型
• 实现动态选项模型（option_items）
• 实现户级回礼状态字段
• 实现软删除机制
• 实现并发编辑版本字段

Phase 4：页面能力

• 实现管理首页（MVP：统计卡片 + 快速搜索 + 只读总览）
• 实现默认只读表格（MVP：户级列表只读展示）
• 实现单条编辑流程（管理员独立编辑页 + 保存前确认摘要 + 审计日志）
• 实现长辈专用搜索与编辑页（MVP：搜索 → 选择 → 有限字段编辑 → 审计日志）
• 实现账号管理页（列表、创建、编辑显示名/角色、重置密码、启停账号）
• 实现审计日志页（倒序列表、按人/动作筛选、详情查看 before/after 快照）
• 实现“新增一户”最小创建流程（管理首页入口 + 新建页 + 创建审计日志）

Phase 5：搜索与统计

• 实现中文搜索
• 实现拼音搜索
• 实现首字母搜索
• 实现多字段筛选（管理首页已支持 side / invite_status / attendance_status 组合筛选）
• 实现排序
• 实现 count 与统计卡片

Phase 6：导入导出

• 设计 CSV 模板
• 实现 CSV 导出
• 实现 CSV 上传预览
• 实现 CSV 校验
• 实现冲突检测与处理
• 审计记录导入行为

Phase 7：已完成增强与交付

• 一键开发启动与演示 seed 数据
• 后台左侧边栏导航
• 管理首页统计前置与搜索/筛选分层布局
• 压力测试数据命令 seed-stress
• 管理首页与长辈页 live refresh
• 长辈页移动端优先 bottom-sheet 编辑模式
• 独立统计与报表页
• light / dark 双主题切换
• Python + Playwright 端到端测试基础设施与主要操作闭环补齐
• Linux 单机生产部署交付：ProductionConfig、Python 3.13 容器镜像、Docker 入口脚本、环境变量示例、安装/部署/校验脚本、生产文档与运维文档

3. 当前重点任务建议

当前核心可用版本已经形成闭环，范围包括：登录与权限、一键开发启动与演示 seed、压力测试 seed-stress、后台左侧边栏、管理首页只读总览、中文 / 拼音 / 首字母搜索、组合筛选、排序、筛选统计、管理首页与长辈页动态刷新、户级单条编辑、管理端新增一户、管理端家庭成员 CRUD、管理端礼金明细 CRUD 与自动汇总回写、长辈专用搜索与 bottom-sheet 有限字段编辑、独立统计与报表页、账号管理、审计日志、CSV 导入导出、light / dark 双主题、Python + Playwright 端到端测试，以及 Linux 单机生产容器化部署文档与脚本交付。

当前阶段说明：

• 功能需求先暂停扩展，当前以部署落地、文档同步、运维校验和必要缺陷修复为主
• 最新一次本地全量测试结果：.venv/bin/python -m pytest tests → 107 passed
• 如未来恢复功能迭代，可参考桌席安排、CSRF / 安全加固、统计报表增强、历史往来能力等方向

4. 风险与注意事项

4.1 数据库差异风险

MySQL 与 SQLite 存在差异，开发时应减少特性耦合。

4.2 搜索准确性风险

拼音搜索存在多音字问题，后续可能需要补充自定义词典。

4.3 误操作风险

若首页默认可编辑，会明显增加长辈和非熟练用户误操作概率。

4.4 CSV 污染风险

若没有导入预览和冲突处理，批量导入很容易污染数据。

5. 文档维护约定

后续开发中应遵循：

• 需求变更优先更新 docs/requirements.md
• 技术方案变更优先更新 docs/technical-design.md
• 开发进展实时更新 docs/todo-progress.md
• README 作为总入口保持同步更新

6. 本次会话沉淀

本次会话已经明确沉淀的新增进展：

• 已完成 HappyWedding（hw）项目命名落地
• 已完成 Flask + SQLAlchemy 项目骨架
• 已完成 6 张核心表模型定义
• 已完成健康检查路由
• 已完成 .venv 本地开发工作流
• 已完成基础测试并验证通过（当前最新一次 .venv/bin/python -m pytest tests 结果为 102 passed）
• 已完成数据库迁移、seed、登录、密码哈希、Session、角色权限边界与认证链路审计写入
• 已完成 SSR 页面 MVP：登录页、管理首页只读总览、管理端单条编辑页、长辈专用搜索与有限字段编辑页
• 已为长辈专用编辑页补充保存前确认摘要、显式防误操作提示、未保存离开提醒、儿童人数前端校验与服务端兜底校验测试，进一步贴合“先确认对象、再确认修改”的交互原则
• 已为管理首页与长辈页补充固定枚举值的中文友好文案映射，减少 pending / groom_side / not_given 等原始值直接暴露给最终用户
• 已完成页面样式基线从 Skeleton CSS 切换到 Tailwind CSS，并进一步迁移到 Tailwind CLI 编译模式
• 已将审计服务扩展到长辈页与管理端业务保存场景（update_household_entry / update_household）
• 已完成管理员侧礼金明细闭环：支持明细新增、编辑、软删除、户级礼金自动汇总回写与审计日志
• 已完成 Linux 单机生产容器化部署文档与配套脚本交付
• 当前进入部署与文档同步阶段，功能需求暂不继续扩展
• 已完成管理端家庭成员管理闭环：在户级编辑页支持成员列表展示、成员新增/编辑/删除，以及对应审计日志与测试覆盖
• 已完成管理首页搜索与统计增强：支持中文 / 拼音 / 首字母搜索、组合筛选、排序、筛选结果计数与摘要统计
• 已完成 CSV 导入导出闭环：模板下载、导出全部、导出当前筛选、上传预览、字段校验、冲突检测、确认导入、预览过期控制与导入审计日志
• 已完成一键开发启动与演示 seed：支持 flask seed-demo 与 flask dev-bootstrap，可自动准备本地演示账号和 3 户演示数据
• 已完成后台左侧边栏与管理首页布局优化：一级入口迁移到左侧边栏，统计信息前置，搜索框独立一栏，筛选/排序单独一栏
• 已完成 Python + Playwright E2E：当前已覆盖管理员搜索编辑、长辈录入页保存、管理端新增一户、家庭成员 CRUD、账号管理提交链路、审计日志筛选与详情、CSV 导入导出闭环、认证与权限边界；同时已补充 GET /reports、GET /?partial=results、GET /entry/?partial=search-results、GET /entry/?partial=edit-sheet 的页面测试覆盖
• 已完成压力测试数据能力：支持 flask seed-stress 生成默认 1000 户、平均每户 4 人、STRESS- 前缀的大规模测试数据
• 已完成管理首页与长辈页 live refresh：基于 partial HTML、300ms debounce、fetch 和 DOM 局部替换
• 已完成长辈页移动端优先 bottom-sheet 编辑模式，保留版本校验、儿童红包校验、未保存离开提醒与保存前确认摘要
• 已完成独立统计与报表页，以及 light / dark 双主题切换

以上内容已经纳入当前文档基线。