# 开发 TODO 与进展

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

## 1. 当前阶段

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

已完成：

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

## 2. 总体路线图

## Phase 0：方案固化

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

## Phase 1：项目初始化

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

## Phase 2：基础能力

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

## Phase 3：业务数据模型

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

## Phase 4：页面能力

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

## Phase 5：搜索与统计

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

## Phase 6：导入导出

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

## Phase 7：已完成增强与交付

- [x] 一键开发启动与演示 seed 数据
- [x] 后台左侧边栏导航
- [x] 管理首页统计前置与搜索/筛选分层布局
- [x] 压力测试数据命令 `seed-stress`
- [x] 管理首页与长辈页 live refresh
- [x] 长辈页移动端优先 bottom-sheet 编辑模式
- [x] 独立统计与报表页
- [x] light / dark 双主题切换
- [x] Python + Playwright 端到端测试基础设施与主要操作闭环补齐
- [x] 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 双主题切换

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