feat: split worship records and return latest prayers and dedications

README.md

@@ -1,4 +1,4 @@
-# Hera 后端
+# 祈运小程序后端
 
 Spring Boot 后端，提供微信小程序登录、手机号验证码绑定、用户资料、协议和关注我们接口。
 
@@ -183,13 +183,22 @@ tail -f logs/hera-error.log
 - `GET /api/nfc/bindings`：本人绑定与解绑历史。
 - `GET /api/virtual-items`：启用的虚拟物字典，按字典排序。
 - `GET /api/tiangong/items`：本人神仙持有状态、上香计数及展示图片。
+
 - `GET /api/user/virtual-items`：本人资产，含失效与送神状态。
 - `GET /api/user/virtual-items/{id}`：本人持有关系详情。
 - `PUT /api/user/virtual-items/sort`：`{"ids":[持有关系ID,...]}`，按提交顺序设置排序值。
-- `POST /api/user/virtual-items/offerings`：`{"userVirtualItemId":1,"offeringType":3,"content":"祈愿"}`。
+- `POST /api/user/virtual-items/offerings`：`{"userVirtualItemId":1,"offeringType":2,"prayerContent":"愿家人平安"}`。
+- `POST /api/user/virtual-items/lifecycle`：`{"userVirtualItemId":1,"actionType":1}`，`1` 请神、`2` 送神。
+- `GET /api/user/virtual-items/lifecycle?holdingId=1`：本人请神/送神流水，`holdingId` 可省略。
 - `GET /api/user/virtual-items/offerings?holdingId=1`：本人供奉记录，`holdingId` 可省略。
-- `POST /api/user/virtual-items/transfers`：`{"userVirtualItemId":1,"toUserId":2,"content":"祝福"}`。
-- `GET /api/user/virtual-items/transfers`：本人发出或收到的回向记录。
+- `POST /api/user/virtual-items/dedications`：`{"userVirtualItemId":1,"dedicationTarget":"家人","dedicationContent":"愿平安顺遂"}`。
+- `GET /api/user/virtual-items/dedications`：本人发起的回向记录。
+- `/api/user/virtual-items/transfers` 保留为上述回向接口的路径别名，使用相同请求和响应，不再接收接收账号 ID。
+
+`GET /api/tiangong/items` 还会为每位神仙返回 `latestPrayer`（`prayerContent`）和
+`latestDedication`（`dedicationTarget`、可空的 `dedicationContent`），供祈愿、回向表单回显。
+仅匹配当前登录用户与该神仙字典 ID 的 `status=1` 且存在对应明细的记录；
+两类分别按 `offered_at DESC, id DESC` 取最新一条，没有可用记录时对应字段为 `null`。
 
 虚拟物字典与天宫列表均返回 `iconUrl`（列表图标）和 `iconDetailUrl`（神仙详情页大图），
 两种图片独立配置，不互相覆盖。`virtual_item.icon_detail_url` 按现库使用
@@ -219,18 +228,43 @@ WebP 应在上传前用支持该格式的工具完整解码，核对尺寸、透
 同类虚拟物在一个用户下只有一条资产记录，保留首次获得的 `nfc_uid` 和获得时间。
 绑定新设备可恢复该类失效资产。解绑最后一台提供该类虚拟物的设备后，资产状态置为 `3`（失效），
 不删除供奉和回向历史；仍有同类设备时保留资产。失效资产不能互动或直接请神，必须重新绑定。
-供奉类型 `1` 请神、`2` 上香、`3` 祈愿、`4` 功德、`5` 送神。绑定激活自动记录请神；
+供奉类型与最新表设计一致：`1` 上香、`2` 祈愿、`3` 回向。原来的 `1` 请神、`5` 送神
+必须改为调用独立的 `/lifecycle` 接口，客户端需随本次后端适配同步升级，不能沿用旧供奉编码。
+请神/送神写 `user_virtual_item_lifecycle`，其中 `action_type` 为 `1` 请神、`2` 送神。
+绑定首次发放或恢复资产也写请神流水；重复绑定本人设备或添加同类设备不重复写请神流水。
 送神置状态 `0`，保有对应设备时可通过请神恢复为 `1`。重复请神、重复送神会拒绝。
-只有功德请求可填写 `meritValue`，要求 1 至 1000000，仅作互动记录，不代表积分、支付或余额。
 
-回向只写记录，不创建接收方资产、不扣除发起方资产，也不把发起方状态改为已回向。
-昵称快照从账号表生成；接收方原本有同类资产时保存其关系 ID，没有则为 `null`。
+供奉主记录只保留用户、虚拟物、类型、状态和时间，明细分别写入
+`user_virtual_item_offering_incense`、`user_virtual_item_offering_prayer`、
+`user_virtual_item_offering_dedication`，主记录与明细在同一事务提交。
+上香可传 `incenseCount`（3、6、9，默认3）、`incenseType`（可省略，1至127）、`remark`（最多255字）。
+每次请求由服务端记录 `incenseTimes=1`；客户端不能通过该字段扩大次数。
+祈愿必须填写 `prayerContent`（非空，最多500字，兼容旧字段名 `content`）。
+通过供奉入口回向必须填写 `dedicationTarget`（非空，最多255字），`dedicationContent` 可为空、最多500字。
+同一请求只允许填写所选类型的明细，`meritValue` 仍为禁用参数，填写即拒绝。
+响应中按类型返回嵌套 `incense`、`prayer`、`dedication` 明细，其余两个为 `null`。
+`holdingId` 历史筛选先校验归属，再按当前用户和虚拟物查询，不依赖主表已删除的持有关系字段。
+天宫的 `incenseCount` 是本人该虚拟物有效上香主记录所关联明细的 `SUM(incense_times)`，
+不按香支数或记录条数计算，无记录时返回0；祈愿、回向和无效主记录不参与累计。
+
+回向只保存发起用户、虚拟物、对象文本和可选的回向文；不关联接收账号，不转移资产。
+专用回向接口兼容 `name`/`content` 字段别名，返回统一的供奉主记录和 `dedication` 明细。
+回向列表仅返回当前用户发起的记录，不通过对象文本推测“接收人”。
 记录不开放通用修改和删除。UID 校验仅确认已入库设备，不具备防复制能力；
 若产品需要防克隆，须增加硬件挑战响应或服务端签发的激活凭证，不能将普通 UID 当作秘密。
 
 `NfcWorkflowTest` 在独立 H2 MySQL 模式测试库验证真实 Mapper XML、HTTP、事务与并发抢绑，
 覆盖解绑上限、跨年、同类多设备、失效恢复、越权、供奉和只记账回向，不访问线上业务数据。
 `mvn test -Dtest=NfcMySqlIntegrationTest -Dhera.nfc.mysql.integration=true` 显式检查现库列名，
-通过只读、零行查询验证 XML 与现表兼容，再在七张连接级临时表中验证读写与回滚。
+通过只读、零行查询验证 XML 与现有供奉拆分表兼容，再在十张连接级临时表中验证读写与回滚。
+新增请神/送神流水表在临时表中验证，不要求联调前向正式库建表。
 临时表创建成功并全部覆盖后才允许测试写入；结束时回滚并关闭连接自动清理，
 不修改正式表结构和业务记录。测试账号需有 `CREATE TEMPORARY TABLES` 权限。
+
+### 供奉拆分后的部署
+
+本次适配以已经存在的供奉主表及三张明细表为前提；部署新代码前，执行
+`src/main/resources/db/virtual-item-lifecycle-update.sql` 创建独立的请神/送神流水表。
+脚本可重复执行，不更新已有业务记录、不推测回填历史。新环境由 `schema.sql` 创建全套表。
+旧的 `named-dedication-update.sql` 只适用于历史回向表，不能在当前已拆分的数据库上重放。
+从更早的旧供奉结构升级时，需另行制定历史数据迁移，不能只重命名类型编码或通过删表重建处理。