# 需求说明

## 1. 项目背景

婚礼筹备过程中，需要系统化管理邀请对象、出席情况、礼金往来、回礼发放、桌席安排，以及婚后的人情往来查询。

本系统以“户”为基本管理单位，而不是以“个人”为唯一单位。

原因包括：

- 邀请通常按户进行
- 礼金通常按户记录
- 桌席安排会参考整户人数与关系
- 婚后还礼也通常按户回溯

## 2. 核心业务对象

### 2.1 户

户是系统中的主实体。

每户包含：

- 户主姓名
- 联系方式
- 所属侧（男方 / 女方 / 共同）
- 关系分类
- 具体关系
- 标签
- 邀请状态
- 到场状态
- 预计人数
- 实际人数
- 儿童人数
- 需红包儿童人数
- 礼金情况
- 回礼情况
- 备注

### 2.2 家庭成员

每户可有多个成员。

成员信息包括：

- 姓名
- 与户主关系
- 性别（可选）
- 年龄段（可选）
- 是否儿童
- 是否需要红包
- 是否预计到场
- 是否实际到场
- 备注

### 2.3 礼金与礼品记录

按户记录，但允许保留多笔明细。

字段包括：

- 记录类型（礼金 / 礼品 / 婚前给 / 当天给 / 婚后补给）
- 金额
- 礼品名称
- 估值（可选）
- 记录时间
- 记录人
- 备注

### 2.4 回礼发放记录

包括：

- 喜糖是否发放
- 伴手礼是否发放
- 儿童红包是否发放
- 其他礼品是否发放
- 发放时间
- 发放人
- 备注

### 2.5 账号与审计记录

系统需要支持简单账号密码登录，用于审计与权限控制。

每个账号至少包括：

- 账号名
- 密码
- 账号角色
- 状态（启用 / 停用）
- 创建时间
- 最后登录时间

审计日志至少记录：

- 操作时间
- 操作账号
- 操作页面
- 操作类型
- 操作对象
- 修改前内容摘要
- 修改后内容摘要

## 3. 用户角色与使用场景

### 3.1 管理员

主要是主筹备人。

职责：

- 查看全量数据
- 新增、编辑、删除或软删除记录
- 创建账号
- 重置密码
- 导入导出 CSV
- 查看审计日志
- 配置长辈专用账号

### 3.2 普通管理账号

可由家庭成员协助使用。

职责：

- 查看首页列表
- 录入和编辑业务数据
- 导出数据
- 查看部分日志（可选）

### 3.3 长辈专用账号

专门给父母长辈使用。

特点：

- 只允许访问专用录入页面
- 不进入复杂管理首页
- 用简单账号密码登录
- 每个长辈账号可以有专属账号名
- 后台可追踪该账号修改了哪些数据

该设计的目的不是做复杂权限体系，而是：

- 简化长辈使用体验
- 区分是谁录入的
- 为审计日志提供身份基础

## 4. 业务流程需求

### 4.1 名单整理

- 管理员预先录入本次婚宴涉及的所有户
- 录入户主与成员信息
- 打标签
- 标记所属侧与关系

### 4.2 邀请管理

- 记录是否已邀请
- 记录是否已回复
- 记录回复内容
- 更新预计人数

### 4.3 到场管理

- 记录实际到场人数
- 标记哪些成员到场
- 支持“礼到人不到”
- 支持“部分到场”

### 4.4 礼金管理

- 按户记录礼金
- 允许多笔记录汇总到一户
- 记录礼品
- 记录记录人和记录时间

### 4.5 回礼管理

- 标记是否发放喜糖
- 标记是否发放伴手礼
- 标记儿童红包发放情况

### 4.6 桌席安排准备

系统当前阶段不一定立即实现完整桌席图，但必须预留字段支持后续安排：

- 所属侧
- 关系分类
- 具体关系
- 人数
- 儿童情况
- 桌席偏好
- 同桌 / 避免同桌信息（后续增强）

### 4.7 婚后查询与还礼参考

- 查询某户礼金历史
- 查询该户的来往记录
- 为未来还礼提供参考

## 5. 页面需求

## 5.1 管理首页

首页是系统主页面，聚焦高频操作，采用“统计总览 + 搜索筛选 + 结果区”的数据密集型管理布局。

必须支持：

- 默认只读
- 单行显式点击“修改”
- 确认保存
- 多字段搜索
- 多字段筛选
- count 统计
- 字段排序
- 管理首页边输入边动态刷新结果
- 低频的 CSV 导入导出能力收纳到页面右上角
- 新增一户（管理员/普通管理账号）
- 查看最近修改
- 将完整统计与报表拆分到独立页面

### 首页建议展示字段

- 户主姓名
- 联系方式
- 所属侧
- 关系分类
- 具体关系
- 标签
- 预计人数
- 实际人数
- 儿童数
- 礼金金额
- 邀请状态
- 到场状态
- 伴手礼状态
- 喜糖状态
- 更新时间
- 操作

## 5.2 长辈专用搜索与编辑页

必须满足：

- 独立 URL
- 独立登录后可访问
- 页面非常简洁
- 不允许纯新增户
- 只允许搜索系统中已存在的户
- 先选择目标户，再进入编辑
- 搜索输入时边输入边动态刷新结果
- 编辑表单适配移动端，以弹窗 / bottom-sheet 形式呈现
- 不展示复杂管理表格和高级筛选
- 保存后给出明显成功反馈

页面流程建议：

1. 搜索户主姓名或手机号
2. 展示结果卡片列表
3. 点击“修改”打开 bottom-sheet 编辑表单
4. 显示目标户确认页
5. 进入简化编辑表单
6. 保存前再次确认

建议允许修改字段：

- 到场状态
- 实际到场人数
- 儿童人数
- 需红包儿童人数
- 礼金金额
- 礼金方式
- 礼金记录场景
- 喜糖状态
- 伴手礼状态
- 儿童红包状态
- 备注
- 联系电话（仅纠正用，可选）

建议只读展示字段：

- 户主姓名
- 所属侧
- 关系分类
- 具体关系
- 预计人数

## 5.3 统计与报表页

必须支持：

- 独立 URL
- 展示总户数、总预计人数、儿童数、礼金总额等总览统计
- 展示礼金金额 Top 榜单
- 展示最近更新户列表
- 作为管理首页之外的独立信息查看页，避免首页承担过多低频信息

## 5.4 CSV 导入导出页

必须支持：

- 下载 CSV 模板
- 导出全部数据
- 导出当前筛选结果
- 上传 CSV
- 预览导入数据
- 校验字段
- 提示冲突
- 选择跳过 / 覆盖 / 合并
- 确认导入

## 5.5 账号管理页

必须支持：

- 新增账号
- 编辑账号
- 重置密码
- 启用 / 停用账号
- 指定角色
- 为长辈创建专属录入账号
- 查看账号最近登录时间

## 5.6 审计日志页

必须支持：

- 查看最近操作
- 按账号筛选
- 按操作类型筛选
- 按时间范围筛选
- 查看单次修改详情

## 6. 搜索需求

系统必须支持多字段搜索，并兼容中文场景。

### 6.1 支持的搜索方式

- 中文直接搜索
- 拼音全拼搜索
- 首字母缩写搜索
- 混合搜索
- 大小写不敏感

### 6.2 建议覆盖字段

- 户主姓名
- 成员姓名
- 关系分类
- 具体关系
- 标签
- 手机号
- 备注

## 7. 筛选、排序、统计需求

### 7.1 多字段筛选

至少支持：

- 所属侧
- 关系分类
- 邀请状态
- 到场状态
- 是否有儿童
- 儿童是否需红包
- 礼金状态
- 礼金金额区间
- 人数区间
- 标签

### 7.2 排序

至少支持：

- 户主姓名
- 关系分类
- 预计人数
- 实际人数
- 儿童数
- 礼金金额
- 更新时间

### 7.3 count 统计

筛选和搜索后，应实时显示：

- 当前匹配户数
- 当前匹配总人数
- 当前匹配儿童数
- 当前匹配礼金总额
- 当前匹配已确认出席户数

## 8. 防呆需求

系统必须重点考虑误操作风险。

### 8.1 编辑防呆

- 默认只读
- 编辑需显式进入
- 保存前确认
- 取消编辑不污染原数据
- 离开编辑页面时提醒未保存（当前已在长辈专用编辑页落地）

### 8.2 删除防呆

- 删除需二次确认
- 建议采用软删除
- 提供短时撤销能力

### 8.3 导入防呆

- 先预览再导入
- 导入前校验
- 冲突提示清晰
- 导入前生成数据快照（后续实现）

### 8.4 长辈使用防呆

- 单列布局
- 大字体
- 大按钮
- 标签清晰
- 不依赖隐藏手势
- 不自动关闭关键提示

## 9. 当前已识别的边界场景

- 一户多位成员，部分出席
- 礼到人不到
- 同一户多次给礼
- 同一户多人代送礼
- 单亲 / 重组家庭
- 有儿童但并非所有儿童都需红包
- CSV 导入时与已有记录冲突
- 多个账号同时编辑同一条记录

## 10. 当前阶段优先级

### 核心可用版本（当前已优先完成）

- 登录
- 账号管理
- 审计日志
- 户级列表与单条编辑
- 新增一户最小创建流程
- 首页搜索、组合筛选、排序、筛选统计与动态刷新
- 管理端家庭成员管理（HouseholdMember）：成员列表、新增、编辑、删除
- 长辈专用搜索、实时刷新与 bottom-sheet 编辑页
- 独立统计与报表页
- 中文 / 拼音 / 首字母搜索
- CSV 导入导出（模板下载、导出全部、导出当前筛选、上传预览、校验、冲突处理、确认导入）
- light / dark 双主题切换
- 压力测试数据生成功能（`seed-stress`）
- Linux 单机生产部署交付（`ProductionConfig`、Python 3.13 容器镜像、Docker 入口脚本、环境变量示例、安装/部署/校验脚本、生产部署与运维文档）

### 当前阶段边界

- 当前版本已形成“核心可用版 + 生产部署交付”的阶段性基线
- 按当前约定，功能需求先暂停扩展，优先保证部署落地、文档同步与必要缺陷修复
- 如未来恢复功能迭代，可优先考虑更丰富统计报表分析、桌席安排、历史往来追溯增强、数据快照回滚、更细权限控制与更智能的还礼参考