feat: refine tiangong flows and integrate profile avatars

docs/account-backend-integration.md

@@ -0,0 +1,66 @@
+# 注册、资料与头像后端联调
+
+## 本次接通范围
+
+- 微信登录 → 新用户绑定手机号 → 完善资料；已注册用户直接恢复后端账号。
+- 编辑页从后端回显，只有个人字段变更才提交资料更新。
+- 头像通过现有后端文件存储服务上传。首页左上角、我的、编辑页共用头像组件和资料状态，成功保存后同步更新。
+- 未填写生日、时辰、地区的新账号保持空值，不使用预览资料冒充真实账号。
+- 登录凭证失效后清除本地会话；失效头像链接通过资料接口刷新，不在前端签名 COS 文件。
+- 天宫绑定等已有隔离 Mock 未改成真实后端业务。本次没有提交或推送代码。
+
+## 本地入口与启动
+
+- 前端：`http://127.0.0.1:4173/#/pages/my/index`，真实模式不带 `preview=1`。
+- 后端：`http://127.0.0.1:8080`，已按用户授权使用现有本地配置启动。
+- `?preview=1` 保留只读样例，不保存资料、不上传头像、不调用注册接口。
+- `?avatarDemo=1` 为用户要求的 H5 已登录头像演示，可直接进入我的、选择本地图片并保存，首页/我的/编辑页同步；不创建登录 token，不请求后端或 COS，刷新后重置，不影响真实登录缓存。演示入口：`http://127.0.0.1:4173/?avatarDemo=1#/pages/my/index`。
+- 导入前端项目根目录的 `project.config.json`，小程序目录为 `dist/`。修改源码后运行 `npm run build:weapp`，H5 运行 `npm run build:h5`。
+- 构建前可设置 `HERA_API_BASE_URL`；真机的 `127.0.0.1` 指向手机本身，必须换成手机可访问的后端地址。
+- H5 不具备小程序 `wx.login` 能力，不使用伪造 code 或临时开发 JWT 绕过注册。首次真实登录请用微信开发者工具或微信。
+
+## 开发者工具验收
+
+1. 导入项目并编译。在“我的”或首页点“登录 / 注册”，执行微信登录。新微信用户应看到手机号、验证码输入；老用户应直接恢复对应账号。
+2. 新用户输入自己的手机号，点“获取验证码”。现有后端返回开发验证码，界面明确标记“非真实短信”；填入后绑定，进入“完善注册资料”。填写昵称、性别、生日、时辰、省市区并保存，应进入“我的”，再次进入编辑页数据应一致。
+3. 点我的头部进入编辑页，依次测试微信头像、相册、拍照；取消选择不提交。选择后仅本页预览，点保存才上传；保存成功后首页、我的、编辑页应显示同一张头像，重新编译/重进后仍由后端回显。
+4. 只修改头像：网络面板应出现 `POST /api/user/avatar`，不出现 `PUT /api/user/profile`，资料修改次数不减少。头像最大 5MB，格式限 JPG/PNG/WebP，服务端负责最终校验。
+5. 只修改个人字段：保存应出现一次资料 PUT。什么都不改直接保存不消耗次数。连续点击保存不能重复提交。
+6. 同时修改头像和资料：先上传头像再保存资料。上传失败时不得提交资料 PUT；若头像成功但资料失败，应明确提示部分成功，重试不重复上传已经保存的头像。
+7. 清除登录缓存或使用失效凭证，进入真实模式应提示登录，不展示其他账号或假样例。已登录头像加载失效时应向资料接口重新取链接；网络不可用时保留默认头像，不无限重试。
+8. 首页、我的及编辑页在窄屏、常见机型和底部安全区检查头像裁切、表单与导航；真机检查相册/相机权限、取消和失败提示。
+
+## 本次使用的全部账号接口
+
+统一业务响应为 `{ code, message, data }`，成功 `code=0`。资料与上传需要 `Authorization: Bearer <token>`；失效登录 HTTP 401。
+
+| 方法与路径 | 参数 | 返回及用途 |
+| --- | --- | --- |
+| POST `/api/auth/wx-login` | JSON `{code}`，由真实 `wx.login` 获取 | 新用户 `{sessionKey,phoneBound:false}`；老用户包含 `{phoneBound:true,token,user}` |
+| POST `/api/auth/sms` | JSON `{phone}` | `{mockCode}`，当前开发验证码，不是真实短信服务 |
+| POST `/api/auth/bind-phone` | JSON `{sessionKey,phone,captcha}` | `{token,user}`，建立/绑定正式账号后进入资料补全或我的 |
+| GET `/api/user/profile` | Bearer token | 完整资料，包含 `avatarUrl`、`remainingEdits`，供回显与头像链接续取 |
+| PUT `/api/user/profile` | JSON `{nickname,gender,birthday,birthHour,province,city,district}` | 完整资料；受现有后端半年 5 次限制，不附带头像字段 |
+| POST `/api/user/avatar` | Bearer token，multipart 字段 `file` | 完整资料；后端调用既有 COS 存储并关联账号，不消耗资料修改次数 |
+| GET `/file/access?token=…` | 后端返回的文件专用临时 token，由图片加载访问 | 302 跳转私有 COS 签名地址；不是登录 token，不在前端拼装签名 |
+
+接口均为现有真实接口，不是本次拟定的假接口。数据库保存 `cos://` 对象引用，前端只使用后端返回的访问 URL，不持久化临时签名为对象身份。
+
+## 已验证与边界
+
+- 前端自动测试 58 项通过（包含日主五行入口图标、隔离头像演示、编辑页样式作用域及 WXSS 兼容回归测试），TypeScript 检查、H5 和微信构建通过。13 个产物 WXSS 均通过本机微信开发者工具自带 `wcsc` 的原生编译检查；这不替代真实登录/上传验收。
+- 后端干净构建默认执行的 17 项单元/隔离测试通过：注册/资料/头像控制器链路、账号 CRUD、仅当前表启动、头像限额与格式、401、文件访问、COS 和 Redis 配置测试。4 项需要显式启用的外部集成测试在默认构建中跳过。业务写入测试使用隔离 H2，微信客户端及实际 COS 上传使用测试替身，不代表已向真实 COS 上传成功。另有 1 项当前配置数据库的只读 Mapper 集成检查通过，不读取真实账号记录或写入数据库。
+- 已运行的本地后端：无登录和无效凭证请求均返回 401；资料 PUT 跨域预检返回 200 并允许 Authorization、Content-Type。前端入口 HTTP 200。
+- 真实联调阶段浏览器验收曾被额度限制阻止；后续用户要求的 H5 已登录演示已在浏览器验证：从相册选择项目测试图片、保存、我的/首页/重新进入编辑页均成功加载同一本地头像。截图保存在 `/private/tmp/hera-avatar-demo-my.png`。这不是实际 COS 上传证据；真实微信授权、真实账号写入和实际 COS 上传/展示仍须完成上述开发者工具验收。
+- 本地 API 为 HTTP，现有文件公开入口也可能为 HTTP。上线和真机需确认 HTTPS、合法请求/上传/下载域名、图片重定向域名，以及文件入口和签发端使用一致的配置。不能仅凭后端启动成功认定真实文件入口已经可用。
+- 头像文件入口本地联调已修复：仅在后端被 Git 忽略的 `.hera-local.yml` 中将 `hera.cos.public-base-url` 覆盖为 `http://127.0.0.1:8080/file/` 并重启。使用用户本次报错对应的已有头像，只读验证本地入口返回 302、私有 COS HTTPS 图片读取返回 200；没有上传、删除文件或修改存储桶权限。远程 `101.43.139.56/file/access` 探测返回 COS 格式的 403 `AccessDenied`，远程反向代理配置未修改；上线需将文件网关请求转发后端签名入口，而非直接转发 COS 的 `/access` 对象路径。开发者工具重新编译/重进我的，以获取新头像 URL；手机真机不能使用电脑的 `127.0.0.1`。
+- 资料 PUT 与头像上传是两个独立接口，部分成功会明确告知，不宣称原子事务；网络超时后服务端是否已提交需重新读取确认，后端当前没有请求幂等键。
+- 修复“进入编辑页再返回，默认头像/我的元素变形”：H5 懒加载的编辑页 CSS 曾以全局 `.water-mascot` 覆盖我的页同名图标。编辑页样式现全部限定 `.edit-page`，并使用独立的 `edit-water-mascot` 类，避免双向样式冲突；不涉及头像数据或接口变更。
+- 根据用户确认的数据库结构，移除 `user_account.nfc_uid` 对应的实体字段、账号 Mapper 读写与新建表定义，不执行补列或删除数据库字段。`user_virtual_item` 中独立的绑定字段不在本次账号字段移除范围。已重新部署本地后端；实际微信登录仍需开发者工具重新获取 code，不能重放已使用的 code。
+- 按系统尚未上线、只采用当前表结构的要求，删除历史用户迁移源码及其测试，解除业务启动对迁移组件的依赖，不再自动补列、修改旧表或搬迁旧账号。保留首次注册和注册后再次登录的正常流程；数据库已有表与记录不删除。干净构建已确认产物没有旧迁移类，清理后的本地后端已重启。
+
+## 与原型差异及待确认
+
+- 保留原有页面视觉与头像选择入口。新增登录失效、资料加载失败、注册补全、上传错误和开发验证码的必要状态提示，不以样例资料掩盖失败。
+- 待确认上线短信供应商及验证码策略；现有开发验证码不能作为生产短信能力。
+- 待确认测试/生产 HTTPS API 和文件访问域名，真实微信账号与 COS 联调需用户在开发者工具授权验收。未改动生产域名或伪造注册凭证。

docs/deity-binding-delivery.md

@@ -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`。
+- 未自动提交或推送代码；未启动或修改后端。

docs/my-element-icon.md

@@ -0,0 +1,37 @@
+# 我的元素：按日主五行显示图标
+
+## 已确认口径
+
+入口复用当前元素报告的 `masterElement`，不按五行最高占比或喜用元素选择。
+
+| 日主天干 | 元素 | 图标 |
+| --- | --- | --- |
+| 甲、乙 | 木 | 绿色叶片 |
+| 丙、丁 | 火 | 橙色火焰 |
+| 戊、己 | 土 | 棕色石块 |
+| 庚、辛 | 金 | 金色圆币 |
+| 壬、癸 | 水 | 蓝色水滴 |
+
+保留“我的元素”标题和原有入口布局，图形加元素小标识；个人默认头像及上传头像不参与这套映射。
+资料缺失或不能计算有效报告时，显示中性问号，点开沿用原有完善出生信息提示，不虚构默认五行。
+
+## 更新与接口
+
+- 继续使用既有资料 GET `/api/user/profile` 提供的生日和出生时辰，在前端生成同一份报告。
+- 编辑资料保存仍使用 PUT `/api/user/profile`。保存回传资料通过现有订阅更新报告与入口图标，无需新接口。
+- 仅日主五行发生变化时图标才变化。同五行的不同生日，以及只改昵称、头像或其他非排盘字段，不要求更换图标。
+- 不修改后端报告、计算规则或个人头像；没有新增后端接口，也没有操作真实用户资料。
+
+## 验收
+
+1. 微信开发者工具重新编译，进入我的，查看元素入口图标。点开报告，确认图标与“日主”属性一致，而非最大百分比。
+2. 无需为测试消耗真实账号的半年修改额度。使用 H5 隔离演示入口 `http://127.0.0.1:4173/?avatarDemo=1#/pages/my/index` 验证修改联动。
+3. 演示时辰保持辰时，生日从 `1998-06-18` 起依次改为 `20`、`22`、`24`、`26` 日并保存，分别应显示火、土、金、水、木；默认头像保持不变。演示仅在本地保存，刷新重置。
+4. 进入编辑页后不修改直接返回，元素图标不应变形；入口图标与生肖图标保持对齐，底部导航不遮挡。
+
+## 已完成检查
+
+- 58 项前端测试、TypeScript 检查、H5／微信构建通过。
+- 13 个产物 WXSS 通过微信开发者工具自带编译器检查。
+- 浏览器隔离演示实际验证五个日期的保存切换，以及入口与日主详情一致、窄屏对齐；没有将模拟资料写入真实后端。
+- 截图：`/private/tmp/hera-day-master-fire.png`、`/private/tmp/hera-day-master-earth.png`、`/private/tmp/hera-day-master-metal.png`、`/private/tmp/hera-day-master-water.png`、`/private/tmp/hera-day-master-wood.png`。

docs/navigation-alignment-fix.md

@@ -0,0 +1,30 @@
+# 财神背景与主导航优化（2026-10-17）
+
+## 修改
+
+- 神像区独立使用等比云纹背景，不再把背景拉伸到供桌。H5 `aspectFit` 内部图片显式居中，长屏神像落在供桌上方。
+- 供桌使用固定比例裁切容器去掉素材白色侧边，未点香/已点香共用同一位置，切换时不移动。
+- 首页、天宫、我的均注册为真实 Tab，统一 `switchTab`，不再混用入栈和重定向。H5 隐藏框架自带栏并恢复完整高度，只展示现有自绘导航。
+- 页面实例保留，首页日期选择、我的生日显示状态不因切换重置；重复点击防止重入。
+- 资料增加 30 秒内存缓存与并发请求合并，过期后台刷新时保留快照，失败提示正在使用上次资料。账号隔离；资料/头像保存成功后用服务器返回值更新缓存，编辑页强制读取最新资料。
+
+## 验收
+
+H5 打开 `http://127.0.0.1:4173/?preview=1#/pages/fortune/index`。微信开发者工具重新编译 `dist` 后按相同步骤操作（真实资料需要已有后端与登录状态，本次不启动后端）。
+
+1. 天宫 → 财神：神像、香炉处于页面中轴；背景不横向拉伸，供桌两侧没有白色窄条。点击上香：供桌点亮但位置不跳动，五个按钮完整显示。
+2. 首页 → 选明日 → 天宫 → 我的 → 首页：仍选中明日；无重复导航，不反复出现整页资料加载占位。
+3. 我的 → 显示生日 → 天宫 → 我的：生日显示状态保留，点击开关不进入编辑页。
+4. 在真实联调环境保存生日/时辰后返回：首页、我的使用新资料重算；预览模式仍不保存，不假装保存成功。
+5. 小屏、长屏反复切换三个入口并返回详情：底部不被裁切，没有横向滚动；连续点击不叠加路由。
+
+## 边界与接口
+
+本次无新增业务接口，无后端修改。沿用 `GET /api/user/profile`、`PUT /api/user/profile`、`POST /api/user/avatar`，仅调整前端缓存；登录成功跳转同步改为 Tab 跳转。天宫仍是原有隔离 Mock，不扣款、不连接设备；未确认分支及拟定接口继续见 [天宫交付说明](./tiangong-delivery.md)。
+
+## 验证记录
+
+- 37 项自动化测试、TypeScript 检查、H5 与微信代码构建通过；仍存在既有 vendor/chunk 体积警告。
+- 浏览器确认三个 Tab 各保留一个 DOM 页面实例，隐藏页面不显示；首页“明日”、我的生日显示状态切回后保留，框架默认导航隐藏。
+- 340×531、320×568、432×932 CSS 视口检查财神，神像图像中轴与容器中轴一致，供桌切换前后同尺寸同位置，五个动作完整，没有横向溢出。
+- 不将浏览器验证与构建通过等同于微信真机验收；未做真机帧率测量，首次资源加载仍受设备与网络影响。

docs/tiangong-delivery.md

@@ -0,0 +1,97 @@
+# 天宫 Mock 原型交付
+
+本次来源：[墨刀 → 洪贞小程序 → 天宫](https://modao.cc/proto/yx6d0Jptt7nctvrsIevgd0/sharing?view_mode=read_only)。不使用“洪贞app”画布。
+
+## 入口与运行
+
+- 本地预览：[天宫](http://127.0.0.1:4173/?preview=1#/pages/fortune/index)。只能在运行预览服务的电脑上使用。
+- 微信开发者工具导入仓库根目录，`project.config.json` 指向 `dist/`。先运行小程序构建，再从首页或我的底部点“天宫”；也可设置编译启动页为 `pages/fortune/index`。
+- 天宫模块当前始终使用隔离 Mock 服务，不是请求后端失败后偷偷兜底；已有首页/个人资料接口不改变。
+- 初始：财神已恭请；其余四位未恭请。示例爱心 100；财神供奉 4 天、功德 99、上香 59 次。其余神仙初始统计为零，均为样例，非真实账户。
+- 状态仅保存在当前 JS 运行会话；同一会话内往返页面同步。刷新 H5、重启小程序或点“重置全部演示”恢复样例。愿望与姓名不上传、不持久化，提交后清空。
+
+## 验收步骤与预期
+
+| 操作 | 预期 |
+| --- | --- |
+| 首页/我的 → 底部天宫 | 三列五个原型图像卡片，暖白背景、浅绿名称条；底部首页/天宫/我的文字对齐、不裁切 |
+| 财神卡片 | 直接进入敬神；云纹背景、红衣财神、供桌和五个竖向按钮，不是整页截图 |
+| 上香 | 供桌出现水果、香，59 变 60；爱心和功德不擅自扣减/增加 |
+| 祈愿 → 空提交 | 显示非空提示，不提交；输入测试愿望后提交只显示 Mock 结果，无真实上传 |
+| 回向 | 显示当前神仙供奉天数、功德、次数；姓名/祝愿完整填写后可模拟提交；关闭或取消可回到详情 |
+| 功德 → 9/99/168 | 选中态、输入值同步。100 余额选择 168 → 余额不足；确定只解释充值未接入，不打开支付 |
+| 功德 → 9 → 确定 | 只显示模拟选择结果，余额仍为 100，不产生捐款或功德奖励 |
+| 功德 → 随机 | 显示随机区间待确认提示，不生成自创金额 |
+| 送神 → 取消 | 保留当前已恭请状态 |
+| 送神 → 确定 | 返回天宫，对应卡片转未恭请；其他神仙不变；保留演示历史统计，不假设清零规则 |
+| 禄星等未恭请卡片 | 卡片内出现“您还未恭请此神 / 是否恭请 / 恭请”，点 × 关闭；恭请进入对应请神页 |
+| 请神 → 确定 | 支架提醒 → 模拟等待；取消不改变恭请状态；无 NFC/蓝牙权限请求 |
+| 等待 → 模拟连接成功 | 成功弹窗 → 进入对应敬神；返回列表该神仙变彩色。不会把禄星错误显示为财神 |
+| 天宫 → Mock 演示设置 → 设为 0 | 未恭请神仙点请神可验收余额不足的演示路径；这不是定义了真实恭请价格 |
+| Mock 演示设置 → 重置全部演示 | 恢复初始卡片、100 爱心、59 上香次数 |
+| 直接打开详情且 id 无效 | 显示未找到并可返回，不默认冒充财神 |
+| 窄屏/矮屏、长回向表单 | 弹窗受视口和安全区约束，内容可滚动，按钮不裁切；底部导航/五个动作可操作 |
+
+## 与原型/逻辑的差异
+
+1. 加入明确 Mock 提示、返回/关闭入口、基本空值保护、操作结果说明及演示设置，仅为安全验收；真实生产文案可联调后收敛。
+2. 原型未恭请提示的卡片内样式已还原；供桌分层素材、上香图像切换、计数 +1、祈愿/回向/送神弹窗来自实际演示点击。
+3. 原型功德弹窗、两个余额不足弹窗、成功提示在总览可读。演示中点击顶部数字、香炉、可见功德热点均未能打开功德弹窗，因此本版新增明确“功德”入口使其可验收，不声称这一入口位置已经由原型跳转确认。
+4. 原型支架等待会自动推进/退出；本版改为明确“模拟连接成功”，可取消，不假装连接了设备。未接入 NFC、蓝牙、支架、支付、捐款、充值。
+5. 只有财神、禄星的独立详情神像可从当前画布读取。寿星/文昌星/月老使用各自列表原图并在请神页标明，不复用财神冒充；这三张完整详情神像仍待提供。
+6. 原型“禄星”介绍正文实际写“上清灵宝天尊”。原文保留并标记不一致，其他四位不自编介绍；神仙画像/名称口径待用户确认。
+7. 当前“善信缘主”用 You（示例），不把原型内王开运当作真实用户。天数、累计功德为演示数据，未定义真实计时与奖励算法。
+8. 无随机区间、请神价格、上香扣减和送神重置规则，因此不实现这些真实业务；只提供已知余额不足/成功的可控演示。
+9. 全部新图像来自墨刀当前已观察到的原始文件，在本地缩放压缩，不依赖运行时墨刀图床；未生成替代神像。
+
+## 全部接口清单
+
+实际页面仅调用 `services/tiangong.ts` 的 `listMockDeities`、`tiangongMock.snapshot/invite/incense/wish/dedicate/sendOff/offering/setDemoBalance/reset`，没有真实天宫网络请求。
+
+服务层保留了 `tiangongRemoteContract`，从未在页面调用；不是已上线或已联调的能力。沿用既有请求层的鉴权方式。以下 `id` 是神仙 id，`bindingId` 是未来设备绑定记录 id。
+
+| 状态 | 方法 | 路径 | 用途/请求字段 |
+| --- | --- | --- | --- |
+| 前端原已有，未验证后端 | GET | `/api/tiangong/items` | 神仙列表、原图及用户恭请状态 |
+| 前端原已有，未验证后端 | GET | `/api/tiangong/items/{id}` | 神仙详情、介绍与统计 |
+| 拟定，待确认 | POST | `/api/tiangong/items/{id}/invite` | 恭请，`bindingId` |
+| 拟定，待确认 | 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}/send-off` | 送神 |
+| 拟定，待确认 | POST | `/api/tiangong/items/{id}/offerings` | 爱心功德，`amount`，非真实支付接口 |
+| 拟定，待确认 | GET | `/api/tiangong/wallet` | 爱心余额 |
+| 拟定，待确认 | GET | `/api/tiangong/bindings/{bindingId}` | 读取绑定/连接状态，不代替真实硬件实现 |
+
+以上拟定路径、返回字段、幂等键、错误码、原子扣款和硬件授权协议都必须经后端确认；不新增猜测的充值接口。
+
+## 待确认问题
+
+2026-10-17 更新：绑定即恭请、每位初始 2 次解绑、重新绑定不恢复额度、0 次禁止解绑已由用户确认，并已补充到 Mock。绑定/解绑与门禁新说明以 [1017 交付](./deity-binding-delivery.md) 为准；以下保留原交付的其他待确认项。
+
+1. 禄星名称、详情画像与“灵宝天尊”正文应统一为哪一位？财神用“武财神”的原型称谓是否准确？请提供另外三位详情神像与五位正式介绍。
+2. 原型“功德”弹窗正式入口在哪里？是否保留当前显式入口？
+3. 恭请是否消耗爱心，各神价格是多少？上香频率、消耗、功德奖励如何计算？送神是否清零统计、解除支架绑定、需要二次验证？
+4. 随机爱心的范围、可用金额规则是什么？真实充值/捐款是否本期接入及其合规、支付流程是什么？
+5. 支架通过 NFC、蓝牙还是其他协议？超时/失败/重复绑定/取消应该如何处理？
+6. 祈愿和回向文本长度、是否必填、隐私存储、保留时长和审核规则是什么？目前仅做非空前端保护，不落库。
+
+## 素材记录
+
+导出工具为浏览器 pageAssets，原文件 `/uploads7/images/…`：
+
+- 五个列表图：`184914331/v2_tm2xlt.png`（财神）、`184914339/v2_tm2xnq.png`（禄星）、`184914344/v2_tm2xp4.png`（寿星）、`184914388/v2_tm2y7b.png`（文昌星）、`184914396/v2_tm2y9p.png`（月老）。
+- 详情神像：`184951976/v2_tm4prs.png`（财神）、`184951979/v2_tm4ps7.png`（禄星）。
+- 云纹：`184328087/v2_tlb2ag.png`；原始响应实际编码为 JPEG，已更正本地后缀。
+- 供桌：`184328109/v2_tlb2f3.jpg`，点香供桌：`184328108/v2_tlb2f2.jpg`。
+- `scripts/optimize-tiangong-assets.cjs` 仅作构建时缩放/压缩，保留神像透明度，需 sharp；不进行绘制或替换内容。
+
+## 验证记录
+
+- 32 项测试（包含 7 项新天宫测试）通过；TypeScript 检查通过。
+- H5 与微信小程序代码构建通过。打包成功不等于微信真机/上传审核通过，尚无微信开发者工具真机验收。
+- 新素材约 520 KB，小程序构建文件实际合计约 1.79 MB；构建仍有既有 vendor/chunk 性能提示，无编译错误。
+- 浏览器实际走通未恭请、模拟绑定、成功进入禄星详情、上香、祈愿空值/有效提交、回向有效提交、功德 168 余额不足、未接入充值说明、送神取消/确定和返回列表变灰。
+- 实测浏览器 CSS 视口 320×568、432×932 无横向溢出，导航文字/五个动作基线一致；320×448 的长回向弹窗受视口约束并可滚动取消。此项不代表所有微信真机已经验收。
+- 还验收了演示余额设为 0、寿星恭请余额不足路径；缺少独立神像/介绍时展示说明，不错误复用财神。
+- 不自动提交或推送代码，未启动后端。素材导出调用异常耗时，任务实际交付晚于计划时间。