# 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 App`
- `App Backend`
- `Mini Program Backend Domain`
- `F6 Supplier Domain`
- `External 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 的统一主后台。”

图中列出了典型保留系统：

- `O2O`
- `Warranty`
- `Retail Store`
- `ROOS`

其中 `Retail Store` 对应“马上下单”体系中的门店注册、门店信息修改、店员管理等门店基础资料能力，不再使用容易被误解为交易订单的旧英文表述。

并通过说明卡强调：

- 它们仍然拥有历史业务数据和流程。
- 它们仍然可以是某些能力的 `Source of Truth`。
- 但面向 APP 的访问，原则上应通过 `App Backend` 聚合和标准化后暴露。

这部分架构表达非常重要，因为它避免了两个极端：

- 一个极端是误以为历史系统可以被立刻彻底替换。
- 另一个极端是继续把移动端做成多个小程序后台的直连入口。

正确做法是：

- 保留历史系统边界。
- 承认它们的业务归属。
- 但将移动端访问统一收束到主后台。

### 3.4 F6 Supplier Domain：供应商能力域

第四列是 `F6 Supplier Domain`。

这部分专门用来说明 F6 的定位：

- 它是供应商域。
- 它提供能力，但不是 APP 的主系统。
- 它既包含页面能力，也包含接口能力。

图中分成两类：

- `F6 WebView Pages`
- `F6 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

最底部是一条横向带，补充说明两件事：

- 系统还会依赖外部服务。
- 整套系统必须遵守统一治理规则。

外部服务示例包括：

- `SMS`
- `Marketing / CRM`
- `WeCom`

治理规则则明确写出 4 条核心边界：

- `App -> App Backend is primary`
- `App -> F6 only in Embedded WebView`
- `F6 APIs go through Adapter`
- `Mini direct access is legacy-only`

这 4 条规则可以理解为第一页的结论。整张图不只是介绍组件，而是在告诉所有参与方：

“系统边界和默认访问方式已经定了，新需求不要再随意绕开它。”

---

## 4. 第二页：System Architecture 详细说明

`System Architecture` 是分层架构图。它建立在第一页能力归属基础上，进一步解释系统按层组织后的技术结构。

如果第一页回答的是“谁负责什么”，那么第二页回答的是：

“这些能力在逻辑架构上如何分层组织，链路如何穿过这些层？”

这一页分成以下层次：

- `Client Tier`
- `Access & Security`
- `App Backend`
- `Integration Layer`
- `Mini Program Backend`
- `F6 Supplier Domain`
- `External Services`
- `Cross-Cutting`

### 4.1 Client Tier：客户端层

最上层是 `Client Tier`。

这里包含：

- `Store User Persona`
- `Mobile App`
- `Native Capabilities`
- `WebView + JSBridge`

这层说明的是：

- 用户并不是直接面对多个后端系统，而是面对一个统一 APP。
- 原生能力和 WebView 容器都属于客户端能力域。
- 客户端负责发起请求、展示页面、承载设备能力和 WebView 容器。

这里再次强调：`WebView + JSBridge` 是一种容器能力，不等于前端可以直接把供应商接口当成主链路使用。

### 4.2 Access & Security：接入与安全层

第二层是 `Access & Security`。

它包含：

- `API Gateway`
- `JWT / Auth`
- `WebView 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 Center`
- `BFF Orchestration`
- `Workbench Aggregation`
- `WebView 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 Adapter`
- `Timeout / Retry`

#### F6 Integration Adapter

它负责：

- 换票。
- 供应商访问上下文准备。
- 将主后台调用收口到统一适配出口。

本质上它是主后台访问 F6 的统一适配出口。

#### Timeout / Retry

这部分表达的是供应商链路治理能力，包括：

- 超时控制。
- 重试策略。

因为 F6 是外部能力域，不稳定性和响应波动风险都比内部模块更高，所以这里保留最关键的超时和重试治理。

### 4.5 Mini Program Backend：历史后台层

第五层是 `Mini Program Backend`。

这一层包含：

- `O2O Backend`
- `Warranty Backend`
- `Retail Store Backend`
- `ROOS Backend`

其中 `Retail Store Backend` 对应原“马上下单”相关的门店、人员、地址和资料维护能力，命名上按业务域表达为门店基础资料后台。

这层的架构含义不是“这些服务很次要”，而是：

- 它们继续承担原有业务责任。
- 它们可以是数据主来源。
- 但移动端调用它们时，优先通过主后台聚合。

这页里灰色虚线从 `BFF Orchestration` 向下扇出，就是在表达：

- 主后台聚合多个 Mini 域。
- 主后台对外统一返回。
- APP 不应把它们当多个主后台直接使用。

### 4.6 F6 Supplier Domain：供应商能力层

右侧是 `F6 Supplier Domain`。

这里分成两个主要能力：

- `F6 WebView Pages`
- `F6 Capability APIs`

它们分别对应两种不同访问模式：

#### F6 WebView Pages

用于页面嵌入场景，例如：

- 销售开单。
- 扫码。
- 结算。
- 入库。

访问特点是：

- 页面最终可能由移动端 WebView 直接打开。
- 但打开前需要经过主后台准备票据和上下文。
- 域名必须在 Allowlist 中。

#### F6 Capability APIs

用于系统间能力调用，例如：

- 采购。
- 促销。
- ERP 补充能力。

访问特点是：

- 前端不能直接调用。
- 只能从 `App Backend -> Integration Adapter -> F6 APIs` 发起。

### 4.7 External Services：外部服务层

底部右侧是 `External Services`，包括：

- `SMS`
- `Marketing / CRM`
- `WeCom`

这说明 APP 主后台除了对接历史内部域和供应商域外，也会调用一些外部平台服务。

这些服务通常承担：

- 短信验证码。
- 营销或客户关系数据。
- 企业协同消息。

它们本质上也是外部依赖，因此在架构里被单独表达，而不是混在主后台内部。

### 4.8 Cross-Cutting：横切关注点

右上方还有一组 `Cross-Cutting` 模块：

- `Observability`
- `Audit / Security`
- `Config 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 Bootstrap`
- `Flow 2 F6 WebView Launch and Session Rules`
- `Flow 3 Home Aggregation and Mini Compatibility`
- `Flow 4 Hybrid Procurement and Inbound Flow`

同时底部补充统一治理规则。

### 5.1 Flow 1：Login and Store Context Bootstrap

这条流程解释登录后的上下文建立过程。

流程步骤是：

1. `App Login`
2. `Token Issue`
3. `Store List + Default Store`
4. `Menu / Permission / Config Baseline`
5. `Context Established`

这个流程在架构上的真正含义不是“登录成功返回 token”这么简单，而是：

- 用户身份只是第一步。
- 系统真正可运行还需要建立当前门店上下文。
- 菜单、权限和配置要跟门店和角色一起确定。
- APP 登录后不是只有一个用户态，而是一个“用户 + 门店 + 角色 + 菜单 + 配置”的完整工作上下文。

所以这条流程强调的是：

- `Store Context` 是核心控制对象。
- 登录完成不代表业务上下文完成。
- APP 中很多行为都依赖这一步建立出的当前门店语义。

### 5.2 Flow 2：F6 WebView Launch and Session Rules

这条流程解释 F6 WebView 嵌入为什么是“例外链路但仍然受控”。

流程步骤是：

1. `App asks for WebView entry`
2. `Backend exchanges / prepares ticket`
3. `Embedded open in WebView`

并补充 3 条强规则：

- `Store switch invalidates WebView`
- `Expired ticket needs refresh`
- `Failure fallback shows safe message + trace ID`

这条流程表达的重点有 4 个：

#### 第一，WebView 入口必须由主后台签发

APP 不是拿到一个 URL 就直接打开，而是要先通过主后台获取受控入口。

#### 第二，WebView 会话受当前门店上下文约束

如果用户切换门店，当前 WebView 会话不能继续沿用旧上下文，否则会造成门店数据串用和权限风险。

#### 第三，票据是时效性的

过期票据需要刷新，而不是无限复用。

#### 第四，失败时必须可支持排障

如果 F6 打不开，不能只给用户一个空白页或技术错误，而是要给出安全提示并带 trace 信息，方便客服、研发和集成排查。

### 5.3 Flow 3：Home Aggregation and Mini Compatibility

这条流程解释首页工作台为什么一定是聚合页，而不是某个单体后端直接吐数据。

流程步骤是：

1. `Workbench request`
2. `Backend aggregates O2O / Warranty / ROOS / Config`
3. `Partial failure returns degradable tiles`
4. `Legacy Mini direct access is compatibility only`

这条流程的重点非常明确：

#### 第一，首页是聚合结果

首页的数据来源天然分散，不可能全部只来自一个系统。

#### 第二，主后台要负责标准化

不同 Mini 域返回结构、状态和错误处理方式可能不同，需要统一加工后再交给 APP。

#### 第三，降级方式必须是“局部降级”

如果其中一个来源失败，不应该让整个首页白屏，而应该：

- 哪个 tile 有问题就降级哪个 tile。
- 其他可用部分继续返回。

#### 第四，历史直连不是默认解法

即使某些 Mini 场景短期仍保留兼容直连，也应明确标记为历史兼容路径，而不是继续作为新功能访问方式。

### 5.4 Flow 4：Hybrid Procurement and Inbound Flow

这条流程解释采购和入库为什么是“混合模式”。

流程步骤是：

1. `Retail store context + permission + normalization`
2. `F6 owns procurement / promotion / ERP`
3. `Inbound execution uses WebView or API path`
4. `Historical 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 Backend`
- `F6 WebView is an embedded exception`
- `Mini systems remain independent`
- `Every 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

这里的检查项可以直接作为评审问题来问：

1. 门店切换是否会关闭当前供应商 WebView 会话。
2. 首页失败是否按 tile 降级而不是整页失败。
3. 采购和入库是否保持 F6-first 的供应商能力归属。
4. 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 时作为系统认知材料。
- 需求讨论时用于确认是否违反既定架构原则。
- 接口联调前用于统一系统边界和责任分工。

如果后续需要，我还可以继续补两类配套文档：

- 一份“面向评审汇报”的精简版讲稿。
- 一份“按模块拆解”的实现说明，把图里的每个块映射到实际研发任务和接口边界。