docs: complete developer documentation (5 guides + index)

- 01-快速开始: local setup for all 3 modules, common issues - 02-配置说明: all env vars, WeChat/Pay/DB/COS config details - 03-架构说明: system overview, directory structure, data flows - 04-部署指南: Tencent Cloud SCF/COS deployment, launch checklist - 05-API接口文档: all 42 endpoints with params and response format - README index with audience guide and quick links
2026-05-18 08:11:30 -07:00
@@ -0,0 +1,232 @@
+# 快速开始
+
+## 项目概述
+
+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
+```