workspace/code/fms/模块管理简化与架构收敛方案.md

# FMS 模块管理简化与架构收敛方案

> 文档状态：方案评审稿  
> 目标：降低新增业务模块的配置成本，明确元数据配置与业务代码的边界  
> 约束：不迁移旧模块配置或旧业务数据；不提供旧表、旧接口、旧配置格式的兼容层

## 1. 结论摘要

当前模块管理的主要问题不是能力不足，而是把“登记业务对象”“定义字段”“设计页面”“配置查询”“配置权限”“定义删除规则”等不同职责，集中成了一个通用模块配置器。简单模块因此也要理解和维护一套近似低代码平台的概念。

建议将系统收敛为以下模式：

```text
业务域代码包（表、SQL、服务、API、页面）
                 │
                 ├── 代码清单登记业务对象、页面和权限点
                 └── 数据库维护模块启停、菜单结构和角色授权
```

核心决策：

1. **业务域代码包成为业务实现的唯一中心。**业务表、查询、保存、校验、业务动作和页面由业务域负责。
2. **模块管理不再设计业务页面。**它只管理代码中已经存在的业务对象及其启停、名称和顺序。
3. **菜单和权限分别管理。**菜单只能指向代码清单中已登记的页面；权限由代码声明，数据库维护用户或角色授权。
4. **保留共享组件，不保留通用业务解释器作为核心路径。**简单资料可复用列表、表单、查询组件；复杂行为进入明确的业务服务。
5. **从全新数据库和新接口开始。**旧 `s_module` 配置、旧 schema JSON、旧通用模块运行时和旧接口不迁移、不兼容、不双写。

## 2. 当前设计的主要负担

当前配置模型大致是：

```text
s_module
  ├── s_field
  ├── s_module_schema（view / edit / query JSON）
  ├── s_autocode
  ├── s_power
  ├── s_relation
  ├── s_delete_rule
  └── s_i18n
```

这套设计能让通用列表和表单快速出现，但也产生了几类持续成本：

- **配置入口太多。**新增模块要在多个面板间切换；字段定义与列表、表单、查询布局分别维护，用户需要理解内部元数据结构。
- **模块概念混杂。**导航树节点、数据对象、虚拟查询对象和页面入口都被叫作“模块”，导致一个模块既像目录又像数据模型和页面定义。
- **运行时过度依赖配置解释。**配置错误会在运行时才表现为页面空白、字段不可写或保存失败，而不是在编译、启动或发布阶段尽早暴露。
- **业务规则被推向通用化。**关系、级联删除、公式、权限和 SQL 配置逐渐形成跨业务解释规则；规则越多，编辑器、校验器和运行时之间的耦合越高。
- **安全边界需要后端兜底。**模块中心在前端限制管理员访问，但元数据和业务写入权限不能依赖路由隐藏或前端角色判断。

问题的根因是：**把少数简单 CRUD 的便利，扩展成所有业务都必须经过的运行时模型。**

## 3. 目标与非目标

### 3.1 目标

- 新增业务对象时，业务规则和数据访问可以在代码中搜索、评审、测试和发布。
- 管理员只做运行配置：菜单组织、对象启停、角色授权和少量展示偏好。
- 简单资料复用统一组件；单据、库存、财务、审批等复杂业务使用专用 API 和服务。
- 页面引用的数据字段、权限点和业务动作可由代码清单静态登记并校验。
- 配置改动有明确的操作权限、审计信息和发布责任。

### 3.2 非目标

- 不建设新的通用低代码平台或通用 JSON 规则引擎。
- 不让数据库配置动态创建业务表、推断保存逻辑或执行任意业务 SQL。
- 不要求每个业务页面都可由管理员拖拽生成。
- 不迁移旧模块配置、旧业务数据或旧接口调用方。
- 不为兼容旧版而保留双运行时、双字段定义或旧配置转换器。
- 第一阶段不做通用代码生成平台；先用一个真实业务域验证代码模板。

## 4. 目标概念模型

必须把四个概念分开：

| 概念 | 含义 | 权威来源 |
| --- | --- | --- |
| 业务域 | 一组共同业务职责，如 customer、sales、inventory | 后端和前端代码目录 |
| 业务对象 | 可被查询或操作的对象，如 customer、sales_order | 业务域代码清单 |
| 页面 | 列表、详情、工作台等用户界面 | 前端代码路由/页面清单 |
| 菜单 | 用户进入页面的导航结构 | 数据库菜单配置 |

菜单不再承担业务对象树的职责；业务对象不再通过树节点推断页面行为；页面也不能靠数据库中任意组件名动态加载。

### 4.1 业务域代码包

建议沿用新架构草案中的业务域组织方式：

```text
domains/
  customer/
    migration/
    sql/
    repository/
    service/
    api/
    page/
    i18n/
  sales/
  inventory/
```

每个业务域明确拥有自己的数据库变更、查询 SQL、保存方式、业务动作、API、页面和多语言资源。跨域调用通过接口或明确的业务关系完成，不通过任意 JSON 规则互相解释。

### 4.2 代码清单

每个业务域提供静态清单，列出可供系统登记的对象、页面和权限点。清单是可执行代码的一部分，不能由数据库传入任意类名或组件名覆盖。

示意：

```text
customer 域
  对象：customer
  页面：customer-list、customer-detail
  权限：customer.read、customer.create、customer.update、customer.disable
```

启动或发布校验至少检查：

- 菜单引用的页面 key 必须存在于代码清单；
- 模块登记的业务对象必须存在于代码清单；
- 授权引用的权限 key 必须已声明；
- 一个页面声明使用的对象必须在清单中登记；
- 数据库表、视图和必要字段必须通过业务域校验。

## 5. 新的模块管理体验

将“模块管理”改名为 **业务对象与模块登记**，不再展示字段设计器、列表设计器、表单设计器、查询设计器、自动编码、模块关系和删除 SQL 规则等运行时配置面板。

### 5.1 业务对象登记

业务对象由代码包提供，管理页面只允许维护少量运行属性：

- 显示名称或启用的多语言资源；
- 是否启用；
- 管理列表中的排序；
- 必要的说明信息。

不允许在这里填写保存表、查询 SQL、字段列表或业务规则。对象登记不是“凭空创建一个业务模块”：新增对象先有代码，再由清单登记。

### 5.2 菜单管理

菜单继续负责导航树和页面入口：

- 只能从代码清单选择页面 key；
- 菜单层级、排序、名称和启停保存在数据库；
- 菜单到业务对象的绑定明确记录，不从父子树或模块类型推断；
- 不允许数据库配置任意前端路由组件。

### 5.3 权限管理

- 权限点由业务域清单声明，代码决定具体操作含义。
- 管理界面只分配已声明的权限给角色或用户。
- 页面入口权限、对象读写权限、业务动作权限分别判定。
- 后端 API 对每次请求重新校验登录身份、对象/动作权限和业务数据范围；前端隐藏按钮只作为体验优化。

## 6. 页面和数据配置边界

### 6.1 业务页面

页面默认由代码实现，并复用现有通用列表、表单、查询、选择器和附件等 UI 组件。业务页面的字段、校验、动作和调用哪个 API 由页面和业务域代码明确声明。

建议的简单资料实现链路：

```text
Migration
→ 业务表 / 查询视图
→ list/detail/save SQL
→ repository / service
→ API
→ 共享列表与表单组件
→ 页面
```

复杂单据的提交、撤回、审批、过账、库存变更等动作必须由业务服务实现，不由表单 JSON、通用保存接口或可编辑 SQL 字段推断。

### 6.2 允许的展示偏好

只在多个业务域确实重复需要时，才保留受限展示配置，例如：

- 用户个人列表列顺序、列宽；
- 少量查询默认值；
- 只影响展示的格式偏好。

这些配置不得改变字段真实类型、保存映射、数据权限、业务校验或事务行为。默认布局优先由代码提供；个人偏好是覆盖，不是创建业务页面的必要步骤。

### 6.3 数据库是事实来源

- Migration 定义真实表结构；
- SQL 文件或受控 repository 实现查询和保存；
- 代码模型定义 API 输入输出和字段语义；
- 代码或受控资源维护系统文案；
- 数据库运行配置只登记启停、菜单和授权。

可以保留 `describe` 能力用于开发期校验或脚手架辅助，但不把数据库实时反射变成生产运行时的字段定义器。

## 7. 数据表与接口调整方向

以下是职责方向，不要求为每个旧表设计转换路径：

| 当前职责 | 目标处理方式 |
| --- | --- |
| `s_module` 中的模块树、视图表、保存表、通用 SQL | 模块登记表只保留稳定对象编码、业务域/对象 key、名称、启停和排序；业务 SQL 移入域代码 |
| `s_field` 运行时字段定义 | 不作为业务页面运行时字段事实来源；字段由业务 API 和页面代码定义 |
| `s_module_schema` 的 view/edit/query JSON | 移除通用解释器依赖；页面结构由代码定义，只可选保留受限展示偏好 |
| `s_autocode` | 编号规则归业务域所有，由业务服务原子获取和验证 |
| `s_relation` | 真实数据关系由 SQL 约束、查询和业务服务表达；不由全局模块关系解释器驱动 |
| `s_delete_rule` | 删除保护和级联行为由业务域服务及数据库约束明确实现 |
| `s_power` 权限点定义 | 权限 key 由代码清单声明，数据库维护角色授权；禁止客户端任意造权限 key |
| `s_menu` / 菜单绑定 | 保留导航职责，但页面目标必须指向代码清单中的安全 page key |
| `s_user_module_pref` | 如有真实用户偏好需求，可保留为展示偏好；不可承载权限或业务规则 |

模块登记表的候选字段：

```text
b_id             业务对象编码
b_domain_code    业务域编码
b_object_code    域内对象编码
b_name           显示名称
b_i18n           多语言资源 key
b_canuse         是否启用
b_xh             管理列表排序
b_bz             说明
```

`(b_domain_code, b_object_code)` 应有唯一约束。最终字段名和表结构在确认代码清单、权限模型和菜单模型后再定；不要把 `view_table`、`save_table`、任意 SQL 或业务配置 JSON 原样搬进新表。

## 8. 安全要求

这次收敛必须同时明确服务端边界：

1. 模块登记、菜单配置、角色授权的写接口必须有服务端系统管理员权限校验。
2. 通用数据写入不能只按客户端传入的 `table` 和 `key_field` 决定是否允许写；应使用受控表清单或专用业务 API。
3. 业务 API 必须校验用户对对象和动作的权限，以及公司、组织等数据范围。
4. 权限定义和页面 key 来自代码清单，不接受页面传入任意字符串作为授权依据。
5. SQL 参数值使用参数绑定；表、列和排序标识符必须来自服务端登记的标识符清单。
6. 关键管理操作记录操作人、对象、变更前后值和请求追踪信息。

## 9. 全新替换策略

本方案不提供旧数据或旧接口的兼容路径：

- 新环境从新的 Migration 基线建库；
- 不迁移旧 `s_module`、`s_field`、`s_module_schema` 或其他模块配置数据；
- 不实现旧 JSON 转换器、双读、双写、旧 API 代理或回退到旧页面的逻辑；
- 新版模块中心不读取旧配置表；
- 旧模块运行时、旧管理路由和仅服务旧运行时的接口随新实现整体移除；
- 旧业务数据迁移不属于本方案范围，需另立项目决策，不在新模块管理中隐式处理。

因此部署策略是新系统按新 schema 初始化，而不是在旧数据库上做无损升级。旧环境如需留档，由环境和备份策略处理，不由新版运行时兼容。

## 10. 实施顺序

### 阶段 A：锁定边界

- 定义业务域代码清单格式；
- 定义对象、页面和权限 key 的命名规则；
- 明确模块登记、菜单和角色授权三者关系；
- 明确简单 CRUD 与复杂业务 API 的使用边界；
- 完成后端管理员授权和通用写接口策略设计。

### 阶段 B：建立新内核

- 使用全新 Migration 建立最小模块登记、菜单、权限和审计结构；
- 实现代码清单校验；
- 实现服务端菜单/授权管理 API；
- 新模块中心只提供登记、启停、排序和菜单/授权入口。

### 阶段 C：验证一个简单业务域

选择客户或产品资料，完整实现：

```text
Migration → SQL → repository/service → API → 页面 → 菜单 → 授权 → 审计
```

该对象必须不依赖 `s_field`、`s_module_schema` 或通用模块解释器才能运行。

### 阶段 D：验证一个复杂业务动作

选择一个真实动作（例如单据提交或审批绑定），验证业务校验、事务和权限均在明确的业务服务中完成；工作流只调用已登记的业务动作。

### 阶段 E：移除旧模块中心实现

- 移除旧模块配置面板和仅供其使用的 JSON 解释逻辑；
- 移除旧运行时对模块字段/schema 的依赖；
- 删除旧模块专属接口与无调用点代码；
- 确认所有菜单页面来自代码清单，所有关键写操作经服务端权限校验。

不为旧数据补转换步骤，也不设置旧新并行期。

## 11. 验收标准

- 开发者新增业务对象时，有一致的业务域模板和单一 API/服务入口。
- 管理员新增菜单时只能选择已编译、已登记的页面和对象。
- 建立简单资料不需要分别维护字段表、列表 JSON、表单 JSON、查询 JSON 才能运行。
- 复杂业务动作的校验、事务和 SQL 均可在对应业务域代码中定位。
- 没有业务页面依赖全局模块 JSON 解释器才能启动。
- 未授权用户直接调用 API 不能修改模块、菜单、权限或业务数据。
- 新数据库初始化后，完整业务示例不需要导入任何旧模块配置即可工作。
- 配置偏好只影响展示，不能放宽数据权限或改变保存行为。

## 12. 代价与风险

- **优点：**运行时更容易理解和测试；业务逻辑可代码评审；减少管理员配置步骤；SQL、权限和事务责任明确。
- **代价：**新增业务对象需要开发和发布，不再承诺管理员零代码创建任意模块。
- **控制新增代码成本：**先建立简单资料业务域模板并复用共享组件；只有至少两个业务域出现相同重复后，再抽取脚手架或通用能力。
- **主要风险：**若大多数模块都要求管理员自行创建且业务结构高度同质，完全代码化会降低业务人员自助能力。应先用真实客户/产品模块验证开发成本，再决定是否增加“生成代码”的开发工具；不要因此恢复生产运行时的通用配置解释器。

## 13. 评审时需要确认

1. 新模块由开发者通过代码清单登记，管理员只能启停和配置菜单/授权，是否作为默认流程？
2. 列表列宽和列顺序是否只保留用户个人偏好，系统级默认布局是否完全由代码维护？
3. 简单 CRUD 的代码模板是否足够，是否先不做自动代码生成器？
4. 新数据库 schema 是否允许直接移除旧模块配置表和旧通用模块 API？

以上四项确定后，再据此制定数据库表结构、API 清单和分阶段实施任务。本方案本身不改代码、不执行数据库变更，也不包含旧数据兼容或迁移实现。