observability

可观测性 Skill（多区域 Flutter + NestJS）

把"生产出了什么事"变得可见。分三层：崩溃/错误采集（前端）、结构化日志 + 追踪（后端）、健康/告警（运维）。所有 <PLACEHOLDER> 替换为项目实际值。

★ 多区域最大约束：cn flavor 禁 Firebase（对应 cn-android-flavor §1），所以 Crashlytics 不能进 cn 包。崩溃采集必须按 flavor 分流。

1. ★ Flavor 感知的崩溃采集（核心决策）

flavor	崩溃采集方案	理由
cn_android	Sentry（可自托管国内）	禁 Firebase → 不能用 Crashlytics；Sentry Dart SDK 无 Google 依赖
overseas_android	Sentry 或 Firebase Crashlytics	二选一；用 Sentry 可与 cn 统一后台
iOS	Sentry 或 Crashlytics	同上

推荐：三 flavor 统一用 Sentry（一个后台看全部，cn 可指向自托管实例；避免维护两套崩溃后台）。Crashlytics 仅在你已重度依赖 Firebase 生态时用于 overseas/iOS。

pubspec.yaml：

dependencies:
  sentry_flutter: ^8.x.x
  # 若 overseas/iOS 另用 Crashlytics（可选，且必须条件 import 隔离，勿进 cn）：
  # firebase_crashlytics: ^4.x.x

★ flavor 分流初始化（对应 flutter-coding-conventions §18 工厂模式）：

// lib/core/config/crash_reporter_factory.dart
Future<void> initCrashReporter(Widget app) async {
  final flavor = FlavorConfig.current;
  final dsn = _dsnForFlavor(flavor);            // 不同 flavor 不同 DSN/项目
  await SentryFlutter.init(
    (o) {
      o.dsn = dsn;
      o.environment = flavor.name;              // cn_android / overseas_android / ios
      o.release = '<APP_PACKAGE>@$appVersion+$buildNumber';  // ★ 与 pubspec 版本号绑定
      o.tracesSampleRate = 0.2;                 // 性能追踪采样，按量调
      o.beforeSend = _redactPII;                // ★ 脱敏（第 5 节）
    },
    appRunner: () => runApp(app),
  );
}

★ cn 的 DSN 指向自托管 Sentry（sentry.<PROD_DOMAIN>），数据不出境、国内上报快；overseas/iOS 可用 Sentry SaaS。

手动上报业务错误 + breadcrumb：

try {
  await api.callAI(...);
} catch (e, st) {
  Sentry.addBreadcrumb(Breadcrumb(message: 'toolId=A1 action=generate', category: 'credits'));
  await Sentry.captureException(e, stackTrace: st);
  rethrow;   // ★ 仍然 rethrow，不吞错（对应日志铁律）
}

2. release 与 buildNumber 绑定（不绑等于没上报）

崩溃如果不带 release 版本号，无法定位是哪个包。铁律：

• o.release = '<pkg>@<versionName>+<buildNumber>'，值从 package_info_plus 读，与 pubspec.yaml（_shared/rules.md §3 唯一真相源）一致
• 每次发版在 CI 里 上传 debug symbols / dSYM，否则堆栈是混淆后的乱码：

  # release-mobile.yml 追加（Sentry）
  - run: |
      flutter build apk --flavor cn --release --split-debug-info=build/symbols --obfuscate ...
  - run: sentry-cli debug-files upload --include-sources build/symbols
    env: { SENTRY_AUTH_TOKEN: ${{ secrets.SENTRY_AUTH_TOKEN }} }
  

• iOS dSYM：archive 后 sentry-cli upload-dif ios/build/...（或 Crashlytics 走 upload-symbols）