补充模型信息xlsx更新设计文档

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

@@ -0,0 +1,268 @@
+# 模型信息 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/`