 lzf_0626
|
404f8f6aa5
|
固化接口体检脚本，并交付双击即用的启动 bat
## tools/portal_api_check.py（新）
把 2026-09-13 那轮"照着接口内容把前端测一遍"的验证固化成可重复跑的脚本。
当时靠这套验证查出 6 个真缺陷，但它们只存在于一次会话里，下次改动没人会重跑：
- `K002`/`K003` 是裸信封，前端按 `payload.data` 取 -> 知识库页显示"已入库 0 块 / 为空"
- 委托/成交详情页照着建表字段写，而接口返回视图没带那些列 -> 5 行永远显示 `--`
- 配置项/路由规则的 `PUT` 要 `If-Match`，却没有端点能返回该 digest -> 首次编辑必然 409
- 回复模板 `scene` 只校验长度不校验枚举 -> 非法值撞数据库 CHECK、冒成 500
- 路由规则表单固定 `max_attempts=2` 且 `fallbacks` 为空 -> 后端必然 422
- 模型端点手填 ID -> 未激活的 ID 直接 422
与 `e2e_smoke_test.py` 分工互补：后者测**业务链路通不通**，本脚本测**接口契约对不对**
（状态码、信封形状、字段名与前端期望是否一致）。
三档，默认只跑第一档：
- 默认只读 41 项（不动数据）
- `--write` 加测写操作：配置项 ETag 链路、`max_attempts` 越界、知识库上传+失效、
回复模板非法枚举、敏感词、推广物料全链路
- `--dangerous` 再加测会改生效配置的操作（激活配置版本会整版本替换，默认不跑，
脚本内注明了恢复办法）
实测：只读 39/39、写入档 54/54 全绿。
## 桌面一键启动（双击即用）
桌面 `启动金融Agent平台.bat` + 仓库 `启动平台.bat`，由
`tools/make_launcher_bat.py` 生成，只负责"双击"这一层，启动逻辑复用 `start.ps1`
（不重复实现，避免两边漂移）。参数可透传：`-Port 8100` / `-NoBrowser` / `-SkipPriceSync`。
不要手写这个 bat：必须同时满足 **GBK 编码 + CRLF 换行 + 无 BOM**。生成器自己
读回来校验这三条。踩过的坑：用 `write_bytes` 直接落盘时没转 CRLF，cmd 对 LF-only
批处理会行边界错乱，把 `echo` 的说明文字当命令执行（实测报
`AT 命令已弃用`、`']' 不是内部或外部命令`）。
## start.ps1 的三处修复
1. **解释器探测选错环境（真机双击失败的主因）**
原先只验证 `--version` 成功就选中，结果挑到一个 Python 3.10 环境：
本项目用了 `datetime.UTC`（3.11+）且依赖 `asyncmy`，启动当场 ImportError ——
而报错发生在**行情刷新**那一步，看起来像"行情源坏了"。
现在实测两项：**版本 >= 3.11** + `import fastapi, sqlalchemy, asyncmy, pydantic` 通过，
并在跳过时打印具体原因。
2. **`Select-Object -First 1` 掐断 native 管道**
`& $exe -c ... 2>&1 | Select-Object -First 1` 拿到首个对象后停掉上游管道，
等于把进程掐了、`$LASTEXITCODE` 变脏，于是**每个候选都被误判成"无法执行"**
（连装好的 jr_py313 也被跳过）。改为先整体接住输出、再在结果上取行。
3. **幂等 + 就绪探测 + Docker 自动拉起**
重复双击不再起第二个 API/Worker（API 按端口、Worker 按进程判断）；
起完等 `/internal/health/ready` 真正应答才报成功；Milvus 不可达时尝试拉起
Docker Desktop 并最多等 60 秒（它不常驻，是"知识检索静默降级"最常见的原因）。
## 实测
- `启动平台.bat` 重复执行：解释器正确选中 jr_py313、依赖检查全 OK、行情已刷新、
两个服务识别为已在跑并跳过、就绪探测 1 秒
- `-Port 8199` 冷启动：新起 API 窗口，8199 的 `/internal/health/ready` 与 `/portal/` 均 200，
测试后已清理
- `ruff check app tests tools alembic hq.py` -> All checks passed
- `start.ps1` 语法解析通过（BOM 已保留）、bat 三项编码约束校验通过
文档同步：`AGENTS.md`（启动方式、bat 生成器、解释器探测两个坑）、
`docs/44-演示流程.md` §0.3/§0.4（双击启动、两条自检线的分工）。
|
2026-09-14 01:59:46 +08:00 |
|