# 模型信息 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/`