feat: P0-4 按库存优化+切割准备清单(缺料告警)

doc/API.md

@@ -405,3 +405,12 @@ uv run uvicorn huamenchuang.main:app --reload   # 启动，http://localhost:8000
 | 删除模板 | DELETE | `/api/order-formats/{id}` | 路径 | |
 
 种子模板 2 套：标准生产订单（默认）、生产订单+BOM 下料单。
+
+### 12.18 合同下料方案升级（v2.20，P0-按库存优化）
+
+`POST /api/cut_solution` 请求扩展：`{contract_id, kerf, use_stock?, stock_length?}`。
+
+- `use_stock=true`：从仓库实际库存（material=profile 且 length>0 且 count>0）取原料优化；需求超出库存时输出 `shortage[]` 缺料清单（length/label/qty），不拦截计算
+- `use_stock=false`：按 `stock_length`（默认 6000mm）虚拟原料，数量按需求自动估算
+- 响应/保存均新增：`result`（完整优化方案）、`preparation[]`（切割准备/领料清单：原料×根数×切割件数×余料）、`shortage[]`（按库存模式的缺料清单）
+- `GET /api/cut_solution/{contract_id}` 返回完整保存方案（含 result/preparation/shortage）