17 — 应用商店接入规范

面向业务系统 / 第三方应用开发方：说明怎样按门户既有规范把应用做出来，才能被管理员登记进应用商店，并被用户开通后正常打开。

权威：以当前代码与门户主数据为准（sys_system、sys_portal_app、sys_sso_client、商店上架发布校验）。
商店本身没有第三方入站开放 API（无 HMAC/OAuth 的「自助上架」）。上架、权益、开通由门户管理员与已登录用户完成。
关联：用户与管理员操作见使用手册 · 应用商店、门户运营；工程说明见 doc/55-应用商店.md；SSO 见 04-SSO接入-IdP.md；权限码见 doc/43-门户应用权限码与菜单联动.md。

1. 结论先说

你要交付什么	门户侧怎么用
可访问的业务地址（HTTPS 推荐）	登记为门户应用的电脑/手机 URL
打开方式：外链或内嵌	`openMode = EXTERNAL` 或 `IFRAME`（已有站内页可用 `INTERNAL`）
需要免登时：按门户 IdP 做授权码回调	管理员登记已有 SSO Client，应用绑定 `clientId`
需要按人控制可见时：约定入口权限码	门户应用 `permCode`；商店开通时写入用户个人商店角色

不要做：为进商店单独打应用包、接微前端运行时、自助注册 SSO Client、或调用 /api/admin/portal/store/**、/api/portal/store/**（后者仅门户会话用户使用）。

一期商店上架范围：

方式	能否上架
外链 `EXTERNAL`	可以
内嵌 `IFRAME`（页面允许被门户嵌套）	可以
免登（建在外链/内嵌上，复用已开通 SSO Client）	可以
站内页 `INTERNAL`（页面已在门户内存在）	可以
纯展示 `NONE`（无可打开地址）	不可以
独立部署编排 / 应用包 / 微前端	不在一期

2. 推荐落地顺序

text

① 业务系统可独立访问
② 门户登记「业务系统」sys_system
③（可选）登记 SSO Client，完成免登联调
④ 门户登记「门户应用」sys_portal_app（地址 + openMode + permCode）
⑤ 用普通账号在办事大厅/首页点开验证
⑥ 管理员在应用商店上架、（按需）签发可装权益、发布
⑦ 用户在商店开通后，工作台按 permCode 可见并可打开

第 ⑥⑦ 步由门户运营完成；你方重点保证 ①～⑤。

3. 业务系统与门户应用

3.1 业务系统

在管理端「集成对接」登记系统，拿到稳定的 system_code。
后续 SSO Client、门户应用都挂在该编码下，不要中途随意改码。

3.2 门户应用（商店挂接对象）

管理员在「门户应用管理」创建时，你方需提供或约定：

字段	要求
`portalAppCode`	全局唯一业务编码，建议小写+下划线，如 `fin_expense`
`portalAppName`	展示名称
`systemCode`	已登记的业务系统
`openMode`	`EXTERNAL` / `IFRAME` /（已有）`INTERNAL`
`pcUrl` / `appUrl`	可打开地址；`NONE` 不能进商店
`permCode`	入口权限；空=全员可见（开通只记安装账，不写角色）
`clientId`	需要免登时绑定已开通的 SSO Client
`supportPc` / `supportMobile`	与真实能力一致，避免大厅出现却打不开

权限码推荐形态：portal:{应用码小写}:view，并与角色授权、菜单联动约定一致（见 doc/43）。

3.3 打开方式注意点

`openMode`	应用侧注意
`EXTERNAL`	新窗口打开；注意浏览器弹窗拦截；回调域名登记正确
`IFRAME`	允许被门户域名嵌套（`X-Frame-Options` / CSP `frame-ancestors`）；登录态、Cookie `SameSite` 需可在嵌套场景工作
`INTERNAL`	仅门户站内路由；第三方业务系统一般不用

发布到商店时，商品会抄写当时的 openMode；之后改门户应用打开方式，已发布商品在运营再次保存/发布时才会同步策略（以管理端实际操作为准）。

4. 免登（SSO）

需要「从门户点进业务不再输密码」时：

按 01-接入准备.md 由门户管理员创建 CONFIDENTIAL Client，绑定你的 system_code。
按 04-SSO接入-IdP.md 实现授权码回调（OAuth2 / OIDC 等）。
client_credentials 未开通，勿按机器账号取 Token 设计用户免登。
门户应用绑定该 clientId；联调在办事大厅点开验证，再进商店。

商店不会替你创建 SSO Client，也不会下发 SDK 包。

5. 与商店开通的关系（给开发的预期）

用户开通商店商品后，门户侧行为：

步骤	说明
校验商品已发布	下架后不能新开通
校验可装权益	免费/不要求权益的商品可跳过；否则需 PLATFORM 或用户部门匹配的 ORG 权益
写开通记录	仅商店账本；不是工作台白名单
授予入口权限	`permCode` 非空时，写入该用户个人角色 `STORE_U_{userId}`
打开应用	仍读 `sys_portal_app` 的地址 / `openMode` / SSO

因此：

你方不必实现「商店开通回调」才能被打开；
你方必须保证应用 URL 与免登在门户打开链路下可用；
卸载只会收回商店个人角色上的那条 permCode；用户若还有业务角色持有同一权限，入口仍可见。

6. 交付给门户运营的检查清单

联调通过后，把下列信息交给管理员即可上架：

[ ] system_code、业务系统名称
[ ] portalAppCode、展示名称、图标（可选）
[ ] 电脑 / 手机打开地址
[ ] 打开方式：EXTERNAL 或 IFRAME（及是否允许嵌套）
[ ] 是否免登；若是，已开通的 client_id 与回调地址列表
[ ] 入口 permCode（或确认全员可见）
[ ] 商店文案：标题、简介、开发商、版本号、更新说明、截图 URL（可选）
[ ] 是否需要「可装权益」（按单位/部门控制谁能开通）

7. 非目标与常见误解

误解	正解
商店提供开放「自助上架」API	无；管理员在门户管理端操作
进商店要改造为微前端 / 打安装包	一期不要
开通后工作台用安装记录过滤	否；只用原来的 `permCode`
个人商店角色会做出向权限同步	否；`STORE_U_` 前缀跳过权限出向
用 OAuth Token 调 `/api/portal/store/**`	不可；商店用户 API 走门户登录会话

8. 相关文档

文档	用途
01-接入准备.md	Client、`system_code`、统一响应
04-SSO接入-IdP.md	免登端点与流程
使用手册 · 应用商店	用户怎么开通
门户运营	管理员怎么上架
`doc/55-应用商店.md`	工程与接口总览
Knife4j `/doc.html`	运行时字段级 OpenAPI（管理/门户分组，非 open）

17 — 应用商店接入规范 ​

1. 结论先说 ​

2. 推荐落地顺序 ​

3. 业务系统与门户应用 ​

3.1 业务系统 ​

3.2 门户应用（商店挂接对象） ​

3.3 打开方式注意点 ​

4. 免登（SSO） ​

5. 与商店开通的关系（给开发的预期） ​

6. 交付给门户运营的检查清单 ​

7. 非目标与常见误解 ​

8. 相关文档 ​