u

code/fms/FMS元数据驱动架构重构方案.md

@@ -0,0 +1,215 @@
+# FMS 元数据驱动架构整体重构方案
+
+> 文档版本：V0.1（方案草案）  
+> 编制日期：2026-10-10  
+> 范围：元数据模型、模块配置、模块运行时及相关数据库结构  
+> 状态：待评审，尚未实施
+
+## 1. 结论摘要
+
+本次重构保留并强化**元数据驱动**这一核心概念。模块定义、字段语义、关系、页面视图和通用行为仍由元数据描述，通用运行时读取已发布的元数据运行。
+
+项目属于草稿 / Demo 阶段，不要求兼容现有元数据表结构和配置 JSON。可以重做元数据数据库，并整体替换配置和运行时主链路；不需要新旧格式长期双写或并行维护。
+
+```text
+物理数据源与表结构 → 模块元数据 → 模板 / 默认值 → 校验 / 编译 / 发布
+                                                    ↓
+                                     统一模块运行时 → SQL 业务表 / 视图
+```
+
+SQL Server 中的真实业务表和视图继续作为业务数据事实来源。元数据描述如何理解、呈现和操作这些数据；不采用 EAV 存储所有业务记录，也不让元数据引擎任意生成业务表。
+
+## 2. 重构目标与边界
+
+- 元数据仍是通用模块的运行时核心，不退化为页面备注或少量展示配置。
+- 常见模块通过数据源、模板和少量字段选择即可完成基础配置。
+- 一个字段只定义一次；列表、表单、查询、详情等视图引用字段，不重复维护语义。
+- 默认配置可推导、可重复生成；用户明确调整过的配置不被覆盖。
+- 元数据发布前经过统一校验，运行时消费同一份有效定义。
+- 元数据数据库可以整体重做，不受 `s_module`、`s_field`、`s_module_schema` 现有结构约束。
+- 复杂查询和业务动作保留 SQL / 后端扩展出口，不强迫所有逻辑都配置化。
+- 不将所有字段值改为 EAV 或通用 JSON；业务表仍通过 SQL migration / 数据库变更管理。
+- 不建设可执行任意脚本的规则引擎，不把库存、财务、结算等复杂事务塞进配置。
+- 不为本次目标无差别重写认证、文件、导出等稳定模块，只调整必要集成点。
+- 不要求兼容旧元数据格式；需要保留的 Demo 数据可一次性导入，否则重建 / 播种。
+
+## 3. 总体架构
+
+```text
+┌──────────────────── 配置面 ────────────────────┐
+│ 元数据工作台 → 草稿定义 → 校验 / 预览 → 发布版本 │
+└────────────────────────┬───────────────────────┘
+                         ↓
+                  元数据目录 / 发布快照
+                         ↓
+┌──────────────────── 运行面 ────────────────────┐
+│ 元数据解析与缓存 → 查询 / 保存 / 权限 / 页面渲染 │
+└────────────────────────┬───────────────────────┘
+                         ↓
+             SQL Server 表、视图与只读查询 SQL
+                         ↓
+            注册的后端业务动作及工作流扩展
+```
+
+### 配置面
+
+工作台负责选择数据源、导入物理字段、指定业务语义、应用模板、调整视图并预览。编辑内容为草稿，通过校验后才能发布。
+
+### 元数据编译与校验
+
+后端维护权威校验与解析逻辑。发布时将模块定义、模板默认值和用户覆盖项合成为有效定义，并检查字段引用、数据源、视图、关系、查询条件和动作引用。前端预览使用后端返回的有效定义，避免前后端分别推导默认规则。
+
+### 运行面
+
+通用运行时负责适合通用化的列表、过滤、排序、分页、字段呈现、标准保存和权限约束。查询值参数化；自定义查询入口仅用于只读查询。多表事务、库存过账、财务结算等动作由后端注册的业务处理器执行。元数据声明动作入口和参数契约，不保存可执行代码。
+
+## 4. 元数据逻辑模型
+
+运行时使用统一逻辑对象 `ModuleDefinition`。它是稳定契约，不要求与单张数据库表或单个 JSON 一一对应。
+
+### 模块
+
+包含稳定编码、名称、多语言键、类型、状态、组织层级、查询数据源、标准保存目标 / 主键、字段、关系、视图、动作引用、模板和发布版本。模块类型收敛为少数明确类别，如标准数据、只读查询、业务动作模块。
+
+### 字段
+
+区分物理事实和业务语义：
+
+- **物理事实**：来源表 / 视图、列名、SQL 类型、长度、精度、可空性等，优先由数据库结构检查得到，不重复手工维护。
+- **业务语义**：标签、多语言键、语义类型、关联目标、是否可编辑 / 列表展示 / 查询 / 排序 / 导出等，由元数据表达。
+- **界面属性**：控件、宽度、格式等仅在需要覆盖默认值时配置。
+
+字段使用模块内稳定编码；视图引用字段编码，不复制物理属性和业务语义。
+
+### 关系、视图与行为
+
+- 关系元数据表达主从、引用和多对多关系，包含源 / 目标模块字段及规则，发布时校验完整性。
+- 表单、列表、查询、详情是不同视图类型，只保存顺序、分组、布局、列宽、排序、操作符等视图特有信息；布局采用可读、可校验的结构化定义，不保存画布坐标。
+- 字段参与视图的默认状态由字段能力、模板和默认策略推导；个性化差异作为显式覆盖。
+- 简单校验和通用 CRUD 可由元数据表达；复杂业务动作映射到稳定的后端处理器编码。
+- 工作流、权限、公式等能力通过稳定引用接入，不重复定义模块字段。
+
+## 5. 元数据数据库重构
+
+以下是逻辑实体职责，最终表名和列定义在元数据契约评审后确定。可重做元数据表结构，但业务记录仍存放于真实 SQL 表。
+
+| 逻辑实体 | 职责 | 建议存储 |
+|---|---|---|
+| 模块 | 身份、类型、数据源、状态、组织关系 | 规范化关系表 |
+| 模块字段 | 字段编码、物理映射、业务语义、能力标记 | 规范化关系表；模块内编码唯一 |
+| 模块关系 | 关系类型及源 / 目标字段 | 规范化关系表；发布时校验引用 |
+| 模块视图 | 表单、列表、查询、详情定义 | 按模块和视图类型区分；灵活布局可用 JSON |
+| 模板 | 默认字段能力、视图结构、推荐规则 | 可版本化定义 |
+| 发布版本 | 不可变快照、版本号、校验结果、发布时间 | 版本记录；运行时按已发布版本读取 |
+| 动作注册 | 动作编码与后端处理器参数契约 | 只存稳定编码和契约，不存可执行代码 |
+
+### 对现有核心表的评估
+
+**结论：需要重构元数据配置表，但不需要仅因配置器难用而整体重做所有业务数据表。** 当前表结构能表达基本模块、字段和关系；主要问题是职责混放、字段能力分散到视图 JSON，以及缺少可发布的版本边界。
+
+- **`s_module`**：当前模块身份 / 树结构与查询表、保存表、主键、数据范围字段、默认排序 SQL、查询 SQL 和扩展 JSON 放在同一表。建议将模块身份与数据源 / 查询定义分开建模；移除缺少强约束的通用 `b_config_json`，把常用配置变为有类型的字段或关联实体。模块树优先只保留权威父级和同级顺序；`depth/path` 仅在查询性能有证据需要时保留为派生索引。模块草稿 / 发布时间应由版本模型管理，不靠一个模块级更新时间代表所有子配置状态。
+- **`s_field`**：当前主要保存名称、业务类型、启用和顺序，尚未明确区分物理列、查询别名、计算 / 虚拟字段。建议增加明确的字段来源种类与来源映射、语义类型和模块级能力；数据库物理类型由 SQL Server 结构检查获得。表单 / 列表 / 查询中的显示顺序和控件差异放到对应视图字段配置，不塞回字段主定义。
+- **`s_module_schema`**：当前每模块按 `view/edit/query` 保存整份 `nvarchar(max)` JSON，便于早期迭代，但字段参与、字段语义和复杂布局容易混在一起。既然不采用拖拽画布，建议将它替换为视图定义 + 结构化的视图字段 / 分组配置；常用属性使用有类型的列，只有少量确实灵活的扩展留在受校验 JSON。表单不保存行列像素坐标，列表不把所有列属性藏在任意 JSON 节点中。
+- **`s_relation`**：保留关系作为独立元数据，但建议引入稳定关系编码 / 标识，显式描述关系用途、基数、展示 / 加载规则，并对模块和字段引用建立数据库约束。现有删除策略等已表达的业务含义应迁移保留，不因改表而丢失。
+- **`s_user_module_pref`**：如保留个性化配置，只允许保存列表列、查询布局等用户偏好覆盖，不得改变模块字段语义、数据源、权限或保存行为。若 Demo 暂无真实个性化需求，可先不纳入新核心模型。
+- **新增发布版本实体**：保存草稿与已发布版本的边界、版本号、校验摘要和不可变运行快照；发布失败不替换当前有效版本。
+
+元数据表之间应使用主键、唯一约束和可表达的外键保障内部引用完整性，并用发布校验补足跨 JSON / 动态数据源的检查。不要为了引用元数据而给所有动态业务表强行建立数据库外键。
+
+### 规范化与 JSON 边界
+
+- 模块、字段、关系、版本等有稳定身份、查询和引用的对象采用关系表。
+- 表单布局、列表列布局、查询 UI 等灵活结构可存 JSON，但其中只能引用已定义字段和动作。
+- 发布快照可采用 JSON 作为编译产物，不作为编辑态唯一事实来源。
+- 对模块编码、模块内字段编码、模块 / 视图类型、版本号等建立唯一约束；可表达的元数据引用建立外键或等效约束，并由发布校验再次检查。
+- 明确删除、改名和关系变更策略，不依赖前端操作顺序保证一致性。
+- 不将业务字段值存入 `entity_id / field_id / value` 三元 EAV 表；不把所有配置塞进单个无约束 JSON。
+- 不复制 SQL 物理列定义后再要求长期人工同步；物理结构优先读取，元数据维护业务语义。
+
+### 草稿、发布与回滚
+
+建议区分编辑草稿与当前发布版本。草稿保存不改变运行中配置；发布时完成校验、生成不可变快照并原子切换当前版本。保留基本发布历史用于问题定位和回滚。Demo 第一版不建设复杂审批、多用户锁或多环境发布平台。
+
+## 6. 配置体验
+
+配置流程采用“默认优先、逐步展开”：
+
+1. 选择模块模板和数据源类型。
+2. 选择表 / 视图，读取物理字段并映射业务语义。
+3. 确认字段能力，自动生成表单、列表、查询初始定义。
+4. 预览常用页面，再按需进入结构化的高级视图配置。
+5. 运行发布校验，通过后发布。
+
+首批模板建议包含基础资料、单据主表、明细表、只读查询 / 报表。模板提供可编辑初始值，不是硬编码页面。
+
+### 不采用拖拽式设计器
+
+表单和列表不再采用画布式拖拽设计器，也不保留绝对坐标 / 自由定位配置。拖拽交互难以精确、重复配置，布局结构也不利于阅读、差异比较和长期维护。
+
+- **表单**：采用模板、分组和字段清单配置。通过字段选择、分组设置、列数 / 排序等结构化属性定义布局；字段顺序使用排序值或批量排序操作，不依赖画布拖动。
+- **列表**：采用列配置表 / 字段矩阵，集中设置是否显示、顺序、宽度、格式、对齐、排序和汇总等属性；支持批量添加、移除和套用模板。
+- **预览**：配置面板旁提供实时预览，但预览仅用于检查结果，不作为拖放编辑画布。
+- **元数据**：保存语义结构和字段引用，不保存像素坐标、拖拽路径或依赖编辑器内部实现的状态。
+- **高级场景**：通过分组、布局模板、字段显示规则及明确的扩展配置解决；不以重新引入自由拖拽作为兜底。
+
+默认规则：
+
+- 根据 SQL 类型推导候选字段类型和控件；语义不明确时要求确认，不做危险猜测。
+- 根据业务语义推导筛选组件、操作符、格式和建议列宽。
+- 新增字段补默认配置；已显式调整的配置不被重置；重置需显式操作。
+- 默认生成必须幂等，同一输入重复应用不产生重复节点或配置漂移。
+- 字段能力集中在矩阵中维护；布局通过模板、分组和排序等结构化配置调整，不使用拖拽画布。
+
+## 7. 现状与重构方向
+
+当前模块配置将字段、列表、表单、查询拆成不同面板，字段参与状态会修改多份界面 JSON；现有表单 / 列表设计器还采用拖拽式交互。本次重构不迁移现有画布和拖拽实现，改用模板、字段矩阵、分组 / 排序表格及实时只读预览。项目已有类型默认值和列表—查询联动逻辑，可保留其业务规则并重新组织。
+
+- `fms-vue/src/views/module/module-management/ModuleFieldsPanel.vue:3`：字段定义与表单 / 列表 / 查询参与关系。
+- `fms-vue/src/views/module/module-management/components/fieldDefaults.js:1`：列表和查询默认值规则。
+- `fms-vue/src/views/module/module-management/components/design-editor/common/schemaModel.js:540`：视图字段节点新增 / 移除。
+- `fms-vue/src/views/module/module-management/index.vue:1431`：配置面板分区导航和绑定。
+
+重构保留已验证的行为意图，但不要求保留当前组件边界、JSON 结构或数据库表结构。
+
+## 8. 整体重构范围与顺序
+
+不做新旧格式长期并行或渐进兼容；按依赖顺序拆分实施任务，便于验证：
+
+1. **确定元数据契约**：模块类型、字段语义、关系、视图、默认覆盖、发布和动作扩展模型。
+2. **重建元数据数据库**：新表、约束、种子 / migration；决定 Demo 配置重建还是一次性导入。
+3. **实现后端目录与编译器**：读取、校验、默认合成、发布、版本切换、缓存失效和回滚。
+4. **替换配置工作台**：数据源检查、字段导入、模板初始化、能力矩阵、预览、发布。
+5. **替换运行时消费链路**：列表、查询、表单、保存统一读取发布定义。
+6. **接入扩展能力**：权限、关系、公式、工作流、导出和业务动作。
+7. **删除旧路径**：完成导入或确认弃用后，删除旧 Schema 适配和重复逻辑。
+
+虽然不需要渐进兼容，仍建议用一个基础资料、一个主从单据、一个只读查询模块验证新契约，再批量建立 Demo 配置。这是新架构验收，不是要求新旧架构并行运行。
+
+## 9. 验收标准
+
+- 新建基础资料模块，无需分别手工搭建字段、表单、列表和查询的基础配置。
+- 表单和列表均可通过结构化配置完成，不需要拖拽画布、绝对坐标或依赖设计器内部状态。
+- 列表列和表单字段可以通过清单 / 矩阵批量配置、排序和复用模板，配置差异可读、可校验。
+- 模块字段只有一个权威定义；多个视图引用字段，不重复维护语义。
+- 默认配置可重复生成，且不覆盖显式配置。
+- 无效字段引用、数据源列缺失、关系目标错误、非法查询规则在发布时给出明确错误。
+- 运行时只消费已发布版本；发布失败不影响当前可用版本。
+- 简单 CRUD 使用通用运行时；复杂业务动作由明确的后端处理器完成。
+- 真实 SQL Server 业务表仍是业务数据事实来源，不引入 EAV 业务数据主存储。
+- 旧元数据路径已删除或仅作为一次性导入工具，不存在双重事实来源。
+
+## 10. 需要同步修订的文档
+
+目前架构文档存在方向冲突：部分草案提出以业务域代码包取代元数据运行时，开发规范与现有系统仍要求模块 / 字段 / 界面元数据驱动通用模块。本方案评审通过后应统一修订：
+
+- `FMS新系统核心架构设计.md`：明确元数据驱动是通用模块核心，SQL / 后端动作是扩展机制。
+- `FMS新系统核心架构实施计划.md`：改为元数据数据库、编译器、工作台和运行时重构任务。
+- `FMS新系统核心表结构设计.md`：重新定义元数据表，不再将现有 `s_module`、`s_field`、`s_module_schema` 作为不可变前提。
+- `开发规范.md`：明确元数据契约、发布定义、查询 / 保存边界和动作扩展约定。
+
+## 11. 假设与待定项
+
+- 暂保留 SQL Server 作为数据库目标；允许重做元数据表，不主动改变租户数据库路由模式。
+- 元数据和 Demo 配置可重建；是否保留样例数据，实施前决定重建或一次性导入。
+- 本文确定架构方向，不冻结最终 DDL、API、类名或 Vue 目录；这些在元数据契约评审后设计。
+- 权限、工作流、公式、多语言是否随模块发布版本整体冻结，需结合实际使用方式决定，避免第一版过度设计。