HTTP 接口索引

本页收录「应用市场」模块对外暴露的全部 HTTP 端点，按用途分组。

来源是源码本身，不是约定：

• wujies-modules/wujies-app-market/.../controller/ 下的 9 个 *Controller；
• 目录服务接口 catalog/AppCatalogApiController（注意它在 catalog/ 包，不在 controller/ 包）；
• 路径与请求头常量 catalog/CatalogApiContract；
• 业务码契约 wujies-common-core 的 plugin/AppRouteHintProvider。

通用约定复制标题链接

分组速览复制标题链接

市场浏览（安装侧）复制标题链接

AppMarketController，前缀 /app/market。只读接口：逛市场与看详情，安装动作在 /app/install。

数据不读本地目录表，而是走 IAppCatalogService——远程目录模式下本地没有目录数据，不这么做就会出现「能装但逛不了市场」。

可见范围由登录身份解析，不由前端传：超级管理员不限；C 端用户（APP_USER）对应 member；其余 B 端用户对应 tenant。

应用上架（上架端）复制标题链接

AppConsoleController，前缀 /app/console。面向平台运营，维护应用目录 app_info。

两处硬约束：

• 上架前必须至少有一个已发布版本（latest_version 非空），否则报「应用尚未发布任何版本，无法上架」；
• appId/status 变更会整片失效菜单缓存，因为「已上架数量」决定菜单过滤是否启用。

GET /app/console/owned-menus 也在这个前缀下，但用途是菜单归属，列在「菜单归属」一节。

应用分类复制标题链接

AppCategoryController，前缀 /app/category。分类是全局表（在 tenant.excludes 中）。

读接口不是上架端专属：市场页要用 GET /app/category/list 做筛选，所以用户版（edition=client）只拦这里的两条写方法。

版本与安装包复制标题链接

版本的维护与发布在 AppVersionController（前缀 /app/version），安装包解析上传在 AppPackageController（前缀 /app/package）。

安装、升级与卸载（安装侧）复制标题链接

AppInstallController，前缀 /app/install。安装 / 启用 / 停用 / 卸载都返回任务 ID，进度与日志经任务中心查询。

// POST /app/install 请求体（AppInstallBo）
{ "appCode": "gallery", "tenantId": null }

purge=true 只是本租户的意愿，不是执行的保证：只要还有别的租户装着同一应用，删菜单 / 删数据表 / 删迁移记录 / 删本机产物都会被跳过，原因写在任务日志里——那些东西是整个部署共享的。

运行时答复（宿主前端）复制标题链接

AppRuntimeController（前缀 /app/runtime）与 AppEditionController（前缀 /app/edition）。这三个端点没有权限注解，原因见下一节。

/app/runtime/remote-apps 的两个细节值得记住：入口带 ?v=<版本号>（不带会被浏览器旧缓存命中，表现为「升级成功但页面还是老样子」）；单条坏数据只记 WARN 跳过，不会让整份清单为空。

工作台复制标题链接

AppWorkbenchController，前缀 /app/workbench。

入口路径 homePath 是三级兜底的结果：当前版本菜单映射 → 跨版本按 appId 找根 → app_info.home_path；三级都取不到时应用卡片会被前端过滤掉。

目录服务（服务间）复制标题链接

AppCatalogApiController，前缀 /app/catalog。调用方是另一个部署的 RemoteAppCatalogService（app-market.catalog.mode=remote 时装配），不是浏览器。

事实清单：

• 请求头名是 X-Catalog-Token，常量在 CatalogApiContract.TOKEN_HEADER，两端共用（路径也共用，避免改一处忘一处）。
• 服务端令牌来自 app-market.catalog.token。留空表示不校验调用方（启动时打一条 WARN）；非空时比对，不区分「没带」与「带错」，只回 ServiceException("目录接口令牌校验失败")。
• 因为调用方没有本机登录会话，/app/catalog/** 写在 wujies-admin 的 security.excludes 里。
• 它读的是平台级目录数据（app_info / app_version / app_category，均已在 tenant.excludes 中），不含任何租户的安装实例；安装实例（app_install / app_install_task / app_schema_history）始终留在各自部署本地。
• 不套 R 包装：调用方是自家 Java 客户端，出错时照样由 GlobalExceptionHandler 吐 {code,msg}，客户端取 msg 原样抛出，以保证远程模式与本地模式的报错文案一致。

配置见 /reference/config（app-market.catalog.mode / base-url / token）。

菜单归属复制标题链接

应用装的菜单是 sys_menu 里的普通行，菜单管理页需要知道「哪些菜单是应用装的」。权威记录是 app_version_menu，反查链为：app_install → app_info → app_version → app_version_menu。

两点说明：

• 权限用菜单管理的读权限而不是应用市场权限——这份数据是菜单管理页的附属信息，能看菜单列表的人就该能拿到；
• 改 path / component / perms / menuType / parentId 与删除这类菜单，由 SysMenuServiceImpl 在服务端拦截（MenuOwnershipProvider，缺席即「没有受保护菜单」）。这一段没有对应的 HTTP 端点，走的是平台既有的菜单管理接口。

不加权限注解的端点复制标题链接

有三个端点刻意不挂 @SaCheckPermission：

三者仍在登录拦截范围内，因此实际要求是「已登录即可」。

GET /app/workbench/apps 走的是同一个判断：它有 @SaCheckLogin 而没有功能权限注解——B 端与 C 端用户都要看工作台，而数据本身已按租户与可见范围收敛。

# 形态自述：任何登录用户的 token 都可以调
curl.exe -H "Authorization: Bearer <token>" http://localhost:8080/app/edition

业务码复制标题链接

响应体统一 {code, msg, data}；code 沿用平台约定（200 成功、401 未授权、403 拒绝、404、500 系统异常、601 警告），前端常量在 plus-ui/src/enums/RespEnum.ts。

应用市场只新增了一个专用码：4610。

4610：应用不可用复制标题链接

含义：你请求的这条路径曾经属于某个插件应用，而那个应用现在没在跑。HTTP 语义仍是「资源不存在」（走的就是同一个 404 兜底），但响应体的 code 是 4610，msg 是应用市场给出的具体措辞。

常量定义在 wujies-common-core 的 AppRouteHintProvider.CODE_APP_UNAVAILABLE，实现是 app-market 的 AppRouteHintResolver。

触发条件（三件同时成立才给提示）：

措辞（msg）按安装状态分四种：

未登录时（例如 token 过期后打的请求）以及远程目录模式下查不到安装记录时，走「未安装或已卸载」这句兜底。

前端怎么区分「应用被卸载」和「真 404」：

不要匹配中文文案，比较响应体的 code：

plus-ui/src/utils/request.ts 里的判定就是 code === HttpStatus.APP_UNAVAILABLE。

治本的配套是 GET /app/runtime/enabled-apps：前端在调某个应用的接口之前先问一次「它现在可用吗」，把 4610 从事后补救变成事前避免。

相关阅读复制标题链接

• 目录中心化与版本形态
• 生命周期
• 远程应用
• 使用应用