hw/docs/requirements.md

需求说明

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 入口脚本、环境变量示例、安装/部署/校验脚本、生产部署与运维文档）

当前阶段边界

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