中间件 PCWEB 产品需求说明书

构建时间2026-06-26 20:10:33（Asia/Shanghai）来源项目中间件文档 / 中间件 PCWEB来源仓../cl-midserver-pcweb-2026来源提交号a6480421a5011a12aaed11a4e5dfc18a9b4e69bf

查看文档来源信息

来源目录：docs
来源文件：功能说明/中间件PCWEB产品需求说明书.md

## 1. 文档信息 | 项目 | 内容 | | --- | --- | | 产品名称 | 中间件 PCWEB 管理后台 | | 所属仓库 | cl-midserver-pcweb-2026 | | 后端服务 | cl-midserver-2026 | | 文档类型 | 产品需求说明书（PRD） | | 验证日期 | 2026-05-19 | | 验证方式 | 启动真实 PCWEB 前端，连接真实中间件后端，使用验收角色账号进入页面并截图 | | 验证账号 | governance_role_smoke | | 验证角色 | 系统管理（角色上下文），authorityId=11 | | 验证应用 | appId=0031766249093132337，addonsType=sys_base |

2. 产品定位

中间件 PCWEB 是中间件后台的可视化管理端，面向平台管理员、模块管理员和有授权的运营维护人员，提供部门、用户、角色、菜单、模块、应用、Key、运行日志等公共治理能力。

本产品不是具体业务域后台。外卖、配送、柜子、电影票等下游业务的订单、商品、门店、支付业务流程不在中间件 PCWEB 内维护。中间件 PCWEB 只负责公共能力，包括账号组织、角色授权、模块接入、菜单发布、Key 接入和运行治理。

3. 本次验证结论

本次验证不是只阅读代码或接口文档，而是实际启动 PCWEB 并连接后端服务完成验证。

验证结论：

验证项	结果	说明
PCWEB 开发服务	通过	Vite 服务运行在 `http://localhost:8088`
后端服务	通过	PCWEB 代理已改为访问 `http://127.0.0.1:8181`
登录链路	通过	通过验证码、RSA、`loginNew` 获取真实 token
动态菜单	通过	后端返回 20 个动态菜单标识
正式页面授权	通过	当前角色授权 15 个正式页面
动作权限	通过	当前角色授权 43 个动作权限
系统菜单发布	通过	系统菜单已发布，页面数 15，动作数 43
应用菜单发布	通过	应用菜单已发布，页面数 1，动作数 1
页面截图	通过	已保存登录页和 8 个后台页面真实截图

4. 运行与接入契约

4.1 前端访问地址

环境	地址
本地开发	`http://localhost:8088`

4.2 后端代理配置

PCWEB 本地开发通过 Vite 代理访问中间件后端。

配置项	当前值	说明
`VITE_BASE_API`	`/api`	主业务接口代理前缀
`VITE_SYSTEM_BASE_API`	`/system-api`	系统接口代理前缀
`VITE_SERVER_PORT`	`8181`	主业务接口后端端口
`VITE_SERVER_SYSTEM_PORT`	`8181`	系统接口后端端口
`VITE_APPID`	`0031766249093132337`	当前应用实例
`VITE_ADDONS_TYPE`	`sys_base`	当前中间件模块
`VITE_APP_KEY`	`pc_middle_20260109`	PCWEB 调用后端的应用 Key

4.3 请求头契约

PCWEB 调用中间件后端时必须携带运行上下文。

请求头	来源	用途
`x-token`	登录后 localStorage token	用户认证
`x-user-id`	当前用户信息	操作人识别
`app-id`	`VITE_APPID` 或当前公共范围	应用实例范围
`addons-type`	当前模块标识	模块范围
`x-app-key`	`VITE_APP_KEY`	应用调用身份

4.4 权限判断契约

PCWEB 权限不是由前端硬编码决定，而是由后端正式发布的菜单、角色授权和 Casbin 接口权限共同决定。

核心链路：

后端发布系统菜单或应用菜单。
菜单节点通过 menuFlag、pageCode、actionCode 表达页面和动作。
角色授权保存页面和动作授权。
页面运行时通过 getMenu 获取可见菜单。
前端通过 meta.pageCode 匹配本地 manifest 页面注册表。
动作按钮通过后端返回的动作授权控制显示或禁用。
后端接口最终由 Casbin 和接口内上下文校验兜底。

边界要求：

项	要求
页面渲染	以 `meta.pageCode` 加前端本地 manifest 注册表为准
历史字段	`component`、`componentPath` 只作为历史承载、发布比对或维护字段，不作为正式运行加载依据
按钮动作	以 `actionCode` 授权结果控制
接口权限	以后端 Casbin 和接口内部上下文校验为最终准入
未发布菜单	不应进入正式运行态
未授权页面	不应进入动态菜单和前端路由

5. 用户角色

角色	使用目标	典型操作
平台管理员	维护中间件公共能力	配置部门、角色、用户、模块、菜单、Key
模块管理员	维护指定模块范围	查看本模块菜单、配置应用菜单、维护模块 Key
运营维护人员	查看运行状态和基础数据	查看运行日志、登录日志、请求日志、字典等
下游开发或接入方	理解菜单和权限契约	接入应用菜单、使用临时 Key 调用接口

6. 页面与功能需求

6.1 登录页

登录页

页面目标

为中间件 PCWEB 提供统一登录入口，完成账号、密码、验证码和 RSA 加密登录。

功能需求

功能	说明
用户名输入	输入平台账号
密码输入	输入账号密码，支持明文/密文显示切换
验证码	展示后端验证码图片，点击图片可刷新
登录	调用 `loginNew` 完成认证
身份选择	当账号存在多个角色或超级管理员上下文时，弹窗选择登录身份

关键接口

接口	用途
`POST /sys_base/public/base/captcha`	获取验证码
`GET /sys_base/public/base/rsaPublicKey`	获取 RSA 公钥
`POST /sys_base/public/base/loginNew`	登录
`POST /sys_base/public/base/selectRole`	多身份登录选择

验收标准

标准	结果
验证码可生成	通过
RSA 登录可用	通过
token 可生成	通过
登录后能进入授权页面	通过

6.2 部门管理

部门管理

页面目标

维护中间件公共组织范围。部门决定用户可覆盖的组织、校区、模块等公共范围，不负责具体业务资源配置。

功能需求

功能	说明
部门树展示	展示当前账号可管理的部门层级
搜索与重置	按部门名称或状态筛选
新增部门	创建公共部门节点
编辑部门	修改部门名称、状态、公共范围
启用/禁用	控制部门是否可用
删除部门	删除符合条件的部门
公共范围提示	明确部门只维护公共范围，不维护角色授权和业务资源

关键边界

部门管理不维护页面权限、按钮权限、店铺、分账方、商户转账等业务域资源。角色授权在角色管理页维护，业务资源在下游模块维护。

关键接口

接口	用途
`POST /sys_base/platform/organization/getOrgTreeList`	获取部门树
`POST /sys_base/platform/organization/getOrgTreeListByShow`	获取启用部门树
`POST /sys_base/platform/organization/createOrganization`	新增部门
`PUT /sys_base/platform/organization/updateOrganization`	更新部门
`DELETE /sys_base/platform/organization/deleteOrganization`	删除部门
`POST /sys_base/platform/organizationMidArea/setOrganizationMidArea`	设置部门校区范围
`POST /sys_base/platform/organizationMidAddons/setOrganizationMidAddons`	设置部门模块范围

6.3 角色管理

角色管理

页面目标

维护角色基础信息、角色可见页面、按钮动作授权和默认首页。角色是中间件权限配置的核心对象。

功能需求

功能	说明
角色列表	展示当前模块范围内可管理角色
新增角色	创建角色并设置角色标识
编辑角色	修改角色名称、父级、状态等
删除角色	删除未被引用或符合删除条件的角色
授权设置	按菜单树配置页面权限和操作权限
绑定应用	配置角色可访问的应用实例
默认首页	设置角色进入系统后的默认页面
授权复制	将一个角色授权复制到另一个角色

权限规则

项	规则
页面权限	来自已发布菜单中的 `pageCode`
动作权限	来自已发布菜单中的 `actionCode`
菜单分组	可勾选批量控制下级页面和操作，但不直接保存为角色权限
接口权限	由 `grantApis` 写入 Casbin 后生效
默认首页	必须是该角色已授权且前端已注册的页面
超级管理员上下文	可绕过角色页面授权，但接口仍需要上下文校验

授权交互

角色授权页按后端正式发布的菜单树展示授权范围。菜单分组用于还原系统菜单层级，可以勾选后批量选择或取消下级页面和操作，但分组自身不会保存为角色权限；页面节点勾选后保存为 pageCode，表示角色可以进入该页面；页面下的操作节点勾选后保存为 actionCode，表示角色可以在对应页面执行该操作。保存时仍由后端根据动作关联的 grantApis 写入 Casbin，前端不直接维护接口权限。

关键接口

接口	用途
`POST /sys_base/platform/authority/getAuthorityList`	获取角色列表
`POST /sys_base/platform/authority/createAuthority`	创建角色
`PUT /sys_base/platform/authority/updateAuthority`	更新角色
`POST /sys_base/platform/authority/deleteAuthority`	删除角色
`POST /sys_base/platform/authority/bindAuthorityApps`	绑定角色应用
`GET /sys_base/platform/manifest/getAuthorityCodeActionStatus`	获取角色页面和动作授权状态
`POST /sys_base/platform/manifest/saveAuthorityCodeActions`	保存角色页面和动作授权

6.4 系统菜单

页面目标

查看当前模块已经发布并生效的系统菜单结构，确认页面、动作、菜单层级和发布状态。

功能需求

功能	说明
模块切换	按模块查看系统菜单
生效菜单树	展示当前正式生效菜单
下载清单	下载当前菜单清单
查看详情	查看页面、动作和接口授权配置
进入发布工作台	处理清单预校验、保存草稿、提交、发布和切换版本

正式边界

系统菜单页面展示的是当前正式运行态菜单。选择 JSON 清单时必须立即完成本地结构检查和服务端预校验；存在阻断项时展示字段和修复建议，保存草稿按钮不可用。未发布、未提交或校验失败的菜单清单不能进入运行态，也不能保存为新的草稿版本。

关键接口

接口	用途
`POST /sys_base/platform/menu/getMenu`	获取当前用户运行菜单
`POST /sys_base/platform/manifest/getMenuCatalogRuntimeView`	获取运行态菜单清单
`GET /sys_base/platform/manifest/getMenuCatalogDetail`	获取菜单清单详情
`POST /sys_base/platform/manifest/getMenuCatalogPublishStatus`	获取发布状态
`POST /sys_base/platform/manifest/validateMenuCatalog`	选择文件后预校验菜单清单
`POST /sys_base/platform/manifest/uploadMenuCatalog`	保存已通过校验的菜单清单草稿
`POST /sys_base/platform/manifest/publishMenuCatalogVersion`	发布菜单版本

6.5 用户管理

用户管理

页面目标

按组织范围管理中间件后台用户，维护账号、基础信息、角色分配、状态和组织归属。

功能需求

功能	说明
组织树	左侧展示当前账号可管理组织
用户列表	右侧展示当前组织范围下用户
新增用户	创建后台账号并分配角色
编辑用户	修改用户资料、组织和角色
设置管理员	设置或取消部门管理员
更换组织	调整用户所属组织
重置密码	管理员重置用户密码
启用/禁用	控制用户账号状态

关键边界

用户管理只维护平台账号与组织、角色关系。具体业务用户、客户、骑手、商户等下游身份不在本页维护。

关键接口

接口	用途
`POST /sys_base/platform/user/getUserList`	获取用户列表
`GET /sys_base/platform/organization/findOrgUserListByPowerAll`	获取权限范围内组织用户
`POST /sys_base/platform/user/admin_register`	新增后台用户
`PUT /sys_base/platform/user/setUserInfo`	更新用户信息
`POST /sys_base/platform/user/setUserAuthority`	设置用户角色
`DELETE /sys_base/platform/user/deleteUser`	删除用户
`PUT /sys_base/platform/organization/setOrgUserAdmin`	设置部门管理员

6.6 应用菜单发布

页面目标

按模块和应用范围维护应用菜单发布状态，支撑下游应用菜单的正式发布和运行态查看。

功能需求

功能	说明
模块切换	查看不同模块的应用菜单
应用范围	当前前端入口暂只开放按具体应用查看和发布应用菜单
运行态查看	展示当前已生效应用菜单
选择清单	选择新的应用菜单 JSON 并立即预校验
保存草稿	将已通过校验的应用菜单清单保存为草稿版本
提交版本	校验并提交菜单版本
发布版本	将通过校验的版本发布为运行态
切换版本	将指定已发布版本切换为当前生效版本

关键边界

应用菜单发布只处理菜单和权限入口，不处理下游业务页面内部逻辑。当前前端入口暂只开放“按具体应用”范围，其他范围模式仅作为后端能力和历史数据解释保留，不在页面下拉中展示。下游业务系统需要按发布后的 pageCode、actionCode 和接口权限契约接入。选择 JSON 清单时必须立即完成本地结构检查和服务端预校验；存在阻断项时展示字段和修复建议，保存草稿按钮不可用，不能把无效清单保存成不可用草稿。

关键接口

接口	用途
`POST /sys_base/platform/manifest/getMenuCatalogRuntimeView`	获取应用菜单运行态
`POST /sys_base/platform/manifest/validateMenuCatalog`	选择文件后预校验菜单清单
`POST /sys_base/platform/manifest/uploadMenuCatalog`	保存已通过校验的菜单清单草稿
`POST /sys_base/platform/manifest/submitMenuCatalogVersion`	提交菜单版本
`POST /sys_base/platform/manifest/publishMenuCatalogVersion`	发布菜单版本
`POST /sys_base/platform/manifest/getMenuCatalogVersionList`	获取版本列表
`POST /sys_base/platform/manifest/generateMenuCatalogExample`	生成示例清单

6.7 模块管理

模块管理

页面目标

维护接入中间件的模块定义，包括模块名称、模块标识、排序和治理模型。

功能需求

功能	说明
模块列表	展示已接入模块
搜索与重置	按模块名称或标识筛选
新增模块	创建模块定义
编辑模块	修改模块基础信息
删除模块	删除符合条件的模块
治理模型	标识模块是否使用 manifest 菜单治理

关键接口

接口	用途
`GET /sys_base/platform/appModel/getAppModelList`	获取模块列表
`POST /sys_base/platform/appModel/createAppModel`	新增模块
`PUT /sys_base/platform/appModel/updateAppModel`	更新模块
`DELETE /sys_base/platform/appModel/deleteAppModel`	删除模块

6.8 Key 管理

Key 管理

页面目标

维护应用 permanent key 元信息，为下游系统换取短期 tempKey 提供基础。

功能需求

功能	说明
Key 列表	展示应用 Key 摘要、类型、状态和有效期
新增 Key	生成新的 permanent key
明文展示	创建成功后一次性展示明文 permanent key
启用/停用	控制 Key 是否可用
删除 Key	删除或废弃指定 Key
刷新	重新加载 Key 列表

安全规则

项	规则
permanent key	只在创建成功后一次性展示明文
tempKey	下游运行时应使用短期 tempKey
调用范围	Key 必须绑定应用、模块和有效状态
审计	Key 使用应记录最近使用时间和运行日志

关键接口

接口	用途
`GET /sys_base/platform/appKey/list`	获取 Key 列表
`POST /sys_base/platform/appKey/upsert`	新增或更新 Key
`GET /public/getTempKey`	通过 permanent key 换取 tempKey

6.9 运行日志

运行日志

页面目标

查看中间件运行日志，辅助排查接口调用、权限写入、运行异常和审计问题。

功能需求

功能	说明
日志列表	展示运行记录
查询	按单号、Key、Value、状态等条件筛选
重置	清空查询条件
状态识别	标识运行记录状态
创建时间	查看日志产生时间

关键接口

接口	用途
`GET /sys_base/platform/sysRunningRecord/getSysRunningRecordList`	获取运行日志列表

7. 页面清单

本次角色授权范围内，后端返回 15 个正式页面。当前 PRD 截图覆盖主要产品流程页面，剩余页面属于系统辅助能力，可在后续按同一模板补图。

页面	pageCode	menuFlag	本次截图
部门管理	`organization.department.manage`	`department`	已覆盖
系统菜单	`system.menu.manage`	`menu`	已覆盖
角色管理	`system.role.manage`	`role`	已覆盖
用户管理	`organization.member.manage`	`user`	已覆盖
应用菜单	`app.menu.publish`	`appMenuPublish`	已覆盖
模块管理	`app.model.manage`	`moduleManage`	已覆盖
Key 管理	`app.app_key.manage`	`appKey`	已覆盖
运行日志	`system.run_log.view`	`runLog`	已覆盖
应用信息	`app.wechat.manage`	`appInfo`	未单独截图
校区管理	`organization.area.manage`	`sysArea`	未单独截图
图片管理	`system.upload.manage`	`upload`	未单独截图
字典管理	`system.dictionary.manage`	`dictionary`	未单独截图
请求日志	`system.operation_log.view`	`requestLog`	未单独截图
登录日志	`system.login_log.view`	`loginLog`	未单独截图
系统配置	`system.setting.manage`	`config`	未单独截图

8. 非功能需求

8.1 安全

需求	说明
登录加密	登录用户名和密码使用 RSA 加密
验证码	登录必须校验验证码
token 认证	后台接口必须携带 `x-token`
应用身份	后台接口必须携带 `app-id`、`addons-type`、`x-app-key`
权限兜底	前端隐藏按钮不是安全边界，后端接口必须校验 Casbin 和上下文
Key 明文	permanent key 明文只允许创建后一次性展示
历史字段	前端不得使用后端 `component` 或 `componentPath` 动态加载页面

8.2 性能

场景	当前判断	要求
登录初始化	会并发获取用户信息和模块列表	保持接口并发，避免串行阻塞
动态菜单	登录后加载一次菜单树	菜单树应控制层级和节点数量
角色授权	页面和动作授权数据量可能较大	授权状态接口应按模块、角色和应用范围收敛
用户列表	组织范围可能很大	必须分页，组织树和用户列表分开加载
日志列表	数据增长快	必须分页和条件查询，避免全量加载
菜单发布	清单校验可能较重	上传、校验、发布应分阶段执行，并返回明确状态

8.3 可维护性

需求	说明
页面注册	正式页面必须进入前端 manifest 注册表
页面文档	重要页面需要同步维护功能说明
接口文档	正式接口应保持一接口一文档
权限命名	`menuFlag`、`pageCode`、`actionCode` 应稳定且语义清晰
下游接入	下游不能依赖中间件历史兼容字段生成运行页面

9. 当前合理性与待优化项

9.1 已合理闭环

项	结论
PCWEB 代理端口	已调整为后端实际端口 `8181`
登录链路	已通过真实后端验证
菜单运行态	已能从后端正式发布菜单生成动态路由
前端页面加载	已按 `pageCode` 匹配本地 manifest 注册页面
角色授权	页面和动作授权已能返回并控制前端
后端门禁	`go test ./...` 已通过上一轮验证
PCWEB 构建	`npm run build` 已通过上一轮验证

9.2 仍需持续收口

项	风险	建议
页面截图覆盖	本 PRD 已覆盖核心页面，但未覆盖全部 15 个页面	后续补齐应用信息、校区、图片、字典、请求日志、登录日志、系统配置截图
历史兼容字段	后端仍可能返回 `component`、`componentPath`	文档已明确不能作为正式运行加载依据，后续接口可逐步降级为维护字段
历史业务结构	支付辅助结构已标记废弃，但仍可能被误用	下游业务支付逻辑应迁移到下游业务模块，中间件只保留公共接入能力
权限性能	授权接口在角色、页面、动作增多后可能变重	保持按模块、角色、应用范围查询，必要时增加缓存和增量保存
日志性能	日志表数据增长后查询压力较大	保持分页、索引、按时间范围查询和定期归档

10. 发布验收标准

中间件 PCWEB 达到可发布状态时，应满足以下标准：

标准	判定方式
前端可构建	`npm run build` 通过
后端测试通过	`go test ./...` 通过
登录可用	可通过验证码、RSA、token 完成登录
菜单可加载	`getMenu` 返回当前用户有权菜单
页面可进入	已授权页面不跳 404，不回退到登录页
未授权不可见	未授权页面不应出现在菜单和路由中
动作受控	按钮按动作授权显示或禁用
接口受控	后端接口权限校验生效
截图可复核	PRD 中页面截图来自真实运行环境

11. 附录：本次真实验证截图

截图	文件
登录页	`docs/功能说明/assets/middleware-pcweb-prd/01-login.png`
部门管理	`docs/功能说明/assets/middleware-pcweb-prd/02-department.png`
角色管理	`docs/功能说明/assets/middleware-pcweb-prd/03-role.png`
系统菜单	`docs/功能说明/assets/middleware-pcweb-prd/04-system-menu.png`
用户管理	`docs/功能说明/assets/middleware-pcweb-prd/05-user.png`
应用菜单发布	`docs/功能说明/assets/middleware-pcweb-prd/06-app-menu-publish.png`
模块管理	`docs/功能说明/assets/middleware-pcweb-prd/07-module.png`
Key 管理	`docs/功能说明/assets/middleware-pcweb-prd/08-app-key.png`
运行日志	`docs/功能说明/assets/middleware-pcweb-prd/09-run-log.png`

中间件 PCWEB 产品需求说明书 ​

2. 产品定位 ​

3. 本次验证结论 ​

4. 运行与接入契约 ​

4.1 前端访问地址 ​

4.2 后端代理配置 ​

4.3 请求头契约 ​

4.4 权限判断契约 ​

5. 用户角色 ​

6. 页面与功能需求 ​

6.1 登录页 ​

页面目标 ​

功能需求 ​

关键接口 ​

验收标准 ​

6.2 部门管理 ​

页面目标 ​

功能需求 ​

关键边界 ​

关键接口 ​

6.3 角色管理 ​

页面目标 ​

功能需求 ​

权限规则 ​

授权交互 ​

关键接口 ​

6.4 系统菜单 ​

页面目标 ​

功能需求 ​

正式边界 ​

关键接口 ​

6.5 用户管理 ​

页面目标 ​

功能需求 ​

关键边界 ​

关键接口 ​

6.6 应用菜单发布 ​

页面目标 ​

功能需求 ​

关键边界 ​

关键接口 ​

6.7 模块管理 ​

页面目标 ​

功能需求 ​

关键接口 ​

6.8 Key 管理 ​

页面目标 ​

功能需求 ​

安全规则 ​

关键接口 ​

6.9 运行日志 ​

页面目标 ​

功能需求 ​

关键接口 ​

7. 页面清单 ​

8. 非功能需求 ​

8.1 安全 ​

8.2 性能 ​

8.3 可维护性 ​

9. 当前合理性与待优化项 ​

9.1 已合理闭环 ​

9.2 仍需持续收口 ​

10. 发布验收标准 ​

11. 附录：本次真实验证截图 ​

中间件 PCWEB 产品需求说明书

2. 产品定位

3. 本次验证结论

4. 运行与接入契约

4.1 前端访问地址

4.2 后端代理配置

4.3 请求头契约

4.4 权限判断契约

5. 用户角色

6. 页面与功能需求

6.1 登录页

页面目标

功能需求

关键接口

验收标准

6.2 部门管理

页面目标

功能需求

关键边界

关键接口

6.3 角色管理

页面目标

功能需求

权限规则

授权交互

关键接口

6.4 系统菜单

页面目标

功能需求

正式边界

关键接口

6.5 用户管理

页面目标

功能需求

关键边界

关键接口

6.6 应用菜单发布

页面目标

功能需求

关键边界

关键接口

6.7 模块管理

页面目标

功能需求

关键接口

6.8 Key 管理

页面目标

功能需求

安全规则

关键接口

6.9 运行日志

页面目标

功能需求

关键接口

7. 页面清单

8. 非功能需求

8.1 安全

8.2 性能

8.3 可维护性

9. 当前合理性与待优化项

9.1 已合理闭环

9.2 仍需持续收口

10. 发布验收标准

11. 附录：本次真实验证截图