20260818172816

code/fms/FMS新系统架构设计.md

@@ -150,7 +150,7 @@
 - 普通业务页面可以由通用运行时生成，复杂业务允许代码扩展。
 - IT 开发人员可以方便地增加特殊 Vue 页面、业务 Handler 和特殊 POST 接口。
 - 每次模块配置保存都生成不可变配置版本，默认可以立即生效，也可以先预览验证再激活，并支持回滚、导出、导入和跨环境迁移。
-- 菜单、动作、数据范围和配置管理权限由统一权限中心处理，字段级隐藏和脱敏作为后续扩展。
+- 菜单、动作、数据范围、字段级访问和配置管理权限由统一权限中心处理；首期支持按用户、角色或用户组配置字段查看和导出权限，复杂条件脱敏作为后续扩展。
 - 菜单、页面、字段、动作、字典和主数据支持统一多语言解析与回退。
 - 技术可观测日志和客户可见的业务操作日志分层存储并可关联追踪。
 - 系统元数据具备完整业务语义，可直接供 AI 理解和调用。
@@ -281,9 +281,11 @@ entities:
   - ocean.booking
   - ocean.shipment
   - ocean.container
-routes:
-  - /ocean/bookings
-  - /ocean/shipments
+pages:
+  - ocean.booking.default-list
+  - ocean.booking.default-form
+menus:
+  - ocean.booking
 ```
 
 模块依赖必须形成有向无环图，不能循环依赖。每个实体、动作、事件和特殊页面只能有一个所属模块；其他模块通过声明依赖后使用公开实体、查询、动作或事件，不能绕过通用运行时直接修改其他模块的数据表。
@@ -306,7 +308,18 @@ routes:
 默认表单：ocean.booking.default-form
 ```
 
-一个实体可以有多个列表、表单和详情页面。页面配置不能反过来决定实体的数据结构。
+一个实体可以有多个列表、表单和详情页面。页面配置不能反过来决定实体的数据结构。页面是稳定的访问入口，负责绑定路由、视图/表单或特殊组件以及页面访问权限；菜单只负责组织页面入口，不重复维护内部页面路由。
+
+页面和菜单的配置关系如下：
+
+```text
+实体
+|- 视图 / 表单
+|- 页面（page_key + route + permission）
+`- 菜单（menu_key + parent + page_key + sort + visible）
+```
+
+菜单类型至少包括 `directory`、`page` 和 `external`。目录菜单不直接代表业务页面；只有子页面存在且当前用户有页面访问权限时，目录才显示。内部 `page` 菜单的路由始终从页面资源解析，外链菜单才允许单独配置 URL。
 
 ### 7.2 字段的稳定标识
 
@@ -396,6 +409,8 @@ writeMode: direct
 
 客户、港口等共享主数据通常是普通引用，删除业务单不能删除客户；订舱明细、箱信息等可能属于组合关系，需要明确随主单归档或删除。`saveobjt` 的多实体事务必须按照关系元数据检查外键、所有权和删除顺序。
 
+组合关系可以作为主实体编辑表单中的子表区域使用。子表区域引用一个 `meta_relation`，并绑定子实体的列表列配置和编辑配置；通用运行时负责维护主外键、行排序、增删改和主子表事务。复杂的跨行计算、跨实体联动和状态变化仍通过动作或特殊 Handler 实现。
+
 ### 7.6 删除策略
 
 不采用所有实体统一软删除。`meta_entity` 必须声明 `deletePolicy`，通用保存和动作引擎根据实体类型、引用关系和业务状态决定是否允许删除：
@@ -433,10 +448,13 @@ writeMode: direct
 | `meta_relation` | 实体关系和引用规则 |
 | `meta_dictionary` | 固定字典和选项 |
 | `meta_query_source` | 复杂查询数据源 |
+| `meta_page` | 页面入口、路由、页面类型、组件和访问权限 |
+| `meta_menu` | 菜单层级、页面/外链绑定、权限、图标、顺序和可见性 |
 | `meta_view` | 列表、详情等视图定义 |
 | `meta_view_field` | 列表字段、顺序、宽度和格式 |
 | `meta_form` | 表单定义 |
 | `meta_form_field` | 表单分组、控件、校验和布局 |
+| `meta_form_relation` | 表单中的主子关系区域、子表视图和编辑行为 |
 | `meta_action` | 通用动作和业务动作 |
 | `meta_i18n` | 多语言资源 |
 | `meta_change_set` | 配置和结构变更集 |
@@ -496,6 +514,46 @@ updated_by
 
 模块 bundle 必须携带多语言资源。售后可以补充和修改翻译，配置发布时一同生成变更集。AI 可以生成批量翻译草稿，但需要保留来源、模型版本并经过人工确认后发布。
 
+### 8.2 页面与菜单配置
+
+页面和菜单都使用稳定业务 key，并随模块配置版本一起发布。推荐的页面配置如下：
+
+```yaml
+page:
+  key: ocean.booking.default-list
+  module: ocean
+  type: runtime
+  route: /ocean/bookings
+  view: ocean.booking.default-list
+  permission: ocean.booking.view
+  visible: true
+```
+
+菜单配置只描述导航树，不重复描述页面布局：
+
+```yaml
+menu:
+  key: ocean.booking
+  module: ocean
+  parent: ocean
+  type: page
+  page: ocean.booking.default-list
+  nameKey: menu.ocean.booking
+  icon: ship
+  sort: 10
+  visible: true
+```
+
+配置校验必须保证：
+
+1. 页面引用的视图、表单、组件和权限资源存在且属于当前模块或其依赖模块。
+2. `page` 菜单必须绑定页面，`directory` 菜单不能绑定页面或 URL，`external` 菜单必须提供外部 URL 和菜单权限。
+3. 同一个激活 release 内，页面 route 唯一，菜单 key、页面 key 和父子关系无循环。
+4. 菜单显示继承页面访问权限；目录菜单下没有可访问页面时不显示。
+5. 页面、菜单名称和图标等显示信息通过统一 i18n 和资源配置解析。
+
+新增或修改页面、菜单、顺序、可见性和路由时，只生成元数据变更集；新增特殊 Vue 组件仍需代码部署。
+
 ## 9. Select 与引用关系
 
 Select 选项应当是一等模型，不再要求为每一个下拉框创建数据库视图。
@@ -861,6 +919,30 @@ removableAfterVersion
 
 例如把已有的 `varchar(50)` 扩大到 `varchar(200)`，或把平台已支持的整数字段迁移为 decimal，属于配置发布和数据库迁移，不属于增加代码能力。变更前仍需完成数据可转换检查、依赖分析、备份检查和影响预览。缩短长度、改变精度或物理删除字段应采用第 11.3 节的渐进式迁移，不能因为“不需要重启”就直接执行危险 DDL。
 
+### 12.6 拖拽式主表单与子表配置
+
+普通主表单和主子表页面由配置中心通过拖拽设计器生成。设计器提供字段、关系、分组和标准控件的组件面板，技术人员可以把字段拖入表单，把组合关系拖入子表区域，并配置顺序、宽度、分组、只读、必填、默认控件和子表操作。
+
+推荐的元数据关系如下：
+
+```text
+meta_form
+|- meta_form_field       主实体字段项
+|- meta_form_relation    主子关系区域
+|   |- relation_key
+|   |- child_view_key     子表列配置
+|   |- child_form_key     子表编辑配置（可选）
+|   |- display_mode       table / form / tabs
+|   |- editable
+|   |- allow_add
+|   |- allow_delete
+|   `- allow_sort
+```
+
+字段、关系、顺序、可见性、宽度和控件类型等稳定属性使用结构化元数据保存；控件特有的属性和布局扩展使用经过 Schema 校验的 JSON 配置。设计器保存时生成 `change_set` 和候选 release，支持预览、校验、发布和回滚，不直接修改当前运行版本。
+
+主表和子表保存使用同一个 `saveobjt` 原子事务。请求可以同时提交主实体和子实体的新增、修改、删除，运行时根据 `meta_relation` 校验所有权、外键、唯一性、删除策略、字段权限、乐观锁和业务校验。子表不是简单地把前端数组覆盖到数据库，正式业务状态下的删除、拆分、合并和跨行计算必须调用动作或特殊 Handler。
+
 ## 13. 通用数据运行时
 
 内部 ERP 以灵活性和开发效率为优先。后端保留少量、稳定、全部使用 POST 的通用能力接口，不为海运订舱、空运单、客户等每个普通实体新增 Controller 和 URL。
@@ -964,6 +1046,8 @@ page     -> 返回当前页、总数、页码和分页大小
 }
 ```
 
+对于主子表编辑，前端可以在一次请求中提交主实体和其组合关系下的子实体变更。通用运行时按关系元数据决定保存顺序、主键回填、行排序、删除策略和事务边界；涉及跨行汇总、状态变更、拆分合并或外部副作用时，必须改用 `action.execute` 或特殊 Handler。
+
 通用运行时根据当前已发布的元数据完成：
 
 - 字段解析和类型转换
@@ -1087,15 +1171,17 @@ MetadataController
 - 字典和分类
 - 普通业务数据列表
 - 简单主表编辑
+- 主表编辑表单和一对多子表编辑表格
 - 通用查询和导出
 
-复杂页面仍由开发人员编写 Vue 组件，例如：
+复杂页面和复杂交互仍由 IT 开发人员编写 Vue 组件或 Handler，例如：
 
 - 海运工作台
 - 订舱操作台
 - 多箱、多提单联动编辑
 - 费用结算
 - 拖拽式单证编排
+- 多层嵌套、跨行公式和复杂状态联动
 
 复杂页面仍然使用相同的实体、字段、引用、动作和通用数据能力，不应建立另一套数据定义。
 
@@ -1116,7 +1202,7 @@ MetadataController
 -> 随前端版本部署
 ```
 
-特殊页面适合海运工作台、多箱多提单联动、费用结算、拖拽编排和高交互批量操作。不能为了追求完全配置化而降低开发人员实现复杂页面的效率。
+特殊页面适合海运工作台、多箱多提单联动、费用结算、拖拽编排和高交互批量操作。IT 开发人员可以继续复用同一套实体、关系、通用保存、动作和权限能力；不能为了追求完全配置化而降低开发人员实现复杂页面和复杂业务逻辑的效率。
 
 ### 14.2 特殊页面注册
 
@@ -1251,11 +1337,12 @@ public class SplitBookingHandler {
 统一权限中心
 = RBAC 功能授权
 + ABAC 数据策略
++ 字段级访问策略
 + 配置管理权限
 + AI 工具权限
 ```
 
-即：角色负责授予用户可以使用哪些功能，数据策略决定用户可以操作哪些记录，配置权限决定谁能修改实体、页面、权限和 Schema。字段级隐藏和脱敏暂不作为第一阶段要求。
+即：角色负责授予用户可以使用哪些功能，数据策略决定用户可以操作哪些记录，字段级访问策略决定用户可以查看、导出或脱敏哪些字段，配置权限决定谁能修改实体、页面、权限和 Schema。首期只做基于用户、角色或用户组的静态字段策略，不引入复杂的条件脱敏规则。
 
 ### 16.1 权限主体
 
@@ -1294,6 +1381,8 @@ public class SplitBookingHandler {
 - 页面可以单独配置 `visible = false`，表示允许通过链接访问但不显示在菜单中。
 - 菜单只是页面和模块的导航表现，不是最终权限判断点。
 
+菜单资源本身保存父子关系、顺序、图标、页面绑定和可见性；页面资源保存 route 和页面访问权限。权限中心返回可访问页面后，菜单运行时按当前 release 构建树并过滤无权页面，目录节点在没有可见子节点时自动隐藏。这样新增普通页面和菜单只需要提交配置变更集，不需要修改前端路由代码；特殊页面仍需先部署组件，再发布对应页面和菜单元数据。
+
 建议的页面权限 key：
 
 ```text
@@ -1380,15 +1469,27 @@ AND
 
 ### 16.6 字段显示与写入边界
 
-第一阶段不建设复杂的字段隐藏和脱敏权限。列表、表单是否显示某字段以及是否渲染为只读，由页面配置决定；后端是否允许写入由实体字段的 `writeMode` 决定。
+字段的页面展示、后端写入和权限可见性是三层不同概念。首期支持按用户、角色或用户组配置字段查看和导出权限，并预留基础脱敏方式；按记录条件、表达式或不同场景动态脱敏暂不纳入首期。
 
 ```text
 页面显示或只读       -> meta_view_field / meta_form_field
+字段查看、导出和脱敏 -> auth_field_policy / 统一权限中心
 后端允许普通写入     -> meta_field.writeMode
 状态变化和受控字段   -> action.execute
 ```
 
-页面配置只是交互表现，不能把 `actionOnly`、`computed` 或 `system` 字段变成可写。以后出现采购底价、证件号等确实需要按角色隐藏或脱敏的字段时，再在统一权限中心增加可选字段策略，并让页面、数据 API、导出、报表和 AI 使用同一个策略；当前架构不预先实现这部分复杂度。
+字段策略至少支持以下维度：
+
+```text
+view       allow / deny
+export     allow / deny
+mask       none / partial / full
+subject    用户、角色或用户组
+```
+
+多个策略同时存在时，拒绝优先于允许；没有配置字段策略的普通字段按实体默认规则处理，敏感字段必须显式配置。字段权限必须由后端统一执行：列表、详情、通用查询、导入导出、报表、后台任务、特殊 Handler 和 AI 工具都必须经过同一个字段权限服务，不能只在前端隐藏列。查询引擎应在生成 SQL 投影或响应序列化阶段裁剪无权字段，导出和 AI 返回也不得通过别的接口绕过策略。
+
+页面配置只是交互表现，不能把 `actionOnly`、`computed` 或 `system` 字段变成可写。字段可见性、导出权限和 `writeMode` 彼此独立；例如用户可以查看成本但不能导出，也可以导出脱敏后的值但不能修改。复杂的按数据条件脱敏、字段级表达式策略和细粒度临时授权留待后续扩展。
 
 ### 16.7 配置管理权限
 
@@ -1452,9 +1553,10 @@ platform.ai.configure
 | `auth_role_permission` | 角色功能授权 |
 | `auth_data_policy` | 数据范围策略 |
 | `auth_role_data_policy` | 角色数据策略关系 |
+| `auth_field_policy` | 字段查看、导出和脱敏策略 |
 | `auth_permission_snapshot` | 可选的编译缓存 |
 
-权限定义、角色模板和数据策略应包含在模块 bundle 中，通过稳定 key 跨环境迁移。具体用户与角色的分配属于环境或租户数据，不应随模块定义覆盖。
+权限定义、角色模板、数据策略和字段策略应包含在模块 bundle 中，通过稳定 key 跨环境迁移。具体用户与角色的分配属于环境或租户数据，不应随模块定义覆盖。
 
 ### 16.11 AI 权限继承
 
@@ -1464,7 +1566,7 @@ AI Gateway 必须继承发起用户的身份和权限上下文：
 用户发起 AI 请求
 -> AI Gateway 获取用户权限快照
 -> 根据动作权限生成可用工具
--> 查询工具自动追加数据权限
+-> 查询工具自动追加数据权限和字段访问策略
 -> 动作工具再次检查动作权限和业务前置条件
 ```
 
@@ -2285,7 +2387,7 @@ created_at
 | 元数据 | 稳定 key、类型、关系、引用、公式和依赖合法性 |
 | Schema Compiler | 空库安装、快照差异计算、失败恢复、重复执行、结构对账和回滚兼容检查 |
 | 通用运行时 | 类型转换、关系保存、`writeMode`、删除策略、乐观锁、事务和批量操作 |
-| 权限 | 菜单、动作、数据范围、导出、后台任务和 AI 使用相同决策 |
+| 权限 | 菜单、动作、数据范围、字段查看/导出/基础脱敏、后台任务和 AI 使用相同决策 |
 | 数据源上下文 | 保持现有 Web 请求注入机制，并验证任务、发布和消息入口会正确设置及清理 `OrgContext` |
 | 幂等与任务 | 超时重试、重复回调、Worker 崩溃接管、死信和人工重跑 |
 | 模块兼容 | bundle 双向差异、稳定 key 冲突、特殊页面与 Handler 的 manifest 契约 |
@@ -2348,7 +2450,7 @@ created_at
 | 复杂业务页面 | 编写代码 | 调整允许开放的配置 |
 | 复杂业务动作 | 编写 Handler | 绑定和配置动作 |
 | 特殊业务接口 | 使用扩展 SDK 开发 | 配置权限、菜单和参数 |
-| 权限中心 | 提供决策引擎和策略类型 | 配置角色、菜单、动作和数据范围 |
+| 权限中心 | 提供决策引擎和策略类型 | 配置角色、菜单、动作、数据范围和字段可见性 |
 | 双层日志 | 提供追踪、日志和审计框架 | 配置字段审计和客户可见范围 |
 | 模块迁移机制 | 提供 Compiler 和发布工具 | 导出、导入和发布变更集 |
 | AI 能力 | 提供工具和扩展点 | 使用 AI 生成配置候选版本 |
@@ -2394,6 +2496,7 @@ created_at
 
 - 沿用并固化现有 `orgId -> OrgContext -> OrgRoutingDataSource` 数据源注入机制。
 - 完成模块、实体、字段、关系、字典模型。
+- 完成页面入口和菜单树模型，明确页面路由、菜单绑定、排序、可见性和权限继承规则。
 - 建立稳定 key 规则和语义描述规范。
 - 确定真实列与扩展字段的边界。
 - 实现不可变配置 release、当前指针、候选预览、回滚和变更集。
@@ -2416,9 +2519,12 @@ created_at
 - 实现 `writeMode`、乐观锁、请求幂等和数据库唯一约束。
 - 实现字典和引用字段。
 - 实现默认列表、表单和查询页面。
+- 实现页面运行时路由解析、按权限过滤菜单树和目录节点裁剪。
+- 实现拖拽式表单设计器、主子关系区域和一对多子表编辑表格。
 - 实现运行时多语言解析、租户默认语言和用户语言切换。
 - 实现售后配置中心。
 - 实现动作和数据范围权限决策引擎。
+- 实现按用户、角色或用户组的字段查看、导出和基础脱敏策略，并在查询、保存、导出、报表、特殊 Handler 和 AI 工具中统一执行。
 - 实现用户权限快照、缓存失效和权限解释。
 - 实现统一 request/trace 上下文和结构化技术日志。
 - 实现业务审计事件、字段变更和客户时间线。