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 等），保留源代码本身。