芙 SPA 文档中心
技术文档总体架构

总体架构

2026-10-14 核对：下文域名与端口为仓库部署约定，本轮未连接线上确认；当前实现已加入共享券/培训核心、独立分析服务和网页学习。

1. 架构目标

总体架构围绕“统一后端、角色复用、单一权威、可追溯运维”设计：

  • 顾客、店长、恢复师、团长和总部人员使用不同入口，但复用同一组核心业务事实；
  • 对外交易链路与总部管理链路分开部署，降低相互抢占资源和权限外溢的风险；
  • 飞轮中台负责管理、分析和任务编排，不重复制造小程序已经产生的交易事实；
  • 外部看板保持轻量，负责展示或触发受控操作，最终状态由后端校验；
  • 域名、ECS、RDS、OSS、证书和第三方费用可以映射到明确的系统责任。

2. 逻辑分层

层级组成核心责任
用户与入口微信小程序、官网、飞轮中台、服务看板、团长经营台、文档中心角色任务、内容展示和交互
接入层www、api、feilun、docs、image 域名及 NginxHTTPS、静态资源、反向代理、跨域边界
应用层小程序后端 :8089、飞轮后端 :8088，共享券与培训核心鉴权、业务规则、状态流转、权限、任务与审计
分析层独立分析 API、Flink CDC、ClickHouse只读源采集、恢复、派生报表和就绪校验
数据层RDS MySQL fuspa、Redis、OSS权威业务数据、会话与缓存、媒体对象
外部生态微信登录、微信支付、历史有赞、内部 ERP身份、支付、历史迁移和库存协同
交付运维GitHub、Jenkins、构建工具、部署脚本、日志和备份构建、发布、回滚、监控和恢复

典型调用路径：

微信小程序 -> api.afuspa.com -> Nginx -> spa-backend:8089 -> RDS / Redis / 微信 / OSS
飞轮浏览器 -> feilun.afuspa.com -> Nginx -> spa-feilun-backend:8088 -> RDS / Redis / OSS
外部看板 -> www.afuspa.com/docs/* -> 浏览器 -> feilun.afuspa.com/api/* -> 飞轮后端
文档访问 -> docs.afuspa.com -> Nginx -> Rspress 静态文件

3. 仓库部署约定

既有部署配置体现两个业务应用主机边界，分析工程另行部署；下面不是本轮线上巡检结果：

部署边界主要入口应用
公开站点与小程序 API 主机www.afuspa.com、api.afuspa.com官网/H5 静态资源、spa-backend:8089
飞轮、文档与持续交付主机feilun.afuspa.com、docs.afuspa.com、jenkins.afuspa.com飞轮前端、spa-feilun-backend:8088、Rspress、Jenkins :8081
共享云资源内网连接RDS MySQL、Redis、OSS/图片服务

该形态实现了接入和进程隔离，但两个后端共享核心数据库，因此数据库故障、连接数耗尽、错误 SQL 和不受控写入仍可能影响全部业务。

4. 应用责任边界

系统负责不负责
微信小程序顾客交易、店长履约、恢复师任务的移动交互直接更新数据库、推断支付最终状态
小程序后端微信登录、会员、预约、商品、订单、支付退款、积分、员工工作台接口总部菜单配置、复杂经营分析
飞轮中台总部与门店管理、CRM、项目和库存配置、订单检索、退款管理、人员薪酬、指标和审计复制另一套订单或支付事实
外部看板门店现场展示、团长范围内经营数据、协议内容独立保存会员、订单、支付或推广关系
文档中心产品、技术、接口、操作和运维知识存放密码、证书私钥和生产密钥
历史有赞/ERP历史查询、迁移对照、必要的库存同步继续成为新业务的第二权威来源

共享核心与独立分析

双后端接入 spa-coupon-core 和 spa-training-core，分别统一券/体验升级及培训规则。分析工程 spa-analytics 独立运行，Flink CDC 从 source.json 指定的只读来源采集到 ClickHouse，前端以 /analytics-api 访问分析服务，业务 /api 不变。

采集配置、恢复点和审计由独立部署管理，不在业务库新建分析任务表。分析只消费业务事实，最终版本去重、字段清单和就绪门禁决定是否可查询；不能反向改交易事实补平分析差异。

5. 核心数据权威

当前阶段两个后端共用一套 fuspa 数据库，必须通过“领域写入责任”约束共享库使用。

数据对象权威事实/写入责任主要消费者
会员档案与会员资产统一会员服务与资产流水小程序、飞轮 CRM、团长经营分析
预约池与服务单预约/履约服务的状态机和审计记录顾客端、店长端、恢复师端、服务看板
商品与库存商品目录和库存流水服务商城、飞轮商品库存、提货流程
订单、支付与退款订单服务、支付回调、退款任务和对账结果所有角色端及财务
团长关系与订单归因推广服务；订单创建时保留归因快照飞轮推广管理、团长经营台
经营指标工作台/财务基于业务事实，独立分析基于 CDC 派生数据各自口径的日报、财务、经营报表和预警
券与培训共享核心的正式领域表、权益、考核和学习流水双后端、中台、小程序及网页学习
图片与媒体OSS 保存对象，数据库保存元数据和地址官网、小程序、飞轮、外部看板
历史有赞数据迁移前只读或限制修改，核对后归档数据迁移与历史查询

禁止通过以下方式破坏单一权威：

  • 前端根据支付页面关闭、网络返回或本地缓存直接标记“已支付”；
  • 看板为提高响应速度复制并长期维护另一套预约状态；
  • 两个后端各自实现同一状态流转且缺少版本、幂等或审计约束；
  • 导入任务覆盖线上已发生变更的数据；
  • 指标页面用与财务口径不同的日期、金额或退款规则自行聚合。

6. 身份与权限边界

入口身份凭证授权重点
小程序wx.login 换取的业务 JWT，附带会员身份顾客本人、员工角色、必要的门店范围
飞轮中台中台账号令牌菜单权限、API 权限、角色和门店数据范围
服务看板中台账号令牌manager:workbench:view 与账号可访问门店
团长经营台中台账号令牌服务单查看、推广查看及团长数据范围

授权必须在后端再次校验。隐藏菜单、前端路由守卫和按钮禁用只是交互保护，不能替代接口权限。

7. 关键非功能基线

一致性

  • 预约提交、支付预下单、支付回调、退款、积分、库存和推广归因必须幂等；
  • 可重试操作使用业务唯一键、请求号或版本号防重；
  • 异步任务记录运行批次、输入范围、结果和失败原因；
  • 金额统一使用最小货币单位传输和计算，避免浮点误差。

可观测性

  • API 统一返回 code、message、requestId 和时间；
  • 入口、应用和后台任务日志保留请求路径、操作者、业务主键和结果；
  • 支付、退款、库存、会员资产和推广归因异常进入可追踪队列或异常中心；
  • 建立应用、数据库、证书、备份和磁盘容量告警。

安全

  • 全部正式域名启用 HTTPS，证书续签可验证；
  • 敏感信息按角色和用途脱敏，导出和关键变更留审计；
  • 开发、测试、生产环境的数据库、密钥、域名和支付配置隔离；
  • 账号密码、微信支付证书和云密钥只进入安全配置，不进入 Git 和文档站。

恢复能力

  • 数据库至少每日自动备份，重要发布前建立恢复点；
  • 后端 JAR 发布前保留旧包，新进程健康检查失败时回滚；
  • 数据库升级脚本与应用版本一同评审，先备份、后变更、再验证；
  • 定期执行恢复演练，而不是只检查“备份文件存在”。

8. 成本与架构映射

成本项主要服务对象扩容触发因素
业务/API ECS官网、H5、小程序后端API 并发、支付回调、静态流量和任务资源争用
飞轮 ECS飞轮前后端、文档、Jenkins报表导出、后台任务、构建和中台访问量
RDS全部核心业务数据规模、慢查询、连接数、备份和恢复目标
Redis登录会话、热点缓存、锁会话量、热点压力、任务并发和高可用要求
OSS/CDN商品、项目、活动和门店图片存储量、请求量、下行流量和图片处理
日志监控与备份全部生产系统保留周期、告警精度、跨区备份和合规要求

不应为了“架构看起来完整”提前采购资源；Redis、CDN、WAF、灾备和已有分析组件的扩容均应由实际容量、风险和恢复目标驱动。

9. 待决策架构事项

  1. 官网、协议、服务看板和团长经营台是否继续共用 /docs/ 路径，还是拆分独立入口。
  2. 两台 ECS 的长期职责、生产与测试隔离及是否引入负载均衡。
  3. 共享 RDS 的账号权限、连接池配额、故障域和未来按服务拆分策略。
  4. image.afuspa.com 的 CDN、防盗链、私有对象和图片处理策略。
  5. 外部看板长期调用飞轮 API，还是迁移到统一业务 API/专用 BFF。
  6. 有赞退出范围、历史数据保留周期和 ERP 同步责任。

任何会改变上述边界的决策，都应形成架构决策记录后再实施。

技术文档

本篇目录