# 相亲小程序开发规划

## 1. 项目目标

## 当前进度

- [x] 已创建 `backend/`、`miniprogram/`、`admin-web/` 项目骨架
- [x] 已完成后端基础初始化：FastAPI 入口、配置、数据库会话、JWT 工具、认证路由、Alembic 基础文件
- [x] 已完成核心数据库模型和首个迁移文件：`users`、`activities`、`registrations`、`match_likes`、`matches`、`announcements`、`admins`
- [x] 已完成小程序基础初始化：`app.js`、`app.json`、`app.wxss`、请求封装、登录封装、核心页面壳
- [x] 已完成后台管理端基础初始化：Vite + Vue3 + Element Plus 基础结构、路由和页面壳
- [x] 已完成用户中心第一批真实接口：`GET /users/me`、`PUT /users/me`、`POST /users/submit-audit`
- [x] 已完成资料完整度计算和审核提交必填校验基础逻辑
- [x] 已完成真实微信登录建档基础流程：`POST /auth/wx-login` 已接入 `code2session` 和用户自动创建/复用逻辑
- [x] 已完成头像上传基础接口：`POST /upload/avatar`，包含图片校验、压缩、模糊图生成、头像字段回写
- [x] 已完成活动系统第一批后端接口：`GET /activities`、`GET /activities/{id}`、`POST /activities/{id}/register`、`DELETE /activities/{id}/register`
- [x] 已完成匹配系统第一批后端接口：`GET /matches/candidates`、`POST /matches/like`、`GET /matches/my`、`GET /matches/{match_id}/detail`
- [x] 已完成公开资料分级接口：`GET /users/public/{user_id}`
- [x] 已完成小程序用户中心基础联调：`profile`、`profile-edit`、`audit-status`
- [x] 已完成小程序活动页基础联调：`activity`、`activity-detail`
- [x] 已完成小程序匹配页基础联调：`match`、`my-matches`
- [x] 已完成小程序我的活动页基础联调：`my-activities`
- [x] 已完成后台审核链路基础联调：管理员登录、待审核列表、审核通过/驳回
- [x] 已完成后台活动管理基础联调：活动列表、活动创建、发布/下架
- [x] 已完成公告系统基础联调：前台公告列表/详情、后台公告创建与列表管理
- [x] 已完成首页运营基础内容联调：首页活动预告、公告栏、公告详情页
- [x] 已完成 AI 推荐基础联调：`POST /matches/ai-suggest`、匹配页 AI 推荐展示、首页会员推荐区
- [x] 已完成后台数据看板基础联调：`GET /admin/dashboard` 与管理端展示页面
- [x] 已补管理员种子账号初始化脚本与说明
- [x] 已完成后端统一错误响应格式基础接入
- [x] 已完成后台活动编辑基础联调
- [x] 已补根目录启动说明文档 `README.md`
- [x] 已完成一轮关键代码检查与高风险问题修复
- [x] 已清理小程序远程占位图依赖，避免合法域名问题
- [x] 已补手工验收清单 `验收清单.md`
- [x] 已补上线准备清单 `上线准备清单.md`
- [x] 已补后台后端增强接口：用户详情、封禁/解封、匹配记录、系统配置
- [x] 已完成微信订阅消息基础接入：审核结果通知、匹配成功通知
- [x] 已完成 Redis 基础接入：微信 access_token 缓存、登录限流、匹配 like 限流
- [ ] 下一步：补推荐列表 Redis 缓存、COS 真上传、自动化测试和最终部署验证

基于 `相亲小程序开发详情.md`，从零到一完成一个微信小程序相亲平台，覆盖以下完整链路：

`微信登录 -> 填写资料 -> 提交审核 -> 审核通过 -> 报名活动 -> 参与匹配 -> 查看匹配结果`

项目整体包含 3 个子系统：

1. 微信小程序前端
2. Python FastAPI 后端
3. Vue3 + Element Plus 后台管理端

开发原则：

1. 先完成 MVP，再逐步补全高级功能
2. 先后端和数据模型，再对接小程序页面
3. 先跑通主链路，再补 AI 推荐、通知、数据看板等增强功能

## 2. 总体开发策略

### 2.1 优先级原则

优先保证业务闭环：

1. 用户能登录
2. 用户能填写资料并提交审核
3. 管理员能审核
4. 用户能报名活动
5. 用户能浏览和匹配异性

### 2.2 版本拆分

1. `V0.1 基础框架`
   前后端项目初始化、数据库连通、登录鉴权、统一响应结构
2. `V0.2 用户资料与审核`
   用户资料编辑、头像上传、完整度计算、提交审核、后台审核
3. `V0.3 活动报名`
   活动列表、详情、报名、取消报名、后台活动管理
4. `V0.4 匹配主链路`
   候选列表、感兴趣、双向匹配成功、我的匹配
5. `V0.5 AI 推荐与通知`
   AI 推荐、每日推荐缓存、微信订阅消息
6. `V0.6 后台完善与上线`
   公告、看板、系统配置、测试、部署、提审

## 3. 开发阶段规划

### 阶段 0：需求冻结与项目初始化

状态：已完成

目标：把规格文档转化为工程执行基础。

交付物：

1. 项目目录结构
2. 接口清单
3. 页面清单与跳转关系
4. `.env.example`
5. README 和开发约定

核心任务：

1. 创建项目目录：`miniprogram/`、`backend/`、`admin-web/`
2. 明确运行环境：Python 3.11、MySQL 8、Redis 7、Node LTS、微信开发者工具
3. 梳理 API 列表与页面流转图
4. 确定代码规范、分支策略、环境变量管理方式

已完成标记：

1. [x] 创建项目目录：`miniprogram/`、`backend/`、`admin-web/`
2. [x] 明确运行环境：Python 3.11、MySQL 8、Redis 7、Node LTS、微信开发者工具
3. [x] 梳理 API 列表与页面流转图
4. [x] 确定代码规范、分支策略、环境变量管理方式

验收标准：

1. 三个项目目录可独立初始化
2. 开发者可按文档快速启动本地环境

### 阶段 1：后端基础设施

状态：进行中

目标：完成后端骨架，支撑后续全部业务模块。

核心任务：

1. 初始化 FastAPI 项目结构
2. 实现 `config.py`、`database.py`、`dependencies.py`
3. 接入 MySQL、Redis、Alembic
4. 增加统一响应格式和异常处理
5. 增加 JWT 鉴权能力
6. 封装微信 `code2session` 调用
7. 封装 COS 上传能力
8. 配置基础日志与健康检查接口

已完成标记：

1. [x] 初始化 FastAPI 项目结构
2. [x] 实现 `config.py`、`database.py`、`dependencies.py`
3. [x] 接入 MySQL、Redis、Alembic
4. [x] 增加统一响应格式和异常处理
5. [x] 增加 JWT 鉴权能力
6. [x] 封装微信 `code2session` 调用
7. [x] 封装 COS 上传能力
8. [x] 配置基础日志与健康检查接口

验收标准：

1. 后端服务可启动
2. 数据库和 Redis 可连接
3. Alembic 可生成并执行迁移
4. JWT 可签发和校验

### 阶段 2：数据库与模型实现

状态：已完成基础模型与首个迁移

目标：建立稳定的数据层。

核心表：

1. `users`
2. `activities`
3. `registrations`
4. `match_likes`
5. `matches`
6. `announcements`
7. `admins`

核心任务：

1. 编写 SQLAlchemy ORM 模型
2. 编写 Pydantic 请求/响应模型
3. 配置索引与唯一约束
4. 编写 Alembic 迁移脚本
5. 初始化管理员账号种子数据

已完成标记：

1. [x] 编写 SQLAlchemy ORM 模型
2. [x] 编写基础 Pydantic 响应模型
3. [x] 配置索引与唯一约束
4. [x] 编写 Alembic 迁移脚本
5. [ ] 初始化管理员账号种子数据

重点注意：

1. `users` 中 JSON 字段映射
2. `matches` 唯一索引避免并发重复匹配
3. 审核状态、报名状态、活动状态的枚举设计

验收标准：

1. 全部核心表迁移成功
2. 本地能插入和查询样例数据

### 阶段 3：认证与用户中心后端

状态：进行中

目标：完成登录、资料编辑、审核提交的后端能力。

接口范围：

1. `POST /auth/wx-login`
2. `POST /auth/refresh`
3. `GET /users/me`
4. `PUT /users/me`
5. `POST /users/submit-audit`
6. `POST /upload/avatar`

核心任务：

1. 微信登录后自动创建用户
2. 获取当前用户资料
3. 支持增量更新资料
4. 自动计算 `profile_completeness`
5. 修改已审核资料后重置为待审核
6. 头像上传、压缩、生成模糊图并上传 COS
7. 审核提交前校验必填字段

已完成标记：

1. [ ] 微信登录后自动创建用户
1. [x] 微信登录后自动创建用户
2. [x] 获取当前用户资料
3. [x] 支持增量更新资料
4. [x] 自动计算 `profile_completeness`
5. [x] 修改已审核资料后重置为待审核
6. [x] 头像上传、压缩、生成模糊图并上传 COS
7. [x] 审核提交前校验必填字段

验收标准：

1. 新用户首次登录能自动建档
2. 用户可多次保存资料
3. 用户可成功提交审核
4. 头像上传成功并回写数据库

### 阶段 4：小程序基础框架

状态：已完成基础初始化，后续继续迭代

目标：完成小程序基础壳、登录态和通用请求封装。

核心任务：

1. 初始化 `app.js`、`app.json`、`app.wxss`
2. 实现 `utils/request.js`
3. 实现登录态管理 `utils/auth.js`
4. 配置 TabBar 页面
5. 建立通用组件：
   `empty-state`、`audit-badge`、`progress-bar`、`activity-card`、`match-card`
6. 完成页面基础壳：
   `home`、`activity`、`match`、`profile`、`profile-edit`、`audit-status`、`activity-detail`、`my-activities`、`my-matches`、`announcement`

已完成标记：

1. [x] 初始化 `app.js`、`app.json`、`app.wxss`
2. [x] 实现 `utils/request.js`
3. [x] 实现登录态管理 `utils/auth.js`
4. [x] 配置 TabBar 页面
5. [ ] 建立通用组件：`empty-state`、`audit-badge`、`progress-bar`、`activity-card`、`match-card`
6. [x] 完成页面基础壳：`home`、`activity`、`match`、`profile`、`profile-edit`、`audit-status`、`activity-detail`、`my-activities`、`my-matches`、`announcement`

验收标准：

1. 小程序项目可在微信开发者工具启动
2. token 可持久化保存
3. 页面可正常跳转
4. 接口请求封装可统一处理错误和鉴权

### 阶段 5：资料填写与审核链路联调

目标：跑通第一条完整业务主链路。

小程序侧任务：

1. `profile` 页面展示用户资料摘要、审核状态、完整度
2. `profile-edit` 分步骤填写并自动保存
3. `audit-status` 展示审核状态与驳回原因

已完成标记：

1. [x] `profile` 页面展示用户资料摘要、审核状态、完整度
2. [x] `profile-edit` 分步骤填写并自动保存
3. [x] `audit-status` 展示审核状态与驳回原因

后台侧任务：

1. 管理员登录
2. 待审核用户列表
3. 用户详情查看
4. 审核通过/驳回

已完成标记：

1. [x] 管理员登录
2. [x] 待审核用户列表
3. [ ] 用户详情查看
4. [x] 审核通过/驳回

验收标准：

1. 用户可在小程序完整填写资料
2. 管理员可在后台审核资料
3. 审核结果可同步反馈到小程序

### 阶段 6：活动系统

状态：进行中

目标：跑通第二条业务主链路“浏览活动并报名”。

后端接口：

1. `GET /activities`
2. `GET /activities/{id}`
3. `POST /activities/{id}/register`
4. `DELETE /activities/{id}/register`
5. 后台活动管理接口

已完成标记：

1. [x] `GET /activities`
2. [x] `GET /activities/{id}`
3. [x] `POST /activities/{id}/register`
4. [x] `DELETE /activities/{id}/register`
5. [x] 后台活动管理接口

小程序页面：

1. 首页活动预告
2. 活动列表页
3. 活动详情页
4. 我的活动页

已完成标记：

1. [ ] 首页活动预告
2. [x] 活动列表页
3. [x] 活动详情页
4. [x] 我的活动页

后台页面：

1. 活动列表
2. 创建活动
3. 编辑活动
4. 发布/下架活动

已完成标记：

1. [x] 活动列表
2. [x] 创建活动
3. [ ] 编辑活动
4. [x] 发布/下架活动

关键校验：

1. 活动已发布
2. 活动报名未截止
3. 用户审核状态已通过
4. 性别名额未满
5. 已报名请求幂等处理
6. 活动开始前 24 小时不可取消

验收标准：

1. 管理员可发布活动
2. 用户可浏览活动并报名
3. 报名状态和按钮态展示正确

### 阶段 7：匹配系统基础版

状态：进行中

目标：跑通第三条主链路“浏览候选人并双向匹配”。

后端接口：

1. `GET /matches/candidates`
2. `POST /matches/like`
3. `GET /matches/my`
4. `GET /matches/{match_id}/detail`
5. `GET /users/public/{user_id}`

已完成标记：

1. [x] `GET /matches/candidates`
2. [x] `POST /matches/like`
3. [x] `GET /matches/my`
4. [x] `GET /matches/{match_id}/detail`
5. [x] `GET /users/public/{user_id}`

小程序页面：

1. 匹配首页候选人列表
2. 卡片详情弹窗
3. 我的匹配记录页

已完成标记：

1. [x] 匹配首页候选人列表
2. [x] 卡片详情弹窗
3. [x] 我的匹配记录页

核心规则：

1. 过滤已不感兴趣用户、已匹配用户、当天已展示用户
2. 点击感兴趣写入 `match_likes`
3. 若存在反向 like，则生成 `matches`
4. 根据关系返回 Level 1/2/3 不同信息层级
5. 利用数据库唯一约束避免重复匹配

验收标准：

1. 用户可浏览候选人
2. 用户可发送感兴趣
3. 双方互相感兴趣时成功匹配
4. 匹配详情仅双方可见

### 阶段 8：AI 推荐

状态：进行中

目标：把候选人浏览升级为可解释的智能推荐。

核心任务：

1. 按规格实现 `match_service.py`
2. 实现 `POST /matches/ai-suggest`
3. 输出匹配分和匹配理由
4. 使用 Redis 缓存每日推荐结果
5. 控制推荐多样性，避免结果过于同质化

已完成标记：

1. [x] 按规格实现 `match_service.py`
2. [x] 实现 `POST /matches/ai-suggest`
3. [x] 输出匹配分和匹配理由
4. [ ] 使用 Redis 缓存每日推荐结果
5. [x] 控制推荐多样性，避免结果过于同质化

验收标准：

1. AI 推荐接口可返回 Top N 候选人
2. 每个候选人具备分数和理由
3. 当日推荐列表稳定且不重复

### 阶段 9：公告与首页运营能力

状态：进行中

目标：补齐内容运营能力和首页展示模块。

核心任务：

1. 完成公告接口：`GET /announcements`、`GET /announcements/{id}`
2. 后台支持公告增删改查
3. 首页展示活动轮播、公告栏、会员推荐区
4. 完成公告详情页

已完成标记：

1. [x] 完成公告接口：`GET /announcements`、`GET /announcements/{id}`
2. [x] 后台支持公告增删改查
3. [x] 首页展示活动轮播、公告栏
4. [x] 完成公告详情页
5. [x] 首页会员推荐区

验收标准：

1. 后台发布公告后首页可见
2. 用户可查看公告详情

### 阶段 10：微信能力与生产能力补强

目标：让系统达到可试运营水平。

核心任务：

1. 接入微信订阅消息
2. 实现审核结果通知
3. 实现匹配成功通知
4. 配置服务器域名、上传域名、COS 域名
5. 增加登录和匹配接口频控
6. 缓存微信 `access_token`
7. 增加日志、异常监控、后台配置项

验收标准：

1. 审核和匹配消息可正常发送
2. 线上域名配置完整可用
3. 接口具备基本限流能力

### 阶段 11：后台管理端完善

状态：进行中

目标：让审核、活动运营、公告管理、数据查看进入可实际使用状态。

页面范围：

1. `/login`
2. `/dashboard`
3. `/users`
4. `/users/audit`
5. `/activities`
6. `/activities/new`
7. `/matches`
8. `/announcements`
9. `/settings`

优先级：

1. 管理员登录
2. 待审核队列
3. 活动管理
4. 公告管理
5. 数据看板
6. 系统设置

已完成标记：

1. [x] 管理员后台项目基础初始化
2. [x] 路由结构搭建
3. [x] 登录、看板、用户、活动、匹配、公告、设置页面壳建立
4. [x] 登录页真实业务联调
5. [x] 待审核列表页真实业务联调
6. [x] 活动管理页真实业务联调
7. [x] 公告管理页真实业务联调
8. [x] 数据看板真实业务页面开发
9. [x] 活动编辑基础能力联调
10. [x] 设置页真实业务联调
11. [x] 匹配记录页真实业务联调
12. [x] 用户详情、搜索筛选基础能力联调
13. [ ] 更多后台增强页面与交互优化

验收标准：

1. 审核人员可高效处理审核任务
2. 运营人员可独立管理活动和公告
3. 管理员可查看核心业务数据

### 阶段 12：测试、部署与上线

状态：进行中

目标：完成交付前的稳定性验证和正式上线准备。

测试范围：

1. 单元测试
   匹配分计算、资料完整度计算、审核状态流转、活动报名校验
2. 接口测试
   `auth/users/activities/matches/admin`
3. 联调测试
   小程序与后端、后台与后端
4. 手工验收
   新用户流程、审核驳回重提流程、活动报名流程、双向匹配流程
5. 基础压测
   登录、活动列表、匹配列表、like 接口

上线准备：

1. 配置生产环境 `.env`
2. HTTPS 域名与服务器
3. MySQL / Redis 生产实例
4. 腾讯云 COS 正式存储桶
5. 微信小程序服务器域名配置
6. 后端和后台部署
7. 小程序隐私协议、提审资料准备

验收标准：

1. 主链路可完整运行
2. 关键功能通过手工和接口验证
3. 小程序具备提审条件

## 4. 推荐开发顺序

为保证效率，建议严格按以下顺序推进：

1. 后端基础框架 + 数据库模型
2. 用户登录、资料、头像上传
3. 小程序登录与资料填写页面
4. 后台登录与审核页面
5. 活动系统前后端
6. 匹配系统前后端
7. AI 推荐能力
8. 公告系统
9. 微信通知、看板、系统设置
10. 测试、部署、上线

## 5. MVP 最小可用范围

如果目标是尽快上线试运营，建议首版只做以下功能：

1. 微信登录
2. 用户资料编辑
3. 提交审核
4. 后台审核
5. 活动列表与活动报名
6. 匹配候选人列表
7. 感兴趣与双向匹配
8. 我的匹配
9. 公告列表

可放到第二阶段的能力：

1. AI 权重后台调参
2. 数据看板复杂图表
3. 微信订阅消息
4. 高级隐私设置
5. 小程序分包优化
6. 更复杂的推荐缓存与去重策略

## 6. 预估工期

按单人开发、AI 辅助编码、边开发边联调估算：

1. 基础框架和数据库：2-3 天
2. 用户资料与审核链路：3-4 天
3. 活动系统：3-4 天
4. 匹配系统：4-5 天
5. 后台管理端：4-6 天
6. AI 推荐与通知：2-3 天
7. 测试与上线准备：3-4 天

总工期：

`21-29 天`

如果只做 MVP：

`12-16 天`

## 7. 主要风险与注意事项

1. 微信登录、合法域名、服务器配置容易成为前期阻塞点
2. COS 上传和图片处理链路必须在真实环境验证
3. 审核状态、资料状态、报名状态存在较多边界条件
4. 双向匹配存在并发创建重复记录风险
5. 小程序页面较多，前期若状态管理不统一，后期维护成本会升高
6. 后台和小程序共用后端接口，鉴权体系必须从一开始区分清楚

## 8. 下一步执行建议

建议立刻开始工程落地，而不是继续停留在规划阶段。

首个执行动作建议为：

1. 创建 `backend/`、`miniprogram/`、`admin-web/` 项目骨架
2. 优先完成 `backend` 初始化
3. 建立数据库模型和迁移
4. 先打通登录、资料、审核主链路

完成上述步骤后，再按规划逐阶段推进即可。