code/ai_finance_agent/docs/接口文档.md

接口文档

最终代码生成：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_reimbursementsidentifierinvoices_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。真实例帧格式如下（示例数字不是实际运行结果）：

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层没有自动重试，图级提取掌握尝试预算；熔断半开仅一个探测；缓存键包含模型、服务地址、参数与输入，失败不缓存。

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