6.6 KiB
MODIFIED Requirements
Requirement: 记录所有账号管理操作
系统 SHALL 通过统一 Audit Event Writer 记录所有账号管理操作，包括创建、更新、删除、企业微信绑定、角色分配和角色移除；成功事件 MUST 与对应业务事实采用该用例约定的可靠事务策略，失败或拒绝事件 MUST 在业务回滚后使用独立短事务写入，不得继续向 tb_account_operation_log 新增记录。
Scenario: 创建账号时记录统一审计事件
- WHEN 用户创建账号成功
- THEN 系统写入
account.createdAudit Event - AND 事件包含操作人、目标账号资源、账号业务标识快照和创建后的关键业务字段
Scenario: 更新账号时记录资源级变更
- WHEN 用户更新账号信息（用户名、手机号、状态等）
- THEN 系统写入账号资源的
before_data和after_data - AND 仅包含本次操作相关的业务字段及其变更
Scenario: 删除账号时保留目标快照
- WHEN 用户软删除账号成功
- THEN 系统记录删除事件及账号删除前的关键业务字段
- AND 账号后续无法从业务表查询时仍可通过资源标识快照识别目标账号
Scenario: 分配角色时记录账号与角色资源
- WHEN 用户为账号分配角色
- THEN 系统记录账号为主要资源、实际分配角色为关联资源的 Audit Event
- AND 事件包含实际生效的角色 ID 与角色名称快照
Scenario: 移除角色时记录账号与角色资源
- WHEN 用户移除账号的角色
- THEN 系统记录账号为主要资源、被移除角色为关联资源的 Audit Event
- AND 事件包含被移除角色 ID 与角色名称快照
Requirement: 审计日志包含完整的操作上下文
系统 SHALL 在统一 Audit Event 中记录操作者快照、来源、结果、目标资源、资源级变更及请求关联上下文，并 MUST 支持一次操作关联多个资源。
Scenario: 记录操作人信息
- WHEN 记录账号管理 Audit Event
- THEN 事件包含稳定的操作者类型、操作者 ID、操作者名称快照和来源
Scenario: 记录目标账号信息
- WHEN 记录账号管理 Audit Event
- THEN 事件至少关联一个账号主要资源
- AND 资源快照包含账号 ID、用户名和账号类型
Scenario: 记录变更数据
- WHEN 账号管理操作改变业务字段
- THEN 账号资源的
before_data和after_data使用 JSONB 保存本次操作相关字段 - AND 密码、验证码、Token、Secret、私钥、Authorization、Cookie 及其他系统安全凭据在写入前被删除
Scenario: 记录请求上下文
- WHEN 账号管理操作来自 HTTP 请求
- THEN 事件包含
request_id、IP、User-Agent、请求方法和请求路径 - AND 可通过
request_id关联 Access Log
Scenario: 记录执行结果
- WHEN 已识别操作人或目标账号的操作成功、失败或被拒绝
- THEN 事件记录对应的
success、failed或denied结果及稳定错误码
Requirement: 操作描述使用中文
系统 SHALL 为账号审计动作维护稳定英文动作编码和中文显示名称，查询接口 MUST 返回动作编码与中文显示名称，不得把可变中文描述作为动作身份或资源关联依据。
Scenario: 创建操作描述
- WHEN 查询账号创建事件
- THEN 响应返回稳定动作编码
account.created和中文显示名称“创建账号”
Scenario: 更新操作描述
- WHEN 查询账号更新事件
- THEN 响应返回稳定动作编码
account.updated和中文显示名称“更新账号”
Scenario: 删除操作描述
- WHEN 查询账号删除事件
- THEN 响应返回稳定动作编码
account.deleted和中文显示名称“删除账号”
Scenario: 分配角色操作描述
- WHEN 查询账号角色分配事件
- THEN 响应返回稳定动作编码和中文显示名称“分配账号角色”
Requirement: 支持按多维度查询审计日志
系统 SHALL 通过统一审计 Query 支持按操作者、账号资源、动作、结果、时间、request_id 和 correlation_id 组合筛选，并 SHALL 使用适配分页倒序查询的索引满足数据库查询低于 50ms 的性能目标。
Scenario: 按操作人查询日志
- WHEN 平台用户查询特定操作者的账号相关事件
- THEN 系统按操作者及时间索引返回倒序分页结果
Scenario: 按目标账号查询日志
- WHEN 平台用户查询特定账号的资源时间线
- THEN 系统返回该账号作为主要、受影响或引用资源关联的事件
Scenario: 按时间范围查询日志
- WHEN 平台用户查询最近 7 天的账号相关事件
- THEN 系统使用时间及事件 ID 进行稳定倒序分页
Requirement: 关联访问日志追溯完整请求链路
系统 SHALL 通过 request_id 关联 Audit Event 与 Access Log，并 SHALL 通过 correlation_id、parent_event_id 关联同一业务操作的后续任务、回调和子事件。
Scenario: 通过request_id关联日志
- WHEN Audit Event 记录
request_id="req-12345" - THEN 平台调查人员可以使用同一
request_id定位对应的 HTTP Access Log
Scenario: 追溯完整请求链路
- WHEN 平台调查人员查询某个账号管理操作
- THEN 系统返回该请求关联的 Audit Event 及可用的后续关联事件
- AND Access Log 继续负责完整 HTTP 请求响应排障，不由 Audit Event 复制完整请求正文
REMOVED Requirements
Requirement: 异步写入不阻塞业务流程
Reason: 旧实现通过裸 Goroutine、部分调用方双重 Goroutine 写入账号操作日志，无法保证事务一致性、进程退出前落库、顺序和失败闭环，不满足资金与后台追责要求。
Migration: 所有新账号及借用账号日志的写入口迁移到统一 Audit Event Writer；高风险成功操作与业务事实同一 GORM 事务，其他成功操作遵循用例明确的事务策略，失败和拒绝使用独立短事务。旧表原样保留，不回填、不转换且不进入新审计中心。
Scenario: 异步写入审计日志
- WHEN AccountService.Create 创建账号成功
- THEN 主流程立即返回，审计日志在独立 Goroutine 中异步写入
Scenario: 写入失败只记录错误日志
- WHEN 审计日志写入数据库失败
- THEN 记录 Error 级别日志，包含完整审计信息，但不影响业务操作结果
Scenario: 业务响应时间不受影响
- WHEN 执行账号创建操作
- THEN API 响应时间不应因审计日志写入而增加（< 1ms）