# 表单引擎（Form Engine）

> **负责人**: FFOA 开发团队  
> **状态**: 🟢 Active  
> **最后更新**: 2025-12-25

---

## 📋 文档导航

| 文档 | 状态 | 最后更新 |
|------|------|---------|
| [产品需求文档](./01-prd.md) | ✅ | 2025-12-07 |
| [用户场景文档](./02-user-journey.md) | 🚧 | 2026-01-11 |
| [架构设计](./03-architecture.md) | ✅ | 2025-12-04 |
| [UI 交互规范](./05-ui-interaction-spec.md) | ✅ | 2025-12-25 |
| [数据模型](./06-data-model.md) | 🚧 | 2026-01-11 |
| [API 文档](./07-api.md) | ✅ | 2025-12-04 |
| [错误码](./08-error-codes.md) | 🚧 | 2026-01-11 |
| [测试场景](./09-test-scenarios.md) | 🚧 | 2026-01-11 |
| [开发路线图](./10-roadmap.md) | ✅ | 2025-12-14 |
| [变更日志](./99-changelog.md) | ✅ | 2025-12-04 |

**状态说明**:
- ✅ Completed/Approved - 已完成并通过评审
- 🚧 In Progress/Draft - 编写中
- ❌ Not Started - 未开始
- 📝 Need Update - 需要更新

---

## 📌 概述

表单引擎是 FFOA 平台的核心数据收集和管理模块，提供动态表单管理系统，支持可视化设计、JSON Schema 驱动、版本管理和审批流集成。

### 核心功能

1. **表单定义管理** - 创建、编辑、删除、发布表单
2. **可视化拖拽设计器** - 拖拽添加字段、配置属性、实时预览
3. **版本管理** - 多版本共存、版本回滚、版本审核
4. **表单实例管理** - 表单填写、提交、查询、导出
5. **动态渲染** - 基于 JSON Schema 的前端动态渲染
6. **多语言支持** - 字段标签、选项、提示的多语言翻译
7. **审批流集成** - 与审批引擎深度集成，支持审批流程
8. **模板系统** - 预设常用表单模板，快速创建

### 业务价值

- 统一数据收集入口，规范数据格式
- 可视化设计降低表单创建成本
- 版本管理保证表单结构可追溯
- 审批集成实现业务流程闭环
- 支持复杂业务场景（KPI、OKR等）

---

## 🏗️ 技术信息

### 代码位置

- **前端**: 
  - `frontend/src/app/(engines)/forms/` - 表单管理页面
  - `frontend/src/app/(engines)/forms/definitions/[id]/design/` - 可视化设计器
  - `frontend/src/features/forms/components/FormRenderer.tsx` - 表单渲染器
  - `frontend/src/features/forms/components/designer/` - 设计器组件
- **后端**: `backend/src/form-engine/`
- **数据库**: `platform_form` Schema

### API 端点

- **Base URL**: `/api/v1/forms`
- **主要接口组**: 
  - 表单定义管理（12个接口）
  - 表单版本管理（10个接口）
  - 表单实例管理（12个接口）
  - 表单翻译管理（6个接口）
  - 表单模板管理（6个接口）
  - 版本审核管理（4个接口）
- **总计**: 50+ 个接口

### 技术栈

- **前端**: Next.js 14 + TypeScript + Tailwind CSS + shadcn/ui
- **拖拽库**: @dnd-kit/core + @dnd-kit/sortable
- **状态管理**: Zustand
- **后端**: NestJS + Prisma + PostgreSQL
- **Schema**: JSON Schema Draft 7

---

## 🔗 相关模块

- [审批引擎](../approval-engine/README.md) - 审批流集成
- [表单管理](../form-management/README.md) - 表单业务配置
- [权限系统](../organization/README.md) - RBAC 权限控制

---

## 🚀 快速开始

### 1. 创建表单

```
访问: /forms/definitions
操作: 点击「创建表单」→ 填写基本信息 → 保存
```

### 2. 设计表单

```
访问: /forms/definitions/[id]/design
操作: 从左侧拖拽字段 → 配置属性 → 保存
```

### 3. 发布表单

```
访问: /forms/definitions
操作: 找到表单 → 操作菜单 → 发布
```

### 4. 填写表单

```
访问: /forms/instances
操作: 点击表单 → 填写内容 → 提交
```

---

## 🎯 功能状态

| 功能 | 状态 | 说明 |
|------|------|------|
| 表单定义管理 | ✅ | 完整的 CRUD 操作 |
| 可视化拖拽设计器 | ✅ | 15 种字段类型，撤销/重做 |
| 版本管理 | ✅ | 多版本共存，版本回滚 |
| 表单实例管理 | ✅ | 提交、查询、导出 |
| 动态渲染 (JSON Schema) | ✅ | 基于 Schema 的前端渲染 |
| 多语言支持 | ✅ | 字段翻译管理 |
| 审批流集成 | ✅ | 深度集成审批引擎 |
| 模板系统 | 🚧 | 80% 完成 |
| 计算字段 | 📋 | 待开发 |
| 条件显示 | 📋 | 待开发 |

---

## 📊 API 统计

| 模块 | 接口数量 |
|------|----------|
| 表单定义管理 | 12 |
| 表单版本管理 | 10 |
| 表单实例管理 | 12 |
| 表单翻译管理 | 6 |
| 表单模板管理 | 6 |
| 版本审核管理 | 4 |
| **总计** | **50** |

---

## 🎨 支持的字段类型

### 基础字段（8种）
- Text - 单行文本
- Textarea - 多行文本
- Number - 数字
- Select - 下拉选择
- Radio - 单选
- Checkbox - 多选
- Date - 日期
- File - 文件上传

### 高级字段（7种）
- Email - 邮箱
- Phone - 电话
- URL - 网址
- Rating - 评分
- Switch - 开关
- Slider - 滑块
- Detail - 明细表格（支持子字段配置）

---

## 🧪 测试

详见测试用例文档（待补充）

---

## 📚 详细文档

- [产品需求文档](./01-prd.md) - 完整功能需求、用户故事
- [架构设计](./03-architecture.md) - 核心概念、数据库设计
- [UI 交互规范](./05-ui-interaction-spec.md) - 页面设计、交互细节
- [API 文档](./07-api.md) - 接口定义、请求响应
- [开发路线图](./10-roadmap.md) - 进度跟踪、待办事项
- [变更日志](./99-changelog.md) - 版本历史记录

---

## 👥 贡献者

- **创建者**: FFOA Team
- **维护者**: Backend Team

---

**创建时间**: 2025-11-20  
**更新时间**: 2025-12-25  
**状态**: ✅ 生产就绪  
**版本**: v1.1