ccdi/docs/design/2026-03-20-model-info-xlsx-update-design.md

模型信息 XLSX 更新与 SQL 可执行性校验设计文档

模块: 模型信息资料维护 日期: 2026-03-20

一、背景

当前仓库中存在模型信息资料文件 assets/模型信息.xlsx，其中维护了各类风险模型的业务口径、技术口径、指标、SQL 等信息。

本次需求要求在不改变文件主体结构的前提下，基于当前项目代码和当前数据库真实结构，对该文件进行一次面向落地性的整理：

1. 将项目和数据库中已经明确存在的信息补充回 XLSX。
2. 对尚未在项目中真实实现的模型，检查其 SQL 在当前环境中能否执行。
3. 对不能执行的 SQL，明确指出当前缺少的对象、字段或执行条件。

二、目标

本次设计目标如下：

1. 直接修改原文件 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，可作为当前库结构和 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
2. 本设计文档 docs/superpowers/specs/2026-03-20-model-info-xlsx-update-design.md
3. 一份实施记录文档，落在 docs/reports/implementation/