# 架构说明 ## 1. 系统架构总览 ``` +-----------------+ | 腾讯云 COS | | (头像/固件存储) | +--------^--------+ | +------------------+ +--------+--------+ +------------------+ | | | | | | | 微信小程序 +--->+ SCF 云函数 +<---+ 管理后台 | | (用户端) | | (Express) | | (uni-app H5) | | +<---+ +--->+ | +-------+----------+ +--------+--------+ +------------------+ | | | BLE | mysql2 v v +-------+----------+ +--------+--------+ | 光子美容仪 | | MySQL | | (蓝牙设备) | | (腾讯云) | +------------------+ +-----------------+ ``` 三端关系： - **小程序** 通过 HTTPS 调用后端 API，通过 BLE 连接硬件设备 - **管理后台** 通过同一套后端 API（`/api/v1/admin/*`）管理数据 - **后端** 部署为腾讯云 SCF 云函数，连接 MySQL 和 COS ## 2. 后端架构 ### 2.1 目录结构 ``` server/src/ ├── index.js # SCF 入口，导出 main_handler ├── app.js # Express 应用，中间件 + 路由挂载 ├── config.js # 环境变量配置 ├── middleware/ │ └── auth.js # JWT 认证中间件 ├── routes/ │ ├── auth.js # 登录/刷新 token │ ├── user.js # 用户信息 │ ├── device.js # 设备绑定/解绑/指令 │ ├── subscription.js # 订阅计划/购买/试用 │ ├── treatment.js # 护理记录同步/查询 │ ├── firmware.js # 固件版本管理 │ └── admin.js # 管理后台全部接口 ├── dao/ │ ├── index.js # barrel export │ ├── user.dao.js # users 表 │ ├── device.dao.js # devices 表 │ ├── binding.dao.js # device_bindings 表 │ ├── subscription.dao.js # subscriptions 表 │ ├── treatment.dao.js # treatment_records 表 │ ├── command.dao.js # device_commands 表 │ ├── device-event.dao.js # device_events 表 │ ├── admin.dao.js # admin_accounts 表 │ ├── log.dao.js # operation_logs 表 │ ├── settings.dao.js # system_settings 表 │ └── firmware.dao.js # firmware_versions 表 └── lib/ ├── serverless.js # SCF event → Express 适配器 ├── db.js # mysql2 连接池 (query/one/transaction) ├── auth.js # JWT 签发/密码哈希/Bearer 读取 ├── response.js # 统一响应 { code, message, data } ├── settings-cache.js # system_settings 内存缓存 (TTL 60s) ├── wechat.js # 微信 code2Session / 获取手机号 ├── cos.js # 腾讯云 COS 客户端 └── utils.js # 日期格式化工具 ``` ### 2.2 请求处理流程 ``` SCF event │ ▼ serverless.js 将 SCF event 转换为 http.IncomingMessage + ServerResponse │ ▼ Express app(req, res) │ ├── express.json() 解析 JSON body ├── CORS 中间件 设置跨域头，处理 OPTIONS ├── rate limiter 对 login/upload 路径限流 ├── authMiddleware 提取 x-forwarded-for → req.ip │ ├── /health 健康检查 ├── /api/v1/auth/* → routes/auth.js ├── /api/v1/user/* → routes/user.js (requireUser) ├── /api/v1/device/* → routes/device.js (requireUser) ├── /api/v1/subscription/* → routes/subscription.js ├── /api/v1/treatment/* → routes/treatment.js (requireUser) ├── /api/v1/admin/* → routes/admin.js (requireAdmin) ├── /api/v1/firmware/* → routes/firmware.js │ ├── 404 handler └── error handler 记录错误日志，返回 3001 ``` ### 2.3 认证机制 JWT 双密钥体系： | 角色 | 签发函数 | 密钥 | payload 字段 | |-------|-------------|---------------------|----------------------------| | user | signUser() | config.jwt.secret | type, user_id, openid | | admin | signAdmin() | config.jwt.adminSecret | type, admin_id, username, role | 中间件层级： - `authMiddleware` — 全局，仅提取 IP，不验证 token - `requireUser` — 路由级，验证 user token，查库确认用户存在且 status=1，挂载 `req.user` - `requireAdmin` — 路由级，验证 admin token，查库确认管理员存在且 status=1，挂载 `req.admin` token 刷新：客户端在 token 剩余 <24h 时自动调用 `/auth/refresh`，过期后有 1 天宽限期。 ### 2.4 DAO 层 每个 DAO 文件只操作一张表，通过 `db.js` 提供的 `query/one/transaction` 与数据库交互： | DAO 文件 | 负责表 | 核心操作 | |-----------------------|---------------------|----------------------------------| | user.dao.js | users | CRUD、openid 查找、分页列表 | | device.dao.js | devices | 设备列表、按用户绑定关系查询 | | binding.dao.js | device_bindings | 创建/确认/取消绑定、活跃绑定查询 | | subscription.dao.js | subscriptions | 试用创建、购买(extend)、查有效订阅 | | treatment.dao.js | treatment_records | 创建记录、按用户分页、更新设备状态 | | command.dao.js | device_commands | 创建指令、拉取待执行、标记完成 | | device-event.dao.js | device_events | 设备异常事件记录 | | admin.dao.js | admin_accounts | 管理员查找/验证 | | log.dao.js | operation_logs | 操作日志写入与分页查询 | | settings.dao.js | system_settings | 全量读取系统配置 | | firmware.dao.js | firmware_versions | 固件版本列表/最新版查询 | ### 2.5 工具库 | 文件 | 职责 | |-------------------|-------------------------------------------------------------| | response.js | `ok(data)` / `fail(code, msg)` 统一响应格式 | | settings-cache.js | system_settings 内存缓存，TTL 60秒，`invalidateCache()` 手动失效 | | wechat.js | 微信登录 `code2Session`、获取手机号 `getPhoneNumber` | | cos.js | 腾讯云 COS 签名 URL 生成 | | utils.js | `toMysqlDate()` 日期格式化（UTC+8） | | wxpay.js | (规划中) 微信支付下单、回调签名验证 | ## 3. 小程序架构 ### 3.1 目录结构 ``` miniprogram/ ├── app.js / app.json / app.wxss # 应用入口 ├── config/ │ └── env.js # API_BASE 配置 ├── pages/ # 18 个页面 │ ├── login/ # 微信登录 │ ├── register/ # 补充信息 │ ├── index/ # 首页 (tab) │ ├── scan/ # 扫码绑定 │ ├── auto-scan/ # 自动扫描蓝牙设备 │ ├── ble-connect/ # BLE 连接 │ ├── bind-success/ # 绑定成功 │ ├── subscribe-prompt/ # 订阅提示 │ ├── subscribe-plans/ # 选择计划 │ ├── subscribe-success/ # 订阅成功 │ ├── wear-check/ # 佩戴检测 │ ├── treatment-setup/ # 护理参数设置 │ ├── treating/ # 护理进行中 │ ├── treatment-done/ # 护理完成 │ ├── history/ # 护理记录 (tab) │ ├── profile/ # 我的 (tab) │ ├── help/ # 帮助 │ └── contact/ # 联系我们 ├── services/ │ ├── ble.js # proxy → ble/index.js │ ├── ble/ # BLE 模块（见 3.3） │ └── command-sync.js # 远程指令拉取与执行 └── utils/ ├── request.js # HTTP 请求封装 └── api.js # 命名 API 函数 ``` ### 3.2 页面导航流程 完整用户旅程（从登录到护理完成）： ``` login ──→ register(新用户) ──→ index(首页) │ ┌───────┴──────┐ ▼ ▼ scan auto-scan (扫码绑定) (自动扫描BLE) │ │ └──────┬───────┘ ▼ ble-connect (蓝牙连接设备) │ ▼ bind-success (绑定成功) │ ┌──────┴──────┐ ▼ ▼ subscribe-prompt (已订阅则跳过) (提示订阅) │ ▼ subscribe-plans (选择计划) │ ▼ subscribe-success ──→ wear-check (佩戴检测) │ ▼ treatment-setup (设置护理参数) │ ▼ treating (护理中) │ ▼ treatment-done (护理完成,同步记录) ``` 底部 Tab 页：首页(index) | 记录(history) | 我的(profile) ### 3.3 BLE 模块拆分 ``` services/ble.js # proxy，直接 re-export ble/index.js │ services/ble/ ├── index.js # barrel，统一导出所有 API ├── protocol.js # 协议常量 + 帧编解码 ├── connection.js # 扫描/连接/断开/自动重连 └── commands.js # 指令发送 + ACK 管理 ``` **协议模式**：`PROTOCOL_MODE = 'vendor_33'`，使用自定义 BLE 服务（FFE0/FFE1/FFE2）而非标准 GATT profile。 **关键设计决策**： - connection.js 维护共享状态（`_deviceId`, `_connected`, `_chars`），commands.js 通过 getter 访问 - 事件系统在 connection.js 中实现（`on/off/emit`），心跳和状态通知作为独立事件分发 - command-sync.js 负责从服务器拉取待执行指令，逐条执行后上报结果 ### 3.4 API 调用层 ``` 页面代码 │ │ var api = require('../../utils/api') │ api.getProfile() │ ▼ api.js 命名函数，封装路径和参数 │ │ http.get('/api/v1/user/profile') │ ▼ request.js 统一封装 wx.request │ ├── 自动附加 Authorization / X-App-Version / X-Platform ├── token 过期前 <24h 自动刷新 ├── code 1001/1002 → 清除 token → reLaunch 到登录页 └── 统一错误格式 { code, message } ``` ## 4. 管理后台架构 ### 4.1 SPA 架构 基于 uni-app (Vue 2) 构建的 H5 单页应用。不使用 vue-router，而是通过动态组件实现页面切换： ``` AdminLayout 固定侧边栏 + 顶栏 └── └── 动态视图 ``` ### 4.2 VIEW_MAP 与 KEEP_ALIVE_VIEWS `pages/admin/index.vue` 中定义了两个核心映射： ```js VIEW_MAP = { dashboard: DashboardView, device: DeviceListView, 'device-detail': DeviceDetailView, user: UserListView, 'user-detail': UserDetailView, subscription: SubscriptionView, record: RecordView, log: LogView, settings: SettingsView } KEEP_ALIVE_VIEWS = [ 'DeviceListView', 'UserListView', 'SubscriptionView', 'RecordView', 'LogView' ] ``` 列表页被 keep-alive 缓存，从详情页返回时保留滚动位置和筛选状态。详情页（device-detail, user-detail）通过 `viewKey` 携带 ID，保证每次进入重新挂载。 导航通过 `$emit('navigate', viewName, props)` 冒泡到 index.vue，由 `onNavigate` 更新 `currentView` 和 `viewProps`。 ### 4.3 API 调用模式 ``` View 组件 │ │ import { get, post } from '../utils/request' │ get('/api/v1/admin/users') │ ▼ utils/request.js 基于 uni.request 封装 │ ├── 自动附加 admin_token (Bearer) ├── code 1001/1002 → 清除 token → reLaunch 到登录页 └── 统一 resolve(data) / reject(error) ``` 状态管理：Pinia store (`store/user.js`) 管理 admin token 和登录信息。 ### 4.4 构建和部署 - 框架：uni-app，编译目标 H5 - 部署方式：构建产物上传至腾讯云 COS 静态托管，或直接部署到 SCF - 菜单项：仪表盘、设备管理、用户管理、订阅管理、护理记录、操作日志、系统设置 ## 5. 数据流 ### 5.1 支付流程 ``` 用户点击购买 后端 微信支付 │ │ │ │ api.purchase(plan) │ │ ├─────────────────────────────>│ │ │ │ (当前: 返回 order_id) │ │ { order_id, payment_params }│ │ │<─────────────────────────────│ │ │ │ │ │ === 正式支付流程(规划中) ====│ │ │ wx.requestPayment(params) │ │ │ ────────────────────────────┼───────────────────────────>│ │ │ 支付回调 (notify) │ │ │<───────────────────────────│ │ │ 验签 → 更新 subscription │ │ │ subscriptionDao.purchase() │ │ │ (extend 模式，叠加天数) │ │ │ │ │ === 开发环境替代方案 ========│ │ │ api.mockPurchase(plan) │ │ ├─────────────────────────────>│ │ │ │ 直接激活订阅 │ │ { status: 'active' } │ │ │<─────────────────────────────│ │ ``` 订阅模型：`subscriptionDao.purchase()` 采用 extend 模式 —— 如已有有效订阅，在现有到期日基础上叠加天数，而非覆盖。 ### 5.2 护理记录同步流程 ``` treating 页面 BLE 设备 后端 │ │ │ │ ble.setParams({...}) │ │ ├─────────────────────────────>│ │ │ ACK │ │ │<─────────────────────────────│ │ │ ble.startTreatment() │ │ ├─────────────────────────────>│ │ │ status notify (周期) │ │ │<─────────────────────────────│ │ │ ...护理进行中... │ │ │ ble.stopTreatment() │ │ ├─────────────────────────────>│ │ │ treatment_complete notify │ │ │<─────────────────────────────│ │ │ │ │ │ 跳转 treatment-done 页面 │ │ │ │ api.syncTreatment({ │ │ device_id, session_id, │ │ start_time, end_time, │ │ regions, duration_ms, │ │ mode, wavelength, │ │ battery, temperature, │ │ pd_values ... │ │ }) │ ├───────────────────────────────────────────────────────>│ │ treatmentDao.create() │ │ treatmentDao. │ │ updateDevice() │ │ { record_id } │ │<───────────────────────────────────────────────────────│ ``` ### 5.3 设备绑定流程 ``` 用户 小程序 后端 │ │ │ │ 扫码/自动扫描获取 device_id│ │ │─────────────────────────────│ │ │ │ api.bindDevice(deviceId) │ │ ├───────────────────────────>│ │ │ │ 检查：用户未绑定其他设备 │ │ │ 检查：设备存在于 devices 表 │ │ │ 取消旧的 pending 绑定 │ │ │ 创建 pending 绑定 + bind_token │ │ { device_id, bind_token } │ │ │<───────────────────────────│ │ │ │ │ │ BLE 连接设备 │ │ │ ble.connect(deviceId) │ │ │ ble.bindDevice(bind_token) │ │ │ ──BLE──> 设备 │ │ │ <──ACK── 设备 │ │ │ │ │ │ api.confirmBind( │ │ │ deviceId, bind_token) │ │ ├───────────────────────────>│ │ │ │ bindingDao.confirmBind() │ │ │ pending → active │ │ { message: 'success' } │ │ │<───────────────────────────│ │ │ │ │ 跳转 bind-success 页面 │ │ │<────────────────────────────│ │ ``` 绑定约束：一个用户同时只能绑定一台设备；绑定前需先通过 BLE 与设备完成配对确认。