form-design-v3 1.0.1 → 1.0.3

package/README.md

@@ -0,0 +1,186 @@
+# form-design-v3
+
+流程表单设计器 / 渲染器（Vue3 + TypeScript），以 npm 包形式交付，支持两种使用方式：
+
+- **插件方式**：注册全局组件 `<FdDesigner>`，用于表单设计页面
+- **命令式渲染**：`renderForm(options)`，由宿主传入容器与数据直接挂载，用于表单运行态渲染
+
+## 安装
+
+```bash
+npm install form-design-v3
+```
+
+peer 依赖（需宿主项目自行安装）：
+
+```bash
+npm install vue@^3.5.0 pinia@^2.3.0 element-plus@^2.14.0 lucide-vue-next@^1.0.0 monaco-editor@^0.56.0
+```
+
+> `element-plus` 为局部按需引入（仅 `ElSelect` / `ElInputNumber` 等少量组件及对应样式）；
+> `monaco-editor` 仅在打开「编写处理函数」代码编辑器时按需加载。
+
+## 使用
+
+### 1. 设计器（插件方式）
+
+```ts
+import { createApp } from 'vue'
+import { createPinia } from 'pinia'
+import DesignerPlugin from 'form-design-v3'
+import 'form-design-v3/style.css' // 库构建不自动注入 CSS，必须显式引入
+import App from './App.vue'
+const app = createApp(App)
+app.use(createPinia())
+app.use(DesignerPlugin, {
+  // 可选：覆盖接口模块与基础模块，默认 apiModule = 'form-designer'
+  apiModule: 'form-designer',
+  baseModule: ''
+})
+app.mount('#app')
+```
+
+```vue
+<template>
+  <!-- 表单 ID 也可通过 URL query ?id=xxx 传入（与后端 / 老设计器一致） -->
+  <FdDesigner :form-id="formId" />
+</template>
+```
+
+### 2. 渲染器（命令式渲染）
+
+```ts
+import { renderForm } from 'form-design-v3'
+import 'form-design-v3/style.css'
+
+const handle = renderForm({
+  container: document.getElementById('form')!,
+  widgets: schema.widgets, // 来自接口返回的表单 Schema
+  formMode: 'approval', // start / approval / view，缺省按控件配置全显
+  formData: { contract_no: 'HT20260001' },
+  events: schema.events, // 生命周期钩子 + 自定义事件
+  formId: schema.formId,
+  apiModule: 'form-designer', // 可选
+  baseModule: '' // 可选
+})
+
+handle.fireEvent('myCustomEvent', payload) // 触发自定义事件
+handle.unmount() // 销毁实例
+```
+
+### 3. 渲染器（组件式渲染）
+
+适合需要注入宿主插槽内容（审批页头、操作栏等）的场景：直接使用 `Renderer` 组件，
+插槽控件渲染为 `<slot>`，宿主按 `slotName` 注入内容。
+
+```vue
+<script setup lang="ts">
+import { Renderer, loadFormFromLocal, type FormSchema } from 'form-design-v3'
+
+// 本地调试：读取设计器保存的表单（localStorage 键 fd:form:{formId}）
+const schema: FormSchema | null = loadFormFromLocal(formId)
+const formData = { contract_no: 'HT20260001' }
+</script>
+
+<template>
+  <Renderer
+    v-if="schema"
+    :form-id="schema.formId"
+    :widgets="schema.widgets"
+    :form-mode="'approval'"
+    :form-data="formData"
+    :events="schema.events"
+  >
+    <!-- 插槽名需与表单中「插槽」控件的 slotName 一致 -->
+    <template #header>
+      <ApprovalHeader />
+    </template>
+    <template #footer>
+      <ApprovalBar />
+    </template>
+  </Renderer>
+</template>
+```
+
+### 4. 接口地址配置
+
+接口路径规则：`{baseUrl}/api/formdesigner/v1/{action}`（bpmapi 后端契约），默认 `baseUrl = '/bpmapi-uat'`。
+
+```ts
+import { configureApi, setBaseUrl } from 'form-design-v3'
+
+// 方式一：安装时配置（见上文插件安装的 baseUrl）
+// 方式二：运行时覆盖
+setBaseUrl('/bpmapi-test')
+```
+
+联调需在宿主 dev-server 配置 bpmapi 代理（后端无 CORS），详见
+[docs/integration-assessment.md](./docs/integration-assessment.md) 第 6 章。
+
+接口文档已按设计态 / 运行态拆分：设计器接口见 [docs/designer-api.md](./docs/designer-api.md)，渲染器接口见 [docs/renderer-api.md](./docs/renderer-api.md)。
+
+## 本地开发
+
+```bash
+npm install
+npm run dev        # 设计器页面（8098 被占用时自动顺延）
+```
+
+联调地址（需 hosts 将 kapi.xincheng.com 指向 127.0.0.1）：
+
+```
+http://kapi.xincheng.com:8098/?id=<表单GUID>&FormVersion=<版本GUID>
+```
+
+URL 参数：`id` 表单 ID（GUID，必填）、`FormVersion` 来源版本 ID、`openType`（`newEdit` 新建版本 / `edit` 编辑指定版本，**无默认值，缺省时后端返回「OpenType无效!」**；老写法 `OpenType` 亦可）、
+`baseUrl` 接口前缀（默认 `/bpmapi-uat`，本地后端联调传 `/bpmapi-local`）。
+
+**保存语义（按 API-backend.md 的 1+1+1 交互）**：
+
+打开时 `opendesigner` 先建版本并返回**工作表单 ID**，后续操作均基于它：
+
+| 操作 | 请求 id | 行为 |
+| --- | --- | --- |
+| 保存 | 工作表单 ID | 写入工作表单（临时记录 Status=4），后端**同步回写版本行** |
+| 另存为 | 源 = 工作表单 ID | 以工作表单为源复制成新表单（含最新保存的设计），返回新表单 ID |
+| 发布 | 工作表单 ID | 回写版本行置 Status=1 + 一口收直写业务库 |
+
+> 打开设计器为三步流程：`opendesigner` → `formconfig` → `allfields`（见 docs/designer-api.md 第 6 章）；
+> 本地 mock（`src/api/mock.ts`）已移除，未配置后端时设计器显示加载失败提示。
+> 真实数据联调记录见 [docs/integration-assessment.md](./docs/integration-assessment.md) 1.3 节。
+
+## 构建与发布
+
+```bash
+npm run build:lib  # 类型声明（vue-tsc）+ 库构建，输出 dist-lib/
+npm pack --dry-run # 预览发布包内容
+npm publish        # 发布到 npm（prepublishOnly 会自动先执行 build:lib）
+```
+
+完整的发布流程（令牌配置、版本管理、问题排查）与消费方接入指引见
+[docs/npm-guide.md](./docs/npm-guide.md)。
+
+产物结构：
+
+```
+dist-lib/
+├── form-design-v3.es.js      # ESM 产物（主入口）
+├── form-design-v3.umd.cjs    # UMD 产物（require 引入）
+├── style.css                   # 全局样式（CSS 变量 + 基础样式）
+└── index.d.ts                  # 类型声明入口（含 components/ widgets/ types/ 等）
+```
+
+## 目录说明
+
+| 目录 | 说明 |
+| --- | --- |
+| `src/api` | 接口封装与 mock（Schema 存取、子表元数据） |
+| `src/components/designer` | 设计器（工具栏 / 画布 / 属性面板 / 组件树） |
+| `src/components/renderer` | 运行态渲染器 |
+| `src/widgets` | 内置控件（card / label / subtable / slot / grid / text） |
+| `src/stores` | 设计器状态管理（撤销重做 / 拖拽 / Schema 装载） |
+| `src/types` | TypeScript 类型定义 |
+| `docs/designer-api.md` | 设计器接口文档（设计态） |
+| `docs/renderer-api.md` | 渲染器接口文档（运行态） |
+| `docs/API-backend.md` | 后端现有实现说明（对接参考） |
+| `docs/integration-assessment.md` | 设计器接入评估（bpmapi 对接） |

package/package.json

@@ -1,12 +1,75 @@
 {
   "name": "form-design-v3",
-  "version": "1.0.1",
-  "main": "CodeEditor-CJeYvarM.js",
+  "version": "1.0.3",
+  "description": "流程表单设计器 / 渲染器 (Vue3 + TS)",
+  "type": "module",
+  "main": "./dist-lib/form-design-v3.umd.cjs",
+  "module": "./dist-lib/form-design-v3.es.js",
+  "types": "./dist-lib/index.d.ts",
+  "style": "./dist-lib/form-design-v3.css",
+  "sideEffects": [
+    "**/*.css"
+  ],
+  "files": [
+    "dist-lib"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist-lib/index.d.ts",
+      "import": "./dist-lib/form-design-v3.es.js",
+      "require": "./dist-lib/form-design-v3.umd.cjs"
+    },
+    "./style.css": "./dist-lib/form-design-v3.css",
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
   "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
+    "dev": "vite",
+    "build": "vue-tsc -b && vite build",
+    "build:types": "vue-tsc -p tsconfig.build.json",
+    "bundle:types": "node scripts/strip-css-dts.mjs && rollup -c dts.config.mjs && node scripts/prune-dts.mjs",
+    "build:lib": "npm run build:types && vite build --mode lib && npm run bundle:types",
+    "preview": "vite preview",
+    "prepublishOnly": "npm run build:lib"
+  },
+  "keywords": [
+    "form",
+    "designer",
+    "renderer",
+    "vue3",
+    "form-engine",
+    "bpm"
+  ],
+  "license": "MIT",
+  "author": "mt",
+  "repository": {
+    "type": "git",
+    "url": "http://code.xincheng.com/oa/bpm_2.0.git",
+    "directory": "designer"
+  },
+  "peerDependencies": {
+    "element-plus": "^2.14.0",
+    "lucide-vue-next": "^1.0.0",
+    "monaco-editor": "^0.56.0",
+    "pinia": "^2.3.0",
+    "vue": "^3.5.0"
   },
-  "keywords": [],
-  "author": "",
-  "license": "ISC",
-  "description": ""
+  "devDependencies": {
+    "@types/node": "^20.19.43",
+    "@vitejs/plugin-vue": "^5.2.1",
+    "element-plus": "^2.14.6",
+    "lucide-vue-next": "^1.0.0",
+    "monaco-editor": "^0.56.0",
+    "pinia": "^2.3.0",
+    "rollup-plugin-dts": "^6.5.1",
+    "typescript": "^5.7.2",
+    "vite": "^6.0.0",
+    "vite-plugin-dts": "^4.5.4",
+    "vite-plugin-monaco-editor": "^1.1.0",
+    "vue": "^3.5.13",
+    "vue-tsc": "^2.1.10"
+  }
 }