简介
本文件为 DouPHP 表单收集系统的完整开发文档，面向开发者说明表单构建器、字段类型管理、表单验证规则、数据提交处理等核心功能的技术实现；并覆盖动态表单生成、条件显示逻辑、文件上传处理、数据导出分析、权限控制、防重复提交、数据备份恢复等高级特性；同时提供自定义字段类型、集成第三方 API、工作流自动化、数据分析报表与实时监控等企业级能力的扩展方案。
项目结构
表单模块采用前后端分离的控制器与服务层设计：
- 后台管理：负责表单定义、元素（字段）配置、数据查看与管理。
- 前台展示：负责表单列表、详情渲染、数据提交与结果反馈。
- 服务层：封装业务逻辑，包括表单与数据的增删改查、数据格式化、分页与导航等。
- 模型层：ORM 映射到数据库表 form、form_data、form_elements。
- 请求校验：使用 Request 类进行参数校验与清洗。
- 视图层：后台模板 form.htm，前台模板 form.dwt。
graph TB
subgraph "后台"
AC["Admin FormController"]
ASvc["Admin FormService"]
AModel["Form / FormData / FormElements"]
AReq["FormFormRequest / FormElementsFormRequest"]
AView["admin/view/form.htm"]
end
subgraph "前台"
FC["Front FormController"]
FSvc["Front FormService"]
FReq["FormSubmitFormRequest"]
FView["theme/default/form.dwt"]
end
subgraph "核心能力"
CoreSvc["Core FormService(工具)"]
Attach["附件存储"]
XSS["XSS过滤"]
Audit["审计日志"]
end
AC --> ASvc
ASvc --> AModel
AC --> AReq
AC --> AView
FC --> FSvc
FC --> FReq
FC --> FView
ASvc --> CoreSvc
FSvc --> CoreSvc
ASvc --> Attach
ASvc --> XSS
AC --> Audit核心组件
- 后台控制器：提供表单 CRUD、元素管理、数据列表与详情查看、状态切换与删除等操作入口。
- 前台控制器：提供表单列表、详情渲染、提交处理与结果跳转。
- 后台服务：封装表单与元素的数据操作、数据格式化、分页、图片上传、编辑面板数据组装等。
- 前台服务：负责获取表单详情、渲染所需数据、调用核心工具进行提交处理。
- 核心服务：提供通用能力，如元素列表获取、数据框格式化、表单列表等。
- 模型：Form、FormData、FormElements 对应三张核心表。
- 请求校验：对表单定义、元素配置、前台提交数据进行严格校验。
- 视图：后台 form.htm 用于表单与元素编辑、数据查看；前台 form.dwt 用于用户填写与提交。
架构总览
表单系统遵循 MVC + Service 的分层架构：
- 控制器接收请求，委托服务完成业务逻辑。
- 服务层组合 ORM、附件、XSS、审计等基础设施能力。
- 模型层通过 ORM 访问数据库。
- 视图层渲染页面。
sequenceDiagram
participant U as "用户"
participant FCtrl as "前台控制器"
participant FReq as "前台请求校验"
participant FService as "前台服务"
participant Core as "核心服务"
participant DB as "数据库"
U->>FCtrl : 访问表单详情页
FCtrl->>FService : getShowPageData(id)
FService-->>FCtrl : 返回表单与字段配置
FCtrl-->>U : 渲染表单页面
U->>FCtrl : 提交表单
FCtrl->>FReq : validated()
FReq-->>FCtrl : 校验通过/错误
FCtrl->>FService : processSubmit(formId, data, ip)
FService->>Core : 解析字段/校验/持久化
Core->>DB : 写入数据
DB-->>Core : 成功
Core-->>FService : 结果
FService-->>FCtrl : 结果(跳转/消息)
FCtrl-->>U : 提示或跳转详细组件分析
后台表单管理
- 表单列表：支持关键词搜索、分页、状态显示、外链预览。
- 新增/编辑：内容经 XSS 过滤，支持主图上传，更新时保留原记录。
- 删除：二次确认，删除前清理关联图片，记录审计日志。
- 元素管理：支持新增、编辑、删除字段元素，包含名称、标识、类型、单位、排序、必填、选项等。
- 数据管理：按表单筛选、关键词搜索、分页、查看详情（自动标记已读）、状态切换、删除。
flowchart TD
Start(["进入后台表单页"]) --> List["加载表单列表"]
List --> Create{"新建表单?"}
Create -- 是 --> New["创建表单记录<br/>XSS过滤内容<br/>可选上传主图"]
Create -- 否 --> Edit["编辑表单"]
New --> Elements["添加/编辑字段元素"]
Edit --> Elements
Elements --> DataList["查看表单数据"]
DataList --> Detail["查看详情(标记已读)"]
Detail --> Toggle["切换状态/删除"]
Toggle --> End(["完成"])前台表单展示与提交
- 列表页：分页展示可用表单。
- 详情页：根据表单配置动态渲染字段，支持富文本内容与图片。
- 提交处理：请求层校验后，交由服务处理，支持错误回显、成功跳转。
sequenceDiagram
participant C as "浏览器"
participant Ctrl as "前台控制器"
participant Req as "请求校验"
participant Svc as "前台服务"
participant Core as "核心服务"
participant DB as "数据库"
C->>Ctrl : GET /form/{id}
Ctrl->>Svc : getShowPageData(id)
Svc-->>Ctrl : 表单+字段配置
Ctrl-->>C : 渲染表单
C->>Ctrl : POST /form/submit
Ctrl->>Req : validated()
Req-->>Ctrl : 校验通过
Ctrl->>Svc : processSubmit(form_id, post, ip)
Svc->>Core : 解析/校验/落库
Core->>DB : INSERT form_data
DB-->>Core : OK
Core-->>Svc : 结果
Svc-->>Ctrl : 结果(跳转/消息)
Ctrl-->>C : 成功提示或错误信息字段类型管理与动态渲染
- 支持的字段类型：输入框、下拉选择、多行文本、单选按钮等。
- 字段属性：名称、标识、类型、单位、排序、是否必填、选项配置。
- 动态渲染：基于字段配置在前台模板中动态生成表单控件，支持条件显示与校验提示。
classDiagram
class Form {
+int id
+string name
+string slug
+text content
+string image
+string back_url
+int status
+datetime created_at
}
class FormElements {
+int id
+int form_id
+string name
+string slug
+string type
+string unit
+int sort
+string must_fill
+string option
}
class FormData {
+int id
+int form_id
+text data_box
+string ip
+int if_read
+int status
+datetime created_at
}
Form "1" --> "many" FormElements : "拥有多个字段"
Form "1" --> "many" FormData : "产生多条数据"表单验证规则与数据提交处理
- 后台请求校验：表单定义与元素配置的参数校验。
- 前台请求校验：提交数据的合法性校验，错误时回显。
- 提交处理：将数据序列化存储至 data_box，支持后续格式化展示与导出。
flowchart TD
In["接收提交数据"] --> Validate["请求层校验"]
Validate --> |通过| Persist["序列化并保存数据"]
Validate --> |失败| Error["返回错误信息"]
Persist --> Format["格式化data_box用于展示"]
Format --> Done["完成"]文件上传处理
- 后台新增/编辑表单支持主图上传，使用附件服务存储，并更新记录中的图片路径。
- 上传过程绑定主键与上传者信息，便于追踪与清理。
数据导出与分析
- 数据列表支持按表单筛选与关键词搜索，便于快速定位。
- 数据详情可格式化展示，便于人工核对与导出。
- 可通过核心服务的格式化方法将 data_box 转换为可读结构，结合后台导出工具实现 CSV/Excel 导出。
权限控制与安全机制
- 后台路由受权限中间件保护，仅授权管理员可访问。
- 内容写入前进行 XSS 过滤，防止脚本注入。
- 删除操作二次确认，避免误删。
- 审计日志记录关键操作（创建、更新、删除），便于追溯。
防重复提交
- 前台提交由请求层校验，结合服务端处理逻辑确保幂等。
- 可在前台模板中禁用重复提交按钮或使用令牌机制增强防护。
数据备份与恢复
- 表单数据存储在数据库中，可通过系统备份工具进行整体备份与恢复。
- 建议定期备份数据库，并在变更表单结构前先行备份。
依赖关系分析
- 控制器依赖服务层，服务层依赖模型与核心工具。
- 前台与后台共享核心服务能力，保证行为一致。
- 附件、XSS、审计等横切能力在服务层统一接入。
graph LR
AdminCtrl["后台控制器"] --> AdminSvc["后台服务"]
FrontCtrl["前台控制器"] --> FrontSvc["前台服务"]
AdminSvc --> Models["Form / FormData / FormElements"]
FrontSvc --> CoreSvc["核心服务"]
AdminSvc --> CoreSvc
AdminSvc --> Attach["附件存储"]
AdminSvc --> XSS["XSS过滤"]
AdminCtrl --> Audit["审计日志"]性能与扩展性
- 分页查询：列表与数据列表均使用分页，减少内存占用。
- 懒加载：仅在需要时格式化 data_box，提升列表性能。
- 索引建议：为 form_id、created_at 建立索引以优化查询。
- 扩展点：
- 自定义字段类型：在元素类型枚举中新增类型，并在前台模板中增加渲染逻辑。
- 第三方 API 集成：在前台服务提交处理中调用外部接口，实现通知或同步。
- 工作流自动化：在服务层插入钩子，触发邮件、短信或站内信。
故障排查指南
- 表单无法显示：检查路由与控制器是否正确，确认表单状态为启用。
- 提交报错：查看请求校验错误信息，确认字段必填与格式。
- 数据未保存：检查服务层是否成功持久化，查看数据库连接与事务。
- 图片不显示：确认附件存储路径与权限，检查记录中的图片字段。
- 审计日志缺失：确认管理员登录态与审计服务可用性。
结论
DouPHP 表单收集系统提供了完整的表单定义、字段管理、数据提交与后台管理能力，具备安全、可扩展与易用的特点。通过服务层抽象与核心工具复用，开发者可快速定制字段类型、集成第三方服务、实现工作流自动化与企业级数据分析与监控。
附录：开发示例与最佳实践
自定义表单字段类型
- 步骤：
- 在元素类型列表中新增类型标识。
- 在前台模板中为该类型编写渲染逻辑。
- 在后端服务中确保该类型的选项与校验规则正确。
- 参考位置：
- 元素类型定义与编辑面板：admin/service/form/FormService.php:343-399
- 前台模板渲染：theme/default/form.dwt
集成第三方 API
- 在前台服务提交处理成功后，调用外部接口（如 CRM、邮件、短信）。
- 注意异常处理与重试机制，避免影响主流程。
- 参考位置：
- 前台提交处理入口：front/controller/form/FormController.php:130-156
实现表单工作流自动化
- 在服务层插入钩子，触发后续动作（如审核、通知、归档）。
- 结合状态字段与后台状态切换，实现简单工作流。
- 参考位置：
- 数据状态切换：admin/service/form/FormService.php:317-328
数据分析与报表生成
- 使用数据列表与格式化能力，导出数据为 CSV/Excel。
- 可按表单、时间范围、关键词筛选，生成统计报表。
- 参考位置：
- 数据列表与格式化：admin/service/form/FormService.php:243-296
- 数据详情格式化：admin/service/form/FormService.php:298-315
实时监控
- 结合审计日志与状态切换，监控表单使用情况。
- 可在后台增加仪表盘，展示提交量、成功率、异常率等指标。
- 参考位置：
- 审计日志记录：admin/controller/form/FormController.php:113-122