5.6 KiB
当前接口以本文为准；早期交付文档中的拟定路径及送神解绑规则已由本次改动替代。
敬神：音频与真实供奉接口
本期规则
- 不提供功德、爱心、钱包、捐款、充值入口，不累计功德。服务端拒绝 offeringType=4 或任何非空 meritValue。历史列和流水保留，不删数据。
- 喇叭默认开启，偏好仅保存在本机。关闭立即静音，音频以音量0继续推进；重新开启只恢复当前实际进度的声音，不暂停、不重头、不补播。最初静音上香也从首轮开始推进，音频已经结束则开启不再出声；追加上香延长点亮，不延长音频。
- 每次上香独立提交。只有服务端返回有效记录 ID 后，次数才+1；请求失败不计数、不播音、不自动重试。网络结果不明时应刷新核对，避免手动重试重复记账。
- 点亮截止时间为最后一次成功请求对应的点击时间+15秒（不从回包开始重计）。持续点击仅增加次数、延长点亮，不重播；音频自然结束不循环。点亮到期即停止声音、恢复供桌，不回退次数。
- 页面隐藏/离开销毁音频。返回只恢复剩余点亮，不自动播放。播放错误提示用户，但不撤销已落库记录。
- 祈愿最多500字；回向对象最多255字＋选填祝愿最多500字。权限、有效绑定由服务端再次验证。成功才清空，失败保留内容。表单提交中防重复，连续上香不节流丢次数。
已接入接口（JWT，标准 ApiResponse）
服务前缀 http://101.43.139.56/hera。
| 接口 | 用途／请求 |
|---|---|
GET /api/tiangong/items（新增） |
本人列表：id/name/iconUrl/description、holdingId、active、days、incenseCount。状态与统计来自数据库，无示例持有。 |
POST /api/user/virtual-items/offerings（复用） |
{userVirtualItemId: 本人holdingId, offeringType: 1, incenseCount: 3} 上香，一次请求计一次；type=2＋prayerContent 祈愿。返回流水及id。 |
POST /api/user/virtual-items/dedications（新增） |
{userVirtualItemId: 本人holdingId, dedicationTarget, dedicationContent?} 回向对象为1至255字文本，祝愿选填、最多500字。返回主流水及嵌套dedication明细，不保留接收账号。 |
前端调用：src/services/tiangong.ts；状态管理：src/utils/tiangongStore.ts。使用服务端持有ID，不猜测数字ID。原型与字典名称精确匹配（财神／武财神、禄星、寿星、文昌星、月老），未配置者禁用，不假装已恭请。账号变更清空缓存，旧响应不能写入新账号。
请神/送神通过 POST /api/user/virtual-items/lifecycle 提交 {userVirtualItemId, actionType}（1请神、2送神）。送神停止供奉并保留设备绑定、累计上香次数，不消耗解绑额度。已送神状态可重新请神；未绑定或过期状态需先完成 NFC 绑定。真实 NFC 绑定与解绑仍待接入。
部署边界
前后端代码推送不等于部署：本次未部署远程后端、未操作远程数据库。
部署时需先执行后端 src/main/resources/db/virtual-item-lifecycle-update.sql 并部署对应后端代码。供奉明细改为上香、祈愿、回向三张表，请神/送神写独立流水，前端构建不能代替数据库迁移与后端部署。
远端无新接口/新表结构时，正式页面提示加载或提交失败，不以 Mock 伪装成功。隔离 H2 测试已验证 Controller→Service→MyBatis→落库，不等同于远端联调。
H5演示：http://127.0.0.1:4173/?avatarDemo=1#/pages/tiangong-detail/index?id=wealth。仅此显式演示和preview使用内存Mock及明确提示，不上传姓名和祝愿，不代表真实账号。普通地址及微信构建走真实接口。
开发者工具验收
- 重新编译，后端及SQL部署后，用已绑定神仙的账号登录→天宫→对应详情。无功德入口，上香次数与服务端一致。
- 开声→上香：网络出现type=1请求，成功才次数+1、点亮。10秒再点一次，再+1；音频不重播，第二次点击15秒后恢复。
- 上香第3秒关闭喇叭，立即无声；第10秒开启，应听到第10秒处剩余音频，不从第3秒接续，次数不变。第15秒音频结束后开启不得再播；第10秒追加上香使供桌仍亮时，也不得重播已结束音频。初始静音上香同样验证。
- 祈愿输入内容→确认，type=2成功显示“祈愿已记录”。回向输入回向对象＋选填祝愿→确认，dedications成功显示“回向已记录”；数据库独立回向明细保留对象和祝愿。
- 断网或停用绑定：三种提交均不显示成功；上香不增加；表单内容保留。切账号后不能沿用旧持有状态，离开不得继续响。
- 真机检查系统静音、音量及来电中断。自动测试验证音量开关、进度推进及结束状态，不能代替听感验收。
用户原WAV未改；本地15秒AAC约179KB。使用 createInnerAudioContext 的play/volume/stop/destroy、结束/错误事件及本机存储，不调用真实支付或硬件。
验证记录
- 音频规则调整后103项前端测试通过，类型检查、H5／微信构建、13个原生WXSS编译检查通过。后端沿用上次H2供奉/NFC测试14项、账号回归8项的验证结果，本次未修改后端。
- 微信产物合计2,022,060 bytes，低于2MiB，后续新增素材需关注余量。
- 浏览器375×812检查上香计数、开关、回向、祈愿及空值校验通过；无浏览器错误。截图
/private/tmp/hera-dedication-no-merit.png。未以浏览器检查替代真机听感和远端联调。