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.

README.md

@@ -19,6 +19,13 @@ Flutter APP 的分包、分层、技术选型等决策记录，按序号阅读
 | [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、格式化、分支、流水线卡点） |
+
+首版范围为 **Android / iOS**，鸿蒙 OHOS 不在首版内（但 SDK 基线锁 3.44.9 是为后续 OHOS 适配留窗口，见 01 和 07）。
 
 ### Architecture-Diagram/
 
@@ -53,9 +60,34 @@ Flutter APP 的分包、分层、技术选型等决策记录，按序号阅读
 | [backend/09-build-deploy.md](./backend/09-build-deploy.md) | 构建与多环境部署（Gradle、Docker、GitLab CI/CD） |
 | [backend/10-testing.md](./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](./07-native-integration.md) 和 [10](./10-webview-h5.md) |
+| 3 | JSBridge 能力数 | 计划稿一度记为 13 项 | PRD §7.4 实际列出 **12 项**，见 [10](./10-webview-h5.md) |
+
 ## 待补充
 
 - API 文档
+- `15-ui-design-system.md` — `core_ui` 的 Material 3 主题、设计 token、暗色模式（对应 PRD §8.2 统一交互规则）
+- `16-i18n.md` — 首版单语言，但需预留 `flutter_localizations` + `intl` 结构（后补代价高）
+
+## 跨文档的阻塞项
+
+这几条不解决会直接卡住工程落地，集中列在这里：
+
+| 阻塞项 | 出处 | 影响 |
+| --- | --- | --- |
+| **iOS 构建链路不成立** | [08](./08-build-flavors.md) | 现有 GitLab Runner 是与后端共用的 Linux runner，`flutter build ipa` 需要 macOS。需决策自建 mac runner / 云端 mac runner / iOS 手工出包 |
+| **后端错误码表未定** | [12](./12-error-and-api-contract.md)、[backend/06](./backend/06-api-design.md) | 客户端无法对错误码做分支处理，只能全部走默认文案 |
+| **Sentry 自建还是 SaaS 未定** | [13](./13-observability-analytics.md) | 崩溃平台已定为 Sentry（Bugly 无法还原 Dart 混淆堆栈，而我们的异常绝大多数是 Dart 异常）。但 `sentry.io` SaaS 属于数据出境且门店网络可达性存疑，自建则需要内网资源和运维承接方——需明确 |
+| **神策服务是否可用未确认** | [13](./13-observability-analytics.md) | 客户端埋点定为神策（团队有经验、官方插件在维护），但本项目**没有现成账号**。公司若未在用，开通是采购流程而非配置项。**不阻塞开工**——事件方案和 `core_analytics` 接口先做，两者与 SDK 无关；实在走不通再换自建 endpoint |
+| **内测分发渠道未定** | [08](./08-build-flavors.md) | Firebase App Distribution 国内可达性存疑，需选替代方案 |
+| **车牌识别技术路径未验证** | [07](./07-native-integration.md) | 通用扫码库只能解条码/二维码，VIN 印刷字符和车牌需要 OCR，车牌可能需要商用 SDK |
 
 ## 语言约定