# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## 项目概述

路桥数据治理与知识库入库脚本项目，用于将标准规范、施工方案等文档向量化并存入 Milvus/MinIO/MySQL。

**核心数据类型**：
- `base_*`：编制依据（标准规范）
- `plan_*`：施工方案
- `status_*`：时效性状态
- `entity_*`：实体抽取

## 常用命令

### 环境安装

```bash
# 创建虚拟环境（默认在项目根目录 .venv）
uv venv

# 安装依赖（使用清华镜像）
uv sync --index-url https://pypi.tuna.tsinghua.edu.cn/simple
```

### 虚拟环境

项目使用 `uv` 管理依赖，虚拟环境位于 `.venv/`。

**激活虚拟环境**：
```bash
# Windows PowerShell
.venv\Scripts\Activate.ps1

# Windows CMD
.venv\Scripts\activate.bat

# Linux/macOS
source .venv/bin/activate
```

**运行方式**：
- 推荐：直接使用 `uv run`（自动在虚拟环境中执行）
  ```bash
  uv run -m src.app.scripts.base_info_json_generation
  ```
- 或：激活虚拟环境后直接运行
  ```bash
  # 先激活虚拟环境
  # 再运行脚本
  ```

### 运行脚本

```bash
# 运行任意脚本（示例）
uv run -m src.app.scripts.base_info_json_generation
uv run -m src.app.scripts.base_in_collection
uv run -m src.app.scripts.status_excel_info_json
```

**重要**：多数脚本是"一次性批处理"，路径参数（`EXCEL_FILE`、`ROOT_FOLDER` 等）直接写在脚本顶部，运行前需改为本地路径。

## 项目架构

### 目录结构

```
src/app/
├── config/           # 配置与客户端初始化
│   ├── setting.py    # .env 配置加载（MinIO/Milvus/MySQL/Embedding）
│   ├── minio_client.py   # MinIO 客户端（单例）
│   ├── milvus_client.py  # Milvus 客户端（LRU缓存）
│   ├── embeddings.py     # MetaXEmbeddings（requests-based，非 OpenAI）
│   └── database.py       # SQLAlchemy 异步引擎
├── models/           # 数据库模型
│   └── standard_base_info.py  # 施工标准规范表模型
└── scripts/          # 数据处理脚本
    ├── base_*        # 编制依据处理流程
    ├── plan_*        # 施工方案处理流程
    ├── status_*      # 时效性状态处理
    ├── entity_*      # 实体抽取与入库
    └── tool/         # 辅助工具（时效性查询、去重等）
```

### 配置管理

所有服务配置通过 `.env` 文件管理，由 `setting.py` 的 `Settings` 类加载：

| 服务 | 关键配置项 |
|------|------------|
| MinIO | `MINIO_ENDPOINT`, `MINIO_ACCESS_KEY`, `MINIO_SECRET_KEY`, `MINIO_BUCKET_NAME` |
| Milvus | `MILVUS_HOST`, `MILVUS_PORT`, `MILVUS_DB`, `MILVUS_USER`, `MILVUS_PASSWORD` |
| MySQL | `DATABASE_URL` (async: `mysql+aiomysql://...`) |
| Embedding | `EMBEDDING_BASE_URL`, `EMBEDDING_MODEL`, `EMBEDDING_API_KEY` |

### 数据处理流程

**编制依据 (base_* 系列)**：
1. `base_count.py` → Excel 与目录编号对比
2. `base_check.py` → 目录结构/命名校验
3. `base_info_json_generation.py` → 生成 JSON（含 MD 切分 parent/children）
4. `base_in_minio.py` → 上传文件到 MinIO
5. `base_info_in_database.py` → 写入 MySQL
6. `base_collections_create.py` → 创建 Milvus Collection（含 BM25 + 中文分词）
7. `base_in_collection.py` → 向量化并写入 Milvus

**施工方案 (plan_* 系列)**：流程同上，Collection 名不同（`t_rag_kng_construction_plan_*`）。

**时效性状态 (status_* 系列)**：Excel → JSON → MySQL → Milvus 状态检索集合。

**实体 (entity_* 系列)**：从文档抽取实体并向量化导入 Milvus 实体集合。

### Markdown 切分逻辑

文档切分在 `base_info_json_generation.py` 中实现：

- **parent**：按 `#` 一级标题切分，超长段（>6000字符）再切片，共享 `parent_id`
- **children**：按中文句号 `。` 切分，保留标题上下文，标题本身不生成子表记录
- `parent_id`：由 `doc_name|parent_seq|h1_title` SHA1 生成，保证稳定
- **Markdown 表格**：整体保留，不按句号切分（避免破坏表结构）
- **HTML 表格**：自动转换为 Markdown 表格格式

### Milvus Collection Schema

Collection（父表/子表结构相同）包含以下字段：

| 字段 | 类型 | 说明 |
|------|------|------|
| `pk` | INT64 | 主键，auto_id |
| `text` | VARCHAR(65535) | 文本内容，**enable_analyzer=True, analyzer_params={"type": "chinese"}** |
| `dense` | FLOAT_VECTOR(4096) | 密集向量（语义检索） |
| `sparse` | SPARSE_FLOAT_VECTOR | 稀疏向量（BM25 函数生成） |
| `document_id` | VARCHAR(128) | 文档 ID |
| `parent_id` | VARCHAR(128) | 父节点 ID |
| `index` | INT64 | 索引序号 |
| `tag_list` | VARCHAR(2048) | 标签 |
| `permission` | JSON | 权限 |
| `metadata` | JSON | 元数据（chinese_name, standard_number, file_url 等） |
| `is_deleted` | BOOL | 删除标志 |
| `created_by/updated_by` | VARCHAR(128) | 创建人/修改人 |
| `created_time/updated_time` | INT64 | 创建/修改时间戳 |

**BM25 + 中文分词配置**（创建 Collection 时必须）：
```python
schema.add_field(
    "text",
    DataType.VARCHAR,
    max_length=65535,
    enable_analyzer=True,
    analyzer_params={"type": "chinese"},  # 关键：中文分词
)
schema.add_function(
    Function(
        name="bm25_fn",
        input_field_names=["text"],
        output_field_names=["sparse"],
        function_type=FunctionType.BM25,
    )
)
```

### 入库脚本运行时特性

`base_in_collection.py` / `plan_info_in_collection.py` 具有以下特性：

- **分批插入**：避免 GRPC 64MB 消息大小限制（默认 50 行/批）
- **重试机制**：失败自动重试 3 次，递增延迟
- **断点续传**：Ctrl+C 暂停时保存进度到 JSON，下次运行可恢复
- **VARCHAR 保护**：超长文本按 UTF-8 字节切分，不截断丢弃
- **Embedding token 保护**：文本切分同时满足 Milvus VARCHAR(65535) 和 embedding 输入限制（约 12KB）
- **幂等写入**：每个文档先按 `document_id` 清理旧数据再写入

## 开发注意事项

- **脚本路径配置**：多数脚本顶部有 `EXCEL_FILE`、`ROOT_FOLDER` 等路径常量，运行前需改为本地路径
- **base/plan 区分**：`base_*` 与 `plan_*` 脚本对应不同数据类型，Collection 名不同，不要混用
- **中文分词器**：创建 Milvus Collection 时必须配置 `analyzer_params={"type": "chinese"}`，否则 BM25 检索效果差
- **向量维度**：默认 4096 维，由 `EMBEDDING_MODEL`（通常是 Qwen3-Embedding-8B）决定
- **Embedding 客户端**：使用 `MetaXEmbeddings`（`embeddings.py`），基于 requests，非 langchain-openai
- **Embedding 批量请求**：默认 max_batch_size=16，有重试机制
- **创建 Collection**：使用 `base_collections_create.py` / `t_kngs_construction_plan_collections_create.py`，确保 schema 正确

### 常见问题

1. **脚本报路径不存在**：检查脚本顶部路径常量是否为本地真实路径
2. **Milvus 插入失败/字段不匹配**：确认 Collection schema 与写入字段一致；必要时先执行 `*_collections_create.py` 重建集合
3. **Embedding 报 context length 超限**：入库脚本已内置文本切分保护（约 12KB），检查是否使用正确脚本版本
4. **BM25 搜索效果差**：确认 Collection 创建时配置了中文分词器