#外部看板与 H5 技术设计

2026-10-14 核对：实现依据 spa-h5 当前源码及 README，本轮不证明线上发布状态。

#1. 项目定位

spa-h5 维护轻量对外页面，当前采用原生 HTML、CSS 和 JavaScript，构建时复制并校验静态资源，不包含独立后端。

生产构建内容发布到官网站点的 /docs/ 目录：

H5 页面只负责交互和展示，会员、预约、服务、订单、支付和推广数据均来自后端。

#2. 当前调用边界

规划文件将服务看板和团长经营台统一归为业务 API 使用方；当前代码实际调用 https://feilun.afuspa.com 的飞轮 API：

www.afuspa.com/docs/* 静态页面
  -> 浏览器跨域 fetch
  -> feilun.afuspa.com/api/*
  -> spa-feilun-backend:8088
  -> fuspa 数据库

因此飞轮后端的 CORS、账号体系、权限映射和可用性会直接影响两个外部看板。未来若迁移到 api.afuspa.com 或专用 BFF，必须保持数据范围、状态语义和错误码兼容。

#3. 通用前端结构

• API 基址由页面 data-api-base 提供，脚本不拼接服务器 IP；
• 登录调用 /api/auth/login，令牌保存在当前标签页的 sessionStorage；
• 请求使用 Authorization: Bearer <token>；
• 页面恢复时调用 /api/auth/me 重新验证令牌和权限；
• 401 清理会话并回登录页，403 保留会话并提示权限不足；
• 网络错误、业务错误和空数据分别展示，不用历史缓存伪装“最新数据”；
• 页面部署在官网域名，飞轮后端只允许显式配置的跨域来源。

使用 sessionStorage 可以降低公共终端关闭标签页后残留登录态的风险，但不能替代终端锁屏、账号最小授权和主动退出。

#4. 门店服务看板

#目标用户

店长、前台和恢复师，用于门店现场查看今日预约、待到店、待派工、服务中、待结算和异常情况。

#当前接口与刷新

#展示状态

看板将后端工作台数据转换为现场视图，重点覆盖：

• 待确认、即将到店和已到店待派工；
• 已派工、服务中和待结算；
• 恢复师、房间、项目和预约时间；
• 异常、延迟、资源冲突和同步失败提示。

页面显示的状态必须来自后端，不根据时间自行把预约推进到“已到店”或“已完成”。

#操作边界

当前看板以读取和展示为主。若增加确认、派工、换人、开始、完成或结算操作，应满足：

1. 每个动作调用现有履约状态机，而不是新增看板专用写表接口；
2. 携带版本号或条件，防止看板与店长工作台并发覆盖；
3. 重新校验 manager 权限和门店范围；
4. 记录操作者、终端、业务主键、前后状态、原因和 requestId；
5. 操作成功后重新读取服务端状态，不以本地更新作为最终结果。

#5. 团长经营台

#当前能力

• 团长档案、所属门店和推广码；
• 渠道服务单及到店/退款状态；
• 推广商品单、服务单和金额汇总；
• 推广客户数、活跃客户和消费汇总；
• 日期、状态、关键词筛选及分页；
• 每 60 秒刷新一次当前查询。

#当前权限

登录账号必须同时具有：

• service-orders:view
• manager:promotion-leaders:view

接口包括：

#归因与日期口径

• 服务单按创建时保存的 promotion_code 归因快照统计，不按之后的会员绑定关系反推；
• 渠道订单日期按支付时间计算；
• 推广业绩日期按订单实际发生时间计算；
• 退款中、已退款和净金额必须使用统一财务口径，不能只按订单当前状态粗略扣减。

#当前限制

当前页面固定使用渠道码 RELAX_CHANNEL 查找团长档案。这适合单一活动看板，但还不等于规划中的通用团长身份模型。

升级为通用团长经营台前需要：

1. 将中台账号、团长档案和可见 leaderId 建立明确绑定；
2. 后端从认证上下文推导可见团长，不接受前端任意指定其他团长；
3. 支持一人多渠道或一渠道多人时的业务规则；
4. 对手机号等敏感字段脱敏，导出和关键查询留审计；
5. 固化预计收益、确认收益、结算周期和异常调整的财务口径。

#6. 培训网页学习

学习页从小程序复制的一次性链接进入外部浏览器，60 秒内兑换一次独立网页会话，最长 2 小时且不超过原小程序登录有效期。兑换后立即从地址清除凭证，原小程序 token 不进入 URL 或网页存储。

认证教材及学习接口经站点根 /api/training-web/ 同源代理至小程序后端。后端重新校验有效员工、培训身份和范围；学员记录前台浏览和实际播放，老师/校长只读，不自动形成学分、考勤或通过结果。

前台按既有累计协议上报，拖动进度、后台及挂起不计观看，倍速按实际时间计量。断网显示未同步并在当前页面恢复后重试，强制关闭可能丢失最后未同步部分；退出清理网页身份并撤销会话。

页面、培训数据库迁移、共享核心、两个后端、同源代理和开关须配套。认证版通常不传 TRAINING_CATALOG；显式构建访客清单意味着静态教材可被访客读取，不能用网页登录宣称该 JSON 或既有 CDN 视频已私有化。

小程序图文页不内置 video/web-view 播放；网页视频存在性、格式兼容及 Android/iOS 真机播放单独验收。部署细节以 spa-h5 README 及 74N 实施记录为准。

#7. 协议页

协议页是公开静态内容，不调用业务 API。发布时应：

• 保持会员协议、用户协议和隐私政策链接稳定；
• 记录版本、生效时间和变更摘要；
• 小程序授权场景引用同一正式地址；
• 不在旧地址直接删除内容，通过兼容跳转保持历史版本可访问性；
• 涉及手机号、支付、画像、第三方共享和数据保留期限时同步法务/合规审核。

#8. 安全基线

1. 页面和 API 全部使用 HTTPS，并限制 connect-src 到必要域名。
2. H5 不内置账号、令牌、固定密码或后端管理密钥。
3. 看板账号按最小权限和门店范围配置，不共用超级管理员账号。
4. 公共大屏不得展示完整手机号、会员资产、服务隐私和财务敏感字段。
5. 页面退出、令牌失效和权限变更后立即停止刷新并清理会话。
6. 飞轮 CORS 只允许正式官网来源；临时测试域名通过环境配置显式加入并及时移除。
7. 若看板开放写操作，必须增加防重、并发版本、审计和错误恢复。

#9. 构建与验收

构建命令：

npm run build

构建脚本生成 dist 并验证必需文件，包含培训页面和教材结构校验。认证学习不依赖访客清单；测试命令与配置以仓库 README 为准。

发布验收：

• /docs/ 下各目录可直接访问和刷新；
• 桌面大屏、平板和移动端布局可用；
• 登录、退出、令牌过期、无权限和跨域失败有明确提示；
• 服务看板断网后保持错误态并继续按周期重试，不显示伪造新状态；
• 团长数据严格限制在授权范围，归因、日期、退款和金额口径与飞轮一致；
• Nginx 缓存策略保证 HTML 可及时更新，带版本的静态资源可以长缓存；
• 发布后检查浏览器控制台、API 错误率和飞轮后端日志。