Guangfei.Zhao
74b02ed427
- Introduced a new section on cross-domain collaboration and aggregation, detailing decision-making processes, contract module usage for cross-domain reads, and domain events for writes. - Added guidelines for parallel aggregation using a dedicated thread pool and context propagation. - Established rules for transaction boundaries, idempotency, optimistic locking, scheduled tasks, and caching strategies in a concurrent environment. - Included examples and best practices for implementing these concepts in the application.
conti-docs
Continental Retail APP 相关的文档参考仓库，用于沉淀架构决策、系统/网络架构图，以及后续会陆续补充的后端设计和 API 文档。
目录说明
App 架构决策文档
Flutter APP 的分包、分层、技术选型等决策记录，按序号阅读：
| 文档 | 内容 |
|---|---|
| 01-project-structure.md | 工程结构 / 分包策略（Melos monorepo） |
| 02-layering.md | 分层架构规范（presentation/domain/data） |
| 03-state-management.md | 状态管理方案（Riverpod） |
| 04-routing.md | 路由方案（go_router） |
| 05-networking.md | 网络层设计（dio） |
| 06-local-storage.md | 本地存储方案（Drift / secure storage / shared_preferences） |
| 07-native-integration.md | 原生能力集成方式（Pigeon） |
| 08-build-flavors.md | 多环境构建（dev/uat/prod flavor） |
| 09-testing.md | 测试策略（单元/Widget/集成测试） |
| 10-webview-h5.md | Embedded H5 容器与 JSBridge（PRD §7 核心链路） |
| 11-store-context-and-session.md | 门店上下文与会话管理（切店级联失效、登出清理） |
| 12-error-and-api-contract.md | 错误处理与 API 契约（ApiResult、异常体系、降级） |
| 13-observability-analytics.md | 可观测性与埋点（Sentry 崩溃上报、神策客户端埋点、日志脱敏） |
| 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 桌面版 或 VS Code 的 Draw.io Integration 插件打开查看。
backend/
后端（Kotlin 2.4 + Spring Boot 4.1 + Java 21 + Gradle 多模块）架构决策文档，按序号阅读：
| 文档 | 内容 |
|---|---|
| backend/01-project-structure.md | 工程结构 / 模块划分（模块化单体，-contract 契约模块，版本基线） |
| backend/02-layering.md | 分层规范（api/application/domain/infrastructure，Entity 边界） |
| backend/03-persistence.md | 持久层方案（Spring Data JPA + Hibernate + MySQL，Flyway 多实例） |
| backend/04-security-auth.md | 安全与认证（Spring Security + JWT，refresh 轮换，门店上下文与越权隔离） |
| backend/05-integration-layer.md | 集成层设计（同步 RestClient + Resilience4j，F6 Adapter / Mini 客户端） |
| backend/06-api-design.md | API 设计规范（统一响应、错误码、请求头、分页与序列化约定） |
| backend/07-config-governance.md | 配置与服务治理（K8s ConfigMap/Secret、Key Vault、启动期校验） |
| backend/08-observability.md | 可观测性（Micrometer Tracing、结构化日志与脱敏、指标与告警、审计） |
| backend/09-build-deploy.md | 构建与多环境部署（Docker、GitLab CI/CD、优雅停机、迁移与回滚协同） |
| backend/10-testing.md | 测试策略（Testcontainers、WireMock、ArchUnit、覆盖率聚合） |
| backend/11-cross-domain-collaboration.md | 跨域协作与聚合（契约模块、领域事件、并行 fan-out 与局部降级） |
| 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 和 10 |
| 3 | JSBridge 能力数 | 计划稿一度记为 13 项 | PRD §7.4 实际列出 12 项，见 10 |
待补充
- API 文档
15-ui-design-system.md—core_ui的 Material 3 主题、设计 token、暗色模式（对应 PRD §8.2 统一交互规则）16-i18n.md— 首版单语言，但需预留flutter_localizations+intl结构（后补代价高）
跨文档的阻塞项
这几条不解决会直接卡住工程落地，集中列在这里：
| 阻塞项 | 出处 | 影响 |
|---|---|---|
| iOS 构建链路不成立 | 08 | 现有 GitLab Runner 是与后端共用的 Linux runner，flutter build ipa 需要 macOS。需决策自建 mac runner / 云端 mac runner / iOS 手工出包 |
| 后端错误码表未定 | 12、backend/06 | 客户端无法对错误码做分支处理，只能全部走默认文案 |
| Sentry 自建还是 SaaS 未定 | 13 | 崩溃平台已定为 Sentry（Bugly 无法还原 Dart 混淆堆栈，而我们的异常绝大多数是 Dart 异常）。但 sentry.io SaaS 属于数据出境且门店网络可达性存疑，自建则需要内网资源和运维承接方——需明确 |
| 神策服务是否可用未确认 | 13 | 客户端埋点定为神策（团队有经验、官方插件在维护），但本项目没有现成账号。公司若未在用，开通是采购流程而非配置项。不阻塞开工——事件方案和 core_analytics 接口先做，两者与 SDK 无关；实在走不通再换自建 endpoint |
| 内测分发渠道未定 | 08 | Firebase App Distribution 国内可达性存疑，需选替代方案 |
| 车牌识别技术路径未验证 | 07 | 通用扫码库只能解条码/二维码，VIN 印刷字符和车牌需要 OCR，车牌可能需要商用 SDK |
已解决（2026-08 后端文档评审）
| 原待确认项 | 结论 | 出处 |
|---|---|---|
| 数据库选型未定 | MySQL 8.4（UAT/Prod 用 Azure Database for MySQL Flexible Server + Private Endpoint） | backend/03、backend/09 |
X-Trace-Id 请求头契约未定 |
客户端传 32 位小写 hex；服务端校验通过则复用，否则忽略并自行生成，最终值在响应头和 ApiResult.traceId 里回写 |
backend/08、05 |
| 分页参数约定未定 | pageNum（1 起）/ pageSize（≤100）/ sort（白名单），响应含 hasMore |
backend/06 |
| 集成层同步还是响应式 | 同步 RestClient，不引入 WebClient/Mono |
backend/05 |
后端错误码表仍未定（见上表阻塞项）：分段规则已在 backend/06 定好，缺的是各业务域把自己的码填进去。
语言约定
文档以中文为主。