conti-docs/README.md

# conti-docs

Continental Retail APP 相关的文档参考仓库，用于沉淀架构决策、系统/网络架构图，以及后续会陆续补充的后端设计和 API 文档。

## 目录说明

### App 架构决策文档

Flutter APP 的分包、分层、技术选型等决策记录，按序号阅读：

| 文档 | 内容 |
| --- | --- |
| [01-project-structure.md](./01-project-structure.md) | 工程结构 / 分包策略（Melos monorepo） |
| [02-layering.md](./02-layering.md) | 分层架构规范（presentation/domain/data） |
| [03-state-management.md](./03-state-management.md) | 状态管理方案（Riverpod） |
| [04-routing.md](./04-routing.md) | 路由方案（go_router） |
| [05-networking.md](./05-networking.md) | 网络层设计（dio） |
| [06-local-storage.md](./06-local-storage.md) | 本地存储方案（Drift / secure storage / shared_preferences） |
| [07-native-integration.md](./07-native-integration.md) | 原生能力集成方式（Pigeon） |
| [08-build-flavors.md](./08-build-flavors.md) | 多环境构建（dev/uat/prod flavor） |
| [09-testing.md](./09-testing.md) | 测试策略（单元/Widget/集成测试） |
| [10-webview-h5.md](./10-webview-h5.md) | Embedded H5 容器与 JSBridge（PRD §7 核心链路） |
| [11-store-context-and-session.md](./11-store-context-and-session.md) | 门店上下文与会话管理（切店级联失效、登出清理） |
| [12-error-and-api-contract.md](./12-error-and-api-contract.md) | 错误处理与 API 契约（`ApiResult`、异常体系、降级） |
| [13-observability-analytics.md](./13-observability-analytics.md) | 可观测性与埋点（Sentry 崩溃上报、神策客户端埋点、日志脱敏） |
| [14-conventions-and-ci-gates.md](./14-conventions-and-ci-gates.md) | 工程规范与 CI 门禁（lint、格式化、分支、流水线卡点） |

首版范围为 **Android / iOS**，鸿蒙 OHOS 不在首版内（但 SDK 基线锁 3.44.9 是为后续 OHOS 适配留窗口，见 01 和 07）。

### Architecture-Diagram/

前期系统架构、网络架构梳理阶段产出的图和说明文档，先保留作为历史参考，后续可能会做精简：

- `architecture-diagram.drawio` / `architecture-diagram-explanation.md` — 系统架构图（System Overview / System Architecture / Key Flows）及说明
- `network-architecture-diagram.drawio` / `network-architecture-explanation.md` — 多云网络架构图（业务域边界、VNet/VPC 拓扑）及说明
- `app-architecture-diagram.drawio` — APP 侧架构图
- `deployment-architecture-diagram.drawio` / `system-architecture-diagram.drawio` — 部署架构图 / 系统架构图
- `gitlab-cicd-azure-deployment-diagram.drawio` — GitLab CI/CD 到 Azure 的部署流程图
- `202606-Continental-Retail-APP-PRD.md` — 产品需求文档（PRD）
- `202606-Conti-Retail-APP-Component-data-source.md` — 功能模块与数据来源整理
- `零售商系统方案研讨会PPT.retro.md` — 方案研讨会复盘记录
- `extract_requirements_to_md.py` / `extract_component_data_to_md.py` — 从原始材料提取内容生成上述 md 文档的脚本

`.drawio` 文件可用 [draw.io 桌面版](https://github.com/jgraph/drawio-desktop) 或 VS Code 的 Draw.io Integration 插件打开查看。

### backend/

后端（Kotlin 2.4 + Spring Boot 4.1 + Java 21 + Gradle 多模块）架构决策文档，按序号阅读：

| 文档 | 内容 |
| --- | --- |
| [backend/01-project-structure.md](./backend/01-project-structure.md) | 工程结构 / 模块划分（模块化单体，`-contract` 契约模块，版本基线） |
| [backend/02-layering.md](./backend/02-layering.md) | 分层规范（api/application/domain/infrastructure，Entity 边界） |
| [backend/03-persistence.md](./backend/03-persistence.md) | 持久层方案（Spring Data JPA + Hibernate + MySQL，Flyway 多实例） |
| [backend/04-security-auth.md](./backend/04-security-auth.md) | 安全与认证（Spring Security + JWT，refresh 轮换，门店上下文与越权隔离） |
| [backend/05-integration-layer.md](./backend/05-integration-layer.md) | 集成层设计（同步 RestClient + Resilience4j，F6 Adapter / Mini 客户端） |
| [backend/06-api-design.md](./backend/06-api-design.md) | API 设计规范（统一响应、错误码、请求头、分页与序列化约定） |
| [backend/07-config-governance.md](./backend/07-config-governance.md) | 配置与服务治理（K8s ConfigMap/Secret、Key Vault、启动期校验） |
| [backend/08-observability.md](./backend/08-observability.md) | 可观测性（Micrometer Tracing、结构化日志与脱敏、指标与告警、审计） |
| [backend/09-build-deploy.md](./backend/09-build-deploy.md) | 构建与多环境部署（Docker、GitLab CI/CD、优雅停机、迁移与回滚协同） |
| [backend/10-testing.md](./backend/10-testing.md) | 测试策略（Testcontainers、WireMock、ArchUnit、覆盖率聚合） |
| [backend/11-cross-domain-collaboration.md](./backend/11-cross-domain-collaboration.md) | 跨域协作与聚合（契约模块、领域事件、并行 fan-out 与局部降级） |
| [backend/12-concurrency-and-scheduling.md](./backend/12-concurrency-and-scheduling.md) | 并发、事务与定时任务（事务边界、幂等、乐观锁、ShedLock、本地缓存） |

## 已知文档间差异（PRD 待修订）

以下几处 PRD / 前期材料与 App 架构文档的结论不一致。**以架构文档为准**，PRD 侧需要回头修订：

| # | 差异 | 现状 | 实际结论 |
| --- | --- | --- | --- |
| 1 | 技术路线 | PRD 表头写「主技术路线 React Native / 备选 Flutter」 | 实际选型是 **Flutter**，01-14 全部基于 Flutter |
| 2 | 扫码归属 | PRD §11.5 与 `Architecture-Diagram/202606-Conti-Retail-APP-Component-data-source.md` 写成「嵌入 F6 扫码页」 | 扫码是 **App 原生实现**（`native_scan`），同时服务 `feature_scan` 和 H5 的 JSBridge，见 [07](./07-native-integration.md) 和 [10](./10-webview-h5.md) |
| 3 | JSBridge 能力数 | 计划稿一度记为 13 项 | PRD §7.4 实际列出 **12 项**，见 [10](./10-webview-h5.md) |

## 待补充

- API 文档
- `15-ui-design-system.md` — `core_ui` 的 Material 3 主题、设计 token、暗色模式（对应 PRD §8.2 统一交互规则）
- `16-i18n.md` — 首版单语言，但需预留 `flutter_localizations` + `intl` 结构（后补代价高）

## 跨文档的阻塞项

这几条不解决会直接卡住工程落地，集中列在这里：

| 阻塞项 | 出处 | 影响 |
| --- | --- | --- |
| **iOS 构建链路不成立** | [08](./08-build-flavors.md) | 现有 GitLab Runner 是与后端共用的 Linux runner，`flutter build ipa` 需要 macOS。需决策自建 mac runner / 云端 mac runner / iOS 手工出包 |
| **后端错误码表未定** | [12](./12-error-and-api-contract.md)、[backend/06](./backend/06-api-design.md) | 客户端无法对错误码做分支处理，只能全部走默认文案 |
| **Sentry 自建还是 SaaS 未定** | [13](./13-observability-analytics.md) | 崩溃平台已定为 Sentry（Bugly 无法还原 Dart 混淆堆栈，而我们的异常绝大多数是 Dart 异常）。但 `sentry.io` SaaS 属于数据出境且门店网络可达性存疑，自建则需要内网资源和运维承接方——需明确 |
| **神策服务是否可用未确认** | [13](./13-observability-analytics.md) | 客户端埋点定为神策（团队有经验、官方插件在维护），但本项目**没有现成账号**。公司若未在用，开通是采购流程而非配置项。**不阻塞开工**——事件方案和 `core_analytics` 接口先做，两者与 SDK 无关；实在走不通再换自建 endpoint |
| **内测分发渠道未定** | [08](./08-build-flavors.md) | Firebase App Distribution 国内可达性存疑，需选替代方案 |
| **车牌识别技术路径未验证** | [07](./07-native-integration.md) | 通用扫码库只能解条码/二维码，VIN 印刷字符和车牌需要 OCR，车牌可能需要商用 SDK |

### 已解决（2026-08 后端文档评审）

| 原待确认项 | 结论 | 出处 |
| --- | --- | --- |
| 数据库选型未定 | **MySQL 8.4**（UAT/Prod 用 Azure Database for MySQL Flexible Server + Private Endpoint） | [backend/03](./backend/03-persistence.md)、[backend/09](./backend/09-build-deploy.md) |
| `X-Trace-Id` 请求头契约未定 | 客户端传 32 位小写 hex；服务端校验通过则复用，否则忽略并自行生成，最终值在响应头和 `ApiResult.traceId` 里回写 | [backend/08](./backend/08-observability.md)、[05](./05-networking.md) |
| 分页参数约定未定 | `pageNum`（1 起）/ `pageSize`（≤100）/ `sort`（白名单），响应含 `hasMore` | [backend/06](./backend/06-api-design.md) |
| 集成层同步还是响应式 | **同步 `RestClient`**，不引入 WebClient/Mono | [backend/05](./backend/05-integration-layer.md) |

后端错误码表仍未定（见上表阻塞项）：分段规则已在 [backend/06](./backend/06-api-design.md) 定好，缺的是各业务域把自己的码填进去。

## 语言约定

文档以中文为主。