feat: refine login flows and integrate tiangong worship audio

docs/birthday-calendar-and-avatar.md

@@ -0,0 +1,45 @@
+# 出生历法与头像入口验收
+
+## 实现与数据约定
+
+- 编辑个人信息、完善注册资料共用 `BirthdayPicker`，支持阳历与农历、真实闰月、大小月日期联动。范围为阳历 1900-01-01 至北京时间今天，与现有生肖/五行计算的支持范围保持一致。
+- `birthday` 仍为对应阳历 `YYYY-MM-DD`，用于生肖、五行和每日计算；新增 `birthdayCalendar: "solar" | "lunar"` 仅记录输入/显示偏好。切换历法不改变实际生日，保存后重新编辑按接口偏好回显。农历闰月可由阳历日期准确还原，不需再保存第二份农历生日。
+- 生日或偏好变更沿用现有个人资料保存与修改额度规则；不在选择或切换时自动保存、不擅自改动后端生日计算。
+- 首页左上角头像使用主 Tab 导航到“我的”，不再是不可点的展示区域。
+- 微信端直接点击头像即使用 `openType=chooseAvatar`，不再先打开本项目的自定义菜单；回调只预览选中的临时文件，点击保存时仍走后端文件服务，不绕过平台用户确认。H5 不支持该微信能力，仍保留相册/拍照菜单。本次 H5 验收不代表已操作微信原生弹窗。
+
+## 接口清单
+
+没有新增路径或改变部署基址，复用以下接口：
+
+- GET `/api/user/profile`：响应新增 `birthdayCalendar`，生日仍为阳历。
+- PUT `/api/user/profile`：请求、响应新增 `birthdayCalendar`；服务端只允许 `solar`、`lunar`。
+- POST `/api/auth/wx-login`、POST `/api/auth/bind-phone`：登录资料中的 `user` 同样返回偏好。
+- POST `/api/user/avatar`：头像保存仍上传至现有文件存储服务，生日选择不影响头像接口。
+
+## 部署前置条件
+
+后端已补 DTO、实体、联合查询、资料 Mapper 和建表定义。已有目标数据库应先由部署人员执行：
+
+`/Users/zhouzhibo/file/hongzhen/idea/hera/src/main/resources/db/birthday-calendar-update.sql`
+
+随后部署/重启新版后端，再更新小程序。脚本只按列是否存在增加 `user_profile.birthday_calendar`，默认 `solar`，不修改生日、不删除数据；没有自动启动时远程迁移。本次未执行远程 MySQL DDL、未部署后端、未提交或推送。
+
+## 验收步骤
+
+1. 开发者工具重新编译，登录后从首页点击左上角头像：应切换到“我的”；再点头部进入编辑信息。
+2. 点击“农历”：显示同一天的农历及对应阳历，实际生日未变；打开日期选择器可单独选择闰月。
+3. 示例农历 2023 年闰二月初一，应对应阳历 2023-03-22。切换年份到无此闰月的年份时，使用该年的普通二月；切到小月时超出天数自动收敛，不提交无效日期。
+4. 在选择器点取消：实际生日不变。点确定、保存、返回再进入：农历偏好与日期保持；切回阳历保存后同样能回显。
+5. 首次注册完善资料使用同一控件。不能选未来日期；保存后生肖、五行使用换算后的阳历日期。
+6. 微信端直接点头像：应立即出现一次微信官方头像选择器，不先弹自定义菜单；确认后预览、取消不更换当前头像。H5 点击头像仍显示相册/拍照菜单。
+
+本地视觉验收可用 `http://127.0.0.1:4173/?avatarDemo=1#/pages/home/index`，其中资料、头像仅为隔离演示，刷新重置；不能据此认定远程保存已生效。
+
+## 已验证与边界
+
+- 79 项前端测试通过，类型检查、H5/微信构建与 13 个文件的原生 WXSS 检查通过；其中头像入口测试验证微信端直接绑定官方选择器、无自定义菜单，以及 H5 的相册入口保留。
+- 后端 12 项 H2/MockMvc 测试通过，验证资料落库、回显、再次登录、非法历法拒绝、头像不受影响；1 项真实 MySQL 测试未配置专用测试库而跳过，没有写远程库。
+- 浏览器实测首页头像跳转、农历闰月确认、隔离演示保存与再次编辑回显，以及注册场景共用选择器。
+- 截图：`/private/tmp/hera-birthday-lunar-edit.png`。
+- 微信官方选择器的外观、取消/安全审核分支需微信开发者工具与真机验收；H5 不模拟成真实微信授权。

docs/incense-sound.md

@@ -0,0 +1,51 @@
+# 敬神：音频与真实供奉接口
+
+## 本期规则
+
+- 不提供功德、爱心、钱包、捐款、充值入口，不累计功德。服务端拒绝 offeringType=4 或任何非空 meritValue。历史列和流水保留，不删数据。
+- 喇叭默认开启，偏好仅保存在本机。关闭立即静音，音频以音量0继续推进；重新开启只恢复当前实际进度的声音，不暂停、不重头、不补播。最初静音上香也从首轮开始推进，音频已经结束则开启不再出声；追加上香延长点亮，不延长音频。
+- 每次上香独立提交。只有服务端返回有效记录 ID 后，次数才+1；请求失败不计数、不播音、不自动重试。网络结果不明时应刷新核对，避免手动重试重复记账。
+- 点亮截止时间为最后一次成功请求对应的点击时间+15秒（不从回包开始重计）。持续点击仅增加次数、延长点亮，不重播；音频自然结束不循环。点亮到期即停止声音、恢复供桌，不回退次数。
+- 页面隐藏/离开销毁音频。返回只恢复剩余点亮，不自动播放。播放错误提示用户，但不撤销已落库记录。
+- 祈愿最多500字；回向任意姓名最多50字＋祝愿最多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: 2}` 上香；type=3＋`content` 祈愿。返回流水及id。 |
+| POST `/api/user/virtual-items/dedications`（新增） | `{userVirtualItemId: 本人holdingId, name, content}` 任意姓名回向。返回流水及id。接收人ID为空，不创建账号、不转移资产。 |
+
+前端调用：`src/services/tiangong.ts`；状态管理：`src/utils/tiangongStore.ts`。使用服务端持有ID，不猜测数字ID。原型与字典名称精确匹配（财神／武财神、禄星、寿星、文昌星、月老），未配置者禁用，不假装已恭请。账号变更清空缓存，旧响应不能写入新账号。
+
+真实 NFC 绑定、解绑、送神不属于本次三项写接口；正式模式不执行本地 Mock 绑定，也不展示示例额度或虚构成功。已有绑定可正常供奉。此前拟定 NFC 契约仍未调用。
+
+## 部署边界
+
+**前后端代码推送不等于部署：本次未部署远程后端、未操作远程数据库。**
+
+部署后端前执行 `hera/src/main/resources/db/named-dedication-update.sql`，仅将 `user_virtual_item_transfer.to_user_id` 改为可空，保留数据。`CREATE TABLE IF NOT EXISTS` 不会更新现存表，不能省略。前端构建不能代替后端部署。此前生日偏好迁移也需按对应文档执行。
+
+远端无新接口/新表结构时，正式页面提示加载或提交失败，不以 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=2请求，成功才次数+1、点亮。10秒再点一次，再+1；音频不重播，第二次点击15秒后恢复。
+3. 上香第3秒关闭喇叭，立即无声；第10秒开启，应听到第10秒处剩余音频，不从第3秒接续，次数不变。第15秒音频结束后开启不得再播；第10秒追加上香使供桌仍亮时，也不得重播已结束音频。初始静音上香同样验证。
+4. 祈愿输入内容→确认，type=3成功显示“祈愿已记录”。回向输入任意姓名＋祝愿→确认，dedications成功显示“回向已记录”；数据库to_user_id为空，姓名祝愿保留。
+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`。未以浏览器检查替代真机听感和远端联调。

docs/tiangong-login-access.md

@@ -0,0 +1,47 @@
+# 天宫登录访问限制
+
+## 行为
+
+- 真实模式没有登录 token：点击中间天宫入口直接发起微信登录，不切换到神仙内容、不堆叠重复登录。首页、我的与天宫直达路由共用同一套登录提示卡片。
+- 直接打开天宫或敬神/请神详情页：没有权限时只显示登录提示和返回首页入口，不挂载神仙列表、神像场景或业务弹窗。直接进入不强制反复跳转，避免用户按返回键陷入循环。
+- 有 token：同一 token 的资料缓存仍在 30 秒有效期内时直接挂载内容，不先切为 checking，不重复请求资料；没有有效缓存才通过共享资料接口确认。401 清除登录后隐藏内容；网络错误显示重试，不当成登录成功，也不随意删除仍有效的 token。
+- 页面隐藏不再重置可复用的已验证状态；重新显示时检查有效期。隐藏或卸载后的旧异步结果不恢复页面权限，切换账号不能沿用另一个 token 的 allowed 状态。注册未完成、仅取得微信临时会话而尚无登录 token，也不能进入天宫。
+- 必要的异步校验使用天宫轻量场景占位和可用的返回入口，不显示“正在确认登录状态”的整页卡片，不提前挂载神仙资料或业务按钮。
+- 现有 `preview=1` 和 `avatarDemo=1` 仅在 H5 的明确演示环境保留访问，仍沿用隔离 Mock，不创建真实身份、不调用真实天宫写接口；微信端不启用这些查询参数。
+- 登录/注册成功后的落点继续沿用我的/完善资料页，没有增加未约定的返回天宫逻辑。用户随后点击天宫即可进入。
+
+## 接口边界
+
+不新增 REST 接口。复用已存在且需要 Bearer token 的 GET `/api/user/profile` 校验，基址按部署配置默认使用 `http://101.43.139.56/hera`。本次没有把天宫 Mock 接口改成真实后端，也不以界面守卫代替服务端鉴权。
+
+## 验收
+
+1. 在微信开发者工具以未登录状态进入首页或我的，点击登录/注册或天宫入口：直接调用微信登录；不能看到任何神仙，连续点击不重复发起登录。
+2. 未登录直达 `pages/fortune/index` 或 `pages/tiangong-detail/index?id=wealth`：只出现登录提示，不能操作恭请、上香、祈愿或其他业务按钮。
+3. 正常完成登录/注册，重新点击天宫：资料校验通过后可进入；首页、我的的导航不受影响。
+4. 登录过期返回 401 后：天宫和详情内容隐藏，重新登录后恢复。断网导致校验失败：显示重新加载和返回首页，不展示旧内容。
+5. H5 普通地址不带演示参数时执行同样拦截；H5 点击登录只提示在微信环境完成，不伪造 code、不再打开“那吉”品牌中间页。明确的演示 URL 保留原型预览。
+
+自动测试覆盖导航拦截、重复点击、登录失败重试、无 token 不请求资料、真实会话校验、401、网络错误、隐藏/卸载后的异步失效，以及直达页面不挂载业务内容。
+
+## 本次验证
+
+- 全量前端测试 83 项通过，TypeScript 检查、H5 构建、微信小程序构建通过；13 个 WXSS 文件通过微信原生编译器检查。
+- 浏览器实测：未登录首页和我的显示相同卡片，H5 登录入口不再跳品牌页；冷启动天宫列表和详情路由仅展示登录提示；独立头像演示模式仍展示隔离 Mock。
+- 小屏视口下检查统一登录提示、操作按钮与底部导航，无遮挡。截图保存在 `/private/tmp/hera-unified-login.png`。
+- 未在浏览器伪造微信登录，也未验证真实微信授权流程；有效会话和过期会话分支由自动测试覆盖。本次未修改后端、未提交或推送代码。
+
+## 锁定页与精简登录流程
+
+- 未绑定任意神仙时，首页和我的元素报告使用固定高度的锁定首屏，裁切长报告并拦截触摸滚动。绑定弹窗、返回、底部导航仍可操作；绑定后移除限制，恢复报告滚动。
+- 微信入口直接执行 `wx.login` 和 POST `/api/auth/wx-login`。已注册的响应直接沿用原有登录成功落点；未绑定手机号的响应仅把临时会话保留在内存，再进入必要的手机号表单，不放入 URL 或持久存储。
+- 手机号验证仍使用 POST `/api/auth/sms` 与 POST `/api/auth/bind-phone`。品牌名称、“一触即吉”和二次微信登录点击已从正常入口流程移除，不绕过后端注册和手机号验证。
+- 微信开发者工具验收：未绑定时在首页和“我的→我的元素”上下滑动，页面不位移；点击绑定/取消仍有效，绑定一个神仙后可正常滚动。分别从三个入口登录，已注册用户不再看到品牌中间页，新用户才显示手机号与验证码表单。
+- 浏览器已用隔离 Mock 验证解绑→锁定→绑定→恢复滚动；没有操作真实绑定或真实短信。截图：`/private/tmp/hera-locked-home.png`、`/private/tmp/hera-unified-login.png`。
+
+## 详情页无登录检查闪屏
+
+- 微信开发者工具登录后进入天宫，再点财神详情、返回、再次进入：资料缓存有效时应直接看到详情，不出现登录检查页。
+- 超过资料缓存有效期、冷启动只有 token 时，仍先校验，使用轻量占位；401 应显示登录入口，断网应显示重试，不能展示未验证的内容。
+- 自动测试覆盖有效缓存首帧允许且不发请求、隐藏/返回不闪检查态、缓存过期必须重新验证、切换账号/退出不能复用旧状态、轻量占位不渲染登录检查卡片。
+- 浏览器已验证隔离 Mock 中详情进入和返回，以及真实未登录直达详情仍被拦截；未伪造登录凭证。真实会话缓存/延迟分支通过自动测试验证，仍需微信端实际网络环境验收。截图：`/private/tmp/hera-tiangong-smooth-detail.png`。