taiyi/xiangqinxiaochengxu
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
master
xiangqinxiaochengxu/相亲小程序开发详情.md

1805 lines
54 KiB
Markdown
Raw Permalink Normal View History

第一次提交
2026-04-17 10:49:14 +08:00
# 相亲小程序 · 完整开发规格文档
> **文档用途**：本文档供 AI 编程助手直接执行，包含完整的功能清单、目录结构、数据库设计、API 接口、页面逻辑和开发注意事项。
> **技术栈**：微信小程序原生（微信开发者工具） + Python FastAPI 后端
> **阅读顺序**：先看第 1-3 节了解全局，再按模块逐节实现。
---
## 目录
1. [项目概览](https://claude.ai/chat/18b08d3b-0364-4e53-804b-61b4cf5b63d4#1-%E9%A1%B9%E7%9B%AE%E6%A6%82%E8%A7%88)
2. [目录结构](https://claude.ai/chat/18b08d3b-0364-4e53-804b-61b4cf5b63d4#2-%E7%9B%AE%E5%BD%95%E7%BB%93%E6%9E%84)
3. [数据库设计](https://claude.ai/chat/18b08d3b-0364-4e53-804b-61b4cf5b63d4#3-%E6%95%B0%E6%8D%AE%E5%BA%93%E8%AE%BE%E8%AE%A1)
4. [后端 API 规格](https://claude.ai/chat/18b08d3b-0364-4e53-804b-61b4cf5b63d4#4-%E5%90%8E%E7%AB%AF-api-%E8%A7%84%E6%A0%BC)
5. [前端页面规格](https://claude.ai/chat/18b08d3b-0364-4e53-804b-61b4cf5b63d4#5-%E5%89%8D%E7%AB%AF%E9%A1%B5%E9%9D%A2%E8%A7%84%E6%A0%BC)
6. [AI 匹配算法](https://claude.ai/chat/18b08d3b-0364-4e53-804b-61b4cf5b63d4#6-ai-%E5%8C%B9%E9%85%8D%E7%AE%97%E6%B3%95)
7. [微信能力集成](https://claude.ai/chat/18b08d3b-0364-4e53-804b-61b4cf5b63d4#7-%E5%BE%AE%E4%BF%A1%E8%83%BD%E5%8A%9B%E9%9B%86%E6%88%90)
8. [后台管理端](https://claude.ai/chat/18b08d3b-0364-4e53-804b-61b4cf5b63d4#8-%E5%90%8E%E5%8F%B0%E7%AE%A1%E7%90%86%E7%AB%AF)
9. [开发注意事项](https://claude.ai/chat/18b08d3b-0364-4e53-804b-61b4cf5b63d4#9-%E5%BC%80%E5%8F%91%E6%B3%A8%E6%84%8F%E4%BA%8B%E9%A1%B9)
10. [环境配置](https://claude.ai/chat/18b08d3b-0364-4e53-804b-61b4cf5b63d4#10-%E7%8E%AF%E5%A2%83%E9%85%8D%E7%BD%AE)
---
## 1. 项目概览
### 1.1 产品定位
线下相亲活动组织工具 + AI 辅助匹配平台。核心流程：
```
用户注册 → 填写资料 → 提交审核 → 审核通过 → 报名活动 / 参与匹配
```
### 1.2 技术栈总览
| 层 | 技术 | 说明 |
| ----- | ------------------------- | -------------------- |
| 小程序前端 | 微信小程序原生（WXML/WXSS/JS） | 使用微信开发者工具开发 |
| 后端框架 | Python 3.11 + FastAPI | RESTful API，async 支持 |
| 数据库 | MySQL 8.0 | 主数据库 |
| 缓存 | Redis 7.x | 会话、频控、热数据缓存 |
| ORM | SQLAlchemy 2.x (async) | 数据库操作 |
| 数据库迁移 | Alembic | 版本管理 |
| 文件存储 | 腾讯云 COS | 头像/活动图片存储 |
| 消息推送 | 微信订阅消息 | 审核结果、匹配成功通知 |
| 后台管理 | Vue3 + Element Plus（独立项目） | 管理员操作界面 |
### 1.3 用户角色
- **普通用户**：微信登录，填写资料，报名活动，参与匹配
- **管理员**：后台审核资料，管理活动，查看数据看板
- **超级管理员**：系统配置，管理员账号管理
---
## 2. 目录结构
### 2.1 小程序前端结构
```
miniprogram/
├── app.js # 全局入口，处理登录态初始化
├── app.json # 全局配置（TabBar、页面注册）
├── app.wxss # 全局样式
├── project.config.json # 项目配置
│
├── pages/
│ ├── home/ # 首页
│ │ ├── home.js
│ │ ├── home.wxml
│ │ ├── home.wxss
│ │ └── home.json
│ ├── activity/ # 活动列表页
│ │ ├── activity.js
│ │ ├── activity.wxml
│ │ ├── activity.wxss
│ │ └── activity.json
│ ├── activity-detail/ # 活动详情+报名页
│ │ └── ...
│ ├── match/ # 匹配主页
│ │ └── ...
│ ├── profile/ # 我的页面
│ │ └── ...
│ ├── profile-edit/ # 资料填写/编辑
│ │ └── ...
│ ├── audit-status/ # 审核状态追踪页
│ │ └── ...
│ ├── my-activities/ # 我报名的活动列表
│ │ └── ...
│ ├── my-matches/ # 我的匹配记录
│ │ └── ...
│ └── announcement/ # 公告详情页
│ └── ...
│
├── components/
│ ├── member-card/ # 会员卡片组件（首页随机展示用）
│ ├── activity-card/ # 活动卡片组件
│ ├── match-card/ # 匹配候选人卡片组件
│ ├── audit-badge/ # 认证/审核状态徽章
│ ├── progress-bar/ # 资料完整度进度条
│ └── empty-state/ # 空状态占位组件
│
└── utils/
├── request.js # 统一 HTTP 请求封装（含 token 刷新）
├── auth.js # 登录态管理
├── upload.js # 图片上传到 COS 封装
└── constants.js # 全局常量（API_BASE_URL 等）
```
### 2.2 后端结构
```
backend/
├── main.py # FastAPI 入口
├── requirements.txt
├── .env # 环境变量（不提交 git）
├── alembic.ini
├── alembic/
│ └── versions/ # 数据库迁移文件
│
├── app/
│ ├── __init__.py
│ ├── config.py # 配置读取（从 .env）
│ ├── database.py # 数据库连接、Session 工厂
│ ├── dependencies.py # FastAPI 依赖注入（current_user 等）
│ │
│ ├── models/ # SQLAlchemy ORM 模型
│ │ ├── __init__.py
│ │ ├── user.py
│ │ ├── activity.py
│ │ ├── registration.py
│ │ ├── match.py
│ │ └── announcement.py
│ │
│ ├── schemas/ # Pydantic 请求/响应模型
│ │ ├── __init__.py
│ │ ├── user.py
│ │ ├── activity.py
│ │ ├── match.py
│ │ └── common.py
│ │
│ ├── routers/ # 路由模块
│ │ ├── __init__.py
│ │ ├── auth.py # 登录/刷新 token
│ │ ├── users.py # 用户信息
│ │ ├── activities.py # 活动相关
│ │ ├── matches.py # 匹配相关
│ │ ├── announcements.py
│ │ ├── upload.py # 文件上传
│ │ └── admin/ # 后台接口（需 admin 权限）
│ │ ├── users.py
│ │ ├── activities.py
│ │ ├── matches.py
│ │ └── dashboard.py
│ │
│ ├── services/ # 业务逻辑层
│ │ ├── auth_service.py
│ │ ├── match_service.py # AI 匹配核心算法
│ │ ├── notify_service.py # 微信订阅消息发送
│ │ └── cos_service.py # 腾讯云 COS 操作
│ │
│ └── utils/
│ ├── security.py # JWT 生成/验证
│ └── wx_api.py # 微信 API 调用封装（code2session 等）
```
---
## 3. 数据库设计
> **所有表**均包含 `created_at DATETIME` 和 `updated_at DATETIME`（自动维护）。
> **字符集**：utf8mb4，排序规则：utf8mb4_unicode_ci。
### 3.1 users 表
```sql
CREATE TABLE users (
id INT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
openid VARCHAR(64) NOT NULL UNIQUE COMMENT '微信 openid',
unionid VARCHAR(64) COMMENT '微信 unionid（可选）',
-- 基础信息（用户填写）
nickname VARCHAR(50) COMMENT '昵称',
real_name VARCHAR(20) COMMENT '真实姓名（审核可见）',
gender TINYINT COMMENT '1=男 2=女',
birth_year SMALLINT COMMENT '出生年份',
city VARCHAR(30) COMMENT '所在城市',
height SMALLINT COMMENT '身高(cm)',
education TINYINT COMMENT '1=高中 2=大专 3=本科 4=硕士 5=博士',
job_industry VARCHAR(50) COMMENT '行业',
job_company VARCHAR(100) COMMENT '单位（仅匹配成功后展示）',
income_range TINYINT COMMENT '月收入段：1=<5k 2=5-10k 3=10-20k 4=20k+',
marriage_status TINYINT DEFAULT 1 COMMENT '1=未婚 2=离异 3=丧偶',
-- 性格与兴趣
personality_tags JSON COMMENT '性格标签数组，如["开朗","细心"]',
hobbies JSON COMMENT '爱好数组，如["旅游","读书","健身"]',
-- 价值观问卷答案
value_answers JSON COMMENT '价值观问卷，格式: {"q1":2,"q2":1,...}',
-- 择偶偏好（用于匹配过滤）
prefer_age_min SMALLINT COMMENT '期望对方最小出生年份（越大越年轻）',
prefer_age_max SMALLINT COMMENT '期望对方最大出生年份',
prefer_city VARCHAR(30) COMMENT '期望城市，null=不限',
prefer_education TINYINT COMMENT '期望最低学历，null=不限',
-- 自我介绍
self_intro TEXT COMMENT '自我介绍（500字内）',
-- 头像
avatar_url VARCHAR(500) COMMENT 'COS 头像 URL',
avatar_blur_url VARCHAR(500) COMMENT '模糊头像 URL（AI 生成或后端处理）',
-- 状态
audit_status TINYINT DEFAULT 0 COMMENT '0=未提交 1=待审核 2=审核通过 3=审核驳回',
audit_remark VARCHAR(500) COMMENT '驳回原因',
audit_time DATETIME COMMENT '审核时间',
auditor_id INT UNSIGNED COMMENT '审核人 admin ID',
-- 账号状态
is_active TINYINT DEFAULT 1 COMMENT '1=正常 0=封禁',
ban_reason VARCHAR(200),
-- 统计
profile_completeness TINYINT DEFAULT 0 COMMENT '资料完整度 0-100',
-- 微信订阅消息
subscribe_audit TINYINT DEFAULT 0 COMMENT '是否订阅审核结果通知',
subscribe_match TINYINT DEFAULT 0 COMMENT '是否订阅匹配成功通知',
created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
updated_at DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
INDEX idx_audit_status (audit_status),
INDEX idx_gender_city (gender, city)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
```
### 3.2 activities 表
```sql
CREATE TABLE activities (
id INT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
title VARCHAR(100) NOT NULL COMMENT '活动标题',
description TEXT COMMENT '活动详情（富文本/Markdown）',
category VARCHAR(20) COMMENT '类型：outdoor/dining/culture/sport/other',
location VARCHAR(200) COMMENT '活动地点',
cover_image VARCHAR(500) COMMENT '封面图 COS URL',
start_time DATETIME NOT NULL COMMENT '活动开始时间',
end_time DATETIME NOT NULL COMMENT '活动结束时间',
signup_deadline DATETIME COMMENT '报名截止时间',
capacity_male SMALLINT DEFAULT 0 COMMENT '男性名额（0=不限）',
capacity_female SMALLINT DEFAULT 0 COMMENT '女性名额（0=不限）',
-- 匹配窗口
match_window_hours INT DEFAULT 48 COMMENT '活动结束后开放匹配的小时数',
-- 状态
status TINYINT DEFAULT 0 COMMENT '0=草稿 1=报名中 2=报名截止 3=进行中 4=已结束',
is_published TINYINT DEFAULT 0 COMMENT '是否在小程序展示',
-- 报名要求
require_audit TINYINT DEFAULT 1 COMMENT '是否要求资料审核通过才能报名',
created_by INT UNSIGNED COMMENT '创建人 admin ID',
created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
updated_at DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
INDEX idx_status_published (status, is_published),
INDEX idx_start_time (start_time)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
```
### 3.3 registrations 表
```sql
CREATE TABLE registrations (
id INT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
user_id INT UNSIGNED NOT NULL,
activity_id INT UNSIGNED NOT NULL,
status TINYINT DEFAULT 1 COMMENT '1=待确认 2=已确认 3=已取消 4=已签到',
checked_in_at DATETIME COMMENT '签到时间',
created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
updated_at DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
UNIQUE KEY uk_user_activity (user_id, activity_id),
INDEX idx_activity_id (activity_id),
FOREIGN KEY (user_id) REFERENCES users(id),
FOREIGN KEY (activity_id) REFERENCES activities(id)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
```
### 3.4 match_likes 表（单向感兴趣记录）
```sql
CREATE TABLE match_likes (
id INT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
from_user_id INT UNSIGNED NOT NULL COMMENT '发起感兴趣的用户',
to_user_id INT UNSIGNED NOT NULL COMMENT '被感兴趣的用户',
source VARCHAR(20) DEFAULT 'manual' COMMENT 'manual=手动 ai=AI推荐',
created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
UNIQUE KEY uk_like (from_user_id, to_user_id),
INDEX idx_to_user (to_user_id),
FOREIGN KEY (from_user_id) REFERENCES users(id),
FOREIGN KEY (to_user_id) REFERENCES users(id)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
```
### 3.5 matches 表（双向匹配成功记录）
```sql
CREATE TABLE matches (
id INT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
user_a_id INT UNSIGNED NOT NULL COMMENT '较小 user_id（保证唯一性）',
user_b_id INT UNSIGNED NOT NULL COMMENT '较大 user_id',
match_score DECIMAL(5,2) COMMENT 'AI 匹配分 0-100',
match_type VARCHAR(20) DEFAULT 'manual' COMMENT 'manual/ai',
source_activity_id INT UNSIGNED COMMENT '来源活动（如果有）',
-- 双方是否查看了对方信息
a_viewed TINYINT DEFAULT 0,
b_viewed TINYINT DEFAULT 0,
matched_at DATETIME DEFAULT CURRENT_TIMESTAMP,
UNIQUE KEY uk_match (user_a_id, user_b_id),
INDEX idx_user_a (user_a_id),
INDEX idx_user_b (user_b_id),
FOREIGN KEY (user_a_id) REFERENCES users(id),
FOREIGN KEY (user_b_id) REFERENCES users(id)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
```
### 3.6 announcements 表
```sql
CREATE TABLE announcements (
id INT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
title VARCHAR(100) NOT NULL,
content TEXT NOT NULL COMMENT 'Markdown 内容',
is_pinned TINYINT DEFAULT 0 COMMENT '是否置顶',
is_published TINYINT DEFAULT 1,
created_by INT UNSIGNED,
created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
updated_at DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
```
### 3.7 admins 表
```sql
CREATE TABLE admins (
id INT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
username VARCHAR(50) NOT NULL UNIQUE,
password_hash VARCHAR(128) NOT NULL COMMENT 'bcrypt hash',
role TINYINT DEFAULT 1 COMMENT '1=普通管理员 2=超级管理员',
is_active TINYINT DEFAULT 1,
last_login DATETIME,
created_at DATETIME DEFAULT CURRENT_TIMESTAMP
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
```
---
## 4. 后端 API 规格
### 4.1 通用规范
```
Base URL（开发）: http://localhost:8000/api/v1
Base URL（生产）: https://your-domain.com/api/v1
认证方式: Bearer Token（JWT）
Content-Type: application/json
统一响应格式:
{
"code": 0, // 0=成功，非0=错误
"message": "ok",
"data": {} // 业务数据
}
错误码约定:
1001 - token 无效或过期
1002 - 权限不足
1003 - 资源不存在
1004 - 参数校验失败
1005 - 业务逻辑错误（message 中包含具体原因）
```
### 4.2 认证接口
#### POST /auth/wx-login
微信登录，通过 code 换取系统 JWT token。
**请求体：**
```json
{
"code": "微信登录临时code",
"subscribe_audit": true, // 是否订阅审核通知（首次登录时传）
"subscribe_match": true
}
```
**响应数据：**
```json
{
"access_token": "eyJ...",
"token_type": "bearer",
"expires_in": 7200,
"user_id": 123,
"audit_status": 0,
"is_new_user": true
}
```
**后端实现要点：**
- 调用微信 `code2session` 接口获取 `openid`
- 用 `openid` 查用户，不存在则自动创建
- 返回 JWT，payload 包含 `user_id`, `openid`, `exp`
#### POST /auth/refresh
刷新 token（在 access_token 快过期时调用）。
---
### 4.3 用户接口
#### GET /users/me
获取当前用户完整信息（含审核状态）。
**响应数据：**
```json
{
"id": 123,
"nickname": "小明",
"gender": 1,
"birth_year": 1995,
"city": "北京",
"height": 175,
"education": 3,
"job_industry": "互联网",
"personality_tags": ["开朗", "细心"],
"hobbies": ["旅游", "读书"],
"self_intro": "...",
"avatar_url": "https://...",
"audit_status": 2,
"audit_remark": null,
"profile_completeness": 85
}
```
#### PUT /users/me
更新当前用户信息。提交后若 `audit_status` 为 0 或 3，自动置为 1（待审核）。
**请求体（所有字段均可选，仅传需要更新的）：**
```json
{
"nickname": "小明",
"gender": 1,
"birth_year": 1995,
"city": "北京",
"height": 175,
"education": 3,
"job_industry": "互联网",
"job_company": "某公司",
"income_range": 3,
"personality_tags": ["开朗"],
"hobbies": ["旅游"],
"value_answers": {"q1": 2, "q2": 1, "q3": 3, "q4": 2},
"prefer_age_min": 1990,
"prefer_age_max": 2000,
"prefer_city": "北京",
"self_intro": "..."
}
```
**后端实现要点：**
- 更新后重新计算 `profile_completeness`（见计算规则 §6）
- 若 `audit_status` 为 2（已通过），用户修改资料后状态重置为 1（待审核）
#### POST /users/submit-audit
提交资料审核申请（状态从0/3变为1）。需要头像已上传。
#### GET /users/public/{user_id}
获取其他用户的公开信息（根据匹配阶段返回不同字段，见信息分级规则）。
**信息分级规则（后端强制执行）：**
- 未匹配：返回 nickname, birth_year范围, city, personality_tags, avatar_blur_url
- 单向感兴趣（我对他/她表示过兴趣）：额外返回 avatar_url, education, hobbies
- 双向匹配成功：额外返回 job_industry, job_company, self_intro, income_range
---
### 4.4 活动接口
#### GET /activities
获取活动列表。
**Query 参数：**
```
status: 1=报名中 4=已结束 (可选，不传返回所有已发布)
page: 页码，默认1
page_size: 每页数量，默认10
```
**响应数据（列表项）：**
```json
{
"id": 1,
"title": "春日户外约会",
"category": "outdoor",
"cover_image": "https://...",
"start_time": "2025-04-20T14:00:00",
"end_time": "2025-04-20T18:00:00",
"signup_deadline": "2025-04-19T23:59:59",
"location": "北京朝阳公园",
"status": 1,
"capacity_male": 20,
"capacity_female": 20,
"registered_male": 15,
"registered_female": 12,
"is_registered": false, // 当前用户是否已报名
"can_register": true // 是否可以报名（考虑审核状态、名额等）
}
```
#### GET /activities/{id}
获取活动详情，包含已报名人员的模糊头像列表（最多展示8个异性）。
#### POST /activities/{id}/register
报名活动。
**后端校验（按顺序检查，失败立即返回对应错误）：**
1. 活动是否存在且已发布
2. 活动报名是否未截止（`signup_deadline > now`）
3. 活动 `require_audit=1` 时，用户 `audit_status` 须为 2
4. 对应性别名额是否未满
5. 用户是否已报名过该活动（幂等处理：已报名则返回成功）
**成功响应：**
```json
{
"registration_id": 456,
"status": 1,
"message": "报名成功，等待确认"
}
```
#### DELETE /activities/{id}/register
取消报名（活动开始前24小时内不可取消）。
---
### 4.5 匹配接口
#### GET /matches/candidates
获取当日推荐候选人列表（异性，每天最多返回10条，Redis 缓存当日推荐列表）。
**Query 参数：**
```
source: manual（手动浏览） | ai（AI推荐）
```
**响应数据（列表项，Level 1 信息）：**
```json
{
"user_id": 456,
"nickname": "小花",
"birth_year_range": "1993-1997", // 模糊处理，5年范围
"city": "北京",
"personality_tags": ["温柔", "活泼"],
"avatar_blur_url": "https://...", // 模糊头像
"match_score": 87.5, // AI 推荐时返回
"match_reasons": ["同样喜欢旅游", "生活节奏相近"] // AI 推荐时返回
}
```
**后端实现要点：**
- 过滤已点过"不感兴趣"的用户
- 过滤已互相匹配成功的用户
- 今日已展示过的用户不重复出现（Redis `SET` 记录）
#### POST /matches/like
对某用户表示感兴趣（触发双向检查）。
**请求体：**
```json
{
"to_user_id": 456,
"source": "manual"
}
```
**响应数据：**
```json
{
"is_mutual": true, // 是否产生了双向匹配
"match_id": 789, // 匹配成功时返回 match_id
"match_info": { // 匹配成功时返回对方 Level 2 信息
"nickname": "小花",
"avatar_url": "https://...",
"education": 3,
"hobbies": ["旅游"]
}
}
```
**后端实现要点：**
1. 写入 `match_likes` 表
2. 查询反向是否存在 `match_likes`（`from_user_id=to_user_id, to_user_id=from_user_id`）
3. 若存在，在 `matches` 表创建记录（user_a_id 取较小值）
4. 匹配成功后发送微信订阅消息给双方（异步任务）
#### POST /matches/ai-suggest
触发 AI 推荐，返回得分最高的候选人列表（最多5个）。
**响应同 /matches/candidates，但包含详细 match_reasons。**
#### GET /matches/my
获取我的匹配成功列表。
**响应数据（列表项）：**
```json
{
"match_id": 789,
"matched_at": "2025-04-15T20:30:00",
"other_user": {
"user_id": 456,
"nickname": "小花",
"avatar_url": "https://...", // 匹配成功后展示真实头像
"education": 3,
"city": "北京",
"hobbies": ["旅游"]
}
}
```
#### GET /matches/{match_id}/detail
获取匹配详情（Level 3 完整信息，仅匹配双方可访问）。
---
### 4.6 公告接口
#### GET /announcements
获取公告列表（置顶的排在前面）。
```
page, page_size 参数同活动接口
```
#### GET /announcements/{id}
获取公告详情。
---
### 4.7 上传接口
#### POST /upload/avatar
上传用户头像。
**请求**：multipart/form-data，字段名 `file`，支持 jpg/png，最大 5MB。
**后端处理：**
1. 接收文件
2. 压缩到 800x800 以内（使用 Pillow）
3. 上传到腾讯云 COS，路径：`avatars/{user_id}/{timestamp}.jpg`
4. 生成模糊版本（Pillow 高斯模糊，radius=15）上传到 COS
5. 更新 users 表 `avatar_url` 和 `avatar_blur_url`
**响应：**
```json
{
"avatar_url": "https://cos.../avatars/123/1713200000.jpg",
"avatar_blur_url": "https://cos.../avatars/123/1713200000_blur.jpg"
}
```
#### POST /upload/activity-cover
上传活动封面图（需 admin token）。
---
### 4.8 后台管理接口
所有 `/admin/*` 接口需要 `admin` 角色的 JWT token。
#### POST /admin/auth/login
管理员账号密码登录，返回 JWT。
#### GET /admin/dashboard
数据看板数据。
**响应数据：**
```json
{
"total_users": 1250,
"active_users_7d": 380,
"pending_audit": 23,
"total_activities": 45,
"ongoing_activities": 3,
"total_matches": 890,
"match_rate": 0.312,
"user_trend": [
{"date": "2025-04-01", "count": 12},
...
],
"match_trend": [...]
}
```
#### GET /admin/users
用户列表，支持搜索和过滤。
```
Query: keyword(昵称/真实姓名), audit_status, gender, page, page_size
```
#### GET /admin/users/{id}
获取用户完整信息（含 job_company 等敏感字段）。
#### PUT /admin/users/{id}/audit
审核用户资料。
**请求体：**
```json
{
"audit_status": 2, // 2=通过 3=驳回
"audit_remark": "照片不清晰，请重新上传" // 驳回时必填
}
```
**后端操作：**
1. 更新 `audit_status`, `audit_remark`, `audit_time`, `auditor_id`
2. 若用户订阅了审核通知，发送微信订阅消息
#### PUT /admin/users/{id}/ban
封禁/解封用户。
#### GET /admin/activities
活动列表（含草稿）。
#### POST /admin/activities
创建活动。
**请求体（完整字段）：**
```json
{
"title": "春日约会",
"description": "Markdown 内容",
"category": "outdoor",
"location": "北京朝阳公园",
"cover_image": "https://...",
"start_time": "2025-04-20T14:00:00",
"end_time": "2025-04-20T18:00:00",
"signup_deadline": "2025-04-19T23:59:59",
"capacity_male": 20,
"capacity_female": 20,
"match_window_hours": 48,
"require_audit": true,
"is_published": false
}
```
#### PUT /admin/activities/{id}
修改活动（已结束的活动不可修改）。
#### PUT /admin/activities/{id}/publish
发布/下架活动（`is_published` 切换）。
#### GET /admin/matches
匹配记录列表，支持按用户ID、日期过滤。
#### GET /admin/system/config
获取系统配置（AI 权重、每日推荐上限等）。
#### PUT /admin/system/config
更新系统配置。
---
## 5. 前端页面规格
### 5.1 app.json 配置
```json
{
"pages": [
"pages/home/home",
"pages/activity/activity",
"pages/match/match",
"pages/profile/profile",
"pages/activity-detail/activity-detail",
"pages/profile-edit/profile-edit",
"pages/audit-status/audit-status",
"pages/my-activities/my-activities",
"pages/my-matches/my-matches",
"pages/announcement/announcement"
],
"tabBar": {
"color": "#999999",
"selectedColor": "#E8593C",
"borderStyle": "white",
"list": [
{
"pagePath": "pages/home/home",
"text": "首页",
"iconPath": "assets/icons/home.png",
"selectedIconPath": "assets/icons/home-active.png"
},
{
"pagePath": "pages/activity/activity",
"text": "活动",
"iconPath": "assets/icons/activity.png",
"selectedIconPath": "assets/icons/activity-active.png"
},
{
"pagePath": "pages/match/match",
"text": "匹配",
"iconPath": "assets/icons/match.png",
"selectedIconPath": "assets/icons/match-active.png"
},
{
"pagePath": "pages/profile/profile",
"text": "我的",
"iconPath": "assets/icons/profile.png",
"selectedIconPath": "assets/icons/profile-active.png"
}
]
},
"window": {
"backgroundTextStyle": "light",
"navigationBarBackgroundColor": "#fff",
"navigationBarTitleText": "相遇",
"navigationBarTextStyle": "black"
}
}
```
### 5.2 app.js 全局初始化逻辑
```javascript
// app.js 核心逻辑（伪代码描述）
App({
globalData: {
userInfo: null,
token: null,
baseUrl: 'https://your-domain.com/api/v1'
},
onLaunch() {
// 1. 检查本地 token
const token = wx.getStorageSync('token');
if (token) {
this.globalData.token = token;
// 2. 验证 token 有效性（调用 /users/me）
// 3. 若失败则重新登录
} else {
this.wxLogin();
}
},
async wxLogin() {
// 1. wx.login() 获取 code
// 2. 调用后端 /auth/wx-login
// 3. 存储 token 到 globalData 和 storage
// 4. 若是新用户，跳转到资料填写页
}
});
```
### 5.3 首页（home）
**功能模块：**
1. **活动预告轮播**（头部 swiper）
- 展示 `status=1`（报名中）的已发布活动
- 每张卡片显示：封面图、标题、时间、剩余名额（「还剩 N 个名额」）
- 点击跳转到活动详情页
2. **公告栏**（轮播或单行滚动）
- 展示最新置顶公告标题
- 点击跳转公告详情页
3. **会员展示区**（随机卡片列表）
- 调用 `GET /matches/candidates?source=manual`
- 展示 Level 1 信息：模糊头像、昵称、城市、性格标签
- 点击卡片跳转到对应用户的公开页（弹出半屏 modal）
**页面加载逻辑：**
```
onLoad:
1. 检查登录态，未登录则调用 app.wxLogin()
2. 并发请求：GET /activities?status=1&page_size=5 和 GET /announcements?page_size=3
3. 展示轮播和公告
onPullDownRefresh:
刷新活动和会员列表
```
### 5.4 活动页（activity）
**功能模块：**
1. **分类 Tab**：全部 / 户外 / 餐饮 / 文化 / 体育
2. **活动卡片列表**（上拉加载更多）
3. **活动状态标签**：报名中（绿）/ 即将截止（橙）/ 已结束（灰）
**活动详情页（activity-detail）：**
1. 封面图（全宽展示）
2. 活动基本信息（时间、地点、人数）
3. 名额进度条：`男 15/20 · 女 12/20`
4. 已报名人员预览（模糊头像列表，最多8个异性）
5. 活动详情内容（富文本渲染）
6. **底部报名按钮**，状态：
- 未审核通过：「完善资料后可报名」→ 点击跳转资料页
- 可报名：「立即报名」
- 已报名：「已报名 ✓」
- 名额已满：「名额已满」
- 已截止：「报名已截止」
### 5.5 匹配页（match）
**布局：**
1. **顶部 AI 匹配按钮**（醒目展示）
2. **今日推荐列表**（卡片式，每张展示 Level 1 信息）
3. 每张卡片底部：「感兴趣 ♥」和「跳过」按钮
**AI 匹配按钮逻辑：**
```
点击 → 调用 POST /matches/ai-suggest
→ 展示匹配结果（含匹配分数和共同点）
→ 用户可逐个查看并点击感兴趣
```
**点击「感兴趣」逻辑：**
```
1. 调用 POST /matches/like
2. 若 is_mutual=true：
- 弹出「匹配成功！」动画弹窗
- 展示对方 Level 2 信息
- 提示「可在「我的匹配」中查看完整信息」
3. 若 is_mutual=false：
- 卡片消失，显示「已发送喜欢」
```
**用户信息弹窗（点击卡片展开）：**
- 展示 Level 1 信息（未点感兴趣前）
- 展示 Level 2 信息（已点感兴趣后）
### 5.6 我的页面（profile）
**布局（从上到下）：**
1. **用户卡片**：头像 + 昵称 + 审核状态徽章（待审核/已通过/未提交）
2. **资料完整度进度条**：`85% 完整，继续完善提升匹配率 →`
3. **功能菜单列表**：
- 编辑资料 → `/profile-edit`
- 审核状态 → `/audit-status`
- 我的活动 → `/my-activities`
- 匹配记录 → `/my-matches`
- 隐私设置（暂时展示，功能后续迭代）
**审核状态页（audit-status）展示：**
```
状态为 0（未提交）: 引导填写资料并提交
状态为 1（待审核）: 展示进度提示「预计 4 小时内完成审核」
状态为 2（已通过）: 绿色勾，展示通过时间
状态为 3（驳回） : 红色提示，展示驳回原因，「重新提交」按钮
```
### 5.7 资料填写页（profile-edit）
**分步骤填写（Step Indicator 展示进度）：**
- Step 1：基本信息（性别、出生年、城市、身高、学历）
- Step 2：职业信息（行业、公司名称）
- Step 3：性格与兴趣（标签多选，爱好最多选8个）
- Step 4：价值观问卷（4道场景题，单选）
- Step 5：择偶偏好（年龄范围、城市、学历要求）
- Step 6：头像上传 + 自我介绍
**每步保存逻辑：**
- 每步完成后立即调用 `PUT /users/me` 保存（非全部填完才保存）
- 允许用户跳步，但提交审核时校验必填字段
**头像上传：**
```
wx.chooseMedia → 压缩 → 上传到后端 /upload/avatar
→ 后端处理并存 COS → 返回 URL → 本地展示
```
**价值观问卷题目（4 题）：**
```
Q1. 周末你更倾向于？
A. 宅在家休息看剧 B. 约三五好友聚餐 C. 户外运动或旅行
Q2. 婚后与父母同住这件事，你的态度是？
A. 希望独立居住 B. 可以接受偶尔同住 C. 愿意长期同住
Q3. 对于两人的经济管理方式，你倾向于？
A. 各自管理各自的 B. 合并统一管理 C. 部分共用部分独立
Q4. 关于要孩子这件事？
A. 明确想要孩子 B. 顺其自然 C. 目前不想要
```
---
## 6. AI 匹配算法
### 6.1 完整实现（match_service.py）
```python
# app/services/match_service.py
from typing import List, Dict
import math
from app.models.user import User
# 各维度权重（可从数据库 system_config 表读取，实现动态调参）
WEIGHTS = {
"age": 0.20,
"hobbies": 0.18,
"values": 0.18,
"education": 0.14,
"activity": 0.12, # 用户活跃度
"location": 0.10,
"height": 0.08,
}
def calculate_match_score(user_a: User, user_b: User) -> Dict:
"""
计算两个用户的匹配分数（0-100）。
user_a 是发起匹配的用户，user_b 是候选人。
返回: {"score": 87.5, "reasons": ["同样喜欢旅游"]}
"""
scores = {}
reasons = []
# 1. 年龄契合度（基于对方的择偶偏好）
age_score = _age_score(user_a, user_b)
scores["age"] = age_score
# 2. 兴趣重叠度（Jaccard 相似度）
hobby_score, hobby_overlap = _hobby_score(user_a, user_b)
scores["hobbies"] = hobby_score
if hobby_overlap:
reasons.append(f"都喜欢{hobby_overlap[0]}")
# 3. 价值观相似度（问卷答案加权欧氏距离）
value_score, value_reason = _value_score(user_a, user_b)
scores["values"] = value_score
if value_reason:
reasons.append(value_reason)
# 4. 学历背景（符合对方偏好加分）
scores["education"] = _education_score(user_a, user_b)
# 5. 活跃度（最近 7 天有登录记录）
scores["activity"] = _activity_score(user_b)
# 6. 地理位置（同城 100，同省 60，跨省 20）
location_score = _location_score(user_a, user_b)
scores["location"] = location_score
if location_score == 100:
reasons.append("同城")
# 7. 身高偏好
scores["height"] = _height_score(user_a, user_b)
# 加权求和
total = sum(scores[dim] * WEIGHTS[dim] for dim in scores)
return {
"score": round(total, 1),
"reasons": reasons[:3] # 最多返回3条理由
}
def _age_score(user_a: User, user_b: User) -> float:
"""检查 user_b 的年龄是否在 user_a 的择偶年龄偏好范围内"""
if not user_b.birth_year:
return 50.0
if user_a.prefer_age_min and user_b.birth_year < user_a.prefer_age_min:
return 0.0
if user_a.prefer_age_max and user_b.birth_year > user_a.prefer_age_max:
return 0.0
# 在偏好范围内，越接近中间值分越高
if user_a.prefer_age_min and user_a.prefer_age_max:
mid = (user_a.prefer_age_min + user_a.prefer_age_max) / 2
diff = abs(user_b.birth_year - mid)
half_range = (user_a.prefer_age_max - user_a.prefer_age_min) / 2
return max(0, 100 - (diff / half_range) * 50)
return 80.0
def _hobby_score(user_a: User, user_b: User):
"""Jaccard 相似度计算兴趣重叠"""
hobbies_a = set(user_a.hobbies or [])
hobbies_b = set(user_b.hobbies or [])
if not hobbies_a or not hobbies_b:
return 30.0, []
intersection = hobbies_a & hobbies_b
union = hobbies_a | hobbies_b
jaccard = len(intersection) / len(union)
return round(jaccard * 100, 1), list(intersection)
def _value_score(user_a: User, user_b: User):
"""价值观问卷：对应题目答案相同则加分"""
answers_a = user_a.value_answers or {}
answers_b = user_b.value_answers or {}
if not answers_a or not answers_b:
return 50.0, None
total_q = 4 # 总题目数
matched = 0
for q in ["q1", "q2", "q3", "q4"]:
if answers_a.get(q) == answers_b.get(q):
matched += 1
score = (matched / total_q) * 100
reason = None
if matched >= 3:
reason = "生活节奏相近"
elif matched >= 2:
reason = "价值观较为一致"
return round(score, 1), reason
def _education_score(user_a: User, user_b: User) -> float:
"""user_b 的学历是否达到 user_a 的偏好"""
if not user_a.prefer_education:
return 80.0
if not user_b.education:
return 40.0
if user_b.education >= user_a.prefer_education:
return 100.0
# 每差一级扣 25 分
diff = user_a.prefer_education - user_b.education
return max(0, 100 - diff * 25)
def _activity_score(user_b: User) -> float:
"""基于最近活跃时间评分"""
from datetime import datetime, timedelta
if not user_b.updated_at:
return 30.0
days_inactive = (datetime.now() - user_b.updated_at).days
if days_inactive <= 3:
return 100.0
elif days_inactive <= 7:
return 80.0
elif days_inactive <= 30:
return 50.0
return 20.0
def _location_score(user_a: User, user_b: User) -> float:
if not user_a.city or not user_b.city:
return 50.0
if user_a.city == user_b.city:
return 100.0
# 简单实现：同省判断（实际可接入城市数据库）
# 此处以城市名前两字作为省份简单判断
if user_a.city[:2] == user_b.city[:2]:
return 60.0
return 20.0
def _height_score(user_a: User, user_b: User) -> float:
"""简单身高偏好：女性用户对男性 175+ 额外加分"""
if not user_b.height:
return 50.0
if user_a.gender == 2 and user_b.gender == 1: # 女看男
if user_b.height >= 175:
return 100.0
elif user_b.height >= 170:
return 70.0
return 40.0
return 70.0 # 其他情况默认中等分
def get_ai_candidates(
current_user: User,
all_candidates: List[User],
limit: int = 5,
diversity_ratio: float = 0.3
) -> List[Dict]:
"""
获取 AI 推荐候选人列表。
diversity_ratio: 多样性候选人比例（避免推荐列表同质化）
"""
scored = []
for candidate in all_candidates:
result = calculate_match_score(current_user, candidate)
scored.append({
"user": candidate,
"score": result["score"],
"reasons": result["reasons"]
})
scored.sort(key=lambda x: x["score"], reverse=True)
# 主列表：高分候选
main_count = math.ceil(limit * (1 - diversity_ratio))
main_list = scored[:main_count]
# 多样性候选：从 main_count+1 到 main_count+10 中随机取
import random
diverse_pool = scored[main_count:main_count + 10]
diverse_count = limit - main_count
diverse_list = random.sample(diverse_pool, min(diverse_count, len(diverse_pool)))
return main_list + diverse_list
def calculate_profile_completeness(user: User) -> int:
"""
计算用户资料完整度（0-100）。
各字段权重不同，越重要的字段权重越高。
"""
fields = {
"nickname": 5,
"gender": 5,
"birth_year": 5,
"city": 5,
"height": 3,
"education": 5,
"job_industry": 5,
"personality_tags": 8, # 至少3个
"hobbies": 8, # 至少3个
"value_answers": 10, # 4题全答完
"avatar_url": 15, # 头像权重最高
"self_intro": 8,
"prefer_age_min": 3,
"prefer_city": 3,
"prefer_education": 3,
"job_company": 4,
"income_range": 5,
}
total_weight = sum(fields.values())
earned = 0
for field, weight in fields.items():
val = getattr(user, field, None)
if field == "personality_tags":
if val and len(val) >= 3:
earned += weight
elif val and len(val) >= 1:
earned += weight * 0.5
elif field == "hobbies":
if val and len(val) >= 3:
earned += weight
elif val and len(val) >= 1:
earned += weight * 0.5
elif field == "value_answers":
if val and len(val) >= 4:
earned += weight
elif val and len(val) >= 2:
earned += weight * 0.5
elif val:
earned += weight
return round((earned / total_weight) * 100)
```
---
## 7. 微信能力集成
### 7.1 登录流程（完整实现）
```python
# app/utils/wx_api.py
import httpx
from app.config import settings
async def code2session(code: str) -> dict:
"""
调用微信 code2session 接口获取 openid
返回: {"openid": "xxx", "session_key": "xxx"}
"""
url = "https://api.weixin.qq.com/sns/jscode2session"
params = {
"appid": settings.WX_APPID,
"secret": settings.WX_SECRET,
"js_code": code,
"grant_type": "authorization_code"
}
async with httpx.AsyncClient() as client:
resp = await client.get(url, params=params)
data = resp.json()
if "errcode" in data and data["errcode"] != 0:
raise ValueError(f"微信登录失败: {data.get('errmsg')}")
return data
```
### 7.2 订阅消息发送
```python
# app/services/notify_service.py
import httpx
from app.config import settings
# 需在微信公众平台申请的订阅消息模板 ID
TEMPLATE_AUDIT_RESULT = "your_audit_template_id" # 审核结果通知模板
TEMPLATE_MATCH_SUCCESS = "your_match_template_id" # 匹配成功通知模板
async def get_access_token() -> str:
"""获取微信接口调用凭证（需加 Redis 缓存，有效期 2 小时）"""
url = "https://api.weixin.qq.com/cgi-bin/token"
params = {
"grant_type": "client_credential",
"appid": settings.WX_APPID,
"secret": settings.WX_SECRET
}
async with httpx.AsyncClient() as client:
resp = await client.get(url, params=params)
return resp.json()["access_token"]
async def send_audit_result(openid: str, passed: bool, remark: str = ""):
"""发送审核结果订阅消息"""
access_token = await get_access_token()
url = f"https://api.weixin.qq.com/cgi-bin/message/subscribe/send?access_token={access_token}"
payload = {
"touser": openid,
"template_id": TEMPLATE_AUDIT_RESULT,
"miniprogram_state": "formal",
"lang": "zh_CN",
"data": {
"thing1": {"value": "资料审核结果通知"},
"phrase2": {"value": "审核通过" if passed else "审核未通过"},
"thing3": {"value": remark or ("恭喜，您的资料已通过审核！" if passed else "请根据提示修改后重新提交")},
}
}
async with httpx.AsyncClient() as client:
await client.post(url, json=payload)
async def send_match_success(openid: str, other_nickname: str):
"""发送匹配成功订阅消息"""
access_token = await get_access_token()
url = f"https://api.weixin.qq.com/cgi-bin/message/subscribe/send?access_token={access_token}"
payload = {
"touser": openid,
"template_id": TEMPLATE_MATCH_SUCCESS,
"page": "pages/my-matches/my-matches", # 点击消息跳转页
"miniprogram_state": "formal",
"data": {
"name3": {"value": other_nickname},
"thing4": {"value": "你们互相感兴趣，匹配成功啦！快去查看吧"},
}
}
async with httpx.AsyncClient() as client:
await client.post(url, json=payload)
```
### 7.3 前端请求封装
```javascript
// utils/request.js
const app = getApp();
const request = (options) => {
return new Promise((resolve, reject) => {
const token = wx.getStorageSync('token');
wx.request({
url: `${app.globalData.baseUrl}${options.url}`,
method: options.method || 'GET',
data: options.data || {},
header: {
'Content-Type': 'application/json',
'Authorization': token ? `Bearer ${token}` : ''
},
success(res) {
if (res.statusCode === 401) {
// Token 失效，重新登录
wx.removeStorageSync('token');
app.wxLogin();
reject(new Error('登录已过期'));
return;
}
if (res.data.code !== 0) {
wx.showToast({ title: res.data.message || '请求失败', icon: 'none' });
reject(res.data);
return;
}
resolve(res.data.data);
},
fail(err) {
wx.showToast({ title: '网络异常，请重试', icon: 'none' });
reject(err);
}
});
});
};
export default request;
```
---
## 8. 后台管理端
> 后台管理使用独立的 Vue3 + Element Plus 项目（非小程序）。以下是关键页面规格。
### 8.1 页面列表
|路由|页面|核心功能|
|---|---|---|
|`/login`|管理员登录|账号密码登录|
|`/dashboard`|数据看板|用户趋势、匹配率、审核积压量图表|
|`/users`|用户管理|搜索、筛选、查看详情|
|`/users/audit`|待审核队列|重点页面，快速审核|
|`/activities`|活动列表|增删改查、发布/下架|
|`/activities/new`|创建活动|表单|
|`/matches`|匹配记录|查看所有匹配，可按用户筛选|
|`/announcements`|公告管理|增删改查|
|`/settings`|系统设置|AI 权重调参|
### 8.2 待审核队列页面逻辑
这是管理员最高频使用的页面，需优化操作效率：
1. 列表展示待审核用户（按提交时间升序，越早越靠前）
2. 显示已等待时长（超过 4 小时标红提示 SLA 警告）
3. 点击用户展开侧边栏，显示完整资料和头像
4. 侧边栏操作：**通过** 按钮（绿色）+ **驳回** 按钮（红色，点击后弹出输入框填写原因）
5. 操作完成后自动加载下一条
---
## 9. 开发注意事项
### 9.1 微信小程序开发注意事项
```
【安全域名配置】
- 微信公众平台 → 开发管理 → 开发设置 → 服务器域名
- request 合法域名：填入后端服务器域名（必须 HTTPS）
- uploadFile 合法域名：填入腾讯云 COS 域名
- 开发阶段可在微信开发者工具中勾选「不校验合法域名」
【登录流程注意】
- wx.login() 返回的 code 有效期为 5 分钟，只能使用一次
- 不要在前端存储 session_key，只存系统颁发的 JWT token
- JWT 推荐有效期 7 天，结合 refresh token 机制
【图片上传注意】
- wx.chooseMedia 替代已废弃的 wx.chooseImage（基础库 2.10.0+）
- 上传前在前端压缩（quality 参数），减少上传时间
- 上传到后端后由后端再次压缩，避免大图存入 COS
【分包加载（后续优化）】
- 当小程序代码超过 1.5MB 时需分包
- 匹配相关页面可放入子包
【wx.request 并发限制】
- 微信限制同时最多 10 个并发请求
- 首页多接口并发请求时注意控制数量
```
### 9.2 后端 FastAPI 开发注意事项
```
【异步数据库操作】
- 使用 SQLAlchemy 2.x async 引擎，配合 asyncmy 驱动
- pip install sqlalchemy[asyncio] asyncmy
- 所有数据库操作使用 async with AsyncSession 上下文
【JWT 配置】
- SECRET_KEY 使用 openssl rand -hex 32 生成，存入 .env
- 算法推荐 HS256
- payload 中仅存 user_id（不存敏感信息）
【CORS 配置】
- 本地开发：allow_origins=["*"]
- 生产环境：allow_origins=["https://your-admin-domain.com"]
- 微信小程序请求不受 CORS 限制，但后台管理 Vue 项目会受影响
【频率限制】
- 匹配接口（/matches/like）：同一用户每分钟最多 20 次，Redis 计数
- 登录接口：同一 IP 每分钟最多 10 次
【图片处理】
- pip install Pillow
- 头像模糊处理：ImageFilter.GaussianBlur(radius=15)
- 上传前校验文件类型（检查文件头 magic bytes，而非仅看后缀名）
【双向匹配并发安全】
- 两个用户同时互相点感兴趣时可能产生竞态条件
- matches 表有 UNIQUE KEY (user_a_id, user_b_id)，用数据库唯一约束保证
- 插入时使用 INSERT IGNORE 或捕获 IntegrityError
【订阅消息异步发送】
- 不要在请求链路内同步发送微信消息（影响响应速度）
- 使用 FastAPI BackgroundTasks 异步发送
- 或接入 Celery + Redis 任务队列（生产环境推荐）
```
### 9.3 数据库注意事项
```
【JSON 字段使用】
- MySQL 5.7+ 支持 JSON 类型
- personality_tags、hobbies、value_answers 使用 JSON 字段
- SQLAlchemy 中使用 JSON 类型映射
【时区处理】
- MySQL 服务器时区设置为 Asia/Shanghai
- 所有 DATETIME 字段存储本地时间（简化处理）
- 前端展示时注意格式化
【索引设计】
- 高频查询：users(gender, city, audit_status)，建复合索引
- match_likes(from_user_id, to_user_id) 已有 UNIQUE 约束（自带索引）
- activities(status, is_published, start_time) 建复合索引
【Alembic 迁移】
- 每次修改 models 后运行：alembic revision --autogenerate -m "描述"
- 应用迁移：alembic upgrade head
- 永远不要在生产环境直接修改表结构
```
### 9.4 腾讯云 COS 配置
```python
# app/services/cos_service.py
from qcloud_cos import CosConfig, CosS3Client
from app.config import settings
def get_cos_client():
config = CosConfig(
Region=settings.COS_REGION,
SecretId=settings.COS_SECRET_ID,
SecretKey=settings.COS_SECRET_KEY
)
return CosS3Client(config)
def upload_file(local_path: str, cos_key: str) -> str:
"""上传文件到 COS，返回公开访问 URL"""
client = get_cos_client()
client.upload_file(
Bucket=settings.COS_BUCKET,
LocalFilePath=local_path,
Key=cos_key,
)
return f"https://{settings.COS_BUCKET}.cos.{settings.COS_REGION}.myqcloud.com/{cos_key}"
# pip install cos-python-sdk-v5
```
---
## 10. 环境配置
### 10.1 .env 文件（后端）
```env
# 微信小程序
WX_APPID=your_wx_appid
WX_SECRET=your_wx_app_secret
# JWT
JWT_SECRET_KEY=your_super_secret_key_generated_by_openssl
JWT_ALGORITHM=HS256
JWT_EXPIRE_HOURS=168 # 7天
# 数据库
DB_HOST=127.0.0.1
DB_PORT=3306
DB_NAME=matchmaking
DB_USER=root
DB_PASSWORD=your_db_password
# Redis
REDIS_HOST=127.0.0.1
REDIS_PORT=6379
REDIS_DB=0
# 腾讯云 COS
COS_REGION=ap-beijing
COS_BUCKET=your-bucket-name
COS_SECRET_ID=your_secret_id
COS_SECRET_KEY=your_secret_key
# 微信订阅消息模板 ID
WX_TEMPLATE_AUDIT=your_audit_template_id
WX_TEMPLATE_MATCH=your_match_template_id
# 系统配置
DAILY_RECOMMEND_LIMIT=10 # 每日推荐上限
AUDIT_SLA_HOURS=4 # 审核 SLA 小时数
```
### 10.2 requirements.txt
```
fastapi==0.111.0
uvicorn[standard]==0.29.0
sqlalchemy[asyncio]==2.0.30
asyncmy==0.2.9
alembic==1.13.1
pydantic==2.7.1
pydantic-settings==2.2.1
python-jose[cryptography]==3.3.0
passlib[bcrypt]==1.7.4
httpx==0.27.0
Pillow==10.3.0
python-multipart==0.0.9
redis==5.0.4
cos-python-sdk-v5==1.9.30
python-dotenv==1.0.1
```
### 10.3 启动命令
```bash
# 安装依赖
pip install -r requirements.txt
# 初始化数据库（首次）
alembic upgrade head
# 创建初始管理员账号（运行一次）
python scripts/create_admin.py --username admin --password your_password
# 启动开发服务器
uvicorn main:app --reload --host 0.0.0.0 --port 8000
# 生产环境启动（多 worker）
uvicorn main:app --host 0.0.0.0 --port 8000 --workers 4
```
### 10.4 main.py 入口
```python
# main.py
from fastapi import FastAPI
from fastapi.middleware.cors import CORSMiddleware
from app.routers import auth, users, activities, matches, announcements, upload
from app.routers.admin import users as admin_users, activities as admin_activities
from app.routers.admin import matches as admin_matches, dashboard
app = FastAPI(title="相亲小程序 API", version="1.0.0")
# CORS
app.add_middleware(
CORSMiddleware,
allow_origins=["*"], # 生产环境改为具体域名
allow_credentials=True,
allow_methods=["*"],
allow_headers=["*"],
)
# 注册路由
app.include_router(auth.router, prefix="/api/v1/auth", tags=["认证"])
app.include_router(users.router, prefix="/api/v1/users", tags=["用户"])
app.include_router(activities.router, prefix="/api/v1/activities", tags=["活动"])
app.include_router(matches.router, prefix="/api/v1/matches", tags=["匹配"])
app.include_router(announcements.router, prefix="/api/v1/announcements", tags=["公告"])
app.include_router(upload.router, prefix="/api/v1/upload", tags=["上传"])
# 后台路由
app.include_router(dashboard.router, prefix="/api/v1/admin/dashboard", tags=["后台-看板"])
app.include_router(admin_users.router, prefix="/api/v1/admin/users", tags=["后台-用户"])
app.include_router(admin_activities.router, prefix="/api/v1/admin/activities", tags=["后台-活动"])
app.include_router(admin_matches.router, prefix="/api/v1/admin/matches", tags=["后台-匹配"])
@app.get("/health")
async def health_check():
return {"status": "ok"}
```
---
## 附录：功能清单总览（MVP 版本）
### 小程序前端（9 个页面）
|页面|功能|状态|
|---|---|---|
|首页|活动预告轮播、公告、会员展示|MVP|
|活动列表|分类浏览、上拉加载|MVP|
|活动详情|详情展示、报名/取消报名|MVP|
|匹配页|候选人浏览、感兴趣/跳过、AI推荐|MVP|
|我的|个人信息、功能入口|MVP|
|资料编辑|6步填写、头像上传|MVP|
|审核状态|状态展示、驳回原因|MVP|
|我的活动|报名活动列表|MVP|
|我的匹配|匹配成功列表、查看详情|MVP|
### 后端 API（28 个接口）
|模块|接口数|
|---|---|
|认证（登录、刷新）|2|
|用户（获取、更新、提交审核、公开信息）|4|
|活动（列表、详情、报名、取消）|4|
|匹配（候选人、感兴趣、AI推荐、我的匹配、详情）|5|
|公告（列表、详情）|2|
|上传（头像、活动封面）|2|
|后台-看板|1|
|后台-用户管理（列表、详情、审核、封禁）|4|
|后台-活动管理（列表、创建、修改、发布）|4|
|合计|**28**|
---
_文档版本：v1.0 · 生成时间：2025年4月_
_如有接口变更，请同步更新本文档对应章节。_
Reference in New Issue Copy Permalink