fix: 项目使用手册更新

README.md

@@ -1,74 +1,164 @@
 # LQKgDataGovernance
 
-路桥数据治理与知识库入库脚本项目（标准规范 + 施工方案 + 状态数据）。
+路桥知识库数据治理脚本集合，主要处理：
+- 编制依据（标准规范）
+- 施工方案
+- 编制依据时效性状态
+- 编制依据实体（术语/背景信息）
 
-## 1. 项目启动
+数据会按脚本流程写入 `Milvus`、`MinIO`、`MySQL`。
 
-### 1.1 环境要求
-安装uv
-powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
+## 快速上手（建议先看）
 
-- Python 3.12+
-- 可访问的服务：Milvus、MinIO、MySQL（如果要跑数据库入库脚本）
+### 1) 环境准备
+- Python `3.12+`
+- 建议使用 `uv`
+- 需要可访问的服务：`Milvus`、`MinIO`、`MySQL`（按你要跑的脚本决定）
 
-### 1.2 安装依赖
+PowerShell 安装 `uv`：
 
-使用 `uv`：
-
-```bash
-uv venv 
-uv sync --index-url https://pypi.tuna.tsinghua.edu.cn/simple
+```powershell
+irm https://astral.sh/uv/install.ps1 | iex
 ```
 
-### 1.4 运行脚本（示例）
-
-进入项目根目录后执行：
+项目根目录安装依赖：
 
 ```bash
-uv run -m src.app.scripts.statu_to_milvus
+uv venv
+uv sync --index-url https://pypi.tuna.tsinghua.edu.cn/simple
 ```
 
-> 提示：大多数脚本在文件顶部有路径常量（如 `ROOT_FOLDER`、`EXCEL_PATH`），运行前请先改成你本机路径。
-
----
+### 2) 先改配置再运行
 
-## 2. 文件说明
+本项目多数脚本是“一次性批处理”，参数直接写在脚本顶部（例如 `ROOT_DIR`、`EXCEL_PATH`、`OUTPUT_JSON`、数据库连接参数等）。
 
-#### base（编制依据）
+运行前请先打开目标脚本，改成你本机路径和连接信息，再执行命令。
 
-- `base_count.py`：比对 Excel ID 与目录，输出缺失目录清单 JSON
-- `base_check.py`：检查目录结构/命名与 Excel 是否一致，输出问题清单
-- `base_info_json_generation.py`：按 Excel + 文件夹生成标准信息 JSON，并切分 MD 为 parent/children
-- `base_in_minio.py`：上传原始文件、MD、JSON 到 MinIO
-- `base_info_in_database.py`：将 JSON 中文档信息写入 MySQL（文档主表 + 标准基础信息表）
-- `base_create_collection.py`：创建 Milvus parent/child collection（含 BM25 function）
-- `base_in_collection.py`：将 JSON 的 parent/children 生成向量并写入 Milvus
+### 3) 运行方式
 
-#### plan（施工方案）
+统一推荐：
 
-- `plan_count.py`：比对 Excel ID 与目录，输出缺失目录清单 JSON
-- `plan_check.py`：检查施工方案目录结构/命名与 Excel 的一致性
-- `plan_info_json_generation.py`：生成施工方案 JSON，并切分 MD 为 parent/children
-- `plan_info_in_minio.py`：上传施工方案原始文件、MD、JSON 到 MinIO
-- `plan_info_in_database.py`：将施工方案 JSON 信息写入 MySQL
-- `plan_info_in_collection.py`：将施工方案 parent/children 向量化后写入 Milvus
-- `plan_chaxun.py`：按 `missing_folders.json` 在目录中做名称匹配检查的小工具
-
-#### 其他/测试脚本
-
-- `statu_to_milvus.py`：状态数据（含发布单位）向量化并写入 Milvus 指定 collection
-- `copy_pdf_md_files.py`：拷贝各子目录中的 PDF/MD 到目标目录，保留子目录结构
-- `ceshi.py`：MinIO 上传测试脚本（批量上传 md）
-- `ceshi_embdding.py`：Embedding 接口联通测试脚本
-- `python_processed_article`：python脚本修复层级
-- `extract_bfp.py`：遍历指定目录的 PDF/DOCX，提取每份文档的“编制依据”章节并汇总标准/法规编号
-- `page_index_md.py`：将 Markdown 目录结构解析成树形 JSON（可选精简/摘要），用于生成节点级索引
+```bash
+uv run -m src.app.scripts.<script_name>
+```
 
----
+示例（状态 Excel 转 JSON）：
 
-## 4. 注意事项
+```bash
+uv run -m src.app.scripts.status_excel_info_json
+```
 
-- 多数脚本为“一次性批处理”，执行前请先确认顶部路径配置。
-- `base_*` 与 `plan_*` 基本一一对应，不要混用目录。
-- 如果 Milvus schema 未开启动态字段，写入字段必须与 collection 定义完全一致。
+## 常用流程（按业务）
+
+### A. 编制依据（base）
+
+最常见顺序：
+1. `base_count.py`：Excel 与目录编号对比（找缺失）
+2. `base_check.py`：目录结构与命名校验
+3. `base_info_json_generation.py`：生成入库 JSON（含 parent/children）
+4. `base_in_minio.py`：上传原始文件/MD/JSON 到 MinIO
+5. `base_info_in_database.py`：写入 MySQL
+6. `base_collections_create.py`：创建 Milvus 集合（首次）
+7. `base_in_collection.py`：向量化并写入 Milvus
+
+### B. 施工方案（plan）
+
+流程与 base 基本一致：
+1. `plan_count.py`：Excel 与目录编号对比（找缺失）
+2. `plan_check.py`：目录结构与命名校验
+3. `plan_info_json_generation.py`：生成入库 JSON（含 parent/children）
+4. `plan_info_in_minio.py`上传原始文件/MD/JSON 到 MinIO
+5. `plan_info_in_database.py`：写入 MySQL
+6. `plan_info_in_collection.py`：JSON向量化并写入 Milvus
+
+`t_kngs_construction_plan_collections_create.py` 与 `t_kngs_construction_plan_collections_import.py` 是施工方案知识结构片段的另一套父子表流程。
+
+### C. 时效性状态（status）
+
+常见顺序：
+1. `status_excel_info_json.py`：Excel 提取关键字段生成 JSON
+2. `status_info_in_database.py`：JSON 写入 MySQL 状态表
+3. `first_bfp_collection_status_create.py`：创建状态检索集合（首次）
+4. `status_to_milvus.py`：状态文本向量化写入 Milvus
+
+### D. 实体数据（entity）
+
+常见顺序：
+1. `first_bfp_collection_entity_create.py`：创建实体集合（首次）
+2. `first_bfp_collection_entity_import.py` 或 `first_bfp_collection_entity_import_v2.py`：抽取并导入实体
+
+## 目录说明（重点）
+
+- `src/app/scripts/`：主脚本目录（base / plan / status / entity / 工具脚本）
+- `src/app/scripts/tool/`：抓取、去重、对比等辅助工具
+- `src/app/scripts/ceshi/`：专家意见筛选脚本
+
+## 全量脚本清单（当前仓库）
+
+### `src/app/scripts/`
+
+- `base_check.py`：检查编制依据目录结构与命名是否和 Excel 一致，输出问题清单。
+- `base_collections_create.py`：创建编制依据 Milvus 父子 collection（含索引与 BM25 稀疏配置）。
+- `base_count.py`：对比 Excel `id` 与目录子文件夹，输出缺失编号清单。
+- `base_create_collection.py`：创建编制依据 collection 的测试/示例版脚本，用于先跑通 schema。
+- `base_in_collection.py`：将编制依据 JSON 的 `parent/children` 向量化后批量写入 Milvus。
+- `base_in_minio.py`：上传编制依据原始文件、MD、JSON 到 MinIO 指定前缀。
+- `base_info_in_database.py`：将编制依据 JSON 写入 MySQL（文档主表 + 标准基础信息表）。
+- `base_info_json_generation.py`：按 Excel + 文件夹生成编制依据 JSON，并补充 parent/children 结构。
+- `character_repair.py`：批量修复文本中的异常字符/乱码字符。
+- `ceshi_embdding.py`：测试 embedding 接口连通性与返回向量维度。
+- `ceshi_minio.py`：测试 MinIO 上传流程是否正常。
+- `copy_pdf_md_files.py`：复制各子目录下 PDF/MD 到目标目录并保留层级结构。
+- `extract_bfp.py`：从 PDF/DOCX 抽取编制依据相关章节并汇总标准/法规条目。
+- `first_bfp_collection_entity_create.py`：创建实体检索用 Milvus collection。
+- `first_bfp_collection_entity_import.py`：从文档中抽取实体并向量化导入 Milvus。
+- `first_bfp_collection_entity_import_v2.py`：实体导入增强版（更强抽取与结构处理能力）。
+- `first_bfp_collection_status_create.py`：创建时效性状态检索的 Milvus collection。
+- `html_tables_to_md.py`：将 Markdown 文件中的 HTML 表格转换为 Markdown 表格。
+- `page_index_md.py`：解析 Markdown 标题层级并生成树形索引 JSON。
+- `pdf_info_image.py`：按页将 PDF 转成图片并输出到同名目录。
+- `plan_chaxun.py`：读取缺失清单，在目录中做名称包含匹配辅助排查。
+- `plan_check.py`：检查施工方案目录结构/命名与 Excel 的一致性。
+- `plan_count.py`：对比施工方案 Excel 与目录 ID，输出缺失目录清单。
+- `plan_entity_import_engine.py`：从施工方案/编制依据 MD 抽取实体并批量导入实体库的通用引擎版脚本。
+- `plan_info_in_collection.py`：将施工方案 JSON 的 parent/children 向量化后写入 Milvus。
+- `plan_info_in_collection_v2.py`：施工方案入库增强版，支持断点续传、失败报告、Milvus 进度校验与更细分文本切分。
+- `plan_info_in_database.py`：将施工方案 JSON 写入 MySQL（文档主表 + 方案基础信息表）。
+- `plan_info_in_minio.py`：上传施工方案原始文件、MD、JSON 到 MinIO。
+- `plan_info_json_generation.py`：按 Excel + 文件夹生成施工方案 JSON，并补充 parent/children。
+- `python_processed_article.py`：调用 LLM 对文章内容做结构化整理与分块输出。
+- `run_all.py`：批量调用 `mineru` 转换 PDF，记录成功/失败与重跑进度日志。
+- `select_url.py`：抓取标准网站信息（状态/发布日期/发布部门等）并增量保存结果。
+- `status_excel_info_json.py`：从时效性 Excel 提取关键字段并导出 JSON。
+- `status_info_in_database.py`：将状态 JSON 异步写入 MySQL 状态表，输出失败记录。
+- `t_kngs_construction_plan_collections_create.py`：创建 `t_kngs` 施工方案知识结构父子 collection。
+- `t_kngs_construction_plan_collections_import.py`：将施工方案知识结构 JSON 切分后导入 `t_kngs` 父子表。
+- `专家意见提取对比.py`：比对原始文件与转换结果，将未匹配的 PDF/DOCX 移动到指定目录。
+- `提取json.py`：从根目录数字子文件夹收集 JSON 并集中拷贝到输出目录。
+
+### `src/app/scripts/tool/`（时效性核对）
+
+- `excel_info_csv.py`：将 Excel（xlsx）转换为 CSV。
+- `gongbiaoku_check.py`：从 工标库 抓取标准状态/发布日期/发布单位等信息。
+- `gongbiaowang_select.py`：从 工标网 抓取标准状态/发布日期/发布单位等信息。
+- `samr_select.py`：从全国标准信息服务平台抓取标准状态与时间字段。
+- `时效性去重.py`：按编号/名称/状态对结果去重并输出删除汇总。
+- `时效性查询结果对比.py`：对比源数据与查询结果，输出缺失/不一致/多余项。
+
+### `src/app/scripts/ceshi/`
+
+- `03-施工方案筛选.py`：施工方案评审意见筛选脚本（初始版本）。
+- `03-施工方案筛选_服务器版.py`：施工方案筛选的服务器并发版（多进程与增量缓存）。
+
+## 常见问题
+
+### 1) 脚本一运行就报路径不存在
+优先检查脚本顶部路径常量是否是你本机真实路径（很多脚本默认是历史路径）。
+
+### 2) 能不能一键全跑
+有 `run_all.py`，但该脚本内默认路径是服务器目录（例如 `/home/ubuntu/...`），本地使用前必须先改。
+
+### 3) Milvus 插入失败或字段不匹配
+先确认目标 collection schema 与脚本写入字段一致；必要时先执行对应 `*_create.py` 重建/初始化集合。
+注意问题：创建collection注意使用chinese分词器，字段创建索引 嵌入不使用OpenAI embedding