01通用约定

接口命名规范

URI 采用增强 RESTful 形式：URL 前缀做安全认证区分，版本号做 API 版本控制（统一放入 URL，如 /v{n}/——整数版本号对应大功能发布 v1 / v2，浮点版本号只补充 API，如 v1.1 / v1.2）。

前缀作用示例
open互联网公开接口，无需认证/open/v1.2/user/接口方法名
auth互联网认证接口，需要认证/auth/v1.2/user/接口方法名
lan局域网内部接口，仅局域网内调用/lan/v1.2/user/接口方法名
self局域网私有接口，仅私有领域服务调用/self/v1.2/user/接口方法名
paas平台业务接口，为外部业务提供集成对接/paas/v1.2/user/接口方法名
paasCallback平台回调接口，由外部服务实现、平台回调/paasCallback/v1.2/user/接口方法名

URL 方法名前缀与 Java 方法命名一致（get/list/page/count/insert/delete/update，动作类无前缀）；HTTP 方法映射：POST=增、DELETE=删、PUT=改、GET=查、POST=动作。

基本信息
接口前缀/open/v1/（公开接口）——接入认证体系后升级 /auth/v1/，前缀即安全等级，网关按前缀统一管控，接口路径零改动
请求格式Content-Type: application/json（文件流端点除外）
响应格式统一包装 JSON（流式接口为 SSE 逐块透传）
鉴权分级终端用户通道免验（IP 限流保护）；查看 / 操作类接口凭查看密钥白名单；截图文件流凭 HMAC 签名 URL（30 分钟限时）
链路追踪全部同步响应携带 traceId——用户报障凭一个 traceId 回查全链路日志
统一响应结构
{
  "code": 200,                    // HTTP 状态码语义（同步接口）
  "msg": "成功",                 // 可直接展示的提示
  "flag": true,                  // 成功判定：失败为 false（code=600 业务异常）
  "traceId": "a1bde0ba625de731",   // 链路追踪码——报障回查的唯一凭据
  "data": { ... }                 // 业务数据
}
字段类型说明
codeintHTTP 状态码语义（同步接口）
msgString响应提示；flag=false 时为用户友好提示（如「该反馈已被 张三 认领」）
flagboolean成功判定，前端以本字段做成功 / 失败分支
traceIdString链路追踪码
dataObject业务数据
公共错误码
业务码HTTP语义
YAOSHU_CODE_UNAVAILABLE503核心服务不可用
LLM_PROXY_ERROR502模型调用失败（上游语义已归一）
INTERNAL_ERROR500服务器内部错误
错误处理的两条设计线：对外「用户能看懂」（msg 为用户友好提示），对内「工程师能定位」（上游错误归一化后原文进日志不进响应——既不泄露上游细节，又保留了排障线索）。
业务错误提示约定

参数与业务规则类拒绝不走异常堆栈，直接以 flag=false + msg 返回，提示语面向用户可读。反馈模块的典型提示（节选）：

提示触发场景
反馈材料超过1MB限制 / 会话转写超过15MB限制提交材料超出容量边界（源头拒绝，不落库）
截图附件不能超过9张 / 单张截图不能超过500KB（压缩后）截图附件越限
缺少查看权限：未携带访问密钥 / 缺少查看权限：密钥无效白名单拒绝（fail-closed：未配置密钥时同样拒绝）
该反馈已被 {claimedBy} 认领 / 任务不存在状态机冲突（冲突明细见 03 节认领端点）
反馈提交过于频繁IP 限流触发

02接口清单

四个对外模块共 12 个端点。鉴权三档：免验 · IP 限流 终端用户通道、查看密钥 团队操作通道、签名 URL 限时文件流。

模块方法路径说明鉴权
系统GET/open/v1/system/health健康检查免验 · IP 限流
版本更新GET/open/v1/app/update/manifest版本更新清单免验 · IP 限流
模型代理POST/open/v1/llm/chat/completions对话补全（OpenAI 兼容 · SSE 流式）免验 · IP 限流
反馈与认领工单POST/open/v1/diagnostic/task/insert提交反馈（落库入池 + 异步自动分类）免验 · IP 限流
POST/open/v1/diagnostic/task/claim认领（条件更新防抢）查看密钥
POST/open/v1/diagnostic/task/release释放回池（仅认领人）查看密钥
POST/open/v1/diagnostic/task/resolve标记完成（仅认领人）查看密钥
POST/open/v1/diagnostic/task/discard删除（仅待认领态，附件级联清理）查看密钥
GET/open/v1/diagnostic/task/list任务列表（按状态过滤）查看密钥
GET/open/v1/diagnostic/task/get任务详情（材料全文 + 签名图片地址）查看密钥
GET/open/v1/diagnostic/task/mine我的反馈回执（按设备标识）免验 · IP 限流
GET/open/v1/diagnostic/task/image截图附件文件流签名 URL
任务状态机四态：pending_claim 待认领 → claimed 已认领 → resolved 已解决；claimed 可释放回 pending_claim，pending_claim 可删除为 discarded（终态留档）。全部流转由服务端按状态机裁决，非法流转直接拒绝。

03端点详述

关键端点的请求 / 响应与错误语义（其余端点按 02 节清单语义直连）：

GET/open/v1/system/health健康检查

验证后端工程启动成功——部署后第一个探活的端点。

响应示例（真实执行结果）
{
  "code": 200,
  "msg": "成功",
  "flag": true,
  "traceId": null,
  "data": "爻枢 Code 后端运行中"
}
GET/open/v1/app/update/manifest版本更新清单

客户端启动时拉取版本更新清单（最新版本号、下载地址、更新策略）。更新策略支持外部配置覆盖、坏配置自动回退内置默认——策略文件解析失败的兜底行为有专门测试覆盖。

POST/open/v1/llm/chat/completions对话补全（OpenAI 兼容 · SSE 流式）

OpenAI 兼容的流式对话端点：请求在服务端完成规则与角色注入后转发上游模型，响应 SSE 逐块透传——调用方零改造接入。请求体为标准 OpenAI Chat Completions 格式；请求体含多模态内容而模型未显式声明多模态时返回 400。

错误响应语义（OpenAI 兼容）
{
  "error": { "message": "…用户可读提示…", "type": "invalid_request_error | proxy_error" }
}
// invalid_request_error → 不可重试（请求/配置类问题，重试无意义）
// proxy_error          → 可重试（上游瞬时故障，退避自愈）

上游 2xx 响应的限流响应头（x-ratelimit-limit/remaining/reset）白名单透传，供调用方做精确退避。

POST/open/v1/diagnostic/task/insert提交反馈

提交反馈，落库即入待认领池（pending_claim），异步触发自动分类（分类失败仅降级为未分类，提交本身不受影响）。

请求体
{
  "sourceSessionId": "session-uuid",          // 源会话 ID（全局入口不传）
  "sourceSessionMessages": [               // 必填：反馈材料，JSON 数组 ≤1MB
    { "role": "user", "content": "点击导出按钮没有反应" }
  ],
  "sourceSessionTranscript": "…全量转写（可选，≤15MB）…",
  "feedbackImages": [                       // 截图附件 ≤9 张，单张解码后 ≤500KB
    { "name": "截图1.png", "data": "data:image/png;base64,iVBORw0KGgo..." }
  ],
  "feedbackType": "defect",                 // defect / requirement，不传由自动分类判定
  "note": "可选补充说明",
  "reporterId": "device-uuid",              // 设备标识，mine 回执查询凭据
  "channel": "user_feedback"                // user_feedback / tool_defect / performance / global_feedback
}
响应（任务摘要，结构同 list 条目）
{
  "code": 200, "msg": "成功", "flag": true, "traceId": "...",
  "data": {
    "taskId": "fb-a1b2c3d4",
    "status": "pending_claim",
    "feedbackType": null,          // 分类异步补全中
    "classifySummary": null,
    "claimedBy": null, "claimedTime": null, "resolveNote": null,
    "createdAt": 1723420800000, "updatedAt": 1723420800000
  }
}
容量与形态在入口即校验：材料必须为 JSON 数组、转写 UTF-8 ≤15MB、截图 ≤9 张且单张 ≤500KB、仅支持 JPEG/PNG——越限直接业务错误拒绝，不落库。
POST/open/v1/diagnostic/task/claim认领（条件更新防抢）

认领走条件更新（WHERE status='pending_claim'），并发多人同抢时恰好一个成功、其余按实际状态收到明确提示。请求体：{ "taskId", "claimer", "feedbackType"(可选，认领时人工补选类型，人工判断优先于自动分类) }。

冲突分支（affected=0 时回读任务按实际状态返回）
{
  "code": 600, "flag": false,
  "msg": "该反馈已被 张三 认领"      // 其余分支：已解决 / 已删除 / 状态刚变化请刷新 / 任务不存在
}
GET/open/v1/diagnostic/task/get任务详情

查询参数 taskId。返回材料全文、分类产出、认领信息与截图地址——imageUrls 为 HMAC 签名的绝对 URL（默认 30 分钟过期），可直接作为 <img src> 使用（无需鉴权头），过期后重调 get 刷新。已删除任务的图片清单已清空。

GET/open/v1/diagnostic/task/mine我的反馈回执

查询参数 reporterId（必填，与提交时一致）。按创建时间倒序最多 100 条，返回状态摘要与本人自述 / 处理回执（note / resolveNote）——查询列即收敛：不含材料全文、联系方式与工作目录。

GET/open/v1/diagnostic/task/image截图附件文件流

get 返回的 imageUrls 即指向本端点。签名 URL 即限时凭证（img 标签无法携带鉴权头）。

查询参数
taskId   形态 fb-[0-9a-f]{8}     // 非白名单形态直接拒绝（路径穿越免疫）
file     形态 [0-9a-f]{32}.(jpg|png)  // 服务端落盘重命名产物
expires  过期时刻（毫秒时间戳）
sig      HMAC-SHA256(taskId|file|expires) 十六进制小写

业务错误：链接过期 → 刷新详情重试；签名不符 / 形态非法 → 拒绝；文件缺失 → 不存在或已被清理。

04契约演进记录

「反馈与认领工单」一次重构迭代的端点变更账目——契约即设计文档、控制器即实现、测试即验证，三者同轮更新，漂移在提交时被拦住：

变更数量明细
新增6认领 / 释放 / 完成 / 删除 / 回执（mine）/ 截图文件流（image）
改造3提交（insert）/ 列表（list）/ 详情（get）——对齐四态状态机与分类字段
下线4旧接口直接移除、不留兼容层（/retry / /cancel / /report / /getStatus），前端同步适配
维护纪律：新增 / 变更接口必须同轮更新本契约与测试，下线接口不留兼容层——契约与实现不允许出现「文档说有、代码没有」的窗口。