# 接口文档

最终代码生成：52 个 HTTP 方法，43 条业务路径。统一前缀 `/api/v1`，OpenAPI完整请求Schema在 `openapi.json`；本清单只从实际注册接口生成。

## 身份、响应与通用参数

受保护接口发送 `Authorization: Bearer <access_token>`；Swagger `/docs` 可使用 Authorize 输入令牌。登录、刷新和健康检查无需访问令牌。角色层级不允许代签；单据所有权、部门范围、状态和版本另行验证。

成功响应为 `{"data":业务对象或分页,"message":"操作成功","request_id":"服务端追踪编号"}`。失败响应为 `{"error":{"code":"机器码","message":"原因","details":附加信息},"request_id":"追踪编号"}`。分页字段 `items/total/page/page_size`，页码从1开始，最大每页100。金额是十进制字符串，时间存UTC并返回带Z的ISO时间；报销类型1差旅/2招待/3办公，风险1低/2中/3高。

常见错误：401未登录/凭据失效；403角色或资源所有权不足；404不存在；409状态/版本/签署冲突；422字段/规则配置校验；429请求过频；503真实模型或向量不可用。校验错误不返回原始密码或令牌输入；服务内部异常只返回稳定错误码及请求ID。

下载、Excel、PDF和CSV直接返回字节；发票上传与审核events是 text/event-stream，不是JSON envelope。浏览器必须使用 fetch + Bearer 处理 SSE，不在 URL 中传令牌。

## 业务返回结构

| 资源 | data 关键字段 |
|---|---|
| 登录/刷新 | access_token、refresh_token、expires_in、token_type、user（不含密码） |
| 报销 | id、number、user_id、department_id、title、description、type、total_amount、status、revision、submitted_at、created_at |
| 报销详情 | 报销字段加 invoices、audits、approval_rounds、approvals |
| 发票 | id、filename、file_hash、content_type、declared_fields、amount、tax_amount、active；内部文件键不返回 |
| 提交/重跑 | audit_id、reimbursement；HTTP202表示排队，不表示审核通过 |
| 审核详情 | snapshot、result、nodes、rules、feedback、status、risk_level、compliance_status、decision、error_code及开始/完成时间 |
| 节点 | node_name、attempt、status、duration_ms、input、output、error_code、token_usage |
| 规则结果 | rule_code、rule_version、invoice_id、passed、severity、execution_status、message、details |
| Agent/规则配置 | 当前不可变version、参数config或params/scope；详情含current/history |
| 审批待办 | round_id、node_index、approver_id、result、opinion、audit_id、reimbursement_id、number、can_decide |
| 签署 | approval、round、reimbursement（同事务后的状态） |
| 政策 | id、title、category、content、active、version、index_status、embedding_model |
| 检索 | mode、items（chunk_id/document_id/title/version/text/score，可含rerank_score/rerank_degraded） |
| 告警 | type、severity、message、status、audit_id、reimbursement_id、ack_by、resolved_by、opinion及处理时间 |
| 日志 | actor_id、action、resource_type、resource_id、request_id、trace_id、before_json、after_json、created_at |
| 统计 | total_count、total_amount、pending_count、approved_count、statuses、risks、departments |

## 全部接口

### POST `/api/v1/auth/login`

功能：验证密码并创建会话。参数：登录名/密码。返回：双令牌与用户。异常：401凭据错误，422参数错误。

鉴权：无需访问令牌。

请求类型：`application/json`；请求契约：`Login`，字段见下方Schema表。

### POST `/api/v1/auth/refresh`

功能：刷新并撤销旧凭据。参数：refresh_token。返回：新双令牌。异常：401已撤销/过期/停用。

鉴权：无需访问令牌。

请求类型：`application/json`；请求契约：`Refresh`，字段见下方Schema表。

### POST `/api/v1/auth/logout`

功能：撤销本人刷新会话。参数：refresh_token。返回：撤销状态。异常：401失效，403非本人。

鉴权：Bearer；另校验角色/所有权/轮次，具体限制见功能说明。

请求类型：`application/json`；请求契约：`Refresh`，字段见下方Schema表。

### GET `/api/v1/auth/me`

功能：返回当前身份。参数：Bearer令牌。返回：无敏感字段的用户。异常：401失效或未登录。

鉴权：Bearer；另校验角色/所有权/轮次，具体限制见功能说明。

### GET `/api/v1/users`

功能：经理查看用户用于审批配置。参数：分页。返回：无密码用户列表。异常：403权限不足。

鉴权：Bearer；另校验角色/所有权/轮次，具体限制见功能说明。

| 参数 | 位置 | 必填 | 类型 / 约束 |
|---|---|---|---|
| page | query | 否 | integer, 默认 1, minimum=1 |
| page_size | query | 否 | integer, 默认 20, minimum=1, maximum=100 |

### POST `/api/v1/users`

功能：管理员创建有效用户。参数：用户/部门/角色/密码。返回：用户。异常：403权限，409重名，422弱密码。

鉴权：Bearer；另校验角色/所有权/轮次，具体限制见功能说明。

请求类型：`application/json`；请求契约：`UserCreate`，字段见下方Schema表。

### PATCH `/api/v1/users/{identifier}`

功能：修改身份/停用。参数：ID和允许字段。返回：更新用户。异常：403权限，404不存在，409停用自己。

鉴权：Bearer；另校验角色/所有权/轮次，具体限制见功能说明。

| 参数 | 位置 | 必填 | 类型 / 约束 |
|---|---|---|---|
| identifier | path | 是 | integer |

请求类型：`application/json`；请求契约：`UserPatch`，字段见下方Schema表。

### GET `/api/v1/departments`

功能：提供部门选项。参数：当前身份。返回：部门列表。异常：401未登录。

鉴权：Bearer；另校验角色/所有权/轮次，具体限制见功能说明。

### POST `/api/v1/departments`

功能：创建部门。参数：名称/启用。返回：部门。异常：403权限，409重名。

鉴权：Bearer；另校验角色/所有权/轮次，具体限制见功能说明。

请求类型：`application/json`；请求契约：`DepartmentBody`，字段见下方Schema表。

### PATCH `/api/v1/departments/{identifier}`

功能：更名或停用。参数：ID/名称/active。返回：部门。异常：403权限，404不存在，409重名。

鉴权：Bearer；另校验角色/所有权/轮次，具体限制见功能说明。

| 参数 | 位置 | 必填 | 类型 / 约束 |
|---|---|---|---|
| identifier | path | 是 | integer |

请求类型：`application/json`；请求契约：`DepartmentBody`，字段见下方Schema表。

### GET `/api/v1/agents`

功能：查看节点配置和实际统计。参数：当前身份。返回：五节点列表。异常：403权限不足。

鉴权：Bearer；另校验角色/所有权/轮次，具体限制见功能说明。

### GET `/api/v1/agents/{node_name}`

功能：查看节点全部版本。参数：固定节点名。返回：当前配置/历史。异常：403权限，404未知节点。

鉴权：Bearer；另校验角色/所有权/轮次，具体限制见功能说明。

| 参数 | 位置 | 必填 | 类型 / 约束 |
|---|---|---|---|
| node_name | path | 是 | string |

### PATCH `/api/v1/agents/{node_name}`

功能：创建不可变配置版本。参数：节点/预期版本/参数。返回：新配置。异常：403权限，409版本冲突，422非法配置。

鉴权：Bearer；另校验角色/所有权/轮次，具体限制见功能说明。

| 参数 | 位置 | 必填 | 类型 / 约束 |
|---|---|---|---|
| node_name | path | 是 | string |

请求类型：`application/json`；请求契约：`ConfigPatch`，字段见下方Schema表。

### POST `/api/v1/agents/{node_name}/test`

功能：真实连接或确定性节点测试。参数：节点名。返回：可用/降级原因。异常：403权限，404未知节点。

鉴权：Bearer；另校验角色/所有权/轮次，具体限制见功能说明。

| 参数 | 位置 | 必填 | 类型 / 约束 |
|---|---|---|---|
| node_name | path | 是 | string |

### GET `/api/v1/rules`

功能：查看生效规则。参数：分页/code/enabled。返回：最新版本列表。异常：403权限不足。

鉴权：Bearer；另校验角色/所有权/轮次，具体限制见功能说明。

| 参数 | 位置 | 必填 | 类型 / 约束 |
|---|---|---|---|
| page | query | 否 | integer, 默认 1, minimum=1 |
| page_size | query | 否 | integer, 默认 20, minimum=1, maximum=100 |
| code | query | 否 | string / null |
| enabled | query | 否 | boolean / null |

### GET `/api/v1/rules/{code}`

功能：追踪规则历史。参数：规则code。返回：当前及所有版本。异常：403权限，404未知规则。

鉴权：Bearer；另校验角色/所有权/轮次，具体限制见功能说明。

| 参数 | 位置 | 必填 | 类型 / 约束 |
|---|---|---|---|
| code | path | 是 | string |

### PATCH `/api/v1/rules/{code}`

功能：保存规则新版本。参数：预期版本/参数/范围/开关。返回：新版本。异常：403权限，409并发，422核心检查绕过。

鉴权：Bearer；另校验角色/所有权/轮次，具体限制见功能说明。

| 参数 | 位置 | 必填 | 类型 / 约束 |
|---|---|---|---|
| code | path | 是 | string |

请求类型：`application/json`；请求契约：`RulePatch`，字段见下方Schema表。

### POST `/api/v1/rules/{code}/test`

功能：独立试算不改变正式结果。参数：invoice/context。返回：规则证据。异常：403权限，404规则，422上下文非法。

鉴权：Bearer；另校验角色/所有权/轮次，具体限制见功能说明。

| 参数 | 位置 | 必填 | 类型 / 约束 |
|---|---|---|---|
| code | path | 是 | string |

请求类型：`application/json`；请求契约：`RuleTest`，字段见下方Schema表。

### GET `/api/v1/reimbursements`

功能：按授权范围列单。参数：分页/状态/类型。返回：报销分页。异常：401未登录，422非法分页。

鉴权：Bearer；另校验角色/所有权/轮次，具体限制见功能说明。

| 参数 | 位置 | 必填 | 类型 / 约束 |
|---|---|---|---|
| page | query | 否 | integer, 默认 1, minimum=1 |
| page_size | query | 否 | integer, 默认 20, minimum=1, maximum=100 |
| status | query | 否 | string / null |
| type | query | 否 | integer / null |

### POST `/api/v1/reimbursements`

功能：创建本人草稿。参数：标题/类型/含税额。返回：草稿。异常：422金额，409序号耗尽。

鉴权：Bearer；另校验角色/所有权/轮次，具体限制见功能说明。

请求类型：`application/json`；请求契约：`ReimbursementCreate`，字段见下方Schema表。

### GET `/api/v1/reimbursements/{identifier}`

功能：查看单据全历史。参数：ID。返回：发票/审核/审批。异常：403无权，404不存在。

鉴权：Bearer；另校验角色/所有权/轮次，具体限制见功能说明。

| 参数 | 位置 | 必填 | 类型 / 约束 |
|---|---|---|---|
| identifier | path | 是 | integer |

### PATCH `/api/v1/reimbursements/{identifier}`

功能：修改本人可编辑单。参数：revision及业务字段。返回：新版本。异常：403所有权，409状态/版本，422金额。

鉴权：Bearer；另校验角色/所有权/轮次，具体限制见功能说明。

| 参数 | 位置 | 必填 | 类型 / 约束 |
|---|---|---|---|
| identifier | path | 是 | integer |

请求类型：`application/json`；请求契约：`ReimbursementPatch`，字段见下方Schema表。

### POST `/api/v1/reimbursements/{identifier}/invoices`

功能：逐文件上传并流式留痕。参数：multipart files/revision/metadata数组。返回：SSE真实进度。异常：前置403/409/422；流内error含部分成功ID。

鉴权：Bearer；另校验角色/所有权/轮次，具体限制见功能说明。

| 参数 | 位置 | 必填 | 类型 / 约束 |
|---|---|---|---|
| identifier | path | 是 | integer |

请求类型：`multipart/form-data`；请求契约：`Body_upload_invoices_api_v1_reimbursements__identifier__invoices_post`，字段见下方Schema表。

### PATCH `/api/v1/invoices/{identifier}`

功能：用户补录未知字段。参数：ID/单据revision/fields。返回：发票与新revision。异常：403非本人，409状态，422字段。

鉴权：Bearer；另校验角色/所有权/轮次，具体限制见功能说明。

| 参数 | 位置 | 必填 | 类型 / 约束 |
|---|---|---|---|
| identifier | path | 是 | integer |

请求类型：`application/json`；请求契约：`InvoicePatch`，字段见下方Schema表。

### DELETE `/api/v1/invoices/{identifier}`

功能：从可编辑单移除发票并保留历史证据。参数：ID/revision。返回：新版本。异常：403/404/409。

鉴权：Bearer；另校验角色/所有权/轮次，具体限制见功能说明。

| 参数 | 位置 | 必填 | 类型 / 约束 |
|---|---|---|---|
| identifier | path | 是 | integer |
| revision | query | 是 | integer, minimum=1 |

### GET `/api/v1/invoices/{identifier}/file`

功能：按所有权读取原始文件。参数：ID。返回：文件流。异常：403权限，404文件不存在；不接受磁盘路径。

鉴权：Bearer；另校验角色/所有权/轮次，具体限制见功能说明。

| 参数 | 位置 | 必填 | 类型 / 约束 |
|---|---|---|---|
| identifier | path | 是 | integer |

### POST `/api/v1/reimbursements/{identifier}/submit`

功能：异步提交。参数：revision/Idempotency-Key。返回：202审核ID。异常：403所有权，409版本/活动任务，422无发票。

鉴权：Bearer；另校验角色/所有权/轮次，具体限制见功能说明。

| 参数 | 位置 | 必填 | 类型 / 约束 |
|---|---|---|---|
| identifier | path | 是 | integer |
| Idempotency-Key | header | 是 | string, minLength=8, maxLength=80 |

请求类型：`application/json`；请求契约：`Revision`，字段见下方Schema表。

### POST `/api/v1/reimbursements/{identifier}/withdraw`

功能：撤回待审单使旧任务失效。参数：ID/revision。返回：终态。异常：403非本人，409非待审核/过期版本。

鉴权：Bearer；另校验角色/所有权/轮次，具体限制见功能说明。

| 参数 | 位置 | 必填 | 类型 / 约束 |
|---|---|---|---|
| identifier | path | 是 | integer |

请求类型：`application/json`；请求契约：`Revision`，字段见下方Schema表。

### GET `/api/v1/audit`

功能：列出有权查看的历史审核。参数：状态/风险/决策/单据/分页。返回：审核分页。异常：401身份。

鉴权：Bearer；另校验角色/所有权/轮次，具体限制见功能说明。

| 参数 | 位置 | 必填 | 类型 / 约束 |
|---|---|---|---|
| page | query | 否 | integer, 默认 1, minimum=1 |
| page_size | query | 否 | integer, 默认 20, minimum=1, maximum=100 |
| status | query | 否 | string / null |
| risk_level | query | 否 | integer / null |
| decision | query | 否 | string / null |
| reimbursement_id | query | 否 | integer / null |

### GET `/api/v1/audit/{identifier}`

功能：完整证据与版本详情。参数：审核ID。返回：快照/节点/规则/反馈。异常：403无权，404不存在。

鉴权：Bearer；另校验角色/所有权/轮次，具体限制见功能说明。

| 参数 | 位置 | 必填 | 类型 / 约束 |
|---|---|---|---|
| identifier | path | 是 | integer |

### GET `/api/v1/audit/{identifier}/events`

功能：实时审核进度。参数：ID/Last-Event-ID。返回：SSE节点/完成/失败/心跳。异常：前置403/404；断线用详情恢复。

鉴权：Bearer；另校验角色/所有权/轮次，具体限制见功能说明。

| 参数 | 位置 | 必填 | 类型 / 约束 |
|---|---|---|---|
| identifier | path | 是 | integer |
| Last-Event-ID | header | 否 | string / null |

### POST `/api/v1/audit/{identifier}/rerun`

功能：授权重跑保留旧结果。参数：审核ID/理由/幂等键。返回：新审核ID。异常：403权限，409终态/在途审批。

鉴权：Bearer；另校验角色/所有权/轮次，具体限制见功能说明。

| 参数 | 位置 | 必填 | 类型 / 约束 |
|---|---|---|---|
| identifier | path | 是 | integer |
| Idempotency-Key | header | 是 | string, minLength=8, maxLength=80 |

请求类型：`application/json`；请求契约：`Rerun`，字段见下方Schema表。

### POST `/api/v1/audit/{identifier}/feedback`

功能：人工审批后独立反馈。参数：已处理审批ID/纠正/理由。返回：反馈及迭代建议。异常：403非签署人，409轮次不匹配。

鉴权：Bearer；另校验角色/所有权/轮次，具体限制见功能说明。

| 参数 | 位置 | 必填 | 类型 / 约束 |
|---|---|---|---|
| identifier | path | 是 | integer |

请求类型：`application/json`；请求契约：`Feedback`，字段见下方Schema表。

### GET `/api/v1/approvals/chains`

功能：查看链配置。参数：分页。返回：审批链列表。异常：403经理权限不足。

鉴权：Bearer；另校验角色/所有权/轮次，具体限制见功能说明。

| 参数 | 位置 | 必填 | 类型 / 约束 |
|---|---|---|---|
| page | query | 否 | integer, 默认 1, minimum=1 |
| page_size | query | 否 | integer, 默认 20, minimum=1, maximum=100 |

### POST `/api/v1/approvals/chains`

功能：创建匹配条件与顺序链。参数：route/范围/nodes。返回：链配置。异常：403权限，422非法人员或金额范围。

鉴权：Bearer；另校验角色/所有权/轮次，具体限制见功能说明。

请求类型：`application/json`；请求契约：`ChainBody`，字段见下方Schema表。

### PATCH `/api/v1/approvals/chains/{identifier}`

功能：更新下一轮链配置。参数：ID/expected_version/完整链。返回：新版本。异常：403、404、409版本、422非法链。

鉴权：Bearer；另校验角色/所有权/轮次，具体限制见功能说明。

| 参数 | 位置 | 必填 | 类型 / 约束 |
|---|---|---|---|
| identifier | path | 是 | integer |

请求类型：`application/json`；请求契约：`ChainBody`，字段见下方Schema表。

### GET `/api/v1/approvals`

功能：查看本人待办与授权历史。参数：pending/单据/分页。返回：记录与关联信息。异常：401身份。

鉴权：Bearer；另校验角色/所有权/轮次，具体限制见功能说明。

| 参数 | 位置 | 必填 | 类型 / 约束 |
|---|---|---|---|
| page | query | 否 | integer, 默认 1, minimum=1 |
| page_size | query | 否 | integer, 默认 20, minimum=1, maximum=100 |
| pending | query | 否 | boolean / null |
| reimbursement_id | query | 否 | integer / null |

### POST `/api/v1/approvals/{identifier}/decide`

功能：处理指定审批并原子推进下一棒。参数：ID/action/opinion。返回：记录/轮次/单据。异常：403自审/非指定人，409重签。

鉴权：Bearer；另校验角色/所有权/轮次，具体限制见功能说明。

| 参数 | 位置 | 必填 | 类型 / 约束 |
|---|---|---|---|
| identifier | path | 是 | integer |

请求类型：`application/json`；请求契约：`Decide`，字段见下方Schema表。

### POST `/api/v1/knowledge/documents/import`

功能：导入真实文本政策。参数：UTF-8 txt/md文件。返回：政策和索引状态。异常：403权限，422文件类型/大小/编码。

鉴权：Bearer；另校验角色/所有权/轮次，具体限制见功能说明。

请求类型：`multipart/form-data`；请求契约：`Body_import_document_api_v1_knowledge_documents_import_post`，字段见下方Schema表。

### GET `/api/v1/knowledge/documents`

功能：阅读政策与索引状态。参数：分页。返回：含正文政策列表。异常：401未登录。

鉴权：Bearer；另校验角色/所有权/轮次，具体限制见功能说明。

| 参数 | 位置 | 必填 | 类型 / 约束 |
|---|---|---|---|
| page | query | 否 | integer, 默认 1, minimum=1 |
| page_size | query | 否 | integer, 默认 20, minimum=1, maximum=100 |

### POST `/api/v1/knowledge/documents`

功能：保存用户制度原文并分块。参数：标题/分类/正文。返回：未索引文档。异常：403权限，422正文不合法。

鉴权：Bearer；另校验角色/所有权/轮次，具体限制见功能说明。

请求类型：`application/json`；请求契约：`KnowledgeBody`，字段见下方Schema表。

### PATCH `/api/v1/knowledge/documents/{identifier}`

功能：修订正文使旧向量失效。参数：ID/预期版本/正文。返回：新版本。异常：403权限，404不存在，409并发。

鉴权：Bearer；另校验角色/所有权/轮次，具体限制见功能说明。

| 参数 | 位置 | 必填 | 类型 / 约束 |
|---|---|---|---|
| identifier | path | 是 | integer |

请求类型：`application/json`；请求契约：`KnowledgeBody`，字段见下方Schema表。

### POST `/api/v1/knowledge/documents/{identifier}/reindex`

功能：排队真实向量化。参数：文档ID。返回：索引任务ID。异常：403权限，404不存在，409已有任务，503无模型。

鉴权：Bearer；另校验角色/所有权/轮次，具体限制见功能说明。

| 参数 | 位置 | 必填 | 类型 / 约束 |
|---|---|---|---|
| identifier | path | 是 | integer |

### POST `/api/v1/knowledge/search`

功能：显式关键词/语义试验。参数：query/mode/top_k/category。返回：模式及原文出处。异常：503真实向量不可用。

鉴权：Bearer；另校验角色/所有权/轮次，具体限制见功能说明。

请求类型：`application/json`；请求契约：`SearchBody`，字段见下方Schema表。

### GET `/api/v1/logs/export`

功能：导出授权日志。参数：与列表相同筛选。返回：UTF-8 BOM CSV。异常：403权限，422时间格式。

鉴权：Bearer；另校验角色/所有权/轮次，具体限制见功能说明。

| 参数 | 位置 | 必填 | 类型 / 约束 |
|---|---|---|---|
| action | query | 否 | string / null |
| trace | query | 否 | string / null |
| actor_id | query | 否 | integer / null |
| resource | query | 否 | string / null |
| since | query | 否 | string / null |
| until | query | 否 | string / null |

### GET `/api/v1/logs`

功能：按人/动作/资源/追踪查证。参数：筛选和分页。返回：只读日志。异常：403权限，422时间格式。

鉴权：Bearer；另校验角色/所有权/轮次，具体限制见功能说明。

| 参数 | 位置 | 必填 | 类型 / 约束 |
|---|---|---|---|
| page | query | 否 | integer, 默认 1, minimum=1 |
| page_size | query | 否 | integer, 默认 20, minimum=1, maximum=100 |
| action | query | 否 | string / null |
| trace | query | 否 | string / null |
| actor_id | query | 否 | integer / null |
| resource | query | 否 | string / null |
| since | query | 否 | string / null |
| until | query | 否 | string / null |

### GET `/api/v1/alerts`

功能：查询授权告警。参数：状态/严重度/类型/分页。返回：持久告警。异常：403权限不足。

鉴权：Bearer；另校验角色/所有权/轮次，具体限制见功能说明。

| 参数 | 位置 | 必填 | 类型 / 约束 |
|---|---|---|---|
| page | query | 否 | integer, 默认 1, minimum=1 |
| page_size | query | 否 | integer, 默认 20, minimum=1, maximum=100 |
| status | query | 否 | string / null |
| severity | query | 否 | string / null |
| type | query | 否 | string / null |

### POST `/api/v1/alerts/{identifier}/acknowledge`

功能：确认异常负责人。参数：ID/意见。返回：已确认告警。异常：403范围，404不存在，409已处理。

鉴权：Bearer；另校验角色/所有权/轮次，具体限制见功能说明。

| 参数 | 位置 | 必填 | 类型 / 约束 |
|---|---|---|---|
| identifier | path | 是 | integer |

请求类型：`application/json`；请求契约：`Opinion`，字段见下方Schema表。

### POST `/api/v1/alerts/{identifier}/resolve`

功能：记录告警处理完成。参数：ID/意见。返回：已解决告警，原风险不变。异常：403范围，409未确认。

鉴权：Bearer；另校验角色/所有权/轮次，具体限制见功能说明。

| 参数 | 位置 | 必填 | 类型 / 约束 |
|---|---|---|---|
| identifier | path | 是 | integer |

请求类型：`application/json`；请求契约：`Opinion`，字段见下方Schema表。

### GET `/api/v1/stats/overview`

功能：实时授权统计。参数：时间/部门。返回：数量、金额、状态、风险、部门。异常：401身份，422时间。

鉴权：Bearer；另校验角色/所有权/轮次，具体限制见功能说明。

| 参数 | 位置 | 必填 | 类型 / 约束 |
|---|---|---|---|
| since | query | 否 | string / null |
| until | query | 否 | string / null |
| department_id | query | 否 | integer / null |

### GET `/api/v1/stats/export`

功能：导出授权财务明细。参数：format/时间/部门。返回：Excel或中文PDF。异常：403权限，422格式，503字体问题。

鉴权：Bearer；另校验角色/所有权/轮次，具体限制见功能说明。

| 参数 | 位置 | 必填 | 类型 / 约束 |
|---|---|---|---|
| format | query | 否 | string, 默认 "xlsx", pattern=^(xlsx\|pdf)$ |
| since | query | 否 | string / null |
| until | query | 否 | string / null |
| department_id | query | 否 | integer / null |

### GET `/api/v1/health`

功能：报告实际数据库和消费者状态。参数：无。返回：组件状态，无凭据。异常：503数据库不可用。

鉴权：无需访问令牌。

## 全部请求 Schema

请求对象默认拒绝额外字段；可选未知值不以默认金额或日期补齐。

### Body_import_document_api_v1_knowledge_documents_import_post

| 字段 | 必填 | 含义 / 类型 / 约束 |
|---|---|---|
| file | 是 | File；string |

### Body_upload_invoices_api_v1_reimbursements__identifier__invoices_post

| 字段 | 必填 | 含义 / 类型 / 约束 |
|---|---|---|
| revision | 是 | Revision；integer |
| metadata | 否 | Metadata；string, 默认 "[]" |
| files | 是 | Files；array[string] |

### ChainBody

| 字段 | 必填 | 含义 / 类型 / 约束 |
|---|---|---|
| name | 是 | 审批链显示名；string, minLength=1, maxLength=100 |
| route | 是 | 对应确定性审核路由；系统批准不配置人工链；string: ["to_supervisor", "to_finance", "to_manual"] |
| type | 否 | 适用报销类型，空表示全部；integer: [1, 2, 3] / null |
| department_id | 否 | 匹配历史单据所属有效部门，空表示全部；integer, exclusiveMinimum=0.0 / null |
| amount_min | 否 | 含税金额下限，空不限制；number / string, pattern=^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$ / null |
| amount_max | 否 | 含税金额上限，必须大于等于下限；number / string, pattern=^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$ / null |
| priority | 否 | 同具体度链的选择优先级，越大越优先；integer, 默认 0, minimum=0.0, maximum=100.0 |
| nodes | 是 | 有序且非空审批链；array, minItems=1, maxItems=10[ChainNode] |
| active | 否 | 仅影响新轮次，已有冻结链不替换；boolean, 默认 true |
| expected_version | 否 | 更新时必填；integer, exclusiveMinimum=0.0 / null |

### ChainNode

| 字段 | 必填 | 含义 / 类型 / 约束 |
|---|---|---|
| approver_id | 是 | 实际有效用户，而非角色占位符；integer, exclusiveMinimum=0.0 |
| role | 是 | 必须与指定人员当前真实身份一致；string: ["supervisor", "auditor", "manager", "admin"] |

### ConfigPatch

| 字段 | 必填 | 含义 / 类型 / 约束 |
|---|---|---|
| expected_version | 是 | 乐观并发版本，不覆盖他人的修改；integer, exclusiveMinimum=0.0 |
| enabled | 否 | 可选能力开关，核心规则和决策不能停用；boolean / null |
| config | 否 | 节点白名单参数，禁止密钥或代码；object / null |

### Decide

| 字段 | 必填 | 含义 / 类型 / 约束 |
|---|---|---|
| action | 是 | 通过、驳回或退回草稿，不接受任意状态；string: ["approve", "reject", "return"] |
| opinion | 是 | 所有审批动作必须留可读意见；string, minLength=2, maxLength=2000 |

### DepartmentBody

| 字段 | 必填 | 含义 / 类型 / 约束 |
|---|---|---|
| name | 是 | 不重复的部门名称；string, minLength=1, maxLength=100 |
| active | 否 | 停用仅影响新业务；boolean, 默认 true |

### Feedback

| 字段 | 必填 | 含义 / 类型 / 约束 |
|---|---|---|
| approval_record_id | 是 | 本人已处理审批记录；integer, exclusiveMinimum=0.0 |
| corrected_fields | 否 | 纠正建议，不覆盖原证据；object |
| reason | 是 | 判断依据；string, minLength=2, maxLength=2000 |

### InvoicePatch

| 字段 | 必填 | 含义 / 类型 / 约束 |
|---|---|---|
| revision | 是 | 所属单据当前版本；integer, exclusiveMinimum=0.0 |
| fields | 是 | 用户填报字段；缺失为未知，不伪造默认金额；object |

### KnowledgeBody

| 字段 | 必填 | 含义 / 类型 / 约束 |
|---|---|---|
| title | 是 | 政策原文标题，用作引用出处；string, minLength=1, maxLength=200 |
| category | 否 | policy分类参与正式政策审核；string, 默认 "policy", pattern=^[a-zA-Z0-9_-]{1,40}$ |
| content | 是 | 用户提供的政策原文；string, minLength=1, maxLength=200000 |
| active | 否 | 停用原文不参与新审核检索；boolean, 默认 true |
| expected_version | 否 | 修订时必须等于当前正文版本；integer, exclusiveMinimum=0.0 / null |

### Login

| 字段 | 必填 | 含义 / 类型 / 约束 |
|---|---|---|
| username | 是 | 已初始化登录名；string, minLength=1, maxLength=50 |
| password | 是 | 仅传输用于校验，不写入日志；string, minLength=1, maxLength=200 |

### Opinion

| 字段 | 必填 | 含义 / 类型 / 约束 |
|---|---|---|
| opinion | 是 | 处理意见，不得仅置状态无依据；string, minLength=2, maxLength=2000 |

### Refresh

| 字段 | 必填 | 含义 / 类型 / 约束 |
|---|---|---|
| refresh_token | 是 | 轮换或撤销的刷新凭据；string, minLength=20, maxLength=500 |

### ReimbursementCreate

| 字段 | 必填 | 含义 / 类型 / 约束 |
|---|---|---|
| title | 是 | 报销目的；string, minLength=1, maxLength=200 |
| description | 否 | 业务补充说明；string, 默认 "", maxLength=5000 |
| type | 否 | 1差旅/2招待/3办公；integer: [1, 2, 3], 默认 1 |
| total_amount | 是 | 含税总额，以两位小数传输；number / string, pattern=^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$ |

### ReimbursementPatch

| 字段 | 必填 | 含义 / 类型 / 约束 |
|---|---|---|
| revision | 是 | 必须等于当前可编辑版本；integer, exclusiveMinimum=0.0 |
| title | 否 | 修改业务目的，不能空字符串；string, minLength=1, maxLength=200 / null |
| description | 否 | 修订补充说明；string, maxLength=5000 / null |
| type | 否 | 修改1差旅/2招待/3办公类型，影响下一轮匹配；integer: [1, 2, 3] / null |
| total_amount | 否 | 修订含税额，服务层校验非负及两位精度；number / string, pattern=^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$ / null |

### Rerun

| 字段 | 必填 | 含义 / 类型 / 约束 |
|---|---|---|
| reason | 是 | 重跑理由记录在审计日志；string, minLength=2, maxLength=1000 |

### Revision

| 字段 | 必填 | 含义 / 类型 / 约束 |
|---|---|---|
| revision | 是 | 预期单据版本，过期返回409；integer, exclusiveMinimum=0.0 |

### RulePatch

| 字段 | 必填 | 含义 / 类型 / 约束 |
|---|---|---|
| expected_version | 是 | 当前规则版本；integer, exclusiveMinimum=0.0 |
| enabled | 否 | 可选规则生效开关，核心检查不允许关闭；boolean / null |
| severity | 否 | 命中时的处理级别，核心严重程度有下限；string: ["warning", "error", "critical"] / null |
| params | 否 | 白名单阈值，不接受表达式；object / null |
| scope | 否 | 可选规则的部门/类型范围；object / null |

### RuleTest

| 字段 | 必填 | 含义 / 类型 / 约束 |
|---|---|---|
| invoice | 是 | 待试算字段，不写正式审核；object |
| context | 否 | 显式试算上下文，不冒充生产历史；object |

### SearchBody

| 字段 | 必填 | 含义 / 类型 / 约束 |
|---|---|---|
| query | 是 | 实际检索问题，不用作系统指令；string, minLength=1, maxLength=2000 |
| mode | 否 | 显式本地词项或真实向量语义模式；string: ["keyword", "semantic"], 默认 "keyword" |
| top_k | 否 | 最多返回的真实片段数量；integer, 默认 5, minimum=1.0, maximum=20.0 |
| category | 否 | 可选分类过滤；string, maxLength=40 / null |

### UserCreate

| 字段 | 必填 | 含义 / 类型 / 约束 |
|---|---|---|
| username | 是 | 唯一登录名；string, pattern=^[A-Za-z][A-Za-z0-9_]{2,49}$ |
| real_name | 是 | 真实显示名称；string, minLength=1, maxLength=80 |
| password | 是 | 至少大小写、数字和符号；string, minLength=10, maxLength=200 |
| department_id | 是 | 有效部门主键；integer, exclusiveMinimum=0.0 |
| role | 是 | 五种固定业务身份，不接受任意角色名；string: ["employee", "supervisor", "auditor", "manager", "admin"] |

### UserPatch

| 字段 | 必填 | 含义 / 类型 / 约束 |
|---|---|---|
| real_name | 否 | 新显示名称；string, minLength=1, maxLength=80 / null |
| department_id | 否 | 新部门，历史单据部门不变；integer, exclusiveMinimum=0.0 / null |
| role | 否 | 管理员授权的固定身份；禁止降级自己；string: ["employee", "supervisor", "auditor", "manager", "admin"] / null |
| active | 否 | 停用后立即拒绝现有访问令牌；boolean / null |

## SSE与幂等/版本示例

上传：POST `/api/v1/reimbursements/1/invoices`，multipart字段 `files` 可以重复多次、`revision`为当前单据版本、`metadata`可选JSON数组并与文件一一对应。每个文件在事务提交后发 progress，部分失败发error并保留已提交ID。真实例帧格式如下（示例数字不是实际运行结果）：

```text
event: progress
data: {"current":1,"total":2,"filename":"invoice.png","invoice_id":1,"revision":2}

event: completed
data: {"reimbursement_id":1,"uploaded_ids":[1,2],"revision":3}

event: error
data: {"code":"FILE_TYPE","message":"只接受真实 PNG、JPEG 和 PDF 文件","uploaded_ids":[1],"revision":2}
```

审核：GET `/api/v1/audit/1/events`，可传 `Last-Event-ID` 为最后已处理节点记录ID；事件 started、node、completed/failed，另有注释心跳。node data是完整节点记录。页面关闭时取消流；断线查询 `/audit/1` 可恢复持久进度，不能把断线当审核失败。

提交 POST `/reimbursements/1/submit` 请求 `{"revision":3}`，必须头 `Idempotency-Key` 长8–80字符；同一次请求重送复用键。返回审核ID后重新提交的新轮次使用新键。PATCH单据/发票以及撤回传revision；PATCH Agent、规则、审批链和政策传expected_version。冲突409后刷新，不自动覆盖。

## AI服务协议

1. VLM/LLM：配置根URL追加 `/chat/completions`，OpenAI兼容messages、temperature、response_format.json_schema；视觉消息的 image_url是受控图片data URL，PDF先逐页转图。响应 `choices[0].message.content` 要通过提取/风险/政策Schema校验。模型测试 GET `/models` 仅查询服务列表，不代表实际识别效果。
2. Embedding：POST根URL `/embeddings`，自定义请求 `{"texts":["真实原文"]}`，响应vectors数组。协议失败可调用LLM服务相同模型的OpenAI embeddings请求，数量及维度必须一致，有限数值且非零；不造向量。真实政策索引才允许语义检索。
3. Rerank：POST根URL `/rerank`，请求query/documents，响应results中的index/relevance_score必须覆盖所有候选且得分有限；失败保留原顺序并标记降级。
4. 服务凭据使用后端 AI_API_KEY。HTTP层没有自动重试，图级提取掌握尝试预算；熔断半开仅一个探测；缓存键包含模型、服务地址、参数与输入，失败不缓存。

外部模型服务未由用户提供，协议和错误分支以合约替身验证，不能据此宣称真实模型效果已验收。