xiangqinxiaochengxu/README.md

# 相亲小程序项目 README

## 1. 项目简介

这是一个基于微信小程序的相亲活动与匹配平台，包含 3 个子系统：

1. `backend/`：Python FastAPI 后端
2. `miniprogram/`：微信小程序原生前端
3. `admin-web/`：Vue3 + Element Plus 后台管理端

当前系统已经完成基础主链路：

1. 微信登录
2. 用户资料编辑与提交审核
3. 后台审核
4. 活动发布、报名、查看我的活动
5. 匹配候选、感兴趣、我的匹配
6. AI 推荐基础能力
7. 公告管理与首页公告展示
8. 后台活动管理、公告管理、数据看板

## 2. 目录结构

```text
xqxcx/
├── backend/                # FastAPI 后端
├── miniprogram/            # 微信小程序
├── admin-web/              # Vue3 后台管理端
├── 开发规划.md
├── 功能差距清单.md
├── 验收清单.md
├── 上线准备清单.md
└── README.md
```

## 3. 环境要求

建议本地环境如下：

1. Python 3.11
2. Node.js 18+
3. npm 9+
4. MySQL 8.0
5. Redis 7.x
6. 微信开发者工具

## 4. 首次启动前准备

### 4.1 准备数据库

先创建数据库：

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

### 4.2 准备 Redis

本地默认配置使用：

1. Host：`127.0.0.1`
2. Port：`6379`
3. DB：`0`

目前代码里 Redis 主要是预留配置，后续通知和缓存能力会继续接入。

## 5. 后端启动说明

### 5.1 进入后端目录

```bash
cd backend
```

### 5.2 创建虚拟环境

Windows PowerShell 示例：

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

### 5.3 安装依赖

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

### 5.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

COS_REGION=ap-beijing
COS_SECRET_ID=your_cos_secret_id
COS_SECRET_KEY=your_cos_secret_key
COS_BUCKET=your_cos_bucket
COS_BASE_URL=https://your-bucket.cos.ap-beijing.myqcloud.com
```

### 5.5 执行数据库迁移

```bash
alembic upgrade head
```

### 5.6 初始化管理员账号

```bash
python scripts/init_admin.py
```

默认管理员账号：

1. 用户名：`admin`
2. 密码：`Admin@123456`

第一次启动后请尽快修改密码。

### 5.7 启动后端服务

```bash
uvicorn main:app --reload
```

默认启动地址：

1. 服务地址：`http://127.0.0.1:8000`
2. API 前缀：`http://127.0.0.1:8000/api/v1`
3. 健康检查：`http://127.0.0.1:8000/health`

### 5.8 后端快速自检

可以先访问：

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

如果返回：

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

说明后端已经正常启动。

## 6. 后台管理端启动说明

### 6.1 进入后台目录

```bash
cd admin-web
```

### 6.2 安装依赖

```bash
npm install
```

### 6.3 启动开发服务

```bash
npm run dev
```

默认会输出一个本地地址，通常类似：

```text
http://127.0.0.1:5173
```

### 6.4 登录后台

使用管理员账号登录：

1. 用户名：`admin`
2. 密码：`Admin@123456`

后台当前已支持：

1. 登录
2. 待审核队列
3. 活动管理
4. 公告管理
5. 数据看板

## 7. 微信小程序启动说明

### 7.1 打开项目

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

```text
miniprogram/
```

### 7.2 检查接口地址

当前小程序默认使用本地接口：

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

默认地址为：

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

如果你的后端不是运行在本机，请改成实际地址。

### 7.3 开发者工具本地调试配置

如果你在本地联调，请在微信开发者工具中勾选：

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

否则会出现错误：

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

### 7.4 真机调试说明

真机调试时不要使用 `localhost`，因为：

1. 手机访问不到你电脑的 `localhost`
2. 微信小程序要求请求域名在后台配置合法域名

真机调试需要：

1. 使用一个外网可访问的后端地址
2. 最好使用 HTTPS
3. 在微信公众平台配置 `request 合法域名`

## 8. 推荐启动顺序

建议按下面顺序启动：

1. 启动 MySQL
2. 启动 Redis
3. 启动后端 `backend/`
4. 启动后台 `admin-web/`
5. 使用微信开发者工具打开 `miniprogram/`

## 9. 常见问题

### 9.1 小程序报错 `request:fail url not in domain list`

原因：

1. 当前请求域名不在微信合法域名列表里
2. 或开发者工具未关闭合法域名校验

解决方式：

1. 本地开发时在微信开发者工具里关闭域名校验
2. 真机或上线时，换成 HTTPS 域名并配置到微信公众平台

### 9.2 后台登录失败

检查：

1. 后端是否已启动
2. 是否已执行 `python scripts/init_admin.py`
3. 默认账号密码是否被修改

### 9.3 数据库迁移失败

检查：

1. `backend/.env` 中的 MySQL 配置是否正确
2. 数据库 `dating_app` 是否已创建
3. MySQL 服务是否已经启动

### 9.4 小程序图片不显示

当前代码已经清理了远程占位图依赖。

如果真实图片不显示，通常是：

1. 返回的图片地址不可访问
2. 图片域名不在微信合法域名配置中

## 10. 当前功能完成情况

当前已完成：

1. 用户登录、资料编辑、审核提交
2. 后台审核
3. 活动列表、详情、报名、我的活动
4. 匹配候选、感兴趣、我的匹配
5. AI 推荐基础能力
6. 公告列表、详情、后台公告管理
7. 后台活动管理、数据看板
8. 后端统一错误响应
9. 项目启动文档、验收清单、上线准备清单

当前仍建议继续补充：

1. 微信订阅消息
2. Redis 推荐缓存与频控
3. COS 真实上传
4. 更完整的后台用户管理与系统设置
5. 自动化测试
6. 生产部署验证

## 11. 相关文档

根目录已提供这些文档：

1. `相亲小程序开发详情.md`
2. `开发规划.md`
3. `功能差距清单.md`
4. `验收清单.md`
5. `上线准备清单.md`

建议使用顺序：

1. 先看 `README.md` 启动项目
2. 再按 `验收清单.md` 做联调
3. 最后按 `上线准备清单.md` 准备部署