feat: implement NFC lifecycle with SN support and Redis integration

README.md

@@ -22,6 +22,23 @@ mvn spring-boot:run
 本机敏感配置可放在仓库根目录的 `.hera-local.yml`，使用与 `application.yml` 相同的 YAML
 层级。后端从项目根目录启动时会自动加载，此文件已加入 Git 忽略清单；服务器使用环境变量配置。
 
+## Redis
+
+使用 Spring Data Redis 和 Lettuce，依赖版本由 Spring Boot 2.7.18 管理。
+默认地址为 `101.43.139.56:6379`，逻辑库为 `0`，连接与命令超时均为 3 秒。
+支持 `REDIS_HOST`、`REDIS_PORT`、`REDIS_USERNAME`、`REDIS_PASSWORD`、`REDIS_DATABASE`、
+`REDIS_SSL` 环境变量；本机密码配置在被 Git 忽略的 `.hera-local.yml` 中。
+
+业务代码可注入 `StringRedisTemplate`。Key、Value 和 Hash 均采用字符串序列化；
+结构化数据使用现有 `ObjectMapper` 显式转换为 JSON。建议 Key 使用 `hera:{业务}:` 前缀，
+缓存和临时数据写入时必须指定合理的 TTL。当前接入连接能力，登录会话、mock 短信验证码
+仍由现有 MySQL 链路保存，未启用用户资料自动缓存。
+
+`mvn test` 包含不访问真实 Redis 的配置测试。
+`mvn test -Dtest=RedisIntegrationTest -Dhera.redis.integration=true` 显式验证真实连接、
+认证、PING、字符串读写与 TTL，使用 `hera:test:redis:{随机值}` 测试键并在结束后删除，
+不清空 Redis。该测试独立于 MySQL，不执行用户表迁移。
+
 ## 腾讯云 COS 文件存储
 
 存储桶为 `hera-1319913268`，地域为 `ap-beijing`，桶权限保持私有读。
@@ -70,25 +87,71 @@ mvn spring-boot:run
 保存在账号表；性别、生日、出生时辰、头像、现居住地区与资料修改额度保存在资料表。
 `User` 仅作为联合查询模型；业务接口不再读写 `hera_user`。
 
-首次启动会由 `UserTableMigration` 为既有正式表补齐缺失字段，并将 `password_hash` 调整为
-可空（纯微信用户未设置密码），因此数据库账号需要相应的建表及 ALTER 权限。
-如发现旧表 `hera_user`，会保留用户 ID，将旧用户和资料迁入正式表，同时保留原表。
-迁移使用数据库锁、事务及版本记录；身份或手机号冲突时停止迁移，不覆盖冲突账号。
-旧用户的资料修改周期以原 `updated_at` 为起点；新周期为首次修改起六个月，最多五次。
-重启前应备份数据库；本地 H2 测试不代表已执行远端 MySQL 迁移。
+当前系统尚未上线，以当前数据库与 `schema.sql` 为准，不执行历史用户迁移、
+启动时补列或修改旧表结构，也不读取或维护历史迁移版本表。
+`schema.sql` 仅通过 `CREATE TABLE IF NOT EXISTS` 初始化缺失的当前业务表；
+已有表结构若发生变化，应先更新代码与建表定义，不自动兼容历史结构。
+纯微信账号的 `password_hash` 可空；资料修改周期为首次修改起六个月，最多五次。
+历史迁移源码与对应测试已移除，但本次清理不会删除数据库中已有的表或记录。
 
 `POST /api/auth/wx-login` 对已绑定手机号的用户额外返回 `token` 和 `user`；未绑定时，
 继续通过 `sessionKey` 和 mock 短信验证码调用 `/api/auth/bind-phone` 完成注册或绑定。
 绑定成功会核销会话与验证码。禁用账号不能登录或使用个人资料接口。
 个人资料接口的字段名保持不变；资料尚未填写时，生日、时辰及五行报告可能为空，不填充虚构资料。
 
-以下接口均需要携带 `Authorization: Bearer <token>`，并支持统一操作：
+原 `/api/data/**` 通用 CRUD 控制器已撤下，避免普通登录用户改写设备归属、资产、
+账号状态或他人资料。Mapper 与内部 CRUD Service 保留，不作为小程序 HTTP 接口。
+账号注册和资料修改继续使用 `/api/auth/**` 与 `/api/user/profile`，尚未提供管理员接口。
 
-- `GET /api/data/{resource}/{id}`：按主键查询
-- `GET /api/data/{resource}?offset=0&limit=20`：分页列表，`limit` 最大为 100
-- `POST /api/data/{resource}`：新增
-- `PUT /api/data/{resource}/{id}`：更新
-- `DELETE /api/data/{resource}/{id}`：删除
+## NFC 与虚拟物
 
-`resource` 可取 `nfc-chips`、`user-accounts`、`user-profiles`、`virtual-items`、
-`user-virtual-items`、`offerings`、`transfers`。
+全部接口需要 `Authorization: Bearer <token>`，用户身份取 JWT，不接收操作者用户 ID。
+列表接受 `offset=0&limit=20`，单页最大 100。芯片和虚拟物字典由可信后台或数据库预先入库，
+不允许小程序自行注册硬件、指定设备奖励或修改流水。
+
+代码以现库结构为准：绑定流水通过 `nfc_uid` 关联设备，芯片不再使用 `last_login_at`。
+`nfc_chip.sn` 为设备序列号，按现库定义使用 `VARCHAR(64) NOT NULL`，无默认值、无唯一索引。
+硬件入库和更新时必须提供 SN；扫描、绑定及本人设备列表返回 `sn`，客户端不能通过绑定请求修改它。
+设备归属和绑定历史仍以唯一 UID 关联，不将 SN 当作唯一标识或绑定凭证。
+新库由 `schema.sql` 创建该字段；旧库若尚未新增，应使用真实序列号补录已有设备后再设置非空约束，
+不自动生成序列号或用 UID 代填，本服务不在启动时自动修改已有表。
+旧库如缺少芯片归属、解绑额度或绑定流水表，可先备份，再手工执行
+`src/main/resources/db/nfc-schema-update.sql`；该脚本不由应用自动执行。新库由 `schema.sql` 建表。
+若已有同名表但字段结构不同，部署前应核对，不会通过删表自动适配。
+
+- `POST /api/nfc/scan`：`{"uid":"设备UID"}`，查看绑定状态，不返回他人身份或 NDEF。
+- `POST /api/nfc/bind`：同上，绑定设备、写绑定流水、激活预置虚拟物，整体事务提交。
+- `POST /api/nfc/unbind`：同上，解绑本人设备并写解绑时间。
+- `GET /api/nfc/devices`：本人当前设备。
+- `GET /api/nfc/bindings`：本人绑定与解绑历史。
+- `GET /api/virtual-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":"祈愿"}`。
+- `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`：本人发出或收到的回向记录。
+
+一个芯片仅允许一个当前用户，一个微信用户可以绑定多个芯片；要求有效账号已绑定微信和手机号。
+重复绑定本人设备只刷新更新时间，不增加绑定次数，也不重复发放资产。
+每台芯片按北京时间自然年最多解绑两次，次数跟随芯片，不因换用户而重置，跨年重新计算。
+
+同类虚拟物在一个用户下只有一条资产记录，保留首次获得的 `nfc_uid` 和获得时间。
+绑定新设备可恢复该类失效资产。解绑最后一台提供该类虚拟物的设备后，资产状态置为 `3`（失效），
+不删除供奉和回向历史；仍有同类设备时保留资产。失效资产不能互动或直接请神，必须重新绑定。
+供奉类型 `1` 请神、`2` 上香、`3` 祈愿、`4` 功德、`5` 送神。绑定激活自动记录请神；
+送神置状态 `0`，保有对应设备时可通过请神恢复为 `1`。重复请神、重复送神会拒绝。
+只有功德请求可填写 `meritValue`，要求 1 至 1000000，仅作互动记录，不代表积分、支付或余额。
+
+回向只写记录，不创建接收方资产、不扣除发起方资产，也不把发起方状态改为已回向。
+昵称快照从账号表生成；接收方原本有同类资产时保存其关系 ID，没有则为 `null`。
+记录不开放通用修改和删除。UID 校验仅确认已入库设备，不具备防复制能力；
+若产品需要防克隆，须增加硬件挑战响应或服务端签发的激活凭证，不能将普通 UID 当作秘密。
+
+`NfcWorkflowTest` 在独立 H2 MySQL 模式测试库验证真实 Mapper XML、HTTP、事务与并发抢绑，
+覆盖解绑上限、跨年、同类多设备、失效恢复、越权、供奉和只记账回向，不访问线上业务数据。
+`mvn test -Dtest=NfcMySqlIntegrationTest -Dhera.nfc.mysql.integration=true` 显式检查现库列名，
+通过只读、零行查询验证 XML 与现表兼容，再在七张连接级临时表中验证读写与回滚。
+临时表创建成功并全部覆盖后才允许测试写入；结束时回滚并关闭连接自动清理，
+不修改正式表结构和业务记录。测试账号需有 `CREATE TEMPORARY TABLES` 权限。