整体调整

d10b0631 · wangteng · 3c26a078 · d10b0631
Commit d10b0631 authored Sep 07, 2026 by wangteng
Hide whitespace changes
Inline Side-by-side

Showing with 29 additions and 334 deletions

web/README.md web/README.md +29 -334

No files found.
--- a/web/README.md
+++ b/web/README.md
-# 数据治理 Web 工具
+# 数据库工具
-> 基于 FastAPI + Vue 3 + Element Plus 的本地浏览器化治理平台
+`web` 是数据库工具的 Vue 3 + FastAPI 实现，提供数据源维护、规则配置、数据质量查询和数据库操作入口。
---
+## 当前功能
-## 🚀 快速开始
+- 数据源：新增、编辑、删除、测试连接、关键字搜索和分页。
+- 规则配置：按任务分组管理任务、字段和规则，支持复制、删除、搜索和分页。
+- 规则查询：按分组选择任务执行校验，支持中断、字段展示配置、结果分页、Excel 导出和 AI 问题分析。
+- 备份、还原、加密、解密：页面展示各自的操作记录；点击新增后在统一风格的弹框中填写操作流程。
+- 页面框架：深色主题、可展开的两级菜单、可折叠侧边栏，以及统一的弹框和分页样式。
-### 1. 安装依赖（首次运行）
+## 运行
-```bash
+前端：
-pip install -r web/requirements.txt
-```
-依赖包括：
- `fastapi` / `uvicorn` — Web 服务
- `pydantic` / `sse-starlette` — 数据模型 + SSE 流
- `pymysql` / `dmPython` / `oracledb` — MySQL / 达梦 / Oracle 驱动
- `anthropic` — Claude API（LLM 增强）
- `python-docx` — Word 报告生成
-### 2. 配置 LLM Key（可选）
-LLM 用于字段注释推测 / 合并建议 / 长度推断 / 空字段分类等智能判断。
-未配置时**自动降级**为规则推理，主流程不受影响。
-#### 方式 A：写到配置文件（推荐）
-编辑 [web/configs/llm.yaml](web/configs/llm.yaml)：
-```yaml
-provider: minimax          # 改为你用的 provider
-api_key: sk-请填入你的_MiniMax_API_Key   # ← 把这里替换为真实 Key
-base_url: https://api.minimaxi.com/anthropic
-model: MiniMax-Text-01
-```
-更多 provider 示例见 [web/configs/llm.example.yaml](web/configs/llm.example.yaml)。
-#### 方式 B：环境变量（适合容器/CI）
-```bash
-# Windows CMD
-set LLM_API_KEY=sk-xxxxx
-set LLM_PROVIDER=minimax
-# Windows PowerShell
-$env:LLM_API_KEY="sk-xxxxx"
-$env:LLM_PROVIDER="minimax"
-# Linux / Git Bash
-export LLM_API_KEY=sk-xxxxx
-export LLM_PROVIDER=minimax
-```
-#### 优先级
-```
-环境变量  >  web/configs/llm.yaml  >  内置默认值
-```
-#### 支持的 Provider
-| provider | 接入方式 | base_url | 模型示例 |
-|----------|---------|----------|---------|
-| `minimax` | Anthropic SDK + 自定义 base_url | `https://api.minimaxi.com/anthropic` | `MiniMax-Text-01` / `MiniMax-01` |
-| `anthropic` | Anthropic SDK 官方 | (默认) | `claude-sonnet-5` / `claude-haiku-4-5-20251001` |
-| `openai` | OpenAI SDK | (默认) | `gpt-4o` / `gpt-4-turbo` |
-启动时会打印当前生效的 LLM 配置：
-```
-[LLM] provider=minimax  model=MiniMax-Text-01
-[LLM] base_url=https://api.minimaxi.com/anthropic
-[LLM] api_key=sk-xxxx...xx（已配置）
-```
-前端右上角可通过 `GET /api/llm/status` 查看当前配置。
-### 3. 启动服务
-**方式 A：Python 启动**
-```bash
-python web/start.py
-# 或
-python -m web.start
-```
-**方式 B：Windows 一键脚本**
-```cmd
-web\start.bat
-```
-**方式 C：直接 uvicorn**
-```bash
-python -m uvicorn web.app:app --host 0.0.0.0 --port 8765
-```
-### 4. 浏览器访问
-打开 **http://localhost:8765**
- Web 界面：填表 → 测试连接（自动抽取数据字典） → 勾选表 → 选择检查项 → 开始治理
- API 文档：http://localhost:8765/docs
- OpenAPI JSON：http://localhost:8765/openapi.json
---
-## 🎯 功能特性
-| 特性 | 说明 |
-|------|------|
-| 🖥️ **Web 界面** | 浏览器访问，Vue 3 + Element Plus 响应式布局 |
-| 🔌 **三数据库** | MySQL（PyMySQL）+ 达梦（dmPython）+ Oracle（oracledb）统一接口 |
-| 🤖 **LLM 增强** | Claude API 用于字段注释推测 / 合并建议 / 长度推断 / 空字段分类 |
-| 📊 **多级表格** | 6 大章节各一张可展开表格，KPI 卡片概览 |
-| 📜 **国标展示** | 4 项内置标准可视化展示在页面（无需查询） |
-| 📡 **实时日志** | SSE 流式推送治理进度，含 INFO/WARN/ERROR 三色 |
-| 📥 **报告下载** | Markdown / Word 双格式，含历史报告检索 |
-| 🗂️ **历史归档** | 每次运行按时间戳归档到 `outputs/<db>/<ts>/` |
-| 🛡️ **优雅降级** | LLM 失败 / DB 失败不卡死，规则推理兜底 |
-| 🔍 **数据字典浏览器** | 测试连接后即可看到所有表/字段；勾选后只分析所选表 |
-| 🧩 **可扩展 Step 注册** | `register_step(...)` 一行注册新 Step，无需改 orchestrator |
---
-## 🗂️ 目录结构
+```powershell
+cd web
+npm install
+npm run dev
 ```
-数据治理/
-├── web/                          ← Web 工具
-│   ├── app.py                    ← FastAPI 入口
-│   ├── start.py                  ← 启动脚本（带依赖检查）
-│   ├── start.bat                 ← Windows 一键启动
-│   ├── requirements.txt
-│   ├── README.md                 ← 本文件
-│   ├── sql/                      ← 所有 SQL 模板（Python 不再写 SQL）
-│   │   ├── loader.py             ← 模板加载器
-│   │   ├── info_schema/          ← INFORMATION_SCHEMA 查询
-│   │   ├── verify/ xzqh/ standards/ empty_fields/ health/
-│   ├── core/                     ← 核心模块
-│   │   ├── db_adapter.py         ← MySQL + 达梦 + Oracle 统一接口
-│   │   ├── data_dict.py          ← 数据字典抽取（connect-test 与 orchestrator 共用）
-│   │   ├── data_dict_cache.py    ← 数据字典进程内缓存（按连接身份）
-│   │   ├── llm.py                ← Claude API 封装
-│   │   ├── job_manager.py        ← 后台任务 + SSE 推送
-│   │   ├── orchestrator.py       ← 流程调度 + Step 注册（register_step）
-│   │   ├── models.py             ← Pydantic 契约
-│   │   └── step_impl/            ← 5 个 Step 的实现（merge_redundancy / empty_fields / missing_comments / length_check / standards）
-│   ├── api/
-│   │   └── routes.py             ← REST 接口
-│   ├── static/
-│   │   ├── index.html            ← Vue 3 单页前端（连接 / 数据字典浏览器 / 配置 / 进度 / 结果 5 张卡）
-│   │   └── style.css
-│   ├── configs/
-│   │   └── defaults.yaml
-│   ├── outputs/                  ← 历史治理产出（按 db/ts 分目录）
-│   └── logs/
-│       └── app.log
-│
-├── workflow/                     ← 原 CLI 工作流（仍可用，独立运行）
-│
-└── standards/                    ← 国标插件（Web 与 CLI 共用）
-    ├── 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
-```
---
-## 🔧 API 端点速查
-| 方法 | 路径 | 说明 |
-|------|------|------|
-| GET | `/api/health` | 健康检查 |
-| GET | `/api/steps` | 列出已注册的 Step 元信息（按 step_id） |
-| GET | `/api/standards` | 列出已注册国标（页面用） |
-| POST | `/api/connect/test` | 测试连接；成功后同步抽取数据字典并缓存到 `DataDictCache` |
-| POST | `/api/jobs` | 提交治理任务（必须带非空 `tables`） |
-| GET | `/api/jobs/{id}` | 查询任务状态（含进度百分比） |
-| DELETE | `/api/jobs/{id}` | 取消任务 |
-| GET | `/api/jobs/{id}/result` | 获取完整结果 |
-| GET | `/api/jobs/{id}/logs/stream` | SSE 日志流 |
-| GET | `/api/history` | 历史治理记录 |
-| GET | `/api/reports/{db}/{ts}/{file}` | 下载报告（md/docx） |
-| GET | `/api/history/{db}/{ts}/result` | 历史结果数据 |
---
-## 🤖 LLM 依赖矩阵
-LLM 不是「增强」，对部分步骤是核心依赖：
-| step_id | LLM 模式 | 用途 | 缺 LLM 行为 |
-|---------|---------|------|------------|
-| `merge_redundancy` 表合并与冗余字段分析 | **required** | 合并 verdict + 高频字段分类 | 任务整体失败 |
-| `missing_comments` 缺失注释字段推测 | **required** | 字段语义推测（拼音/英文→中文） | 任务整体失败 |
-| `empty_fields` 大范围空字段扫描 | none | 纯程序化检查 | — |
-| `length_check` 字段长度检查 | none | 内置 GB/YD 标准规则 | — |
-| `standards` 国家标准校验 | none | 内置标准插件抽样 | — |
-### 设计要点
- **required** 步骤：任务启动时预检 LLM 可用性；不可用 → `RuntimeError` → 任务标 `JOB_FAILED`
- **optional** 步骤：LLM 可用就用，失败自动降级到规则推理
- **批处理**：`merge_redundancy` / `missing_comments` 的 LLM 调用按 15/30 字段/批，避免 200 次串行 API
- **数据字典与 Step 分离**：连接时已经抽好并缓存到 `DataDictCache`，任务启动直接复用
-LLM 调用封装在 [web/core/llm.py](web/core/llm.py)。配置 Key 见上方「配置 LLM Key」
+前端默认运行在 `http://localhost:5175`，并将 `/api` 代理到后端 `http://localhost:8767`。
-小节；未配置时勾选 LLM-required 的任务会被拦截、整体失败。
-## 🧩 新增 Step 的步骤
+后端：
-1. 在 [web/core/orchestrator.py](web/core/orchestrator.py) 末尾加一个 `_run_xxx(...)` 适配函数
+```powershell
-2. 在同一文件调一次 `register_step(step_id="xxx", title=..., requires_db=..., llm_mode="none", required=False, order=N, fn=_run_xxx)`
+cd C:\Users\cdkj\WEB\db-tools
-3. 在 [web/core/step_impl/](web/core/step_impl/) 里放实现函数，签名为 `(cfg, dict_data, llm, log, cancel_event, table_filter) -> dict`
+python -m web.backend.start
-> Step 注册是声明式 dict + decorator 风格；新增/删除/重排 Step 不需要改 orchestrator 主循环。
-## 📑 调整检查项分组（不改前端）
-「要跑的检查」卡片里的多级 / 折叠 / 排序完全由一个 JSON 文件驱动，改分组只动它。
-文件：[web/configs/analysis_tree.json](web/configs/analysis_tree.json)
-```json
-{
-  "groups": [
-    {
-      "key": "basic",
-      "title": "基础检查",
-      "description": "不需要调用大模型的基础数据质量检查",
-      "default_expand": true,
-      "children": [
-        { "step_id": "merge_redundancy" },
-        { "step_id": "empty_fields" },
-        ...
-      ]
-    },
-    ...
-  ]
-}
 ```
-字段说明：
+后端接口文档：`http://localhost:8767/docs`。
-| 字段 | 作用 |
-|------|------|
-| `key` | 分组 ID（前端无引用，但删除后整个组会消失）|
-| `title` | 组标题，显示在折叠行 |
-| `description` | 鼠标悬停在 title 上时通过原生 `title` 显示 |
-| `default_expand` | 首次加载时是否展开 |
-| `children` | 该组下的 step；每项只放 `step_id`（必须在 orchestrator 已注册）|
-未被任何 group 引用的 step 会自动归到 `__ungrouped__` 组，避免静默丢失。
-> 分组是视图层概念 —— 改 JSON 不影响后端执行什么 step，只影响 UI 怎么摆。后端契约不变。
---
-## 🛡️ 三数据库适配说明
-通过 [web/core/db_adapter.py](web/core/db_adapter.py) 统一抽象：
+## 数据存储
-| 项 | MySQL | 达梦 | Oracle |
+- 任务、字段、规则和数据源保存于 `web/data/web.db`。
-|----|-------|------|--------|
+- 数据源密码目前按内部工具模式保存；部署到共享或生产环境前，应替换为受保护的凭据方案。
-| 驱动 | `pymysql` | `dmPython` | `oracledb` 1.4.x (thin) |
+- 备份、还原、加密、解密页面的操作记录目前写入浏览器 `localStorage`，按操作类型分别保存。实际执行和服务端操作记录表尚未接入。
-| 占位符 | `%s` | `?` | `:1` |
-| 标识符引用 | `` ` `` (反引号) | `"` (双引号 ANSI) | `"` (双引号 ANSI) |
-| 字段大小写 | 视配置 | 默认大写 → 统一规范化为小写 | 默认大写 → 统一规范化为小写 |
-| 长文本类型 | `text/longtext/...` | `text/clob/longvarchar` | `varchar2/clob/nclob/long` |
-| 数据字典 | `INFORMATION_SCHEMA.COLUMNS` | `ALL_TAB_COLUMNS` | `ALL_TAB_COLUMNS` |
-| 默认端口 | 3306 | 5236 | 1521 |
-> ⚠️ 达梦驱动 `dmPython` 需要本地先安装达梦客户端，否则 `pip install dmPython` 会失败。
+## 验证
-> Oracle 用 `oracledb` thin 模式，**无需**安装 Oracle Instant Client；`database` 字段填 Oracle 的 service_name（如 `ORCLPDB1`），不是表 schema 名。
->
-> ⚠️ **Oracle 版本兼容**：本仓库把 oracledb 锁在 **1.4.x**（`requirements.txt`），因为 2.0+ 的 thin 模式收紧了对老 Oracle 的支持，**Oracle 11.2 也会报 DPY-3010**：
->
-> ```
-> DPY-3010: connections to this database server version are not supported by python-oracledb in thin mode
-> ```
->
-> 1.4.x 的 thin 模式对 11.2 ~ 最新 Oracle 都正常。如果将来只连 12c+ / 19c / 21c，可以放开到 `oracledb>=2.0`。
->
-> 若连接 **10g / 9i 等更老版本**，1.x 也报 DPY-3010，则需要装 [Oracle Instant Client](https://www.oracle.com/database/technologies/instant-client/downloads.html)，应用会在首次连接时自动 `oracledb.init_oracle_client()` 切到 **thick 模式**（OCI 原生，支持 Oracle 9i+）。Instant Client 默认从 PATH / 注册表 / `ORACLE_HOME` 自动搜索；若不在默认路径，可在请求里显式传 `oracle_client_dir` 字段（如 `r"C:\oracle\instantclient_19_8"`）。
---
+```powershell
+cd web
-## ⚠️ 已知事项
+npm run build
-1. **多数据库兼容**：所有 SQL 查询已用 ANSI 写法 + 适配层规范化，达梦 / Oracle 可直接复用；Oracle 数据字典走 `ALL_TAB_COLUMNS` / `ALL_TABLES`（无 `INFORMATION_SCHEMA`）；Oracle thin 模式不支持的版本会自动尝试加载 Instant Client 切 thick 模式
-2. **报告 bug 修复**：新版 Web 工具修正了原 `reporter.py` 的多处字段名不匹配（如 `over_provision_ratio`、`risk/suggestion` 等）
-3. **单进程**：JobManager 使用进程内 asyncio 队列，并发任务排队执行；如需多任务并行可改为 Celery
-4. **数据安全**：数据库密码仅在内存中传递，不写日志；提交前可勾选「启用 LLM」控制是否走外网
---
-## 🗃️ SQL 模板管理
-所有 SQL 语句都集中在 `web/sql/` 目录下，**Python 代码不再直接拼 SQL**。
-### 模板语法（占位符）
-| 语法 | 含义 | 示例 |
-|------|------|------|
-| `${var}` | 简单字符串替换 | `${schema}` |
-| `${var \| quote}` | 按当前 dialect 自动加引号 | `${table \| quote}` → MySQL 反引号 / 达梦双引号 / Oracle 双引号 |
-| `${list \| join:","}` | 列表按分隔符拼接 | `${cols \| join:","}` |
-### Dialect 加载规则
-加载器优先找 `<name>.<dialect>.sql`，找不到则用 `<name>.sql` 兜底。
-### 使用示例
-```python
-from web.sql.loader import get_sql_loader
-loader = get_sql_loader()
-sql = loader.render("info_schema/list_columns", dialect="mysql", schema="mydb")
-# SELECT ... FROM INFORMATION_SCHEMA.COLUMNS c WHERE c.TABLE_SCHEMA = `mydb`
-sql = loader.render("info_schema/list_columns", dialect="dameng", schema="mydb")
-# SELECT ... FROM ALL_TAB_COLUMNS c WHERE c.OWNER = "mydb"
-sql = loader.render("info_schema/list_columns", dialect="oracle", schema="mydb")
-# SELECT ... FROM ALL_TAB_COLUMNS c WHERE c.OWNER = UPPER(:1)
 ```
-详细文档：[sql/README.md](sql/README.md)
+构建成功后，Vite 会在 `dist/` 输出前端产物。
---
-## 📝 后续可扩展
- [ ] 添加更多国标插件（邮箱、银行卡、邮编等）
- [ ] 接入 jaydebeapi 作为达梦 JDBC 替代驱动（dmPython 装不上的兜底方案）
- [ ] 报告编辑器（在线编辑 Markdown / 一键导出）
- [ ] 多任务并行（Celery + Redis）
- [ ] 用户系统（FastAPI Users + JWT）
- [ ] Docker 镜像打包
---
-## 📚 相关文档
- [docs/DESIGN.md](docs/DESIGN.md) — **完整设计书**（架构、模块、LLM 判断矩阵）
- [../CLAUDE.md](../CLAUDE.md) — 顶层项目目标
\ No newline at end of file