# 快速开始

## 项目概述

jw-beauty 是一款光子美容仪配套系统，包含三个子项目：

- **微信小程序** (`miniprogram/`) — 用户端，蓝牙连接设备、护理流程、订阅管理
- **后端服务** (`server/`) — Express.js API，部署为腾讯云 SCF HTTP 函数
- **H5 管理后台** (`admin-console/`) — Vue 3 + uni-app H5，管理设备/用户/订阅/固件

## 前置要求

| 工具 | 版本要求 | 说明 |
|------|---------|------|
| Node.js | >= 18 | 后端使用 Express 5，管理后台使用 Vite 5 |
| npm | >= 8 | 随 Node.js 一起安装 |
| MySQL | >= 5.7 | 本地开发用，推荐 8.0；也可用 Docker |
| 微信开发者工具 | 最新稳定版 | 小程序调试用 |
| Git | 任意 | 版本管理 |

## 获取代码

```bash
git clone <仓库地址>
cd jw-beauty
```

## 后端启动

### 1. 安装依赖

```bash
cd server
npm install
```

### 2. 配置环境变量

```bash
cp .env.example .env
```

编辑 `.env`，至少填写数据库连接信息：

```ini
NODE_ENV=development
PORT=3000

# 数据库（必填）
DB_HOST=127.0.0.1
DB_PORT=3306
DB_USER=root
DB_PASSWORD=你的MySQL密码
DB_NAME=jw_beauty

# 微信登录（本地开发可暂不填，有 mock 登录）
WECHAT_APPID=
WECHAT_SECRET=

# JWT 密钥（开发环境用默认值即可，会自动 fallback）
JWT_SECRET=replace-with-a-long-random-secret
ADMIN_JWT_SECRET=replace-with-a-different-long-random-secret

# 管理员账号（开发环境默认 admin/admin）
ADMIN_USERNAME=admin
ADMIN_PASSWORD=admin

# 腾讯云（头像上传/COS 功能需要，本地开发可暂不填）
TENCENT_SECRET_ID=
TENCENT_SECRET_KEY=
TENCENT_REGION=ap-guangzhou
COS_BUCKET=jw-bucket-1426323813
COS_REGION=ap-guangzhou
```

### 3. 创建数据库

先手动创建数据库：

```bash
mysql -u root -p -e "CREATE DATABASE IF NOT EXISTS jw_beauty DEFAULT CHARSET utf8mb4 COLLATE utf8mb4_unicode_ci;"
```

然后运行初始化脚本（建表 + 插入默认设置 + 创建管理员账号）：

```bash
npm run db:init
```

### 4. 启动服务

```bash
npm start
```

看到以下输出说明启动成功：

```
Server listening on http://localhost:3000
```

### 5. 验证

```bash
curl http://localhost:3000/health
```

期望返回：

```json
{"code":0,"data":{"status":"ok"}}
```

## 小程序启动

### 1. 打开项目

用微信开发者工具打开 `miniprogram/` 目录。

项目的 AppID 已在 `project.config.json` 中配置为 `wxc4045074ef298510`。如果你没有该 AppID 的权限，可以用测试号或在开发者工具中选择"测试号"。

### 2. 指向本地后端

编辑 `miniprogram/config/env.js`，将 `ENV` 改为 `local`：

```js
var ENV = 'local'   // 改为 local，API 请求会发到 http://localhost:3000

var API_BASES = {
  local: 'http://localhost:3000',
  test: 'https://api.vsai.net.cn',
  prod: 'https://api.vsai.net.cn'
}
```

### 3. 注意事项

- **不校验合法域名**：在开发者工具「详情 > 本地设置」中勾选「不校验合法域名、web-view（业务域名）、TLS 版本以及 HTTPS 证书」，否则 localhost 请求会被拦截
- **BLE 蓝牙功能需要真机调试**：模拟器无法使用蓝牙，设备连接/护理流程必须在真机上测试
- **`__DEV__` 标志**：当 `ENV` 不是 `prod` 时，`__DEV__` 为 `true`，会启用 mock 绑定、mock 购买等开发便捷功能
- **权限**：小程序使用了蓝牙、位置（蓝牙依赖）、相机（扫码）权限，真机调试时需要授权

## 管理后台启动

### 1. 安装依赖

```bash
cd admin-console
npm install
```

### 2. 指向本地后端

编辑 `admin-console/src/config/env.js`，将 `ENV` 改为 `local`：

```js
const ENV = 'local'   // 改为 local

const API_BASES = {
  local: 'http://localhost:3000',
  test: 'https://api.vsai.net.cn',
  prod: 'https://api.vsai.net.cn'
}
```

### 3. 启动开发服务器

```bash
npm run dev
```

启动后访问终端输出的地址，通常是 `http://localhost:5173/admin/`。

> 注意路径末尾的 `/admin/`，这是 `vite.config.js` 中配置的 `base` 路径。

### 4. 登录

使用默认管理员账号登录：

- 用户名：`admin`
- 密码：`admin`

（与 `.env` 中 `ADMIN_USERNAME` / `ADMIN_PASSWORD` 一致）

### 5. 构建生产版本

```bash
npm run build:h5
```

构建产物在 `dist/build/h5/` 目录，部署到 COS：

```bash
npm run deploy:cos
```

## 常见问题

### 端口 3000 被占用

修改 `.env` 中的 `PORT`，同时更新小程序和管理后台的 `env.js` 中 `local` 对应的地址。

### 数据库连接失败

1. 确认 MySQL 服务已启动
2. 确认 `.env` 中 `DB_HOST`、`DB_PORT`、`DB_USER`、`DB_PASSWORD` 正确
3. 确认已创建 `jw_beauty` 数据库
4. 如果用 Docker 跑 MySQL，注意 host 应为 `127.0.0.1` 而非 `localhost`（避免 socket 连接问题）

### 微信登录在开发环境怎么测试

开发环境（`NODE_ENV=development`）下，服务端提供了 mock 端点：

- **mock 绑定设备**：不需要真实蓝牙握手
- **mock 购买订阅**：不需要真实微信支付

小程序端 `__DEV__` 为 `true` 时会显示对应的开发快捷入口。

如果需要测试真实微信登录，需要在 `.env` 中填写 `WECHAT_APPID` 和 `WECHAT_SECRET`（从微信公众平台获取）。

### 管理后台页面空白

确认访问地址包含 `/admin/` 路径前缀。直接访问 `http://localhost:5173/` 会 404。

### npm install 报错

确认 Node.js 版本 >= 18。可以使用 nvm 管理多版本：

```bash
nvm install 18
nvm use 18
```