feat: P0-6 Excel导入导出全套(客户/合同/库存/统计, 自动表头探测)

doc/API.md

@@ -431,3 +431,17 @@ uv run uvicorn huamenchuang.main:app --reload   # 启动，http://localhost:8000
 | **收款统计** | GET | `/api/receipts/statistics` | `year?`（默认当年） | `{total_received, contract_total, unreceived, monthly[12]}`（对齐 statistics/_tb） |
 
 合同列表（`GET /api/contracts`）响应行新增：`received`（有效收款合计）、`unreceived`（合同额-已收）。
+
+### 12.20 Excel 导入导出（v2.20 新增，P0-数据迁移）
+
+依赖 `openpyxl` + `python-multipart`。导入文件自动探测表头行（兼容带标题行的导出格式）；导出为带样式 xlsx。
+
+| 接口名称 | 方式 | URL 路径 | 请求参数 | 说明 |
+|---|---|---|---|---|
+| 客户导入模板 | GET | `/api/customers/excel-template` | — | 列：姓名*/电话/地址/业务员/备注 |
+| **客户批量导入** | POST | `/api/customers/excel-in` | multipart `file` | 对齐 customers_excel_in；缺姓名行跳过并逐行报错 |
+| 客户导出 | GET | `/api/customers/excel-out` | — | 全量 |
+| 合同导出 | GET | `/api/contracts/excel-out` | — | 对齐 contracts_excel，含已收金额 |
+| **库存批量导入** | POST | `/api/warehouse/excel-in` | multipart `file` | 对齐 materials_config_excel：同名材料更新（数量累加），否则新增 |
+| 库存导出 | GET | `/api/warehouse/excel-out` | — | 对齐 warehouse_excel_out |
+| 统计报表导出 | GET | `/api/reports/excel-statistics` | — | 对齐 excel-statistics：订单汇总+收款统计双 Sheet |