feat: auth

docs/agent_design.md

@@ -2,7 +2,7 @@
 
 ## 1. 项目目标
 
-本项目用于实现一个“多目标地点最优路线规划”服务。
+本项目用于实现一个“多目标地点最优路线规划 + 货物装载规划”服务。
 
 核心能力如下：
 
@@ -13,6 +13,8 @@
 - 根据策略选出最佳路线
 - 返回结构化 JSON，供前端直接消费
 - 在需要时生成高德 deep link
+- 接收区域和车牌号，获取待出货出货单与车辆容量
+- 根据针织/梭织规则选择可装载的出货单
 
 当前阶段的目标不是构建一个复杂的调度系统，而是先交付一个可工作的第一版 Agent API。
 
@@ -30,25 +32,36 @@
 
 - `main.py`
   - FastAPI 入口
-  - 暴露 `/healthz` 和 `/route/plan`
-  - 负责 HTTP 错误映射
+  - 暴露 `/healthz`、`/route/plan` 和 `/load/plan`
+  - 负责 Authorization 鉴权与 HTTP 错误映射
 - `schemas.py`
   - 定义请求和响应模型
   - 实现输入校验
-- `agent.py`
+- `agent/route_plan.py`
+  - 路线规划 Agent
   - 负责 LLM、MCP、prompt、运行护栏、结果护栏
+- `agent/load_plan.py`
+  - 装载规划 Agent
+  - 负责装载模型、skills、工具接入与结构化输出
+- `agent/load_plan_tools.py`
+  - 装载规划业务 API 工具
+  - 当前提供车辆详情和未出货出货单查询
+- `skills/fabric-load-planning/SKILL.md`
+  - 装载规划 skill
+  - 定义面料判断、欠载与不混装规则
 - `.env`
   - 管理模型配置、MCP 配置和运行护栏配置
 
 运行链路：
 
 1. 前端请求进入 FastAPI
-2. Pydantic 校验请求结构
-3. 服务侧执行预护栏检查
-4. Agent 运行，并由 `system_prompt` 驱动模型调用高德 MCP 工具
-5. Agent 返回结构化结果
-6. 服务侧执行结果护栏检查
-7. 返回 JSON 给前端
+2. `/route/plan` 和 `/load/plan` 先通过 Authorization 鉴权
+3. Pydantic 校验请求结构
+4. 根据不同入口进入对应 Agent
+5. Agent 调用地图 MCP 或装载业务 API 工具
+6. Agent 返回结构化结果
+7. 服务侧执行错误映射
+8. 返回 JSON 给前端
 
 ## 4. 关键技术选型与决策依据
 
@@ -100,6 +113,22 @@
   - `maps_schema_navi`
   - `maps_weather`
 
+### 5.2 装载规划 Agent 接入
+
+- 装载规划 Agent 使用独立模型配置：
+  - `LOAD_PLAN_BASE_URL`
+  - `LOAD_PLAN_API_KEY`
+  - `LOAD_PLAN_MODEL`
+  - `LOAD_PLAN_REQUEST_TIMEOUT_SECONDS`
+- 装载规划业务 API 使用独立配置：
+  - `LOAD_PLAN_API_HOST`
+  - `LOAD_PLAN_AGENT_ACCESS_KEY`
+  - `LOAD_PLAN_API_TIMEOUT_SECONDS`
+- 当前装载规划已接入两个业务工具：
+  - 按车牌查询车辆详情
+  - 按区域查询未出货出货单
+- 装载规则通过 `pydantic-ai-skills` 从本地 `skills/` 目录注入
+
 ### 5.2 Prompt 组织方式
 
 `system_prompt` 中定义了以下行为约束：
@@ -211,6 +240,9 @@
 - 超限请求可返回 422，并中止模型执行
 - 已改为严格 deep-link 模式：成功结果必须包含 deep link，否则直接失败
 - 已增加前置点位解析与 POI 校验阶段，缺少 `poi_id` 或命中模糊时直接失败
+- 已增加 `/load/plan` HTTP 入口
+- 已接入装载规划 Agent、业务 API tools 与本地 skills
+- 已验证 `merchant_id + area + license_plate` 可返回装载规划结果
 
 当前尚未完成：
 
@@ -219,6 +251,7 @@
 - 深链策略的更强一致性校验
 - 自动化测试
 - 前端展示层 HTML 输出
+- 多出货单组合场景的稳定性增强
 
 ## 8. 关键取舍