Mobile App 技术栈与后端关系

Guest App & Employee App 架构总览 · 更新于 2026-02-05

1. 整体架构

两个 Mobile App 与 Web App 共享同一个后端服务（Express.js :3000），通过不同的 API 路由模块访问各自的业务数据。

graph TB subgraph Clients["客户端"] WEB["Web App
(Next.js :3001)"] GUEST["Guest App
(Flutter)"] EMP["Employee App
(Flutter)"] end subgraph Backend["后端服务 :3000"] API["Express.js API"] PB["/api/public/booking/*"] GA["/api/guest-auth/*"] MOB["/mobile/*"] TC["/time-clock/*"] SCH["/schedules/*"] AUTH["/auth/employee/*"] CORE["其他共享路由
/centers, /payroll, ..."] end DB[("PostgreSQL :5433
多租户 Schema")] WEB --> API GUEST --> PB GUEST --> GA EMP --> AUTH EMP --> MOB EMP --> TC EMP --> SCH EMP --> CORE API --> DB PB --> DB GA --> DB MOB --> DB TC --> DB SCH --> DB AUTH --> DB CORE --> DB style GUEST fill:#065f46,stroke:#4ade80,color:#fff style EMP fill:#4c1d95,stroke:#c084fc,color:#fff style WEB fill:#0c4a6e,stroke:#38bdf8,color:#fff style DB fill:#78350f,stroke:#fbbf24,color:#fff

2. 共同技术栈

两个 App 使用完全相同的核心框架和开发工具链：

类别	技术	版本	说明
框架	Flutter + Dart	3.16+ / SDK ≥3.2.6	跨平台（iOS + Android 一套代码）
状态管理	flutter_bloc	^8.1.3	BLoC 模式，事件驱动单向数据流
路由	go_router	^13.0.0	声明式路由，支持嵌套/重定向/ShellRoute
HTTP	dio	^5.4.0	网络请求客户端，支持拦截器
依赖注入	get_it + injectable	^7.6.4 / ^2.3.2	运行时 DI 容器 + 代码生成注册
数据类	freezed + json_serializable	^2.4.x / ^6.7.x	不可变模型 + JSON 序列化代码生成
安全存储	flutter_secure_storage	^9.0.0	存 JWT Token（iOS Keychain / Android Keystore）
本地存储	hive + hive_flutter	^2.2.3	存偏好设置（语言、主题等轻量数据）
国际化	flutter_localizations + intl + ARB	^0.18.1	中英双语，`generate: true` 自动生成
日期格式	intl (DateFormat)	^0.18.1	日期时间本地化格式
网络检测	connectivity_plus	^5.0.2	检测网络连接状态
UUID	uuid	^4.2.2	本地生成唯一标识（离线消息等）

开发工具链（dev_dependencies）

工具	用途
`build_runner`	代码生成执行器（`dart run build_runner build`）
`freezed`	生成不可变数据类 + copyWith + 模式匹配
`json_serializable`	生成 fromJson / toJson 方法
`injectable_generator`	扫描 @injectable 注解生成 DI 注册代码
`hive_generator`	生成 Hive TypeAdapter
`mockito` + `bloc_test`	单元测试 Mock + BLoC 测试辅助
`integration_test`	Flutter 集成测试框架（真机/模拟器）

3. 差异对比

Guest App 独有依赖

mapbox_maps_flutter — 门店地图展示（Mapbox GL）
add_2_calendar — 预约后添加到系统日历
url_launcher — 打开地图导航、拨打电话

定位：面向顾客，功能轻量 — 预约、门店查找、账户管理

Employee App 独有依赖

socket_io_client — WebSocket 实时聊天
fl_chart — 报表图表（KPI、业绩）
image_picker — 聊天发图片
file_picker — 聊天发文件附件
permission_handler — 系统权限请求（相机/存储）
pull_to_refresh — 下拉刷新列表
firebase_messaging — 推送通知（预留，暂禁用）

定位：面向员工，功能重 — 打卡、聊天、排班、报表、小费

4. 后端 API 端点映射

Guest App 调用的端点

全部是已有的公共 API，Web 端公共预约页面也在调用同一组端点：

路由前缀	后端文件	认证方式	说明
`/api/public/booking/*`	`backend/api/public/booking.js`	手机验证码 / 无认证	门店、服务、时段、预约 CRUD
`/api/guest-auth/*`	`backend/api/guest-auth.js`	Guest JWT	注册、登录、密码、邮箱验证、会员升级

Employee App 调用的端点

复用现有后端路由共享

路由	后端文件	说明
`/auth/employee/*`	`backend/auth/employee_auth_controller.js`	员工登录/登出/刷新/密码
`/time-clock/*`	`backend/api/time-clock.js`	打卡、时间卡、PIN 验证、补卡
`/schedules/*`	`backend/api/schedules.js`	排班查询
`/payroll/*`	`backend/api/payroll.js`	工资单
`/centers`	`backend/api/centers.js`	门店列表
`/tenants/public`	`backend/api/tenants-validate.js`	租户公开信息

Employee App 专属路由 Mobile Only

路由	后端文件	说明
`/mobile/my-services/*`	`backend/api/mobile/my-services.js`	今日待服务列表、标记完成
`/mobile/reviews/*`	`backend/api/mobile/reviews.js`	服务后请求顾客评价
`/mobile/tips/*`	`backend/api/mobile/tips.js`	服务后请求小费
`/mobile/chat/*`	`backend/api/mobile/chat.js`	员工聊天（1v1 + 群聊）
`/mobile/announcements/*`	`backend/api/mobile/announcements.js`	店长公告
`/mobile/team/*`	`backend/api/mobile/team.js`	团队成员、换班请求、请假
`/mobile/reports/*`	`backend/api/mobile/reports.js`	管理者 KPI/业绩/销售报表
`/mobile/notifications/*`	`backend/api/mobile/notifications.js`	推送通知设置、Token 注册

为什么有 /mobile/* 专属路由？

移动端屏幕小、网络不稳定，需要精简的数据格式（比如只返回今日预约而不是全部）和聚合接口（一个请求拿到多个维度数据）。 /mobile/* 路由返回移动端优化的响应结构，减少请求次数和传输量。

5. 认证与数据流

Guest App 认证流程

sequenceDiagram participant G as Guest App participant API as Backend :3000 participant DB as PostgreSQL G->>API: POST /api/public/booking/send-code
{phone} API->>G: SMS 验证码已发送 G->>API: POST /api/public/booking/confirm
{phone, code} API->>DB: 查找/创建 guest 记录 API->>G: {guestToken, guest} Note over G: 或使用会员账号登录 G->>API: POST /api/guest-auth/login
{email, password} API->>DB: 验证凭据 API->>G: {accessToken, refreshToken, guest}

Employee App 认证流程

sequenceDiagram participant E as Employee App participant API as Backend :3000 participant DB as PostgreSQL E->>API: POST /auth/employee/login
{email, password, tenantId} API->>DB: 验证凭据 + 加载权限 API->>E: {accessToken, refreshToken, employee} Note over E: 可选：PIN 快捷登录 E->>API: POST /time-clock/pin/verify
{pin} API->>E: {verified: true} Note over E: 实时聊天连接 E->>API: WebSocket connect (Socket.io)
Authorization: Bearer {token} API->>E: 连接成功，加入聊天房间

6. 项目目录结构

Guest App

guest_mobile_app/qqnails_guest_app/
├── lib/
│   ├── app/
│   │   └── router.dart          # 路由配置
│   ├── core/
│   │   ├── api/                 # API 客户端 + 端点
│   │   ├── di/                  # 依赖注入
│   │   ├── storage/             # Hive 本地存储
│   │   ├── theme/               # 主题配置
│   │   └── utils/               # 工具类
│   ├── features/
│   │   ├── auth/                # 登录/注册/密码
│   │   ├── booking/             # 预约流程
│   │   └── stores/              # 门店选择
│   └── l10n/                    # ARB 翻译文件
├── ios/                         # iOS 原生配置
├── android/                     # Android 原生配置
└── pubspec.yaml

Employee App

employee_mobile_app/
├── lib/
│   ├── app/
│   │   └── router.dart          # 路由 + 底部导航
│   ├── core/
│   │   ├── api/                 # API 客户端 + 端点
│   │   ├── di/                  # 依赖注入
│   │   ├── l10n/                # LocaleCubit
│   │   ├── storage/             # Hive 本地存储
│   │   ├── theme/               # 主题配置
│   │   └── utils/               # 工具类
│   ├── features/
│   │   ├── auth/                # 登录/PIN
│   │   ├── home/                # 首页仪表盘
│   │   ├── chat/                # 聊天(Socket.io)
│   │   ├── time_clock/          # 打卡/时间卡
│   │   ├── my_services/         # 今日服务
│   │   ├── reviews/             # 评价请求
│   │   ├── tips/                # 小费请求
│   │   ├── schedule/            # 排班查看
│   │   ├── swap_leave/          # 换班/请假
│   │   ├── announcements/       # 公告
│   │   ├── reports/             # 报表(管理者)
│   │   └── settings/            # 个人设置
│   └── l10n/                    # ARB 翻译文件
├── ios/                         # iOS 原生配置
├── android/                     # Android 原生配置
└── pubspec.yaml

7. 端口与服务汇总

服务	端口	技术	调用者
Backend API	`:3000`	Express.js + Socket.io	Web App + Guest App + Employee App
Web App	`:3001`	Next.js 14	浏览器
PostgreSQL	`:5433`	PostgreSQL 15	Backend 内部
Guest App	-	Flutter (iOS/Android)	调用 :3000
Employee App	-	Flutter (iOS/Android)	调用 :3000 (HTTP + WebSocket)

一句话总结

一个后端，三个前端。Web App、Guest App、Employee App 全部调用同一个 Express.js 后端（:3000），通过不同的路由模块（/api/public/*、/api/guest-auth/*、/mobile/*、/auth/employee/*）实现各自的业务逻辑。数据库层面通过 PostgreSQL Schema 实现多租户隔离。