269 lines
8.4 KiB
Markdown
269 lines
8.4 KiB
Markdown
# 模型信息 XLSX 更新与 SQL 可执行性校验设计文档
|
||
|
||
**模块**: 模型信息资料维护
|
||
**日期**: 2026-03-20
|
||
|
||
## 一、背景
|
||
|
||
当前仓库中存在模型信息资料文件 [assets/模型信息.xlsx](/Users/wkc/Desktop/ccdi/ccdi/assets/模型信息.xlsx)，其中维护了各类风险模型的业务口径、技术口径、指标、SQL 等信息。
|
||
|
||
本次需求要求在不改变文件主体结构的前提下，基于当前项目代码和当前数据库真实结构，对该文件进行一次面向落地性的整理：
|
||
|
||
1. 将项目和数据库中已经明确存在的信息补充回 XLSX。
|
||
2. 对尚未在项目中真实实现的模型，检查其 SQL 在当前环境中能否执行。
|
||
3. 对不能执行的 SQL，明确指出当前缺少的对象、字段或执行条件。
|
||
|
||
## 二、目标
|
||
|
||
本次设计目标如下：
|
||
|
||
1. 直接修改原文件 [assets/模型信息.xlsx](/Users/wkc/Desktop/ccdi/ccdi/assets/模型信息.xlsx)，不另存副本。
|
||
2. 对表内模型逐行判定“已真实实现”或“未真实实现”。
|
||
3. 对未真实实现的模型补齐可明确推出的缺失字段。
|
||
4. 在表尾新增两个结论列：
|
||
- `当前环境是否可执行SQL`
|
||
- `当前缺少内容`
|
||
5. 结论以当前仓库代码、当前 `ccdi` 数据库和当前 MySQL 方言能力为准，不做外部依赖默认成立的假设。
|
||
|
||
## 三、范围
|
||
|
||
### 3.1 本次范围
|
||
|
||
- 读取并更新 `Sheet1` 现有模型数据
|
||
- 基于项目代码、SQL 脚本、规则定义和数据库结构补充模型信息
|
||
- 对未真实实现模型的 SQL 进行当前环境可执行性判断
|
||
- 在 XLSX 中新增结论列
|
||
- 补充本次操作对应的实施记录
|
||
|
||
### 3.2 不在本次范围
|
||
|
||
- 不新增新的业务模型
|
||
- 不为了补齐表格而设计新的业务规则
|
||
- 不修改项目中的后端实现逻辑
|
||
- 不修改数据库表结构以适配 XLSX 中的未实现 SQL
|
||
- 不对已真实实现模型的表格行进行主动重写或口径重构
|
||
|
||
## 四、现状分析
|
||
|
||
### 4.1 XLSX 现状
|
||
|
||
`Sheet1` 当前包含 14 列，核心列包括：
|
||
|
||
1. 序号
|
||
2. 模型名称
|
||
3. 核心异常点（展示在前端页面）
|
||
4. 业务口径
|
||
5. 相关指标
|
||
6. 指标英文名
|
||
7. 风险筛查对象
|
||
8. 技术口径
|
||
9. 代码
|
||
10. 限制阈值指标
|
||
11. 可疑结果返回
|
||
12. 风险等级
|
||
|
||
当前表内部分模型已经填有 SQL，但存在以下问题：
|
||
|
||
- 部分字段为空或不完整
|
||
- 大小写风格不统一
|
||
- 部分 SQL 引用了当前环境中不存在的外部库表
|
||
- 部分 SQL 包含当前 MySQL 不支持的语法或明显错误
|
||
|
||
### 4.2 项目与数据库现状
|
||
|
||
当前环境已确认具备以下能力和对象：
|
||
|
||
- 数据库可连接，目标库为 `ccdi`
|
||
- 已存在核心表：
|
||
- `ccdi_base_staff`
|
||
- `ccdi_bank_statement`
|
||
- `ccdi_staff_fmy_relation`
|
||
- `ccdi_asset_info`
|
||
- `ccdi_biz_intermediary`
|
||
- `ccdi_model_param`
|
||
- `ccdi_bank_tag_rule`
|
||
- `ccdi_bank_statement_tag_result`
|
||
- `ccdi_bank_tag_rule` 已初始化多类模型规则，但其中不少规则仍为“占位规则，待补充真实SQL”
|
||
- 仓库中已有一份核对报告 [docs/reports/implementation/2026-03-17-model-sql-check-and-rewrite.md](/Users/wkc/Desktop/ccdi/ccdi/docs/reports/implementation/2026-03-17-model-sql-check-and-rewrite.md)，可作为当前库结构和 SQL 兼容性判断的参考基线
|
||
|
||
## 五、判定规则
|
||
|
||
### 5.1 已真实实现模型
|
||
|
||
只有同时满足以下口径之一的模型，才认定为“已真实实现”并跳过：
|
||
|
||
1. 项目中已经存在真实 SQL 或明确的命中逻辑实现。
|
||
2. 项目中已经存在真实结果产出逻辑，而不是仅有规则占位或参数定义。
|
||
|
||
以下情况不认定为已真实实现：
|
||
|
||
- 只有 `ccdi_bank_tag_rule` 占位规则定义
|
||
- 只有 `ccdi_model_param` 参数定义
|
||
- 备注中明确写明“待补充真实SQL”
|
||
- 只有模型名称、规则编码等元数据，没有真实落地逻辑
|
||
|
||
### 5.2 未真实实现模型
|
||
|
||
凡是不满足“已真实实现模型”标准的行，一律进入本次补充和校验范围。
|
||
|
||
对这类行执行两类操作：
|
||
|
||
1. 补充可从现有项目和数据库中明确推出的信息
|
||
2. 校验该行 SQL 在当前环境中的可执行性
|
||
|
||
## 六、方案对比
|
||
|
||
### 6.1 方案 A：直接在原 XLSX 上逐行补全与校验
|
||
|
||
做法：
|
||
|
||
- 逐行读取模型信息
|
||
- 判定是否已真实实现
|
||
- 对未真实实现模型直接在原表中补全与新增结论列
|
||
|
||
优点：
|
||
|
||
- 最短路径实现
|
||
- 输出物就是用户要求的原始文件
|
||
- 不引入额外中间文件或额外同步成本
|
||
|
||
缺点：
|
||
|
||
- 需要严格控制回填规则，避免误改已存在口径
|
||
|
||
### 6.2 方案 B：先生成中间清单，再统一回写 XLSX
|
||
|
||
做法：
|
||
|
||
- 先把 XLSX 转成结构化清单
|
||
- 在清单中完成判定与校验
|
||
- 再二次回写 XLSX
|
||
|
||
优点：
|
||
|
||
- 处理过程更易追踪
|
||
|
||
缺点：
|
||
|
||
- 步骤变长
|
||
- 不符合本次“直接修改原文件”的最短路径目标
|
||
|
||
### 6.3 方案 C：只新增校验列，不回填缺失字段
|
||
|
||
做法：
|
||
|
||
- 保持原字段不动
|
||
- 只新增可执行性相关两列
|
||
|
||
问题：
|
||
|
||
- 无法满足“根据项目和数据库内有的字段更新到这个 xlsx 中”的要求
|
||
|
||
### 6.4 结论
|
||
|
||
采用方案 A。
|
||
|
||
## 七、XLSX 更新设计
|
||
|
||
### 7.1 表结构调整
|
||
|
||
保留 `Sheet1`、原列顺序和原行顺序不变，在现有最后一列后新增两列：
|
||
|
||
1. `当前环境是否可执行SQL`
|
||
2. `当前缺少内容`
|
||
|
||
### 7.2 回填原则
|
||
|
||
对未真实实现模型，采用“能明确推出才补，不做主观扩写”的原则：
|
||
|
||
- `指标英文名`
|
||
- 优先使用项目中已有的 `indicator_code`、`param_code`、规则编码或现有统一命名风格
|
||
- `风险筛查对象`
|
||
- 优先从 SQL 的 `from/join` 范围、现有规则定义和同类模型写法中归纳
|
||
- `技术口径`
|
||
- 优先按 SQL 实际筛选逻辑进行摘要式补充
|
||
- `可疑结果返回`
|
||
- 按 SQL 输出对象判断，例如 `流水明细`、`对象聚合`
|
||
- `风险等级`
|
||
- 优先采用当前规则表或同类规则现有等级
|
||
|
||
若现有材料无法唯一确定，则保留原值，不额外发明新业务口径。
|
||
|
||
### 7.3 已真实实现模型处理原则
|
||
|
||
对于已真实实现模型：
|
||
|
||
- 仅做识别和跳过
|
||
- 不主动回填原行缺失字段
|
||
- 不因当前表格写法和现有实现口径略有差异而重写整行
|
||
|
||
## 八、SQL 可执行性校验设计
|
||
|
||
### 8.1 校验基准
|
||
|
||
SQL 是否“可在当前环境执行”，以以下条件同时成立为准：
|
||
|
||
1. 当前 `ccdi` 数据库中相关表和字段已存在
|
||
2. SQL 使用的函数和语法兼容当前 MySQL 能力
|
||
3. SQL 中引用的对象不依赖当前环境不存在的外部 schema、外部表或临时准备表
|
||
4. SQL 本身不存在明显语法错误
|
||
|
||
### 8.2 结论写法
|
||
|
||
- 可执行：`是`
|
||
- 不可执行：`否`
|
||
|
||
### 8.3 缺少内容写法
|
||
|
||
- 若可执行，填写 `/`
|
||
- 若不可执行，填写最小必需缺项或明确错误，示例：
|
||
- `缺少外部表 odsdb.blfmconf`
|
||
- `缺少中介账号清单表`
|
||
- `当前 MySQL 不支持 WITH`
|
||
- `exists 子句写法错误`
|
||
- `SQL 中占位变量 PROJECT_ID 未替换`
|
||
|
||
### 8.4 不做的事情
|
||
|
||
本次不会为了让 SQL 勉强通过而：
|
||
|
||
- 默认补造不存在的中间表
|
||
- 默认将外部库对象视为可访问
|
||
- 擅自重写业务含义
|
||
|
||
如果当前环境缺项导致 SQL 无法执行，直接在结论列中说明。
|
||
|
||
## 九、执行步骤
|
||
|
||
按以下顺序执行：
|
||
|
||
1. 读取 XLSX 全部模型行
|
||
2. 基于项目代码、规则表、SQL 脚本和数据库结构逐行判定是否已真实实现
|
||
3. 对未真实实现模型补齐可明确推出的字段
|
||
4. 对未真实实现模型的 SQL 做当前环境可执行性判断
|
||
5. 回写两个新增结论列
|
||
6. 保存原文件
|
||
7. 在 `docs/reports/implementation/` 补充本次实施记录
|
||
|
||
## 十、风险与控制
|
||
|
||
### 10.1 主要风险
|
||
|
||
1. 误把占位规则判定为已实现，导致该行被错误跳过
|
||
2. 根据不充分信息补出带有主观推断的业务口径
|
||
3. 将“理论可改写后可执行”误写成“当前环境可执行”
|
||
|
||
### 10.2 控制措施
|
||
|
||
1. 已实现判定从严，仅认可真实 SQL 或真实结果逻辑
|
||
2. 回填坚持“可明确推出才补”
|
||
3. 可执行性仅以“当前环境直接执行”为准，不按未来补齐条件判断
|
||
|
||
## 十一、产出物
|
||
|
||
本次最终产出包括：
|
||
|
||
1. 更新后的 [assets/模型信息.xlsx](/Users/wkc/Desktop/ccdi/ccdi/assets/模型信息.xlsx)
|
||
2. 本设计文档 [docs/superpowers/specs/2026-03-20-model-info-xlsx-update-design.md](/Users/wkc/Desktop/ccdi/ccdi/docs/superpowers/specs/2026-03-20-model-info-xlsx-update-design.md)
|
||
3. 一份实施记录文档，落在 `docs/reports/implementation/`
|