# D1 实施与验收记录 日期:2026-10-26(Asia/Shanghai)。本次按用户要求先完成代码,数据库和 API Key 随后补充。**D1 代码实现不等于真实服务验收通过。** ## 已实现范围 - 三组 Flyway 迁移:账号/档案/公告/关注与历史/标签;检索方案/批次/有序快照/会话消息;任务/幂等命令/事件/实际调用/证据/临时文件元数据。D2–D3 所需表提前建立,不代表这些业务接口均已实现。 - Spring Security 会话认证,BCrypt 初始 admin,CSRF 覆盖登录、退出和所有写接口。账号由环境初始化,不提供注册或默认弱密码。未登录的任务、档案、文件、关注均被拦截;不存在的文件接口也不绕过登录。 - 八组手填档案,后端计算版本、时间和完善状态;最低企业名称+主营业务;四维权重固定名称,非负且不能全零。版本冲突返回 409,避免多页面覆盖。 - 关注增删、读取及初始历史原子保存,重复关注只保留一条。只能关注已从真实检索取得的公共公告;取消关注清理其历史与标签绑定,不删除公告或独立任务。 - 单实例有界执行器(2 线程、16 排队),D1 单任务执行一个白名单验证动作。三个工作流锁定版本并正确发送 `X-Client`,没有“一次 HTTP 请求执行完整 Skill”的虚构接口。 - 有序持久化事件、SSE 重放、创建/继续幂等、等待输入/主体/预算、取消、重启中断处理。HTTP 传输不自动重试。 - 实际调用账本保存状态、HTTP 状态、耗时、`meta.cost_units`、返回的实际模型与 usage。未知成本为 null,不能当成零。文本响应不保存或向前端发送 `reasoning_content`。 - 前端同源客户端、会话恢复、真实登录与退出、档案读取保存、移除档案 AI 导入、清除旧演示档案自动加载、任务验证页与真实事件组件;不自动上传浏览器旧演示数据。 ## 需要补充的环境变量 | 变量 | 用途 | 必须时间 | | --- | --- | --- | | `DB_URL` | MySQL JDBC URL,含数据库名及 UTC 连接时区 | 后端启动前 | | `DB_USERNAME` / `DB_PASSWORD` | 数据库用户名与密码 | 后端启动前 | | `ADMIN_INITIAL_PASSWORD` | 首次初始化 admin,不限制最小长度;不能为空,UTF-8 最多 72 字节(BCrypt 上限) | 首次启动前 | | `ZLBX_API_KEY` | 知了标讯数据与账户查询 | 知了真实验证前 | | `DEEPSEEK_API_KEY` | 文本、结构化、流式、联网 Search/Fetch、视觉 | 模型真实验证前 | 完整占位符见根目录 `.env.example`。不需要 Redis、Milvus、向量模型、OSS、千问、智谱或发布渠道密钥。后端启动时读取环境,补充或变更后重启;随后可显式继续原先等待配置的任务。 ## 已开放接口 统一 `/api`,除 CSRF 引导与登录外均需要服务端会话 Cookie;写请求要带 CSRF header。错误响应 `{"code":"...","message":"..."}`,不返回 SQL 或供应商原始认证错误。 | 方法与路径 | 请求 / 行为 | | --- | --- | | `GET /auth/csrf` | 返回 `{token,headerName}`,含登录前引导;原样回传 token | | `POST /auth/login` | `application/x-www-form-urlencoded`:`username=admin&password=...`,成功后重新获取 CSRF | | `GET /auth/me` | 恢复真实登录会话 | | `POST /auth/logout` | 会话失效,删除 Cookie;写请求必须有 CSRF | | `GET/PUT /company-profile` | 与前端八组字段一致;PUT 含当前 version,返回服务端权威版本与完善状态 | | `GET /watch` | 当前账号的关注记录及历史 | | `POST/DELETE /watch/{projectId}` | 关注或取消,公告 ID 例如 `zlbx-8240`;不接受演示项目 | | `GET /watch/{projectId}/history` | 只读自己的关注历史 | | `POST /agent/tasks` | 创建单动作验证任务,必须 `Idempotency-Key` | | `GET /agent/tasks` | 最近 50 个当前账号任务 ID | | `GET /agent/tasks/{id}` | 状态、原始参数快照、结果、真实调用账本和证据 | | `POST /agent/tasks/{id}/continue` | 仅等待状态允许;补充同类任务参数,必须独立 `Idempotency-Key` | | `POST /agent/tasks/{id}/cancel` | 停止未发出的动作;已发出的请求继续计费和记账 | | `GET /agent/tasks/{id}/events` | SSE;支持 `Last-Event-ID` 或 `?after=数字` | | `GET /agent/tasks/{id}/event-history` | JSON 事件分页,每次最多 100,after 为上次事件 ID | | `GET /agent/tasks/{id}/report` | D1 与任务详情相同,返回单项验证结果,不生成完整业务报告 | | `GET /system/limits` | 可公开的调用、积分、分页及未来文件保护值,不返回密钥 | 任务示例(先登录获取会话与 CSRF): ```json { "operation": "BID_SEARCH", "workflow": "TENDER_SEARCH", "input": "智慧水务,水质监测", "entityConfirmed": false, "maxCalls": 1, "maxCostUnits": 1 } ``` `workflow` 为 `TENDER_SEARCH` / `COMPANY_INTEL` / `BID_DECISION`;对应 `zlbx-bidding/2.3.0` / `company-intel/1.0.2` / `bid-decision/1.0.4`。`operation` 白名单:`ZLBX_BALANCE`、`BID_SEARCH`、`BID_DETAIL`、`COMPANY_SEARCH`、`COMPANY_PROFILE`、`MODEL_TEXT`、`MODEL_JSON`、`MODEL_STREAM`、`WEB_SEARCH`、`WEB_FETCH`、`VISION`。客户端不能指定任意工具 URL 或认证头。 `BID_SEARCH` 是 D1 小样本探针:关键词用中英文逗号分隔,最多 10 个,组内 OR;全国近 90 天,阶段 `[1,2,4,7,8]`,只读第 1 页、最多 3 条,不宣称全量召回。`BID_DETAIL` 只接受数字公告 ID。企业画像需要显式确认主体;不根据第一条自动选择或合并集团。视觉仅发送后端生成的“D1 8240”样图,不接收文件上传。 幂等键 8–128 字符,按账号隔离;同键同请求返回同任务,同键不同请求 409。继续操作按任务和独立命令键防重。SSE ID 全局递增,同任务有序;只读事件重连不会重复收费。终态或等待状态发送 `idle` 后关闭;补充参数后重新订阅。事件包括 `RECEIVED`、`STATE`、`TOOL_START`、`TOOL_COMPLETE`、`TOOL_FAILED`、`REPORT_FRAGMENT`。不会展示私有推理链。 ## 保护值与边界 - 默认每任务最多 5 次实际请求、10 知了积分;每个 D1 探针只执行一步。预算不足时暂停继续,必须用户显式操作。**未核实工具价格时,积分预算无法保证首个请求一定不超额**;返回 cost 后如实展示,不把未知费用当作 0。暂停后的继续累计调用次数,不清零账本。 - D2 检索保护值先配置每页 50、最多 5 页;D1 探针仅最多 3 条,不占用全批预算。检索结果单位由供应商原样保留,D2 前不在列表中假装已完成金额标准化和排序。 - HTTP 连接超时 10 秒,请求/读取默认 90 秒,最多 4 MiB 响应,不跟随供应商重定向;所有超时和不确定结果不自动重试。 - 未来文件保护值预先配置:20 MiB、PDF 50 页、视觉最多 20 页/张、原件 24 小时、审计元数据 180 天。D1 尚未开放上传,也尚未运行文件清理,不能把这些配置当作文件能力已交付。 - 临时文件处理选用 Apache Tika 负责 Office/文本/HTML 类型检测与文字提取,PDFBox 负责逐页 PDF/扫描页渲染;D3 再加入经核实兼容版本和代表性样例,D1 不引入尚未使用的解析库。 - 服务重启把排队/计划/运行任务标记为 `PARTIAL`,进行中的调用标记 `UNKNOWN`,不自动重放。会话需重新登录。 ## 测试与真实验收 本地验收结果(2026-10-26): - 后端 `mvn test`:**15 项通过,0 失败,0 错误,0 跳过**。覆盖会话/CSRF/退出、密码哈希、三组迁移、档案版本/权重、并发幂等、等待主体/输入、继续防重、业务失败/额度不足/空结果/限流、真实协议流片段与 usage、事件重放、归属鉴权、关注唯一与历史清理、内网 URL 拒绝、缺凭证预检、重启中断恢复,以及各 D1 供应商动作的本地协议契约。 - 前端 `npm run build`:通过。新增 API 客户端、任务事件 Hook、服务验证页,以及本次登录/档案/App/Topbar 的定向 ESLint:通过。 - 对旧 `store.tsx` / `DiscoverPage.tsx` 的定向 lint 仍有 8 项预存错误;已用 Git HEAD 原文件复验,分别是混合导出 Fast Refresh 规则、渲染时 Date.now 和 effect 内同步状态更新。本次不扩大范围整改旧原型。Vite 的单包体积 >500 kB 提醒仍保留,构建成功。 - 浏览器端(临时 H2 文件库,供应商 Key 清空):错误密码被拒绝;正确登录;初次档案为空、无 AI 导入;手填公司名/主营业务后保存 v1;刷新后仍可读;关闭并重新启动 Java 进程、重新登录后内容与 v1 仍在;历史验证任务仍在;缺 Key 显示 WAITING_INPUT,实际调用列表为空;退出回到登录页。测试服务已关闭,测试数据未写入真实库。 - 测试使用 H2 MySQL 模式和本地 HTTP 协议样例,不证明真实 MySQL/供应商可用。H2 由 Spring Boot 管理为 2.4.240,Flyway 提示其已验证版本为 2.3.232;当前 3 组迁移与测试均通过,仍需真实 MySQL 验收。 ![D1 缺凭证时的真实等待状态与零实际调用](./d1-service-check.png) | 依赖验收 | 当前状态 | 补充后执行 | | --- | --- | --- | | MySQL 迁移、刷新与后端重启后档案仍可读 | 待补数据库,未验证 | 启动、保存、刷新、重启、登录回查版本 | | 知了余额与权限 | 待补 `ZLBX_API_KEY`,未验证 | 余额单项任务 | | 知了检索/详情/主体/画像字段与费用 | 未发真实请求 | 小样本任务,记录字段、耗时、HTTP、cost,脱敏后锁定差异 | | DeepSeek 文本/JSON/流式 | 待补 `DEEPSEEK_API_KEY`,未验证 | 分别创建三项任务,记录实际 model 与 usage | | DeepSeek Search / Fetch | 未发真实请求 | 独立两项任务;不能由文本成功推定联网通过 | | DeepSeek 视觉 | 未发真实请求 | 样图识别应读出 D1 8240,人工核对内容与 usage | 真实验证请使用页面逐项显式发起,不要一次批量跑完整深度报告。任务详情保存实际返回数据供契约核对,文档中只登记脱敏字段与调用 ID,禁止复制 Key、原始认证头和带签名参数的完整 URL。 官方协议核对(2026-10-26):[DeepSeek 模型与调用](https://api-docs.deepseek.com/quick_start/agent_integrations/)、[Search & Fetch](https://api-docs.deepseek.com/guides/search/)、[视觉](https://api-docs.deepseek.com/guides/vision/)、[Spring Security CSRF](https://docs.spring.io/spring-security/reference/servlet/exploits/csrf.html)。模型默认 `deepseek-flash`,实际标识以每次响应为准;不能把参考项目的旧模型别名当作实测版本。