签入版本
This commit is contained in:
@@ -0,0 +1,191 @@
|
||||
:::tip 案例演示
|
||||
案例演示模块是代码生成器的参考模板，展示了标准 CRUD 模块的完整实现。包含文件字段处理、枚举字典映射、状态管理等功能，可作为新模块开发的参考范例。
|
||||
:::
|
||||
|
||||
## 模块结构
|
||||
|
||||
```
|
||||
src/modules/example/
|
||||
├── models.py # 案例模型
|
||||
├── schema.py # 表单验证（WTForms）
|
||||
├── repository.py # 数据访问层
|
||||
├── service.py # 业务逻辑层（继承 BaseService）
|
||||
└── router.py # 路由控制器
|
||||
```
|
||||
|
||||
## 案例模型
|
||||
|
||||
```python
|
||||
# src/modules/example/models.py
|
||||
class Example(BaseModel, BaseDB):
|
||||
"""
|
||||
案例演示模型
|
||||
|
||||
包含文件字段（avatar）、枚举字段（type/status）等典型业务字段。
|
||||
"""
|
||||
__tablename__ = DB_PREFIX + "example"
|
||||
__table_comment__ = "案例演示表"
|
||||
|
||||
# 案例名称
|
||||
name = db.Column(db.String(255), nullable=False, index=True, comment="案例名称")
|
||||
# 案例图片（存相对路径）
|
||||
avatar = db.Column(db.String(255), nullable=False, comment="案例图片")
|
||||
# 案例类型：1-类型1 2-类型2 3-类型3 4-类型4
|
||||
type = db.Column(db.Integer, nullable=True, default=0, server_default=text('0'),
|
||||
comment="案例类型：1-类型1 2-类型2 3-类型3 4-类型4")
|
||||
# 案例状态：1-在用 2-停用
|
||||
status = db.Column(db.Integer, nullable=True, default=0, server_default=text('0'),
|
||||
index=True, comment="案例状态：1-在用 2-停用")
|
||||
# 排序
|
||||
sort = db.Column(db.Integer, nullable=True, default=0, server_default=text('0'),
|
||||
comment="案例排序")
|
||||
```
|
||||
|
||||
## 服务层实现
|
||||
|
||||
```python
|
||||
# src/modules/example/service.py
|
||||
class ExampleService(BaseService):
|
||||
"""
|
||||
案例演示服务类
|
||||
|
||||
展示文件字段处理、枚举映射等标准 CRUD 模式。
|
||||
"""
|
||||
repository = ExampleRepository
|
||||
form = ExampleForm
|
||||
status_form = ExampleStatusForm
|
||||
model_name = "案例演示"
|
||||
|
||||
@classmethod
|
||||
def before_add(cls, form):
|
||||
"""新增前钩子：处理文件字段"""
|
||||
_handle_file_fields(form)
|
||||
|
||||
@classmethod
|
||||
def before_update(cls, form, obj):
|
||||
"""更新前钩子：处理文件字段"""
|
||||
_handle_file_fields(form)
|
||||
|
||||
@classmethod
|
||||
def _enrich_page_records(cls, records):
|
||||
"""分页富化：文件字段拼接 URL"""
|
||||
for data in records:
|
||||
data["avatar"] = get_file_url(data.get("avatar"))
|
||||
return records
|
||||
|
||||
@classmethod
|
||||
def _detail_dict(cls, obj):
|
||||
"""详情序列化：文件字段拼接 URL"""
|
||||
data = model_to_dict(obj)
|
||||
data["avatar"] = get_file_url(data.get("avatar"))
|
||||
return data
|
||||
|
||||
|
||||
def _handle_file_fields(form):
|
||||
"""文件字段处理：临时文件迁移到正式目录"""
|
||||
avatar = form.data.get("avatar")
|
||||
if avatar:
|
||||
form.avatar.data = save_file(avatar, "example")
|
||||
```
|
||||
|
||||
### 文件字段处理模式
|
||||
|
||||
这是项目中处理文件字段的标准模式：
|
||||
|
||||
| 步骤 | 时机 | 处理 |
|
||||
|:---|:---|:---|
|
||||
| 1. 前端上传 | 用户选择文件 | 上传到临时目录，获得临时 URL |
|
||||
| 2. 提交表单 | 前端提交 | 将临时 URL 传给后端 |
|
||||
| 3. `before_add`/`before_update` | Service 钩子 | `save_file` 迁移到正式目录 |
|
||||
| 4. 存储数据库 | Repository.create | 存相对路径 |
|
||||
| 5. 查询返回 | `_detail_dict`/`_enrich_page_records` | `get_file_url` 拼接完整 URL |
|
||||
|
||||
### 枚举字段映射
|
||||
|
||||
通过 `serialize_maps` 声明枚举字段与字典编码的映射：
|
||||
|
||||
```python
|
||||
class ExampleService(BaseService):
|
||||
serialize_maps = {
|
||||
'type': 'example_type', # 案例类型 → 数据字典
|
||||
'status': 'example_status' # 案例状态 → 数据字典
|
||||
}
|
||||
```
|
||||
|
||||
查询结果自动包含 `typeText` 和 `statusText` 字段。
|
||||
|
||||
## 表单验证
|
||||
|
||||
```python
|
||||
# src/modules/example/schema.py
|
||||
class ExampleForm(BaseForm):
|
||||
"""案例创建/编辑表单"""
|
||||
name = StringField('案例名称', validators=[
|
||||
DataRequired(message='案例名称不能为空'),
|
||||
Length(max=255, message='案例名称长度不得超过255个字符')
|
||||
])
|
||||
avatar = StringField('案例图片', validators=[Optional(), Length(max=255)])
|
||||
type = IntegerField('案例类型', validators=[
|
||||
Optional(), NumberRange(min=1, max=4, message='案例类型值在1~4之间')
|
||||
])
|
||||
status = IntegerField('案例状态', validators=[
|
||||
Optional(), NumberRange(min=1, max=2, message='案例状态值在1~2之间')
|
||||
])
|
||||
sort = IntegerField('案例排序', validators=[
|
||||
Optional(), NumberRange(min=0, max=99999)
|
||||
])
|
||||
|
||||
def validate_name(self, field):
|
||||
"""案例名称唯一性校验"""
|
||||
if not field.data:
|
||||
return
|
||||
current_id = self.id.data if self.id.data else None
|
||||
if ExampleRepository.exists_by({'name': field.data}, exclude_id=current_id):
|
||||
raise ValidationError("案例名称已存在")
|
||||
|
||||
|
||||
class ExampleStatusForm(BaseForm):
|
||||
"""案例状态更新表单"""
|
||||
id = IntegerField('案例ID', validators=[
|
||||
DataRequired(message='案例ID不能为空'),
|
||||
NumberRange(min=1, message='案例ID必须大于0')
|
||||
])
|
||||
status = IntegerField('案例状态', validators=[
|
||||
DataRequired(message='案例状态不能为空'),
|
||||
NumberRange(min=1, max=2, message='案例状态值在1~2之间')
|
||||
])
|
||||
```
|
||||
|
||||
## API 接口
|
||||
|
||||
| 方法 | 路径 | 权限节点 | 说明 |
|
||||
|:---|:---|:---|:---|
|
||||
| GET | `/api/v1/example/page` | `sys:example:page` | 分页查询 |
|
||||
| GET | `/api/v1/example/detail/<id>` | `sys:example:detail` | 详情查询 |
|
||||
| GET | `/api/v1/example/list` | `sys:example:list` | 列表查询（无分页） |
|
||||
| POST | `/api/v1/example/add` | `sys:example:add` | 新增案例 |
|
||||
| PUT | `/api/v1/example/update` | `sys:example:update` | 编辑案例 |
|
||||
| DELETE | `/api/v1/example/delete/<id>` | `sys:example:delete` | 删除案例 |
|
||||
| DELETE | `/api/v1/example/batchDelete` | `sys:example:batchDelete` | 批量删除 |
|
||||
| PUT | `/api/v1/example/status` | `sys:example:status` | 设置状态 |
|
||||
|
||||
## 数据字典
|
||||
|
||||
| 字典编码 | 用途 | 字典项示例 |
|
||||
|:---|:---|:---|
|
||||
| `example_type` | 案例类型名称 | 1=类型1, 2=类型2, 3=类型3, 4=类型4 |
|
||||
| `example_status` | 案例状态名称 | 1=在用, 2=停用 |
|
||||
|
||||
## 作为代码生成器参考
|
||||
|
||||
案例演示模块是代码生成器的参考模板，新模块开发时可参考其模式：
|
||||
|
||||
1. **模型定义**：继承 `BaseModel + BaseDB`，字段注释完整
|
||||
2. **表单验证**：继承 `BaseForm`，`validate_` 方法实现唯一性校验
|
||||
3. **数据访问**：继承 `BaseRepository`，实现 `page()` / `list_enabled()`
|
||||
4. **业务服务**：继承 `BaseService`，声明 `repository` / `form` / `model_name`
|
||||
5. **路由控制**：Blueprint + `@check_permission` + `@check_demo` + `@operation_log`
|
||||
|
||||
## 总结
|
||||
|
||||
案例演示模块是标准 CRUD 模块的参考范例，展示了文件字段处理（`save_file`/`get_file_url`）、枚举字典映射（`serialize_maps`）、状态管理（`update_status`）等典型模式。新模块开发或代码生成器生成的代码均以此模块为参考。
|
||||
Reference in New Issue
Block a user