# 罗汉到家后端技术栈、架构与后续规划 文档版本2026-09-23。项目是可在线演示的上门按摩 O2O 全栈 MVP不是纯前端 Mock。生产数据由腾讯云 CloudBase 云函数与 PostgreSQL 持久化本地保留 Express Prisma SQLite 作为类型更完整、便于调试的开发后端。## 1. 系统目标与边界后端承担账号、技师、服务、档期、订单、履约、评价、积分及经营管理八类核心能力。当前目标是让面试官能用用户、技师、管理员三种身份完成可信业务闭环同时保持小体量免费部署。mermaidflowchart LRWEB[React 用户端 / 技师端 / 管理端] --|HTTPS JSON /api| API[CloudBase Node.js HTTP 云函数]API -- AUTH[JWT RBAC 会话版本]API -- DB[(CloudBase PostgreSQL)]WEB -. 本地开发 .- EXPRESS[Express 5 TypeScript]EXPRESS -- PRISMA[Prisma ORM]PRISMA -- SQLITE[(SQLite)]前端只依赖统一 REST 契约因此可在不改页面业务逻辑的情况下切换线上云函数与本地 Express。线上方案降低常驻服务器费用本地方案提供 Prisma 数据模型、类型检查和快速联调体验。## 2. 技术栈| 层级 | 技术 | 用途与选择原因 || --- | --- | --- || 线上运行时 | Tencent CloudBase、Node.js 20 | 国内访问友好HTTP 云函数按请求运行适合免费演示 || 线上数据库 | CloudBase PostgreSQL | 多账号共享、关系查询和持久化经营数据 || 本地 API | Express 5、TypeScript | 路由与领域模块清晰便于类型检查和后续拆分 || 本地数据访问 | Prisma 6、SQLite | 声明式模型、关系查询、迁移无需额外安装数据库 || 输入校验 | Zod 云函数等价校验 | 拒绝非法手机号、价格、排班、服务和状态输入 || 身份认证 | JWT HS256 | 无状态鉴权适合云函数令牌有效期 7 天 || 密码安全 | crypto.scrypt 随机盐 | 数据库不存明文密码恒定时间比较哈希 || 权限控制 | RBAC | USER、TECHNICIAN、ADMIN 三种角色由服务端隔离 || Web 安全 | Helmet、CORS 白名单、Body 限制 | 降低常见响应头、跨域和大请求风险 || 自动化验证 | TypeScript、Puppeteer、Node 脚本 | 覆盖构建、按钮反馈、角色空间、账号隔离和改密 || 部署 | CloudBase CLI、Surge | 云函数/数据库与静态前端分离当前可维持免费额度 |## 3. 后端模块textserver/src/├─ middleware/ JWT 鉴权、角色授权、错误处理├─ modules/│ ├─ auth/ 注册、登录、修改密码│ ├─ technicians/ 技师列表、详情、独立档期│ ├─ orders/ 下单、取消、状态机、评价│ ├─ profile/ 用户资料、地址、偏好、收藏、积分│ ├─ technician-workbench/ 技师订单与履约推进│ └─ admin/ 看板、订单、用户、技师、服务管理└─ shared/ 数据库、密码、会话版本、统一错误线上 cloudfunctions/luohan-api/ 实现相同接口index.js 负责公共、认证和用户资料路由其余按管理端、订单、技师工作台拆分。两套实现共享业务契约避免前端为部署环境维护两套逻辑。## 4. 数据模型| 实体 | 关键数据 | 关系/用途 || --- | --- | --- || User | 手机号、姓名、角色、密码哈希、积分、偏好 | 登录主体可关联技师档案或用户订单 || Technician | 头像、职称、位置、评分、经验、排班、上下线/归档 | 公开技师资料与工作台主体 || Service | 名称、说明、价格、时长、上下架 | 平台可配置服务目录 || TechnicianService | technicianId、serviceId | 技师与服务多对多关系 || Order | 用户、技师、服务、预约时间、地址、金额、状态 | 交易与履约主记录 || OrderStatusLog | orderId、status、createdAt | 订单状态审计轨迹 || Favorite | userId、technicianId | 每个用户独立收藏关系 || PointRecord | userId、变动值、原因 | 积分账本避免只保存余额 || AuditLog | 操作人、动作、目标、元数据 | 管理员关键操作留痕 |用户地址目前与偏好一起以 JSON 存储在 User.preferences这是免费 MVP 的兼容性取舍进入商用阶段后会拆为 Address 表并增加默认地址约束。## 5. 认证、会话和权限注册或登录后签发 JWT载荷包括json{ sub: 用户 ID, role: USER, ver: 密码哈希指纹, exp: 0 }ver 是密码哈希的不可逆短指纹。每次受保护请求都会读取当前用户并比较指纹因此用户修改密码或管理员重置技师密码后所有旧令牌立即失效无需增加收费缓存或修改数据库结构。前端改密成功后主动退出并要求使用新密码重新登录。权限边界- USER只读写自己的资料、地址、收藏、订单和评价。- TECHNICIAN只能读取分配给自己的订单并按状态机推进履约。- ADMIN读取经营聚合管理订单、用户、服务、技师档案和账号。新建技师时同步创建工作台账号。历史未绑定档案可在管理端填写手机号和初始密码完成绑定手机号全局唯一。公共面试演示账号禁止改密或被重置避免后续访问者无法登录。## 6. 核心业务规则### 6.1 档期与下单每个技师拥有独立的 workDays、workStart、workEnd。可预约性依次校验技师/服务有效、技师提供该服务、日期在开放范围、北京时间尚未过去、属于该技师排班、同一技师同一时间没有未取消订单。冲突查询始终包含 technicianId所以 A 技师 20:00 被预约不会占用 B 技师 20:00。前端用于即时提示后端保留最终校验防止绕过页面提交。### 6.2 订单状态机text待接单 → 已接单 → 已出发 → 已到达 → 服务中 → 已完成└──────── 可取消的终止状态状态不能任意跳跃。到达时记录准时数据完成后写入用户积分及积分流水。订单管理可按订单号、用户、手机号、技师和状态筛选并展示下单时间与预约时间。### 6.3 评价、指标与归档已完成订单仅可评价一次评价结果落库并重新计算技师评分。准时率初始为 100%之后按真实到达记录计算从业经验由管理员依据资质填写。技师“删除”采用软归档保留历史订单有进行中订单时拒绝归档。## 7. 主要 API| 方法 | 路径 | 权限 | 用途 || --- | --- | --- | --- || POST | /api/auth/register | 公开 | 用户注册 || POST | /api/auth/login | 公开 | 密码/演示验证码登录 || GET | /api/auth/me | 已登录 | 校验会话并返回当前账号 || PUT | /api/auth/password | 已登录 | 修改密码并使旧会话失效 || GET | /api/technicians/:id/availability | 公开 | 获取该技师排班和占用时段 || POST | /api/orders | USER | 创建订单 || POST | /api/orders/:id/review | USER | 提交完成订单评价 || GET | /api/admin/dashboard | ADMIN | 经营看板聚合 || POST | /api/admin/technicians | ADMIN | 新建技师及登录账号 || POST | /api/admin/technicians/:id/bind-account | ADMIN | 为旧档案绑定账号 || POST | /api/admin/technicians/:id/reset-password | ADMIN | 重置技师密码并注销旧会话 || DELETE | /api/admin/technicians/:id | ADMIN | 软归档技师 |成功统一返回 { data: ... }失败统一返回 { error: { code: ..., message: ... } }便于前端集中处理反馈。## 8. 部署、配置与测试生产链路Surge 静态前端 → CloudBase HTTP 云函数 → CloudBase PostgreSQL。本地链路Vite → Express → Prisma → SQLite。仓库仅提交 .env.exampleJWT 密钥、CloudBase API Key、数据库连接等真实配置不进入 Git。生产 CORS 只允许正式前端域名。常用检查bashnpm run buildnpm run check:role-workspacesnode scripts/check-account-isolation.mjsnode scripts/check-account-workflows.mjsnode scripts/check-password-change.mjs自动化覆盖账号资料隔离、收藏隔离、技师工作台身份、地址持久化、评价、管理员重置密码以及改密后旧令牌失效。线上写测试会恢复临时密码避免污染演示账号。## 9. 当前取舍和风险- 固定验证码仅用于公开演示不发送真实短信正式产品必须接入验证码过期、频率限制和风控。- 技师头像当前压缩至 100 KB 后随记录保存规模扩大应迁移到对象存储与 CDN。- 支付、聊天、定位移动属于交互演示没有真实资金回调和持续位置通道。- 云函数版本以应用层查询防止档期冲突高并发下应增加数据库唯一约束与事务重试。- 本地与云端存在双实现维护成本接口契约必须通过回归脚本保持一致。- 当前访问令牌 7 天有效且改密可整体失效但没有多设备会话列表和单设备退出。## 10. 后续规划### P0面试演示稳定性当前阶段- 保持三角色主流程、账号隔离、档期、订单状态、评价与管理端全链路可回归。- 增加云函数错误告警、数据库备份说明和部署后烟雾测试。- 为关键写操作增加请求幂等键避免弱网重复下单。### P1小规模真实运营- 将 Address、Review 拆为独立表支持评价文本、标签、申诉与管理端审核。- 头像迁移至对象存储接入受限短信、支付沙箱、消息通知和退款状态。- 引入短效 Access Token Refresh Token、设备会话管理、登录限流和异常登录记录。- 增加管理员审计日志页面、细粒度权限、数据导出和敏感字段脱敏。- 完善订单并发事务、超时自动取消、技师请假/停排和服务时长占用。### P2规模化与可靠性- Redis 缓存和分布式锁、消息队列处理通知/积分/统计WebSocket 或推送承载实时状态。- 可观测性结构化日志、链路追踪、指标、告警与错误聚合。- PostgreSQL 高可用、自动备份与恢复演练读写热点索引和慢查询治理。- CI/CD 执行类型、单元、集成、E2E、安全扫描和分阶段发布。- 完成隐私协议、数据最小化、账号注销、数据保留和支付/定位合规评审。## 11. 补充项目亮点不是堆叠技术名称而是把真实业务规则落到服务端三角色权限不能靠隐藏按钮收藏和订单按账号隔离技师档期独立状态推进有约束评价、积分、准时率来源可追溯技师用归档保留历史改密会注销旧会话线上共享数据与本地工程化后端保持同一接口。后续规划说明了当前免费 MVP 的取舍以及如何按业务增长逐步演进而不是一开始过度设计。