# 接口契约与运行交付 适用版本:D1–D4;更新时间 2026-10-28(北京时间)。实际本地结果见 [D4 实施与验收](D4实施与验收.md)。 ## 1. 测试环境启动 后端 Java 21、Maven 3.9+、MySQL 8;前端使用带锁文件的 npm 安装。本轮验证 Node 23.11.1 / npm 10.9.2,部署可使用满足 Vite 引擎约束的团队 Node 版本。 1. 新建空的 `rz_gb` MySQL 数据库,字符集 utf8mb4。账号需具备本库迁移与业务读写权限;不要复用其他项目数据库。Flyway 首次自动执行 V1–V7,升级环境只执行未运行的版本。 2. 数据库和 `rz.admin-password` 直接配置在 `src/main/resources/application.yaml`,构建后随 JAR 加载,不再自动读取根目录的 `application-local.yaml`。切换部署环境前核对数据库地址和账号,修改后重新打包。初始密码不限制最小长度,但不能为空,UTF-8 不超过 BCrypt 的 72 字节上限。既有 admin 不会因重启被重置。 3. 除 `ZLBX_API_KEY`、`DEEPSEEK_API_KEY` 外,参数均直接在 YAML 中维护。API Key 在启动终端或 IDE 环境变量中设置。从后端根目录运行,无需加载 `.env`: ```sh export JAVA_HOME=$(/usr/libexec/java_home -v 21) mvn spring-boot:run ``` 默认后端端口 8240;`GET /actuator/health` 检查就绪。主机默认 Java 8 时必须先指定 Java 21。本轮用已安装 Maven;Wrapper 的独立 Maven 发行包需要可下载且可写缓存。 ```sh cd ../rz-GB-web npm ci npm run dev ``` 前端默认 3000,通过同源 `/api` 代理到 8240。开发时可用 `API_PROXY_TARGET=http://127.0.0.1:8244 npm run dev -- --port 3004` 指向独立本地后端;此变量仅被 Vite 服务端读取,不是浏览器密钥配置。 真实供应商未配置时,任务等待配置或输入,不返回演示数据。不向前端 `VITE_*` 放 API Key。 ## 2. 构建、初始化与代理 ```sh # 后端目录 export JAVA_HOME=$(/usr/libexec/java_home -v 21) mvn -Djava.awt.headless=true verify java -Djava.awt.headless=true -jar target/rz-GB-0.0.1-SNAPSHOT.jar # 前端目录 npm ci npm run build ``` 后端运行 JAR 时,直接使用包内的数据库和管理员初始化配置,并通过进程环境提供两个 API Key。主 YAML 和 JAR 均包含凭证,应限制访问;生产 JAR 不包含 H2、测试口令或模拟服务。若需覆盖包内配置,可填写 `application-local.example.yaml` 并通过 `--spring.config.additional-location=file:/绝对路径/application-local.yaml` 显式加载。前端交付目录是 `dist/`,部署到静态服务,路由回退到 `index.html`;不能用旧 HTML 原型代替后端。 通过同一域名提供前端和 `/api`,HTTPS 下将主 YAML 的 `server.servlet.session.cookie.secure` 改为 `true`。反向代理需关闭 SSE 响应缓冲并允许长连接,例如: ```nginx location /api/ { proxy_pass http://127.0.0.1:8240; proxy_http_version 1.1; proxy_set_header Host $host; proxy_set_header X-Forwarded-Proto $scheme; proxy_buffering off; proxy_read_timeout 180s; } ``` 本期任务执行和会话是单实例;重启需重新登录。数据库中的任务、会话、文件和业务数据保留。重启恢复只标记中断,不重发收费请求;不要把多个实例同时连到同库当作已支持的并行调度。 ## 3. 通用请求契约 - 前缀 `/api`。除登录与 CSRF 引导外均需真实会话;Cookie 为 HttpOnly。所有改变状态的请求必须带 `/auth/csrf` 返回的 headerName/token;登录后 CSRF 轮换,客户端重新读取。 - 任务创建、继续、方案执行、关注变更使用 `Idempotency-Key`。8–128 位,允许字母、数字及 `._:-`。相同作用域同键同内容回查;同键不同内容 409。创建键按账号隔离;继续键按任务隔离;客户端不自动重试写请求。 - 通用错误 JSON:`{"code":"稳定错误码","message":"脱敏中文说明"}`。401 重新登录;403 刷新 CSRF 后由用户重试;409 刷新版本/检查范围;413 拆分;429 稍后显式重试;502/503/504 查看已有结果与未知费用。原始 SQL、请求密钥和私有模型推理不会返回浏览器。 - 检索日期为北京时间自然日的 `YYYY-MM-DD`,首尾包含;持久化创建时间 API 返回时间戳/ISO 时间,前端按北京时间展示。检索条件不得偷偷替换成当前日期。 - 浏览器金额字段统一为万元(`*Wan`),上游元/万元适配在后端集中转换。未知金额保持 null;负数、上下限倒置及非法权重拒绝。 - 原检索按发布时间排序;获客偏好只改顺序。返回平台总命中/已读/去重/展示/停止原因,均不等于全库保证。 ## 4. 现有业务接口 | 模块 | 接口及关键行为 | | --- | --- | | 登录 | GET `/auth/csrf`,POST `/auth/login`(表单 username/password),GET `/auth/me`,POST `/auth/logout` | | 公司档案 | GET/PUT `/company-profile`;版本检查、八组表单、四维权重;没有档案导入接口 | | 检索 | POST/GET `/searches`,GET `/searches/{id}`、`/{id}/items?page=1&size=20`;size 1–50,只读固定快照 | | 继续/偏好 | POST `/searches/{id}/continue` 继续未成功页,POST `/{id}/view` 只重排原候选,普通检索拒绝偏好改序 | | 方案 | GET/POST `/search-schemes`,PUT/DELETE `/{id}`,POST/GET `/{id}/runs`;编辑需版本,手动执行锁定条件及方案版本 | | 公告 | GET `/projects/{id}`,只允许当前账号曾取得或关注的公告 | | 关注 | GET `/watch`,POST/DELETE `/watch/{projectId}`,POST `/watch/{projectId}/changes`,GET `/watch/{projectId}/history` | | 标签 | GET/POST `/tags`,DELETE `/tags/{id}`,PUT `/watch/{projectId}/tags`;按账号隔离、版本和幂等事务 | | 任务 | POST/GET `/agent/tasks`,GET `/{id}` 或 `/{id}/report`,POST `/{id}/continue`、`/{id}/cancel` | | 文件 | POST `/files`(multipart purpose=BID_PROJECT、file),GET/DELETE `/files/{id}`;只读本人文件、首次绑定不可转移 | | 用量 | GET `/usage` 汇总本地账本;GET `/system/limits` 读取保护值;均不主动调用外部余额接口 | 各业务完整请求例子沿用 [D1](D1实施与验收.md)、[D2](D2实施与验收.md)、[D3](D3实施与验收.md)。旧 `/projects/import` 是计划草案,当前项目研判入口通过任务标题/URL/文件输入实现,没有单独的手动公告导入接口。 ### 事件和恢复 `GET /agent/tasks/{id}/events?after=0` 返回 SSE;`Last-Event-ID` 优先于 after。游标必须为非负整数,ID 全局递增,同任务按 ID 有序;事件不是连续自然数。`event-history?after=...` 每次最多读 100 条,按最后 ID 继续。 SSE 发送 `task-event`(id/type/payload)及 `idle`(终态/等待);终态刚好与读取并发时继续追完最后事件。浏览器只展示已保存的动作,不公开私有推理。重连、GET 报告和历史均不创建任务。 状态包括 RECEIVED、PLANNING、RUNNING、WAITING_INPUT、WAITING_ENTITY、WAITING_BUDGET、SUCCEEDED、PARTIAL、FAILED、CANCELLED。只有 WAITING_* 可继续。已定位的公司、文件、项目、模式、父任务和范围不可变;问答问题也不可换。失败/重启中断需核对账单后显式新建,不自动恢复收费动作。 ### 历史会话与问答 | 接口 | 请求/响应重点 | | --- | --- | | POST `/conversations` | `{"title":""}` 新建;空标题由首个问题自动生成 | | GET `/conversations?q=&offset=0` | 按标题/用户问题字面搜索,每次最多 50 条,offset 继续;不解释 `%`、`_` 为通配符 | | GET `/conversations/{id}` | 标题、version、创建/更新时间 | | PATCH `/conversations/{id}` | `{"title":"新标题","version":2}`;冲突返回 409 | | DELETE `/conversations/{id}` | 清除目录与消息;保留独立报告/费用/原件,响应说明范围 | | GET `/conversations/{id}/messages` | 用户问题和 task_id;助手内容保存在独立任务报告,不复制成第二份可漂移答案 | | POST `/conversations/{id}/tasks` | `{"taskId":"已有本人任务ID"}`,只关联已有任务,不收费;重复关联同会话无副作用 | | POST `/conversations/{id}/messages` | 问题及 scope,带 Idempotency-Key;原子写消息、标题、任务后才调度模型 | ```json { "question": "这批项目哪些信息尚未披露?", "scope": { "batchId": "检索任务ID", "projectId": null } } ``` 整批只填 batchId;单项目可以同时填 batchId/projectId,或只填 projectId 使用本人最近取得该项目的快照。所有范围均在服务端鉴权。执行中的检索拒绝冻结,需等待完成或暂停;无候选、跨账号或无证据拒绝并提供下一步。 问答任务 operation=`SNAPSHOT_QA`,workflow=`TENDER_SEARCH`,保留该工作流版本来源,**不代表重新调用了 tender-search**。调用账本明确为一次 DeepSeek 模型请求;请求只使用已读数据,零知了深查。模型选择由后端配置,客户端不能指定工具地址或系统提示词。 单次问答正文摘录 1000 字/公告、全部上下文 600,000 字符;长期文件证据摘录 2000 字/段。超过上下文限制拒绝,不只分析当前页。模型回答校验并不证明来源事实真实,也不保证自然语言语义完全正确,需根据原始来源人工复核。 ## 5. 三个 Skill 版本与实际工具映射 | 工作流 | 锁定版本 / X-Client | 实际白名单工具 | | --- | --- | --- | | tender-search | 2.3.0 / zlbx-bidding/2.3.0 | search_bids、query_bids_advanced;区域聚合 get_top_purchasers、get_top_suppliers、aggregate_bids_advanced | | company-intel | 1.0.2 / company-intel/1.0.2 | search_company、get_company_profile、get_company_business_keywords、get_company_partners、query_bids_advanced、aggregate_bids_advanced、find_competitors | | bid-decision | 1.0.4 / bid-decision/1.0.4 | search_bids、get_bid_detail、search_company、get_company_profile、get_company_partners、find_potential_bidders、get_price_trends、query_bids_advanced | 公开资料由后端固定的 DeepSeek Search/Fetch 端点补充;模型、视觉与问答共用后端模型配置。版本代表已锁定的本地编排映射,不是三个外部 Skill 服务。只在实际 HTTP 开始时记外部调用;LOCAL / ENTITY_CACHE、FILE_PARSE 单列,不记外部扣费。 本轮未取得真实供应商字段差异与计费合同,仍按现有适配契约使用 data.items、企业/聚合字段、meta.cost_units、模型 usage。真实响应不符合时失败并报告契约错误,不能把测试样例当实测差异记录。实际模型 ID 从响应保存,配置名不冒充实际模型标识。 预算默认外部调用最多 25、知了积分 100;单企业最多 18。未知费用不得视为零,后续暂停确认;未知单价首个请求可能超过保护值。DeepSeek token 与知了积分不相加。默认文件 24 小时到期,每分钟清理;审计保留策略的自动归档/删除尚未实现,不会自动清除收费证据。 ## 6. 真实验收接续 提供专用测试数据库与供应商凭证、余额和代表性真实标书后,按四天计划 6.2 逐步演示。先少量验证余额、检索、详情、文本、JSON、真实流、Search/Fetch 和视觉,再跑完整企业/项目路径;记录脱敏请求/响应状态、实际模型、调用 ID、日期范围、来源、积分和 token。 在这些证据齐备前,[D4 验收账](D4实施与验收.md)中的“真实未验证”保留原状态。当前不包含生产部署、生产多实例验证或全量复杂标书识别承诺。