255 lines
11 KiB
Markdown
255 lines
11 KiB
Markdown
# 模块管理功能设计
|
||
|
||
> 范围：模块管理这一功能本身的设计定义，覆盖 **模块、字段定义、菜单、多语言、权限** 五大能力。
|
||
> 定位：本文档描述「模块管理页面能配置什么、各能力如何分工」，**不描述**通用 `ModuleTable`/`ModuleForm` 的渲染实现，也不描述角色赋权页面（授权在另一处）。
|
||
> 配套原型：`fms-vue/src/views/ModuleManageDemo.vue`（纯前端，仅作演示）。
|
||
|
||
---
|
||
|
||
## 1. 设计目标与边界
|
||
|
||
模块管理是一个**配置中枢**，让实施人员用「填表」的方式定义一套业务功能，而不必改代码。它同时服务于四类下游消费者：
|
||
|
||
| 消费者 | 从模块管理取走什么 |
|
||
| --- | --- |
|
||
| 通用列表 `ModuleTable` | 字段清单、列标题、列表/表单开关、排序 |
|
||
| 通用表单 `ModuleForm` | 字段控件类型、校验、表单分组 |
|
||
| 菜单投影 | 哪些功能节点可见、显示什么名字 |
|
||
| 权限内核 | 该模块声明了哪些操作（编码）可供授权 |
|
||
|
||
### 核心原则：各自负责各自
|
||
|
||
1. **权限负责「有什么操作」**，只声明编码目录，不持有任何界面文案。
|
||
2. **多语言负责「所有界面文案」**，是菜单、模块、权限、字段、提示、按钮和校验信息的统一文案数据源。
|
||
3. **字段定义驱动列表与表单**，自身不关心权限、不关心翻译落点。
|
||
4. **菜单是功能树的可投影子集**，不单独存一份菜单数据。
|
||
|
||
---
|
||
|
||
## 2. 模块（Module）
|
||
|
||
模块是配置的中心对象，聚合「数据源 + 字段 + 表单分组 + 操作目录」。
|
||
|
||
### 2.1 基本信息
|
||
|
||
| 项 | 说明 |
|
||
| --- | --- |
|
||
| 模块编码 `b_code` | 可修改的唯一小写编码，如 `m_biz`、`m_user` |
|
||
| 模块名称 | 在「多语言」中以 `module.<编码>` 维护（见 §5） |
|
||
| 查询对象 `view_name` | 只读裸对象名（视图），如 `v_bs_business` |
|
||
| 保存对象 `save_name` | 可写裸表名，如 `b_business`；只读模块允许为空 |
|
||
| 业务主键 | 可选，用于展示与去重的业务字段，不代替系统主键 `b_id` |
|
||
| 默认排序 | 如 `b_id DESC` |
|
||
| 表单分组 | 见 §3.3 |
|
||
|
||
### 2.2 操作目录（权限项来源，见 §6）
|
||
|
||
模块声明它拥有哪些操作：`actions: [{ code, name }, ...]`。例如 `m_biz` 声明 `1=新增 … 7=导出`。
|
||
|
||
### 2.3 与其它能力的关联
|
||
|
||
```
|
||
Module
|
||
├─ fields[] → 驱动 ModuleTable / ModuleForm（§3）
|
||
├─ groups[] → 组织 Form 分组（§3.3）
|
||
├─ actions[] → 声明可被授权的操作编码（§6）
|
||
└─ 被功能树 page/module 节点引用 → 投影进菜单（§4）
|
||
```
|
||
|
||
---
|
||
|
||
## 3. 字段定义（Field）
|
||
|
||
字段是模块下的最小元数据单元，**通用列表与通用表单都由字段配置驱动**。
|
||
|
||
### 3.1 字段属性
|
||
|
||
| 属性 | 说明 |
|
||
| --- | --- |
|
||
| 字段编码 `code` | 模块对前端暴露的稳定字段名，如 `b_ywno`、`b_amount` |
|
||
| 标题 `caption` | 在「多语言」中以 `field.<模块>.<字段>` 维护，列表/表单共用 |
|
||
| 数据类型 `dataType` | `string / text / number / select / date / boolean` |
|
||
| 表单分组 `groupId` | 指向模块的分组，Form 按分组渲染 |
|
||
| 列表显示 `showInList` | 是否作为列表列 |
|
||
| 表单显示 `showInForm` | 是否在表单中出现 |
|
||
| 必填 `required` | 表单校验 |
|
||
|
||
> 字段配置不保存查询操作符、不保存固定 SQL；高级查询运行时按字段类型给出合法操作符。
|
||
|
||
### 3.2 驱动关系
|
||
|
||
- **列表列** = `fields` 中 `showInList = true` 的子集，按所属分组/排序渲染列与标题。
|
||
- **表单控件** = `fields` 中 `showInForm = true` 的子集，`dataType` 决定控件（文本/数字/下拉/日期/布尔），`required` 决定校验。
|
||
|
||
### 3.3 表单分组（Group）
|
||
|
||
模块下可设多个分组（如「主信息」「费用信息」），字段通过 `groupId` 归属分组。简单表单可不配置分组，落入默认分组。
|
||
|
||
---
|
||
|
||
## 4. 菜单（Menu / 功能树）
|
||
|
||
菜单**不是独立数据**，而是「功能树」中满足条件的节点投影。
|
||
|
||
### 4.1 功能树节点
|
||
|
||
统一功能树 `s_function_node` 组织全部入口，节点类型：
|
||
|
||
| 类型 | 含义 | 能否投影菜单 |
|
||
| --- | --- | --- |
|
||
| `directory` | 业务域/目录 | 可（`showInMenu`） |
|
||
| `page` | 已注册手写页面，可绑定模块 | 可（`showInMenu`） |
|
||
| `module` | 纯配置定位，供技术归类 | 否 |
|
||
| `group` | 配置分组 | 否 |
|
||
|
||
### 4.2 菜单投影规则
|
||
|
||
一个节点真正出现在某角色的菜单里，需同时满足：
|
||
|
||
1. 节点类型 ∈ {`directory`, `page`}；
|
||
2. `showInMenu = true`；
|
||
3. 当前角色对该节点拥有「查看」权限。
|
||
|
||
### 4.3 关键场景：同模块、不同页面、不同权限
|
||
|
||
多个 `page` 节点可绑定**同一个模块**（如 `m_biz` 被 `海运业务单 / 业务单查询 / 业务单审核` 三个页面引用）。它们共享字段与操作目录，但：
|
||
|
||
- 可见性各自独立（`业务单审核` 设 `showInMenu=false`，不进菜单）；
|
||
- 权限各自独立（操作员在「海运业务单」可提交，在「业务单审核」仅可审核）——授权由角色赋权页另配（不在本页面）。
|
||
- 模块父子关系（含 `module` 节点）仅用于技术归类与定位，**不**定义保存事务、主子表外键或业务流程。
|
||
|
||
---
|
||
|
||
## 5. 多语言（i18n）
|
||
|
||
所有**界面显示名**唯一数据源，以稳定 `i18nKey` 为中心，多种语言并列。
|
||
|
||
### 5.1 覆盖范围
|
||
|
||
| 命名空间 | i18nKey 规则 | 示例 |
|
||
| --- | --- | --- |
|
||
| 菜单/功能树 | `menu.<节点id>` | `menu.page_biz` |
|
||
| 模块 | `module.<模块编码>` | `module.m_biz` |
|
||
| 字段 | `field.<模块>.<字段code>` | `field.m_biz.b_ywno` |
|
||
| 权限 | `power.<模块>.<权限code>` | `power.m_biz.audit` |
|
||
| 按钮 | `button.<模块>.<动作>` | `button.m_biz.approve` |
|
||
| 占位提示 | `placeholder.<模块>.<字段>` | `placeholder.m_biz.customer` |
|
||
| 校验提示 | `validation.<模块>.<规则>` | `validation.m_biz.customer_required` |
|
||
| 通用文案 | `common.<名称>` | `common.save` |
|
||
|
||
### 5.2 数据结构
|
||
|
||
```js
|
||
i18nData = {
|
||
"menu.page_biz": { "zh-CN": "海运业务单", "en-US": "Sea Business Orders", "zh-TW": "海運業務單" },
|
||
"field.m_biz.b_ywno": { "zh-CN": "业务单号", "en-US": "Order No.", "zh-TW": "業務單號" }
|
||
// ...
|
||
}
|
||
```
|
||
|
||
- 实体本身**只持有 `i18nKey`，不持有任何文案**，显示一律走 `t(i18nKey)`。
|
||
- 回退顺序：当前语言 → `zh-CN` → `i18nKey` 本身。
|
||
- 切换语言时，功能树、字段标题、菜单预览实时联动。
|
||
|
||
### 5.3 管理界面要求
|
||
|
||
- 「多语言管理」是主配置中心，模块下的多语言面板是按当前模块过滤后的快捷编辑入口；两处写入同一张多语言表。
|
||
- 支持按命名空间、模块、语言和缺失翻译状态筛选。
|
||
- 以「Key + 各语言列」并列编辑；某语言留空即回退简体。
|
||
- **缺失翻译检测**：非默认语言留空时标红，并汇总「N 条缺失」，提示补录。
|
||
|
||
---
|
||
|
||
## 6. 权限（Permission）
|
||
|
||
权限负责**声明一个模块有哪些可授权操作**，仅此而已。
|
||
|
||
### 6.1 权限项结构
|
||
|
||
```js
|
||
// 模块声明
|
||
actions: [
|
||
{ code: 1, name: "新增", i18nKey: "power.m_biz.create" },
|
||
{ code: 5, name: "审核", i18nKey: "power.m_biz.audit" },
|
||
{ code: 7, name: "导出", i18nKey: "power.m_biz.export" }
|
||
]
|
||
```
|
||
|
||
- `code`：稳定操作编码，前端与后端统一引用（如 `5` 永远代表「审核」）。**授权与校验只认 `code`，不认名字。**
|
||
- `name`：管理员可读的默认中文回退标签。
|
||
- `i18nKey`：权限显示名绑定的多语言键；终端按钮如果需要不同文案，使用独立的 `button.*` Key。
|
||
|
||
### 6.2 权限与按钮文案的边界
|
||
|
||
- 授权与校验始终只认 `code`，不依赖任何语言文本。
|
||
- 权限名称和按钮文案都进入统一多语言资源，但使用不同 Key，避免把「审核」与「通过」错误耦合。
|
||
- 权限定义保持 `{code, name, i18nKey}` 自洽；按钮、提示和校验信息按各自命名空间独立维护。
|
||
|
||
### 6.3 与授权层的关系（边界）
|
||
|
||
- 本页面**只负责声明**操作目录（`code` 集合）。
|
||
- 真正的「角色 → 节点 → 允许哪些 `code`」赋权在**另一页面**配置，不在模块管理内。
|
||
- 模块管理里的菜单预览可用一份写死的授权结果做示意，但不在此维护。
|
||
|
||
### 6.4 扩展约定
|
||
|
||
- 模块新增一个权限项（如 `8=核销`），授权层无需改结构，直接照单收编码即可——两层天然对齐。
|
||
|
||
---
|
||
|
||
## 7. 五者关系总览
|
||
|
||
```
|
||
功能树 (directory/page/module/group)
|
||
│ page 节点绑定 模块
|
||
▼
|
||
模块 (Module: 查询/保存对象, 字段, 分组, 操作目录)
|
||
├─ 字段 ─────────────► 驱动 ModuleTable / ModuleForm
|
||
├─ 分组 ─────────────► 组织 Form
|
||
└─ 操作目录(code) ────► 权限内核（角色赋权页另行消费）
|
||
▲
|
||
│ 各自只声明稳定编码并绑定 i18nKey
|
||
│
|
||
多语言 (i18nKey → 多语言值) ──► 菜单 / 模块 / 权限 / 字段 / 按钮 / 提示 / 校验的唯一文案源
|
||
|
||
菜单 = 功能树中 showInMenu=1 且角色有查看权限的节点投影
|
||
```
|
||
|
||
---
|
||
|
||
## 8. 与当前原型（Demo）的对应关系
|
||
|
||
| 设计项 | 原型位置 | 备注 |
|
||
| --- | --- | --- |
|
||
| 功能树四类节点 | `functionTree` | 已是响应式可编辑 |
|
||
| 模块基本信息/字段/分组 | `modules` | `m_module/m_user/m_biz/m_fee` |
|
||
| 字段驱动列表/表单 | `字段配置` Tab | 列表/表单/必填开关 |
|
||
| 菜单投影 | `菜单预览` Tab | 按角色 + 语言渲染 |
|
||
| 多语言 | `多语言` Tab | Key + 三语，含缺失标红 |
|
||
| 权限目录 | `权限项` Tab | `code + name`，可增删 |
|
||
|
||
### 与原型的对齐情况
|
||
|
||
原型已按本文设计落地：
|
||
|
||
- **多语言覆盖所有界面文案**；权限名称使用 `power.*`，终端按钮使用独立的 `button.*`，两者不耦合。
|
||
- **权限项包含 `{code, name, i18nKey}`**；授权仍只认 `code`，`name` 作为默认中文回退。
|
||
- **字段多语言可在字段配置处点击设置**：标题单元格带多语言按钮，点击打开该字段的简体/English/繁體编辑框（i18nKey 形如 `field.<模块>.<字段>`）。
|
||
- **字段 `i18nKey` 统一为 `field.<模块>.<字段>`**，与模块/菜单 `<id>` 前缀、整体「命名空间.容器.标识」规则一致。
|
||
- 授权 `roleNodePerm` 仍为写死 mock，仅用于菜单预览示意，符合 §6.3 边界（角色赋权在另一页面，不在模块管理内）。
|
||
|
||
---
|
||
|
||
## 9. 数据模型概览（落库参考）
|
||
|
||
| 表 | 用途 |
|
||
| --- | --- |
|
||
| `s_module` | 模块定义（查询/保存对象、排序） |
|
||
| `s_module_field` | 字段配置（编码、标题键、类型、列表/表单/必填、分组） |
|
||
| `s_module_group` | 表单分组 |
|
||
| `s_function_node` | 功能树（目录/页面/分组/模块定位） |
|
||
| `s_i18n` | 统一多语言键值（key → 各语言值），覆盖所有界面文案 |
|
||
| 权限相关表 | 独立系统表，不属于 Table/Form 渲染配置 |
|
||
|
||
> 角色与权限内核使用独立系统表，不写入模块渲染配置；后端按 `module_id` + 操作 `code` 校验权限，不能只依赖前端隐藏。
|