API 边界与导航
本页说明系统对外入口的边界，以及前端、浏览器插件、代理和后端之间的职责分工。具体接口路径仍以 API 参考 为准。
调用方
当前调用后端的主体有六类：
- React 前端，通过 frontend/src/api/client.ts 访问后端。
- 浏览器插件，通过桥接脚本把外部购物车批次送到导入页，再由前端调用后端。
- Agent skill，通过 CLI 命令面访问后端 API。
- CLI，通过
python -m lsm_cli访问后端 API。 - MCP，通过
lsm_mcp调用 CLI 子进程，不直接访问数据库。 - 企业微信智能机器人和微信客服，通过 MCP、CLI 与后端 API 完成查询和确认后的写操作。
- 调试脚本或运维工具，通过 Bearer Token 或开发环境文档页访问 FastAPI。
从系统边界上看，业务后端只有一个，即 FastAPI。
入口边界
| 路径前缀 | 归属层 | 说明 |
|---|---|---|
/api/* | FastAPI 业务接口 | 主业务入口 |
/api/events | FastAPI SSE | 实时推送入口 |
/static/* | FastAPI 静态资源 | 上传图片、模板和导出资源 |
/health | FastAPI 健康检查 | 部署探活 |
/docs /redoc /openapi.json | FastAPI 文档 | 仅非生产运行模式默认开放 |
/cart-import | 前后端桥接入口 | 后端重定向到前端导入页 |
鉴权边界
- 浏览器页面默认使用 HttpOnly Cookie。
- 脚本和调试工具可以使用
Authorization: Bearer。 - 管理员接口额外依赖
require_admin。 GET /api/events同样要求登录。
涉及 Cookie 的写请求在安全运行模式下还会经过来源校验，因此新域名、反向代理或跨域部署都要同步检查 CORS_ORIGINS。
前端边界
前端通过统一 API 基址访问后端，禁止拼接服务内部地址。前后端边界包含以下约束：
- 以 HTTP 快照为主，SSE 增量更新为辅。
- 表格状态、列宽和展开状态保存在浏览器本地。
- 实验步骤查库存的临时结果保存在用户绑定的
sessionStorage中，并按有效期清理。 - 认证状态和 UI 状态由 Zustand 管理，不直接回写后端。
- LLM 与 PubChem 调用由后端统一处理，前端不持有服务端凭据；前端 Sentry 使用独立的构建时公开配置。
页面入口、状态逻辑和工具函数分别对应 应用骨架、前端 Hooks 和 前端 Lib 工具箱。
浏览器插件边界
浏览器插件与后端通过导入页桥接：
- 插件从外部采购平台采集数据。
- 插件把批次写入
chrome.storage.local。 import-bridge.js在/cart-import页面把批次同步到页面环境。- 前端导入页逐条调用标准试剂订单或耗材订单创建接口。
/api/cart-sync用于匹配分析，导入落库统一走标准订单创建接口。
浏览器插件定位为外部采集器，系统前端仍由 React 应用承担。
CLI、MCP 与机器人边界
Agent skill 和脚本应统一走 lsm_cli/。lsm_cli/ 只暴露明确列入 README 的命令。lsm_mcp/ 在 HTTP 层提供 MCP 工具，但工具实现仍调用 CLI 子进程，并继承 CLI 的命令白名单和退出码契约。
企业微信智能机器人和微信客服入口位于 robot/。它们不直接访问数据库，也不生成任意命令；查询和写操作都要经过 MCP、CLI 和后端 API。借用和归还等写操作必须在候选明确后等待用户确认。
外部服务边界
- 实验步骤查库存通过后端访问 OpenAI 兼容 LLM 和 PubChem，接口参数与结果均由服务层校验。
- LLM 配置为空时，实验步骤提取与 CAS 解析接口返回服务不可用，不降级为未经确认的本地推断。
- Sentry 的 DSN 配置为空时保持停用；前端 source map 仅在构建环境提供上传凭据时发布。
- LLM 用量日志仅保存调用元数据，实验步骤原文和模型响应不进入用量表。
代理与部署边界
docker/nginx/default.conf 把前后端统一到一个入口：/api/反代到后端。/static/透传到后端。/docs、/redoc和/openapi.json单独透传。/落到前端产物并回退到index.html。
部署层是统一入口，但安全头、CSRF、CORS 和 /static/ 缓存仍由 FastAPI 主导。
新增接口前检查清单
- 这是对象 CRUD，还是工作流动作。
- 是否补齐
get_current_user或require_admin。 - 是否要触发 SSE 广播与缓存失效。
- CLI 或 MCP 是否需要同步暴露该能力。
- 是否涉及上传体积保护、CSRF、CORS 或代理头。
- 是否需要同步更新 API 参考。
相关页面
- 查接口路径：看 API 参考。
- 看后端分层：看 后端服务地图。
- 看业务流程：看 核心 API 与工作流。
- 看认证、Cookie、CSRF 与 Redis 降级：看 认证与安全。
- 看运行时入口、中间件、WAL 与 SSE 生命周期：看 运行时与入口。
- 看实验步骤查库存的用户流程：看 实验步骤查库存。