# 法律风险提示 V2 接口文档 (API Reference)

该文档定义了“法律风险提示助手” V2 版本的核心接口规范。V2 接口支持智能意图识别、多地区过滤以及高度结构化的法律风险返回。

---

## 1. 核心检索接口 (Lawrisk Search V2)

通过自然语言或事项名称检索相关的许可事项及其法律风险提示内容。

- **URL**: `/fs-ai-asistant/api/workflow/lawrisk/v2`
- **Method**: `POST` (推荐) 或 `GET`
- **Authentication**: 无 (面向前端查询) / 或根据部署配置

### 1.1 请求参数 (JSON Payload)

| 字段名 | 类型 | 必须 | 说明 |
| :--- | :--- | :--- | :--- |
| `query` | `string` | 是 | 搜索文本。支持模糊描述（如“开餐馆的风险”）或准确事项名（如“食品经营许可”）。 |
| `region` | `string|array` | 否 | 地区过滤。支持地区 ID 或名称（如 `"市级"`, `["禅城区", "南海区"]`）。 |
| `top` | `number` | 否 | 推荐问题返回数量，默认为 5。 |
| `debug` | `boolean` | 否 | 为 `true` 时返回检索路径、LLM 耗时等调试信息。 |

### 1.2 响应字段说明

#### 整体结构
| 字段名 | 类型 | 说明 |
| :--- | :--- | :--- |
| `success` | `boolean` | 接口调用是否成功。 |
| `message` | `string` | 结果描述。 |
| `data.risk_subject` | `array` | 匹配到的主体信息列表。 |
| `data.questionExtend` | `array` | 推荐的相关问题列表（基于数据库内的主题动态生成）。 |
| `data.llmRespond` | `string` | 辅助话术（仅在未匹配到结果时提供提示语）。 |
| `data.executionTime` | `number` | 后端总耗时（ms）。 |

#### risk_subject (匹配主体) 内部结构
| 字段名 | 类型 | 说明 |
| :--- | :--- | :--- |
| `region` | `object` | 主体所属行政区划 (`id`, `name`)。 |
| `theme` | `object` | 主体所属行业分类 (`id`, `name`)，如“餐饮服务”。 |
| `permits` | `array` | 该主体下包含的具体行政许可事项。 |

#### permits (具体事项) 内部结构
| 字段名 | 类型 | 说明 |
| :--- | :--- | :--- |
| `id` | `uuid` | 事项唯一标识。 |
| `name` | `string` | **事项名称**。 |
| `jurisdiction_scope`| `string` | **事项实施层级**。 |
| `contact_info` | `string` | **联系方式 (外部)**。面向公众的咨询服务热线（已替换原内部负责部门信息）。 |
| `unit_name` | `string` | **实施单位名称**。 |
| `source_update_date`| `string` | 数据最新更新日期 (YYYY-MM-DD)。 |
| `risks` | `array` | **法律风险详情列表**。 |

#### risks (风险详情) 内部结构
| 字段名 | 类型 | 说明 |
| :--- | :--- | :--- |
| `serial_number` | `string` | 风险项序号。 |
| `risk_content` | `string` | **风险提示内容文本**。 |
| `legal_basis` | `string` | **法律依据**。 |
| `document_no` | `string` | **文号**。 |
| `summary` | `string` | **摘要**。关键法律条款缩影。 |
| `remark` | `string` | **备注**。额外的法律补充说明（独立于摘要）。 |

---

## 2. 地区列表接口

获取系统内所有已注册并有数据的行政区域。

- **URL**: `/fs-ai-asistant/api/workflow/lawrisk/v2/regions`
- **Method**: `GET`

### 2.1 响应示例
```json
{
  "success": true,
  "data": {
    "regions": [
      { "id": "uuid-1", "name": "市级" },
      { "id": "uuid-2", "name": "禅城区" }
    ]
  }
}
```

---

## 3. 主题列表接口 (V2 Themes)

获取系统中所有可用的行业主题及其对应的事项统计。

- **URL**: `/fs-ai-asistant/api/workflow/lawrisk/v2/themes`
- **Method**: `GET`

### 3.1 响应字段说明
- `data.themes`: 包含主题名称、唯一 ID、关联事项数量及关联地区数量。

---

## 4. 未绑定事项接口 (Unbound Permits)

返回所有已进入系统（在地区中有数据）但尚未分配到任何主题的许可事项。

- **URL**: `/fs-ai-asistant/api/workflow/lawrisk/v2/unbound-permits`
- **Method**: `GET`

### 4.1 响应字段说明
- `data.permits`: 包含地区信息、事项名称、实施单位及更新时间。用于快速定位需要分类的数据。

---

## 5. 事项列表接口 (Legacy Get Permits)

获取指定地区下所有的许可事项列表。

- **URL**: `/fs-ai-asistant/api/workflow/lawrisk/getPermits`
- **Method**: `POST`

---

## 6. 数据更新策略

- V2 接口返回的所有数据均支持动态更新。
- 导入 Excel 时，请确保“摘要”和“备注”列正确填写，接口会严格区分两者。
- 联系方式统一采用 Excel 模板中的“联系方式”列（外部咨询），不再返回内部关联部门信息。