351 lines
11 KiB
Markdown
351 lines
11 KiB
Markdown
# LSFX Mock Server 异常账户基线同步设计文档
|
||
|
||
**模块**: `lsfx-mock-server`
|
||
**日期**: 2026-03-31
|
||
|
||
## 一、背景
|
||
|
||
当前 `lsfx-mock-server` 已完成异常账户命中流水的主链路接入：
|
||
|
||
- `FileService` 可为 `logId` 生成稳定的 `abnormal_account_hit_rules`
|
||
- `FileRecord` 内已保存 `abnormal_accounts`
|
||
- `StatementService` 已能按异常账户事实拼接 `SUDDEN_ACCOUNT_CLOSURE`、`DORMANT_ACCOUNT_LARGE_ACTIVATION` 命中流水
|
||
|
||
但现阶段异常账户事实仅存在于 Mock 进程内存中，尚未同步到主项目真实规则依赖的关联表 `ccdi_account_info`。这会导致两个问题：
|
||
|
||
1. Mock 返回的流水看起来满足异常账户规则，但真实打标 SQL 缺少账户事实，命中不稳定
|
||
2. 同一个 `logId` 下，“命中流水”与“真实账户事实”没有形成完整闭环
|
||
|
||
本次需求要求在生成可以命中异常账户的流水时，同时向关联表插入最小事实数据，保证真实规则命中条件成立。
|
||
|
||
## 二、目标
|
||
|
||
- 在 `fetch_inner_flow(...)` / 上传创建 `logId` 时一次性同步异常账户事实到 `ccdi_account_info`
|
||
- 保持同一个 `logId` 的异常账户事实、返回流水、真实打标条件三者一致
|
||
- 保持现有 `/watson/api/project/getBSByLogId` 接口协议不变
|
||
- 保持 `StatementService` 只负责读 `FileRecord` 生成流水，不新增写库副作用
|
||
- 对异常账户基线写库失败采用显式失败语义，不返回半成功 `logId`
|
||
|
||
## 三、非目标
|
||
|
||
- 不新增异常账户独立接口
|
||
- 不修改现有随机规则命中策略
|
||
- 不扩展 `ccdi_account_info` 为完整账户域模型
|
||
- 不在 `getBSByLogId` 首次查询时补做异常账户写库
|
||
- 不新增兜底、补丁或降级链路
|
||
|
||
## 四、方案对比
|
||
|
||
### 4.1 方案 A：在创建 `logId` 时同步异常账户基线，推荐
|
||
|
||
做法：
|
||
|
||
- `FileService` 生成 `FileRecord` 和 `abnormal_accounts`
|
||
- 在保存 `file_records[log_id]` 之前，同步将异常账户事实幂等写入 `ccdi_account_info`
|
||
- 后续 `StatementService` 只读内存事实生成流水
|
||
|
||
优点：
|
||
|
||
- 触发点单一，同一个 `logId` 只写一次
|
||
- 不把写库副作用混进读接口
|
||
- “命中前提未建好就不返回 `logId`” 的语义最清晰
|
||
- 与现有 `fetch_inner_flow -> getBSByLogId` 主链路最一致
|
||
|
||
缺点：
|
||
|
||
- 需要新增一个很小的异常账户基线写库服务
|
||
|
||
### 4.2 方案 B：在 `getBSByLogId` 首次生成流水时再写库
|
||
|
||
优点：
|
||
|
||
- 只有真正查询流水时才落库
|
||
|
||
缺点：
|
||
|
||
- 读接口承担写库副作用，职责变重
|
||
- 缓存、重试和并发下更容易出现重复写库或半成功状态
|
||
- 不符合当前 Mock 服务“先建上传记录，再查流水”的链路习惯
|
||
|
||
### 4.3 方案 C：继续只保留内存事实，不做运行时写库
|
||
|
||
优点：
|
||
|
||
- 实现最省事
|
||
|
||
缺点：
|
||
|
||
- 无法保证真实规则稳定命中
|
||
- 不满足当前需求
|
||
|
||
## 五、结论
|
||
|
||
采用方案 A。
|
||
|
||
原因如下：
|
||
|
||
- 最短路径实现真实闭环
|
||
- 不破坏现有服务职责边界
|
||
- 最容易保证“同一个 `logId` 一次建好全部命中前提”
|
||
- 最符合你要求的“生成可以命中的流水时，同时向关联表插入数据”
|
||
|
||
## 六、总体设计
|
||
|
||
### 6.1 新增服务边界
|
||
|
||
新增 `AbnormalAccountBaselineService`，职责仅有一项：
|
||
|
||
- 将 `FileRecord.abnormal_accounts` 幂等同步到 `ccdi_account_info`
|
||
|
||
职责划分如下：
|
||
|
||
- `FileService`
|
||
- 生成 `logId`
|
||
- 选择员工身份
|
||
- 生成异常账户命中计划
|
||
- 生成 `abnormal_accounts`
|
||
- 调用异常账户基线同步服务
|
||
- `AbnormalAccountBaselineService`
|
||
- 连接数据库
|
||
- 以 `account_no` 为键执行幂等写入
|
||
- `StatementService`
|
||
- 继续只根据 `FileRecord` 生成命中流水
|
||
- 不负责数据库写入
|
||
|
||
### 6.2 调用顺序
|
||
|
||
改造后的 `fetch_inner_flow(...)` 主链路如下：
|
||
|
||
1. 生成 `logId`
|
||
2. 生成规则命中计划
|
||
3. 创建 `FileRecord`
|
||
4. 生成 `record.abnormal_accounts`
|
||
5. 调用 `_apply_abnormal_account_baselines(file_record)`
|
||
6. 基线写库成功后，再将 `file_record` 放入 `self.file_records`
|
||
7. 继续后续现有逻辑并返回响应
|
||
|
||
这个顺序的关键点是：
|
||
|
||
- 不把异常账户写库放到 `StatementService`
|
||
- 不在基线未落库成功时返回可用 `logId`
|
||
|
||
### 6.3 失败语义
|
||
|
||
- 若 `abnormal_account_hit_rules` 为空：直接跳过，不写库
|
||
- 若命中了异常账户规则但 `abnormal_accounts` 为空：视为内部状态异常，直接失败
|
||
- 若数据库连接失败或 upsert 失败：`fetch_inner_flow(...)` 直接失败，本次 `logId` 不写入内存
|
||
- 不做补丁式重试，不返回半成功结果
|
||
|
||
## 七、数据模型设计
|
||
|
||
### 7.1 内存事实结构
|
||
|
||
继续复用当前 `FileRecord.abnormal_accounts` 结构，最小字段为：
|
||
|
||
- `account_no`
|
||
- `owner_id_card`
|
||
- `account_name`
|
||
- `status`
|
||
- `effective_date`
|
||
- `invalid_date`
|
||
- `rule_code`
|
||
|
||
说明：
|
||
|
||
- `rule_code` 仅作为 Mock 内部路由字段使用
|
||
- 对外接口不返回这批事实
|
||
|
||
### 7.2 `ccdi_account_info` 同步字段
|
||
|
||
本次只同步真实规则命中所需的最小字段：
|
||
|
||
- `account_no`
|
||
- `account_type`
|
||
- `account_name`
|
||
- `owner_type`
|
||
- `owner_id`
|
||
- `bank`
|
||
- `bank_code`
|
||
- `currency`
|
||
- `is_self_account`
|
||
- `trans_risk_level`
|
||
- `status`
|
||
- `effective_date`
|
||
- `invalid_date`
|
||
- `create_by`
|
||
- `update_by`
|
||
|
||
其中字段值约束如下：
|
||
|
||
- `account_no`
|
||
- 直接使用 `record.abnormal_accounts[*].account_no`
|
||
- `account_name`
|
||
- 直接使用 `record.abnormal_accounts[*].account_name`
|
||
- `owner_type`
|
||
- 固定写 `EMPLOYEE`
|
||
- `owner_id`
|
||
- 写 `owner_id_card`
|
||
- `bank`
|
||
- 固定写当前异常账户样本对齐的银行名称
|
||
- `bank_code`
|
||
- 固定写当前异常账户样本对齐的银行编码
|
||
- `currency`
|
||
- 固定 `CNY`
|
||
- `is_self_account`
|
||
- 固定 `1`
|
||
- `trans_risk_level`
|
||
- 固定 `HIGH`
|
||
- `status`
|
||
- 由规则事实决定
|
||
- `effective_date`
|
||
- 由规则事实决定
|
||
- `invalid_date`
|
||
- 仅销户规则写值
|
||
|
||
本次不补充 `monthly_avg_trans_count`、`monthly_avg_trans_amount`、`dr_max_single_amount` 等推导型字段，因为当前两条真实规则命中依赖的是账户状态与流水窗口，不依赖这些预统计字段。
|
||
|
||
## 八、幂等策略设计
|
||
|
||
### 8.1 唯一定位键
|
||
|
||
以 `account_no` 作为异常账户事实的唯一定位键。
|
||
|
||
原因：
|
||
|
||
- Mock 内部异常账户事实和异常账户样本流水都以账号为唯一桥梁
|
||
- 同一个员工可能存在多个账户，按 `owner_id` 先删后插会扩大影响面
|
||
- 账号粒度最符合异常账户明细展示与后续回溯链路
|
||
|
||
### 8.2 Upsert 规则
|
||
|
||
对每条异常账户事实执行单条幂等 upsert：
|
||
|
||
- 若账号不存在：插入
|
||
- 若账号已存在：覆盖本次 Mock 负责的核心字段
|
||
|
||
覆盖范围仅限：
|
||
|
||
- `account_name`
|
||
- `owner_type`
|
||
- `owner_id`
|
||
- `bank`
|
||
- `bank_code`
|
||
- `currency`
|
||
- `is_self_account`
|
||
- `trans_risk_level`
|
||
- `status`
|
||
- `effective_date`
|
||
- `invalid_date`
|
||
- `update_by`
|
||
- `update_time`
|
||
|
||
明确不做的事：
|
||
|
||
- 不按员工先删整批账户
|
||
- 不清空其他来源的账户数据
|
||
- 不以 `owner_id` 做批量覆盖
|
||
|
||
## 九、一致性约束
|
||
|
||
必须同时满足以下约束：
|
||
|
||
1. `record.abnormal_accounts[*].account_no` 必须等于对应异常账户样本流水的 `accountMaskNo`
|
||
2. `record.abnormal_accounts[*].owner_id_card` 必须等于对应异常账户样本流水的 `cretNo`
|
||
3. 同一个 `logId` 下，异常账户事实与异常账户流水必须来自同一份 `FileRecord`
|
||
4. `StatementService` 返回流水时不得覆盖已存在的异常账户样本账号
|
||
|
||
这意味着“内存事实 -> 返回流水 -> 数据库账户事实”三者会围绕同一个 `account_no` 对齐，后端真实 SQL 与结果回溯链路不会漂移。
|
||
|
||
## 十、模块改动设计
|
||
|
||
### 10.1 `lsfx-mock-server/services/file_service.py`
|
||
|
||
改动点：
|
||
|
||
- 注入新的 `abnormal_account_baseline_service`
|
||
- 新增 `_apply_abnormal_account_baselines(file_record)` 封装方法
|
||
- 在 `fetch_inner_flow(...)` 与上传建档链路中，于 `self.file_records[log_id] = file_record` 之前调用该方法
|
||
|
||
职责保持：
|
||
|
||
- 仍是异常账户规则计划和事实的唯一生成入口
|
||
- 不直接拼装 SQL 字符串，数据库写入交给独立服务
|
||
|
||
### 10.2 `lsfx-mock-server/services/abnormal_account_baseline_service.py`
|
||
|
||
新增文件，提供：
|
||
|
||
- 数据库连接
|
||
- 输入校验
|
||
- 单条异常账户事实 upsert
|
||
- 批量 apply 入口
|
||
|
||
建议方法签名：
|
||
|
||
```python
|
||
def apply(self, staff_id_card: str, abnormal_accounts: List[dict]) -> None:
|
||
...
|
||
```
|
||
|
||
说明：
|
||
|
||
- `staff_id_card` 用于做最小一致性校验
|
||
- `abnormal_accounts` 为当前 `logId` 已生成好的异常账户事实列表
|
||
|
||
### 10.3 `lsfx-mock-server/services/statement_service.py`
|
||
|
||
本次不新增写库逻辑，仅维持现有一致性保证：
|
||
|
||
- 继续从 `FileRecord` 读取 `abnormal_accounts`
|
||
- 继续根据 `rule_code` 选择异常账户样本构造器
|
||
- 保持 `_apply_primary_binding(...)` 只兜底缺失账号，不覆盖异常账户样本账号
|
||
|
||
## 十一、测试设计
|
||
|
||
### 11.1 `tests/test_file_service.py`
|
||
|
||
补充断言：
|
||
|
||
- 命中异常账户规则时，`fetch_inner_flow(...)` 会调用异常账户基线同步服务
|
||
- 同步服务收到的账号、员工身份证、状态、生效日、销户日与 `record.abnormal_accounts` 完全一致
|
||
- 基线同步失败时，`file_records` 中不会残留该 `logId`
|
||
|
||
这里优先使用 fake service / stub 断言调用参数，不直接依赖真实数据库。
|
||
|
||
### 11.2 `tests/test_statement_service.py`
|
||
|
||
保留现有异常账户流水样本测试，再补充链路一致性断言：
|
||
|
||
- 同一个 `logId` 下，异常账户样本流水中的 `accountMaskNo` 必须全部来自 `record.abnormal_accounts`
|
||
- `StatementService` 不会因本次改造新增数据库写入副作用
|
||
|
||
### 11.3 `tests/test_abnormal_account_baseline_service.py`
|
||
|
||
新增服务层单测，覆盖：
|
||
|
||
- 空异常账户列表直接跳过
|
||
- 命中规则但事实为空时报错
|
||
- 新账号插入
|
||
- 已有账号按 `account_no` 幂等更新
|
||
|
||
## 十二、验收标准
|
||
|
||
本次设计实施后，应满足以下验收结果：
|
||
|
||
1. 创建 `logId` 时，命中的异常账户事实会一次性写入 `ccdi_account_info`
|
||
2. 同一个 `logId` 后续查询流水不会再次写库
|
||
3. `ccdi_account_info.account_no` 与异常账户样本流水 `accountMaskNo` 完全一致
|
||
4. 写库失败时，不返回半成功 `logId`
|
||
5. 现有异常账户命中流水生成、分页与缓存语义保持不变
|
||
|
||
## 十三、结论
|
||
|
||
本次采用“创建 `logId` 时一次性同步异常账户基线”的方式改造 `lsfx-mock-server`：
|
||
|
||
- 让异常账户命中样本不再停留在 Mock 进程内存
|
||
- 让 `ccdi_account_info` 与返回流水围绕同一个账号闭环
|
||
- 保持现有接口不变
|
||
- 保持最短路径实现，不引入兼容性和补丁式方案
|
||
|
||
这能确保 Mock 生成的异常账户流水不仅“看起来能命中”，而且“真实规则一定具备命中所需的账户事实前提”。
|