数据库核心表结构说明 #

Tduck 开源社区版的表单设计核心机制是基于“文档型”设计思想（使用关系型数据库 MySQL 存储 JSON Schema 字段），这使它具有极高的灵活性。

根据官方数据库初始化脚本 tduck-v6.sql，本节为您梳理系统中最关键的几张核心数据库表及相互关系。

🔑 1. 核心表一览 #

👤 用户账号表：ac_user #

存储后台管理用户的账户和安全验证信息。

• id (Bigint, PK)：用户唯一ID
• name (String)：用户姓名
• email (String)：登录邮箱（也是核心账号）
• phone_number (String)：手机号
• password (String)：加密后的密码 (基于 BCrypt 强哈希加密)
• avatar (String)：头像 URL 地址
• deleted (Boolean)：软删除状态（代替传统的状态禁用）

📝 用户表单表：fm_user_form #

存储用户创建的每一个表单/问卷的基本信息（元数据）。

• id (Bigint, PK)：主键ID
• form_key (String, Unique)：表单唯一标识 key（一般为一段随机字符串，如 RWGsm4AR，用于前端路由和访问）
• name (Text)：表单名称（标题）
• description (Text)：表单描述或填写寄语
• user_id (Bigint)：创建该表单的管理员ID (ac_user.id)
• type (String)：表单类型
• status (Tinyint)：状态 (1: 草稿, 2: 收集中, 3: 停止收集)
• is_deleted (Boolean)：是否已删除（存入回收站）

🧱 表单项定义配置表：fm_user_form_item #

存储单个表单内拖拽生成的具体组件定义（如输入框、单选按钮等）。

• id (Bigint, PK)
• form_key (String)：所属表单的 form_key
• form_item_id (String)：组件在表单内的唯一逻辑ID（如 field101）
• type (String)：表单项类型（如 input, select, checkbox, rate）
• label (Text)：表单项标题（如 “您的姓名”）
• required (Boolean)：是否必填
• placeholder (String)：输入框的提示文字
• scheme (Json)：核心字段。存储该组件最原始的前端 JSON 配置数据。
• reg_list (Json)：绑定的正则表达式校验规则列表。
• span (Integer)：栅格宽度（如 24 代表整行，12 代表半行）
• sort (Bigint)：排序权重，用于前端顺序渲染

📊 表单收集数据结果表：fm_user_form_data #

用于记录提交回来的问卷答案和数据，是收集到的数据的存储核心。

• id (Bigint, PK)
• form_key (String)：对应的表单 form_key
• serial_number (Integer)：提交序号（自增编号）
• original_data (Json)：核心字段。所有用户填写的表单数据，前端将其序列化为 Map 并以原生 JSON 格式保存在此字段。
  • 存储样例：{"field101": "张三", "field102": "男", "field103": ["篮球", "音乐"]}
• submit_request_ip (String)：提交者的 IP 地址
• submit_address (String)：基于 IP 解析出的地理位置
• submit_os (String)：提交者所使用的操作系统类型
• submit_browser (String)：提交者所使用的浏览器类型
• submit_ua (Json)：完整的用户代理 (User-Agent) 原始 JSON 数据
• complete_time (Integer)：用户填写并完成表单消耗的时间（单位：毫秒）
• wx_open_id (String)：微信环境内提交时的微信 OpenID（配合公众号授权使用）
• wx_user_info (Json)：微信用户的昵称、头像等原始 JSON 信息

🎨 表单个性化主题配置表：fm_user_form_theme #

存储用户对表单的个性化主题外观设置。

• id (Bigint, PK)
• form_key (String)：关联的表单 form_key
• theme_color (String)：主题的颜色代码
• logo_img (String)：LOGO 图片的地址
• logo_position (String)：LOGO 在页面中的显示位置
• background_color (String)：背景颜色
• background_img (String)：背景图片的 URL
• head_img_url (String)：头部海报/头图的地址
• submit_btn_text (String)：提交按钮上的自定义文字
• show_title (Boolean)：是否显示标题
• show_describe (Boolean)：是否显示描述语
• show_number (Boolean)：是否在问题前显示自动序号

⚙️ 系统环境配置表：sys_env_config #

存储系统全局参数，采用 JSON 格式存储值。

• id (Bigint, PK)
• env_key (String)：配置的 Key 值（如 fileEnvConfig、deepSeekEnvConfig）
• env_value (Json)：参数的具体配置，以原生 JSON 格式保存
• create_time / update_time：创建和更新时间

🔗 Webhook 配置表：webhook_config #

存储用户为表单配置的外部数据推送（Webhook）目标地址及触发事件。

• id (Bigint, PK)
• hook_name (String)：配置的友好显示名称
• source_type (String)：来源类型（如 FORM）
• source_id (String)：来源的唯一 ID（一般对应 form_key）
• url (String)：接口推送接收方的 HTTP/HTTPS 目标地址
• request_type (String)：请求类型（如 POST）
• enabled (Boolean)：是否启用推送

📦 Webhook 事件记录表：webhook_event #

记录 Webhook 推送的流水账，包括失败重试次数、最后一次错误信息等。

• id (Bigint, PK)
• webhook_config_id (Bigint)：关联的配置 ID (webhook_config.id)
• source_id (String)：对应的数据主键 ID
• event_type (String)：触发事件（如 CREATE、UPDATE、DELETE）
• event_data (Text)：推送出去的 JSON 数据包
• status (String)：状态（pending、success、failed）
• retry_times (Integer)：已重试次数
• last_error (Text)：最近一次发送失败的异常堆栈信息

🔄 2. 数据流动与保存关系 #

当一个最终用户填写并提交一个表单时，系统的数据流向如下：

graph TD
    User([用户在前端填写并提交]) --> |POST 请求 /user/form/data/public/create| API[tduck-api 接收参数]
    API --> |解析与校验| Service[tduck-form 业务层]
    Service --> |将提交的表单项提取为 JSON Map| DB[(fm_user_form_data 结果表)]
    DB --> |以 original_data JSON 原生格式存储| Result[完成归档并提供给管理后台进行数据清洗与导出]