更新记录

1.0.0（2026-07-23）

首次发布。
Android 接收自有平台后端推送的收款 JSON，并支持本机 TTS 播报、前台事件回调和后台显式广播唤起。
iOS 使用原生 AVSpeechSynthesizer，由宿主 APNs/UniPush 回调调用 handlePaymentNotice()。
支持事件 ID 去重、金额校验、播报模板、语速/音调、语音准备状态和本地事件清理。
Android 支持前台服务、显式广播，以及通知权限、电池优化和自启动设置边界说明。

平台兼容性

uni-app x(3.8.0)

Chrome	Safari	Android	Android插件版本	iOS	iOS插件版本	鸿蒙	微信小程序
-	-	5.0	1.0.0	12	1.0.0	-	-

其他

多语言	暗黑模式	宽屏模式
×	√	×

收款到账TTS播报

面向自有收银平台的 uni-app x App 插件。后端完成支付回调验签、解密和订单状态更新后，将收款事件交给 App；插件内置跨平台 TTS 语音合成能力，在设备本机直接播报，并向前台页面回调事件。

典型链路：

支付服务端回调 -> 业务后端验签并更新订单 -> 推送收款 JSON -> App 调用插件 -> 本机 TTS 播报

插件不读取支付宝或微信 App 的系统通知，不读取聊天内容，也不上传支付数据。客户端播报只用于提醒，不能替代服务端入账、验签、对账或支付凭证。

核心特性

内置原生 TTS 语音合成：Android 使用系统 TextToSpeech，iOS 使用 AVSpeechSynthesizer，无需接入第三方语音服务或额外语音播报 SDK。
动态播报模板：支持 {source}、{amount}、{currency}、{orderNo} 变量，可自定义“微信支付收款 12.80 元”等播报内容。
语音参数可调：支持播报开关、语速和音调配置，语速/音调配置范围为 0.5 - 2.0。
到账事件智能处理：内置金额格式校验、正数校验、事件 ID 去重、重复事件拦截和最近事件管理。
前台与后台协同：前台页面可实时收到结构化事件回调；Android 支持可选前台服务和宿主推送 SDK 显式广播桥接。
本机处理与状态可观测：不上传收款数据，可查询 TTS 是否准备完成、播报开关、后台服务和电池优化状态。

支持范围

当前支持 uni-app x App 的 Android 和 iOS 构建：

平台	已实现能力	后台入口
Android	原生 `TextToSpeech`、收款事件校验、去重、前台事件回调、可选前台服务和显式广播接收	由宿主推送 SDK 原生回调发送显式广播
iOS	原生 `AVSpeechSynthesizer`、收款事件校验、去重、前台事件回调	由宿主在 APNs 或 UniPush 回调中调用 `handlePaymentNotice()`

插件不内置 FCM、APNs、UniPush 或小米/华为等厂商推送 SDK，也不提供 Web、小程序和 HarmonyOS 实现。

快速接入

import {
    configurePaymentNotice,
    startPaymentNotice,
    handlePaymentNotice,
    onPaymentNotice,
    PaymentNoticeEvent
} from '@/uni_modules/KB-payment-notice'

configurePaymentNotice({
    enabled: true,
    speechEnabled: true,
    speechTemplate: '{source}收款{amount}元',
    speechRate: 1.0,
    speechPitch: 1.0,
    dedupeWindowMs: 5000
})

onPaymentNotice((event: PaymentNoticeEvent) => {
    console.log('平台收款', event.orderNo, event.amount)
})

startPaymentNotice()

后端事件交给插件：

const result = handlePaymentNotice(JSON.stringify(payload))
console.log(result.code, result.message)

configurePaymentNotice({ enabled: true }) 和 startPaymentNotice() 都可以启用播报，实际项目建议只保留一处初始化逻辑。

收款事件

handlePaymentNotice(payload) 接收 JSON 字符串。amount 必须是大于 0、最多两位小数的十进制字符串；id 建议使用服务端唯一的支付事件 ID。没有 id 时，插件使用完整 payload 作为去重依据。

{
  "id": "pay_evt_202607230001",
  "amount": "12.80",
  "currency": "CNY",
  "source": "微信支付",
  "orderNo": "ORDER-10001",
  "title": "收款到账",
  "metadata": "门店一号"
}

字段说明：

id：支付事件唯一标识，用于去重。
amount：必填金额字符串，正数且最多两位小数。
currency：币种，缺省为 CNY。
source：收款来源，缺省为 platform。
orderNo：业务订单号，可选。
title、metadata：事件附加信息，可选。

插件会校验金额、按 dedupeWindowMs 去重，并在事件有效且未重复时触发设备端 TTS 和 onPaymentNotice()。重复事件不会再次播报。去重记录是本地内存/本地存储状态，不是服务端幂等；账务仍以服务端订单状态为准。

API

通用 API：

configurePaymentNotice(config)：设置开关、TTS 模板、语速、音调和去重窗口；Android 会保存到本地，iOS 仅对当前进程有效，宿主启动时应重新配置。
startPaymentNotice() / stopPaymentNotice()：启用或停用收款播报。
handlePaymentNotice(payload)：处理后端传入的收款 JSON。
speakPaymentNotice(amount, source?, orderNo?)：手动播报，适合页面测试；生产事件使用 handlePaymentNotice()。
getPaymentNoticeStatus()：读取平台、播报和 TTS 状态。
onPaymentNotice(handler) / offPaymentNotice()：注册或移除前台事件回调。
getLastPaymentNotice()：读取当前进程中的最近事件；进程被回收后不保证保留。
clearPaymentNotice()：清理本地事件队列、最近事件和去重记录。

TTS 语音合成使用系统已安装的中文语音包。speechReady 为 false 时，表示当前设备尚未准备好可用语音，需检查系统 TTS 引擎、中文语音数据和设备音频状态；插件不会在云端合成或上传文本。

Android 专用 API：

startPaymentNoticeKeepAlive() / stopPaymentNoticeKeepAlive()：开启或关闭 Android 前台服务。开启后系统通知栏显示常驻服务通知。
isIgnoringBatteryOptimizations()：查询本应用是否已加入 Android 电池优化白名单。
requestIgnoreBatteryOptimizations()：打开 Android 电池优化设置页，由用户确认是否加入白名单。
openAutoStartSettings()：尝试打开常见厂商的自启动设置页；是否生效必须由用户手动确认。

Android 后台与推送

插件的 Android 显式广播接收器只负责接收宿主推送 SDK 转交的业务 JSON，不负责连接或配置推送服务。宿主在 FCM、UniPush 或厂商推送的原生消息回调中发送：

val intent = Intent("uts.sdk.modules.kbPaymentNotice.PAYMENT_NOTICE")
    .setPackage(context.packageName)
    .putExtra("payment_notice_payload", payloadJson)
context.sendBroadcast(intent)

启用前台服务后，可以提高普通退后台、息屏场景下的服务存活和播报稳定性，但不是“永不被杀”的权限。Android 13 及以上首次启用时需要允许通知权限，收款播报通知渠道也必须保持开启。

以下情况仍可能导致无法收到或播报：用户强行停止 App、系统或厂商冻结后台、通知权限或通知渠道被关闭、系统回收进程、推送 SDK 投递失败，以及设备音量、静音、蓝牙路由或 TTS 语音包不可用。

电池优化边界

requestIgnoreBatteryOptimizations() 只是打开 Android 系统的电池优化豁免页面，不会自动授权；只有用户确认后，isIgnoringBatteryOptimizations() 才会返回 true。它的作用是减少 Doze 等电量限制对后台运行的影响，不是降低插件耗电；加入白名单可能增加耗电，也不能保证推送、后台执行或 TTS 一定成功。

自启动边界

openAutoStartSettings() 会按设备尝试打开小米、华为、OPPO、iQOO、vivo 等常见厂商入口，无法识别时回退到应用详情页。Android 没有统一的自启动 API，插件不能替用户开启设置，也不能准确查询自启动是否已开启。

用户已经开启前台服务并允许设备自启动时，设备重启后插件会尝试恢复前台服务；部分 ROM 可能阻止开机启动。自启动和电池优化豁免都不能绕过用户的“强行停止”，也不能把普通推送变成必达的进程内动态播报。

iOS 后台边界

iOS 不提供 Android 式常驻后台保活服务，也没有 Android 电池优化白名单或自启动设置。宿主在 APNs 或 UniPush 消息回调中拿到后端已验签的 JSON 后调用：

handlePaymentNotice(payloadJson)

应用前台时，插件会触发事件回调和系统 TTS。应用在后台或进程被系统回收时，能否执行回调、执行多久以及能否完成语音播放，取决于宿主推送配置和 iOS 系统调度，插件不作保证。

权限、隐私与安全

Android 声明前台服务、媒体播放前台服务类型、通知、忽略电池优化和开机广播相关权限。
Android 13 及以上启用前台服务时可能弹出通知权限申请；电池优化豁免必须由用户在系统页面确认。
插件不申请通知读取、录音、通讯录、定位或短信权限，不读取支付宝或微信通知。
插件不负责支付回调验签、解密或订单幂等。后端完成这些步骤后再推送事件，不要使用客户端播报结果直接发货、记账或修改余额。
收款 JSON 会在设备本机处理，不上传到插件服务端。

真机验收

使用 Android/iOS 真机和已集成插件的自定义基座。
启用播报，先调用 speakPaymentNotice() 验证前台 TTS。
使用后端测试接口发送收款 JSON，验证事件回调、金额校验和重复事件去重。
Android 配置宿主推送 SDK 原生广播，并分别测试普通后台、息屏、划掉任务、重启设备和通知权限关闭。
iOS 配置宿主 APNs 或 UniPush 回调，分别测试前台、后台和进程不在时的系统行为。
单独验证强行停止、厂商后台策略、省电策略、静音和无可用 TTS 语音包等限制场景。