ZQ Platform

主题

表单管理模块 ​

概述 ​

表单管理模块是低代码平台的核心，提供可视化表单设计、动态数据操作、权限控制等功能。分为两个子模块：

  • form_manager：表单元数据管理（设计、发布）
  • form_data_manager：表单数据动态操作（CRUD）

模块路径 ​

子模块路径API 前缀
表单元数据backend-fastapi/core/form_manager//api/core/form
表单数据backend-fastapi/core/form_data_manager//api/core/form-data

数据模型 ​

FormMeta（表单元数据） ​

python
class FormMeta(BaseModel):
    __tablename__ = "core_form_meta"

    application_id: str     # 所属应用 ID
    name: str               # 表单名称
    code: str               # 表单编码（唯一）
    form_type: str          # 表单类型
    status: str             # 状态
    version: int            # 版本号
    db_config: str          # 数据库连接配置
    main_table: str         # 主表名
    main_table_schema: str  # 主表 Schema
    main_table_database: str # 主表数据库
    form_config: dict       # 表单配置（JSONB）
    list_config: dict       # 列表配置（JSONB）

FormSubTable（子表关联） ​

python
class FormSubTable(BaseModel):
    __tablename__ = "core_form_sub_table"

    form_id: str            # 表单 ID
    table_name: str         # 子表名
    table_schema: str       # 子表 Schema
    table_database: str     # 子表数据库
    alias: str              # 别名
    foreign_key: str        # 外键字段
    related_field: str      # 关联字段
    relation_type: str      # 关联类型

表单类型 (form_type) ​

值说明
normal普通表单
workflow流程表单

表单状态 (status) ​

值说明
draft草稿
published已发布

服务层 ​

FormService（表单元数据服务） ​

静态方法类，提供以下功能：

CRUD 操作 ​

方法说明
list(db, page, page_size, filters)获取表单列表（带应用名称）
get(db, form_id)获取表单详情
get_by_code(db, code)根据编码获取
create(db, data)创建表单（含子表）
update(db, form_id, data)更新表单（子表先删后建）
delete(db, form_id)删除表单（物理删除）
batch_delete(db, ids)批量删除

发布管理 ​

方法说明
publish(db, form_id, data)发布表单
unpublish(db, form_id)停用表单
copy(db, form_id)复制表单

导入导出 ​

方法说明
export_config(db, form_id)导出配置（JSON）
import_config(db, data)导入配置（JSON）

发布时自动创建 ​

发布表单时自动创建以下资源：

  1. 菜单：path=/form-render/{code}，type=online_form
  2. 权限：6 种操作权限
  3. 资源注册：字段元数据注册
权限编码说明
form:{code}:view查看
form:{code}:add新增
form:{code}:edit编辑
form:{code}:delete删除
form:{code}:export导出
form:{code}:import导入

FormDataService（表单数据服务） ​

工厂模式，通过 create_service(db, form_code) 创建实例。

数据查询 ​

方法说明
list(db, page, page_size, filters, sort)分页查询（含数据权限）
get(db, pk)获取详情（含子表）
get_field_values(db, field, search)获取字段唯一值列表

数据写入 ​

方法说明
create(db, data)创建（主表+子表）
update(db, pk, data)更新（子表差异更新）
delete(db, pk)删除（子表+主表）
batch_delete(db, pks)批量删除

导入导出 ​

方法说明
export_to_excel(db, filters, fields)导出 Excel
get_import_template(db)获取导入模板
import_from_excel(db, file)从 Excel 导入

内部处理 ​

方法说明
_get_allowed_fields()获取字段白名单
_fill_system_fields_for_create()填充创建系统字段
_fill_system_fields_for_update()填充更新系统字段
_apply_data_scope_filter_safe()应用数据权限过滤
_fill_relation_display_names()填充关联字段显示名
_fill_virtual_fields()填充虚拟字段
apply_field_permissions()应用字段权限

DynamicSQLBuilder ​

动态 SQL 构建器，适配 PostgreSQL/MySQL：

方法说明
build_select(table, fields, where, order, limit)构建 SELECT
build_count(table, where)构建 COUNT
build_insert(table, data)构建 INSERT
build_update(table, data, where)构建 UPDATE
build_delete(table, where)构建 DELETE

WHERE 条件支持：eq、ne、gt、gte、lt、lte、like、in、range、null、not_null

API 接口 ​

表单元数据 API ​

方法路径说明
GET/list获取表单列表
GET/form-types获取表单类型
GET/published/simple获取已发布表单（下拉用）
GET/{id}获取表单详情
GET/code/{code}根据编码获取
POST/创建表单
PUT/{id}更新表单
DELETE/{id}删除表单
DELETE/batch/delete批量删除
POST/{id}/publish发布表单
POST/{id}/unpublish停用表单
POST/{id}/copy复制表单
GET/{id}/export导出配置
POST/import导入配置

表单数据 API ​

方法路径说明
GET/{code}/permissions获取操作权限
GET/{code}/field-permissions获取字段权限
GET/{code}/list获取数据列表
GET/{code}/field-values/{field}获取字段值列表
GET/{code}/detail/{pk}获取数据详情
POST/{code}创建数据
PUT/{code}/{pk}更新数据
DELETE/{code}/{pk}删除数据
DELETE/{code}/batch/delete批量删除
POST/{code}/export/task导出 Excel
GET/{code}/import/template下载导入模板
POST/{code}/import/excel导入 Excel

配置结构 ​

form_config（表单配置） ​

json
{
  "items": [...],           // 表单项数组
  "tableConfigs": [...],    // 表配置（字段类型映射）
  "labelWidth": 120,        // 标签宽度
  "labelPosition": "right", // 标签位置
  "size": "default",        // 尺寸
  "formPadding": 20,        // 表单内边距
  "formMargin": 0,          // 表单外边距
  "itemSpacing": 16,        // 项间距
  "formWidth": "100%",      // 表单宽度
  "formMaxWidth": "none",   // 最大宽度
  "formBackground": "#fff", // 背景色
  "formBorder": "none",     // 边框
  "formBorderRadius": 0,    // 圆角
  "formShadow": "none"      // 阴影
}

list_config（列表配置） ​

json
{
  "columns": [...],         // 列配置
  "queryFields": [...],     // 查询字段
  "buttons": {              // 按钮配置
    "showAdd": true,
    "showEdit": true,
    "showDelete": true,
    "showView": true,
    "showExport": true,
    "showImport": true,
    "showBatchDelete": true
  },
  "listType": "table",      // 列表类型（table/card）
  "containerType": "drawer", // 容器类型
  "table": {...},           // 表格配置
  "card": {...},            // 卡片配置
  "dialog": {...},          // 弹窗配置
  "drawer": {...},          // 抽屉配置
  "subTableButtons": [...], // 子表按钮
  "customButtons": [...]    // 自定义按钮
}

权限控制 ​

三级权限体系 ​

  1. 操作权限：控制用户能执行哪些操作
  2. 数据权限：控制用户能看到哪些数据
  3. 字段权限：控制用户能看到哪些字段

数据权限类型 ​

scope_type说明
all全部数据
self仅本人创建的数据
dept本部门数据
dept_and_children本部门及子部门数据
custom自定义部门范围

字段权限级别 ​

级别说明
write可读写
read只读
hidden隐藏
masked脱敏

请求/响应示例 ​

创建表单数据 ​

请求：

json
POST /api/core/form-data/order
{
  "order_no": "ORD001",
  "customer_name": "张三",
  "amount": 1000.00,
  "items": [
    {"product": "商品A", "qty": 2, "price": 300},
    {"product": "商品B", "qty": 1, "price": 400}
  ]
}

查询表单数据 ​

请求：

GET /api/core/form-data/order/list?page=1&pageSize=20&filter_status=pending&sort=-sys_create_datetime

响应：

json
{
  "items": [...],
  "total": 100
}

与其他模块的关系 ​

  • 菜单模块：发布时创建 online_form 类型菜单
  • 权限模块：发布时创建 6 种操作权限
  • 工作流模块：流程表单关联工作流定义
  • 资源注册：发布时注册字段元数据（用于数据权限/字段权限配置）

Released under the MIT License.

Copyright © 2024-present JZKJ