# 启动记录

## 1. 项目结构

当前项目包含 3 个子系统：

1. `backend/`：FastAPI 后端
2. `miniprogram/`：微信小程序
3. `admin-web/`：后台管理端

本次启动优先保证：后端可用，小程序可打开。

## 2. 首次启动顺序

建议按下面顺序启动：

1. 启动 MySQL
2. 启动后端 `backend/`
3. 检查后端健康状态
4. 打开微信开发者工具并加载 `miniprogram/`
5. 编译小程序

## 3. 后端首次启动记录

### 3.1 进入目录

```powershell
cd backend
```

### 3.2 创建虚拟环境

```powershell
python -m venv .venv
.\.venv\Scripts\Activate.ps1
```

### 3.3 安装依赖

```powershell
pip install -r requirements.txt
```

### 3.4 配置环境变量

将：

- `backend/.env.example`

复制为：

- `backend/.env`

至少需要确认这些配置已填写：

```env
MYSQL_HOST=127.0.0.1
MYSQL_PORT=3306
MYSQL_USER=root
MYSQL_PASSWORD=123456
MYSQL_DATABASE=dating_app

REDIS_HOST=127.0.0.1
REDIS_PORT=6379
REDIS_DB=0

JWT_SECRET_KEY=replace_with_a_secure_secret

WX_APPID=your_wx_appid
WX_SECRET=your_wx_secret
```

### 3.5 准备数据库

先创建数据库：

```sql
CREATE DATABASE dating_app DEFAULT CHARACTER SET utf8mb4;
```

### 3.6 执行迁移

```powershell
alembic upgrade head
```

### 3.7 启动后端

```powershell
uvicorn main:app --reload
```

### 3.8 健康检查

启动后访问：

```text
http://127.0.0.1:8000/health
```

如果返回：

```json
{"status":"ok"}
```

说明后端启动成功。

## 4. 小程序启动记录

### 4.1 打开目录

使用微信开发者工具打开：

```text
miniprogram/
```

### 4.2 本地接口地址

当前小程序接口地址已调整为：

```text
http://127.0.0.1:8000/api/v1
```

涉及文件：

1. `miniprogram/utils/constants.js`
2. `miniprogram/app.js`

### 4.3 开发者工具配置

本地联调时建议勾选：

1. `不校验合法域名`
2. `不校验 HTTPS 证书`

否则可能出现：

```text
request:fail url not in domain list
```

### 4.4 当前已处理的问题

之前小程序存在一个启动风险：

1. `app.js` 启动时会立刻登录
2. 登录依赖后端接口和 `wx.login`
3. 一旦接口不可用，页面可能表现为打不开或白屏

当前已做处理：

1. `miniprogram/app.js` 启动登录增加了容错
2. `miniprogram/pages/home/home.js` 首页接口请求增加了失败兜底
3. 接口地址从 `localhost` 统一改成了 `127.0.0.1`

现在即使后端暂时异常，小程序页面也不应因为启动登录失败而直接打不开；只是页面数据可能为空。

## 5. 真机调试说明

真机不要使用：

1. `localhost`
2. `127.0.0.1`

原因：

1. 手机访问不到你电脑本机地址
2. 小程序请求域名需要在微信后台配置

真机联调时应改成：

1. 电脑局域网 IP
2. 或可访问的正式域名

## 6. 常见错误排查

### 6.1 小程序页面打不开

优先检查：

1. 后端是否已启动
2. `http://127.0.0.1:8000/health` 是否可访问
3. 微信开发者工具是否关闭了域名校验限制
4. 控制台是否有 `request:fail`
5. 控制台是否有 `wx.login` 相关错误

### 6.2 微信登录不可用

当前 `miniprogram/project.config.json` 中使用的是：

```text
touristappid
```

这适合先看页面结构，但如果要走完整微信登录，通常需要替换成真实小程序 `appid`。

### 6.3 接口请求失败

检查项：

1. 后端服务是否运行在 `127.0.0.1:8000`
2. 路径前缀是否为 `/api/v1`
3. 后端数据库是否可连接
4. `.env` 中微信配置是否正确

## 7. 本次记录结论

本项目第一次启动时，正确顺序是先启动后端，再打开小程序。

如果只是看页面：

1. 可以先打开小程序
2. 即使接口失败，页面现在也应能打开

如果要完整联调登录和数据：

1. 必须先启动后端
2. 必须保证数据库和相关环境变量配置正确
3. 最好使用真实小程序 `appid` 进行微信能力联调