25 KiB
Continental Retail APP Architecture Diagram 详细说明
本文用于解释 architecture-diagram.drawio 中的 3 张系统架构图，帮助产品、研发、架构、移动端、后端、集成、测试和评审人员快速理解这套系统为什么这样设计、每一页分别在说明什么、不同域之间的关系如何划分，以及关键访问链路和治理规则如何落地。
这 3 张图不是数据库设计图，也不是接口字段定义图，更不是某台服务器部署细节图。它们的定位是：
- 用于统一架构认知。
- 用于评审系统边界和责任归属。
- 用于说明主访问链路和例外链路。
- 用于帮助研发和测试理解关键业务运行方式。
1. 这 3 张图整体在表达什么
这套图表达的是一套“统一移动入口、主后台统一编排、历史后台保留独立边界、供应商能力受控接入”的系统架构。
它的核心目标不是把所有历史系统都并进一个后台，而是在保留实际业务边界的前提下，把移动端访问链路重新组织成一个清晰、可治理、可演进的体系。
3 张图分别承担不同职责：
System Overview说明系统能力分别归谁拥有，重点是“谁负责什么”。System Architecture说明系统按层分布后的结构关系，重点是“系统怎么连接、怎么治理”。Key Flows and Context Governance说明关键业务链路在运行时如何流转，重点是“具体流程怎么走、异常和上下文怎么管”。
这 3 张图共同强调以下架构原则：
Mobile App -> App Backend是唯一主访问链路。App Backend是 APP 的主后台和统一业务编排中心。Mini Program Backend继续保持独立后台域，不直接并入主后台。F6 Supplier Domain是供应商能力域，不被定义为 APP 主后台。Mobile App -> F6只允许发生在嵌入式WebView场景。App Backend -> F6 APIs必须经过F6 Integration Adapter。- 历史 Mini 直连链路只保留为兼容路径，不作为推荐默认方案。
2. 图例和颜色到底在表达什么
为了让读图的人在 3 页之间建立统一认知，这套图对颜色和线条语义做了固定约定。
2.1 颜色语义
- 蓝色区域和蓝色节点
表示 APP 本身和
App Backend主域相关能力。 - 绿色区域和绿色节点
表示保留的
Mini Program Backend历史业务域。 - 橙色区域和橙色节点
表示
F6 Supplier Domain、WebView 入口、供应商接入和集成适配层。 - 灰色区域和灰色说明 表示通用治理、跨域聚合、外部服务或非主业务实体说明。
- 红色点线 表示历史兼容链路，只是过渡保留，不是推荐设计。
2.2 连线语义
- 蓝色实线 表示主访问链路，也就是 APP 面向主后台的标准访问方式。
- 橙色虚线 表示 F6 相关的例外链路，包括嵌入式 WebView、换票和供应商访问路径。
- 灰色虚线 表示聚合访问、外部服务访问或跨域读取。
- 红色点线 表示历史兼容直连，不建议在新功能中继续复制。
这组语义在 3 页中都保持一致。第三页底部的 Route Semantics 也用线段样例再次标注这些规则，避免读图时只靠颜色文字理解链路含义。因此这套图并不是 3 张孤立页面，而是一套统一的架构表达。
3. 第一页：System Overview 详细说明
System Overview 是能力归属图。它的重点不是展示某个接口先调谁、后调谁，而是回答一个更基础的问题：
“整套系统里，不同能力到底归哪个域负责？”
这一页把系统划分成 4 个主域和 1 个底部治理带：
Mobile AppApp BackendMini Program Backend DomainF6 Supplier DomainExternal Services + Governance Rules
3.1 Mobile App：统一移动入口
左侧第一列是 Mobile App，代表用户真正使用的移动端容器。
这部分说明的是，APP 在架构中的职责主要是“承载、呈现、调用原生能力、维持当前会话”，而不是直接承担复杂跨系统编排。
它包含几个关键块：
Login / Agreement / App Shell表示 APP 是唯一统一入口，用户从这里进入整个系统。WebView + JSBridge表示 APP 具备嵌入式 WebView 承载能力，但这里特别强调“只用于 F6 portal pages”，不是泛化的任意外部浏览器。Native Capabilities表示扫码、相机、上传、蓝牙、通知等设备能力由 APP 容器掌控。Store-Aware Session Holder表示 APP 本地会持有当前门店和角色上下文，但上下文本身的权威归属仍然在主后台。
换句话说，APP 主要负责：
- 提供统一入口。
- 承担页面容器。
- 调度设备能力。
- 保存当前会话状态。
但 APP 不负责：
- 多系统聚合编排。
- 供应商 API 直接调用。
- 业务权限主判断。
- 门店上下文主定义。
3.2 App Backend：主业务域和控制中心
中间第二列是 App Backend，这是整页最核心的部分。
这一列强调的是：APP 主后台不只是一个普通 API 服务，而是整个移动平台的控制面和编排中心。
它包含以下能力：
Auth and Token Center负责登录、令牌签发、刷新、退出和身份可信控制。Store Context + Menu + Permission + Config负责当前门店、角色范围、菜单权限和配置下发。Workbench Aggregation负责首页工作台、提醒、摘要和多个系统结果的统一返回。Business Orchestration负责订单、采购、流程上下文和字段标准化。WebView Ticket and Signing Entry负责 F6 WebView 场景的换票、上下文准备和 trace handoff。
这一列的含义非常明确：
- APP 所有主流程都应先到这里。
- 这里决定用户是谁、当前在哪个门店、可以看什么菜单、有什么权限。
- 这里负责把复杂的后端异构系统整合成移动端可用结果。
- 这里也是所有供应商接入和链路治理的统一出口。
如果没有这一层，移动端就会变成一个多后台直连客户端，导致：
- 门店和角色上下文不统一。
- 权限边界难以收口。
- 多系统异常无法统一处理。
- 供应商接入逻辑扩散到多个模块。
3.3 Mini Program Backend Domain：保留独立边界的历史系统域
第三列是 Mini Program Backend Domain。
这部分要表达的不是“历史系统不重要”，而是：
“这些系统仍然重要，但它们不是 APP 的统一主后台。”
图中列出了典型保留系统：
O2OWarrantyRetail StoreROOS
其中 Retail Store 对应“马上下单”体系中的门店注册、门店信息修改、店员管理等门店基础资料能力，不再使用容易被误解为交易订单的旧英文表述。
并通过说明卡强调：
- 它们仍然拥有历史业务数据和流程。
- 它们仍然可以是某些能力的
Source of Truth。 - 但面向 APP 的访问，原则上应通过
App Backend聚合和标准化后暴露。
这部分架构表达非常重要，因为它避免了两个极端：
- 一个极端是误以为历史系统可以被立刻彻底替换。
- 另一个极端是继续把移动端做成多个小程序后台的直连入口。
正确做法是：
- 保留历史系统边界。
- 承认它们的业务归属。
- 但将移动端访问统一收束到主后台。
3.4 F6 Supplier Domain：供应商能力域
第四列是 F6 Supplier Domain。
这部分专门用来说明 F6 的定位：
- 它是供应商域。
- 它提供能力，但不是 APP 的主系统。
- 它既包含页面能力，也包含接口能力。
图中分成两类：
F6 WebView PagesF6 Capability APIs
并给出代表性示例：
- WebView 例子：
Sales, scan, settlement, inbound - API 例子：
Procurement, activity, inventory sync
这里的核心意思是：
- 页面可以在受控情况下嵌入到 APP WebView 中。
- API 不允许 APP 前端直接调用。
- 所有 API 级访问应通过
App Backend内部适配层完成。
3.5 底部：External Services 和 Governance Rules
最底部是一条横向带，补充说明两件事：
- 系统还会依赖外部服务。
- 整套系统必须遵守统一治理规则。
外部服务示例包括：
SMSMarketing / CRMWeCom
治理规则则明确写出 4 条核心边界：
App -> App Backend is primaryApp -> F6 only in Embedded WebViewF6 APIs go through AdapterMini direct access is legacy-only
这 4 条规则可以理解为第一页的结论。整张图不只是介绍组件，而是在告诉所有参与方：
“系统边界和默认访问方式已经定了，新需求不要再随意绕开它。”
4. 第二页：System Architecture 详细说明
System Architecture 是分层架构图。它建立在第一页能力归属基础上，进一步解释系统按层组织后的技术结构。
如果第一页回答的是“谁负责什么”，那么第二页回答的是：
“这些能力在逻辑架构上如何分层组织，链路如何穿过这些层？”
这一页分成以下层次：
Client TierAccess & SecurityApp BackendIntegration LayerMini Program BackendF6 Supplier DomainExternal ServicesCross-Cutting
4.1 Client Tier：客户端层
最上层是 Client Tier。
这里包含：
Store User PersonaMobile AppNative CapabilitiesWebView + JSBridge
这层说明的是：
- 用户并不是直接面对多个后端系统，而是面对一个统一 APP。
- 原生能力和 WebView 容器都属于客户端能力域。
- 客户端负责发起请求、展示页面、承载设备能力和 WebView 容器。
这里再次强调：WebView + JSBridge 是一种容器能力，不等于前端可以直接把供应商接口当成主链路使用。
4.2 Access & Security：接入与安全层
第二层是 Access & Security。
它包含：
API GatewayJWT / AuthWebView Allowlist
这层表达的是系统接入不能裸奔，所有访问必须经过入口控制和安全校验。
API Gateway
API Gateway 代表统一 API 接入入口，负责：
- HTTPS / TLS 接入。
- 路由分发。
- 基础限流和治理。
- 将移动端和后端实现细节隔离。
JWT / Auth
JWT / Auth 代表统一身份凭证体系，负责：
- 令牌签发。
- 令牌刷新。
- 请求身份识别。
- 为后续权限和上下文建立可信基础。
WebView Allowlist
WebView Allowlist 是这一层里很关键的一个治理点。
它表达的是：
- 并不是任何外部 WebView 页面都可以被 APP 打开。
- 嵌入式 WebView 域名必须是受控、登记和允许的。
- 这既是安全规则，也是架构边界规则。
4.3 App Backend：主后台层
第三层是 App Backend，也是架构主域。
这里包含：
Identity & Store CenterBFF OrchestrationWorkbench AggregationWebView Ticket Center
Identity & Store Center
这个模块负责：
- 用户身份。
- 门店主数据。
- 角色范围。
- 菜单权限。
它的意义是让系统具备统一上下文中心，否则每个后端域都按自己的方式解释用户和门店，会导致移动端体验严重割裂。
BFF Orchestration
这是面向移动端的统一 BFF 编排层，负责：
- 统一接口形态。
- 聚合和标准化多个后端返回。
- 减少前端直接理解多个后端协议的复杂度。
在架构里它是非常重要的一层，因为 APP 实际看到的“后端世界”，应该优先由它统一封装，而不是暴露历史系统差异。
Workbench Aggregation
这个模块更聚焦首页和工作台聚合能力，典型包括：
- 待办。
- 提醒。
- 门店经营摘要。
- 多来源业务 tile 数据。
它说明首页不是由单一系统直接返回，而是由主后台整合多个来源后下发。
WebView Ticket Center
这个模块专门解决 F6 WebView 场景下的入口控制问题，负责：
- 生成或换取 WebView 票据。
- 绑定当前用户和门店上下文。
- 传递 trace 信息。
- 为嵌入式 WebView 提供受控启动入口。
这意味着 APP 打开 F6 WebView 时，并不是裸跳 URL，而是先由主后台准备好上下文和票据条件。
4.4 Integration Layer：集成适配层
第四层是 Integration Layer。
这一层存在的意义，是把供应商接入复杂性控制在一个专门层里，而不是扩散进整个业务系统。
包含两个关键组件：
F6 Integration AdapterTimeout / Retry
F6 Integration Adapter
它负责：
- 换票。
- 供应商访问上下文准备。
- 将主后台调用收口到统一适配出口。
本质上它是主后台访问 F6 的统一适配出口。
Timeout / Retry
这部分表达的是供应商链路治理能力，包括：
- 超时控制。
- 重试策略。
因为 F6 是外部能力域，不稳定性和响应波动风险都比内部模块更高，所以这里保留最关键的超时和重试治理。
4.5 Mini Program Backend：历史后台层
第五层是 Mini Program Backend。
这一层包含：
O2O BackendWarranty BackendRetail Store BackendROOS Backend
其中 Retail Store Backend 对应原“马上下单”相关的门店、人员、地址和资料维护能力，命名上按业务域表达为门店基础资料后台。
这层的架构含义不是“这些服务很次要”，而是：
- 它们继续承担原有业务责任。
- 它们可以是数据主来源。
- 但移动端调用它们时，优先通过主后台聚合。
这页里灰色虚线从 BFF Orchestration 向下扇出，就是在表达：
- 主后台聚合多个 Mini 域。
- 主后台对外统一返回。
- APP 不应把它们当多个主后台直接使用。
4.6 F6 Supplier Domain：供应商能力层
右侧是 F6 Supplier Domain。
这里分成两个主要能力：
F6 WebView PagesF6 Capability APIs
它们分别对应两种不同访问模式：
F6 WebView Pages
用于页面嵌入场景，例如：
- 销售开单。
- 扫码。
- 结算。
- 入库。
访问特点是：
- 页面最终可能由移动端 WebView 直接打开。
- 但打开前需要经过主后台准备票据和上下文。
- 域名必须在 Allowlist 中。
F6 Capability APIs
用于系统间能力调用，例如：
- 采购。
- 促销。
- ERP 补充能力。
访问特点是：
- 前端不能直接调用。
- 只能从
App Backend -> Integration Adapter -> F6 APIs发起。
4.7 External Services：外部服务层
底部右侧是 External Services，包括：
SMSMarketing / CRMWeCom
这说明 APP 主后台除了对接历史内部域和供应商域外，也会调用一些外部平台服务。
这些服务通常承担：
- 短信验证码。
- 营销或客户关系数据。
- 企业协同消息。
它们本质上也是外部依赖，因此在架构里被单独表达，而不是混在主后台内部。
4.8 Cross-Cutting：横切关注点
右上方还有一组 Cross-Cutting 模块：
ObservabilityAudit / SecurityConfig Center
这些不是某个独立业务流程，而是所有流程都必须共享的治理能力。
Observability
负责：
- Trace ID
- 日志
- 指标
确保跨域链路可追踪。
Audit / Security
负责：
- 敏感信息控制。
- 关键行为留痕。
- 审计证据保留。
Config Center
负责：
- 菜单配置。
- 开关配置。
- WebView 入口策略。
这部分说明 APP 平台不是硬编码系统，而是需要较强配置化能力支撑运营和演进。
4.9 第二页想强调的核心结论
第二页最终想让读图人形成以下认知：
- 客户端只有一个统一入口。
- 安全和接入必须前置。
- 主后台必须承担统一 BFF 和统一上下文职责。
- 供应商接入必须通过适配层治理。
- 历史 Mini 域继续存在，但面向 APP 的输出需要经由主后台整合。
- 所有跨域链路都要可观测、可审计、可配置、可降级。
5. 第三页：Key Flows and Context Governance 详细说明
第三页是运行时流程图。它不是在重新画系统结构，而是在解释：
“当业务真实运行起来时，这套架构的关键行为是怎么发生的？”
这一页选了 4 条最关键的流程：
Flow 1 Login and Store Context BootstrapFlow 2 F6 WebView Launch and Session RulesFlow 3 Home Aggregation and Mini CompatibilityFlow 4 Hybrid Procurement and Inbound Flow
同时底部补充统一治理规则。
5.1 Flow 1：Login and Store Context Bootstrap
这条流程解释登录后的上下文建立过程。
流程步骤是：
App LoginToken IssueStore List + Default StoreMenu / Permission / Config BaselineContext Established
这个流程在架构上的真正含义不是“登录成功返回 token”这么简单，而是：
- 用户身份只是第一步。
- 系统真正可运行还需要建立当前门店上下文。
- 菜单、权限和配置要跟门店和角色一起确定。
- APP 登录后不是只有一个用户态，而是一个“用户 + 门店 + 角色 + 菜单 + 配置”的完整工作上下文。
所以这条流程强调的是：
Store Context是核心控制对象。- 登录完成不代表业务上下文完成。
- APP 中很多行为都依赖这一步建立出的当前门店语义。
5.2 Flow 2：F6 WebView Launch and Session Rules
这条流程解释 F6 WebView 嵌入为什么是“例外链路但仍然受控”。
流程步骤是：
App asks for WebView entryBackend exchanges / prepares ticketEmbedded open in WebView
并补充 3 条强规则：
Store switch invalidates WebViewExpired ticket needs refreshFailure fallback shows safe message + trace ID
这条流程表达的重点有 4 个：
第一，WebView 入口必须由主后台签发
APP 不是拿到一个 URL 就直接打开，而是要先通过主后台获取受控入口。
第二，WebView 会话受当前门店上下文约束
如果用户切换门店，当前 WebView 会话不能继续沿用旧上下文，否则会造成门店数据串用和权限风险。
第三，票据是时效性的
过期票据需要刷新，而不是无限复用。
第四，失败时必须可支持排障
如果 F6 打不开，不能只给用户一个空白页或技术错误，而是要给出安全提示并带 trace 信息，方便客服、研发和集成排查。
5.3 Flow 3：Home Aggregation and Mini Compatibility
这条流程解释首页工作台为什么一定是聚合页，而不是某个单体后端直接吐数据。
流程步骤是：
Workbench requestBackend aggregates O2O / Warranty / ROOS / ConfigPartial failure returns degradable tilesLegacy Mini direct access is compatibility only
这条流程的重点非常明确：
第一，首页是聚合结果
首页的数据来源天然分散，不可能全部只来自一个系统。
第二，主后台要负责标准化
不同 Mini 域返回结构、状态和错误处理方式可能不同，需要统一加工后再交给 APP。
第三，降级方式必须是“局部降级”
如果其中一个来源失败，不应该让整个首页白屏，而应该：
- 哪个 tile 有问题就降级哪个 tile。
- 其他可用部分继续返回。
第四，历史直连不是默认解法
即使某些 Mini 场景短期仍保留兼容直连，也应明确标记为历史兼容路径，而不是继续作为新功能访问方式。
5.4 Flow 4：Hybrid Procurement and Inbound Flow
这条流程解释采购和入库为什么是“混合模式”。
流程步骤是：
Retail store context + permission + normalizationF6 owns procurement / promotion / ERPInbound execution uses WebView or API pathHistorical data may still come from Mini aggregation
这条流程在业务上很关键，因为它说明采购和入库类能力并不是纯内部能力，也不是纯供应商能力，而是一个混合场景。
它的架构含义是：
- 主后台负责上下文、权限和统一口径。
- F6 负责其擅长和实际拥有的供应商能力。
- 页面型操作可能通过 WebView 完成。
- 接口型能力通过适配层访问。
- 部分历史辅助数据可能仍来自 Mini 域聚合。
这也解释了为什么：
- 不能把 F6 当主后台。
- 也不能假装采购和入库完全脱离 F6。
- 更不能让前端自己到处直连多个系统完成业务。
正确解法是由主后台掌控主流程，由供应商承接其能力边界内的部分。
6. 底部治理规则和线段语义在告诉我们什么
第三页底部的 Shared Governance Rules、Route Semantics 和 Review checks 不是补充装饰，而是整套架构落地的检查清单和读图规则。
6.1 Shared Governance Rules
这里明确了 4 条总规则：
Store context is owned by App BackendF6 WebView is an embedded exceptionMini systems remain independentEvery degraded or supplier-facing failure returns a user-safe message and a trace ID
它们分别约束：
- 上下文归属。
- 例外链路边界。
- 历史系统独立性。
- 失败处理方式。
6.2 Route Semantics
这里用线段样例说明第三页所有关键链路的读法：
Primary App route对应蓝色实线，表示 APP 到主后台的标准主链路。F6 embedded / exception对应橙色虚线，表示 F6 WebView 嵌入、票据换取或供应商例外链路。Aggregation / external对应灰色虚线，表示主后台向 Mini 域、外部服务或聚合来源发起的访问。Legacy compatibility对应红色点线，表示历史兼容路径，只能作为过渡保留，不能作为新功能默认链路。
这部分和第二页的图例保持一致，目的是让评审人员在看流程图时能直接区分“主链路、例外链路、聚合链路、历史链路”，避免把 F6 WebView 或 Mini 直连误解成默认访问方式。
6.3 Review Checks
这里的检查项可以直接作为评审问题来问：
- 门店切换是否会关闭当前供应商 WebView 会话。
- 首页失败是否按 tile 降级而不是整页失败。
- 采购和入库是否保持 F6-first 的供应商能力归属。
- Mini 直连是否被严格控制为过渡链路。
如果某个新需求或技术方案违反了这里的检查项，通常意味着它已经偏离当前架构原则。
7. 为什么必须这样设计
这套架构不是为了“画得好看”，而是为了解决当前业务现实中的几个核心问题。
7.1 解决多入口和多后台混乱
历史上不同能力分散在多个小程序和后台里，APP 如果继续直接对接多个后端，移动端复杂度会越来越高。
统一 App Backend 作为主后台后，可以：
- 收敛前端访问入口。
- 统一账号和门店上下文。
- 统一权限和配置。
7.2 保留历史资产而不是强行推倒重来
Mini Program Backend 仍然保留业务边界，避免为了“统一”而做不现实的大拆大建。
这使系统具备：
- 现实可落地性。
- 渐进式演进能力。
- 更低迁移风险。
7.3 把 F6 当成供应商能力，而不是主系统
这是整个架构中最重要的认知之一。
因为 F6：
- 不是自有主后台。
- 协议和稳定性不完全可控。
- 同时提供页面和接口两类能力。
所以必须：
- 页面入口受控。
- API 接口后端统一适配。
- 供应商异常和主系统隔离。
7.4 支持真实业务运行中的上下文治理
系统不是“登录就结束”，而是多门店、多角色、多链路环境下持续运行。
因此必须把以下能力做成架构级规则：
- 当前门店上下文。
- WebView 会话绑定和失效控制。
- 跨域链路可追踪。
- 失败时可降级、可审计、可支持排障。
8. 读完这 3 页后应该形成的统一认知
如果要用一句话总结这 3 页图，它表达的是：
“Continental Retail APP 是一个以 App Backend 为统一主后台、以 Mobile App 为统一入口、以 Mini Program Backend 为保留独立历史域、以 F6 为受控供应商能力域的混合架构系统。”
更具体地说，所有参与方应形成以下共识：
- APP 不是多个后台的并列客户端，而是统一入口。
App Backend不是普通接口层，而是控制面和编排中心。- Mini 后台继续存在，但面向 APP 时应优先通过主后台聚合。
- F6 是供应商域，页面和接口都要按受控方式接入。
- 门店上下文是系统运行的核心治理对象。
- 首页聚合必须支持局部降级。
- WebView 是例外链路，不是默认业务通路。
- 所有跨域链路都必须可治理、可观测、可审计。
9. 这份说明适合怎么使用
这份文档适合以下用途：
- 架构评审时作为讲解稿。
- 产品、研发、测试 onboarding 时作为系统认知材料。
- 需求讨论时用于确认是否违反既定架构原则。
- 接口联调前用于统一系统边界和责任分工。
如果后续需要，我还可以继续补两类配套文档：
- 一份“面向评审汇报”的精简版讲稿。
- 一份“按模块拆解”的实现说明，把图里的每个块映射到实际研发任务和接口边界。