Commit 624ee95e authored by 王蔡翾's avatar 王蔡翾
Browse files

bug修复

parent 6e1d9234
# 只有 API Key 使用环境变量;数据库、管理员及其余参数在 src/main/resources/application.yaml 中配置。
# 可以直接在启动终端或 IDE 中设置,无需创建 .env;若使用 .env,仍需手动导出。
# API Key 仅后端使用,禁止放入 VITE_*。
ZLBX_API_KEY=
DEEPSEEK_API_KEY=
...@@ -31,3 +31,11 @@ build/ ...@@ -31,3 +31,11 @@ build/
### VS Code ### ### VS Code ###
.vscode/ .vscode/
# 部署凭证只保存在本机,允许提交不含密钥的示例。
.env
.env.*
!.env.example
# 可选的外部覆盖配置可能含凭证,禁止纳入 Git;如需使用须通过启动参数显式加载。
/application-local.yaml
var/
# 如昼商机助手后端
Java 21 / Spring Boot 4.1.2 / MySQL 8。前端位于相邻的 `rz-GB-web`。
D1–D4 代码已实现:会话登录、公司档案、分页检索与获客、平台市场聚合、匹配度及摘要快照、检索方案、八状态关注与标签、任务/SSE、实际调用和证据账本。新增单/双企业情报、项目快速/完整研判、投标文件解析与视觉、主体确认和预算恢复。D4 已补充持久化会话、单项目/整批快照问答、清理与恢复验收。2026-10-29 已接入本地指定的 MySQL 8.0.27,验证 V1–V7 迁移、健康检查、管理员登录及档案读取;104 项本地测试通过。供应商凭证及真实业务联调仍待补充,数据库重启持久化未在本次验证。
## 配置与启动
1. 创建空的 MySQL 8 数据库 `rz_gb`,字符集 `utf8mb4`。应用账号需具备该库的建表、索引和读写权限;Flyway 会按版本迁移,不需要手动逐个执行 SQL。
2. 数据库和管理员初始信息直接维护在 `src/main/resources/application.yaml` 的 `spring.datasource` 与 `rz.admin-password` 中,打包后随 JAR 加载。部署前核对数据库地址和账号;初始密码不限制最小长度,但不能为空,UTF-8 不超过 BCrypt 的 72 字节上限;`admin` 已存在时重启不会重置密码。
3. 其余参数直接修改 `src/main/resources/application.yaml`。只有 `ZLBX_API_KEY`、`DEEPSEEK_API_KEY` 使用终端或 IDE 的环境变量;可以暂不设置,先运行登录和档案功能。
4. 从后端项目根目录启动,无需加载 `.env`:
```sh
export JAVA_HOME=$(/usr/libexec/java_home -v 21)
mvn spring-boot:run
```
运行 JAR 不再依赖工作目录中的 `application-local.yaml`,修改主 YAML 后需要重新打包部署。源码主 YAML 和 JAR 均包含数据库及管理员初始化凭证,应限制访问。若需外部覆盖,可按 `application-local.example.yaml` 填写文件,再通过 `--spring.config.additional-location=file:/绝对路径/application-local.yaml` 显式加载。旧 `.env` 的数据库及其他参数不再由本项目读取。
服务默认 `http://localhost:8240`;`GET /actuator/health` 用于就绪检查。生产同源 HTTPS 部署时将主 YAML 中 `server.servlet.session.cookie.secure` 改为 `true`,反向代理 `/api` 到后端,并关闭 SSE 缓冲、设置足够的读超时。会话保存在当前实例内存,后端重启后需要重新登录;档案、任务、关注保存在数据库中。
## 前端
```sh
cd ../rz-GB-web
npm ci
npm run dev
```
默认 `http://localhost:3000`,Vite 已代理 `/api` 到 `8240`。先登录后填写公司档案,进入“服务验证”逐项测试。对话调研已接入四个真实任务入口、主体选择与预算暂停;未配置真实供应商时明确等待,不生成演示结果。
## 测试
```sh
export JAVA_HOME=$(/usr/libexec/java_home -v 21)
mvn -Djava.awt.headless=true verify
```
自动测试仅使用 test 作用域 H2 和本地 HTTP 模拟服务,不使用真实密钥,不产生外部费用。生产不包含 H2,不会自动降级到内存库。MySQL 重启持久化和真实服务验证需补充连接/凭证后执行,参见 `docs/D1实施与验收.md`。
D3 工作流、文件矩阵与验收见 [D3 实施与验收](docs/D3实施与验收.md)。D2 接口、快照、预算及验收见 [D2 实施与验收](docs/D2实施与验收.md);基础会话、事件与配置见 [D1 实施与验收](docs/D1实施与验收.md)。需求与四天计划保持在 [docs](docs/README.md)。
D4 结果、102 项本地测试、格式/异常矩阵和真实验收待办见 [D4 实施与验收](docs/D4实施与验收.md);构建、V1–V7 初始化、部署和新增接口见 [接口契约与运行交付](docs/接口契约与运行交付.md)。
# 可选的外部覆盖示例;默认数据库与管理员配置已在 src/main/resources/application.yaml 中维护。
# 如需覆盖,复制为 application-local.yaml,填写后通过以下启动参数显式加载,无需激活 profile:
# --spring.config.additional-location=file:/绝对路径/application-local.yaml
# 本示例不含凭证,根目录的实际 application-local.yaml 仍由 Git 忽略。
spring:
datasource:
# JDBC 库名不加反引号;UTC 会话与本项目的数据库时间戳约定一致。
url: "jdbc:mysql://localhost:3306/rz_gb?useUnicode=true&characterEncoding=UTF-8&connectionTimeZone=UTC&forceConnectionTimeZoneToSession=true"
username: ""
password: ""
rz:
# 首次初始化使用;已有 admin 时不会重置密码。使用引号,避免 YAML 把数字密码解析为数值。
admin-password: ""
# 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`,实际标识以每次响应为准;不能把参考项目的旧模型别名当作实测版本。
# D2 实施与验收记录
日期:2026-10-27(北京时间)。范围对应《四天开发计划》4.1–4.3。
**D2 前后端代码与本地联调已完成,真实 MySQL / 知了接口验收尚未通过。** 当前执行环境未配置数据库、admin 初始密码、知了及 DeepSeek 凭证,本轮未向真实供应商发送请求,未产生外部查询费用。
## 交付范围
- 发现商机提供普通检索、获客报告、区域市场三个模式。默认全国、近 90 天;今天、三天、一周、一个月、半年、一年与自定义日期均可使用。日期在创建时固定,使用北京时间。
- 关键词使用逗号分隔,最多十个。OR 对接 `search_bids`;AND 对接 `query_bids_advanced` 的组间 AND。金额在本系统使用万元,适配接口时转换为元,并区分 `min_amount` 与 `min_money`。
- 普通检索的省份/金额是显式硬条件,按发布时间降序展示。获客省份/金额仅用于偏好排序,不排除其他省份或未知预算候选。可用同批临时偏好视图调整顺序,不请求新页、不改变原快照。
- 每页读取均记录真实请求开始、状态、耗时及实际费用;同一批次按公告 ID 去重,记录平台命中、已取数、去重数、展示数、页数和停止原因。预算等待后从下一页继续,不重新读取成功页。
- 同名标题不合并项目。有明确 `project_code`、采购方、地区和标段时建立阶段关联链,保留各阶段公告及证据;字段不足则保持独立公告。当前计数明确按公告,避免将无法核实的项目数冒充真实归并结果。
- 列表摘要逐页执行原文规则摘录,保留建设内容、地区、节奏、资质业绩片段、信息缺口及证据定位。未取得正文时不补造资质或工期,不自动逐项获取详情、调用企业情报或投标决策。
- 四维匹配由后端计算并冻结档案版本、权重、维度依据与完整性。档案未完善时不提供综合分;已完善时未知维度用中性 50 分并标待核验。按权重归一化,最终一次四舍五入取整;匹配分不是资格认证或中标概率。
- 方案支持保存、编辑、删除和手动执行。方案执行与版本登记同一事务提交后才派发任务。执行保存固定日期、条件、档案和公告事实/分析;编辑或删除方案不改变旧结果。历史 Tab 只回读,不触发收费请求。
- 关注八状态可人工自由跳转、从暂不考虑恢复、单独修改备注。状态/备注/历史一次事务提交,版本检查防覆盖,命令幂等防重复留痕;未变化的同值保存不新增历史。
- 标签支持创建、全局删除解绑、项目多选与筛选,账号隔离。标签绑定和删除会更新关注版本。取消关注沿用确认弹窗,只清理个人关注、历史与标签绑定,不删除公告或独立报告。
- 前端“了解采购方”“深入研判”保留显式入口,目前明确提示由 D3 接入,没有伪造深查调用。
## 区域市场的两种统计口径
区域市场明确指定的省份是硬条件,留空为全国;未填业务词时实际使用并公开展示:`智慧水务、供水、污水处理、水质监测、管网漏损`。
工作流先调用 `get_top_purchasers`、`get_top_suppliers`、`aggregate_bids_advanced(group_by=month)`,再读预算允许的公告页。三个聚合步骤共享任务预算、调用账本及哈希证据;预算暂停恢复时跳过成功步骤。
平台 Top 与趋势按其工具实际口径展示,公告勾选的阶段只约束公告样本。采购方工具统计采购、供应商工具统计中标、月度工具使用支持的公告口径,不能把这些数字与样本公告数混算成市场份额。只有样本统计时明确标“已读去重公告样本”;聚合失败或预算不足不以样本冒充平台统计。
由于 Top 工具的锁定契约未提供 AND 分组,区域市场当前只接受 OR;需要 AND 时使用普通检索/获客,不能悄悄改成 OR。公告初始保护值最多 5 页 × 50 条;市场的三次聚合也占请求预算,所以默认 5 次上限下通常只剩两页公告额度。达到部署保护值不能无限继续。
## 新增及扩展接口
所有接口在 `/api` 下,需要服务端会话;写请求必须带 CSRF。
| 方法与路径 | 行为 |
| --- | --- |
| `POST /searches` | `{conditions,maxCalls,maxCostUnits}`,必须带 `Idempotency-Key`;返回统一任务 |
| `GET /searches` | 最近 50 次执行,含方案名称/版本及时间;不产生外部调用 |
| `GET /searches/{id}` | 任务状态、已验证报告、实际调用与证据 |
| `GET /searches/{id}/items?page=1&size=20` | 从固定批次分页,每页 1–50;不读取上游新页 |
| `POST /searches/{id}/continue` | 原条件加新累计预算,独立幂等键;仅等待状态可继续 |
| `POST /searches/{id}/view` | `{preference,regions,minWan,maxWan}`;临时重排原候选集,无外部请求 |
| `GET /projects/{id}` | 当前账号已取得或关注的公告快照 |
| `GET/POST /search-schemes` | 列举/保存方案;保存不执行检索 |
| `PUT/DELETE /search-schemes/{id}` | 编辑需当前 version,删除保留独立执行记录 |
| `GET/POST /search-schemes/{id}/runs` | 历史任务 ID / 手动执行;POST 需幂等键,预算用部署上限;发现商机传 `strictFilters=true`,将旧 LEADS 方案的地区与金额转为新任务硬条件,原方案和历史任务不变 |
| `GET /watch?group=跟进中&tag=重点` | 可选按三个分组和标签筛选,含版本、公告、标签与历史 |
| `POST /watch/{id}/changes` | `{status?,note?,version}`,必须带幂等键;status 留空可单改备注 |
| `GET /watch/{id}/history` | 按关注版本排序的个人状态/备注历史 |
| `GET/POST /tags`、`DELETE /tags/{id}` | 标签列举、创建、全局解绑删除 |
| `PUT /watch/{id}/tags` | `{tags:[标签名称],version}`,必须带幂等键,标签必须属于本人 |
`conditions` 字段:`keywords`、`keywordMode: ANY/ALL`、`mode: SEARCH/LEADS/MARKET`、`beginDate/endDate`、`stages`;偏好 `preference: COMPREHENSIVE/REGION/BUSINESS/AMOUNT`、`preferredRegions`、`budgetMinWan/budgetMaxWan`;显式硬条件 `hardRegions`、`hardMinWan/hardMaxWan`。后端拒绝向 LEADS 偷渡硬筛选。所有金额非负、上下限有序、日期不晚于今天且跨度不超过一年。
数据库新增 **V5**:任务档案快照、列表分析快照与哈希、方案执行版本登记、关注幂等命令、历史版本、市场聚合证据关联。保留 V1–V4,不改写已发布迁移。生产仍必须使用 MySQL,H2 仅在测试作用域。
## 验证结果
| 验证 | 结果与证明范围 |
| --- | --- |
| Java 21 `mvn -o test` | **39 项通过,0 失败、0 错误、0 跳过**;H2 MySQL 模式+本机 HTTP 模拟供应商 |
| 前端 `npm run build` | TypeScript 与 Vite 构建通过,保留 >500 kB 包体提醒 |
| 本次新增/替换页面及契约、事件 Hook、App 定向 ESLint | 通过;未把旧 UI 组件全库 lint 作为已通过 |
| 本机浏览器获客/关注 | 登录、档案保存、方案保存、读取两页返回 4 条/去重 3 条、未知金额保留、完整测试样本 100 分、偏好视图、关注、状态备注事务、标签、历史、刷新回读均验证 |
| 本机浏览器区域市场 | 3 次平台聚合+2 页公告,共 5 次本机请求;聚合 800 与样本 3 分开展示;空档案综合分显示 `—` |
| 真实 MySQL / 供应商 | **未验证**,缺环境配置;不以模拟测试代替真实验收 |
自动测试还覆盖:OR/AND 参数和万元转换、原检索发布时间排序、评分精确权重及高分上限、缺正文/缺预算、证据篡改拒绝、同标题不同阶段保留、可靠编号关联、方案编辑/删除不改快照、旧档案不重算、关注重复命令与旧版本拒绝、标签权限/解绑、市场聚合预算恢复不重跑,以及原 D1 会话/CSRF/供应商失败边界。
下图为明确标注“测试”的本机夹具,不是真实采购项目:
![关注状态、备注、标签与历史测试](./d2-watch-fixture.png)
![平台聚合与公告样本范围测试](./d2-market-fixture.png)
## 开源架构参考与本次采纳
本次查阅六个仓库说明,并补读可访问的监控脚本、Fire Enrich 编排器、中文 DOCX 解析器和 DeepResearch 控制器。没有复制第三方源码或引入其运行依赖;历史调研中的提交与许可记录仍在 [GitHub 相似项目调研](./GitHub相似项目调研.md)。
| 项目与本次访问来源 | 可借鉴之处 | 本轮处理 |
| --- | --- | --- |
| [BidMaster-Pro](https://github.com/guangshu100/BidMaster-Pro) | 招标解读、Skill 与商机入口的功能组织 | 作为功能对照;本轮原始 fetchers 路径未成功访问,不追加未经核实的实现断言 |
| [全国机会监控脚本](https://raw.githubusercontent.com/FightingThrones/guiyang-tender-monitor-skill/main/guiyang-tender-monitor/scripts/tender_monitor.py) | 结构化来源、评分理由与日报字段 | 不复制分数阈值筛掉候选的做法,偏好变化保留原集合 |
| [中文 DOCX 解析器](https://raw.githubusercontent.com/sanwudazhiyuan/-bid-analysis/main/src/parser/docx_parser.py) | 段落/表格保留顺序、格式与证据定位 | 原文摘录保留定位;完整文件链路属于 D3,未提前声称完成 |
| [TenderGraph](https://github.com/Amawta-labs/tendergraph) | 后端在模型之外校验证据与来源版本,明确合成数据范围 | 公告证据、列表分析哈希、范围校验及冻结报告;不采用其合成商机作生产数据 |
| [Fire Enrich 编排器](https://raw.githubusercontent.com/firecrawl/fire-enrich/main/lib/agent-architecture/orchestrator.ts) | 按所需字段选择阶段、共享已取得上下文 | 列表摘要复用本批原始事实,不附带触发企业深查 |
| [DeepResearch 控制器](https://raw.githubusercontent.com/spring-ai-alibaba/deepresearch/main/src/main/java/com/alibaba/cloud/ai/example/deepresearch/controller/ChatController.java) | 有限执行、SSE、停止及人工继续入口 | 复用现有持久化任务/有序事件和预算等待;不整体迁入 Graph/RAG 平台 |
这些是针对本项目的工程判断,不是第三方部署、抽取准确率或供应商覆盖率的实测结论。
## 真实环境后续验收
按根目录环境示例配置 MySQL、admin 密码、知了 Key 后启动。先小样本确认 OR/AND、金额单位、公告正文及项目编号字段,再运行全国近 90 天获客。核对调用 ID、平台总数、分页、积分、来源;选浙江偏好检查安徽等候选及未知预算仍保留。独立验证市场三个工具的字段与口径,再验证服务重启后方案、报告与关注仍可读取。
D3 企业情报/项目深挖、文件解析及 D4 全范围恢复/历史会话等继续按原计划实施。当前摘要是可追溯规则摘录,不是模型完成的深度招标解读;不得以列表分数承诺资格通过或中标。
# D3 实施与验收
日期:2026-10-28(北京时间)。本次继续现有 D1/D2 未提交代码,没有重置或覆盖已有成果。
**状态:前后端代码、本地自动测试和浏览器联调已完成;真实 MySQL、知了、DeepSeek 账号联调未验证,因此不能把 D3 的真实服务验收门槛标为通过。** 本地 HTTP 模拟请求只用于可重复测试,不是实际供应商数据或计费凭证。
## 1. 已实现范围
### 企业情报与双公司对比
- `COMPANY_RESEARCH` 固定使用 company-intel 1.0.2。先查询企业候选;完整返回范围中仅有一个且全称精确匹配时可以自动确认。多主体、简称或模糊匹配均等待选择,不按记录量选择第一条。
- 双公司必须全部完成主体确认后才启动后续画像;两个主体不能相同。确认值与本任务候选比对,确认后锁定,预算继续不能把旧事实拼到新公司上。
- 基础画像、业务词、客户、供应商、中标明细、年度聚合和真实投标重叠竞对分别实际请求。历史明细与伙伴只覆盖返回页/Top20,不声称已取全量。单企业 Top3 竞对仅查基础画像,不递归展开。
- 双公司共同客户为两家客户样本的企业全称交集;交锋事实展示竞对工具原始 `co_bid_count` 等字段。没有交锋数据时不把行业头部当直接竞对。
- 公开资料通过后端 DeepSeek Search 查询,最多三条;首个安全来源再通过 Fetch 获取正文。每条网页来源单独登记证据;未检出风险不等于无风险。
- 已完成企业任务可选择画像、伙伴、业绩、竞对或公开资料局部追问。子任务复用经过校验的确认主体缓存,账本明确显示 `LOCAL / ENTITY_CACHE`,只补查选定部分,不重复执行整份工作流。
### 项目研判
- `BID_RESEARCH` 固定使用 bid-decision 1.0.4。支持完整标题、知了公告链接、其他公开公告链接及投标文件。普通公开链接先 Fetch,再使用公开标题站内定位;知了链接走详情工具原生 `bid_url` 参数,不自行删改签名。
- 公告或采购方有歧义时等待候选选择。快速模式取得项目正文、采购方基础画像与证据建议;完整模式增加采购方历史供应商/采购史、潜在竞争者、公开资料,并在明确有品牌及型号时查询历史单价。
- 服务项目或无型号时不查询品牌价格;不混算项目总价、设备单价或不同规格,不产生利润承诺和精确胜率。
- 创建项目任务时冻结我方档案;档案完善且取得公开项目正文时复用既有四维规则输出我方适配、完整性、依据与档案版本。评分不是资格认定或胜率。
- 文件没有完整公开标题时可先创建任务,再等待补充;不会把文件全文送到公开搜索。无站内结果时保留文件/公开网页事实并明确未核实。文件与公告是否完全一致、是否最新版,仍需人工核对。
- 获客结果的“了解采购方”“深入研判”先展示对应输入,用户显式发起后才创建父子任务。后端检查账号、批次及所选对象,每批最多五个、串行执行;结果链接显示在原对象下。初始获客报告不隐式深查。
### 文件与真实轨迹
- 上传只接受 `BID_PROJECT`,取当前会话账号为归属;沿用 CSRF。首次绑定后不能转移至另一个任务,公司档案导入不开放。
- 使用 Apache POI 5.5.1、PDFBox 3.0.8、jsoup 1.21.2 与 TwelveMonkeys WebP 解码。正文按段落/工作表与行/幻灯片/PDF 页保留定位;不伪造 Office 页码。依赖依据:[POI 提取文档](https://poi.apache.org/text-extraction.html)、[PDFBox 3 迁移文档](https://pdfbox.apache.org/3.0/migration.html)。
- 文字 PDF 本地提取,扫描页渲染后逐页视觉;同页存在文字页眉和大幅扫描图时仍走视觉。图片按帧解码,GIF 不只读取第一帧。Office 宏、HTML 脚本和外链不执行。
- 默认最大原件 20 MiB、PDF 50 页、视觉 20 页、提取全文 200,000 字符;工作表/幻灯片数复用 50 上限;临时解析图片总量最多为原件大小保护值的两倍(默认 40 MiB),按段检查。压缩包保留 POI 的压缩比防护,并限制单项解压大小。超限明确要求拆分,不静默截断。
- 原件、提取全文、临时页图都保存在数据库,24 小时到期或手动删除时统一清空,写入删除审计。任务报告必要摘录与调用账本保留,界面明确提示这一范围。
- 四个入口共享真实后端 SSE 和事件游标;移除 `runSkillTrace` 及原调研模板回答。收费步骤先落 STARTED,再发 HTTP;报告只展示持久化事件与已保存结果,不展示私有推理。
## 2. 预算、恢复与证据规则
- 部署默认外部请求保护值提高为 25、积分保护值为 100;可通过 `TASK_MAX_CALLS` / `TASK_MAX_COST_UNITS` 降低。单企业最多 18 次,双企业和项目最多 25 次,每个任务拥有独立调用及积分预算;实际执行还受部署保护值限制。
- 知了积分、DeepSeek token、联网请求次数分别记录,合计由后端权威计算、前端只展示,不相加为同一费用。缺失费用保持未知;不会用零或预估值冒充实际扣费。
- 达到调用/积分预算时暂停;知了响应缺积分时也暂停。继续时显式确认已发生的请求与未知费用,或增加预算。未知单价的首个请求可能超出积分保护值,不能承诺事前精确控制。
- 每个成功步骤保留唯一快照,继续或幂等重试跳过成功步骤。取消与发请求使用同一任务锁;取消后不再发送后续请求,在途请求照实保存结果和费用。
- 失败/未知结果不自动重试;服务重启仍使用已有的 PARTIAL 恢复规则,避免重放收费请求。
- 事实绑定证据 ID、完整来源 URL、定位和原始快照哈希。报告重建校验所有事实;并发读取时先取步骤,再取来源,避免把刚提交的步骤误判为缺失。
- 模型生成稿属于服务端草稿,不作为事实来源展示。模型建议只允许引用本任务已登记来源;关键数字必须原样存在于引用依据。未通过校验的建议隐藏,任务标为部分完成,保留可核查事实与费用。
## 3. 新增接口与请求示例
沿用 `/api/agent/tasks`、`/{id}/continue`、`/{id}/cancel`、`/{id}/events`、`/{id}/report`,写请求仍需会话、CSRF 和 `Idempotency-Key`。创建/继续幂等键各自作用于原有任务账本,刷新报告只读,不二次收费。
```json
{
"operation": "COMPANY_RESEARCH",
"workflow": "COMPANY_INTEL",
"input": "",
"entityConfirmed": false,
"maxCalls": 18,
"maxCostUnits": 10,
"research": {
"companies": ["待研究企业名称"],
"selections": {},
"mode": "FULL",
"fileId": null,
"parentId": null,
"targetProjectId": null,
"focus": null,
"acknowledgedCalls": 0
}
}
```
- 项目改用 `BID_RESEARCH / BID_DECISION`、`companies: []`,`input` 为完整标题/公开链接;上传文件时填写 `fileId`。`mode` 为 `QUICK` 或 `FULL`。
- `research.selections` 的键与候选 `choices[].key` 一致,值必须是本任务返回候选 ID。不能用 `entityConfirmed: true` 绕过候选校验;新建任务不能预先提交选择或费用确认。
- 继续沿用完整原请求,只修改合法选择、预算,以及已经发生的请求数 `acknowledgedCalls`。定位后的项目、公司、文件、模式、父任务和追问范围不能改变。
- 局部企业追问使用已完成企业任务 `parentId` 和 `focus`:`profile / partners / performance / competitors / public`。
- 文件:`POST /api/files`,multipart 字段 `purpose=BID_PROJECT`、`file`;`GET /api/files/{id}` 读取本人元数据与提取预览;`DELETE /api/files/{id}` 清理本人原件、全文与临时图片。浏览器不手设 multipart Content-Type,以保留 boundary。报告页在任务结束或取消后提供明确范围的原件删除操作。
- 新增迁移 `V6__research_files.sql`:研究步骤、锁定主体、原件/派生文件字段、删除审计。保留 D1–D2 表和请求指纹兼容,不修改已发布迁移内容。
## 4. 已执行验证
### 自动化
- 后端 `JAVA_HOME=$(/usr/libexec/java_home -v 21) mvn -q verify`:**79 项测试通过,0 失败、0 错误**。包括原有 39 项、D3 工作流 17 项、文件解析 23 项。
- 前端 `npm run build`:通过。
- 对本次修改涉及的 TS/TSX 执行 ESLint:通过。包括调研页、统一任务组件、事件订阅、API 客户端、发现商机入口、App、Topbar 及移除演示代码涉及文件。
- 两个仓库 `git diff --check`:通过。
工作流测试覆盖:同名等待前无深查、双公司都确认、唯一精确匹配、非法/锁定选择、单/双企业、快速/完整研判、标题/知了链接/公开链接/文件路径、X-Client 路由、预算恢复幂等、未知积分确认、暂停取消与在途取消计费、局部追问缓存、父子任务五对象及串行约束、篡改证据拒绝、模型引用失败隐藏、视觉实际 HTTP 与隐私字段隔离、文件归属/用途/CSRF/过期/删除。
### 格式矩阵
| 格式 | 本地代表性样本结果 | 定位/边界 |
| --- | --- | --- |
| TXT、MD、CSV、HTML | 通过 | UTF-8 中文、GB18030;HTML 不执行脚本;CSV 保留原始行 |
| DOC | 通过 | Apache POI 官方开源样本;段落定位,来源及许可证见测试资源目录 |
| DOCX | 通过 | 中文段落和表格,明确没有可靠分页 |
| XLS、XLSX | 通过 | 中文工作表、行号、数值;伪装后缀拒绝 |
| PPT、PPTX | 通过 | 中文文字、幻灯片编号 |
| 文字 PDF | 通过 | 本地提取,不额外视觉 |
| 扫描 PDF | 通过 | 按页生成视觉输入 |
| 混合 PDF | 通过 | 文字页/扫描页分别处理;文字页眉加扫描正文也识别为需视觉 |
| JPG、PNG、GIF、WebP | 通过 | 解码后转逐帧视觉输入;WebP 使用实际解码器 |
| 损坏、伪装、加密、超页/超全文 | 通过 | 明确失败或提示拆分,没有静默截断 |
这些是代表性合成/开源样本,并非全量真实标书。中文复杂 PDF、低清扫描、GIF 动画合成、Office 嵌入图片/复杂图表、超大表格和复杂布局在 D4 继续扩大样本验收。
### 浏览器(H2 + 本地 HTTP 模拟服务)
已实际登录测试账号并操作:四入口展示;同名企业只有一次主体查询即暂停;选择分公司后完成工作流;一次调用预算暂停及确认恢复;区域市场入口返回聚合/公告报告;从获客结果创建采购方子任务;multipart 上传非敏感 TXT 并完成文件项目快速研判。检查了真实事件、源链接、消耗、文件定位与缺口文案。
- [企业画像截图](images/D3-企业画像-本地模拟.png)
- [文件研判截图](images/D3-文件研判-本地模拟.png)
截图和界面测试资料均明确使用“界面测试”样本,不能当作知了或 DeepSeek 真实业务验收证据。测试服务使用内存数据库,验收后停止,不更改生产数据。
## 5. 尚未通过的真实验收与 D4 边界
1. 本地没有提供真实数据库连接、知了/DeepSeek 凭证,真实 MySQL 迁移/重启持久化、供应商字段/积分、模型、Search/Fetch 和视觉均**未验证**。需配置后按 D1/D2/D3 文档逐项实测,尤其核对各企业/项目工具的实际字段。
2. 模型事实名字、文件与公告一致性、历史价格可比规格仍需人工核验;服务端引用/数字校验不等于尽调结论真实或来源网站真实。
3. 明细与伙伴限返回首批,公开资料最多三条;共享客户是样本交集,不能称全量共同客户。未返回的事实显示缺口。
4. 多扫描页加完整研判可能达到累计 25 次保护上限,需要拆分资料或在创建时选择快速模式;不能无限增加预算绕过部署保护。
5. 前端构建有主 JS 包超过 500 kB 的体积提醒,构建成功;本次没有扩大到无关依赖清理或全站代码拆包。
6. D4 的完整历史会话 CRUD、整批问答、断线/服务重启场景扩大、全范围真实资料格式/异常验收和部署交付仍按四天计划继续。本次没有把这些项目提前标为完成。
# D4 实施与验收
日期:2026-10-28(北京时间)。继续 D1–D3 已有未提交成果,未重置两个仓库。
**交付状态:D4 前后端实现、本地回归、代表性格式测试、浏览器联调与运行文档已完成;真实 MySQL、知了和 DeepSeek 联调未验证。不能据此宣称四天计划全部真实验收通过。**
当前进程未设置 DB_URL、DB_USERNAME、DB_PASSWORD、ADMIN_INITIAL_PASSWORD、ZLBX_API_KEY、DEEPSEEK_API_KEY;后端没有 `.env`。未读取或输出其他项目的凭证,未使用模拟数据替代真实服务证据。
## 1. 本次实现
### 历史会话与真实问答
- 新增会话新建、按标题及用户问题搜索、分页、自动标题、带版本的重命名、删除与历史消息读取。首次问题自动生成标题,人工命名后不再覆盖;同一任务重复关联不重复写消息。
- 调研四入口创建的任务关联到持久化会话。较早 D1–D3 的独立任务仍可从最近任务回查;没有静默为旧任务批量生成会话。
- “发现商机”提供整批结果及单项目 AI 提问,“重点关注”提供单项目入口。打开入口不调用模型,明确提交问题才发起一个 `SNAPSHOT_QA` 任务。
- 整批从数据库读取该快照的全部 `search_item`,不取当前分页的 20 条,不使用前端临时偏好排序作为事实。单项目仅包含所选项目。候选、条件、日期、已读取数、平台总命中数、来源在提交时冻结并计算完整性哈希。
- 问答只调用一次后端模型,不重新执行招投标检索、企业情报或项目深查。报告标为建议与推断;逐条核验来源、关键数字及链接。无效回答隐藏,任务部分完成,实际模型与 token 仍保留。
- 每个候选保留全部标准化字段;每条正文最多提供前 1000 字,明确标记摘录。完整上下文超过 600,000 字符时拒绝并建议单项目提问,不静默省略候选,也不宣称读过完整标书。
- 后续问题默认沿用最近一次快照问答范围,每次按当时批次冻结;每次模型请求独立记账。当前不把历史模型回复当新事实来源;依赖省略指代的问题应补全对象名称。
- 删除会话只删除会话及消息。独立任务、实际费用、关注、原件按各自生命周期保留;桌面与窄屏均有明确删除范围和确认交互。
- 移除原未接入后端的 AI 面板、本地模板回答、模拟逐字流及内存会话存储,当前页面不会将这些内容作为真实结果展示。
### 文件生命周期与格式边界
- 到期文件在 GET 时立即清理,定时任务尚未运行也不能返回全文。定时清理每次最多 100 条,按到期顺序处理;重复清理/手动删除只保留一次删除审计。
- 文件绑定、证据记录同事务;发出新的依赖文件请求前再次检查删除、归属和过期。已经登记并发出的请求属于在途请求,删除不能撤回已发送内容和实际费用。
- 原件、提取全文与派生图片保存在有期限的临时表,删除统一置空。长期文件证据只保留每段最多 2000 字的必要摘录和定位,不再复制整份长文件全文;这部分摘录与费用账本不会随原件删除。
- 补充 DOC/DOCX、XLS/XLSX、PPT/PPTX 的内嵌图片提取;位图走相同视觉预算。无法可靠定位的图片只标资源编号及“位置需人工核对”,不伪造页码。不能解码的矢量图明确提示转换后补充。
- 既有 20 MiB、50 页、20 视觉页、200,000 字、临时图片总量保护值继续生效。Office 图片消耗同一视觉页预算,超限明确拆分。
- 公司档案导入仍关闭;文件只允许 `BID_PROJECT`。
### 恢复、费用与错误
- SSE 保留事件游标、去重及重连;网络不可达时按退避延迟只读重试,最多 15 秒间隔,恢复后追完最终事件。401/403/404 停止重连,登录失效回登录页。
- 创建与继续任务仍通过持久化幂等键及请求指纹防重;浏览器重复点击、网络结果未知后手动重试保留当前请求键。页面刷新、历史读取、来源展开、用量读取均不创建新收费任务。
- 重启把正在执行的任务标为 PARTIAL,在途 STARTED 调用标 UNKNOWN / RESTART_INTERRUPTED,不自动重放。生产会话保存在实例内存,重启后需要重新登录。
- 失败、部分完成、预算暂停均保留已有来源、调用与费用,并提供补充资料、调整条件或返回入口的下一步。取消后可手动刷新结果与用量,核对仍在途的请求。
- 新增 `/api/usage`,只汇总本账号持久化调用;知了积分、模型 token、未知用量分别列示,不能把本地账本当平台余额。服务验证页可显式读取,不隐式发起余额查询。
## 2. 已执行验证
运行环境:Java 21.0.12.1、Maven 3.9.16、Node 23.11.1、npm 10.9.2。Maven 启动命令明确指定 Java 21,避免主机默认 Java 8。
| 验证 | 实际结果 |
| --- | --- |
| `JAVA_HOME=$(/usr/libexec/java_home -v 21) mvn -q -Djava.awt.headless=true verify` | 102 项测试,0 失败、0 错误、0 跳过;生成后端 JAR |
| `npm run build` | TypeScript 和 Vite 构建通过,生成 `rz-GB-web/dist` |
| 本次修改涉及的 TS/TSX、Vite 配置 ESLint | 通过 |
| 两仓库 `git diff --check` | 通过 |
| 中文文字 PDF 额外样本 | 本机系统中文字体生成非敏感样本;中文、预算、行内报价文本完整提取,保留第 1 页定位,不调用视觉 |
| 实际进程强制中断/重启 | 临时文件 H2 + 本机模拟 HTTP;重新登录后 PARTIAL,原调用 UNKNOWN,报告/事件可读;模拟请求始终一次,无自动重放 |
| 浏览器 | 测试账号登录 → 模拟检索 → 整批问答 → 来源/费用 → 会话改名 → 刷新恢复 → 桌面侧栏搜索;同时检查窄屏会话操作 |
测试共六组:原基础业务 29 项、排序 5 项、摘要匹配 5 项、研究工作流 17 项、文件解析 30 项、D4 集成 16 项。D4 集成覆盖 25 个候选跨两页的末条问答、冻结范围、单项目范围、并发幂等、自动标题/搜索/版本冲突/删除、账号隔离、坏引用/坏数字、供应商认证/限流/超时/不可达、即时过期清理、长期摘录范围和只读用量。
测试最初在受限沙箱中因禁止本机 HTTP 端口失败,改为允许本机端口的测试进程后通过;文件解析以 `java.awt.headless=true` 运行。没有把环境启动失败记为业务测试通过。
![D4 历史会话与快照问答(本地模拟)](images/D4-历史会话与快照问答-本地模拟.png)
截图里的 `d4-ui-fixture-only` 和“界面测试”均为本地模拟资料,不代表真实 DeepSeek 模型、知了数据或真实扣费证据。
### 格式矩阵
| 格式/边界 | 本地结果 | 验证口径 |
| --- | --- | --- |
| TXT、MD、CSV、HTML | 通过 | UTF-8 中文、GB18030、CSV 原始行、HTML 脚本不执行 |
| DOC | 通过 | POI 开源段落样本;真实中文老 DOC 复杂排版未验证 |
| DOCX | 通过 | 中文段落/表格、内嵌位图;不伪造页码 |
| XLS、XLSX | 通过 | 中文表格/行号、内嵌图片、公式读取缓存值,不更新外链 |
| PPT、PPTX | 通过 | 中文幻灯片、内嵌位图,图像资源位置需人工核对 |
| 文字 PDF | 通过 | 常规英文样本及额外中文样本;不触发视觉 |
| 扫描/混合 PDF | 通过 | 逐页渲染、文字页与扫描页分流、文字页眉加扫描正文 |
| JPG、PNG、WebP、GIF | 通过 | 实际解码;GIF 增加两帧样本与逐帧定位 |
| 损坏/后缀伪装/加密/超限 | 通过 | 拒绝或要求拆分,不静默截断 |
| 低清真实标书、复杂图表/矢量/动画合成语义 | 未验证 | 无真实标书和真实视觉凭证;不承诺完整版面还原或 OCR 准确率 |
扫描件测试验证了本地渲染、视觉请求结构、位置和成本记录,未证明真实模型识别质量。
### 异常矩阵
| 场景 | 已验证行为 |
| --- | --- |
| 无结果、未知预算/地区、部分页成功 | 保留已读范围与缺口,未知金额不当零、不删除候选 |
| 401/403、业务失败、余额不足 | 区分认证、业务与预算原因;等待或失败,不当作无结果 |
| 429、网络超时、HTTP 503、网页域名不可达 | 明确原因及下一步;超时结果 UNKNOWN,不自动重试 |
| 模型引用或数字不可验证 | 隐藏生成结论,保留事实与实际用量 |
| 重复提交/同键不同内容 | 同键同内容复用;不同内容或会话冲突返回 409 |
| SSE 事件重放、取消、服务重启 | 事件有序、重放不创建收费调用;取消停止后续;重启保留未知费用 |
| 文件过期/删除/跨账号/跨任务 | 全文及派生物清理;拒绝非法复用,审计不重复 |
| 冻结上下文过大 | 明确提示单项目提问,不删除候选凑入模型上下文 |
## 3. A01–A20 验收账
“本地通过”仅指合成样例、测试数据库和模拟 HTTP。真实验收列不能由本地结果自动推导。
| 编号 | 本地判定与证据 | 真实验收 |
| --- | --- | --- |
| A01 鉴权退出 | 通过;真实安全过滤链、CSRF、登录/退出测试及浏览器登录 | 待指定环境 |
| A02 持久化 | 通过;数据库读取及临时文件 H2 进程重启 | MySQL 未验证 |
| A03 四入口 | 通过;既有 D3 浏览器记录及工作流测试 | 未验证 |
| A04 招投标实际请求 | 通过;本机 HTTP 调用与报告对应 | 知了未验证 |
| A05 初始不深挖 | 通过;工具白名单与调用断言 | 待真实账本核对 |
| A06 偏好不变候选 | 通过;候选集合、未知预算测试 | 待真实数据复核 |
| A07 两种排序 | 通过;冻结排序及匹配测试 | 待真实数据复核 |
| A08 召回范围 | 通过;分页、去重、平台总数、停止原因 | 供应商字段未验证 |
| A09 主体确认 | 通过;确认前无深查、范围冲突测试 | 同名真实主体未验证 |
| A10 双公司/项目 | 通过;单/双主体和快/完整工作流测试 | 未验证 |
| A11 真实轨迹 | 通过;本机请求账本与事件、移除模拟流 | 真实模型流未验证 |
| A12 来源与推断 | 通过;证据哈希、引用/数字拒绝、来源页面 | 来源事实仍需人工核验 |
| A13 预算费用 | 通过;暂停恢复、未知费用、token 分账 | 真实积分/账单未验证 |
| A14 八状态 | 通过;事务、版本、幂等、标签与历史测试 | 待指定环境演示 |
| A15 全格式 | 通过;代表性格式矩阵 | 真实资料/真实 OCR 未验证 |
| A16 清理删除 | 通过;归属、到期、手动清理、必要摘录审计 | 待指定环境定时任务核对 |
| A17 无结果/失败 | 通过;异常矩阵与可执行提示 | 真实错误字段未验证 |
| A18 幂等恢复 | 通过;SSE 测试及实际进程重启,无重复请求 | MySQL/反向代理断线未验证 |
| A19 会话快照 | 通过;CRUD、浏览器刷新、跨两页整批 QA | 指定环境未验证 |
| A20 评分 | 通过;非法权重、精确舍入、档案版本及高分样本 | 真实样本不硬造高分 |
## 4. 交付与尚未完成项
- 实现位于后端 `rz-GB` 与相邻前端 `rz-GB-web`;新增 Flyway V7,未修改 V1–V6 的已发布结构。代码按要求补充中文业务注释。
- 构建、部署、接口、事件/幂等/金额/日期单位和确认流程见 [接口契约与运行交付](接口契约与运行交付.md)。三个 Skill 锁定版本及本地工具映射也在该文档。
- 前端构建仍有主 JS 超过 500 kB 的提示,构建成功;本轮未扩展到全站拆包。
- 单实例任务执行器与内存会话沿用现有设计;多实例调度、自动通知、注册、标书生成和生产高可用不在本期。
- 仍需提供指定测试环境 MySQL 连接、admin 初始密码、知了和 DeepSeek 凭证/余额及代表性真实标书,再按四天计划 6.2 演示脚本和 D1–D3 的真实服务清单执行。届时记录实际模型 ID、工具字段、积分、token、Search/Fetch、扫描件识别及数据库重启结果。
- 未做生产部署,也没有提交、推送、创建 PR 或改动真实业务数据。真实凭证不足属于未验证条件,不等于已通过的交付承诺。
# 如昼商机助手:GitHub 相似项目调研
调研日期:2026-10-26(北京时间)。
## 1. 结论
有相似项目,但本轮检索尚未发现同时覆盖“水行业商机召回、三个专用 Skill、企业情报、具体项目研判、人工跟进八状态”的现成完整替代品。已有仓库分别覆盖招标解读、机会监控、企业信息补全、证据校验和 Agent 编排。
建议继续现有 Java/React 项目,按模块借鉴。优先阅读 Spring AI Alibaba DeepResearch、TenderGraph 和中文招标文件解析系统;BidMaster-Pro 适合作功能对照,但不宜仅凭 README 就整体引入。
这是一份公开资料与定向源码调研,不是部署验收、安全审计或许可证法律意见。本文中的“值得参考”“不宜直接引入”是结合本项目范围作出的工程判断。
## 2. 检索与核实方法
- 以 GitHub 为主,补充检索 Gitee;查询招投标 Agent、商机监控、采购情报、企业调研、销售线索与 Java 研究 Agent。
- 下表八个项目均查看仓库页面/README,并通过 GitHub 公共 API 获取许可证识别、Star、归档状态和默认分支最新提交。
- 定向读取九个实现/依赖文件:各项目一个关键文件,DeepResearch 另读 `pom.xml`。未安装、执行第三方代码,未进行真实模型和数据源调用。
- Star 是调研当时的快照;最近提交日期取默认分支最新提交的 committer 时间,转换为北京时间。不是搜索引擎抓取日期,也不是仓库 `updated_at` 或其他分支 push 时间。
- 下表八个仓库在查询时均未归档,但“不归档”“有测试目录”“Star 多”均不能证明生产可用。
## 3. 候选项目对比
“关联度”指与本项目某个模块的接近程度,不是完整覆盖率。
| 项目 | 关联度与方向 | 技术形态 | Star | 默认分支最新提交(北京时间) | 许可核实 |
| --- | --- | --- | ---: | --- | --- |
| [BidMaster-Pro](https://github.com/guangshu100/BidMaster-Pro) | 高:中文招投标 Agent、解读、Skill、商机监控 | Python/FastAPI;React/Electron 客户端 | 409 | [2026-09-03](https://github.com/guangshu100/BidMaster-Pro/commit/cc89d9093651e3410f68384f926ceef672b76534) | LICENSE 为 AGPL-3.0;README 却写 MIT,存在冲突 |
| [guiyang-tender-monitor-skill](https://github.com/FightingThrones/guiyang-tender-monitor-skill) | 高:中小企业商机发现、适合度、日报 | Python 脚本+Skill+来源目录 | 2 | [2026-07-16](https://github.com/FightingThrones/guiyang-tender-monitor-skill/commit/072d054b509fc67a726bd2c8fe14fcd367f7b70a) | CC BY-NC 4.0;README 明示商业用途需另行授权 |
| [招标文件智能解析系统](https://github.com/sanwudazhiyuan/-bid-analysis) | 高:中文资格、评分、风险、原文定位 | Python 解析/服务+Web 前端 | 35 | [2026-04-23](https://github.com/sanwudazhiyuan/-bid-analysis/commit/08dc9366e408d335dca7d9e46974e46fe8d60f65) | Apache-2.0 |
| [TenderGraph](https://github.com/Amawta-labs/tendergraph) | 高:投标工作台、证据、人工确认 | TypeScript/Next.js,Codex 相关运行链路 | 0 | [2026-07-21](https://github.com/Amawta-labs/tendergraph/commit/771537b070004f91b20b26c34e460655c9dd03f4) | 代码 Apache-2.0;仓库声明合成基准数据另用 CC BY 4.0 |
| [TenderAI](https://github.com/teja05-45/TenderAI) | 中高:公告文件提取、OCR、引用问答 | FastAPI、LangGraph、ChromaDB、Streamlit | 0 | [2026-07-23](https://github.com/teja05-45/TenderAI/commit/e82b0969d90df3e87fe4aa0f267e9b0ede5620a7) | MIT |
| [Fire Enrich](https://github.com/firecrawl/fire-enrich) | 中高:企业情报、资料补全、来源展示 | TypeScript/Next.js;Firecrawl+OpenAI | 1,293 | [2025-10-08](https://github.com/firecrawl/fire-enrich/commit/94e061dc5bab94e5838cceb8b3d5e6af329d2d50) | MIT;不代表其外部服务和全部依赖同许可 |
| [Spring AI Alibaba DeepResearch](https://github.com/spring-ai-alibaba/deepresearch) | 业务中、技术高:规划、工具、流式、人工反馈 | Java/Spring AI Alibaba Graph;Vue3 | 373 | [2026-03-02](https://github.com/spring-ai-alibaba/deepresearch/commit/7f009adf56fadacdc78a02c4967aebe784918b11) | Apache-2.0 |
| [mtender-mcp-server](https://github.com/nalyk/mtender-mcp-server) | 中:采购搜索、买方/供应商统计、阶段与文档 | TypeScript/Node.js/MCP | 0 | [2026-05-06](https://github.com/nalyk/mtender-mcp-server/commit/9512496f85fdcb69733770f2423a4bea7079a8ff) | ISC |
许可证列结合仓库页面、README、GitHub API 与实际文件核对。其中监控 Skill 的 API 识别结果为 `NOASSERTION`,其 README/LICENSE 明确使用 CC BY-NC 4.0,不能把未自动识别当作无约束许可。
## 4. 逐项可借鉴内容与限制
### 4.1 BidMaster-Pro:功能覆盖较广,但不能直接当完整底座
README 描述招标解读、标书生成、检查、OCR、公司知识库和商机资讯。与我们的单项目分析和 Skill 组织形式接近,但其重心还包括本期不做的标书生成与排版。[仓库说明](https://github.com/guangshu100/BidMaster-Pro)
抽查发现 `services/news/fetchers.py` 实现 RSS 等获取路径,但其中 HTML 适配器交由其他流程,浏览器适配器是空实现;这不证明整个项目没有其他抓取能力,但不足以据此认为已具备通用浏览器采集。[抽查文件](https://github.com/guangshu100/BidMaster-Pro/blob/cc89d9093651e3410f68384f926ceef672b76534/services/news/fetchers.py#L250)
README 的 MIT 描述与实际 AGPL-3.0 LICENSE 不一致。建议作为功能/界面对照,代码复用前先明确具体版本和授权,不能按 README 的 MIT 一句直接采用。[实际 LICENSE](https://github.com/guangshu100/BidMaster-Pro/blob/cc89d9093651e3410f68384f926ceef672b76534/LICENSE)
### 4.2 全国招投标机会监控 Skill:最贴近“每天找几个值得跟的项目”
它面向中小软件和集成企业,提供来源池、机会评分、摘要与日报;值得参考报告字段与来源管理。本项目仍以知了 API 为主,不需要因此回到自建全网爬虫。[仓库说明](https://github.com/FightingThrones/guiyang-tender-monitor-skill)
源码中存在 `score >= 8` 才保留候选的逻辑;若照搬会与我们“偏好仅用于排序”的规则冲突。其软件行业关键词与判断规则也不能直接当水行业评分。[筛选实现](https://github.com/FightingThrones/guiyang-tender-monitor-skill/blob/072d054b509fc67a726bd2c8fe14fcd367f7b70a/guiyang-tender-monitor/scripts/tender_monitor.py#L560)
作者明确商业用途需要另行授权,因此先作为产品参考,不纳入默认代码复用清单。[许可说明](https://github.com/FightingThrones/guiyang-tender-monitor-skill#许可证)
### 4.3 中文招标文件智能解析系统:最值得参考文档提取
README 覆盖 DOC/DOCX/PDF 解读、资格和评分条件、风险提示与原文定位。源码 `parse_docx` 按 XML body 的出现顺序交错读取段落和表格,适合借鉴到我们对招标文件条件、金额和上下文的提取中。[解析实现](https://github.com/sanwudazhiyuan/-bid-analysis/blob/08dc9366e408d335dca7d9e46974e46fe8d60f65/src/parser/docx_parser.py#L325)
它偏标书解读与审查,不能替代商机召回、企业情报和人工跟进。README 的速度与准确性宣传未由本轮复现;许可为 Apache-2.0,仍需对拟复用文件及依赖逐项检查。[仓库与许可](https://github.com/sanwudazhiyuan/-bid-analysis)
### 4.4 TenderGraph:最值得参考“结论必须有证据”
提供投标工作台、来源版本、要求变更和人工审批;README 明确机会收件箱使用合成数据,不宣称通用实时商机发现,所以不能当真实公告数据服务。[项目说明与范围](https://github.com/Amawta-labs/tendergraph)
`gates.ts` 在模型之外校验结构、claim/evidence ID、来源范围、可用状态和快照哈希。适合借鉴“后端拒绝没有证据的结论”的方法,不需要整体搬入其审批体系或模型运行方式。[校验实现](https://github.com/Amawta-labs/tendergraph/blob/771537b070004f91b20b26c34e460655c9dd03f4/src/lib/harness/gates.ts#L23)
该仓库是 Build Week 版本,Star 和使用样本较少;本轮未验证部署、运行成本及生产稳定性。
### 4.5 TenderAI:适合参考文件处理状态与引用问答
README 描述 PDF/OCR、结构化元数据、RAG 问答、项目对比和报告。实际 LangGraph 文件有解析、OCR、元数据、embedding、finalize 节点,并在失败时转到收尾节点,能参考其处理链路。[工作流源码](https://github.com/teja05-45/TenderAI/blob/e82b0969d90df3e87fe4aa0f267e9b0ede5620a7/app/agents/graph.py#L33)
仓库页面仅有 3 次提交,且采用 Python/Streamlit,未见与我们相同的获客与跟进产品闭环。适合作流程参考,不能据此承诺中文全部文件格式或现有 React/Java 能直接复用。[仓库](https://github.com/teja05-45/TenderAI)
### 4.6 Fire Enrich:适合参考企业情报按需补全
从邮箱/域名推导企业,再补全企业画像等字段,带来源上下文。源码按所需字段选择阶段,并把已发现数据传给后续阶段,可借鉴为“只补查用户需要的信息”。[编排实现](https://github.com/firecrawl/fire-enrich/blob/94e061dc5bab94e5838cceb8b3d5e6af329d2d50/lib/agent-architecture/orchestrator.ts#L19)
它不是中国企业同名确认、历史中标关系或真实竞对数据服务;其接口依赖 Firecrawl/OpenAI,迁到知了/DeepSeek 需要适配。默认分支一年多未有新提交,不能仅因 1,293 Star 就判定持续活跃。[仓库](https://github.com/firecrawl/fire-enrich)
### 4.7 Spring AI Alibaba DeepResearch:与当前后端最接近
支持研究计划、在线搜索、人工反馈和流式输出。实际 `ChatController` 存在 `/stream`、`/stop`、`/resume` 路径,适合参考任务执行和用户确认交互。[控制器](https://github.com/spring-ai-alibaba/deepresearch/blob/7f009adf56fadacdc78a02c4967aebe784918b11/src/main/java/com/alibaba/cloud/ai/example/deepresearch/controller/ChatController.java#L105)
但核对到其依赖为 Java 17、Spring Boot 3.4.8、Spring AI Alibaba 1.0.0.4;我们当前为 Java 21、Boot 4.1.2,前端也为 React 而不是 Vue。不能把“同为 Spring”当成复制即可运行的兼容保证。[依赖文件](https://github.com/spring-ai-alibaba/deepresearch/blob/7f009adf56fadacdc78a02c4967aebe784918b11/pom.xml#L12)
建议借鉴有限步骤、人工反馈与 SSE 接口形态,不整套引入其多 Agent、代码执行和混合 RAG 基础设施。
### 4.8 mtender-mcp-server:数据工具边界参考
面向摩尔多瓦公开采购,README 提供搜索、采购方/供应商聚合、公告阶段、文档获取和 OCR 回退等工具。源码将搜索注册成独立 MCP 工具,可参考查询参数、分页与资源链接的边界。[搜索工具](https://github.com/nalyk/mtender-mcp-server/blob/9512496f85fdcb69733770f2423a4bea7079a8ff/src/tools/search.ts)
它不提供中国水行业公告或知了数据,国家数据模型也不同。只作工具接口和采购生命周期设计参考,不新增为第四个业务 Skill。[仓库](https://github.com/nalyk/mtender-mcp-server)
## 5. 与本项目的对应关系
下表为本轮工程判断;“参考”不表示已接入、适配或测得性能收益。
| 本项目需求 | 优先参考 | 采纳尺度 |
| --- | --- | --- |
| 主 Agent 路由、计划、补问 | DeepResearch | 参考人工中断/继续的接口思路,保留三个受控工作流 |
| 真实调用轨迹与 SSE | DeepResearch | 业务事件与模型报告分开;仍需自行实现持久化事件、幂等和收费去重 |
| 水行业商机召回 | 已提供的 tender-search+知了 API | 本轮仓库不能替代已确认数据源;监控 Skill 仅借鉴来源与报告设计 |
| 偏好不漏候选 | 本项目自行实现 | 不复制监控脚本的分数硬过滤或软件行业规则 |
| 中文招标文件提取 | 中文招标文件解析系统、TenderAI | 参考段落/表格顺序、失败收尾和证据定位,不为此整体改成 Python |
| 企业情报按需查询 | Fire Enrich | 参考阶段化和共享上下文,主体确认/中标客户关系仍使用既定 Skill |
| 事实/推断、引用校验 | TenderGraph | 先实现证据 ID 存在性、来源范围、必要数字校验;不扩展完整审批系统 |
| 八状态、标签、档案和检索快照 | 现有前后端继续实现 | 本轮没有找到可直接替换该业务闭环的模块 |
| 费用审计与预算暂停 | 本项目自行实现 | 不能把流式输出或 Agent 日志等同于真实积分/token 账本 |
## 6. 对四天计划的影响
本轮没有证据支持“换成某仓库可以立即缩短到一天上线”。引入不同语言后端、不同前端、向量库和多 Agent 平台,会增加迁移与运维工作。
建议保持原四天计划,只补充以下设计参考:
1. **D1:**参考 DeepResearch 的执行/人工反馈接口形态,仍以现有统一任务对象和白名单工具客户端为准;单独验证 Boot 版本兼容,不直接导入旧依赖。
2. **D2:**把“偏好变化候选集不变”作为必须自动验证的规则;引入第三方评分前先检查是否存在阈值删除。
3. **D3:**参考中文文档解析的结构顺序与 TenderGraph 的证据准入;企业情报只执行被请求的步骤。
4. **D4:**增加引用不存在、失效证据、阶段重复公告、文件表格错配及重复收费的验收,而不是根据开源项目宣传免验收。
代码复用若发生,应固定具体提交、记录来源和许可,先抽取最小模块验证。此调研没有复制任何第三方代码进业务项目,也没有修改原开发计划或业务代码。
## 7. 补充线索与未验证部分
检索还发现 [DuoLa-BidAgent](https://github.com/duolaAmengweb3/DuoLa-BidAgent)(本地企业资料/公开招投标/项目工作区)、[bid-agent](https://github.com/yellowfacehc/bid-agent)(招标信息获取)和 [ai-lead-radar](https://github.com/ck830820/ai-lead-radar)(招采线索监测)。本轮只阅读搜索返回的项目说明,未核实其完整源码、许可和维护数据,不纳入上述优先复用建议。
Gitee 检索返回的候选多为采购管理、监管评标或二次转载,未进一步验证为与本项目相同的销售侧商机 Agent。本轮结论是有限范围检索结果,不是对 GitHub/Gitee 全站项目的穷尽证明。
尚未验证:第三方完整部署、真实中国公告召回率、中文抽取准确率、模型实际消耗、依赖安全性、商用授权适用性。上述指标不能从 README、Star 或少量代码抽查直接推断。
# 如昼商机助手开发文档
更新时间:2026-10-28(北京时间)。
本目录记录结合现有前后端和三个专用 Skill 制定的需求与四天开发计划。已完成 D1–D4 代码实现与本地测试,真实 MySQL、知了与 DeepSeek 的验收待补充环境配置;具体结果见 D1–D4 记录。
## 阅读顺序
1. [需求分析与 Skill 集成方案](./需求分析与Skill集成方案.md):已确认范围、现状差距、Skill 能力与冲突、场景路由、召回排序、任务事件、证据成本、文件与数据设计。
2. [四天开发计划](./四天开发计划.md):开工依赖、D1–D4 交付与验收、接口草案、二十项验收矩阵、测试和风险处理。
3. [D1 实施与验收](./D1实施与验收.md):当前代码范围、接口、环境变量、保护值、测试结果与真实依赖待验证项。
4. [D2 实施与验收](./D2实施与验收.md):检索获客、市场聚合、方案快照、关注事务、架构参考和 39 项自动测试记录。
5. [D3 实施与验收](./D3实施与验收.md):企业/项目工作流、文件、主体选择与预算恢复。
6. [D4 实施与验收](./D4实施与验收.md):历史会话与快照问答、清理、102 项测试、格式/异常矩阵及逐项真实验收状态。
7. [接口契约与运行交付](./接口契约与运行交付.md):V1–V7、构建部署、事件/幂等、金额日期单位及工具映射。
## 本轮确认
D3 详细结果见 [D3 实施与验收](./D3实施与验收.md):企业/项目工作流、文件格式矩阵、候选与预算恢复、79 项测试和浏览器本地联调记录。
- 后端为 `rz-GB`,前端为相邻的 `rz-GB-web`;后续由 AI 实现并完成联调。
- 知了标讯 API 是本期主要数据源;飞书清单待补,不自建全网站爬虫。
- 一个主 Agent 编排 tender-search 2.3.0、company-intel 1.0.2、bid-decision 1.0.4;只承诺这三个 Skill 的能力。
- 真实 DeepSeek 模型与公开资料检索;后端配置凭证,admin 预设账号。
- 保留原有检索、匹配度、方案、跟进、档案、会话,新增调研四入口与获客流程。
- 原检索按发布时间排列;获客报告按相关度/偏好排序,地域和金额偏好不默认过滤候选。
- 获客初始报告只真实调用招投标检索;用户明确选择后才做企业情报或投标决策深挖。
- 文件只用于投标项目解析;公司档案手填,关闭原 AI 文件导入。
- 格式覆盖文本、PDF(含扫描件)、Word、Excel/CSV、PowerPoint、HTML 与指定图片格式;详细清单和限制见需求文档。
- 来源、数据缺口、实际调用与成本可审计;状态由人手动修改。
## 更新原则
产品需求和用户最新确认优先于 Skill 目录内的通用引导。Skill 说明不代表已完成注册、付费查询、联网验证或部署;接口草案也不代表后端已有接口。
实施过程中每日更新完成情况与实际验收记录。外部依赖未验证、工具失败或仅用模拟样例的部分必须如实标记,不能用演示动画替代真实执行证据。
This diff is collapsed.
# 四天计划完成度核查
核查日期:2026-10-29(北京时间)。范围:`rz-GB`、相邻 `rz-GB-web`、四天开发计划、需求分析和 D1–D4 验收记录。本轮只新增核查报告,未修改业务代码、配置或数据库,未使用真实供应商密钥。
## 结论
四天计划的主要业务已有实现,本地自动测试和构建通过;**不能判定四天计划全部验收完成,也不能判定现在能直接运行完整真实业务**。当前最先需要解决的是数据库及首次管理员配置,再完成知了、DeepSeek 和指定环境的真实联调。另有若干功能与原计划存在差距,不能统一归因为“只差 API Key”。
“已实现”表示代码和本地测试证据存在;“真实待验收”表示尚未证明真实数据库、供应商响应、模型质量及实际部署满足要求。没有用文档中的完成声明替代本次代码检查和测试。
## 四天逐项核对
| 计划 | 本轮确认存在的实现 | 尚未完成的验收或功能 |
| --- | --- | --- |
| D1:基础工程和真实依赖 | Java 21 工程、Flyway V1–V7、admin 初始化、会话/CSRF、手填档案及版本、统一任务、幂等、事件/SSE、工具白名单和调用账本 | MySQL 初始化与重启持久化;真实知了余额/检索/详情/企业字段;真实模型文本/JSON/流、Search/Fetch、视觉及实际计费记录 |
| D2:检索、获客和跟进 | 分页与去重、硬条件/偏好分离、普通检索与获客两种排序、范围统计、规则摘录与四维匹配、方案快照、关注八状态、标签/备注/历史事务及版本 | 真实数据字段、金额单位、分页总数、召回效果及积分核对;真实网页从检索到跟进的完整演示 |
| D3:企业、项目和文件 | 四入口、主体选择、单/双企业、采购方历史、项目快/完整模式、来源与引用检查、局部补查、文件解析/视觉调用、预算暂停、父子任务 | 同名真实企业和双公司报告核验;真实标题/链接/文件三路研判;真实扫描件/复杂标书质量;自然语言任务路由尚缺 |
| D4:恢复和交付 | 历史会话 CRUD、固定快照单项目/整批问答、到期/手动文件清理、删除审计、取消/重启中断、SSE 重放、用量读取、代表性格式和异常测试、运行文档 | 指定环境 MySQL/SSE 代理与重启验收;供应商真实账单;真实文件矩阵;超大问答分段汇总、审计保留期执行和文档一致性仍有差距 |
列表摘要目前是已有正文的规则摘录,并非逐公告模型总结;代码和界面已说明这一口径。无正文会提示缺口。这不应被宣传为读完标书后的完整 AI 研判。
## 直接影响启动和真实业务的缺项
### 1. 数据库和首次管理员配置
本轮检查时,后端目录只有 `.env.example`,没有 `.env`;当前工具进程未设置 `DB_URL`、`DB_USERNAME`、`DB_PASSWORD`、`ADMIN_INITIAL_PASSWORD`、`ZLBX_API_KEY`、`DEEPSEEK_API_KEY`。未读取其他项目的凭证,也没有据此断言用户的其他主机或 IDE 不存在配置。
本机 3306、8240、3000 未观察到监听进程;这只描述本轮检查时的本机状态,不排除远端数据库或非默认端口。
要先运行登录、档案和本地业务接口,需要:
1. 可连接的 MySQL 8 数据库,建议空库 `rz_gb`、字符集 `utf8mb4`。
2. 应用账号具有该库迁移建表、索引和读写权限。
3. 配置数据库三项变量;首次设置管理员密码,至少 12 字符、UTF-8 最多 72 字节。
4. 显式导出环境变量再启动;Spring Boot 不会自动读取 `.env`。
5. 实际执行 Flyway V1–V7,登录并保存档案,重启后再次读取,证明 MySQL 持久化有效。
证据:[application.yaml](../src/main/resources/application.yaml:14)、[SecurityConfig.java](../src/main/java/com/example/rzgb/auth/SecurityConfig.java:34)、[运行说明](../README.md)。本机已具备 Java 21、Maven、Node/npm,不需要把这些再次列为未安装的软件。
### 2. 知了与 DeepSeek 真实服务
完整检索、获客、企业情报、联网研究、模型问答和扫描件解析,还需要后端 `ZLBX_API_KEY`、`DEEPSEEK_API_KEY`,并确认账户余额、接口使用权限和部署主机网络可达。
不能只补密钥就宣布完成。必须用少量请求核对真实响应与当前适配契约:`data.items`、企业/聚合字段、`meta.cost_units`、实际模型标识、token usage;然后再跑完整工作流。如果字段不同,需要修改适配与对应测试。
本轮查阅的知了官方 API 概述与 DeepSeek Search/Fetch、视觉文档支持代码采用的基础路径、认证方式及能力方向,未发现足以直接判定这些能力不存在的依据;但这不能证明当前账号权限、具体工具参数或真实效果已经通过。
- [知了官方 API 概述](https://ai.zhiliaobiaoxun.com/docs/api)
- [DeepSeek Search](https://api-docs.deepseek.com/api/search/)
- [DeepSeek Fetch](https://api-docs.deepseek.com/api/fetch/)
- [DeepSeek Vision](https://api-docs.deepseek.com/guides/vision/)
### 3. 指定环境的启动和代理
本地开发需实际启动后端 8240 和前端 3000。部署构建产物时需配置静态站点、路由回退及同源 `/api` 反向代理;SSE 关闭代理缓冲并允许长连接。HTTPS 部署启用安全会话 Cookie。
当前按单实例设计运行,内存登录会话在重启后失效,需要重新登录;这与业务数据是否持久化是两回事。多实例调度和生产高可用不在本期,不是本地单实例启动的前置条件。
操作见 [接口契约与运行交付](接口契约与运行交付.md)。
## 除环境以外,确认存在的计划差距
| 项目 | 原计划/需求 | 当前实现与影响 | 建议 |
| --- | --- | --- | --- |
| 自然语言统一任务入口 | 自然语言与场景表单统一进入意图、参数确认和工作流 | 前端根据所选场景直接指定 operation/workflow;后端接收显式类型,没有自然语言意图解析及条件提取。输入完整企业名/标题可用,但一句“找浙江近三个月的水务项目”不会自动转成对应查询 | 若保留原需求,补意图路由、结构化参数预览/确认和歧义补问;在此之前明确只支持场景表单 |
| 超大整批问答 | 超上下文时分段汇总并展示覆盖范围 | 已冻结全部候选,但超过 600,000 字符时返回 `QA_CONTEXT_LIMIT`,要求改单项目;没有分段汇总。普通大小批次仍可用 | 增加分段与最终汇总,保留各段覆盖对象、引用及费用;或明确收窄需求 |
| 手动导入项目后关注 | 计划草案含 URL/投标文件解析预览,确认后关注 | 已有标题/URL/文件研判入口,但没有独立 `/projects/import` 及手动导入后进入关注的完整链路;关注依赖已经存在的 project。交付文档承认未提供该接口 | API 名称可以调整,但若保留该业务需求,需补解析预览、确认落库及关注闭环 |
| 审计数据保留期 | 需求建议审计元数据 180 天,可配置 | `auditRetentionDays` 可配置且对外显示,但代码未消费该值执行归档/删除;原件/全文/派生图片清理已实现。不能把“配置为 180 天”理解为届时自动清理 | 明确保留范围和引用关系后补归档/清理,或说明目前长期保留 |
| 文档及检查收尾 | 交付说明应与最终功能一致 | 前端 README 开头仍说 D3 是原型、按钮不发深查,末尾又描述 D3/D4 已接入;全量 lint 也未通过 | 更新过期说明,处理遗留 lint;不阻塞已通过的构建,但不能称全部工程检查通过 |
定位:[ResearchPage.tsx](/Users/ruzhoukeji/rz-GB-web/src/pages/ResearchPage.tsx:70)、[TaskRequest.java](../src/main/java/com/example/rzgb/task/TaskRequest.java:10)、[SnapshotQa.java](../src/main/java/com/example/rzgb/conversation/SnapshotQa.java:58)、[文件清理](../src/main/java/com/example/rzgb/files/BidFileService.java:76)、[AppProperties.java](../src/main/java/com/example/rzgb/config/AppProperties.java:18)。
已额外确认:深挖串行控制不是缺项。`TaskService.validateParent` 已在父任务锁内检查同批最多五个子任务、已有未结束子任务则拒绝新建。前端当前逐个进入对象,没有批量勾选界面;本轮不把批量界面当作串行能力缺失。
## 本轮实际执行的检查
| 检查 | 2026-10-29 本轮结果 |
| --- | --- |
| Java 21,`mvn -o -q -Djava.awt.headless=true verify` | 通过;102 项,0 失败、0 错误、0 跳过;后端 JAR 存在 |
| 后端测试范围 | 基础 29、排序 5、摘录匹配 5、研究工作流 17、文件解析 30、D4 集成 16 |
| `npm run build` | TypeScript 与 Vite 通过,生成 dist;主 JS 554.06 kB,存在大于 500 kB 的体积提示 |
| `npm run lint` | 未通过,8 个错误,集中在既有 UI 组件导出规则及 sidebar 渲染期间 Math.random |
| 两仓库 `git diff --check` | 通过;没有因此修改或清理已有未提交代码 |
| 当前配置与默认端口 | 当前进程缺上述数据库和供应商变量;后端无 .env;默认端口未见监听 |
| MySQL、真实供应商、真实标书和部署代理 | 未执行,不记为通过 |
| 浏览器完整业务演示 | 本轮未重跑;D3/D4 文档保留的是此前 H2 + 本机模拟 HTTP 的浏览器记录 |
首次后端测试因沙箱不允许监听本机临时 HTTP 端口而失败;允许测试在沙箱外使用本机端口后,同一命令全部通过。测试使用 H2 和本地模拟服务,没有外部收费请求。日志:`/tmp/rzgb-review-maven-approved.log`、`/tmp/rzgb-review-web-build.log`、`/tmp/rzgb-review-web-lint.log`。
## 建议执行顺序与通过标准
1. **先让基础服务启动**:配置 MySQL/管理员、运行迁移,验证健康检查、登录、档案读写及重启持久化。
2. **再验证真实依赖**:少量核对余额、公告检索/详情、企业搜索/画像、文本/JSON/流、Search/Fetch、视觉;对照响应修正适配。
3. **跑完整业务闭环**:检索→获客→关注状态/标签→企业及双公司→项目快/完整研判→标题/URL/真实文件→会话与整批提问,核对来源和账单。
4. **补齐保留的计划差距**:自然语言、超大问答分段、手动项目关注、审计保留期;更新交付文档和 lint。
5. **指定环境验收**:代理下 SSE 断线恢复、重复提交、预算暂停/取消、进程重启、原件过期/删除与复杂真实文件。每项有脱敏证据后再更新 A01–A20 的真实验收列。
当前可以确认“核心代码和本地回归具备”,不能确认“真实业务已经正常运行”或“四天计划 100% 完成”。
# 接口契约与运行交付
适用版本: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)中的“真实未验证”保留原状态。当前不包含生产部署、生产多实例验证或全量复杂标书识别承诺。
This diff is collapsed.
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment