用途：为 .NET MAUI 应用添加推送通知，覆盖 Android（Firebase Cloud Messaging）、iOS（Apple Push Notification Service）与 Azure Notification Hub 的端到端接入流程。
主要能力：提供架构说明（MAUI 应用 → ASP.NET Core 后端 → Azure Notification Hub → FCM/APNS → 设备）、故障排查表、平台配置检查清单与关键注意事项。
必要配置与用法：Android 需在 Platforms/Android/ 放置 google-services.json 并在 .csproj 加 <GoogleServicesJson>，添加 Xamarin.Firebase.Messaging（仅 Android 条件），在 API 33+ 请求 POST_NOTIFICATIONS，API 26+ 先创建通知渠道，OnNewToken 中始终调用 RegisterAsync，并在清单注册 FirebaseMessagingService 与 MESSAGING_EVENT 过滤器。iOS 需在 Apple 开发者门户启用 Push Notifications，上传 APNs 密钥（.p8）到 Azure Notification Hub，Entitlements.plist 设置 aps-environment，.csproj 设置 CodesignEntitlements，授权后主线程调用 RegisterForRemoteNotifications，设备令牌转小写十六进制（无短横线）。后端需配置 FCM V1 JSON 与 APNS 密钥，BaseAddress 以 / 结尾，标签表达式按每组不超过 20 分批，平台字符串用 "fcmv1" 与 "apns"。
限制与常见坑：HttpClient.BaseAddress 缺少结尾 / 会导致相对 URI 解析静默失败；调试构建下 Firebase 令牌频繁变化，跳过 OnNewToken 会导致后端持有过期令牌而推送失败；令牌冷启动可能为空，需用 IsNullOrWhiteSpace 防护；Azure NH 标签表达式超过 20 个标签会抛异常；使用旧值 "gcm" 会导致设备注册返回 422；iOS 模拟器不支持 APNS，必须用真机。
其他：完整实现模板见 references/push-notifications-api.md。具体平台版本支持与收费情况暂未提供。