feat: added type field into warehouse model

2025-11-20 15:44:35 +08:00
parent 6091280fdc
commit 2a838199fa
22 changed files with 1384 additions and 38 deletions
--- a/docs/WAREHOUSE_TYPE.md
+++ b/docs/WAREHOUSE_TYPE.md
@@ -0,0 +1,146 @@
+# 仓库类型 (WarehouseTypeEnum)
+
+本文档描述了 `basic_info` 模块中 `WareHouse` 模型的 `type` 字段及其枚举值。
+
+## 功能说明
+
+仓库类型字段 (`type`) 用于区分仓库的类别，目前支持两种类型：
+
+- **整仓**: 存储完整的、未分割的货物
+- **散仓**: 存储零散的、分割后的货物
+
+## 枚举值
+
+### WarehouseTypeEnum
+
+| 值 (Integer) | 名称 (String) | 描述 |
+|--------------|---------------|------|
+| `1`          | `整仓`        | 默认值，用于存储整卷/整件货物 |
+| `2`          | `散仓`        | 用于存储散卷/拆分后的货物 |
+
+## 模型定义
+
+```python
+class WarehouseTypeEnum(models.IntegerChoices):
+    """仓库类别枚举"""
+    WHOLE = 1, '整仓'
+    SCATTERED = 2, '散仓'
+
+
+class WareHouse(ModelBase):
+    # ...
+    type = models.IntegerField(
+        choices=WarehouseTypeEnum.choices,
+        default=WarehouseTypeEnum.WHOLE,
+        verbose_name='仓库类别',
+    )
+    # ...
+```
+
+## API 使用
+
+### 创建仓库
+
+**端点**: `POST /api/backend/warehouses/`
+
+**请求体示例**:
+
+```json
+{
+  "name": "主仓库",
+  "type": 1,
+  "location": "工厂一楼",
+  "area": "广州",
+  "mode": 1
+}
+```
+
+**参数说明**:
+- `type`: 仓库类型，可选值：`1` (整仓) 或 `2` (散仓)，默认为 `1`
+
+### 列表查询
+
+**端点**: `GET /api/backend/warehouses/`
+
+**响应示例**:
+
+```json
+{
+  "results": [
+    {
+      "id": 1,
+      "name": "主仓库",
+      "type": 1,
+      "location": "工厂一楼",
+      "mode": 1,
+      "area": "广州"
+    },
+    {
+      "id": 2,
+      "name": "散货仓",
+      "type": 2,
+      "location": "工厂二楼",
+      "mode": 1,
+      "area": "广州"
+    }
+  ]
+}
+```
+
+### 更新仓库
+
+**端点**: `PATCH /api/backend/warehouses/{id}/`
+
+**请求体示例**:
+
+```json
+{
+  "type": 2
+}
+```
+
+## Admin 界面
+
+在 Django Admin 界面中：
+
+- **列表页**: `type` 字段显示在列表中，并可用于筛选
+- **编辑页**: `type` 字段显示为下拉选择框
+- **显示文本**: 使用中文标签（整仓/散仓）
+
+### Admin 配置
+
+- `list_display` 包含 `type` 字段
+- `list_filter` 包含 `type` 字段，方便按类型筛选
+
+## 注意事项
+
+1. **默认值**: 创建仓库时，如果未指定 `type`，默认为 `1`（整仓）
+2. **验证**: `type` 字段只接受 `1` 或 `2` 两个值
+3. **兼容性**: 现有仓库记录在迁移后将自动设置为默认值（整仓）
+4. **扩展性**: 如需添加新的仓库类型，可在 `WarehouseTypeEnum` 中添加新枚举值
+
+## 数据库迁移
+
+新字段通过以下迁移添加：
+
+- 迁移文件: `basic_info/migrations/0010_warehouse_type.py`
+- 字段: `type` (IntegerField)
+- 默认值: `1` (整仓)
+
+## 测试覆盖
+
+测试文件包括：
+
+- **模型测试**: `basic_info/tests.py` - 测试字段默认值、枚举值等
+- **API 测试**: `api_man/tests.py` - 测试 CRUD 操作和 API 返回值
+
+运行测试：
+
+```bash
+# 测试模型
+uv run python manage.py test basic_info.tests.WarehouseTypeTestCase
+
+# 测试 API
+uv run python manage.py test api_man.tests.WarehouseAPITestCase
+```
+