# 标准库匹配模块 - 时效性审查

## 简介

本模块提供基于内存匹配规则的标准时效性审查功能，替代原有的向量搜索+LLM判断方式，具有以下优势：

- **高性能**：数据加载到内存后，查询无需访问数据库
- **准确性**：基于规则的精确匹配，不受LLM幻觉影响
- **无LLM依赖**：纯规则匹配，无需调用大模型
- **易于维护**：清晰的匹配规则逻辑，便于调试和优化

## 模块结构

```
standard_matching/
├── __init__.py              # 模块导出
├── standard_dao.py          # 数据访问对象（从MySQL加载数据）
├── standard_service.py      # 核心业务逻辑（内存匹配）
└── README.md               # 使用说明
```

## 核心组件

### 1. StandardMatchingService

标准匹配服务，对外暴露的统一接口。

**主要方法：**
- `initialize()`: 从数据库加载数据到内存（只需调用一次）
- `check_standards(standards)`: 批量检查标准列表
- `check_single(seq_no, name, number)`: 检查单个标准

### 2. StandardTimelinessReviewer

时效性审查器，位于 `reviewers/standard_timeliness_reviewer.py`，提供更高级的审查功能。

**主要方法：**
- `review_standards(standards)`: 审查标准列表，返回详细审查结果
- `review_single(name, number, seq_no)`: 审查单个标准
- `convert_to_standardized_format(results)`: 转换为标准格式（兼容原有审查系统）

## 使用示例

### 方式1：使用便捷函数（推荐）

```python
import asyncio
from foundation.infrastructure.mysql.async_mysql_conn_pool import AsyncMySQLPool
from core.construction_review.component.reviewers import review_standards_timeliness

async def main():
    # 初始化数据库连接池
    db_pool = AsyncMySQLPool()
    await db_pool.initialize()

    # 定义要检查的标准列表
    standards = [
        {"standard_name": "铁路桥涵设计规范", "standard_number": "TB 10002-2017"},
        {"standard_name": "起重机 钢丝绳 保养、维护、检验和报废", "standard_number": "GB/T 5972-2016"},
    ]

    # 执行时效性审查
    results = await review_standards_timeliness(standards, db_pool=db_pool)

    # 处理结果
    for result in results:
        print(f"{result.standard_name}: {result.process_result}")
        if result.has_issue:
            print(f"  问题: {result.issue_type}")
            print(f"  建议: {result.suggestion}")

    await db_pool.close()

asyncio.run(main())
```

### 方式2：使用异步上下文管理器

```python
from core.construction_review.component.reviewers import StandardTimelinessReviewer

async def main():
    db_pool = AsyncMySQLPool()
    await db_pool.initialize()

    async with StandardTimelinessReviewer(db_pool=db_pool) as reviewer:
        # 审查标准
        results = reviewer.review_standards(standards_list)

        # 转换为标准格式（兼容原有系统）
        standardized = reviewer.convert_to_standardized_format(
            results,
            check_item="timeliness_check",
            chapter_code="basis",
            check_item_code="basis_timeliness_check"
        )

    await db_pool.close()
```

### 方式3：直接使用 StandardMatchingService

```python
from core.construction_review.component.standard_matching import StandardMatchingService

async def main():
    # 创建服务并初始化
    service = StandardMatchingService(db_pool=db_pool)
    await service.initialize()

    # 批量检查
    results = service.check_standards([
        {"standard_name": "铁路桥涵设计规范", "standard_number": "TB 10002-2017"},
    ])

    for result in results:
        print(f"状态: {result.status_code}")
        print(f"结果: {result.final_result}")
```

## 匹配结果状态码

| 状态码 | 说明 | 风险等级 |
|--------|------|----------|
| OK | 标准现行有效 | none |
| SUBSTITUTED | 标准被替代 | high |
| ABOLISHED | 标准废止无替代 | high |
| MISMATCH | 名称与标准号不匹配 | medium |
| NOT_FOUND | 标准库不存在 | medium |

## 匹配规则流程

1. **标准号精确匹配**
   - 匹配成功 -> 检查名称是否匹配 -> 检查时效性状态
   - 匹配失败 -> 尝试模糊匹配标准号

2. **名称匹配**
   - 精确匹配成功 -> 检查时效性状态
   - 模糊匹配成功 -> 返回不匹配（标准号错误）
   - 匹配失败 -> 返回不存在

3. **时效性状态处理**
   - 现行/试行 -> 正常
   - 废止 -> 查找同名现行标准（被替代）
   - 废止无替代 -> 废止无现行

## 性能考虑

- 数据加载：应用启动时一次性从MySQL加载，约1-2秒（1000+条标准）
- 内存占用：约5-10MB（取决于标准数据量）
- 查询速度：内存操作，单次匹配 < 1ms

## 集成到现有系统

新的时效性审查逻辑可以集成到以下模块：

1. **timeliness_basis_reviewer.py**: 编制依据时效性审查
2. **timeliness_content_reviewer.py**: 三级分类内容时效性审查

集成方式：将原有的向量搜索+LLM判断逻辑替换为新的规则匹配逻辑。

示例：
```python
# 原有方式（向量搜索+LLM）
search_results = await self._async_search_basis(basis, collection_name)
match_result = await match_reference_files(reference_text=search_results, review_text=basis)
llm_out = await determine_timeliness_issue(match_result)

# 新方式（规则匹配）
from core.construction_review.component.reviewers import review_standard_timeliness_with_standardized_output
results = await review_standard_timeliness_with_standardized_output(
    standards_list,
    db_pool=db_pool
)
```

## 注意事项

1. **数据库连接池**：使用时需要传入已初始化的 AsyncMySQLPool 实例
2. **单例模式**：StandardTimelinessReviewer 支持单例模式，可通过 `get_standard_matching_service()` 获取全局实例
3. **数据更新**：如果标准库数据发生变化，需要重新初始化服务以加载最新数据
