婚礼户级人员管理系统

这是一个面向婚礼筹备场景的 Web 管理系统，用于按“户”为单位管理邀请、出席、礼金、回礼、桌席安排、CSV 导入导出、审计日志与账号权限。

当前项目已经形成可测试的核心可用版本，已经落地 Flask 应用骨架、6 张核心数据表模型、数据库迁移能力、seed 初始化命令、登录与权限、管理端与长辈端关键页面、搜索排序统计增强、CSV 导入导出闭环，以及对应测试与开发文档。本文档作为后续开发、协作、验收的总入口。

0. 当前状态速览

已完成的核心可用版本功能

• 已支持 flask db init / migrate / upgrade
• 已支持 flask seed-admin / seed-options / seed-all / seed-demo / seed-stress / dev-bootstrap
• 已生成首个 migration：migrations/versions/cc52be716e44_initial_migration.py
• 已验证 SQLite 本地库下迁移和 seed 命令链路
• 已完成最小可用认证闭环：登录 / 登出、密码校验、Session、当前用户上下文、角色访问边界
• 已完成审计日志基础写入（认证链路 + 业务保存）：登录成功、登录失败、停用账号登录、登出、未登录访问、越权访问、创建户、管理端保存户、长辈页保存户、创建账号、更新账号、重置密码、启停账号
• 已提供可用的 SSR 页面闭环：
  • 登录页
  • 管理首页只读总览（含左侧边栏、统计信息前置、中文 / 拼音 / 首字母搜索、组合筛选、排序、筛选结果摘要、最近更新人、状态中文友好文案、边输入边动态刷新结果）
  • 管理端单条编辑页
  • 管理端新增一户入口与最小创建流程
  • 管理端家庭成员管理（HouseholdMember）：在户级编辑页支持成员列表、新增、编辑、删除与审计日志
  • 管理端礼金明细管理（gift_records）：在户级编辑页支持礼金明细列表、新增、编辑、软删除、自动汇总回写与审计日志
  • 长辈专用搜索与有限字段编辑页（含移动端优先搜索结果卡片、bottom-sheet 弹窗编辑、保存前确认摘要、显式防误操作提示、未保存离开提醒、儿童人数校验、边输入边动态刷新结果）
  • 统计与报表页（独立展示总览统计、礼金 Top 10、最近更新户）
  • 管理员账号管理页（列表、创建、编辑、重置密码、启停账号）
  • 管理员审计日志页（倒序列表、筛选、详情查看 before/after 快照）
  • CSV 导入导出页与首页入口（模板下载、导出全部、导出当前筛选、上传预览、校验、冲突处理、确认导入、导入审计日志）
• light / dark 双主题切换（localStorage 持久化、首屏防闪烁、Tailwind CLI 编译样式）
  • 压力测试数据生成命令 flask seed-stress（默认 1000 户、平均每户 4 人、STRESS- 前缀）
  • Python + Playwright 端到端测试（管理员搜索编辑、长辈录入页保存、管理端新增户、家庭成员 CRUD、账号管理提交链路、审计日志筛选与详情、CSV 导入导出闭环、认证与权限边界）
• 当前最新一次本地验证结果：
  • .venv/bin/python -m pytest tests → 102 passed
  • .venv/bin/python -m pytest tests/e2e -q → 请以本地最近一次执行结果为准（需先安装 Playwright Chromium）
  • bash -n scripts/generate-secrets.sh scripts/install-linux-systemd.sh scripts/deploy-systemd.sh scripts/verify-deployment.sh → 通过
• 已补齐 Linux 单机生产部署交付：ProductionConfig、Gunicorn、systemd 服务模板、Caddy 反向代理模板、环境变量示例、部署/校验脚本、生产部署与运维文档

本地最快验证路径

.venv/bin/python -m flask dev-bootstrap

在启动应用前，如首次拉取仓库或前端样式有变更，请先编译 CSS：

npm install
npm run build:css

日常前端样式开发建议额外开启监听：

npm run watch:css

其中：

• Tailwind 源文件：app/static/src/styles.css
• 编译输出：app/static/css/main.css
• 模板通过 {{ url_for('static', filename='css/main.css') }} 引用编译结果

随后执行：

.venv/bin/python -m flask dev-bootstrap

该命令会自动完成：

• flask db upgrade
• flask seed-all
• flask seed-demo
• 输出演示账号
• 启动本地开发服务

默认演示账号：

• admin / ChangeMe123!
• editor-demo / EditorDemo123!
• entry-demo / EntryDemo123!

如需快速构造大规模压力数据，可额外执行：

.venv/bin/python -m flask seed-stress

默认会生成：

• 1000 户压力测试 household
• 平均每户 4 人
• STRESS- 前缀户编码

也支持自定义参数：

.venv/bin/python -m flask seed-stress --household-count 500 --members-per-household 3 --prefix TEST-

当前版本状态说明

• 当前版本以“核心可用版 + 生产部署交付”作为阶段性基线，功能范围暂不继续扩展
• 已交付 Linux 单机生产部署方案：Caddy + systemd + Gunicorn，并补齐部署脚本与运维文档
• 如未来恢复功能迭代，可优先考虑桌席安排、更细粒度权限 / CSRF 加固，以及更丰富的统计分析能力

当前内部版本已知限制

• 当前表单 POST 流程尚未接入显式 CSRF Token 机制，当前版本主要面向受控的内部使用场景；正式发布前建议补充 CSRF 防护。
• 管理端已支持家庭成员 CRUD、礼金明细 CRUD 与自动汇总回写、搜索/排序/筛选统计增强、管理页与长辈页 live refresh、独立统计报表页、CSV 导入导出与审计日志，但桌席安排与正式发布级安全加固仍未完成。

1. 项目目标

系统主要服务于婚礼筹备过程中的家庭成员协作，尤其要兼顾：

• 主筹备人对全量数据的管理需求
• 父母长辈对已录入邀请对象的简单搜索与信息完善需求
• 婚礼现场和婚前阶段对礼金、到场、回礼的登记需求
• 婚后对礼簿、人情往来、修改记录的追溯需求

系统核心不是“按个人管理通讯录”，而是：

以“户”为单位的邀请、到场、礼金、回礼、桌席安排、长期人情往来台账系统。

2. 当前已确认技术栈

• 后端：Python 3
• 前端：jQuery + Tailwind CSS（CLI 编译输出到 Flask app/static/）
• 数据库：MySQL（正式环境）/ SQLite（本地测试）
• 当前数据模型基线：6 张核心表（accounts、households、household_members、gift_records、audit_logs、option_items）
• 页面形态：服务端渲染为主，jQuery 做增强交互
• 数据导入导出：CSV
• 中文搜索：支持中文、拼音、首字母缩写
• 登录机制：简单账号密码登录
• 审计要求：记录谁在什么时候修改了什么

3. 文档导航

• 需求说明
• 技术方案与详细设计
• 开发 TODO 与进展
• 开发环境与启动说明
• 生产部署说明
• 生产运维说明

4. 当前范围（已明确）

4.1 业务范围

• 按户管理邀请对象
• 每户设置户主代表
• 每户维护家庭成员信息
• 记录预计到场人数、实际到场人数
• 标记儿童及需发红包的儿童
• 记录礼金、礼品、伴手礼、喜糖、红包发放情况
• 支持桌席安排所需的关系与偏好信息
• 支持 CSV 导入导出
• 支持多字段搜索、筛选、排序、统计
• 支持长辈专用搜索与编辑入口
• 支持后台账号管理与审计日志

4.2 用户角色

• 管理员：主筹备人，拥有完整管理权限
• 普通管理账号：可查看、编辑、录入
• 长辈专用账号：只允许登录专用搜索与编辑页，方便追踪具体修改人

5. 核心设计原则

• 默认只读，避免误操作
• 显式点击“修改”后才允许编辑
• 保存前尽量提供确认
• 批量导入必须先预览、校验、再确认
• 页面简洁，适合父母长辈使用
• 重要操作必须可追溯
• 账号身份与录入记录绑定

6. 快速约定（当前基线）

为避免后续开发时反复讨论，当前先约定以下实现基线：

• 第一个管理员账号在项目初始化阶段手动创建
• 后续新账号由管理员在系统后台创建
• 密码不明文存储，必须做哈希处理
• 登录态采用服务器 Session 方案
• 已实现登录后按角色跳转：entry_only 默认进入 /entry/，其余角色默认进入 /
• 已实现安全的 next 参数校验，仅允许站内跳转
• 长辈专用账号登录后默认进入专用搜索与编辑页
• 本次婚宴涉及的户由管理员预先录入系统
• 长辈账号只能搜索既有户并修改有限字段，不允许纯新增户
• 长辈修改行为写入审计日志，便于追踪是谁修改的

7. 当前维护重点

当前仓库已形成可测试的核心可用版本，并补齐了 Linux 单机生产部署文档与配套脚本。按照当前约定，功能需求先暂停扩展，后续以文档同步、部署落地、运维校验和必要缺陷修复为主。

如未来重新进入功能迭代阶段，可参考以下方向：

1. 桌席安排与更完整的婚宴现场协作能力
2. CSRF 与更多正式发布前安全加固
3. 统计报表、历史往来与数据沉淀能力增强

8. 备注

更多需求会继续补充，本仓库中的文档应持续更新，作为后续开发唯一的书面基线。