3.1 KiB
3.1 KiB
App 架构决策文档
Flutter APP 的分包、分层、技术选型等决策记录，按序号阅读。
这些文档是本仓库代码的约束来源。 代码和文档不一致时，以文档为准改代码。
首版范围为 Android / iOS，鸿蒙 OHOS 不在首版内（但 SDK 基线锁 3.44.9 是为后续 OHOS 适配留窗口，见 01 和 07）。
| 文档 | 内容 |
|---|---|
| 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、格式化、分支、流水线卡点） |
这份副本从哪来、怎么更新
原件在 conti-docs 仓库的根目录，那里是唯一事实来源。
这里是一份副本，目的是让在本仓库里干活的人（和 AI）不用切仓库就能查到约束。
代价是会漂移。改文档去 conti-docs 改，然后同步过来，不要只改这一边：
cp ../../conti-docs/[0-9][0-9]-*.md ./
# 复制完把跨仓链接改回来（原件里是 ./backend/ 和 ./Architecture-Diagram/）
sed -i 's|](\./backend/|](../../conti-backend/docs/|g' ./[0-9][0-9]-*.md
sed -i 's|](\./Architecture-Diagram/|](../../conti-docs/Architecture-Diagram/|g' ./[0-9][0-9]-*.md
跨仓链接（架构图、后端文档）按 Continental-App/ 下三个仓库平级摆放来写相对路径。
换了目录结构这些链接就断了，重跑一次上面的 sed 即可。
相关
- 后端架构决策：
conti-backend/docs/（Kotlin + Spring Boot，01-12） - 架构图与 PRD：
conti-docs/Architecture-Diagram/ - PRD 与架构文档已知不一致的三处、未决阻塞项（iOS 构建链路、错误码表、Sentry 自建还是 SaaS 等）：
见
conti-docs/README.md