conti-docs

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

目录说明

flutter-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	可观测性与埋点（Bugly 崩溃上报、神策埋点与错误看板、日志脱敏）
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 插件打开查看。

prd/

当前生效的产品需求文档，整合了原始需求、现状小程序实测截图与 APP 设计稿：

文档	内容
prd/Continental-Retail-APP-PRD.md	Continental Retail APP PRD V1.1 —— 19 个模块、296 条编号需求、173 张图、44 张正文表格。第 4 章的 167 张图每张均配有四段式说明。需求描述与编号需求以文本书写（表格只用于字段清单、矩阵与统计）。自包含文档，不引用本仓库其它 md，可直接转 Word
prd/modules/	PRD 第 4 章的 14 个业务模块拆分件，每模块一个文件：正文 4.x + 逐张配图的四段式说明（页面内容 / 关键交互 / 可用角色 / 需求关联）+ 从 10.2、附录 A/B/C 归拢的本模块分片。第 4 章的编辑入口，需求变更改这里；主文件第 4 章是回灌产物，勿直接编辑。14 个模块已全部建成，167 张图逐张核看后写了说明；逐图核对使第 4 章需求从 121 条增至 222 条、待确认从 74 条增至 121 条，已于 2026-08 回灌主文件（V1.1）

同目录下的 images/（自 origin-prd 抢救的 F6 与后台原型图）、app-design-images/（设计稿）、mini-program-images/{O2O,ROOS,Warranty}/（现状小程序截图）为其图源。

三份 PRD 的关系（避免看错文档）：

文档	性质	是否可作需求依据
prd/Continental-Retail-APP-PRD.md	V1.1，现行版本	✅ 是（第 4 章的编辑入口在 prd/modules/）
origin-prd/Conti Retail APP需求分析文档.md	V0.9，业务侧编制的原始需求，V1.0 的主线来源，保留存档	✅ 是（V1.0 已全量归位）
Architecture-Diagram/202606-Continental-Retail-APP-PRD.md	前期架构梳理阶段的草稿，其需求陈述非真实需求	❌ 否，仅可参考文档写法

V1.0 相对 V0.9 的主要变化：修复第 4 章编号断裂、将「我的」从采购下剥离为一级模块、补齐库存 / 财务对账 / 返利 / 经营业绩 / 营销会员 / 福利兑换六个缺失模块、新增系统集成与架构边界 / 非功能需求 / 验收标准 / 风险清单四章、新增权限矩阵与需求追溯矩阵。

V1.1 相对 V1.0 的主要变化：第 4 章拆分到 prd/modules/ 并逐张核看 167 张配图，为每张图补写四段式说明；据此补录 V1.0 未记的机制与口径冲突，第 4 章需求 121 → 222 条、待确认 74 → 121 条，全文需求 195 → 296 条、待确认 97 → 144 条；修正 FIN / MKT / STM 三处 REQ 编号错位（10.2 各行标注原编号以便追溯）；同步更新头部规模声明、附录 B / C / D.2 与第 10.2 节。

其中 144 条需求仍待业务确认，集中在 PRD 第 10 章；本 README「跨文档的阻塞项」也已并入 PRD 第 10.3 节。

scripts/

脚本	用途
scripts/build_prd.py	PRD 构建脚本，三个子命令：backfill 把 prd/modules/ 的 14 个模块回灌进主文件第 4 章并重算派生数据、verify 跑 7 项一致性校验、export 压缩配图并出 Word
scripts/reference.docx	Word 版式模板，首次 export 时自动生成（东亚字体钉为标题「微软雅黑」/ 正文「等线」）。已存在则原样使用，可用 Word 直接调样式

必须用仓库根目录的 .venv（自带 pandoc 与 Pillow，系统 Python 缺依赖）：

.venv/Scripts/python.exe scripts/build_prd.py verify              # 只校验，不改文件
.venv/Scripts/python.exe scripts/build_prd.py backfill --dry-run  # 预览回灌差异
.venv/Scripts/python.exe scripts/build_prd.py backfill            # 回灌，末尾自动跑 verify
.venv/Scripts/python.exe scripts/build_prd.py export              # 压缩配图 + 出 docx

export 做两件事：把 prd/ 下三个图源目录的 PNG 就地调色板量化（首次跑：23.4 MB → 9.7 MB，已量化的会跳过，日后新加的截图会自动压掉），再用 pandoc 生成 prd/Continental-Retail-APP-PRD.docx（约 9.8 MB，含全部 173 张图与三级目录）。PDF 不由脚本生成——pandoc 转 PDF 要 LaTeX，用 Word 打开 docx 另存。

量化是有损的（256 色）。这批截图是扁平 UI 图，实测中位 RMS 误差 0.82/255、最差 3.10，肉眼看不出差别。原图都在 git 历史里，要取回某张跑 git checkout <commit> -- prd/xxx.png。

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、本地缓存）

tech-selection/

对外的技术选型说明材料，写给客户方，可直接作为会议材料使用：

文档	内容
tech-selection/前端技术路线评估-Flutter-vs-UniApp.md	Flutter / uni-app / uni-app x 三条路线对比，结论推荐 Flutter。六章：① 市面跨端方案清单与四条架构路线 ② 三者定位与架构对比 ③ 结合本项目业务的技术评估 ④ 生态、社区与 AI 工具链 ⑤ 构建发布与可扩展性 ⑥ 结论（含成本口径：首版 ±10% 基本持平，差异在五年周期）。含非技术读者可读的通俗解释与术语表

与 flutter-app/ 的分工：技术结论仍以 flutter-app/01-14 为准，本目录只做对外解释与论证，不产生新的技术决策。文中所有对 uni-app x 的判断都在附录 A 给出了官方文档链接，便于客户自行复核（核验日期 2026-08-25，日后引用前建议重新抽查）。

已知文档间差异（已在 PRD V1.0 修订）

以下几处前期材料与 App 架构文档的结论不一致。以架构文档为准，prd/Continental-Retail-APP-PRD.md 已按架构结论写入并在其第 10 章记录了裁决过程：

#	差异	前期材料	实际结论	V1.0 处置
1	技术路线	Architecture-Diagram/202606-Continental-Retail-APP-PRD.md 表头写「主技术路线 React Native / 备选 Flutter」	实际选型是 Flutter，01-14 全部基于 Flutter	✅ 文档控制表已写 Flutter（PRD C4）；对客户的完整论证见 tech-selection/
2	扫码归属	202606 PRD 第 11.5 节 与 Architecture-Diagram/202606-Conti-Retail-APP-Component-data-source.md 写成「嵌入 F6 扫码页」	扫码是 App 原生实现（native_scan），同时服务 feature_scan 和 H5 的 JSBridge，见 07 和 10	✅ PRD REQ-INT-003 已校正（PRD C5）
3	JSBridge 能力数	计划稿记 13 项、202606 PRD 记 12 项	以 10 为准：表格 13 行，因 toast/dialog/loading 合并为一行，实际 method 名共 15 个	✅ PRD 第 7.3 节的 JSBridge 能力清单已按此重述

待补充

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

跨文档的阻塞项

这几条不解决会直接卡住工程落地，集中列在这里（PRD 第 10.3 节 同步收录了这张表，两处需一并维护）：

阻塞项	出处	影响
神策服务是否可用未确认	13	客户端埋点定为神策，且崩溃明细看板也要建在神策上（见下方已解决表），但本项目没有现成账号。公司若未在用，开通是采购流程而非配置项。不阻塞开工——事件方案和 core_analytics 接口先做，两者与 SDK 无关；实在走不通，埋点和错误明细都要另找落点

已解决（2026-08 技术决策）

原阻塞项	结论	出处
iOS 构建链路不成立	远程一台 Mac 出包。首版手工执行仓库内的 scripts/build_ios.sh；后续把这台 Mac 注册成 GitLab Runner（macos tag）接进流水线。构建命令必须来自仓库脚本，符号表/dSYM 要带回归档	08
后端错误码表未定	分段方案 + 一组基础码现在定死，业务码在开发对应模块时随接口增补，不集中排期。客户端默认展示后端 message，只有需要特殊 UX 的码才进 ApiCode	12、backend/06
Sentry 自建还是 SaaS 未定	不引入 Sentry。崩溃走现有的腾讯 Bugly（原生崩溃/ANR），错误明细与看板走神策自定义事件 app_error + 在神策上二次开发。连带决策：release 不开 --obfuscate（两者都还原不了混淆后的 Dart 堆栈），只保留 --split-debug-info	13、08
内测分发渠道未定	不用 Firebase。Android 走自建/公司托管的 OTA 分发页，iOS 走 TestFlight；后续可能并入管理后台的「APP 发布管理」，把分发、版本检查、强制升级一起收口	08
车牌识别技术路径未验证	用付费的阿里云 OCR（RecognizeLicensePlate），拍照上传换识别结果，不做端侧模型。客户端不直连，由后端代理（AK/SK 不下发、图片经 OSS 中转）。交互随之从"取景框自动识别"变为"拍一张照"，且弱网下不可用——手工输码是常驻并列入口	07、backend/05

已解决（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

上面几条都留了各自的收尾工作，散在对应文档的「待确认项」里：车牌识别的置信度阈值与图片压缩参数、OCR 调用量与计费口径、关掉混淆后的安全侧确认、Mac Runner 接入流水线的时点。

语言约定

文档以中文为主。