Files

T

Guangfei.Zhao 444db49818 feat: add engineering conventions and CI gates documentation

- Introduced a new document outlining SDK version locking, static analysis, formatting, generated artifacts management, branching and commit conventions, and CI gate checks.
- Updated README to include the new conventions document.
- Modified API design to use numeric error codes instead of strings, with a dedicated ErrorCode object for better maintainability.
- Adjusted global exception handling to return numeric error codes.
- Updated tests to reflect changes in error code handling.

2026-08-13 19:28:36 +08:00

7.2 KiB

Raw Blame History

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 + Spring Boot + Gradle）架构决策文档，按序号阅读：

文档	内容
backend/01-project-structure.md	工程结构 / 模块划分（Gradle 多模块，模块化单体）
backend/02-layering.md	分层规范（api/application/domain/infrastructure）
backend/03-persistence.md	持久层方案（Spring Data JPA + Hibernate，Flyway）
backend/04-security-auth.md	安全与认证方案（Spring Security + JWT，门店上下文）
backend/05-integration-layer.md	集成层设计（F6 Adapter / Mini 域客户端）
backend/06-api-design.md	API 设计规范（统一响应、DTO、版本化）
backend/07-config-governance.md	配置与服务治理（K8s ConfigMap/Secret）
backend/08-observability.md	可观测性（Trace ID、日志、审计）
backend/09-build-deploy.md	构建与多环境部署（Gradle、Docker、GitLab CI/CD）
backend/10-testing.md	测试策略

已知文档间差异（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

语言约定

文档以中文为主。

7.2 KiB Raw Blame History Unescape Escape