# V2 API 许可证名称匹配和审批部门显示修复总结

## 提交信息
- **Commit**: 60b94d8
- **日期**: 2025-12-23
- **类型**: feat (新功能)

## 问题描述

### 1. 许可证名称匹配问题
用户查询"药品经营许可"时，系统无法直接匹配到数据库中的"药品经营许可证"，导致触发LLM而不是直接数据库查询。

### 2. 审批部门显示问题
查询"营业执照"时，返回的 `unit_name` 字段为 `null`，即使已经导入了审批部门数据。

## 根本原因

1. **严格的精确匹配**: `find_permit_contexts_by_name` 只支持完全相同的名称匹配
2. **缺失的数据表**: `permit_approval_departments` 表不存在
3. **错误的SQL语法**: 模糊匹配使用了 `||` 连接符，在某些数据库中不兼容
4. **缺少数据**: 即使表存在，也没有审批部门映射数据

## 解决方案

### 1. 许可证名称前缀匹配 (licensing_repo.py)

**修改函数**: `find_permit_contexts_by_name`

```python
# 添加前缀匹配逻辑
if not rows and len(permit_name) >= 2:
    sql_fuzzy = """
        SELECT ... FROM ... WHERE p.name LIKE %s
    """
    cur.execute(sql_fuzzy, (permit_name + "%",))
    rows = cur.fetchall()
```

**效果**: 
- "药品经营许可" 现在可以匹配 "药品经营许可证"
- "营业执照" 可以匹配 "营业执照（副本）"等

### 2. 审批部门表自动创建 (licensing_repo.py)

**新增函数**:
- `_create_permit_approval_departments_schema()`: 创建表结构
- `_ensure_permit_approval_departments_schema()`: 确保表存在

**表结构**:
```sql
CREATE TABLE IF NOT EXISTS permit_approval_departments (
    id uuid PRIMARY KEY,
    permit_name text NOT NULL,
    department_name text NOT NULL,
    created_at timestamptz NOT NULL DEFAULT now(),
    updated_at timestamptz NOT NULL DEFAULT now()
)
```

### 3. 修复SQL JOIN逻辑 (licensing_repo.py)

**修改前**:
```sql
LEFT JOIN permit_approval_departments pad 
   ON (pad.permit_name = p.name OR p.name LIKE pad.permit_name || '%')
```

**修改后**:
```sql
LEFT JOIN permit_approval_departments pad 
   ON (p.name = pad.permit_name OR p.name LIKE CONCAT(pad.permit_name, '%'))
```

**改进**:
- 使用 `CONCAT()` 函数，兼容性更好
- 支持精确匹配和前缀匹配

### 4. 新增管理API端点 (v2.py)

**端点**: `POST /fs-ai-asistant/api/workflow/lawrisk/admin/approval-departments/setup`

**功能**:
- 自动插入常见的审批部门映射
- 支持更新已存在的映射
- 返回操作统计信息

**预置映射**:
- 营业执照 → 市场监管部门
- 食品经营许可证 → 市场监管部门
- 药品经营许可证 → 市场监管部门
- 医疗器械经营许可证 → 市场监管部门
- 特种设备使用登记 → 市场监管部门

### 5. 更新 .gitignore

**新增规则**:
```gitignore
# 临时脚本
analyze_*.py
final_importer.py
ultimate_importer.py
*_importer.py

# Excel文件（除模板外）
*.xlsx
!样表.xlsx
```

## 文件变更

### 修改的文件
1. `lawrisk/services/licensing_repo.py` (+1200行)
   - 新增审批部门表管理
   - 修复许可证名称匹配逻辑
   - 修复SQL JOIN语法

2. `lawrisk/api/v2.py` (+89行)
   - 新增审批部门设置API端点

3. `.gitignore` (+9行)
   - 添加临时文件忽略规则

4. `docs/API_V2.md` (更新)
   - 文档更新

5. `static/db_admin.html` (更新)
   - 前端界面调整

## 测试验证

### 测试场景1: 前缀匹配
**输入**: "药品经营许可"
**预期**: 直接返回"药品经营许可证"的数据，不触发LLM
**结果**: ✅ 通过

### 测试场景2: 审批部门显示
**输入**: "营业执照"
**预期**: `unit_name` 返回 "市场监管部门"
**结果**: ✅ 通过

### 测试场景3: 精确匹配优先
**输入**: "营业执照"（数据库中存在完全相同的名称）
**预期**: 优先返回精确匹配结果
**结果**: ✅ 通过

## 影响范围

### 正面影响
1. ✅ 提升用户体验：减少不必要的LLM调用
2. ✅ 提高响应速度：直接数据库查询比LLM快
3. ✅ 降低成本：减少LLM API调用
4. ✅ 数据完整性：审批部门信息正确显示

### 潜在风险
1. ⚠️ 前缀匹配可能返回多个结果（已通过精确匹配优先缓解）
2. ⚠️ 需要定期维护审批部门映射表

## 后续建议

1. **数据维护**: 定期更新 `permit_approval_departments` 表
2. **监控**: 监控前缀匹配的准确率
3. **扩展**: 考虑添加同义词匹配功能
4. **文档**: 更新API文档，说明新的匹配逻辑

## 相关链接

- Commit: 60b94d8
- 相关Issue: V2 API Search Logic
- 测试环境: http://127.0.0.1:5000