CL 正式文档平台

中间件前后端产品需求说明书 ​

构建时间2026-06-26 20:10:33（Asia/Shanghai）来源项目中间件文档 / 中间件后端来源仓../cl-midserver-2026来源提交号69b951a07311e75887b57e0400d888f89dd72cac
查看文档来源信息
  • 来源目录：addons/sys_base/docs
  • 来源文件：功能说明/中间件前后端产品需求说明书.md
## 1. 文档目的 本文用于说明中间件前后端产品的目标、范围、核心功能、权限规则、运行契约、前后端协作方式、性能与安全要求，以及当前已识别的整改项。

本文是中间件产品总纲，不替代以下正式资料：

  • addons/sys_base/docs/接口文档：正式接口级说明。
  • addons/sys_base/docs/契约说明：运行契约、字段边界和上下游责任。
  • addons/sys_base/docs/功能说明：具体模块使用说明。
  • cl-midserver-pcweb-2026/docs：PCWEB 页面、接口调用和本地注册说明。

2. 产品定位 ​

中间件是统一后台治理和下游接入平台，负责提供后台用户、部门、角色、权限、菜单发布、应用接入、微信应用资料同步、服务态认证、运行上下文和 PCWEB 管理端运行支撑能力。

中间件不是下游业务系统，不承载订单、店铺、分账、配送、售后、营销、业务支付编排等具体业务域流程。下游业务模块可以复用中间件的公共治理能力，但业务域数据和业务流程应留在下游模块内实现。

3. 产品边界 ​

3.1 中间件负责 ​

  • 后台用户登录、身份选择和当前运行上下文。
  • 后台用户、部门、角色、应用范围和公共范围管理。
  • 角色页面权限、动作权限、默认页和接口权限同步。
  • system_menu 与 app_menu 正式菜单清单的上传、提交、发布、版本查看和切换。
  • PCWEB 正式页面入口、本地页面注册、运行时菜单装配。
  • 应用信息、模块信息、Key 管理和服务态认证支撑。
  • 微信应用资料按模块授权范围同步。
  • 运行日志、请求日志、登录日志和关键权限审计支撑。
  • 下游模块接入所需的正式契约、接口文档和验收门禁。

3.2 中间件不负责 ​

  • 下游订单、店铺、商品、分账、配送、业务支付编排等具体业务。
  • 下游用户端页面业务逻辑。
  • 下游业务私有数据权限的细粒度规则。
  • 下游业务接口的内部性能优化。
  • 下游业务菜单未发布时的本地兜底菜单、演示菜单或 mock 菜单生成。
  • 已废弃历史业务模型的继续扩散。

3.3 历史兼容边界 ​

仓库中仍存在少量历史兼容对象，例如历史支付分账辅助结构、历史 common DTO、历史应用模板字段等。这些对象只允许服务旧链路收尾、历史数据读取或迁移，不得作为新中间件正式能力继续扩散。

支付分账、商户转账、分账接收人等业务含义不属于中间件正式角色/权限模型。新增支付或分账能力应回到下游业务模块实现。

4. 使用对象 ​

使用对象主要诉求
超级管理员维护全局治理入口、菜单清单、模块、应用、角色和关键配置
角色管理员创建角色、复制角色、设置角色权限、默认页和可管理角色范围
部门管理员维护组织部门、成员和公共范围
应用管理员维护应用信息、微信应用资料、Key 和应用菜单
PCWEB 使用者通过后台管理端完成正式治理操作
下游模块开发者接入中间件菜单、授权、应用资料和服务态接口
服务态调用方使用受控 Key 调用中间件服务态接口

5. 核心概念 ​

5.1 应用与模块 ​

  • addonsType：模块标识，是菜单、角色、权限、应用接入和服务态同步的重要隔离字段。
  • 应用实例：具体接入的应用或微信应用资料。
  • 模块管理：维护模块基础资料和治理模式。

5.2 登录上下文 ​

登录运行态由当前上下文决定，而不是只由用户表字段决定。

关键字段包括：

  • accessMode：role 或 super_admin。
  • authorityId：当前选中的角色 ID。
  • addonsType：当前模块。
  • appUUID：当前应用。
  • isSuperAdminContext：当前是否为超级管理员上下文。

超级管理员用户切换到普通角色上下文后，应按普通角色权限运行。

5.3 页面、菜单和动作 ​

字段含义
pageCode正式页面码，表达一个稳定页面能力
menuFlag菜单承载标识，用于角色菜单授权和运行菜单匹配
actionCode正式动作码，用于按钮、动作和语义权限判断
grantMenuFlags动作对应的菜单授权标识
grantApis动作或页面对应的后端接口权限映射

5.4 grantApis ​

grantApis 是业务动作权限和后端接口权限之间的映射表。

示例：

json
{
  "actionCode": "role.create",
  "grantMenuFlags": ["role::add"],
  "grantApis": [
    {
      "method": "POST",
      "path": "/sys_base/platform/authority/createAuthority"
    }
  ]
}

含义：

text
角色获得 role.create 动作权限
-> 系统读取 role.create 对应的 grantApis
-> 写入 Casbin
-> 后端按 authorityId + path + method 判断接口是否放行

grantApis 只表达接口权限映射，不表达接口性能成本、限流策略或异步执行策略。高成本接口需要额外的性能和风控设计。

5.5 Casbin ​

Casbin 是后端接口权限最终拦截机制。接口请求进入后，后端按以下三元组判断：

text
authorityId + request path + request method

前端按钮权限只控制显示和交互体验，不是安全边界。后端 Casbin 和必要的 manifest runtime guard 才是最终安全边界。

6. 核心业务流程 ​

6.1 登录与身份切换 ​

  1. 用户提交账号、密码和验证码。
  2. 后端返回可用上下文或默认上下文。
  3. 用户在多上下文场景下选择 role 或 super_admin。
  4. 后端签发带当前上下文的 token。
  5. PCWEB 读取用户信息、应用模型、菜单和运行时权限。
  6. PCWEB 根据默认页进入正式页面。
  7. 身份切换后必须重新读取用户信息、菜单、权限和默认页。

6.2 用户与部门管理 ​

  1. 管理员进入部门或用户页面。
  2. 页面按当前上下文加载可见组织、部门、校区和成员。
  3. 管理员新增、编辑、调动成员或维护公共范围。
  4. 后端必须按当前用户可管理范围限制目标数据。

6.3 角色授权 ​

  1. 管理员创建或选择角色。
  2. 管理员为角色绑定应用。
  3. 管理员在授权抽屉中选择页面、动作和默认页。
  4. 后端校验操作者是否有权给目标角色下发这些能力。
  5. 后端保存角色菜单授权到 sys_authority_menus。
  6. 后端根据已授权动作的 grantApis 重建 Casbin。
  7. PCWEB 重新读取权限状态。

6.4 系统菜单发布 ​

  1. 管理员进入系统菜单发布页。
  2. 上传 system_menu 清单。
  3. 后端校验清单结构、页面、动作、菜单承载和默认页。
  4. 管理员提交版本。
  5. 管理员发布版本。
  6. 后端将菜单承载同步到 sys_base_menus。
  7. 当前模块运行菜单以已发布版本为准。

6.5 应用菜单发布 ​

  1. 管理员进入应用菜单发布页。
  2. 选择目标模块和应用范围。
  3. 上传 app_menu 清单。
  4. 后端按 addonsType + catalogType + appScope 隔离版本。
  5. 发布后供应用端或下游模块按正式范围读取。

6.6 应用资料同步 ​

  1. 下游服务态调用方使用受控 Key 请求同步。
  2. 后端按 addonsType 查询被授权的微信应用资料。
  3. 返回最小必要配置资料。
  4. 默认不应返回运行时 AccessToken、业务回调地址或业务私有配置。

当前同步查询仍存在 FIND_IN_SET(addons_id) 的性能隐患，后续应改为模块与应用关系表。

7. 功能模块需求 ​

7.1 登录与身份切换 ​

项目需求
登录支持账号密码登录、验证码校验和上下文装配
身份选择支持普通角色和超级管理员上下文
身份切换切换后重新签发 token，并重建前端运行态
默认页默认页必须来自当前上下文可访问页面
异常旧 token 并发返回不得误踢用户回登录页

7.2 用户管理 ​

项目需求
用户维护支持新增、编辑、启停、删除、重置密码
角色绑定用户可绑定当前模块内角色
组织范围普通角色只能维护可管理范围内用户
超管能力超管上下文可维护全局用户和角色关系

7.3 部门管理 ​

项目需求
部门维护支持组织树、部门新增、编辑、删除
成员管理支持部门成员查看和调动
公共范围支持维护部门公共范围，如校区和模块范围
边界店铺、分账方等业务资源不在部门页维护

7.4 角色管理 ​

项目需求
角色维护支持新增、编辑、删除、复制角色
应用绑定支持角色可进入哪些应用实例
页面授权支持按 pageCode 授权页面
动作授权支持按 actionCode 授权动作
默认页默认页必须属于已授权页面
可管理角色支持设置当前角色还能继续管理哪些角色
接口权限保存授权后同步重建 Casbin

7.5 菜单管理 ​

项目需求
系统菜单管理中间件 PCWEB 治理菜单
应用菜单管理下游应用菜单清单
版本管理支持上传、提交、发布、查看详情、切换当前版本
运行态当前运行菜单只以已发布清单为准
缺省状态未发布时返回空状态，不生成演示菜单或兜底菜单

7.6 模块管理 ​

项目需求
模块资料维护模块标识、名称、治理模式等基础信息
治理模式正式链路固定使用 manifest 治理
下游接入下游模块通过 addonsType 接入菜单和权限

7.7 应用信息与 Key 管理 ​

项目需求
应用信息维护微信应用、支付主体和应用实例资料
Key 管理支持服务态 Key 创建、查询、失效和临时凭证
安全明文密钥只允许创建时返回一次，后续脱敏展示
同步服务态同步只返回授权范围内资料

7.8 日志与审计 ​

项目需求
登录日志记录登录行为
请求日志记录平台请求
运行日志记录关键运行事件
权限审计记录授权保存、Casbin 变更和关键治理动作

8. 前后端协作要求 ​

8.1 后端职责 ​

  • 维护正式接口、运行契约和权限判断。
  • 返回当前上下文、菜单、权限、默认页和公共范围。
  • 保存角色授权，并同步菜单授权和 Casbin。
  • 发布系统菜单和应用菜单。
  • 对未授权接口进行后端拦截。
  • 对历史字段标明兼容边界，不作为新运行契约扩散。

8.2 PCWEB 职责 ​

  • 登录和身份切换后重建运行态。
  • 调用后端正式接口，不本地 mock 正式权限结果。
  • 使用 pageCode 命中本地页面注册表。
  • 对 actionCode 使用 v-auth 或 v-disabled 控制按钮。
  • 对重操作提供 loading、防重复点击和必要确认。
  • 不动态加载后端返回的 component 或 componentPath。

8.3 页面注册边界 ​

后端响应中的 component 和 componentPath 只作为历史承载、发布对照或排查字段。PCWEB 正式运行时必须通过：

text
meta.pageCode -> manifestPageRegistry -> 本地 component loader

不允许把后端返回路径作为动态组件加载契约。

9. 权限设计 ​

9.1 页面权限 ​

页面权限基于：

text
authorityId + addonsType + pageCode 对应 menuFlag

角色拥有页面对应 menuFlag 后，该页面才允许出现在运行菜单中。

9.2 动作权限 ​

动作权限基于：

text
authorityId + actionCode + grantMenuFlags

PCWEB 使用 actionCode 控制按钮显示或禁用。后端保存授权时根据 actionCode 对应的 grantMenuFlags 写入菜单授权。

9.3 接口权限 ​

接口权限基于：

text
authorityId + grantApis.path + grantApis.method

保存授权时，后端根据已授权动作和页面的 grantApis 重建 Casbin。接口请求进入后，后端按 Casbin 判断是否放行。

9.4 超级管理员上下文 ​

超级管理员上下文可访问正式治理能力，但仍必须保持运行上下文清晰。超级管理员切换到普通角色上下文后，必须按普通角色权限运行。

9.5 下游授权 ​

sys_base 自身使用代码清单授权。下游业务模块必须使用已发布 system_menu 授权，不得继续使用 saveAuthorityCodeActions 保存业务菜单授权。

10. 性能与安全分析结果 ​

10.1 当前合理点 ​

  • 权限判断不在每次接口请求时解析完整 manifest，而是保存授权时重建 Casbin。
  • 接口请求最终按 Casbin 判断，权限判断成本较低。
  • 菜单、权限和默认页在登录或身份切换时重建，不要求每个页面重复拉取。
  • 菜单发布、角色授权等重操作属于低频管理动作，允许同步完成。

10.2 当前不合理点 ​

编号问题影响整改要求
P1Casbin 中间件 Redis 校验成功后仍继续本地 Enforce所有受保护接口存在重复权限判断Redis 权限判断改为 allow / deny / miss 三态，allow 直接放行
P2运行态权限复用完整授权状态接口登录或身份切换拿到过重数据新增轻量运行态权限接口，只返回 pageCodes、actionCodes 和版本信息
P3菜单版本列表无分页版本记录增多后打开工作台变慢GetMenuCatalogVersionList 增加分页，默认 20 条，最大 100 条
P4微信应用同步使用 FIND_IN_SET(addons_id)应用数据量增大后查询不可索引化改为模块与应用关系表，使用索引和 JOIN 查询
P5角色授权保存缺少后端互斥和幂等重复提交或并发保存会重复重建 Casbin按 authorityId + addonsType 加短锁，前端防重复提交
P6菜单发布缺少发布锁同一模块并发发布可能竞争按 addonsType + catalogType + appScopeKey 加发布锁
P7Runtime view 每次实时构树菜单管理页频繁刷新时成本偏高按当前发布版本缓存，发布、切换、hidden 更新时失效
P8grantApis 缺少成本和风险等级授权页无法识别高成本或高风险动作后续扩展 costLevel、riskLevel、rateLimitKey、auditRequired

10.3 高成本接口清单 ​

接口成本判断当前结论
POST /sys_base/platform/manifest/saveAuthorityCodeActions保存授权、同步默认页、重建 Casbin低频可接受，但需加锁和防重复
POST /sys_base/platform/manifest/savePublishedMenuAuthority保存下游菜单授权、同步默认页、重建 Casbin低频可接受，但需加锁和防重复
POST /sys_base/platform/manifest/publishMenuCatalogVersion校验清单、同步菜单承载、写发布记录同步可接受，但需发布锁
POST /sys_base/platform/manifest/uploadMenuCatalog校验并保存版本可接受，需控制清单大小
POST /sys_base/platform/manifest/getMenuCatalogVersionList当前无分页必须分页
POST /sys_base/public/service/syncWechatAppsInfo模块授权应用查询，当前使用 FIND_IN_SET必须改数据模型和索引
GET /sys_base/platform/manifest/getPublishedMenuAuthorityStatus构造完整授权树管理页可用，运行态应换轻量接口

11. 非功能需求 ​

11.1 安全 ​

  • 前端权限控制不得作为安全边界。
  • 后端接口必须经过 JWT、上下文和 Casbin 校验。
  • skipList 只能包含登录、验证码、公钥、健康检查等必要公开接口。
  • 生产和预发环境不得配置为 develop 以绕过权限校验。
  • 高风险动作必须记录审计。
  • 服务态同步不得返回未授权应用资料。

11.2 性能 ​

  • 高频运行态接口必须轻量化。
  • 管理页完整树接口不得复用于登录高频链路。
  • 版本列表、用户列表、日志列表必须分页。
  • 低频重操作必须防重复提交。
  • 菜单树和运行视图应按版本缓存。

11.3 稳定性 ​

  • 授权保存和菜单发布需要后端锁避免并发覆盖。
  • Casbin 更新后必须清理 Redis 权限缓存。
  • 权限保存失败不得出现菜单授权成功但 Casbin 未同步的半成功状态。

11.4 可维护性 ​

  • 新增页面必须补 pageCode、本地页面注册和正式文档。
  • 新增动作必须补 actionCode、grantMenuFlags 和必要 grantApis。
  • 新增接口必须确认是否应纳入 grantApis。
  • 历史兼容对象必须标注边界，不得继续扩散。

12. 下游接入要求 ​

下游模块接入中间件时必须满足：

  1. 定义稳定的 addonsType。
  2. 发布正式 system_menu 清单。
  3. 每个页面提供 pageCode、menuFlag、路由信息和用途说明。
  4. 每个动作提供 actionCode、grantMenuFlags 和必要 grantApis。
  5. 未发布菜单时，下游 PCWEB 不得生成兜底菜单。
  6. 下游角色授权必须走 getPublishedMenuAuthorityStatus 和 savePublishedMenuAuthority。
  7. 下游业务接口性能和限流由下游负责，但中间件应提供成本等级和审计扩展位。

13. 验收标准 ​

13.1 后端验收 ​

  • go test ./... 通过。
  • 权限保存后 sys_authority_menus 和 Casbin 同步一致。
  • 未授权角色访问接口返回权限不足。
  • 超级管理员上下文访问正式治理入口正常。
  • 普通角色上下文只返回已授权菜单、动作和默认页。
  • 未发布 system_menu 时返回空菜单或未发布状态，不生成兜底菜单。

13.2 PCWEB 验收 ​

  • npm run build 通过。
  • 登录、身份切换后菜单、权限、默认页重建。
  • v-auth 和 v-disabled 按 actionCode 生效。
  • 页面通过 pageCode 命中本地注册表。
  • 后端 component/componentPath 不作为运行时动态加载来源。
  • 重操作按钮有 loading 和防重复提交。

13.3 文档验收 ​

  • 影响正式行为的代码变更必须同步更新正式文档。
  • 接口文档、契约说明和功能说明保持中文正文。
  • 新增正式接口必须一接口一文档。
  • 下游阅读正式接口和契约时应回到文档平台发布站点。

14. 后续版本规划 ​

v1.1 权限与性能收口 ​

  • 修复 Casbin Redis 与本地 Enforce 重复判断。
  • 增加运行态轻量权限接口。
  • 菜单版本列表分页。
  • 授权保存和菜单发布增加后端锁。

v1.2 数据模型与同步优化 ​

  • 微信应用与模块授权关系改为关系表。
  • SyncWechatAppsInfo 去除 FIND_IN_SET。
  • 菜单树和 runtime view 增加版本缓存。

v1.3 grantApis 风险治理 ​

  • 扩展 grantApis 成本等级、风险等级、限流 key 和审计要求。
  • 清单发布校验 router 与 grantApis 覆盖关系。
  • 高风险动作在授权页展示提示。

15. 附录：正式文档索引 ​

后端正式文档源：

  • addons/sys_base/docs/接口文档
  • addons/sys_base/docs/契约说明
  • addons/sys_base/docs/功能说明

PCWEB 正式文档源：

  • cl-midserver-pcweb-2026/docs/接口文档
  • cl-midserver-pcweb-2026/docs/契约说明
  • cl-midserver-pcweb-2026/docs/功能说明

CL 正式文档平台

统一发布开发规范、中间件接口契约与功能说明