架构决策：BusinessEvent 业务事件落库

日期：2026-08-01

状态：已采纳，待生产数据迁移

Owner Agent：Backend Core（报告/留资写入点联动 Report Media Backend）

Service Lock：BusinessEvent*、预约/报告/留资事件调用点、工作台报告漏斗

Paired QA：Core Flow QA + Report Share QA

Data Model Review Required：Yes

Access / Privacy Review Required：Yes

1. 决策背景

此前本体中的 Event 多数只表达“动作发生后应存在的事实”，并没有统一事件表。报告打开仅写应用日志，工作台只能由前端临时拼预约、报告和留资，无法可靠支持经营漏斗、StoreCustomer 时间线、回访归因和复购统计。

2. 冻结模型

BusinessEvent 是不可变事实，不是业务对象当前状态，也不是消息队列。

字段	语义
`event_id`	随机事件 ID；不使用数据库自增 ID 做外部关联
`event_type` / `event_version`	过去时事件名与 schema 版本
`store_id`	强制门店数据范围
`store_customer_id`	可选门店客户稳定关系，供客户时间线使用
`aggregate_type` / `aggregate_id`	事件对应的 Appointment、Report 或 ReportLead
`actor_user_id` / `actor_role`	操作人快照；匿名公开事件可空
`source`	customer / admin / public_report / system / migration
`occurred_at`	业务事实发生时间
`metadata_json`	服务端白名单低敏维度，不接受原始请求体
`idempotency_key`	可选稳定键，保证一个业务结果只落一条
`create_time`	事件入库时间

事件表只追加，不提供更新、软删除或通用明细 API。

3. 第一批真实事件

事件	可靠触发点	幂等口径
`appointment_created`	预约保存成功	appointment ID
`appointment_status_changed`	合法状态迁移保存成功	appointment ID + 目标状态
`service_started`	`new -> doing`	appointment ID
`service_completed`	`doing -> done`	appointment ID
`report_submitted`	报告及图片保存成功	report ID
`report_sent`	门店员工首次显式确认宠主实际收到	report ID；`report_sent:{reportId}`
`report_opened` / `report_reopened`	公开报告打开埋点	每次有效打开；统计按 report ID 去重
`lead_submitted`	每次留资提交成功	可重复记录；漏斗按 lead ID 去重

2026-08-02 增量决策：report_sent 已通过显式确认状态机可靠落地；复制链接、二维码和预览不构成发送。详见《架构决策-报告确认发送状态-2026-08-02》。follow_up_completed、rebook_created 仍无可靠状态机或归因字段，本阶段明确不伪造。

4. 隐私边界

事件表不得保存手机号、报告 token 或 token hash、媒体 URL、IP、openid/unionid、备注、内容全文、密码、密钥或任意请求体。
报告打开接口只用 token 在服务端定位 Report，事件仅保存内部 report ID；日志继续只记 SHA-256 前 8 位 hex。
管理端只开放按当前会话 storeId 聚合的漏斗结果，不开放事件明细。

5. 一致性与迁移

预约、状态迁移、报告提交与事件写入处于同一数据库事务。
留资沿用现有并发幂等事务边界；重复提交可产生动作事件，漏斗按 lead ID 去重，不放大转化数。
历史迁移只回填可从数据库确定的预约创建、报告提交、由报告确认的服务完成和留资提交。
历史报告打开与开始服务时间无法可靠恢复，不做猜测性回填。

迁移顺序：

20260801_split_service_identity.sql
20260801_create_store_customer.sql
20260801_create_business_event.sql

6. BusinessEvent 与 AuditLog 边界

BusinessEvent 记录“经营上发生了什么”；AuditLog 记录“谁对受保护配置或数据做了什么变更”。本阶段先完成服务闭环事实，后续在门店开通、员工权限、设置修改和敏感操作进入生产化时建立独立 AuditLog，不把安全审计字段混入经营事件。

7. 验收

mvn test 全绿，迁移 SQL 集成测试通过。
npm run build（admin）通过，工作台“已打开”来自事件汇总。
customer 访问工作台事件汇总为 403；boss/staff 只能读取本店。
事件 metadata 隐私单测证明不含原始 token、手机号或 IP。
本体校验通过且 controller/entity 0 漂移。

4.4 KiB Raw Blame History Unescape Escape