签入版本

2026-09-12 23:12:15 +08:00
commit 91998056ca
1841 changed files with 341325 additions and 0 deletions
@@ -0,0 +1,138 @@
+:::tip 参数管理
+参数管理模块用于管理动态系统参数，支持按参数键查询、修改，无需重启服务即可生效。
+:::
+
+## 模块结构
+
+```
+application/param/
+├── models.py     # 参数模型
+├── forms.py      # 表单验证
+├── services.py   # 业务逻辑层
+├── views.py      # 视图层
+└── urls.py       # 路由配置
+```
+
+## 参数模型
+
+```python
+# application/param/models.py
+from application.models import BaseModel
+
+class Param(BaseModel):
+    """参数模型类"""
+    class Meta:
+        db_table = 'django_param'
+
+    name = models.CharField(max_length=100, verbose_name='参数名称')
+    code = models.CharField(max_length=100, verbose_name='参数编码')
+    value = models.CharField(max_length=255, verbose_name='参数值')
+    type = models.IntegerField(verbose_name='参数类型：0-系统 1-业务')
+    status = models.IntegerField(verbose_name='参数状态：1-正常 2-禁用')
+    sort = models.IntegerField(verbose_name='参数排序')
+    note = models.CharField(max_length=255, null=True, blank=True, verbose_name='参数备注')
+```
+
+## 表单验证
+
+```python
+# application/param/forms.py
+from django import forms
+from application.param.models import Param
+
+class ParamForm(forms.ModelForm):
+    class Meta:
+        model = Param
+        fields = ['name', 'code', 'value', 'type', 'status', 'sort', 'note']
+        error_messages = {
+            'name': {
+                'required': '参数名称不能为空',
+            },
+            'code': {
+                'required': '参数编码不能为空',
+            },
+            'value': {
+                'required': '参数值不能为空',
+            },
+        }
+```
+
+## 按编码取值
+
+这是参数模块的核心自定义方法，供其他业务模块调用：
+
+```python
+# application/param/services.py
+def get_value_by_code(code, default=None):
+    """根据参数编码获取参数值"""
+    param = Param.objects.filter(
+        code=code, status=1, is_delete=False
+    ).first()
+    return param.value if param else default
+```
+
+### 使用示例
+
+```python
+from application.param.services import get_value_by_code
+
+# 获取参数值（存在且状态=正常时返回值，否则返回默认值）
+default_pwd = get_value_by_code("USER_DEFAULT_PASSWORD", "123456")
+upload_limit = get_value_by_code("UPLOAD_MAX_SIZE", "10")
+maintenance = get_value_by_code("MAINTENANCE_MODE", "0")
+```
+
+:::tip 典型用法
+在其他 service 中注入参数值，实现运行时可调的业务配置：
+
+```python
+from application.param.services import get_value_by_code
+
+def reset_password(user_id):
+    # 从参数表读取默认密码，无需硬编码
+    default_pwd = get_value_by_code("USER_DEFAULT_PASSWORD", "123456")
+    # ... 重置密码逻辑
+```
+:::
+
+## API 接口
+
+| 接口 | 方法 | 权限节点 | 说明 |
+|:----|:----|:----|:----|
+| `/param/page` | GET | `sys:param:page` | 分页查询 |
+| `/param/detail/<int:param_id>` | GET | `sys:param:detail` | 详情查询 |
+| `/param/add` | POST | `sys:param:add` | 新增参数 |
+| `/param/update` | POST | `sys:param:update` | 编辑参数 |
+| `/param/delete/<int:param_id>` | POST | `sys:param:delete` | 删除参数 |
+
+### 查询参数
+
+分页接口支持以下查询参数：
+
+| 参数 | 类型 | 说明 |
+|:----|:----|:----|
+| `pageNo` | int | 页码，默认 1 |
+| `pageSize` | int | 每页条数，默认 10 |
+| `name` | string | 参数名称，模糊搜索 |
+| `code` | string | 参数编码，模糊搜索 |
+| `type` | int | 参数类型（0=系统 1=业务） |
+| `status` | int | 参数状态（1=正常 2=禁用） |
+
+## 与系统配置的区别
+
+| 特性 | 参数管理（Param） | 系统配置（Config） |
+|:----|:----|:----|
+| 用途 | 单个系统参数 | 配置分组 + 配置项 |
+| 结构 | 扁平（name+code+value） | 两级（config + config_item） |
+| 典型场景 | 默认密码、功能开关 | SMTP 配置、站点信息 |
+
+## 总结
+
+参数管理模块是项目中典型的简单 CRUD 模块，核心特点：
+
+```
+1. 按编码取值：get_value_by_code() 供其他业务模块调用
+2. 模糊搜索：name/code 模糊搜索，type/status 等值搜索
+3. 唯一性校验：name 和 code 双重唯一性
+4. 软删除 + 状态过滤：自动过滤已删除和已禁用的参数
+```