workspace/code/fms/docs/refactor/阶段一模块管理.md

阶段一：模块管理

目标

在不开发通用 ModuleTable、ModuleForm 的前提下，完成可通过页面操作验证的模块管理纵向闭环。

本阶段范围

• 建立模块、字段、表单分组、选项来源和功能节点的数据库结构。
• 写入模块管理自身的种子配置。
• 复用现有通用查询、分页和事务保存接口。
• 提供手写的功能树与模块详情工作区。
• 支持模块基本信息、字段设计、表单分组、菜单绑定和功能树位置维护。
• 统一将 SQL Server bigint 作为字符串返回前端，避免雪花 ID 精度丢失。

数据库对象

对象	用途
dbo.s_module	模块定义
dbo.s_module_field	模块字段配置
dbo.s_module_group	表单分组配置
dbo.s_option_source	固定或模块查询选项来源
dbo.s_option_item	固定选项明细
dbo.s_function_node	目录、页面、技术分组和模块位置

数据库脚本位于：

fms-api/src/main/resources/db/migration/001_module_management.sql

脚本可以重复执行，首次执行时创建配置表并写入 s_module 模块种子数据。

页面入口

• 菜单：系统管理 / 模块管理
• 路由：/system/modules

页面采用左侧功能树、右侧模块详情的桌面工作布局（不兼容移动端）。未被功能节点引用的模块统一进入“未归档模块”。详情包含：

• 基本信息。
• 字段设计，字段与表单分组在同一工作区维护。
• 功能树中的菜单绑定和隐藏子模块位置。

功能树可以在页面内维护目录、页面、模块绑定和隐藏子模块。目录与页面的 b_show_in_menu 配置会投影到侧边栏，并与尚未迁移的静态菜单合并，避免迁移期间丢失入口。

接口边界

本阶段没有新增模块管理 CRUD 接口，继续复用：

• /api/data/page
• /api/data/loaddata
• /api/data/saveobjt
• /api/data/nextid

模块、字段和分组通过一次 saveobjt 请求在同一事务中保存，功能树节点独立保存。删除模块时同时清理功能节点引用；存在下级功能节点时禁止直接删除。

页面验收步骤

1. 使用机构 G3HD 登录新系统。
2. 进入“系统管理 / 模块管理”。
3. 确认能够看到内置的“模块管理”模块。
4. 打开该模块，检查基本信息、5 个字段配置和 1 个表单分组。
5. 在功能树管理中新增一个临时目录和页面节点。
6. 新建一个临时模块，填写裸查询对象名、裸保存对象名、可选业务主键字段和默认排序；页面不应出现主键策略和保存模式。
7. 为临时模块新增字段、表单分组和功能树位置并保存。
8. 将一个页面菜单绑定到临时模块，并在它下面增加隐藏子模块。
9. 重新进入临时模块，确认字段、分组和树形位置能够完整加载。
10. 修改字段标题或排序并保存，重新加载后确认修改生效。
11. 删除临时模块，确认模块、字段、分组和无下级节点的功能树引用一起删除。
12. 确认内置的 s_module 模块不能从页面删除。

本阶段暂不包含

• 通用 ModuleTable。
• 通用 ModuleForm。
• 独立的选项来源管理页面。
• 正式模块权限内核。
• 结构化模块查询接口。
• 业务模块迁移。

这些能力在模块管理页面验证配置模型稳定后继续建设。