feat: auth

docs/frontend_api.md

@@ -10,6 +10,7 @@
 
 - `GET /healthz`
 - `POST /route/plan`
+- `POST /load/plan`
 
 默认本地开发地址示例：
 
@@ -17,7 +18,24 @@
 http://127.0.0.1:8000
 ```
 
-### 2.1 CORS
+### 2.1 Authorization
+
+除 `GET /healthz` 外，当前业务接口都需要通过 `Authorization` 请求头进行鉴权。
+
+请求头格式：
+
+```text
+Authorization: <AGENT_HTTP_AUTH_KEY>
+```
+
+说明：
+
+- 不使用 `Bearer` 前缀
+- 服务端从 `.env` 中读取 `AGENT_HTTP_AUTH_KEY`
+- 如果服务端未配置该值，请求会返回 `503`
+- 如果请求头缺失或值不匹配，请求会返回 `401`
+
+### 2.2 CORS
 
 当前服务已启用 CORS。
 
@@ -48,6 +66,7 @@ GET /healthz
 
 ```http
 POST /route/plan
+Authorization: <AGENT_HTTP_AUTH_KEY>
 Content-Type: application/json
 ```
 
@@ -444,3 +463,86 @@ Content-Type: application/json
 - 前端确认 deep link 的按钮交互形式
 - 前后端统一 422 错误展示文案
 - 后续若输出结构调整，需要同步更新本文档
+
+## 11. 装载规划接口
+
+### 11.1 请求
+
+```http
+POST /load/plan
+Authorization: <AGENT_HTTP_AUTH_KEY>
+Content-Type: application/json
+```
+
+### 11.2 请求体
+
+```json
+{
+  "merchant_id": 1,
+  "area": "中大",
+  "license_plate": "粤A4Y0Y5"
+}
+```
+
+### 11.3 请求字段说明
+
+- `merchant_id`
+  - 必填
+  - 商户 ID
+- `area`
+  - 必填
+  - 按区域筛选待出货出货单，精确匹配
+- `license_plate`
+  - 必填
+  - 目标运输车辆车牌号
+
+### 11.4 成功响应示例
+
+```json
+{
+  "success": true,
+  "license_plate": "粤A4Y0Y5",
+  "selected_shipment_ids": [13],
+  "summary": "待出货出货单共1个，出货单ID13的销售品幅宽均为170cm，判定为针织面料，包含2条销售品，未超过车辆针织最大装载容量120条，因此选择该出货单进行装载。",
+  "warnings": [
+    "当前装载条数为2条，未达到针织面料最大运输容量120条，属于欠载方案。"
+  ]
+}
+```
+
+### 11.5 响应字段说明
+
+- `success`
+  - 是否成功完成装载规划
+- `license_plate`
+  - 本次规划对应的车牌号
+- `selected_shipment_ids`
+  - 被选中的出货单 ID 列表
+- `summary`
+  - 可直接展示给用户的装载说明
+- `warnings`
+  - 欠载、字段缺失、无法判定面料等提示信息
+
+### 11.6 错误语义
+
+- `401`
+  - `Authorization` 请求头缺失或值不正确
+- `422`
+  - 装载规则护栏错误或输入不满足规划要求
+- `503`
+  - 装载模型配置、业务 API 配置或服务端鉴权配置缺失
+- `502`
+  - 上游业务 API 返回错误，例如车辆不存在或接口请求失败
+- `504`
+  - 装载模型或业务 API 超时
+- `500`
+  - 未预期的内部错误
+
+### 11.7 当前行为说明
+
+- Agent 会先查询指定 `area` 的未出货出货单，再查询指定车牌的车辆容量
+- 面料类型仅通过 `sales_items[].printing_job_width` 判断
+- 装载量按销售品条数计算，不按 `quantity` 长度或米数计算
+- 默认不允许混装针织和梭织
+- 优先选择不超载且尽量接近最大容量的方案
+- 如果只能欠载，会在 `warnings` 中明确提示