vault backup: 2026-05-26 01:18:18

2026-05-26 01:18:18 +08:00
parent 669d3b4400
commit 7cdf0ec9a4
4 changed files with 850 additions and 3 deletions
--- a/prop-acc/scenarios/billing/audit-activitylog-trace.md
+++ b/prop-acc/scenarios/billing/audit-activitylog-trace.md
@@ -0,0 +1,311 @@
+---
+title: prop-acc · billing · 场景 - activitylog 审计追溯
+aliases:
+  - activitylog 审计
+  - 操作日志查询
+  - audit-activitylog-trace
+  - 场景-activitylog 追溯
+tags:
+  - 场景
+  - prop-acc
+  - 账单
+  - 审计
+  - 合规
+audience:
+  - 业务人员
+  - 财务
+  - 审计师
+  - 法务
+status: 已发布
+sub_feature: billing
+last_review: 2026-05-26
+code_version: 2026-05-22
+---
+
+# 场景:activitylog 审计追溯
+
+billing 模块**首次启用** `spatie/laravel-activitylog`(prop-acc 其他模块仅用 meta JSON)。所有关键操作(作废 / 批删 / 挂起 / 恢复 / 收款 / 创建)记 activitylog,审计 / 内审 / 法务可**精准追溯**:谁 / 什么时候 / 在哪 / 改了什么。
+
+## 典型情境
+
+> [!example] 真实情境
+> 5 月 20 日,内审师审计 5 月嘉禾花园账单数据,发现:
+>
+> - 5 月 15 日有一次**批量删除 92 张账单**(`bulk_deleted`)
+> - 同日有 5 条 **bill voided**(账单作废)
+> - 还有几张账单的 status 从 Suspended → Unpaid(恢复)
+>
+> 审计师要查清:
+> - 谁操作的?
+> - 操作的原因?
+> - 影响了哪些具体账单?
+> - 是否合规?
+
+## 业务人员 / 审计师视角
+
+### 第 1 步:确定查询维度
+
+- **谁操作**:`causer_id`(操作员)
+- **什么时候**:`created_at` 范围
+- **操作类型**:`event`(created / voided / bulk_deleted / suspended / resumed / collected / split)
+- **针对哪个对象**:`subject_type` + `subject_id`(单条操作)/ properties.affected_bill_nos(批量)
+- **操作详情**:`properties` JSON 字段
+
+### 第 2 步:运行 SQL 查询
+
+#### 查询 1:某员工某月所有操作
+
+```sql
+SELECT
+    id,
+    event,
+    subject_type,
+    subject_id,
+    properties,
+    created_at
+FROM activity_log
+WHERE causer_id = ?    -- 王主管 ID
+  AND created_at BETWEEN '2026-05-01' AND '2026-05-31 23:59:59'
+ORDER BY created_at DESC;
+```
+
+返回:
+
+| id | event | subject | properties (节选) | created_at |
+|---|---|---|---|---|
+| 1023 | bulk_deleted | (null) | mode=DeleteAndVoid, reason="...", deleted=92, voided=5 | 2026-05-15 14:32 |
+| 1022 | voided | Bill #500 | reason="业务调整", from_status=Partial | 2026-05-15 14:31 |
+| 1021 | collected | Bill #321 | amount=800, channel=微信 | 2026-05-10 11:23 |
+| ... | ... | ... | ... | ... |
+
+#### 查询 2:某 Bill 的所有操作历史
+
+```sql
+SELECT
+    event,
+    causer_id,
+    properties,
+    created_at
+FROM activity_log
+WHERE subject_type = 'App\\Models\\Bill'
+  AND subject_id = ?    -- 具体 Bill ID
+ORDER BY created_at ASC;
+```
+
+返回该 Bill 的**全生命周期**:created → collected → voided 等。
+
+#### 查询 3:批量删除的详情
+
+```sql
+SELECT
+    causer_id,
+    properties->>'$.mode' AS mode,
+    properties->>'$.reason' AS reason,
+    properties->>'$.total_selected' AS selected,
+    properties->>'$.deleted_count' AS deleted,
+    properties->>'$.voided_count' AS voided,
+    properties->>'$.blocked_count' AS blocked,
+    JSON_LENGTH(properties->'$.affected_bill_nos') AS affected_count,
+    created_at
+FROM activity_log
+WHERE event = 'bulk_deleted'
+  AND created_at BETWEEN ? AND ?
+ORDER BY created_at DESC;
+```
+
+可看出**每次批删**的统计 + 原因。
+
+#### 查询 4:某 bill_no 是否被批删 / 作废过
+
+```sql
+SELECT *
+FROM activity_log
+WHERE event = 'bulk_deleted'
+  AND JSON_CONTAINS(
+      properties->'$.affected_bill_nos',
+      JSON_QUOTE('B-202605-501-001 [DELETED]')
+  );
+```
+
+或:
+
+```sql
+-- 灵活模糊匹配
+SELECT *
+FROM activity_log
+WHERE event = 'bulk_deleted'
+  AND properties->'$.affected_bill_nos' LIKE '%B-202605-501-001%';
+```
+
+可追溯到**已物理删的 Bill** 是何时被谁删的。
+
+### 第 3 步:解读 properties
+
+不同 event 的 properties 结构不同:
+
+| event | properties 主要字段 |
+|---|---|
+| `created`(账单创建)| `bill_no, amount, fee_type_id, resident_id` |
+| `collected`(收款)| `amount, channel, receipt_id` |
+| `voided`(单作废)| `reason, from_status, to_status, bill_no, amount, paid_amount` |
+| `suspended`(挂起)| `reason, from_status, to_status, bill_no` |
+| `resumed`(恢复)| `reason, from_status, to_status, bill_no` |
+| `split`(拆账单)| `target_resident, amount_split, original_bill_id, new_bill_id` |
+| `bulk_deleted`(批删)| `mode, reason, total_selected, deleted_count, voided_count, blocked_count, affected_bill_nos[]` |
+
+详见 [[smart-bulk-delete-design]]"activitylog 设计"段。
+
+### 第 4 步:出审计报告
+
+```markdown
+# 2026 年 5 月 嘉禾花园账单操作审计报告
+
+## 审计范围
+- 时段:2026-05-01 至 2026-05-31
+- 模块:billing
+- 关注操作:bulk_deleted, voided
+
+## 高敏操作统计
+- 批量删除(bulk_deleted):2 次
+  - 5/15 王主管:92 删 + 5 作废,原因"5 月 1 日 Replace 策略误用清理"
+  - 5/28 李经理:30 删,原因"测试数据清理"
+- 单条作废(voided):8 次
+  - 大多与上述批删事件关联
+  - 1 次独立:5/22 王主管作废 Bill #321(原因:陈先生纠纷调解结果)
+
+## 异常发现
+- 无未授权操作(所有 bulk_deleted 操作员均有 bill.bulkDelete 权限)
+- 无超规模操作(单次最多 92 张,合规)
+- 所有操作都填了 reason(合规)
+
+## 合规结论
+- ✅ 所有高敏操作均有 audit trail
+- ✅ 操作员权限符合岗位
+- ✅ 原因填写规范
+
+## 建议
+- 长期保留 activitylog(至少 7 年,与会计档案同周期)
+- 季度审计抽查
+```
+
+## 业户视角
+
+业户**通常不直接接触** activitylog。但**法律纠纷时**:
+
+- 业户对某账单的操作有疑问 → 业户可申请查看 activitylog
+- 物业有义务**留存 + 展示**操作历史(透明化、可追溯)
+- 业户/法院通过 activitylog 评估物业操作合规性
+
+## 法务 / 监管视角
+
+| 用途 | 怎么用 |
+|---|---|
+| **司法纠纷举证** | 业户起诉物业不当操作 → 物业拿 activitylog 证明操作合规 |
+| **政府监管检查** | 检查批量删除 / 作废操作是否合理 |
+| **行业自律审计** | 行业协会定期抽查 |
+| **内部审计** | 财务总监 / 审计部门定期审 |
+
+## 与 prop-acc 其他模块的对比
+
+| 模块 | 审计方案 |
+|---|---|
+| **billing(本)** | **activitylog + meta** |
+| deposit | meta JSON(`force_closed_*` / `freeze_reason` 等)|
+| prepaid | meta JSON(`freeze_reason` / `unfreeze_reason`)|
+| meter | meta JSON(`decommission_reason`)|
+| adhoc | meta JSON 或 `voided_at` 字段 |
+
+billing 的 activitylog 是 prop-acc **首个启用 spatie 审计日志的模块**(issue.md Q6 标志性改进)。其他模块**可以借鉴**(未来若启用,有 billing 实施经验)。
+
+## activitylog 表结构(spatie 标准)
+
+```sql
+CREATE TABLE activity_log (
+    id BIGINT PRIMARY KEY,
+    log_name VARCHAR(255),
+    description TEXT,            -- 简单描述
+    subject_type VARCHAR(255),   -- 对象类(Bill)
+    subject_id BIGINT,           -- 对象 ID
+    causer_type VARCHAR(255),    -- 操作员类(User)
+    causer_id BIGINT,            -- 操作员 ID
+    properties JSON,             -- 详情(reason / amount / etc.)
+    event VARCHAR(255),          -- 自定义事件名
+    batch_uuid VARCHAR(36),      -- 可关联多条 log
+    created_at TIMESTAMP,
+    updated_at TIMESTAMP,
+    INDEX idx_subject(subject_type, subject_id),
+    INDEX idx_causer(causer_type, causer_id),
+    INDEX idx_event(event),
+    INDEX idx_created_at(created_at)
+);
+```
+
+## 数据保留与归档
+
+> [!warning] activitylog 表会快速增长
+> 每次高敏操作 1 条 + 收款 / 创建 / 编辑等可能也加 → 数据增长快。
+>
+> 建议:
+>
+> - **生产环境**:保留 1-3 年热数据(查询性能优)
+> - **冷数据归档**:超 1 年的迁到 archive 表 / 对象存储
+> - **永久保留**:某些事件(bulk_deleted / voided)**法定 7+ 年**
+>
+> 当前未实施归档,数据量大后需要运维介入。
+
+## 常见问题
+
+> [!question] activitylog 与 meta JSON 的关系?
+> 互补:
+>
+> | 方面 | activitylog | meta JSON |
+> |---|---|---|
+> | 保留多久 | 全平台共表(易归档)| 与对象同存(无法独立归档)|
+> | 查询性能 | 按时间 / 类型查快 | 在对象上 random access 快 |
+> | 关联多个对象 | ✅(properties 数组) | ❌(只在自己 meta)|
+> | 跨模块查询 | ✅ | ❌(各模块字段不同)|
+> | 操作上下文 | ✅(causer_id 直接)| ❌(若没存)|
+>
+> 推荐:meta 存"对象当前状态的辅助"(如 voided_at);activitylog 存"事件链"(谁干了什么)。两者不冲突。
+
+> [!question] 业务人员如何看 activitylog?
+> 当前**没有 UI**(spatie 包提供数据存储,UI 需自建)。审计师 / 业务方查询:
+>
+> - 直接 SQL(本场景示范)
+> - 让运维查 / 出导出
+> - 未来加 `ActivityLogResource` Filament UI(优先级看需求)
+
+> [!question] activitylog 能改 / 删吗?
+> 系统层面**理论上可改**(就是普通表)。**合规上不应改**(篡改审计 = 大罪)。
+>
+> 高级实施:用**append-only**表(数据库层面 disallow UPDATE/DELETE)+ 定期写校验和(若数据被改可发现)。当前未实施。
+
+> [!question] 跨模块审计能合并查吗?
+> 可以(activitylog 是全平台共表)。但其他模块当前**没启用 activitylog**(用 meta),所以跨模块审计**目前只看 bill 模块**。未来若其他模块启用,可统一查。
+
+> [!question] activitylog 与系统日志(Laravel log)的差异?
+> | 维度 | activitylog | Laravel log |
+> |---|---|---|
+> | 内容 | 业务事件(带 subject / causer / properties) | 技术日志(error / debug / info)|
+> | 持久化 | 数据库 | 文件 / 集中日志服务 |
+> | 业务查询 | ✅ 结构化,SQL 查 | ❌ 全文搜索 |
+> | 合规价值 | **高** | 低(辅助排错)|
+>
+> 两者并存,各管各的。activitylog 关注**业务操作**,Laravel log 关注**系统行为**。
+
+## 异常分支
+
+- 发现疑似篡改 → 物业内部审计 + 法务介入
+- 数据量太大查询慢 → 归档老数据
+- 业户申请查 activitylog → 出报告(由审计师 / 法务出)
+- 长期审计需求 → 加 `ActivityLogResource` UI(未来扩展)
+
+## 相关文档
+
+- [[smart-bulk-delete-design]](核心 activitylog 设计)
+- [[delete-vs-void-dual-track]]
+- [[bulk-delete-batch-mistake]]
+- [[void-paid-bill]]
+- [[suspend-bill]]
+- [[resume-bill]]
+- [[audit-monthly-billing-vs-collection]]