# form-engine

**Repository Path**: zdyumath/form-engine

## Basic Information

- **Project Name**: form-engine
- **Description**: 个人表单引擎测试
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-30
- **Last Updated**: 2026-05-16

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# FormEngine · 项目文档

> 基于 [Claude Design 导出的设计稿](../.fetched/form-engine/) 演进而来的低代码表单引擎产品文档。
> 更新时间：2026-04-28

---

## 📚 文档目录

### 顶层 · 产品视角

| 文档 | 内容 | 适合谁看 |
|---|---|---|
| [01-需求文档.md](./01-需求文档.md) | 产品定位 / 用户角色 / 三大场景 / 8 大模块 / MVP 边界 / SDK 嵌入能力 | 产品 · 业务方 |
| [02-设计方案.md](./02-设计方案.md) ⭐ | **UI 视觉系统 + UE 交互细节 + 信息架构 + 关键场景 + 与 ADR-06 的关系** | UI/UE · 前端工程师 |
| [03-任务清单.md](./03-任务清单.md) | 已完成 · P0 · P1 · P2 · 路线图 · 完成度自检 | PM · 团队成员 |
| [Schema规范_v2.md](./Schema规范_v2.md) ⭐ | **唯一权威的 Schema 合同文档** — fields/layout/rules 三段式 + 控件清单 + 表达式规范 | 全员 |
| [form-schema.meta.json](./form-schema.meta.json) | 元规范（JSON Schema 自校验） | 引擎/校验器开发者 |

### 架构设计（10 + 1 文档）

| # | 文档 | 内容 |
|---|---|---|
| 00 | [00_索引.md](./架构设计/00_索引.md) | 文档间依赖图 + 阅读顺序 |
| 01 | [01_系统架构图.md](./架构设计/01_系统架构图.md) | C4 上下文 / 容器视图 / 模块视图 / 10 条 ADR |
| 02 | [02_数据模型设计.md](./架构设计/02_数据模型设计.md) | PostgreSQL DDL + 多租户 + jsonb 索引策略 |
| 03 | [03_API契约.md](./架构设计/03_API契约.md) | REST + OpenAPI 3.1 |
| 04 | [04_技术选型最终确认.md](./架构设计/04_技术选型最终确认.md) | 前后端版本号锁定 |
| 05 | [05_技术预研报告.md](./架构设计/05_技术预研报告.md) | 引擎内核 / SDK / jsonb 性能 |
| 06 | [06_Schema元规范实现.md](./架构设计/06_Schema元规范实现.md) | 元规范文件 + 前后端校验器 + 迁移管道 |
| 07 | [07_核心业务流程时序图.md](./架构设计/07_核心业务流程时序图.md) | 设计 → 发布 → 填报 → 审批 时序 |
| 08 | [08_安全架构.md](./架构设计/08_安全架构.md) | 鉴权 / 多租户 / 沙箱 / 审计 |
| 09 | [09_部署架构.md](./架构设计/09_部署架构.md) | Docker / K8s / 私有化部署 |
| 10 | [10_设计态与规范态转换.md](./架构设计/10_设计态与规范态转换.md) | designer-core/transform.ts 双向转换器 |

> 📐 **`04-技术架构.md` 已删除**：原内容与「架构设计」10 份文档重复；权威架构请直接看 `架构设计/`。

### 后端实施（执行计划）

| # | 文档 | 用途 |
|---|---|---|
| 00 | [00_决策冻结清单.md](./后端实施/00_决策冻结清单.md) | D-01~D-05 + 安全架构默认方案正式冻结 |
| 01 | [01_总览与计划.md](./后端实施/01_总览与计划.md) | 5 阶段甘特图 + 各阶段任务清单 + 横切关注 |
| 02 | [02_阶段0_执行前准备.md](./后端实施/02_阶段0_执行前准备.md) | 环境清单 / 仓库骨架 / 模板文件 / 5 天任务 |

---

## 🎯 关键产物速查

### 设计资产
- **设计系统 Skill**：[`~/.claude/skills/form-engine-design/SKILL.md`](../../.claude/skills/form-engine-design/SKILL.md) — 10 节复用指南
- **Design Tokens + 组件类**：[`src/styles.css`](../src/styles.css) — 完整 CSS 变量系统
- **图标库**：[`src/components/icons.jsx`](../src/components/icons.jsx) — 110+ Feather 风 SVG

### 应用入口
- **运行**：`npm install && npm run dev`，访问 `http://localhost:5177`
- **构建**：`npm run build`，输出 `dist/`
- **预览**：`npm run preview`

### 设计原稿
- 原始 HTML/CSS/JS：[`.fetched/form-engine/`](../.fetched/form-engine/)
- 设计师对话记录：[`.fetched/form-engine/chats/chat1.md`](../.fetched/form-engine/chats/chat1.md)

---

## 🗺 项目结构总览

```
D:\workcode\design\
├── docs/                          ← 本文档目录
│   ├── README.md                  ← 你在这里
│   ├── 01-需求文档.md
│   ├── 02-设计方案.md             ← UI/UE 重点
│   ├── 03-任务清单.md
│   ├── Schema规范_v2.md           ← Schema 合同文档
│   ├── form-schema.meta.json
│   └── 架构设计/                  ← 9 + 1 份架构文档
│       ├── 00_索引.md
│       ├── 01_系统架构图.md
│       ├── 02_数据模型设计.md
│       ├── 03_API契约.md
│       ├── 04_技术选型最终确认.md
│       ├── 05_技术预研报告.md
│       ├── 06_Schema元规范实现.md
│       ├── 07_核心业务流程时序图.md
│       ├── 08_安全架构.md
│       └── 09_部署架构.md
│
├── src/                           ← 视觉验证原型（React + Vite）
│   ├── main.jsx
│   ├── App.jsx
│   ├── styles.css
│   └── components/                ← 19 个模块
│
├── .fetched/                      ← 原始设计稿
├── CLAUDE.md                      ← 项目运行指引
├── package.json
├── vite.config.js
└── index.html
```

---

## 🎨 设计风格速记

> 完整内容见 [02-设计方案.md](./02-设计方案.md)。

**Style ID：清新爽朗 · 青蓝主题（fresh-airy-cyan）**

5 大设计原则：
1. **留白优先** — 极浅冷白底 + 大量空隙
2. **边线即结构** — 1px hairline，阴影只用于浮层
3. **冷静色彩** — 主色 cyan，语义色克制
4. **中性高对比** — 4 级灰阶，正文近黑非纯黑
5. **32px 节奏** — 一切尺寸围绕 32 hit target

**关键 token**：

```css
:root {
  --bg: #f6f9fb;          /* 应用底 */
  --bg-panel: #ffffff;    /* 卡片 */
  --ink-1: #0b1f2a;       /* 主文 */
  --c-500: #06b6d4;       /* cyan 主色 */
  --line: #e4ecf1;        /* hairline */
  --row-h: 34px;          /* 默认行高 */
  --radius: 8px;          /* 默认圆角 */
  --t-fast: 120ms cubic-bezier(.2,.6,.2,1);
}
```

**字号阶梯**：11 / 12 / 13（基础）/ 14 / 17 / 22  
**字体栈**：Inter + PingFang SC + JetBrains Mono

> S1 实施时这套 Token 通过 `@platform/ui` Adapter 注入 AntD ConfigProvider，详见 02-设计方案 §10「与 ADR-06 的关系」。

---

## 🚀 当前完成度

| 维度 | 进度 | 备注 |
|---|---|---|
| 设计稿 | ████████████████████ 100% | 视觉/交互/规范全部就位 |
| UI 原型实现 | ████████████████████ 95% | 19 模块覆盖 8 端 + 全局能力 |
| Schema 规范 | ████████████████████ 100% | v1 草案 + 元规范定义 |
| 架构设计 | ████████████████████ 100% | 9 份文档 + 10 ADR |
| 真实引擎实现 | ████████████░░░░░░░░ 60% | engine-core (TS) 已用，运行态走通；JSONata 沙箱待补 |
| 后端 | ░░░░░░░░░░░░░░░░░░░░ 0% | 实施计划已就绪（[后端实施/](./后端实施/)），等阶段 0 启动 |
| SDK | ░░░░░░░░░░░░░░░░░░░░ 0% | engine-core / engine-react / sdk |

**下一步重点**：
1. **后端阶段 0**：执行 [02_阶段0_执行前准备.md](./后端实施/02_阶段0_执行前准备.md) 5 天任务清单 → 仓库骨架 + Docker compose + Flyway
2. **后端阶段 1**：基础设施 + 认证 + 多租户隔离（3 周）
3. **前端 storage adapter 抽象**：localStorage / HTTP 双后端切换

---

## 📝 文档维护约定

- **Schema 规范是唯一合同**：任何 widget / type / 表达式约定改动，必须先改 `Schema规范_v2.md` + `form-schema.meta.json`，再传导到代码
- **架构决策**新增 ADR 写入 `01_系统架构图.md` §9（统一编号 ADR-NN）
- **设计原则变化**：双向同步 `02-设计方案.md` ↔ SKILL.md
- **每次原型大改后**回看 `03-任务清单.md` 同步状态

---

## 🔗 相关链接

- 项目运行指引：[../CLAUDE.md](../CLAUDE.md)
- 原始需求文档：`D:\workcode\test420\docs\表单引擎需求文档.md`（已合并入 [01-需求文档.md](./01-需求文档.md)）
- 设计稿原稿：[../.fetched/form-engine/](../.fetched/form-engine/)
- 设计 Skill：`~/.claude/skills/form-engine-design/SKILL.md`