# 婚礼户级人员管理系统

这是一个面向婚礼筹备场景的 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` → `107 passed`
  - `.venv/bin/python -m pytest tests/e2e -q` → 请以本地最近一次执行结果为准（需先安装 Playwright Chromium）
  - `bash -n scripts/generate-secrets.sh scripts/install-linux-container.sh scripts/deploy-container.sh scripts/verify-container-deployment.sh` → 通过
- 已补齐 Linux 单机生产容器化部署交付：`ProductionConfig`、Python 3.13 容器镜像、Docker 入口脚本、环境变量示例、安装/部署/校验脚本、生产部署与运维文档

### 本地最快验证路径

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

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

```bash
npm install
npm run build:css
```

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

```bash
npm run watch:css
```

其中：

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

随后执行：

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

该命令会自动完成：

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

默认演示账号：

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

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

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

默认会生成：

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

也支持自定义参数：

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

### 当前版本状态说明

- 当前版本以“核心可用版 + 生产部署交付”作为阶段性基线，功能范围暂不继续扩展
- 已交付 Linux 单机生产部署方案：Python 3.13 容器 + 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. 文档导航

- [需求说明](./docs/requirements.md)
- [技术方案与详细设计](./docs/technical-design.md)
- [开发 TODO 与进展](./docs/todo-progress.md)
- [开发环境与启动说明](./docs/development-setup.md)
- [生产部署说明](./docs/production-deployment.md)
- [生产运维说明](./docs/production-ops.md)

## 4. 当前范围（已明确）

### 4.1 业务范围

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

### 4.2 用户角色

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

## 5. 核心设计原则

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

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

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

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

## 7. 当前维护重点

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

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

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

## 8. 备注

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