docs/00-overview.md

docs/07-api.md

@@ -0,0 +1,58 @@
+# 07 API 规范
+
+## 路由
+
+RESTful，统一前缀 `/api/v1/`。
+
+```
+GET  /api/v1/warehouses
+GET  /api/v1/skus
+GET  /api/v1/inventory
+
+POST /api/v1/inbounds
+POST /api/v1/inbounds/{inbound_no}/receive
+POST /api/v1/inbounds/{inbound_no}/putaway
+
+GET  /api/v1/outbounds
+POST /api/v1/outbounds/{outbound_no}/allocate
+POST /api/v1/outbounds/{outbound_no}/pick
+POST /api/v1/outbounds/{outbound_no}/pack
+POST /api/v1/outbounds/{outbound_no}/ship
+```
+
+要点：
+
+- 资源名使用复数。
+- 路由参数优先使用业务编码（`inbound_no`、`outbound_no`），而非自增 ID。
+- 业务动作（状态流转）使用 `POST /{resource}/{code}/{action}`。
+- 认证使用 Laravel Sanctum，授权使用 Policies / Gates。
+
+## 统一返回格式
+
+不要每个 Controller 自己定义一套返回结构。
+
+成功：
+
+```json
+{
+    "success": true,
+    "message": "OK",
+    "data": {}
+}
+```
+
+失败：
+
+```json
+{
+    "success": false,
+    "message": "操作失败",
+    "errors": {}
+}
+```
+
+分页数据使用统一格式（具体字段在 Phase 2 确定并固化到统一响应工具类中），所有列表接口保持一致。
+
+## 内部 API（Python Service）
+
+Laravel 调用 Python 的内部接口统一使用 `/internal/v1/` 前缀，见 [11-py-service.md](./11-py-service.md)。