首次提交：初始化后端、数据库结构与文档代码

docs/餐饮零售数据中台/有赞接口/5.查询总部下门店和仓库信息 (youzan.retail.open.warehouse.query.3.0.0).md

@@ -0,0 +1,76 @@
+
+# 查询总部下门店和仓库信息 (youzan.retail.open.warehouse.query.3.0.0)
+
+## 1. 接口基本信息
+
+* **API 名称**：查询总部下门店和仓库信息
+* **API 接口名**：`youzan.retail.open.warehouse.query`
+* **版本号**：`3.0.0`
+* **接口描述**：用于连锁总部或多网点商家，批量查询其底下的所有真实仓库以及具有仓库属性的“线下门店”信息。获取到的 `warehouse_code` 是后续调用库存调整、盘点、调拨等单据接口的**必传核心参数**。
+
+---
+
+## 2. 请求说明
+
+* **请求协议**：HTTPS
+* **请求方式**：POST (推荐 `application/json` 格式)
+* **请求地址**：
+
+  ```http
+  https://open.youzanyun.com/api/youzan.retail.open.warehouse.query/3.0.0
+  ```
+
+---
+
+## 3. 请求参数
+
+在请求的 Body 中传入以下 JSON 参数：
+
+| 参数名称 | 类型 | 是否必填 | 示例值 | 参数说明 |
+| :--- | :--- | :---: | :--- | :--- |
+| `access_token` | String | **是** | `9b510e232...` | 有赞云 API 鉴权凭证（请使用连锁总店的 Token 授权） |
+| `page_no` | Integer | 否 | `1` | 页码，默认从 1 开始 |
+| `page_size` | Integer | 否 | `20` | 每页返回的数量，建议默认 20，最大通常不超过 100 |
+| `warehouse_name` | String | 否 | `北京一号仓` | 仓库或门店名称（支持模糊搜索筛选） |
+| `retail_source` | String | 否 | `YOUZAN` | 零售调用来源。*（注：该字段官方已于 2021-04-26 废弃取消强校验，新接入开发者无需传值，不影响调用）* |
+
+---
+
+## 4. 响应参数
+
+响应主体包裹在 `data` 中，主要返回门店与仓库的映射列表信息。
+
+| 根级参数名称 | 类型 | 描述说明 |
+| :--- | :--- | :--- |
+| `success` | Boolean | 请求是否成功 (`true`/`false`) |
+| `code` | Integer | 状态码，`200` 表示成功 |
+| `message` | String | 成功或错误提示信息 |
+| `data` | Object | **查询结果总包** |
+| └─ `count` | Integer | 匹配到的总条数（用于计算分页） |
+| └─ `items` | Array | **仓库/门店信息列表集合** |
+
+### 4.1 `items` 数组内核心业务字段解构
+
+| 内部参数名称 | 类型 | 核心说明 |
+| :--- | :--- | :--- |
+| `warehouse_code` | String | **仓库/门店编码（核心参数）**。有赞系统内部生成的唯一编码（如 `MD00021` 或 `TEST001`）。 |
+| `warehouse_name` | String | 仓库或门店的名称。 |
+| `warehouse_type` | Integer | 仓库属性类型。区分该主体是“普通大仓”还是“线下实体门店”。 |
+| `kdt_id` | Long | 绑定的对应店铺/网点的底层 ID。（如果该仓是独立门店，则返回对应门店的 kdt_id） |
+| `status` | Integer | 仓库状态。例如正常营业、停用等。 |
+| `address` | String | 仓库或门店的详细物理地址。 |
+
+---
+
+## 5. ⚠️ 开发者防坑指南与注意事项（核心高频报错提醒）
+
+1. **极其容易混淆的 `warehouse_code` 与 `kdt_id`（错误码 `234000003`）**：
+   在有赞新零售/连锁系统中，“线下门店”本身也被视作一个“仓库”。很多开发者在调用“查询/调整门店商品库存”接口（如 `youzan.retail.open.query.warehousestock` 或 `youzan.retail.open.stock.adjust`）时，**错误地将门店的底层店铺ID（`kdt_id`）当作仓库编码传了进去**，这会导致接口直接报错：`{"code": 234000003, "message": "仓库信息不存在"}`。
+   **正确做法**：必须先调用本接口（`youzan.retail.open.warehouse.query`），拿到门店对应的真实 `warehouse_code`（类似 `MD00021`），再用这个编码去调用库存接口。
+
+2. **ERP 映射关系的建立（库存对接必读）**：
+   如果您正在对接第三方 ERP 系统的网店/门店库存同步，正确的初始化流必须是：
+   在第三方系统中建立映射表 → 调用本接口全量拉取有赞的 `warehouse_code` → 与 ERP 系统里的仓库编码（或者门店编号）进行 `1:1` 的绑定映射。
+
+3. **连锁授权架构提示**：
+   本接口属于“零售连锁/多网点”场景下的专属 API。调用时使用的 `access_token` 必须是由**总部（总店）**授权产生的。如果使用单店或无多网点权限的微商城 Token 请求，可能会拉取为空或提示权限不足。