签入版本

2026-09-12 23:12:15 +08:00
commit 91998056ca
1841 changed files with 341325 additions and 0 deletions
@@ -0,0 +1,114 @@
+:::tip 参数管理
+参数管理模块用于管理系统配置和业务配置，每个参数包含名称、编码、值、类型、排序、状态等属性。本模块是典型的「BaseService 简单模块」，通过声明差异点即可获得完整 CRUD 能力。
+:::
+
+## 模块结构
+
+```
+src/modules/param/
+├── models.py     # 参数模型
+├── schema.py     # 表单验证（WTForms）
+├── repository.py # 数据访问层
+├── service.py    # 业务逻辑层（继承 BaseService）
+└── router.py     # 路由控制器
+```
+
+## 参数服务
+
+```python
+# src/modules/param/service.py
+from src.common.base_service import BaseService
+from src.modules.param.schema import ParamForm, ParamStatusForm
+from src.modules.param.repository import ParamRepository
+
+
+class ParamService(BaseService):
+    """
+    参数服务类
+
+    继承 BaseService 获得标准 CRUD 能力。
+    """
+    repository = ParamRepository
+    form = ParamForm
+    status_form = ParamStatusForm
+    model_name = "参数"
+
+
+# ============================================================
+# 模块级代理函数：保持 router 调用兼容
+# ============================================================
+
+get_param_page = ParamService.get_page
+get_param_detail = ParamService.get_detail
+get_info = ParamService.get_info
+add_param = ParamService.add
+update_param = ParamService.update
+delete_params = ParamService.remove
+update_param_status = ParamService.update_status
+```
+
+:::tip 简单模块模式
+参数模块是典型的简单 CRUD 模块，只需声明 `repository` / `form` / `model_name` 即可获得完整能力。唯一性校验在 Schema 的 `validate_` 方法中实现，分页查询在 Repository 的 `page()` 方法中定义。
+:::
+
+## 分页查询
+
+Repository 的 `page()` 方法定义分页查询逻辑：
+
+```python
+# src/modules/param/repository.py
+class ParamRepository(BaseRepository):
+    model = Param
+
+    @classmethod
+    def page(cls, params: dict):
+        """参数分页查询"""
+        return cls.find_page(
+            page=int(params.get('pageNo', 1)),
+            page_size=int(params.get('pageSize', PAGE_SIZE)),
+            filters={'type': params.get('type'), 'status': params.get('status')},
+            like_filters={'name': params.get('name'), 'code': params.get('code')},
+            order_by='sort',
+        )
+
+    @classmethod
+    def list_enabled(cls, params=None):
+        """查询启用的参数列表"""
+        params = params or {}
+        return cls.find_list(
+            filters={'status': 1},
+            like_filters={'name': params.get('name')},
+            order_by='sort',
+        )
+```
+
+## 枚举显示名映射
+
+通过 `serialize_maps` 声明枚举字段与字典编码的映射关系，分页和详情接口自动补充 `{field}Text` 字段：
+
+```python
+class ParamService(BaseService):
+    serialize_maps = {
+        'type': 'param_type',      # 参数类型 → 数据字典
+        'status': 'param_status'   # 参数状态 → 数据字典
+    }
+```
+
+查询结果自动包含 `typeText` 和 `statusText` 字段，前端直接使用。
+
+## API 接口
+
+| 方法 | 路径 | 权限节点 | 说明 |
+|:---|:---|:---|:---|
+| GET | `/api/v1/param/page` | `sys:param:page` | 分页查询（支持 name/code 模糊、type/status 精确） |
+| GET | `/api/v1/param/detail/<id>` | `sys:param:detail` | 详情查询 |
+| GET | `/api/v1/param/list` | `sys:param:list` | 参数列表（无分页） |
+| POST | `/api/v1/param/add` | `sys:param:add` | 新增参数 |
+| PUT | `/api/v1/param/update` | `sys:param:update` | 编辑参数 |
+| DELETE | `/api/v1/param/delete/<id>` | `sys:param:delete` | 删除参数 |
+| DELETE | `/api/v1/param/batchDelete` | `sys:param:batchDelete` | 批量删除 |
+| PUT | `/api/v1/param/status` | `sys:param:status` | 设置状态 |
+
+## 总结
+
+参数管理模块是典型的简单 CRUD 模块，继承 BaseService 声明 `repository` / `form` / `model_name` 即可获得完整能力。分页查询在 Repository 的 `page()` 方法中通过 `filters` / `like_filters` / `order_by` 定义，唯一性校验在 Schema 的 `validate_` 方法中实现。