|
|
一个 **线上数字供灯 + 线下寺院/宫庙供灯履约** 的一体化平台
# 功能说明书(WishSpace · 心愿里)
> 版本:V3.5 | 更新:2026-11-21 | 适用代码:`main` 分支当前提交
>
> 本文说明平台**已实现并可验收**的功能,按「使用角色 → 业务域 → 功能点」组织。
> 未实现或受限的部分集中列在第 9 节,避免把规划当能力对外承诺。
---
## 1. 产品定位
WishSpace(中文名「心愿里」)是一个 **线上数字供灯 + 线下寺院/宫庙供灯履约** 的一体化平台。
- **线上**:在 3D 寺院场景里选灯位、点灯、写心愿,灯在场景中真实亮起,心愿进入心愿墙。
- **线下**:浏览真实地点与服务,按时段预约下单,由平台合作方到场执行,上传凭证、平台审核、完成结算。
- **平台侧**:内容审核、派单调度、履约监督、凭证审核、退款投诉、财务结算、用户与权限一整套运营后台。
- **虚拟货币**:内置金币(默认名「福缘」),可充值、可直接抵扣订单金额。
一句话概括:**把"许愿"这件很轻的事,做成一条可下单、可履约、可追溯、可结算的完整链路。**
---
## 2. 角色与入口
| 角色 | 入口 | 说明 |
|---|---|---|
| 游客 | `/`(无需登录) | 可浏览首页、3D 场景(匿名身份)、心愿墙、地点列表;自动获得二字昵称 |
| 普通用户 | `/login` | 点灯、许愿、下单、支付、充值、退款、投诉、查看订单与灯 |
| 合作方(寺院/服务商) | `/provider/login` | 接单、执行、上传凭证、查看结算与统计 |
| 平台运营/审核/财务/客服 | `/admin/login` | 按权限点使用后台各模块 |
**一人多角色的边界**:权限按 `RBAC + 数据范围` 控制。平台级角色看全量数据;`location_admin` 只看被授权地点;`provider_admin` / `executor` 只看本合作方数据(由 `provider_id` 收口,不靠前端隐藏)。
---
## 3. 用户端功能
### 3.1 首页与导航
| 功能 | 说明 |
|---|---|
| 首屏引导 | 3D 场景作背景,主打文案「让每一份心愿,都有一个温暖的地方」,主按钮「静静走进去」 |
| 快捷入口 | 心愿墙、线下道场、我的祈福、登录/注册 |
| 游客身份 | 未登录自动分配二字昵称并签发 12 小时票据,可进多人场景 |
| 站点信息 | 站点名、公告、客服联系方式由后台配置下发(`/sys/config/public`) |
### 3.2 3D 点灯场景
| 功能 | 说明 |
|---|---|
| 五院场景 | 中院(大雄宝殿)、前院、东院(观音殿)、西院(地藏殿)、塔院(石塔 + 藏经阁),可行走约 1074 ㎡ |
| 第三人称漫游 | 键鼠/触屏移动,滚轮缩放(与转向分离),相机跟随并做遮挡回缩,不穿墙 |
| 殿宇可进入 | 四座殿可从明间走入拜佛,台基/踏跺为可站立面,角色逐级抬升 |
| 灯位点亮 | 180 个灯位,点击空灯位进入点灯面板;点亮后灯盏抬升 0.24m、坐在铜灯钩顶端,与未点亮的小灯位明显不同 |
| 灯上信息 | 灯上只展示点灯人的**会员昵称**(悬停见气泡);牌位称谓、心愿、点亮与到期时间仅灯主本人可见 |
| 灯型选择 | 不同灯型对应不同外观与金币价,价目由后台配置 |
| 心愿填写 | 点灯时写心愿(内容、分类、公开/私密、是否匿名),提交后进入审核 |
| 动作与音效 | 合掌、礼佛、木鱼、念珠、静坐 5 种动作,配套循环音;起身自动停音 |
| 环境音 | 夜风 + 细雨 + 远处钟声,全部 Web Audio 程序合成(无音频素材);音量压在背景乐之下,首次交互解锁,右上角「音」可静音 |
| 背景乐 | 空灵静谧:D 宫五声随机游走 + 拨弦/颂钵 + 卷积混响,同样零素材;随环境音一起开关 |
| 在场感 | WebSocket 实时同步同场景其他用户的昵称、造型、位置与动作;顶栏显示在场人数 |
| 小地图 | 院落矩形 + 连廊条带,点击院落按路点距离决定"走过去"还是"传送" |
| 真实天气 | 后院外的天色跟随灯院所在地(默认杭州)的真实天气:晴为月夜星空、阴为灰云、雨雪则落下雨丝/雪花;顶栏显示「晴 14°」这样的实时天气标签 |
| 画质三档 | 高/中/低手动切换;帧率持续偏低自动降档并提示,避免卡死(低画质关闭雨雪粒子) |
| 降级兜底 | 无 WebGL / 上下文丢失 / 模型 404 时切 2D 网格视图,功能不中断 |
| 软广告位 | 右上角「福运盘」跳转外部站点,纯 DOM 实现,不占 3D 绘制开销 |
### 3.3 心愿墙
| 功能 | 说明 |
|---|---|
| 公开心愿流 | 仅展示审核通过的公开心愿,支持分页与分类 |
| 心愿详情 | 心愿内容、点灯人昵称(匿名则隐藏)、灯型、时间 |
| 点赞 | 登录用户可点赞/取消,计数实时更新,重复点赞幂等 |
| 我的还愿 | 「我的 → 心愿」查看自己提交的心愿及审核状态,可编辑/删除未审核项 |
| 内容安全 | 提交即进审核队列;敏感词与联系方式在广播/展示前再过一道闸门 |
### 3.4 线上点灯下单与支付
**主流程**
```
选场景 → 选灯位 → 选灯型 → 写心愿 → 提交订单 → 支付 → 心愿审核 → 点灯生效
```
| 环节 | 规则 |
|---|---|
| 灯位占用 | 一个灯位同一时间只能有一盏有效灯,重复下单返回「该灯位已被点亮」 |
| 订单有效期 | 默认 15 分钟(`ORDER_EXPIRE`),超时自动关单并释放灯位 |
| 下单频控 | 默认 10 分钟 5 单(`ORDER_RATE_WINDOW` / `ORDER_RATE_LIMIT`) |
| 支付方式 | ① 金币全额抵扣 ② 第三方渠道(沙箱/微信/支付宝,按部署配置) |
| 支付幂等 | 同一订单重复支付不会重复扣款;回调重复投递只入账一次 |
| 取消 | 待支付可取消;已支付需走退款流程 |
**金币支付**:服务端按后台汇率把订单金额(分)换算成金币数,前端只展示不换算。余额不足返回 `42207`,订单保持待支付。扣币与订单落账在同一业务流程内完成,落账失败自动退回金币。
**点灯只显示金币**:选灯型的价目、面板底部「应付」、支付页主价签一律用后台配置的币名(默认「福缘」),
人民币只出现在金币充值页。库里的 `price_amount`(分)保留用于对账与退款,不在点灯链路上露出。
钱包未配置(`coins` 缺失)时才回退显示人民币,避免出现「0 福缘」这种坏文案。
### 3.5 线下供灯预约
| 功能 | 说明 |
|---|---|
| 地点列表 | 按地区、服务类型筛选,展示封面、起价、距离/评分等 |
| 地点详情 | 图文介绍、可提供的服务、价格、可选时段、须知、地图位置 |
| 服务选择 | 同一地点多种服务(如供灯、祈福法会、代供花果),各自价格与时长 |
| 时段与容量 | 按排班生成时段,每时段有容量上限;**下单锁量,先到先得,不超卖** |
| 下单 | 10 项校验(地点状态、服务可售、时段余量、限购、金额、实名信息等)+ 5 份快照(价格/服务/地点/时段/联系人) |
| 订单查询 | 「我的 → 订单」查看状态、进度、凭证、退款入口 |
| 退款申请 | 服务完成后 7 天内可申请(`REFUND_AFTER_SALE`),按状态与规则校验 |
| 投诉 | 对订单提交投诉,进入客服处理队列 |
| 通知 | 支付成功、派单、开始服务、完成、退款结果等节点站内通知 |
### 3.6 我的(个人中心)
| 功能 | 说明 |
|---|---|
| 资料 | 昵称、头像、性别、生日、手机号/邮箱(脱敏展示) |
| 昵称 | 注册后沿用游客昵称;可改名,全局唯一,撞名返回 `42201` |
| 虚拟形象 | 选择造型(发型/服饰/配色等白名单字段),场景内同步展示 |
| 我的灯 | 线上已点亮的灯,可回场景查看 |
| 我的订单 | 线上/线下订单统一列表与详情 |
| 我的福缘 | 余额、充值、充值记录、收支明细 |
| 通知 | 站内消息列表、未读数、标记已读 |
| 协议与隐私 | 查看用户协议/隐私政策/退款规则;查看本人同意记录 |
| 账号安全 | 改密码、退出登录、注销账号(软删 + 合规保留) |
| 举报 | 对违规内容/用户提交举报 |
### 3.7 金币(福缘)与充值
| 功能 | 说明 |
|---|---|
| 币名 | 默认「福缘」,**后台可改**,改后用户端文案同步 |
| 汇率 | 默认 1 元 = 1 福缘,可配置;不足 1 个按 1 个计 |
| 充值金额 | 最低 **5 元**,单笔上限可配;提供预设金额与自定义输入 |
| 收款方式 A | **上传收款码**:展示后台配置的收款码图片,用户扫码转账后上传付款截图,后台人工确认到账 |
| 收款方式 B | **支付宝**:RSA2 签名,PC 跳转 `page.pay`、移动跳转 `wap.pay`,异步通知验签后自动到账 |
| 收款方式 C | **微信支付**:APIv3 H5 下单,平台证书验签 + APIv3 密钥解密后自动到账 |
| 收款方式 D | **沙箱**:仅联调环境,下单后可点「模拟支付」 |
| 渠道选择 | **管理后台四选一**,服务端只听配置;前端传渠道或改金额均无效 |
| 到账体验 | 扫码方式提交凭证后轮询订单状态,确认到账自动刷新余额;渠道支付回跳后自动查单 |
| 充值记录 | 单号、金额、到账金币、渠道、状态、时间、备注 |
| 收支明细 | 每笔变动记录方向(收入/支出)、业务类型、关联单号、变动后余额 |
| 每日签到 | 每天一次,奖励 1 个金币;3D 场景顶栏「签」与「我的」页签到卡两个入口,显示连续 / 本月 / 累计天数与本月日历,重复签到返回 42201 |
| 状态机 | `pending`(待支付/待确认)→ `paid`(已到账)/`closed`(超时关闭)/`rejected`(驳回) |
**安全约定**:支付密钥加密存储、后台只回显打码值;保存时留空或含 `****` 表示不修改。收款码公开可读,转账凭证私有(仅本人与有权限的运营可见)。
---
## 4. 合作方工作台
| 模块 | 功能 |
|---|---|
| 工作台 | 待接单/进行中/待上传凭证/今日完成等概览 |
| 任务列表 | 按状态筛选,展示服务、时段、地点、联系人(脱敏) |
| 接单/拒单 | 接单后进入执行;拒单累计达上限(默认 3 次)自动改派 |
| 开始服务 | 到达现场后开始,记录开始时间 |
| 上传凭证 | 服务过程照片/视频(单任务上限默认 9 个),支持删除重传 |
| 完成任务 | 提交后进入平台审核;异常情况可标记执行异常 |
| 结算单 | 查看周期结算金额、明细、状态 |
| 人员管理 | 查看本合作方员工与角色 |
| 统计 | 完成量、准时率、评分等经营数据 |
| 资质维护 | 上传营业执照/宗教活动场所登记证等,等待平台审核 |
---
## 5. 平台管理后台
后台共 17 个模块,菜单按权限点动态显示。
### 5.1 数据看板
今日订单、本月 GMV、累计订单、待处理任务、心愿总数/待审/点亮中、线上 GMV、订单状态分布、近 7 日趋势、平台概览(注册用户、线下/线上订单、GMV)、功能开关快捷入口。
### 5.2 线上运营
| 模块 | 功能 |
|---|---|
| 心愿审核 | 列表筛选、查看详情、通过/驳回(填理由)、批量处理 |
| 场景与 3D | 场景列表与详情、灯位与灯型配置、场景对象坐标维护、模型与光照参数(`config` JSON) |
| 灯型管理 | 名称、价格、外观、上下架 |
| 活动管理 | 法会/主题活动的内容、时间、参与方式 |
| 线上订单 | 查询、详情、状态、退款入口 |
| 线上统计 | 订单量、GMV、灯位使用率、心愿审核效率 |
### 5.3 线下运营
| 模块 | 功能 |
|---|---|
| 合作方管理 | 入驻、资料、资质文档审核、暂停/终止合作 |
| 道场管理 | 新建/编辑地点、提交审核、审核、发布、下架;地址与图文 |
| 服务与价格 | 服务类型、产品、地点服务、价格、排班、容量生成 |
| 订单管理 | 全量订单查询、详情、取消、备注、强制改状态(留审计) |
| 任务履约 | 任务列表/详情、人工派单、改派、超时监控 |
| 凭证审核 | 查看凭证、通过/驳回、要求重传 |
| 退款处理 | 退款申请列表、审核、驳回、打款 |
| 投诉处理 | 投诉工单、回复、升级、结案 |
| 结算管理 | 按周期生成结算单、审核、标记打款、查看明细 |
| 功能开关 | `feature.offline`、`feature.offline.pay`、`feature.online`、`feature.wish.wall` 四个对外开关 |
### 5.4 用户与平台
| 模块 | 功能 |
|---|---|
| 用户管理 | 查询、详情、启用/禁用、分配角色 |
| 角色与权限 | 角色列表、新建角色、配置权限点 |
| 举报处理 | 举报列表、处置、留痕 |
| 审计日志 | 后台关键操作全量记录(谁、何时、对什么、做了什么、原因) |
| 系统设置 | 站点信息、业务参数、协议版本等键值配置 |
| 充值管理 | 待确认/已到账/已驳回筛选、看凭证、确认到账、驳回、关闭超时单 |
| 金币设置 | 币名、汇率、金额区间、预设金额、订单有效期、收款方式与参数 |
---
## 6. 关键状态机
### 6.1 线下订单(`offline_orders.order_status`)
```
pending_payment ──支付成功──> paid ──> pending_assignment ──> assigned ──> accepted
│
▼
completed <── pending_review <── pending_evidence <── in_progress ─┘
任意履约阶段 ──> refund_pending ──> refunded
异常分支:execution_exception(执行异常)、manual_review(人工介入)、cancelled(已取消)
```
- 迁移由 `orderTransitions` 白名单驱动,非法跃迁一律 `409`,不存在"无条件 UPDATE"。
- 每次迁移写 `offline_order_status_logs`(from/to/操作者/原因),可完整回放。
### 6.2 线上订单
`pending_payment` → `paid` →(心愿审核通过)→ 灯 `active`;待支付可 `cancelled`。
### 6.3 充值单
`pending` → `paid` | `closed`(超时)| `rejected`(驳回);只有 `pending` 能被改变,重复审核返回 `409`。
---
## 7. 权限模型
### 7.1 内置角色(种子数据,可再扩展)
| 角色 | 范围 | 主要权限 |
|---|---|---|
| `super_admin` 超级管理员 | 平台 | 全部 |
| `online_ops` 线上运营 | 平台 | 场景、心愿、活动、线上订单、充值查看 |
| `offline_ops` 线下运营 | 平台 | 合作方、地点、服务、订单、履约、凭证、充值审核 |
| `location_admin` 地点管理员 | 地点 | 仅被授权地点的服务与容量 |
| `provider_admin` 合作方管理员 | 合作方 | 本合作方任务、人员、结算 |
| `finance` 财务 | 平台 | 退款、结算、调账、收款配置 |
| `reviewer` 审核员 | 平台 | 心愿、地点、凭证审核 |
| `executor` 执行人员 | 合作方 | 接单、上传凭证 |
| `support` 客服 | 平台 | 举报、投诉、退款查看 |
| `user` 普通用户 | — | 用户端默认角色 |
### 7.2 鉴权实现
- 登录签发 JWT(access 2h / refresh 30 天),前端 401 自动刷新并重试一次。
- 接口级 `RequirePerm("xxx.yyy.zzz")`,权限点与菜单同源,前端隐藏只是体验,后端才是闸门。
- 数据范围在 SQL 层收口(`provider_id` / `location_id`),越权访问返回 403 而非空列表。
---
## 8. 平台工程能力(非界面功能)
| 能力 | 说明 |
|---|---|
| 统一响应 | `{code,message,data,request_id}`;分页固定 `{list,total,page,page_size}` |
| 幂等 | 写请求支持 `Idempotency-Key`,重复请求回放首次响应(4xx 不缓存) |
| 金额精度 | 全链路以「分」为整数存储与传输,禁止浮点 |
| ID | 雪花 ID,字符串传输,避免 JS 精度丢失 |
| 事件驱动 | Outbox 表 + worker 消费,支付成功→建任务→自动派单等异步动作不丢 |
| 定时任务 | 超时关单、容量生成、自动派单、结算生成、充值单过期等,靠 KV 锁多实例互斥 |
| 限流 | 全局/写/登录/WS 建连四级,按 IP 与用户维度 |
| 文件 | 本地或 S3 兼容存储,预签名直传,公开/私有用途白名单 |
| 审计 | 后台敏感操作全量留痕,日志可归档 6 个月 |
| 可观测 | `/healthz`、`/readyz`、结构化 JSON 日志、请求 ID 贯穿 |
| 3D 资产 | 模型、灯位、导航数据由同一脚本生成,保证"模型里灯在哪"与"库里灯在哪"一致 |
---
## 9. 已知边界与限制
| 项 | 现状 | 影响 |
|---|---|---|
| 混合支付 | 不支持 | 金币要么全额抵扣,要么走第三方渠道,不能"金币 + 现金" |
| 金币退款 | 财务后台调账 | 金币支付订单退款未自动退币,需人工处理 |
| 扫码充值 | 人工确认 | 依赖运营在后台核对付款截图,非实时到账 |
| 真实支付渠道 | 需自备商户号 | 支付宝/微信参数需在后台配置,未配置时对应方式显示「缺参数」 |
| 3D 美术 | 程序化占位模型 | 已可替换正式 GLB,视觉精细度取决于美术交付 |
| 殿内相机 | 贴墙会拉近 | 4~5 m 进深空间内视角受限,过近时隐藏角色 |
| 昵称池 | 24,000 个 | 用尽后游客无法再自动分配,需扩字池 |
| 微信生态 | 未做小程序/公众号登录 | 目前为 H5 + 账号密码/验证码登录 |
| 多语言 | 仅简体中文 | 无 i18n 框架 |
| 消息通道 | 站内通知 | 未接短信/模板消息/邮件通道(可扩展) |
---
## 10. 版本与验收
- 当前功能基线:`docs/TEST-REPORT.md` §4(含逐项验收记录与缺陷闭环)。
- 接口契约:`docs/openapi.yaml`(OpenAPI 3.0)。
- 数据库:61 张表,见 `docs/DATABASE.md`。
- 金币与充值专项:`docs/WALLET.md`。
- 3D 场景技术细节:`docs/3D-SCENE.md`。
|
|