fs-lawrisk/docs/API_V2.md

法律风险提示 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`	否
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 响应示例

{
  "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 模板中的“联系方式”列（外部咨询），不再返回内部关联部门信息。