fear: stock reverse placeholder

docs/20251128-stock.md

@@ -359,6 +359,133 @@ Warehouses can operate in different modes:
 }
 ```
 
+### 4. Stock Snapshot List
+
+- **URL**: `GET /api/v1/stock-snapshots/`
+- **Description**: Read-only list of `StockSnapshot` entries. Supports `limit/offset` pagination,搜索与过滤。
+- **Query Parameters**:
+  | 参数 | 说明 |
+  |------|------|
+  | `product` / `product_name` / `product_code` | 指定产品或模糊搜索 |
+  | `warehouse` / `warehouse_name` | 指定仓库或模糊搜索 |
+  | `stock_change_record` | 关联的出入库记录 ID |
+  | `unit` | 单位过滤 |
+  | `cancelled` | `true/false`，是否被标记取消 |
+  | `has_offset` | `true/false`，筛选是否存在冲抵记录 |
+  | `date_from` / `date_to` | 创建时间范围（`YYYY-MM-DD`） |
+  | `search` | 针对产品名、产品编码、仓库名的全文搜索 |
+  | `ordering` | 排序字段，默认 `-created_at` |
+
+**Response 示例**：
+```json
+{
+  "count": 2,
+  "results": [
+    {
+      "id": 901,
+      "product": 15,
+      "product_name": "纯棉印花布",
+      "warehouse": 3,
+      "warehouse_name": "严进仓",
+      "delta": "120.00",
+      "quantity_before": "80.00",
+      "quantity_after": "200.00",
+      "stock_change_record": 456,
+      "stock_change_record_type": "入库",
+      "stock_change_record_source": "采购",
+      "unit": 1,
+      "unit_display": "米",
+      "num_of_rolls": 3,
+      "offset_to": null,
+      "cancelled": false,
+      "created_at": "2025-11-25T12:05:00Z"
+    }
+  ]
+}
+```
+
+### 5. Merchant Auto Complete Setting
+
+- **URL**: `POST /api/v1/set-merchant-auto-complete-stock-change/`
+- **Description**: 为当前商户开启 / 关闭“创建出入库记录后自动完成”功能。开启后，`create_*` 接口在事务内会立即调用 `stock.services.make_stock_change_completed`，自动写入库存与快照。
+- **Request**:
+```json
+{
+  "auto_complete": true
+}
+```
+- **Response**:
+```json
+{
+  "status": "success"
+}
+```
+
+只有具备员工身份的登录用户才可调用该接口。
+
+### 6. Stock Change Completion Behavior
+
+- **自动完成**：当商户开启 `auto_complete_stock_change` 时，任意模式的创建接口都会立即调用 `make_stock_change_completed`，更新 `Inventory` 并生成 `StockSnapshot`。
+- **手动完成**：当需要补处理或未开启自动完成时，可调用 `POST /api/v1/stock-change/<id>/finish/` 手动触发 `make_stock_change_completed`，也可直接在后台脚本里调用服务函数。
+- **状态字段**：`StockChangeRecord.is_finished` / `finished_at` 会在完成时标记，用于列表和详情接口判断记录是否已经生效。
+
+### 7. Finish Stock Change Record (Manual)
+
+- **URL**: `POST /api/v1/stock-change/<id>/finish/`
+- **Description**: 手动触发指定出入库记录的库存扣减与快照写入，适用于未开启自动完成或需要补处理的场景。仅当前商户下且仓库可见的员工可调用。
+- **Request**: 无需请求体，只需保证 URL 中的 `<id>` 为目标 `StockChangeRecord` 的 ID。
+- **Response**:
+```json
+{
+  "status": "success",
+  "message": "库存变动记录已标记为完成",
+  "stock_change_record": {
+    "id": 17,
+    "type": 1,
+    "warehouse": 1,
+    "warehouse_name": "严谨仓",
+    "source_type": 1,
+    "source_type_display": "采购",
+    "source_id": 123,
+    "is_finished": true,
+    "finished_at": "2025-11-25T12:30:00Z",
+    "created_at": "2025-11-25T11:50:00Z",
+    "created_by": "stock_admin",
+    "remarks": null
+  }
+}
+```
+
+### 8. Stock Change Offset (Red Flush Placeholder)
+
+- **URL**: `POST /api/v1/stock-change/<id>/offset/`
+- **Description**: 面向未来的库存红冲入口。当前仅提供占位实现，用于锁定最终接口形态；实际红冲逻辑尚未上线，因此调用会返回 `501 Not Implemented`，方便前端或上游业务在流程编排中预留节点。
+- **Request**:
+```json
+{
+  "reason": "审批错误，需要冲销",
+  "items": [
+    {
+      "product_id": 1,
+      "quantities": ["50.00"]
+    }
+  ],
+  "request_id": "po-123-offset",
+  "extra_meta": {
+    "source": "purchase_order",
+    "operator": "warehouse_admin"
+  }
+}
+```
+- **Response（当前占位行为）**:
+```json
+{
+  "error": "stock_offset_not_ready",
+  "message": "库存红冲功能尚未实现",
+  "record_id": 25
+}
+```
+
 ## Examples
 
 ### Example 1: Creating a Stock-in Record (Full Mode)
@@ -419,6 +546,12 @@ curl -X POST http://example.com/api/v1/stock-change/restrict/ \
   }'
 ```
 
+### Example 4: Finish a Stock Change Record Manually
+```bash
+curl -X POST http://example.com/api/v1/stock-change/17/finish/ \
+  -H "Authorization: Bearer your_token"
+```
+
 ## Error Handling
 
 ### Common Error Responses