From 84d775bc90e5c022fa686a5337ab0669a2eabca9 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E6=96=87=E7=9D=BF=20=E5=BC=A0?= <zzz0217asdf@163.com>
Date: Sun, 20 Sep 2026 14:30:15 +0800
Subject: [PATCH] =?UTF-8?q?=E8=A1=A5=E5=85=85=E6=96=87=E6=A1=A3?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 docs/api.md | 55 ++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 54 insertions(+), 1 deletion(-)

diff --git a/docs/api.md b/docs/api.md
index 1f54ab83..d0a9a0d9 100644
--- a/docs/api.md
+++ b/docs/api.md
@@ -92,7 +92,7 @@
 | limit    | integer | 否   | 每页条数，默认 20，上限 100 |
 | offset   | integer | 否   | 偏移量，默认 0             |
 
-> 该接口**不按物料状态过滤**，已作废的物料同样会出现在结果里，调用方需要自己判断 `status` 字段。
+> `status` 默认 `active`，所以该接口默认只返回有效物料，已作废的物料需要显式传 `status=all` 或 `status=obsolete` 才能查到。业务单据的物料下拉正是靠这个默认值自然排除了作废物料；库存流水的检索框则要显式传 `status=all`，才能查到已作废物料的历史。
 
 **响应**（`data` 为分页对象，此处只展示 `items` 内元素）：
 
@@ -889,6 +889,59 @@
 
 ---
 
+### GET /stock/:materialId/details
+
+查询某个物料在各库存维度（组织 / 仓库 / 库位）上的明细。**该接口不分页**，`data` 直接是数组；物料存在但从没有过库存记录时返回空数组。
+
+**路径参数：**
+
+| 参数       | 类型    | 必填 | 说明     |
+|------------|---------|------|----------|
+| materialId | integer | 是   | 物料 ID  |
+
+**响应：**
+
+```json
+{
+  "code": 0,
+  "message": "success",
+  "data": [
+    {
+      "id": 1,
+      "organization_id": 1,
+      "organization": "默认组织",
+      "warehouse_id": 1,
+      "warehouse": "默认仓库",
+      "location_id": 1,
+      "location": "主库位",
+      "material_id": 1,
+      "on_hand": "500",
+      "reserved": "0",
+      "locked": "0",
+      "in_transit": "0",
+      "updated_at": "2026-01-01T08:00:00Z"
+    }
+  ]
+}
+```
+
+| 字段       | 类型    | 说明                   |
+|------------|---------|------------------------|
+| on_hand    | string  | 现有库存               |
+| reserved   | string  | 预留数量               |
+| locked     | string  | 锁定数量               |
+| in_transit | string  | 在途数量               |
+
+> `reserved`、`locked`、`in_transit` 三个维度当前没有任何业务写入，恒为 `0`；只有 `on_hand` 会随出入库变动。作废校验会把这四项一起纳入判断。
+
+**状态码：**
+
+- `200 OK` — 成功
+- `400 Bad Request` — 物料 ID 非法
+- `404 Not Found` — 物料不存在
+
+---
+
 ### GET /stock/warning
 
 分页查询需要关注的物料：预警处于启用状态，并且现有库存已触达阈值。阈值为 0 的物料在库存降到 0 时也会出现在这里。