jw-beauty/docs/dev/01-快速开始.md

快速开始

项目概述

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	任意	版本管理

获取代码

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

后端启动

1. 安装依赖

cd server
npm install

2. 配置环境变量

cp .env.example .env

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

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. 创建数据库

先手动创建数据库：

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

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

npm run db:init

4. 启动服务

npm start

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

Server listening on http://localhost:3000

5. 验证

curl http://localhost:3000/health

期望返回：

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

小程序启动

1. 打开项目

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

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

2. 指向本地后端

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

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. 安装依赖

cd admin-console
npm install

2. 指向本地后端

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

const ENV = 'local'   // 改为 local

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

3. 启动开发服务器

npm run dev

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

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

4. 登录

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

• 用户名：admin
• 密码：admin

（与 .env 中 ADMIN_USERNAME / ADMIN_PASSWORD 一致）

5. 构建生产版本

npm run build:h5

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

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 管理多版本：

nvm install 18
nvm use 18