54 lines
5.6 KiB
Markdown
54 lines
5.6 KiB
Markdown
> 当前接口以本文为准；早期交付文档中的拟定路径及送神解绑规则已由本次改动替代。
|
||
|
||
# 敬神：音频与真实供奉接口
|
||
|
||
## 本期规则
|
||
|
||
- 不提供功德、爱心、钱包、捐款、充值入口，不累计功德。服务端拒绝 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及明确提示，不上传姓名和祝愿，不代表真实账号。普通地址及微信构建走真实接口。
|
||
|
||
## 开发者工具验收
|
||
|
||
1. 重新编译，后端及SQL部署后，用已绑定神仙的账号登录→天宫→对应详情。无功德入口，上香次数与服务端一致。
|
||
2. 开声→上香：网络出现type=1请求，成功才次数+1、点亮。10秒再点一次，再+1；音频不重播，第二次点击15秒后恢复。
|
||
3. 上香第3秒关闭喇叭，立即无声；第10秒开启，应听到第10秒处剩余音频，不从第3秒接续，次数不变。第15秒音频结束后开启不得再播；第10秒追加上香使供桌仍亮时，也不得重播已结束音频。初始静音上香同样验证。
|
||
4. 祈愿输入内容→确认，type=2成功显示“祈愿已记录”。回向输入回向对象＋选填祝愿→确认，dedications成功显示“回向已记录”；数据库独立回向明细保留对象和祝愿。
|
||
5. 断网或停用绑定：三种提交均不显示成功；上香不增加；表单内容保留。切账号后不能沿用旧持有状态，离开不得继续响。
|
||
6. 真机检查系统静音、音量及来电中断。自动测试验证音量开关、进度推进及结束状态，不能代替听感验收。
|
||
|
||
用户原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`。未以浏览器检查替代真机听感和远端联调。
|