上一次删除 Step 3「数据验证」时把这个 SQL 模板也删了，但实际
Step 4_empty_fields.py（新 Step 3 大范围空字段扫描）也需要它来
预先统计每张表的实际行数（拿真实 COUNT(*) 而不是 information_schema
的 TABLE_ROWS 估算值）。

症状：最近一次 run (20260806_144238) 把全部 149 张表都标记为
"统计行数失败: SQL 模板不存在" → high_empty_fields_count=0，
"大范围空字段" tab 完全没数据（虽然日志显示 Step 已"完成"）。

修复：恢复 web/sql/verify/count_table_rows.sql，并更新注释说明
本 SQL 是 Step 3 大范围空字段扫描用的（不是 Step 3「数据验证」）。

注意：需要重新跑一次分析才能拿到新的 empty_fields 数据。

移除 Step 3「数据验证」后，Step 号出现断层：1,2,4,5,6,7。重新编号让 Step 号
连续 1-6，对用户更直观。

改动：

orchestrator.py：
- STEP_REGISTRY：4→3 (空字段扫描), 5→4 (缺注释), 6→5 (字段长度), 7→6 (国标校验)
- STEP_DEPENDENCIES 同步重新编号
- step_name() 同步重新编号（'3_empty_fields' / '4_missing_comments' / 等）
- _run_step4/5/6/7 重命名为 _run_step3/4/5/6（调用方 STEP_REGISTRY 已对，自动匹配）
- 顶部 docstring 重写：6 步流程 + 重新编号说明

step_impl/*.py：每个文件里的 step="X" 日志标签同步重新编号
（4→3, 5→4, 6→5, 7→6），同时把 docstring 和 message 文本里的 Step X 字样也改了。
文件本身保留旧文件名（如 step4_empty_fields.py）—— 内部实现细节，
不影响外部行为；如果未来想重命名可单独一次提交。

routes.py：list_steps() 的 StepInfo 也重新编号（4→3, 5→4, 6→5, 7→6）

frontend index.html：
- form.steps 默认 [1,2,4,5,6,7] → [1,2,3,4,5,6]
- 兜底过滤改成 n >= 1 && n <= 6（兼容旧缓存残留的 8/7/3）
- TAB_STEP_MAP：
  - redundancy tab：step 3 → 2（与 merge 同一来源）
  - empty: 4 → 3
  - missing: 5 → 4
  - length: 6 → 5
  - standards: 7 → 6

注：未触及 workflow/ 旧 CLI 目录、docs/DESIGN.md / README.md 文档，
那些是历史描述，单独一次文档 PR 一起改。

行为：UI 显示 Step 1-6 连续 6 个分析 Step，进度计算 / 报告生成
/ section 关联都不变。文件 / 函数命名差异仅是内部实现细节。

Step 3 实际产出价值低且有副作用：
1. 「行政区划孤儿编码检查」只判断字典表 c_bri_xzqh 是否存在，
   没有真正跑 LEFT JOIN 找孤儿（代码注释里写了「可扩展」）
2. 「数据质量问题检查」只是占位，返回空列表
3. 「验证合并候选实际行数」有点用，但 result 已经直接覆盖 Step 2 的输出

最致命的是 _run_step3 返回 section_key='redundancy_fields' —— 这会
反向覆盖 Step 2 的 LLM 分类结果（classification / reasoning /
recommendation 全没了，只剩 Step 3 的简单 field + table_count 列表）。
也就是说 Step 2 的 LLM 工作被 Step 3 默默销毁了。移除 Step 3 同时也修了
这个覆盖 bug，Step 2 的分类结果能正确进入报告。

改动：

- 删除 web/core/step_impl/step3_verify.py
- 删除 web/sql/verify/ + web/sql/xzqh/ 整个目录（仅 Step 3 使用）
- orchestrator.py：
  - STEP_REGISTRY 移除 (3, 数据验证, _run_step3, ...)
  - STEP_DEPENDENCIES 移除 3: {1, 2}
  - step_name() 移除 3: '3_verify'
  - 删除 _run_step3 函数
  - 顶部 docstring 重写：6 步流程 + 移除 Step 3 的原因
- routes.py：list_steps() 不再返回 Step 3
- job_manager.py：all_steps 默认值改成从 STEP_REGISTRY 取
  （保持单一来源，避免硬编码漏改）
- frontend index.html：
  - form.steps 默认 [1,2,3,4,5,6,7] → [1,2,4,5,6,7]
  - 兜底过滤也加上 n !== 3（兼容旧本地缓存残留）

注：未触及 workflow/ 旧 CLI 目录，它走的是另一套独立实现。

行为：
- UI 上「执行步骤」区只有 6 个分析 Step
- /api/steps 返回 6 项
- 主流程跑完后无条件生成报告（Step 8 拆出来之前的约定不变）
- Step 2 LLM 分类结果不再被覆盖，能正确进冗余字段报告

症状：最近 run 里 Step 2「表合并与冗余字段分析」21/21 高频字段全部
classification=unknown, source=llm_failed。但 LLM 调用本身成功
（HTTP 200），只是解析阶段拿不到 valid JSON。

根因：web/configs/llm.yaml 默认 max_tokens=1024。Step 2 让 LLM 返回
每条 reasoning+recommendation 各 50-100 字中文 ≈ 200-300 tokens，
15 字段 × ~250 tokens ≈ 3750 tokens 远超 1024 上限 → LLM 响应被截断
在某个汉字中间 → JSON 不完整 → _safe_parse_json 返回 None → 21 个
字段全标 unknown。

复现：用真实 15 字段 prompt 调 complete()，返回 2824 字符但末尾
"\u5e76\u4e14\u5bb9\u6613\u88ab'" 明显是截断。

修复（A+B 一起）：

A. web/configs/llm.yaml：max_tokens 1024 → 4096，附注释说明为什么
B. web/core/step_impl/step2_merge_redundancy.py：BATCH 30 → 8，
   附注释说明为什么

实测验证（重启后）：8 字段 batch 全部解析成功，分类到 4 种
（suspicious/common_business/common_base/true_redundancy），没有
任何 None 失败。

下次跑 21 字段 → 3 个 batch（8+8+5），每个都能塞进 4096 tokens。

注意：需重启后端服务才能让两处都生效（llm.py 是 Python 代码，
llm.yaml 是启动时 LLMConfig.load() 一次缓存到 _client 单例）。

之前 Step 8 出现在 UI 的「执行步骤」复选框里，用户可取消勾选；后端也按 8 in steps 决定是否生成报告，导致：
1. 用户可能漏勾导致拿不到报告
2. 进度条分母里挂着「报告生成」让人误以为它也算分析步骤

按用户要求，报告生成应该是分析完成的固定产出，不应该作为可选步骤。

改动：

- orchestrator.py
  - STEP_REGISTRY 移除 (8, 报告生成, ...) 一项
  - STEP_DEPENDENCIES 移除 8: set() 注释也清掉
  - step_name() 不再支持 8
  - 去掉 has_step8 / main_steps 不再过滤 8
  - 「开始 生成报告（Markdown + Word）」从 if 8 in steps 改为无条件执行
  - 顶部 docstring 改写说明新约定

- job_manager.py：默认 all_steps 从 range(1,9) 改为 range(1,8)

- routes.py：list_steps() 不再返回 Step 8；steps_planned 默认 range(1,9) → (1,8)

- models.py：ConnectRequest.steps 注释从「默认全 8 步」改为「默认全 7 步；报告生成不在 steps 内」

- step8_report.py：移除 4 处 step='8' 日志标签（不再是 Step）

- frontend index.html
  - form.steps 默认 [1..8] 改为 [1..7]
  - startJob 兜底过滤：form.steps = form.steps.filter(n => n !== 8)
    （防止旧浏览器缓存里残留的 8 让后端报错）
  - form-hint 补充「报告生成不在步骤列表里，每次分析完成后会自动生成 Markdown + Word 供下载」

行为：
- UI 上「执行步骤」区只有 7 个分析 Step
- /api/steps 返回 7 项
- 主流程跑完后无条件生成报告，sections.reports.markdown/docx 照常返回
- 关键 Step 失败时仍会 RuntimeError 终止整个任务（与之前一致，sections 数据不全就没东西可报告）

原 step8_report.py 两个问题：

1. Markdown 每个章节都截前 10-20 条样本，详细信息缺失
2. docx 后半部分只是 stub：标题 + f"{summary}" 把整个 dict 塞进段落，
   浏览器/Word 里看到的就是一坨 JSON 风格的字符串，没有表格

重写方案：两个版本共用 SECTION_ORDER + 同名渲染函数（_md_xxx / _docx_xxx），
保证两边结构对齐。

新增/补齐的章节内容：

- 表合并候选：完整候选明细（ID/优先级/相似度/公共列数/差异列/建议/风险）
  + 各候选组的公共列清单 + 强/弱废弃候选分开列表
- 冗余字段：全部高频字段（不再截 20）+ LLM 失败标「⚠️ 待人工核对」
- 大范围空字段：阈值说明 + 按表汇总（高空数倒序） + 字段明细按表分组
  （每张表高空/中空字段单独子表，含空值率） + 跳过表清单
- 缺失注释字段：summary（涉及表/LLM 调用次数）+ 按表分布 + 推测注释明细
  （全列） + 未推测样本
- 字段长度异常：6 个汇总指标 + 全部异常字段（按 wasted_bytes desc 排，
  10 列含国标/规则/依据）
- 国标违规：按标准统计 + 每标准下的违规字段明细 + 违规样本（最多 500 条）

辅助细节：
- Markdown 表格换行用 <br>、管道符转义 \|、空值显示 -、浮点格式 xx.xx%
- docx 用原生 add_table + style 'Light Grid Accent 1'，Heading 1/2/3 分层
- 顶层 docstring 说明新结构；SECTION_ORDER 单一来源驱动两版渲染

smoke test：拿真实 outputs/smart-build/20260804_085733/findings/_all_findings.json
跑过，Markdown 11425 字符 / 255 行，docx 24 段 + 7 张表格，数据正确。

三处问题一起修：

1. Markdown 按钮点了没反应
   - 按钮 @click 传 'md'，但 jobResult.reports 里的 key 是 'markdown'
   - downloadReport 拿不到 url，静默 return
   - index.html:188 downloadReport('md') → downloadReport('markdown')

2. 改为字节流下载
   - 原方案 window.open('/api/reports/...')：浏览器把 .md 直接显示在页面上
   - 改 fetch + blob + <a download>：触发浏览器「另存为」对话框，体验正确
   - 路径正则兼容正反斜杠（Windows/Linux）
   - 三段（db/run_id/filename）都 encodeURIComponent
   - 错误用 ElementPlus.ElMessage.error 提示，不再静默退出

3. API 路由路径少一段导致 404
   - routes.py 在 web/api/，少算一层 base 就跨过了 web/ 目录
   - 原 base = <项目根>/outputs/...，实际文件在 <项目根>/web/outputs/...
   - .parent.parent.parent → .parent.parent，与 job_manager.py 保持一致

嵌套 el-table 在 expand 行里列宽不稳定（之前两版：先加 width:100%，再换 overflow-x:auto + minWidth，都仍只渲染出 3 列，注释/空值率被挤掉）。

改为原生 <table class="inner-empty-table">，浏览器原生 table 渲染稳定可靠：
- 列定义：字段名 160 / 类型 100 / 注释 auto / 空值数 110 / 空值率 220
- 保留 el-progress 进度条展示空值率
- style.css 新增 .inner-empty-table 样式：表头浅灰、边框、斑马纹、悬停高亮

确认硬刷新（Ctrl+Shift+R）后展开任一行，5 列正常横向排开。

两处前端 UI 调整：

1. LLM-required 步骤（Step 2 / 5）加 🪄 MagicStick 图标 + tooltip 提示
   - 图标橙色 #e6a23c，仅在 s.llm_mode === 'required' 时显示
   - hover 提示'此步骤需要调用大模型，可能会比较耗时'
   - 标题后追加'需 LLM' warning tag，与'必选'红色 tag 并列
   - form-hint 升级：'带 ✨ 图标的步骤需调用大模型，耗时会较长
     （每步数秒到数十秒）'

2. 数据库类型只露 MySQL：
   - 删 el-radio-button label='dameng'
   - 后端 API 仍接受 db_type='dameng'，只是 UI 不再露选项
   - form.db_type 默认 'mysql' 不变

验证：MagicStick 在 element-plus/icons-vue 包内；
本地 == HTTP 服务返回（66056 字节）。

Step 2 / 5 是 LLM-required 步骤，前端暴露开关容易让人误以为可以关闭、
跑出残缺结果。本轮简化前端：固定开启 LLM。

- 删除「启用 LLM」el-switch UI 块（原来与「执行步骤」并排 col 12）
- 执行步骤 col 升级为 24 整行，避免复选框拥挤
- 删除 form.enable_llm 字段（form reactive 状态里）
- 提示语扩展：'Step 2 / 5 需 LLM（已在 web/configs/llm.yaml 配置）'
- 后端无需改：ConnectRequest.enable_llm 默认 True，
  即使前端忘了带字段也会走默认值，不会降级到 False

验证：前端启用 LLM / enable_llm / el-switch 标记全部清除（65222 字节）
本地 == HTTP 服务返回一致。

Step2 / Step5 两个 LLM 必跑步骤把单次请求承载量翻倍：

- step2_merge_redundancy.py: BATCH = 15 → 30
  （高频字段分类，21 个字段 → 1 次 LLM 调用，原来 2 次）
- step5_missing_comments.py: BATCH = 15 → 30
  （缺失注释推测，119 个字段 → 4 次 LLM 调用，原来 8 次）

每次调用时间略增（更多 input/output tokens），但消除了网络
往返 + LLM 服务侧 per-call 启动成本，总耗时预计缩短 30-50%。

未上更大 batch 的考虑：Step2 每条 item 约 100 tokens，
30 条后 prompt 已 ~3000 tokens，再大会撞输出 token 上限
并触发 LLM 注意力衰减。

首次跑后请观察 start.log 中 LLM 命中成功率（之前 119/119），
若下降到 100/119 以下需回调 BATCH。

AST 全部通过。

两轮迭代：

第一轮：参考字段长度异常 tab 的新模板布局，把缺失注释字段 tab
从旧的 prop + fixed 改成 width:100% + min-width + 模板内联：
  - 表名 / 表注释 (template)
  - 字段名 / 字段注释 (template)
  - 类型  (prop data_type)
  - 推测注释 (prop predicted)
  - 置信度 (template + el-tag)
  - 依据  (prop reason)
  el-table 加 style='margin-top: 12px; width: 100%' max-height=560

第二轮：用户反馈'推测注释和类型都没有显示'，可能是 prop 在某些
el-table-column 顺序/min-width 组合下被截断到不可见。
把这两个列也改成 template 渲染并加兜底：
  - 类型：优先 data_type，其次 column_type，最后 '—'，<code> 等宽字体
  - 推测注释：有内容则显示，无则斜体'（未推测）'

未提交：.gitignore（与本任务无关的此前改动）。

之前结果只在所有 step 完成后才返回，导致前端看不到中间进度。本轮改：

后端增量发布：
- orchestrator.run_governance_workflow 新增 on_section_update 回调
  回调在每步完成且有 section_key 时触发
- job_manager 新增 _sync_section_update 同步回调到 job.result['sections']
  （job.result 在任务结束时再被整体 result 替换）
- api/routes.py /jobs/{id}/result 取消'必须 completed'限制，
  running/failed/cancelled 状态也允许读取 sections

前端轮询 + tab 状态：
- pollStatus 每 1.5s 同时拉 status 与 result；
  loadResult 改为 merge sections（不整体替换 jobResult）
- TAB_STEP_MAP 映射 tab -> (step, sectionKey)
- tabStatus computed 按状态返回 'idle'|'running'|'done'
- TAB_BADGE 配置：info(非分析对象)/warning(分析中)/success(分析完成)
- 6 个 el-tab-pane 全部改用 #label slot，加 el-tag 徽章

bug 修复：OverviewStats 必填字段在运行中没数据导致 500：
- core/models.py: database/host/db_type 改为带默认值 ''
- api/routes.py: OverviewStats 构造用 try/except 兜底，失败降级到全零值

AST 全部通过；本地 == HTTP 服务返回一致。

经历多轮迭代，本次提交整合以下改动：

后端 step7_standards.py：
- SAMPLE_SPECS 列表：每条标准可对应多条抽样规格（当前 1 条 default）
- 抽样时捕获实际渲染的 SQL 与 spec_id 落到每条 detail
  （sample_sql / sample_spec_id）— 后端保留供报告用
- violations_flat 增 table_comment / column_comment 字段
- 每条标准新增 violating_fields_count + details_with_violations
  （过滤掉 violations==0 的字段，前端直接消费）
- 过滤零违规标准，不进入 violations_by_standard

前端 index.html：
- 字段点击联动：selectedField + selectFieldFilter / clearFieldFilter
  + filteredViolations computed；选中后明细表只显示该字段违规
- 按标准统计表中字段清单改用 details_with_violations，
  自动隐藏 0 违规字段；字段数列加「N / M」红字显示有违规字段数
- 标准列去除「取数口径」折叠面板（用户认为没意义）
- 明细表去除选中字段时的 SQL 蓝边面板（用户认为没意义）
- 明细表改为 4 列：表/表注释、字段/字段注释、标准/标准名、值/违规原因
- alert 文案改为「X 个标准有违规（共 Y 条违规记录）」
- .field-link / .field-link--active CSS：选中字段高亮

数据 / UI 一致性验证：本后端 AST 通过；本地 == HTTP 服务返回（59051 字节）。
"

用户反馈国标违规 tab 列被压扁、表格未铺满。上一版用 overflow-x:auto 包裹
未能根治。根因：原 el-table-column type="expand" 嵌套子 el-table 加
el-tabs__content 的 overflow:hidden 组合在某些视口下渲染异常。

参照字段长度异常 tab 的简洁模板布局重做两个表：

按标准统计（7 列，无展开）：
  - 标准         width=120
  - 标准名称    min-width=380  模板：粗体代码 + 小字名称
  - 字段数      width=100 align=right
  - 抽样数      width=120 align=right
  - 违规数      width=120 align=right
  - 违规率      width=140 三色（>50% 红 / >20% 橙 / 余绿）
  - 字段清单/违规率  min-width=340  模板内联最多 6 个字段，超出显示「…等共 N 个字段」
    （替代原本的展开行，违规率按字段级别上色）

违规明细（3 列大幅合并）：
  - 表 / 字段         min-width=280  模板：粗体表名 + 小字字段名
  - 标准 / 标准名     min-width=320  模板：粗体规则代码 + 小字标准名
  - 值 / 违规原因    min-width=420  模板：<code> 包值 + 小字错误原因

样式统一字段长度 tab：
  el-table style="margin-top: 12px; width: 100%" max-height="480"
删除上一版的 overflow-x: auto 包裹（不再需要）。

验证：本地 == HTTP 服务返回（54914 字节一致）。

原规则只按 column_name 正则匹配，对命名不规范但注释清楚的字段（如
code_a / value1 等通用名）漏判。本次扩展：

- 规则结构改 dataclass LengthRule：
    name_pattern: re.Pattern
    comment_keywords: tuple[str, ...]
    expected_length / standard / description
- 每条规则同时给出字段名正则 + 字段注释关键字列表（CI 子串匹配）
- 新增 _match_rule(col_name, col_comment, rule) → (hit, basis_text)
    字段名正则未命中再试注释关键字
- issue dict 新增字段 basis：
    "column_name 匹配 ^pattern$"  或  "column_comment 命中关键字「kw」"
- summary 新增 matched_by_name / matched_by_comment 计数

注释关键字示例（已覆盖常见中文命名习惯）：
  身份证号 → 身份证 / 公民身份
  手机号   → 手机号 / 手机号码 / 移动电话
  信用代码 → 统一社会信用代码 / 社会信用代码 / 信用代码
  行政区划 → 行政区划 / 行政区划代码 / 地区编码
  邮政编码 → 邮政编码 / 邮编
  邮箱     → 邮箱 / 电子邮件 / e-mail
  银行卡   → 银行卡号 / 银行卡

前端 '字段长度异常' tab：'国家标准 / 规则' 列加宽 320→340，下方新增一行
'依据：<basis>' 小字斜体，便于审计。

烟雾测试 5 用例：t1.id_card(身份证号)、t4.region_code(空注释) 走字段名；
t2.code_a(注释含手机号)、t5.admin_code(注释含行政区划代码) 走注释关键字；
t3.remark(备注) 正确剔除。

原 v-if="currentJob" 的'取消任务'按钮：
  - 任务运行中 → 显示
  - 任务完成/失败/取消后 → currentJob 仍 truthy，但用户已无'取消'语义可做，
    按钮消失后再无任何动作按钮，体验断层

改成按状态显示两种按钮：
  - 运行中：'取消任务' (danger, 调用 cancelJob 走 DELETE /api/jobs/{id})
  - 其它状态（已完成/失败/已取消/有旧结果）：'重新分析' (warning)
    调用新增的 resetAndStart()：
      - clearInterval(pollTimer) + close SSE
      - 重置 currentJob / jobResult / jobStatus / logs 全清零
      - await startJob() 重新启动一次

测试：本地文件 = 服务返回（52958 字节一致），Refresh 图标已确认存在于 icons-vue 包。

上一轮改完后，用户截图反馈：
  - 表名/字段名/国家标准/规则 4 列内容不显示（show-overflow-tooltip + 窄列下被截断到看不见）
  - 表注释、字段注释两个数据字段没列展示
  - 表格没铺满 tab 区域，右边大量空白

修复（6 列合并布局，总宽 1240px）：
  - 表名 / 表注释       width=260   模板展示：粗体表名 + 小字表注释（无则斜体）
  - 字段名 / 字段注释   width=240   模板展示：粗体字段名 + 小字字段注释
  - 长度 (实际/标准)    width=130   模板：实际值红色加粗 / 灰色 / 标准值
  - 浪费字节           width=90    模板渲染
  - 国家标准 / 规则    width=320   模板：粗体标准号 + 小字规则说明
  - 建议               width=200   直接 prop
- el-table 加 style="width: 100%"，强制撑满 tab 容器宽度
- 去掉全部 show-overflow-tooltip，避免窄列截断到不可见
- max-height=560，行多时纵向滚动

数据字段 table_comment/column_comment 在 step6 产出里就有，无需改后端。

原表 9 列、累计固定宽 1100+px、首两列 fixed → 在较窄窗口下渲染异常。
改为 7 列、min-width 弹性布局、去掉 fixed、合并'实际长度/标准长度'：
  - 表名          min-width=140  show-overflow-tooltip
  - 字段名        min-width=130  show-overflow-tooltip
  - 长度(实际/标准) min-width=130 模板渲染 (实际红色加粗/灰色/标准)
  - 浪费字节       width=90   align=right
  - 国家标准      min-width=120  show-overflow-tooltip
  - 规则          min-width=160  show-overflow-tooltip
  - 建议          min-width=160  show-overflow-tooltip
  - el-table 加 max-height=560，行多时纵向滚动

数据字段全部已在 step6 产出，无需改后端。
验证：HTTP 抓取的页面 HTML 已含新表格定义。

- step6_length_check.py: 移除 llm 入参与自定义字段 LLM 推断分支，
  只保留内置 GB/YD 14 条规则；签名简化为 run_step6(dict_data, log)
- orchestrator.py: STEP_REGISTRY 中 Step 6 的 llm_mode 由 optional 改为 none；
  _run_step6 不再向 run_step6 传 llm；顶部 llm_mode 取值注释同步
- routes.py: /api/steps 返回的 Step 6 描述去掉「LLM 可选」字样
- README.md: LLM 依赖矩阵删除 Step 6 行，新增说明 Step 1/3/4/6/7/8 均无 LLM 依赖
- DESIGN.md: Step 6 章节由「固定 + LLM 混合」改为「100% 固定代码」，
  删除 suggest_length_rule 示例
- CLAUDE.md: 补充「不要自动提交，我说提交再提交」纪律

验证：
  - ast.parse 通过 (orchestrator.py / routes.py / step6_length_check.py)
  - 烟雾测试：varchar(50) id_card + varchar(20) mobile → 2 条异常，符合预期

上一个提交引入了 wave 调度,如果用户勾选了有依赖的
Step 但没勾该依赖(如选 1/3/4/5 但不选 2),
调度器会在 ready=[] 时抛 RuntimeError('调度死锁'),
整个 job 标失败,日志提示看起来很严重但其实只是用户配置问题。

修复:
- 在进入 wave 调度前加预处理,把'依赖不在计划里'
  的 Step 拎出来 WARN 跳过(沿用非关键失败的处理路径)
- 把 wave 循环里 ready=[] 时的 RuntimeError 降级为 ERROR +
  break(防御性保留,理论上预处理后不应该再发生)
- 调度计划日志里多加一行 '因依赖缺失跳过=...' 字段,
  用户 / 排查时可以一眼看出被跳了哪个

验证(steps=[1,3,4,5] 此次失败案例):
  调整前:Job 失败,错误 '调度死锁: 剩余 [3] 但无依赖被满足'
  调整后:Step 3 因缺 [2] 被 WARN 跳过,Job 正常跑完 1/4/5

目标
- Step 1（数据字典）为强制步骤，前后端都防御性兜底
- 其余 Step 按依赖图分波并行执行（Wave 调度）
- Step 8 报告生成显式排在所有主步骤之后

调度器（orchestrator.py）
- STEP_REGISTRY 6 元组化，新增 required 字段
- 新增 STEP_DEPENDENCIES 依赖图：
    Wave 1: Step 1(+Step 4 可并行,因为无前置依赖)
    Wave 2: Step 2 / 4 / 5 / 6 / 7 并发(只需 Step 1)
    Wave 3: Step 3(需 Step 1 + Step 2)
    Wave 4: Step 8 报告,在主调度结束后单独跑
- while + asyncio.gather 实现 wave 调度
- 必选步骤缺失时自动追加并打 WARN 日志
- 关键 Step 失败:整流程终止;非关键:标记 failed,
  其余步骤继续(基于依赖的 wave 仍正常推进)
- _run_step4 改为接收 step_outputs["1_data_dict"],
  避免在 Wave 1 与 Step 1 重复连库拉元数据

step4_empty_fields.py
- run_step4 新增 dict_data 参数;复用 Step 1 数据,
  缺省时回退到自取(支持独立跑 Step 4)

前后端契约
- models.StepInfo 加 required: bool
- routes.py /api/steps 给 Step 1 标 required=True
- index.html:el-checkbox :disabled="s.required"
  + 必选 step 标题旁红色 "必选" 标签
- startJob 启动前再兜底检查一次 form.steps 是否包含所有必选

perf
- 全部 8 步情形下,从串行 ~55s 降至 ~30s 级别
  (Wave 2 同时跑 5 个, 加上 LLM 同时批分类 vs 串行等待)

后端
- models.py: OverviewStats 补充 mid_empty_fields / standards_applied 字段，
  避免被 routes.py 的字段过滤机制误删
- orchestrator.py: _build_overview 修正 nested overview_meta 取值（三层嵌套，
  之前一直兜底到 0 → 表/字段总数显示 0)
- step4_empty_fields.py: 修复 table_comment 始终为空（之前从列级 row 取
  table_comment，应从 table_summary 取），新增 per_table.total_fields 与
  field_record 用同一份 table_comment_map

前端 (index.html / style.css)
- 隐藏历史记录入口（保留后端接口，便于以后恢复）
- 移除「中空字段」KPI 卡片（位于中间不符合浏览习惯）
- 大范围空字段 tab：
  * 字段明细（平铺：等级/表名/表注释/字段名/字段注释/类型/空值数/空值率）
    上移到主视图位置
  * 按表统计下移为辅助视图，表名+表注释合并到一列避免错位
- 冗余字段 tab：把 prop 改成与后端实际数据一致的
  field/table_count/classification/reasoning/recommendation/source，并
  给 llm_failed / true_redundancy / suspicious / common_business /
  common_base 各加色 tag 显著标识
- 修复"\"LLM 失败\""导致的 template compile 错误引发的白屏
  （HTML 属性里 \ 不会被当 JS 转义，把 " 换成「 」即可）
- .app-main 宽度 1400 → 1800px，table 更舒展

Why：与本次\"分批次提交并写明关联性\"的工作一致，固化到 CLAUDE.md，
     后续每次 commit 都遵循\"提交信息描述清楚做了什么、为什么\"的格式。

把工作流包装成浏览器化的产品：填表 → 测试连接 → 一键治理 → 实时进度。

核心架构
- web/app.py         FastAPI 入口 + CORS + 静态资源挂载
- web/start.py       启动前依赖检查（可选 anthropic / dmPython）
- web/start.bat      Windows 一键启动脚本
- web/api/routes.py  12 个 REST 接口（jobs/history/standards/reports...）

调度与运行
- web/core/orchestrator.py 8 步流程调度 + 步骤级日志 + 异常 traceback
- web/core/job_manager.py  后台任务管理 + LogBuffer + SSE 订阅
- web/core/db_adapter.py   MySQL / 达梦 统一连接与查询
- web/core/step_impl/      8 个 Step 的 Web 版实现

LLM 增强（可降级）
- web/core/llm.py          Anthropic / OpenAI / MiniMax 多 provider 适配
- configs/llm.example.yaml provider / api_key / base_url / model 模板

SQL 模板体系（Python 不再写 SQL）
- web/sql/info_schema/     list_columns / list_tables  按 dialect 区分 MySQL / 达梦
- web/sql/verify/          count_table_rows
- web/sql/empty_fields/    count_with_nulls
- web/sql/xzqh/            check_dict_table_exists / find_xzqh_orphans
- web/sql/standards/       sample_field_values
- web/sql/health/          check_connection
- web/sql/loader.py        占位符 + dialect 自动加载

前端（无构建步骤）
- web/static/index.html    Vue 3 单页应用
- web/static/lib/          Vue + Element Plus 静态资源
- web/static/style.css

实时日志 / 历史归档 / 报告下载
- SSE 流（GET /api/jobs/{id}/logs/stream）
- outputs/<db>/<ts>/findings/_all_findings.json
- outputs/<db>/<ts>/reports/{md,docx}
- GET /api/history /api/reports/{db}/{ts}/{file}

调试能力（本次一并落地）
- 三路日志：SSE 实时流 + web/logs/app.log + outputs/<db>/<ts>/run.log
- 每步开始 / 完成带耗时、进度 N/M；异常带 traceback 与异常类型
- 数据库 [DB] 连接 / SQL 执行时间；路由 [POST /api/xxx] 入参摘要
- 启动脚本自带 web/logs/start.log

Why：CLI 工作流需要登录机器；Web 端把治理入口放到任何能开浏览器的设备上，
     配合 SSE 实时反馈，业务方也能直接用。
How：复用 workflow/ 中的 8 步逻辑与 standards/ 国标插件；新增 Pydantic 契约
     + job_manager + SSE，前后端用 REST + 事件流通信。

把以下两个文件加入 .gitignore，避免 API Key / 主机信息泄露：
- web/configs/llm.yaml        含 provider api_key
- workflow/config.yaml        含 DB host / user（密码走 env var）

对应的模板文件仍纳入版本控制：
- web/configs/llm.example.yaml
- workflow/config.example.yaml

Why：执行治理时本地会有真实凭据，复用项目时按模板复制即可。

把 Phase 1 的 7 个独立脚本收敛成一条流水线：

工作流核心 workflow/
- run_governance.py：CLI 入口，支持 --db / --steps / --skip / --offline
- config.example.yaml：阈值 / 数据库 / 输出配置（实际 config.yaml 不入库）
- core/
    db.py      连接与查询辅助
    utils.py   配置加载、目录管理、JSON I/O
    reporter.py Markdown + Word 报告生成
- steps/       8 个 Step 的实现（每个文件一个 Step）

8 步流水线：
  1 数据字典 -> 2 合并/冗余(离线) -> 3 数据验证(连库)
  -> 4 空字段(连库) -> 5 缺注释(离线) -> 6 长度检查(离线)
  -> 7 国标校验(连库) -> 8 报告生成(离线)

国标插件 standards/ 独立可扩展
- base.py + registry.py 自动发现所有标准
- std_001_id_card.py   GB 11643-1999  身份证
- std_002_uscc.py      GB 32100-2015  统一社会信用代码
- std_003_mobile.py    YD/T 1313      手机号
- std_004_xzqh.py      GB/T 2260      行政区划代码

Why：脚本是一次性产物，工作流才是可复用的工程；分离国标后新增规范
     只需要再写一个 std_xxx.py 文件。
How：每个 Step 是独立类，产出统一为 dict，run_governance.py 按编号串行
     执行；国标通过字段名匹配自动加载，registry 提供全局发现。

第一阶段，针对 smart-build 数据库做一次性手工治理：
- fetch_data_dictionary.py：拉取 information_schema，输出 data_dictionary.json
- check_empty_fields.py：逐表扫 NULL/空字符串比例，输出高空字段报告
- verify_merge_redundancy.py + .sql：连库验证合并候选的实际行数
- validate_standard_fields.py：对身份证/手机/统一社会信用代码等抽样校验
- check_field_length.py：识别 VARCHAR 超出固定长度的字段（基于国标）
- check_uncommented_fields.py：扫描无注释字段，按字段名启发式推测
- generate_report.py：把以上 JSON 汇总成 Word 报告

Why：先把\"用什么工具看什么数据\"跑通，再抽象成可复用工作流。
How：每个脚本独立运行，输出落 JSON 到 data_dictionary/，最终由
     generate_report.py 汇总成 数据治理报告_smart-build.docx。

定义项目的核心目标与约束：
- 只读分析 smart-build 数据库（MySQL），不修改任何数据
- 五个治理方向：可合并表/冗余字段、空字段、缺注释、固定长度字段、规范字段
- 已识别的国标：身份证、统一社会信用代码、手机号、地区编码
- 工作流分阶段沉淀：脚本 -> 工作流 -> Web 端

Why：后续所有治理脚本、工作流、Web 端都以本目标为准绳。
How：CLAUDE.md 描述目标；.gitignore 屏蔽运行产物（outputs/、JSON
     输出、__pycache__、work-logs 等），保留源代码本身。