98 lines
9.3 KiB
Markdown
98 lines
9.3 KiB
Markdown
# 天宫 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、寿星恭请余额不足路径；缺少独立神像/介绍时展示说明，不错误复用财神。
|
||
- 不自动提交或推送代码，未启动后端。素材导出调用异常耗时，任务实际交付晚于计划时间。
|