Flutter 中国 + 海外 多平台 App 开发 · Agent Skills

简体中文 | English

一套给 AI 编码助手（Claude Code / Codex / Cursor 等）用的工程规范包，把"中国市场 + 海外市场、iOS + Android、Flutter 前端 + NestJS 后端"三flavor 全区发布的真实踩坑经验，蒸馏成可被 agent 自动加载的 Skill。

A set of agent-loadable engineering skills for building & shipping a Flutter + NestJS app to both China and overseas markets (iOS + Android), with three build flavors, distilled from real production experience.

这不是一个"即用框架"，而是一套 参考骨架 + 铁律清单。所有代码片段用 `` 占位，落地时替换为你的项目值。它的价值在于：让 AI 助手在你开发多区域 App 时，自动想起那些上架被拒、跨租户越权、切租户 race、积分丢失、cn 包混入 Google 被华为拒 之类的坑。

---

这套东西覆盖什么（诚实版）

这是一条经过生产验证的精选技术栈，不是"任你挑供应商的集成大全"。下面如实标注覆盖边界：

✅ 已覆盖

• 三 flavor 架构：iOS（APNs + App Store IAP）/ cn_android（JPush + 微信支付宝 + 阿里云）/ overseas_android（FCM + Play Billing）+ 互斥硬约束（cn 禁 Firebase、overseas 禁 JPush）
• 前端：Flutter + Riverpod + go_router + Freezed + i18n 多语言 + UI 原语 + 多租户 Provider 重置
• 后端：NestJS + Prisma + MySQL 多租户铁律 + JWT + Redis + BullMQ + UploadService（本地/OSS）+ 内容审核
• 登录：Apple / Google / 微信 / QQ 第三方登录 + 服务端验签 + 账号打通 + App Store 4.8 合规
• 支付：微信支付 / 支付宝（fluwx/tobias）/ Apple IAP（JWS 验签）/ Google Play Billing
• 推送：极光 JPush（国内）/ FCM（海外）/ APNs（iOS）
• 存储：阿里云 OSS / 腾讯云 COS / AWS S3（UploadService 统一抽象，env 切换零改码）
• 地图定位：高德（国内）/ Google Maps / Mapbox 按国家路由 + GCJ-02 坐标 + 定位权限合规
• 合规：ICP 备案名双 label / 隐式标识技术说明文档 / Privacy Manifest / GDPR·CCPA
• 测试：单元 / widget / golden / ★flavor 条件编译测试 / 多租户隔离 / 扣费退款
• CI/CD：GitHub Actions 三 flavor 矩阵构建 + iOS 签名（fastlane match）+ 产物守卫 + 部署流水线
• 可观测性：flavor 感知崩溃采集（Sentry）+ 结构化日志 + 健康告警 + PII 脱敏
• 部署：rsync + PM2 + Nginx 生产 SOP（ask-before-write / dry-run / uploads 双向补齐）
• 可跑 starter：examples/starter/——三 flavor Flutter 骨架 + NestJS /health 后端（已实测 flutter analyze / 后端 /health 通过）

❌ 暂未覆盖（Roadmap，欢迎 PR）

• 华为原生 HMS Push（当前走 JPush 厂商通道）
• 海外订阅：Stripe / RevenueCat
• Flutter Web / Desktop 目标
• 微信原生分享（fluwx 支持，尚未单独成文）

想要上面某块？开 issue 说需求，或参照现有 skill 的写法提 PR。每个 skill 都是自洽的单文件规范，容易增补。

---

Skill 索引（15 个）

从 flutter-multi-region-dev 进入——它是路由器，会按你的上架范围告诉 agent 加载哪些子 skill。