# 服务端架构

## 概述

服务端是一个运行在腾讯云 SCF（Serverless Cloud Function）上的 Node.js 应用，以 HTTP 函数形式对外暴露 RESTful API。不依赖任何 Web 框架（如 Express/Koa），所有路由和请求处理均为手写实现。

**技术栈：** Node.js + mysql2 + jsonwebtoken + bcryptjs + cos-nodejs-sdk-v5

---

## 目录结构

```
server/
├── index.js                  # 入口：re-export src/index.js
├── scf_bootstrap             # SCF Web 函数冷启动脚本
├── package.json
├── scripts/
│   ├── init-db.js            # 数据库初始化（建表 + 种子数据）
│   └── local-server.js       # 本地开发 HTTP 服务器
├── sql/
│   └── schema.sql            # 完整 DDL（11 张表）
└── src/
    ├── index.js              # SCF 入口：导出 main_handler(event, context)
    ├── app.js                # 请求分发：解析 → 路由匹配 → 执行 → 响应
    ├── config.js             # 环境变量集中配置
    ├── lib/
    │   ├── auth.js           # JWT 签发/验证、bcrypt 密码哈希
    │   ├── cos.js            # 腾讯云 COS 客户端（预签名 URL）
    │   ├── db.js             # MySQL 连接池、query/one/transaction
    │   ├── log.js            # 操作日志写入
    │   ├── request.js        # SCF event → ctx 对象解析
    │   ├── response.js       # ok/fail/http 响应构造
    │   ├── router.js         # 轻量正则路由器
    │   ├── utils.js          # 日期格式化工具
    │   └── wechat.js         # 微信小程序 API（code2Session、手机号）
    └── routes/
        ├── admin.js          # 管理后台 CRUD
        ├── auth.js           # 微信登录 + token 刷新
        ├── device.js         # 设备绑定/解绑/命令/事件
        ├── firmware.js       # 固件管理 + OTA 检查
        ├── subscription.js   # 订阅状态/购买/核销
        ├── treatment.js      # 护理记录同步/查询
        └── user.js           # 用户信息 CRUD
```

---

## 请求生命周期

一个请求从进入到返回的完整流程：

```
SCF 触发 / HTTP 请求
     │
     ▼
scf_bootstrap (PORT=9000, node scripts/local-server.js)
     │
     ▼
local-server.js 收集请求体，构造 API Gateway event 对象
     │
     ▼
src/index.js → main_handler(event, context)
     │
     ▼
src/app.js → handle(event)
     │
     ├── createContext(event)    ← 解析 method/path/headers/query/body/ip
     ├── OPTIONS ?              → 直接返回 204（CORS 预检）
     ├── /health ?              → 返回 { status: 'ok' }
     ├── router.match(method, path)
     │    ├── 无匹配            → 404 not_found
     │    └── 有匹配            → 提取 URL 参数，调用 handler(ctx)
     │         ├── handler 返回值 → http(200, body)
     │         └── handler 抛异常 → http(500, fail(3001, 'server_error'))
     │
     ▼
SCF API Gateway 响应格式：
{
  isBase64Encoded: false,
  statusCode: 200,
  headers: { 'Access-Control-Allow-Origin': '*', ... },
  body: '{"code":0,"message":"success","data":{...}}'
}
```

### 关键设计点

- **无中间件链**：没有 Koa/Express 那样的中间件栈。鉴权在每个路由处理函数开头手动调用 `requireUser(ctx)` 或 `requireAdmin(ctx)`。
- **CORS**：所有响应都带 `Access-Control-Allow-Origin: *`，允许 `Content-Type, Authorization, X-Device-Id, X-App-Version, X-Platform` 请求头。
- **路由器**：自研轻量实现，把 `/api/v1/device/:device_id` 这样的路径转换成正则表达式，匹配时提取参数写入 `ctx.params`。

---

## 配置结构

所有配置通过 `dotenv` 从 `.env` 文件加载，集中定义在 `src/config.js`：

| 配置项 | 环境变量 | 默认值 | 说明 |
|--------|---------|--------|------|
| `db.host` | `DB_HOST` | - | MySQL 地址 |
| `db.port` | `DB_PORT` | 3306 | MySQL 端口 |
| `db.user` | `DB_USER` | root | |
| `db.password` | `DB_PASSWORD` | - | |
| `db.database` | `DB_NAME` | jw_beauty | |
| `jwt.secret` | `JWT_SECRET` | dev-user-secret | 用户 token 签名密钥 |
| `jwt.adminSecret` | `ADMIN_JWT_SECRET` | dev-admin-secret | 管理员 token 签名密钥 |
| `jwt.expiresIn` | - | 7d | token 有效期 |
| `cos.secretId` | `TENCENT_SECRET_ID` | - | COS 密钥 |
| `cos.secretKey` | `TENCENT_SECRET_KEY` | - | COS 密钥 |
| `cos.bucket` | `COS_BUCKET` | jw-bucket-1426323813 | |
| `cos.region` | `COS_REGION` | ap-guangzhou | |
| `wechat.appid` | `WECHAT_APPID` | - | 小程序 AppID |
| `wechat.secret` | `WECHAT_SECRET` | - | 小程序密钥 |

**生产环境保护**：如果 `NODE_ENV=production` 且 JWT 密钥仍为默认值，进程启动时会直接抛异常，防止带着测试密钥上线。

---

## 数据库层

### 连接方式

使用 `mysql2/promise`，惰性初始化单例连接池：

- 连接数上限：5
- 命名占位符：`:param_name`（通过 `namedPlaceholders: true` 启用）
- 时区：`+08:00`

### 查询工具

| 函数 | 说明 |
|------|------|
| `query(sql, params)` | 执行查询，返回行数组 |
| `one(sql, params)` | 执行查询，返回第一行或 `null` |
| `transaction(work)` | 获取连接 → BEGIN → 执行 work(conn) → COMMIT/ROLLBACK → 释放 |
| `limitClause(pageSize, offset)` | 返回 ` LIMIT N OFFSET M` 字符串片段 |

### 数据表一览

共 10 张表，全部 InnoDB + utf8mb4_unicode_ci：

| 表名 | 用途 | 主键 |
|------|------|------|
| `users` | 小程序用户 | user_id (自增) |
| `devices` | 设备信息 | device_id (字符串) |
| `bindings` | 用户-设备绑定关系 | binding_id (自增) |
| `subscriptions` | 用户订阅 | subscription_id (自增) |
| `treatment_records` | 护理记录 | record_id (自增)，session_id 唯一索引 |
| `device_events` | 设备事件日志 | event_id (自增) |
| `device_commands` | 远程指令队列 | command_id (自增) |
| `operation_logs` | 操作审计日志 | log_id (自增) |
| `admin_accounts` | 管理员账号 | admin_id (自增) |
| `system_settings` | 系统配置键值对 | setting_key (字符串) |
| `firmware_files` | 固件文件记录 | firmware_id (自增) |

### 核心表详细结构

**users**

| 字段 | 类型 | 说明 |
|------|------|------|
| user_id | BIGINT UNSIGNED AUTO_INCREMENT | 主键 |
| openid | VARCHAR(64) UNIQUE | 微信 openid |
| nickname | VARCHAR(100) | 昵称 |
| avatar | VARCHAR(500) | 头像 URL |
| phone | VARCHAR(32) | 手机号 |
| gender | TINYINT | 0=未知 |
| status | TINYINT | 1=正常 |

**devices**

| 字段 | 类型 | 说明 |
|------|------|------|
| device_id | VARCHAR(32) | 主键，设备编号 |
| product_id | VARCHAR(64) | 产品型号，默认 HOX_LIGHT_MASK |
| device_secret | VARCHAR(128) | 设备密钥 |
| firmware_version | VARCHAR(32) | 固件版本 |
| status | TINYINT | 1=未激活 2=在线 3=离线 4=禁用 |
| battery | TINYINT UNSIGNED | 电量 |
| temperature | TINYINT UNSIGNED | 温度 |
| last_online_at | DATETIME | 最后在线时间 |

**bindings**

| 字段 | 类型 | 说明 |
|------|------|------|
| binding_id | BIGINT AUTO_INCREMENT | 主键 |
| user_id | BIGINT | 外键 → users |
| device_id | VARCHAR(32) | 外键 → devices |
| bind_token | CHAR(16) | 绑定令牌（16位 hex） |
| bind_expires | DATETIME | 令牌过期时间（10 分钟） |
| bind_status | TINYINT | 1=已绑定 2=已解绑 3=待确认 |

**subscriptions**

| 字段 | 类型 | 说明 |
|------|------|------|
| subscription_id | BIGINT AUTO_INCREMENT | 主键 |
| user_id | BIGINT | 外键 → users |
| plan | VARCHAR(32) | trial / monthly / yearly |
| status | TINYINT | 1=生效 2=过期 3=取消 |
| amount | DECIMAL(10,2) | 金额 |
| start_time / expire_time | DATETIME | 有效期 |

**treatment_records**

| 字段 | 类型 | 说明 |
|------|------|------|
| record_id | BIGINT AUTO_INCREMENT | 主键 |
| session_id | VARCHAR(64) UNIQUE | 会话 ID（唯一标识一次护理） |
| device_id / user_id | | 设备和用户 |
| regions | VARCHAR(255) | 护理区域（逗号分隔或位掩码） |
| total_duration_ms | INT UNSIGNED | 护理时长（毫秒） |
| mode | TINYINT | 0=普通 1=智能 |
| avg_pd | DECIMAL(8,4) | 平均光密度 |
| pd_json | JSON | 详细光密度数据 |

---

## 鉴权系统

### 双密钥 JWT

系统使用两套独立的 JWT 密钥：

```
用户 token:  JWT_SECRET       → type: 'user',  payload: { user_id, openid }
管理员 token: ADMIN_JWT_SECRET → type: 'admin', payload: { admin_id, username, role }
```

两种 token 都是 7 天有效期。

### 用户登录流程

```
小程序 wx.login()  →  code
      │
      ▼
POST /api/v1/auth/login { code }
      │
      ├── server 调用微信 jscode2session 换取 openid
      ├── 查询/自动创建 users 记录
      ├── 签发 JWT（含 user_id, openid）
      └── 返回 { token, user_id, user_info, expires_in: 604800 }
```

### 管理员登录流程

```
POST /api/v1/admin/login { username, password }
      │
      ├── 查询 admin_accounts 表
      ├── bcrypt 验证密码
      │   └── 失败 → 尝试旧 SHA-256 验证
      │        └── 成功 → 自动迁移密码到 bcrypt
      ├── 签发 JWT（含 admin_id, username, role）
      └── 返回 { token, admin_id, username, real_name, role }
```

### Token 刷新

`POST /api/v1/auth/refresh`：

- token 未过期且剩余 > 7 天 → 原样返回
- token 未过期且剩余 ≤ 7 天 → 签发新 token
- token 已过期但在 3 天宽限期内 → 签发新 token
- token 已过期超过 3 天 → 拒绝，需重新登录

---

## API 接口清单

### 认证与用户

| 方法 | 路径 | 鉴权 | 说明 |
|------|------|------|------|
| POST | `/api/v1/auth/login` | 无 | 微信登录，返回 JWT |
| POST | `/api/v1/auth/refresh` | Bearer (可过期) | 刷新 token |
| GET | `/api/v1/user/profile` | 用户 | 获取个人信息 |
| PUT | `/api/v1/user/profile` | 用户 | 修改昵称/头像/性别 |
| POST | `/api/v1/user/phone` | 用户 | 绑定手机号（微信授权） |

### 设备

| 方法 | 路径 | 鉴权 | 说明 |
|------|------|------|------|
| POST | `/api/v1/device/bind` | 用户 | 发起绑定（生成 bind_token，10分钟有效） |
| POST | `/api/v1/device/bind/confirm` | 用户 | 确认绑定（BLE 握手完成后调用） |
| POST | `/api/v1/device/unbind` | 用户 | 解绑设备 |
| GET | `/api/v1/device/list` | 用户 | 已绑定设备列表 |
| GET | `/api/v1/device/:device_id` | 用户 | 设备详情（校验归属） |
| GET | `/api/v1/device/command/pending` | 用户 | 拉取待执行远程指令 |
| POST | `/api/v1/device/command/result` | 用户 | 上报指令执行结果 |
| POST | `/api/v1/device/event` | 用户 | 上报设备事件 |

### 订阅

| 方法 | 路径 | 鉴权 | 说明 |
|------|------|------|------|
| GET | `/api/v1/subscription` | 用户 | 查询当前订阅状态 |
| POST | `/api/v1/subscription/purchase` | 用户 | 购买（未接入支付，仅生成订单号） |
| POST | `/api/v1/subscription/verify` | 管理员 | 后台核销订阅（临时方案） |

### 护理记录

| 方法 | 路径 | 鉴权 | 说明 |
|------|------|------|------|
| GET | `/api/v1/treatment/history` | 用户 | 分页查询历史记录 |
| POST | `/api/v1/treatment/sync` | 用户 | 同步护理记录（INSERT ON DUPLICATE） |
| GET | `/api/v1/treatment/:record_id` | 用户 | 单条记录详情（按 session_id 查） |

### 固件

| 方法 | 路径 | 鉴权 | 说明 |
|------|------|------|------|
| GET | `/api/v1/firmware/latest` | 用户 | OTA 更新检查 |
| GET | `/api/v1/admin/firmware` | 管理员 | 固件列表 |
| POST | `/api/v1/admin/firmware` | 管理员 | 上传固件记录 |
| POST | `/api/v1/admin/firmware/:id/status` | 管理员 | 启用/禁用固件 |

### 管理后台

| 方法 | 路径 | 鉴权 | 说明 |
|------|------|------|------|
| POST | `/api/v1/admin/login` | 无 | 管理员登录 |
| GET | `/api/v1/admin/dashboard` | 管理员 | 仪表盘统计 |
| GET/POST | `/api/v1/admin/devices` | 管理员 | 设备列表/预生成产品码 |
| GET | `/api/v1/admin/devices/:id` | 管理员 | 设备详情 |
| POST | `/api/v1/admin/devices/:id/unbind` | 管理员 | 强制解绑 |
| POST | `/api/v1/admin/devices/:id/command` | 管理员 | 下发远程指令 |
| GET | `/api/v1/admin/devices/:id/commands` | 管理员 | 指令历史 |
| GET | `/api/v1/admin/users` | 管理员 | 用户列表 |
| GET | `/api/v1/admin/users/:id` | 管理员 | 用户详情（含设备和最近护理） |
| GET/POST | `/api/v1/admin/subscriptions` | 管理员 | 订阅列表/创建订阅 |
| GET | `/api/v1/admin/records` | 管理员 | 所有护理记录 |
| GET | `/api/v1/admin/logs` | 管理员 | 操作日志 |
| GET/POST | `/api/v1/admin/settings` | 管理员 | 系统设置读写 |

---

## 外部服务集成

### 微信小程序 API

| 接口 | 用途 |
|------|------|
| `jscode2session` | 用 code 换取 openid（登录） |
| `cgi-bin/token` | 获取 access_token（缓存在内存中，带 60s 安全边际） |
| `getuserphonenumber` | 通过授权码获取用户手机号 |

开发环境绕过：如果 `NODE_ENV=development` 且 code 为空或以 `dev_` 开头，返回合成的 openid，不调用微信。

### 腾讯云 COS

用于固件文件存储。`getObjectUrl(key, expiresSeconds)` 生成预签名下载 URL，默认 3600 秒有效。

---

## 错误码约定

所有响应格式为 `{ code, message, data }`：

| code | 含义 |
|------|------|
| 0 | 成功 |
| 404 | 路由不存在 |
| 1001 | 鉴权失败（token 无效/过期） |
| 1002 | 管理员权限不足 |
| 1004 | 用户不存在 |
| 1005 | 资源不存在（设备/记录） |
| 1006 | 设备未绑定 |
| 2001 | 参数校验失败 |
| 3001 | 服务器内部错误 |

---

## 部署方式

```
腾讯云 SCF（Web 函数）
     ├── 入口：scf_bootstrap → node scripts/local-server.js
     ├── 端口：9000
     ├── 运行时：Node.js
     └── 触发方式：API Gateway HTTP 触发
```

本地开发：`npm start` → `node scripts/local-server.js` → 监听 `config.port`（默认 3000）。