# App 架构决策文档

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

**这些文档是本仓库代码的约束来源。** 代码和文档不一致时，以文档为准改代码。

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

| 文档 | 内容 |
| --- | --- |
| [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、格式化、分支、流水线卡点） |

## 这份副本从哪来、怎么更新

原件在 **[`conti-docs`](../../conti-docs/)** 仓库的根目录，那里是唯一事实来源。
这里是一份副本，目的是让在本仓库里干活的人（和 AI）不用切仓库就能查到约束。

代价是会漂移。**改文档去 `conti-docs` 改，然后同步过来**，不要只改这一边：

```bash
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/`](../../conti-backend/docs/)（Kotlin + Spring Boot，01-12）
- **架构图与 PRD**：[`conti-docs/Architecture-Diagram/`](../../conti-docs/Architecture-Diagram/)
- **PRD 与架构文档已知不一致的三处**、**未决阻塞项**（iOS 构建链路、错误码表、Sentry 自建还是 SaaS 等）：
  见 [`conti-docs/README.md`](../../conti-docs/README.md)