feat: refine tiangong flows and integrate profile avatars

2026-10-17 22:44:09 +08:00
1 parent 4608dbd5cf
commit 5be2ca6b50
@@ -0,0 +1,84 @@
+# 1017 绑定 / 解绑页面交付
+
+## 已确认口径
+
+- 绑定就是恭请，两者共用状态；任意一位已绑定即可解锁首页、生肖周运和元素报告。
+- 卡片使用财神、禄星、寿星、文昌星、月老对应的现有原型图片，不使用“山鬼花钱”；界面统称“神仙”。
+- 每位神仙 Mock 初始剩余 2 次解绑机会，每次成功解绑减 1，取消不扣减，重新绑定不恢复额度。0 次时不可解绑，送神也不能绕过限制。
+- 仅做前端 Mock，未启动或修改后端，不申请 NFC 权限，不连接设备、不扣款、不绑定真实微信号。
+
+## 页面与入口
+
+1. “我的 → 我的天宫”按实际 Mock 绑定状态生成数量及神仙卡片。无绑定时显示空态和绑定入口；已绑定时点卡片打开详情，右上角“••• → 解绑神仙”打开二次确认。
+2. 解绑最后一位：首页摘要及维度区域模糊遮罩、元素报告模糊遮罩，显示“须绑定神仙 / 开启你的守护之旅 / 绑定神仙 / 联系我们”；生肖弹窗只显示生肖及绑定提示，不显示周运结果。
+3. 点击“绑定神仙”先打开明确标注的模拟 NFC 选择器，再打开对应神仙确认卡；关闭/取消均不绑定，点击“确认绑定”才修改 Mock 状态。确认后原页面即时解锁，不需要刷新。
+4. 天宫原有请神流程保留支架提醒和模拟等待，“模拟连接成功”后增加核对神仙的确认绑定卡；确认绑定后进入原有“请神成功 / 敬神”流程。
+5. 与之前的缓存 Tab 兼容，绑定、解绑、上香、重置会通知已挂载的页面，数量和门禁不会因页面缓存失去同步。
+
+## 验收步骤
+
+H5：`http://127.0.0.1:4173/?preview=1#/pages/my/index`。微信开发者工具重新编译项目 `dist` 目录后，从“我的”开始同样操作；真实资料读取仍需要原有后端及登录状态，H5 示例模式不需要后端。
+
+| 点击位置 | 期望结果 |
+| --- | --- |
+| 初次启动 → 我的 → 我的天宫 → 财神 | 初始绑定 1 位，显示财神、DEMO 唯一 ID、示例守护天数与更多按钮 |
+| 更多 → 解绑神仙 → 取消 → 再次打开 | 仍绑定财神，剩余次数仍为 2 |
+| 更多 → 解绑神仙 → 确定解绑 | 财神从“我的天宫”移除，数量变为 0，模拟提示成功 |
+| 首页 / 我的元素 / 我的生肖 | 分别显示首页遮罩、元素锁定遮罩、生肖绑定提示；不允许操作模糊区域的排序按钮 |
+| 元素锁定页 → 绑定神仙 → 财神 → 关闭卡片 | 仍锁定，不绑定、不扣次数 |
+| 绑定神仙 → 财神 → 确认绑定 | 元素报告即时解锁；首页、周运同步解锁；“我的天宫”恢复财神 |
+| 财神卡片 → 更多 → 解绑 | 剩余次数是 1；再次解绑后是 0 |
+| 再次绑定财神 → 更多 → 解绑 | 显示 0 次、禁用确认按钮并提示次数用尽；可取消或关闭 |
+| 天宫 → 财神 → 送神（0 次） | 同样禁止送神解绑，不存在另一入口绕过限制 |
+| 已有财神时，再绑定禄星 → 解绑禄星 | 数量先变 2 再变 1；首页仍解锁；财神额度不受影响 |
+| 天宫 → 未恭请神仙 → 恭请 → 请神 → 支架确认 → 模拟连接成功 | 出现对应神仙确认绑定卡，关闭不绑定；确认后成功进入敬神 |
+
+刷新网页/重启小程序会重置整个 Mock 会话（包括次数、绑定状态），不是生产系统的年度重置。也可用“天宫 → Mock 演示设置 → 重置全部演示”重置示例。
+
+## 与原型的差异 / Mock 边界
+
+- 依据文件夹里的 5 张截图实现。未提供独立金卡装饰、吊坠、飘带素材，金色边框/挂环使用 CSS 重建，没有把整张截图当可交互页面；神仙图片复用现有天宫原图，部分图片保留原图浅色底。
+- 按用户确认，金币“山鬼花钱”替换为对应神仙；保留现有“天宫”导航名称，不恢复截图中的“灵境”。
+- 真实碰一碰用显式的“Mock 模拟 NFC 识别”选择代替，展示 `DEMO-…-001` ID；一物一微信号、跨账号归属校验必须由后端完成，不能用本地状态代替。
+- 只演示解绑次数递减和禁用；真实年度计数、幂等、并发扣减、安全校验均未实现。守护天数及功德沿用现有示例，未擅自新增清零/返还规则。
+- “联系我们”沿用原有企业微信待配置提示，没有伪造客服接通。
+- 页面锁定是 Mock 的界面状态，不是服务端安全权限控制；正式上线必须在服务端控制报告访问与绑定归属。
+
+## 接口清单
+
+本次绑定/解绑/天宫操作均调用隔离的 `tiangongMock`，不发业务网络请求。真实接口仅预留于 `src/services/tiangong.ts` 的 `tiangongRemoteContract`，没有在页面调用。
+
+| 状态 | 方法 / 路径 | 用途 |
+| --- | --- | --- |
+| 既有；H5 preview 使用示例，不请求后端 | GET `/api/user/profile` | 首页及我的资料；资料修改/头像接口沿用，不在本次绑定流程调用 |
+| 既有前端路径，天宫本次不调用 | GET `/api/tiangong/items` | 神仙列表、绑定/恭请状态，供收藏与解锁状态使用 |
+| 既有前端路径，天宫本次不调用 | GET `/api/tiangong/items/{id}` | 神仙详情、介绍、统计 |
+| 拟定，待联调 | POST `/api/tiangong/items/{id}/invite` | 确认绑定/恭请；请求 `bindingId` |
+| 拟定，待联调 | GET `/api/tiangong/bindings/{bindingId}` | 绑定信息、唯一 ID、守护天数、剩余次数 |
+| 本次新增拟定契约，待确认 | POST `/api/tiangong/bindings/resolve` | 校验 NFC 凭证并返回待绑定信息；请求 `nfcCredential` |
+| 本次新增拟定契约，待确认 | POST `/api/tiangong/bindings/{bindingId}/unbind` | 原子解绑并返回剩余次数、是否仍有绑定神仙 |
+| 拟定，待联调 | POST `/api/tiangong/items/{id}/send-off` | 送神；应与解绑共享服务端额度和归属检查 |
+| 拟定，待联调 | POST `/api/tiangong/items/{id}/incense` | 上香 |
+| 拟定，待联调 | POST `/api/tiangong/items/{id}/wishes` | 祈愿，`text` |
+| 拟定，待联调 | POST `/api/tiangong/items/{id}/dedications` | 回向，`name`、`text` |
+| 拟定，待联调 | POST `/api/tiangong/items/{id}/offerings` | 爱心功德档位，`amount`；不是支付接口 |
+| 拟定，待联调 | GET `/api/tiangong/wallet` | 爱心余额 |
+
+绑定返回类型 `DeityBindingInfo`：`bindingId`、`deityId`、`uniqueId`、`bound`、`guardedDays`、`remainingUnbinds`。解绑返回 `UnbindResult`：`binding` 和 `hasAnyBoundDeity`。路径与字段均未假定已被后端实现。
+
+## 后续真实联调待确认
+
+1. NFC 标签内容、识别协议、微信端入口、服务端签名验证方式；已被他人绑定、凭证失效、设备不支持时的提示与恢复流程。
+2. 正式年度额度何时重置、按什么时区；解绑后守护天数、功德、上香记录如何保留或清零。当前仅沿用已有 Mock 记录，不自行设定新规则。
+3. 企业微信客服参数，以及绑定/解绑接口鉴权、幂等键、并发冲突与错误码。
+
+这些问题不阻碍当前已经确认的 Mock 演示，但正式接入前需要明确。
+
+## 验证记录
+
+- 41 项自动化测试通过，覆盖最后一位解绑重新锁定、任意绑定解锁、逐神仙额度、重绑不恢复次数、0 次时解绑/送神都被拒绝、订阅通知及原有首页/生肖/元素规则。
+- TypeScript 检查、H5 和微信小程序代码构建通过；仍有既有 vendor/chunk 体积提示，没有编译错误。未进行微信真机 NFC 或帧率验收。
+- 浏览器实际走通取消解绑、最后一位解绑、首页/生肖/元素锁定、元素页重绑即时解锁、天宫原有请神流程确认绑定、周运恢复、两位绑定的独立列表、单独解绑保留另一位、2→1→0 后重绑仍为0、解绑按钮置灰和送神入口同样禁用。
+- 浏览器 CSS 视口 320×448、340×531、432×932 检查卡片、确认弹窗、首页与元素遮罩，未见横向溢出；小屏卡片关闭按钮与确认/取消可见。已恢复临时视口设置。
+- 截图：`/private/tmp/hera-bind-confirm.png`、`/private/tmp/hera-binding-card.png`、`/private/tmp/hera-unbind-confirm.png`、`/private/tmp/hera-unbind-exhausted.png`、`/private/tmp/hera-home-unbound.png`、`/private/tmp/hera-element-unbound.png`、`/private/tmp/hera-zodiac-unbound.png`。
+- 未自动提交或推送代码；未启动或修改后端。