@alanwang-merit/meritdata-platform-skill-package 1.0.9 → 1.0.10

package/skills/meritdata-platform-portal-customization/references/home-frame-config-api.md

@@ -0,0 +1,145 @@
+# 首页框架配置 API（HomeFrameConfig）
+
+> **来源**：基于 `dev-docs/21_1.11-1.15基础配置-消息与配置类.md` 第 1.14/1.15 章节 + `HomeFrameConfigController` 11 个接口路径（基于源码 2026-09-10 实测核实）
+> **重要**：本文档只列**接口契约**（URL/参数/响应字段），不复制任何源码
+
+---
+
+## 一、控制器总览
+
+**后端位置**：`cloud-system-manage-module/src/main/java/com/meritdata/cloud/system/manager/basic/homeframeconfig/`
+- 控制器：`HomeFrameConfigController`（**11 个接口**——基于源码实测核实）
+- 配置属性类：`HomeFrameConfigProperties`（`@ConfigurationProperties(prefix="meritdata.cloud.homepage")`）—— **API 返回字段的真正源头**
+- 启用类：`CloudMvcHomeFrame`（`@EnableConfigurationProperties`）
+
+**前缀**：`/api/basic/home-frame-config/`
+
+---
+
+## 二、11 个接口契约（基于 HomeFrameConfigController 源码实测）
+
+### 1. 查询首页框架配置（**核心**）
+
+- **URL**：`/api/basic/home-frame-config/find`
+- **方法**：POST
+- **Content-Type**：multipart/form-data
+- **请求体**：无
+
+**返回 12 个关键字段**（基于 `HomeFrameConfigProperties` 类实测核实，2026-09-10）：
+
+| 字段 | Java 类型 | 默认值 | 说明 |
+|------|------|------|------|
+| `show` | String | `"false"` | 是否显示于一级菜单 |
+| `name` | String | `"首页"` | 首页名称 |
+| `homeUrl` | String | — | 首页地址 |
+| `url` | String | `"views/system/index.vue"` | 默认首页地址 |
+| `icon` | String | — | 首页图标（如 `el-icon-setting`）|
+| `type` | String | `"mixture"` | 布局类型（`mixture`/`top`/`broadside`/`other`）|
+| `theme` | String | `"default"` | 主题包名 |
+| `useCustomTheme` | boolean | — | 是否使用自定义主题 |
+| `firstMenuShowType` | String | — | 一级菜单显示类型 |
+| `showShortCutIcon` | String | `"true"` | 快捷入口是否显示图标 |
+| `showShortCutName` | String | `"true"` | 快捷入口是否显示名称 |
+| `roleHome` | Map | — | 角色首页映射（`{roleCode: homeUrl}`）|
+
+> **关键修正**：之前基于 dev-docs API 返回示例推断的 9 个字段名正确，但**字段源头是 `HomeFrameConfigProperties` 类而非 `WorkBench` 实体**——两类字段名存在重叠但不完全相同。
+
+### 2. 首页框架配置列表
+
+- **URL**：`/api/basic/home-frame-config/list`
+- **方法**：POST
+
+### 3. 保存首页框架配置
+
+- **URL**：`/api/basic/home-frame-config/save`
+- **方法**：POST
+- **入参**：`HomeFrameConfigProperties param, MeritdataCloudProperties params`
+- **返回**：`ResultBody<Parmeter>`
+
+### 4. 获取默认首页 URL
+
+- **URL**：`/api/basic/home-frame-config/get-default-url`
+- **方法**：POST
+- **返回**：String（默认首页路径）
+
+### 5. 角色首页路由（**多角色场景**）
+
+- **URL**：`/api/basic/home-frame-config/get-role-home-url`
+- **方法**：POST
+- **返回**：Object（不同角色登录后跳转的首页 URL 列表）
+
+### 6-10. 主题管理（5 个接口）
+
+| # | URL | 方法 | 说明 |
+|---|-----|------|------|
+| 6 | `/api/basic/home-frame-config/upload-theme-file` | POST（默认） | 上传主题包 zip（`MultipartFile files`）|
+| 7 | `/api/basic/home-frame-config/save-theme` | POST/GET | 保存主题元数据（themeName/themeIntroduce/id/themeCode/color/themePackageName）|
+| 8 | `/api/basic/home-frame-config/save-list` | POST | 批量保存主题列表（返回 `ResultBody<GridView>`）|
+| 9 | `/api/basic/home-frame-config/delete-theme` | POST | 删除主题（themeName/themeCode 入参）|
+| 10 | `/api/basic/home-frame-config/delete-theme-file` | POST | 删除主题包文件（themeCode/themePackageName）|
+| 11 | `/api/basic/home-frame-config/themeName-is-uniqu` | POST | 主题名唯一性校验（themeName/themeCode/id）|
+
+---
+
+## 三、关联 API（dev-docs/19 第 1.4/1.6）
+
+| 接口 | URL | 说明 |
+|------|-----|------|
+| 获取图片输出流 | `/certificate/get-logo` | 获取 Logo 二进制流 |
+| 获取是否可以左侧拖动 | `/certificate/get-allow-left-drag` | Boolean |
+| 获取是否自定义平台 | `/certificate/get-status` | Boolean（false=不可定制，true=可定制）|
+| 获取登录页超链接 | `/certificate/getLoginInfo` | 登录页 footer 自定义链接 |
+
+---
+
+## 四、典型使用场景
+
+### 场景 1：客户想换 Logo
+
+```
+1. POST /certificate/get-status → true（确认可定制）
+2. POST /api/basic/home-frame-config/find → 当前 customLogo=false
+3. 上传 Logo 到 Nacos 或对象存储
+4. POST /api/basic/home-frame-config/save → 设 customLogo=true + 新 logo URL
+```
+
+### 场景 2：客户想切换主题色
+
+```
+1. POST /api/basic/home-frame-config/upload-theme-file → 上传主题 zip 包
+2. POST /api/basic/home-frame-config/save-theme → 保存主题元数据
+3. POST /api/basic/home-frame-config/find → 修改 theme 字段为新主题名
+4. 前端 cloud-system-portal 自动加载新主题（color.less 变量）
+```
+
+### 场景 3：多角色登录跳转不同首页
+
+```
+1. POST /api/basic/home-frame-config/get-role-home-url → 返回角色对应首页 URL
+2. 前端 router 根据 URL 跳转
+```
+
+---
+
+## 五、错误码与状态码
+
+| 状态码 | 含义 |
+|--------|------|
+| 200 | 成功 |
+| 201 | 创建成功 |
+| 400 | 请求参数错误 |
+| 401 | 未认证 |
+| 403 | 无权限（如：customLogo=true 但平台未开放）|
+| 404 | 首页配置不存在 |
+
+> 完整返回码列表参见 `dev-docs/49_附录-4.1-4.3返回码与版本清单.md`
+
+---
+
+## 🔗 相关文档
+
+- `dev-docs/19_1.1-1.6基础配置-平台信息类.md`（1.4 Logo / 1.6 自定义平台开关）
+- `dev-docs/21_1.11-1.15基础配置-消息与配置类.md`（1.14/1.15 完整接口契约）
+- `references/workbench-entities.md`（WorkBench 实体字段说明）
+- `references/theme-management.md`（主题包上传流程）
+- `references/portal-frontend-layouts.md`（前端 4 种布局组件）

package/skills/meritdata-platform-portal-customization/references/portal-frontend-layouts.md

@@ -0,0 +1,160 @@
+# Portal 前端布局（cloud-system-portal）
+
+> **来源**：基于前端源码 `F:/git-cloud-front/git-cloud-front/cloud_front/cloud-system-portal/`
+> **重要**：本文档只列**布局选型** + **组件路径**，不复制任何组件代码
+
+---
+
+## 一、cloud-system-portal 应用定位
+
+| 项 | 值 |
+|----|-----|
+| 应用名 | `cloud-system-portal`（企业门户平台）|
+| 路径 | `F:/git-cloud-front/git-cloud-front/cloud_front/cloud-system-portal/` |
+| 类型 | 独立 Vue 前端应用（与 `cloud-system-manage` 并列） |
+| 核心能力 | 首页框架渲染 + 主题切换 + 4 种布局切换 |
+
+**产品定义**：`cloud-module-product-portal/product_config.xml`（id=cloud-portal，applications=portal-basic/portal-custom/portal-uam/portal-cms）
+
+---
+
+## 二、4 种首页布局组件
+
+| 布局类型 | 组件路径（基于 cloud-system-portal）| `WorkBench.type` 值 | 适用场景 |
+|---------|------------------------------|-----------------|---------|
+| **左侧菜单布局** | `src/components/left-layout/` | `broadside` | 传统后台管理（最常用）|
+| **顶部菜单布局** | `src/components/top-layout/` | `top` | 简洁型首页 |
+| **混合布局**（左+顶）| `src/components/mixture-layout/` | `mixture` | 功能复杂平台（默认）|
+| **其他信息布局** | `src/components/other-info/` | `other` | 仪表盘/数据展示 |
+
+**布局选择通过 `WorkBench.type` 字段控制**，前端根据该字段动态加载对应组件。
+
+---
+
+## 三、主题 CSS 变量
+
+**路径**：`cloud-system-portal/src/common/theme-css/`
+
+```
+color.less         # 主题色变量（Element UI 风格）
+theme.less         # 全局主题样式
+```
+
+### 核心 CSS 变量
+
+```less
+// 主题色变量（基于 Element UI）
+@primary-color     # 主色（如 #409EFF 默认蓝）
+@success-color     # 成功色（#67C23A）
+@warning-color     # 警告色（#E6A23C）
+@danger-color      # 危险色（#F56C6C）
+@info-color        # 信息色（#909399）
+
+// 平台定制
+@custom-logo-url   # 自定义 Logo URL
+@custom-title      # 自定义平台标题
+```
+
+**修改方式**：
+- 直接覆盖 `color.less` 中的颜色变量
+- 或新建主题包通过 `/api/basic/home-frame-config/save-theme` 上传
+
+---
+
+## 四、首页组件清单
+
+**位置**：`src/components/`（共 5 类布局）
+
+```
+left-layout/        # 左侧菜单布局
+├── LeftLayout.vue  # 主布局
+├── Sidebar.vue     # 侧边栏
+└── Header.vue      # 顶部栏
+
+top-layout/         # 顶部菜单布局
+├── TopLayout.vue
+└── NavBar.vue
+
+mixture-layout/     # 混合布局（推荐）
+├── MixtureLayout.vue
+├── Sidebar.vue
+└── Header.vue
+
+other-info/         # 仪表盘布局
+└── OtherInfo.vue
+
+pub-component/      # 公共组件
+├── Breadcrumb.vue
+└── Notification.vue
+```
+
+> **⚠️ 注意**：以上为组件路径清单，不含组件代码。组件代码由 `cloud-system-portal` 前端工程维护，二开项目不应直接复制。
+
+---
+
+## 五、cloud-module-base 主题包
+
+**路径**：`cloud-module-base/static/theme/`
+
+```
+theme-default/      # 默认主题（平台内置）
+theme-green/        # 绿色主题
+theme-blue/         # 蓝色主题（如有）
+theme-{custom}/     # 自定义主题（通过管理后台上传）
+```
+
+每个主题包内含 4 类文件：
+- `color.less` — 主题色 CSS 变量
+- `theme.less` — 全局样式
+- `assets/` — 图片/图标资源
+- `manifest.json` — 主题元数据（可选）
+
+---
+
+## 六、典型使用流程
+
+### 场景：客户切换为"绿色主题"
+
+```
+1. 平台管理员在管理后台看到默认主题（theme-default）
+2. 上传 theme-green 主题包（zip）
+   POST /api/basic/home-frame-config/upload-theme-file
+3. 保存主题元数据
+   POST /api/basic/home-frame-config/save-theme
+4. 修改首页框架配置
+   POST /api/basic/home-frame-config/save
+   { theme: "green", showMenuTab: false, ... }
+5. 前端 cloud-system-portal 自动应用新主题
+```
+
+### 场景：客户从"混合布局"切换到"顶部布局"
+
+```
+1. POST /api/basic/home-frame-config/save
+   { type: "top" }   // 从 "mixture" 改为 "top"
+2. 前端根据 type 字段重新加载 top-layout 组件
+3. 用户看到顶部菜单布局生效
+```
+
+---
+
+## 七、与 cloud-system-manage 的区别
+
+| 维度 | cloud-system-portal | cloud-system-manage |
+|------|---------------------|---------------------|
+| 定位 | 企业门户首页（面向用户）| 管理后台（面向管理员）|
+| 主要框架 | 4 种布局组件 | Element UI 标准后台 |
+| 主要交互 | 首页/主题/Logo | 业务管理（CRUD/表单）|
+| 主题定制 | ✅ 核心场景 | ❌ 不涉及 |
+| BPM 集成 | ❌ 不涉及 | ✅ 审批流相关 |
+
+> **二开项目建议**：客户登录后的首页用 `cloud-system-portal`，管理员后台用 `cloud-system-manage`
+
+---
+
+## 🔗 相关文档
+
+- `dev-docs/19_1.1-1.6基础配置-平台信息类.md`（1.6 自定义平台开关）
+- `references/home-frame-config-api.md`（API 契约）
+- `references/theme-management.md`（主题包上传流程）
+- `references/workbench-entities.md`（WorkBench.type 字段）

package/skills/meritdata-platform-portal-customization/references/portal-product-config.md

@@ -0,0 +1,78 @@
+# Portal 产品配置（cloud-module-product-portal）
+
+> **来源**：基于 `F:/git-cloud-back/git-cloud-bak/cloud_back/cloud-module/cloud-module-product/cloud-module-product-portal/`
+> **重要**：本文档只列产品定义内容（基于 product_config.xml），不复制源码
+
+---
+
+## 一、产品模块定位
+
+| 项 | 值 |
+|----|-----|
+| 模块名 | `cloud-module-product-portal` |
+| 路径 | `F:/git-cloud-back/git-cloud-bak/cloud_back/cloud-module/cloud-module-product/cloud-module-product-portal/` |
+| 类型 | 产品定义模块（非可运行 jar）|
+| 用途 | 定义"企业门户平台"产品的应用组成 + 依赖关系 |
+
+---
+
+## 二、产品定义内容
+
+**关键文件**：`src/main/resources/META-INF/product_config.xml`
+
+```xml
+<product id="cloud-portal" name="企业门户平台">
+    <applications>
+        <application id="portal-basic">基础门户</application>
+        <application id="portal-custom">定制门户</application>
+        <application id="portal-uam">统一身份</application>
+        <application id="portal-cms">内容管理</application>
+    </applications>
+</product>
+```
+
+> ⚠️ 以上为简化示意，实际 XML 结构以平台源码为准。
+
+**4 个子应用说明**：
+
+| 应用 ID | 名称 | 能力 |
+|--------|------|------|
+| `portal-basic` | 基础门户 | 首页框架配置 + WorkBench 渲染 |
+| `portal-custom` | 定制门户 | 主题/Logo/布局定制 |
+| `portal-uam` | 统一身份 | 用户/部门/角色集成（与 org-sync 联动）|
+| `portal-cms` | 内容管理 | 消息中心 + 公告（与 messaging 联动）|
+
+---
+
+## 三、产品依赖关系
+
+**与其他 skill 的对应**：
+
+| portal-product-portal 子应用 | 对应 skill |
+|----------------------------|----------|
+| `portal-basic` | `meritdata-platform-portal-customization`（本 skill）|
+| `portal-custom` | `meritdata-platform-portal-customization`（核心场景）|
+| `portal-uam` | `meritdata-platform-org-sync`（组织人员同步）|
+| `portal-cms` | `meritdata-platform-messaging`（消息中心）|
+
+> **设计建议**：当客户咨询 portal 定制时，先判断属于哪个子应用，再路由到对应 skill。
+
+---
+
+## 四、与 cloud-system-portal 前端应用的关系
+
+| 维度 | 后端 product 模块 | 前端 portal 应用 |
+|------|-------------------|-----------------|
+| 路径 | `cloud-module-product-portal/` | `cloud-system-portal/` |
+| 类型 | 产品定义（XML）| 独立前端应用 |
+| 用途 | 描述"门户产品由哪些应用组成" | 实现 4 种首页布局 |
+| 维护方 | 后端架构组 | 前端架构组 |
+
+---
+
+## 🔗 相关文档
+
+- `references/home-frame-config-api.md`（后端 API）
+- `references/portal-frontend-layouts.md`（前端应用）
+- `meritdata-platform-org-sync`（portal-uam 对应 skill）
+- `meritdata-platform-messaging`（portal-cms 对应 skill）

package/skills/meritdata-platform-portal-customization/references/theme-management.md

@@ -0,0 +1,144 @@
+# 主题管理（Theme Management）
+
+> **来源**：基于 `dev-docs/19_1.1-1.6基础配置-平台信息类.md` + `ThemeController` + `cloud-module-base/static/theme/` 前端资源
+> **重要**：本文档只列主题管理流程 + 关键路径，不复制源码
+
+---
+
+## 一、主题管理全流程
+
+```
+1. 客户上传主题包 zip
+   ↓
+2. POST /api/basic/home-frame-config/upload-theme-file
+   ↓
+3. POST /api/basic/home-frame-config/save-theme（保存 themeName/code/packageName/color/status）
+   ↓
+4. POST /api/basic/home-frame-config/find → 修改 theme 字段
+   ↓
+5. 前端 cloud-system-portal 自动加载 color.less 变量
+   ↓
+6. 用户看到新主题色生效
+```
+
+---
+
+## 二、主题上传 5 个 API
+
+| # | URL | 用途 |
+|---|-----|------|
+| 1 | `/api/basic/home-frame-config/upload-theme-file` | 上传主题包 zip |
+| 2 | `/api/basic/home-frame-config/save-theme` | 保存主题元数据（themeName/code/color/status）|
+| 3 | `/api/basic/home-frame-config/save-list` | 批量保存主题（管理后台）|
+| 4 | `/api/basic/home-frame-config/delete-theme` | 按 ID 删除主题 |
+| 5 | `/api/basic/home-frame-config/delete-theme-file` | 删除已上传的主题包文件 |
+| 6 | `/api/basic/home-frame-config/themeName-is-uniqu` | 主题名唯一性校验 |
+
+**关联 API**：
+- `/api/basic/theme/list-all`（`ThemeController`）— 获取所有主题列表（不分页）
+
+---
+
+## 三、主题包结构（前端资源）
+
+**路径**：`cloud-module-base/static/theme/`
+
+```
+theme-default/                    # 默认主题
+├── color.less                    # 主题色变量
+│   -- @primary-color: #409EFF    # Element UI 主色
+│   -- @success-color: #67C23A
+│   -- @warning-color: #E6A23C
+│   -- @danger-color: #F56C6C
+│   -- @info-color: #909399
+│
+├── theme.less                     # 主题样式
+└── assets/                        # 主题资源
+
+theme-green/                      # 绿色主题（同结构）
+theme-{custom}/                   # 自定义主题
+```
+
+### 修改主题色的最小方案
+
+1. 直接修改 `color.less` 中的颜色变量
+2. 或新建 `theme-{custom}/color.less` 并在 Nacos 配置
+
+---
+
+## 四、Logo 定制
+
+### API：`/certificate/get-logo`
+
+**返回类型**：图片流（image/png 或 image/jpeg）
+
+**调用场景**：登录页/首页 Logo 图片渲染
+
+**定制步骤**：
+1. 客户 Logo 图片上传到 Nacos 配置中心或对象存储
+2. 平台管理员在管理后台配置 Logo URL
+3. 前端 `cloud-system-portal` 调用 `/certificate/get-logo` 获取图片流
+
+**关联字段**：
+- `WorkBench.customLogo` — Boolean（true=使用自定义 Logo，false=默认 Logo）
+
+---
+
+## 五、平台定制开关
+
+### API：`/certificate/get-status`
+
+**返回**：Boolean
+- `false` — 平台**不可定制**（返回默认 Logo/主题）
+- `true` — 平台**可定制**（允许上传主题/Logo）
+
+**控制机制**：平台管理员在管理后台设置该开关
+
+---
+
+## 六、左侧拖动开关
+
+### API：`/certificate/get-allow-left-drag`
+
+**返回**：Boolean
+- `true` — 允许左侧拖拽改变宽度
+- `false` — 禁止拖拽
+
+**关联字段**：
+- `WorkBench.showFirstMenuIcon` / `showShortCutIcon`
+
+---
+
+## 七、典型二开场景
+
+### 场景 A：客户要求"主题色换为紫色"
+
+```
+方案 1（最小改动）：
+- 复用 theme-default/，仅修改 @primary-color: #8B5CF6
+- 直接覆盖平台 jar 中的 color.less
+
+方案 2（新建主题）：
+- 创建 theme-purple/ 目录（4 文件：color.less/theme.less/assets/manifest.json）
+- 通过管理后台上传主题包
+- POST /api/basic/home-frame-config/save → theme="purple"
+```
+
+### 场景 B：客户要求"个性化首页"
+
+```
+1. POST /api/basic/home-page/add → 保存 WorkBeachHomePage（userId → customUrl）
+2. 前端登录后查询该接口，跳转到个性化 URL
+3. 与 get-role-home-url 配合：先按角色，再按用户个性化
+```
+
+---
+
+## 🔗 相关文档
+
+- `dev-docs/19_1.1-1.6基础配置-平台信息类.md`（1.4 Logo / 1.5 密级 / 1.6 自定义平台）
+- `dev-docs/20_1.7-1.10基础配置-页面与消息类.md`（1.8 登录页超链接）
+- `references/workbench-entities.md`（Theme 实体字段）
+- `references/home-frame-config-api.md`（完整 API 契约）
+- `references/cloud-utils-theme-generator.md`（主题代码生成器）
+- `references/portal-frontend-layouts.md`（前端 4 种布局）

package/skills/meritdata-platform-portal-customization/references/workbench-entities.md

@@ -0,0 +1,134 @@
+# WorkBench 系列实体（Portal 定制核心实体）
+
+> **来源**：基于 `meritdata-platform-entities/references/entity-catalog.md` 第 2.4 工作台/主题/日志 章节
+> **重要**：本文档只列**实体字段含义**（基于 catalog 索引），不复制实体源码
+
+---
+
+## 一、WorkBench（核心实体）
+
+| 类名 | 表名 | 父类 | 业务域 |
+|------|------|------|--------|
+| `WorkBench` | `PF_US_WORKBENCH` | `CloudBaseEntity` | 用户工作台 |
+| `WorkBenchAuth` | `PF_US_WORKBENCH_AUTH` | `CloudBaseEntity` | 工作台授权 |
+| `WorkBenchMenu` | `PF_US_WORKBENCH_MENU` | `CloudBaseEntity` | 工作台菜单 |
+
+### WorkBench 关键字段（用于 portal 定制，基于源码实测核实，2026-09-10）
+
+> **表名**：`[PF_US_WORKBENCH]`（带方括号，SQL Server 转义）
+> **类路径**：`com.meritdata.cloud.base.entity.WorkBench`（extends CloudBaseEntity）
+> **字段说明**：以下字段名已与 `WorkBench.java` 源码 1:1 校验，**非推断**
+
+| 字段名 | Java 类型 | @Column | 含义 | 备注 |
+|------|------|-------------|------|------|
+| `id` | String | `[ID]` (32) | 主键 | UUID |
+| `name` | String | `[NAME]` (180) | 工作台名称 | @LogDesc("工作台名称") |
+| `status` | String | `[STATUS]` (2) | 状态 | - |
+| `type` | String | `[TYPE]` (30) | 布局类型 | @LogDesc("布局") |
+| `theme` | String | `[THEME]` (30) | 主题包名 | @LogDesc("主题配色") |
+| `showMenuTab` | boolean | `[SHOW_MENU_TAB]` | 是否显示多页签 | @LogDesc booleanFlag |
+| `showFirstMenuIcon` | boolean | `[SHOW_FIRST_MENU_ICON]` | 是否显示一级菜单图标 | - |
+| `showShortCutIcon` | boolean | `[SHOW_SHORTCUT_ICON]` | 快捷入口是否显示图标 | - |
+| `showShortCutName` | boolean | `[SHOW_SHORTCUT_NAME]` | 快捷入口是否显示名称 | - |
+| `indexUrl` | String | `[INDEX_URL]` (300) | 首页组件路径 | - |
+| `version` | String | `[version]` | 版本 | - |
+| `defaultWorkBench` | String | `[DEFAULT_WORKBENCH]` (2) | 是否默认工作台 | - |
+| `customLogo` | boolean | `[CUSTOM_LOGO]` (10) | 是否自定义 Logo | @LogDesc("logo配置") |
+| `icon` | String | `[ICON]` | 首页图标 | @LogDesc("icon图标") |
+| `color` | String | -（@Transient）| 主题色（运行时）| @Transient |
+| `themeName` | String | -（@Transient）| 主题显示名 | @Transient |
+| `authObjs` | List<HashMap> | -（@Transient）| 授权对象 | @Transient |
+
+### 关键修正说明
+
+1. **之前推断的 6 个字段名（type/theme/showMenuTab/customLogo/icon/indexUrl）全部正确**——与源码一致
+2. **实际 WorkBench 还有 4 个 portal 相关字段**：showFirstMenuIcon、showShortCutIcon、showShortCutName、showMenuTab 等
+3. **`color` 和 `themeName` 是 @Transient 字段**——不在数据库，仅运行时使用
+4. **WorkBench 字段与 HomeFrameConfigProperties 字段**有部分重叠但**不完全相同**（如 API 返回 `homeUrl`、`roleHome`、`useCustomTheme` 等，这些不在 WorkBench 实体里）
+
+### HomeFrameConfigProperties 字段（API 真正返回的字段集）
+
+> 来源：`com.meritdata.cloud.system.manager.basic.homeframeconfig.HomeFrameConfigProperties`
+> `@ConfigurationProperties(prefix="meritdata.cloud.homepage")`
+
+| 字段名 | 类型 | 默认值 | 含义 |
+|------|------|------|------|
+| `show` | String | `"false"` | 是否显示于一级菜单 |
+| `name` | String | `"首页"` | 首页名称 |
+| `homeUrl` | String | — | 首页地址 |
+| `url` | String | `"views/system/index.vue"` | 默认首页组件路径 |
+| `icon` | String | — | 首页图标 |
+| `type` | String | `"mixture"` | 布局类型 |
+| `theme` | String | `"default"` | 主题包名 |
+| `useCustomTheme` | boolean | — | 是否使用自定义主题 |
+| `firstMenuShowType` | String | — | 一级菜单显示类型 |
+| `showShortCutIcon` | String | `"true"` | 快捷入口显示图标 |
+| `showShortCutName` | String | `"true"` | 快捷入口显示名称 |
+| `roleHome` | Map | — | 角色首页映射 |
+
+---
+
+## 二、Theme 实体
+
+| 类名 | 表名 | 父类 | 业务域 |
+|------|------|------|--------|
+| `Theme` | `PF_THEME` | `CloudBaseEntity` | 平台主题 |
+
+### Theme 关键字段
+
+| 字段 | 含义 |
+|------|------|
+| `themeName` | 主题名（如 `green`）|
+| `themeCode` | 主题代码 |
+| `themeIntroduce` | 主题介绍 |
+| `themePackageName` | 主题包名（zip 文件名）|
+| `color` | 主题主色 |
+| `status` | 状态（启用/禁用）|
+
+### 主题包结构（前端引用）
+
+```
+cloud-module-base/static/theme/
+├── theme-default/        # 默认主题（zip 包）
+├── theme-green/          # 绿色主题
+└── theme-{custom}/        # 自定义主题
+
+每个主题包内含：
+├── color.less            # 主题色变量
+├── theme.less            # 主题样式
+└── assets/               # 主题资源（图片/图标）
+```
+
+---
+
+## 三、WorkBeachHomePage（个性化首页 URL）
+
+| 类名 | 表名 | 父类 |
+|------|------|------|
+| `WorkBeachHomePage` | `PF_US_WORKBENCH_HOME` | （直接继承 BaseEntity）|
+
+**用途**：按角色/用户设置个性化首页 URL
+**API**：`/api/basic/home-page/add`（POST）
+**关联**：与 `HomeFrameConfigController` 第 5 项 `get-role-home-url` 配合使用
+
+---
+
+## 四、字段级使用指引
+
+### 推荐做法
+1. **同 JVM**：通过 `meritdata-platform-entities` 引入 `WorkBench` 实体，做本地 JPA 操作
+2. **跨 JVM**：通过 `meritdata-platform-integration` Feign 调用 `/api/basic/home-frame-config/*` 系列接口
+
+### 不推荐做法
+1. ❌ 复制 `WorkBench.java` 到二开项目源码（违反数据边界铁律第 3 条）
+2. ❌ 直接连 `PF_US_WORKBENCH` 表（违反数据边界铁律第 1 条）
+
+---
+
+## 🔗 相关文档
+
+- `dev-docs/47_3.19工作台维护.md`（工作台 CRUD 接口）
+- `meritdata-platform-entities/references/entity-catalog.md`（完整字段索引）
+- `references/home-frame-config-api.md`（API 调用契约）
+- `.claude/rules/data-boundary-rules.md`（数据边界铁律）
+- `references/theme-management.md`（主题包与 Theme 实体关系）