# 项目架构分析报告

## 📋 项目概述

**项目名称**: XINxiangqin（新相亲）  
**项目类型**: 婚恋社交平台  
**架构模式**: 微服务架构（Spring Cloud Gateway + 多服务模块）  
**开发时间**: 2024-2025

---

## 🏗️ 技术架构

### 后端技术栈

#### 核心框架
- **Spring Boot**: 2.7.15
- **Spring Cloud**: 2021.0.8
- **Spring Cloud Alibaba**: 2021.0.5.0
- **Java版本**: JDK 8
- **构建工具**: Maven

#### 数据层
- **ORM框架**: MyBatis-Plus 3.5.3
- **数据库**: MySQL 8.0.33
- **缓存**: Redis (Spring Data Redis)
- **对象存储**: MinIO 7.1.0

#### 其他技术
- **WebSocket**: 实时聊天功能
- **腾讯云IM SDK**: tim-wx-sdk 2.27.6 (用于小程序聊天)
- **工具库**: Lombok 1.18.30

### 前端技术栈

#### 小程序端 (LiangZhiYUMao)
- **框架**: uni-app (Vue 2)
- **HTTP客户端**: Axios 1.12.2
- **UI组件**: uni-ui组件库
- **聊天SDK**: tim-wx-sdk 2.27.6

#### 管理后台 (marriageAdmin-vue)
- **框架**: Vue 3.5.22
- **UI组件库**: Element Plus 2.11.5
- **状态管理**: Pinia 3.0.3
- **路由**: Vue Router 4.5.1
- **构建工具**: Vite 7.1.7
- **图表库**: ECharts 6.0.0

---

## 🎯 系统架构设计

### 微服务模块划分

```
XINxiangqin/
├── gateway/              # API网关服务 (端口: 8083)
├── common/               # 公共模块（实体类、工具类）
└── service/              # 业务服务模块
    ├── login/            # 登录服务
    ├── homePage/         # 首页服务 (端口: 8081)
    ├── dynamic/          # 动态服务 (端口: 8086)
    ├── websocket/        # WebSocket聊天服务 (端口: 1004)
    ├── randomMatch/      # 随机匹配服务 (端口: 1003)
    ├── Essential/        # 基础服务（用户信息等）(端口: 1005)
    ├── Recommend/        # 推荐服务
    └── admin/            # 管理端服务 (端口: 8088)
```

### 网关路由配置

网关统一入口：`http://localhost:8083`

| 路由路径 | 目标服务 | 端口 | 说明 |
|---------|---------|------|------|
| `/admin/**` | admin服务 | 8088 | 管理端页面和API |
| `/api/admin/**` | admin服务 | 8088 | 管理端API |
| `/ws/chat/**` | websocket服务 | 1004 | WebSocket聊天 |
| `/api/chat/**` | websocket服务 | 1004 | 聊天REST API |
| `/match/**` | randomMatch服务 | 1003 | 匹配服务 |
| `/api/announcement/**` | homePage服务 | 8081 | 公告服务 |
| `/api/dynamic/**` | dynamic服务 | 8086 | 动态服务 |
| `/media/**` | dynamic服务 | 8086 | 媒体文件 |
| `/api/message/**` | dynamic服务 | 8086 | 系统消息 |
| `/api/user/**` | Essential服务 | 1005 | 用户基础服务 |
| `/api/**` | homePage服务 | 8081 | 首页服务（兜底路由） |

---

## 📱 功能模块分析

### 小程序端功能 (LiangZhiYUMao)

#### 核心功能模块

1. **用户认证模块**
   - 微信授权登录
   - 手机号绑定
   - 身份证验证
   - 用户资料管理

2. **匹配推荐模块**
   - 今日推荐
   - 智能推荐
   - 在线匹配
   - 随机匹配
   - 对象要求设置

3. **社交功能模块**
   - 动态广场（发布、浏览、点赞、评论）
   - 消息系统（聊天、系统消息）
   - 黑名单管理
   - 举报功能

4. **星命运算模块** ⭐
   - 属相测算
   - 星座卡片
   - 星座配对
   - 八字测算
   - 八字配对
   - MBTI测试

5. **服务模块**
   - 红娘服务（列表、详情）
   - 活动管理（列表、详情、报名）
   - 精品课程（列表、详情）
   - 成功案例（列表、详情）
   - 兼职红娘申请

6. **会员功能**
   - VIP会员
   - 私人定制

7. **个人中心**
   - 我的资料
   - 我的活动
   - 设置中心

#### 第三方API集成

- **天行数据API**: 星座、生肖配对、八字查询
- **极速数据API**: 专业八字排盘
- **腾讯云IM**: 实时聊天功能

### 管理后台功能 (marriageAdmin-vue)

#### 管理功能模块

1. **数据面板**
   - 用户统计
   - 活动统计
   - 收入趋势
   - ECharts图表展示

2. **内容管理**
   - 轮播图管理
   - 小喇叭公告管理
   - 活动管理（含报名统计）
   - 红娘管理
   - 课程管理
   - 成功案例管理

3. **用户管理**
   - 用户列表
   - VIP用户管理
   - VIP套餐管理

4. **审核管理**
   - 动态审核
   - 举报处理

---

## 🗄️ 数据库设计

### 核心数据表

#### 用户相关
- `users`: 用户主表
  - 字段：userId, phone, email, nickname, password, gender, birthDate, avatarUrl, status等
  - 安全：手机号AES-256加密，密码bcrypt加密

- `user_profile`: 用户扩展信息表
  - 字段：房产、车辆、身高、体重、星座、生肖、学历、工作、薪资等
  - 认证：实名认证、学历认证、工作认证、婚姻状态认证

- `vip`: VIP会员表
- `blacklist`: 黑名单表
- `checkin`: 签到表

#### 社交相关
- `user_dynamics`: 用户动态表
- `dynamic_comments`: 动态评论表
- `dynamic_likes`: 动态点赞表
- `dynamic_reports`: 动态举报表

#### 聊天相关
- `chat_messages`: 聊天消息表
- `chat_sessions`: 聊天会话表

#### 业务相关
- `activities`: 活动表
- `activity_registrations`: 活动报名表
- `matchmakers`: 红娘表
- `courses`: 课程表
- `success_cases`: 成功案例表
- `announcements`: 公告表
- `banners`: 轮播图表

#### 管理相关
- `admin_users`: 管理员用户表

---

## 🔐 安全机制

### 数据安全
- **手机号加密**: AES-256加密存储
- **密码加密**: bcrypt哈希加密
- **Token认证**: JWT Token + Redis存储
- **CORS配置**: 网关统一处理跨域

### 认证流程
1. 小程序：微信授权登录 → 获取openid/unionid → 生成Token
2. 管理后台：用户名密码登录 → 验证 → 生成Token
3. Token存储在Redis中，设置过期时间

---

## 📡 API接口设计

### 接口规范
- **统一响应格式**: `{code, message, data}`
- **统一错误处理**: 网关层统一处理
- **RESTful风格**: 遵循REST规范

### 主要接口分类

#### 用户相关
- `/api/user/**` - 用户信息、资料管理

#### 动态相关
- `/api/dynamic/**` - 动态CRUD、点赞、评论
- `/api/message/**` - 系统消息

#### 匹配相关
- `/match/**` - 匹配算法、推荐

#### 聊天相关
- `/api/chat/**` - 聊天消息REST API
- `/ws/chat/**` - WebSocket实时聊天

#### 管理相关
- `/admin/**` - 管理端页面和API
- `/api/admin/**` - 管理端API

---

## 🚀 部署架构

### 服务端口分配

| 服务 | 端口 | 说明 |
|------|------|------|
| Gateway | 8083 | API网关（统一入口） |
| HomePage | 8081 | 首页服务 |
| Dynamic | 8086 | 动态服务 |
| WebSocket | 1004 | 聊天服务 |
| RandomMatch | 1003 | 匹配服务 |
| Essential | 1005 | 基础服务 |
| Admin | 8088 | 管理端服务 |

### 依赖服务
- **MySQL**: 主数据库
- **Redis**: 缓存和Token存储
- **MinIO**: 对象存储（图片、文件）

---

## 🔧 开发环境配置

### 小程序端配置
- **API地址**: `config/api-config.js` 中配置
- **第三方API**: 天行数据、极速数据API Key配置
- **开发工具**: HBuilderX / 微信开发者工具

### 管理后台配置
- **API地址**: `src/config/api.js`
- **开发服务器**: Vite Dev Server (端口: 5173)
- **代理配置**: Vite代理到网关

### 后端配置
- **数据库**: 各服务`application.yml`中配置
- **Redis**: 各服务独立配置
- **MinIO**: 文件上传服务配置

---

## 📊 项目特点

### 优势
1. **微服务架构**: 模块化设计，易于扩展和维护
2. **前后端分离**: 小程序和管理后台独立开发
3. **功能完整**: 涵盖婚恋平台核心功能
4. **第三方集成**: 丰富的API集成（星座、八字、聊天等）
5. **安全机制**: 完善的数据加密和认证体系

### 技术亮点
1. **网关统一管理**: Spring Cloud Gateway统一路由和CORS
2. **实时通信**: WebSocket + 腾讯云IM双重保障
3. **智能推荐**: 推荐算法服务独立
4. **内容审核**: 动态审核机制
5. **数据可视化**: ECharts图表展示

### 待优化点
1. **服务发现**: 当前使用硬编码URI，可引入Nacos/Eureka
2. **配置中心**: 可引入配置中心统一管理配置
3. **监控体系**: 可添加服务监控和链路追踪
4. **API文档**: 可集成Swagger/Knife4j
5. **测试覆盖**: 单元测试和集成测试

---

## 🎯 后续修改建议

### 代码层面
1. **统一异常处理**: 各服务统一异常处理机制
2. **API版本控制**: 引入版本号管理API
3. **参数校验**: 统一使用Bean Validation
4. **日志规范**: 统一日志格式和级别
5. **代码规范**: 统一代码风格和命名规范

### 架构层面
1. **服务注册发现**: 引入Nacos或Eureka
2. **配置中心**: 使用Nacos Config或Spring Cloud Config
3. **API网关增强**: 添加限流、熔断、降级
4. **分布式事务**: 引入Seata处理分布式事务
5. **消息队列**: 引入RabbitMQ/Kafka处理异步任务

### 功能层面
1. **搜索功能**: 用户搜索、动态搜索
2. **推荐算法优化**: 基于机器学习的推荐
3. **数据分析**: 用户行为分析、匹配成功率分析
4. **消息推送**: 集成推送服务（极光推送等）
5. **支付功能**: 集成支付功能（微信支付、支付宝）

---

## 📝 关键文件位置

### 配置文件
- 网关配置: `gateway/src/main/resources/application.yml`
- 小程序API配置: `LiangZhiYUMao/config/api-config.js`
- 管理后台API配置: `marriageAdmin-vue/src/config/api.js`
- 小程序路由: `LiangZhiYUMao/pages.json`
- 管理后台路由: `marriageAdmin-vue/src/router/index.js`

### 核心代码
- 公共实体: `common/src/main/java/com/zhentao/pojo/`
- 小程序工具: `LiangZhiYUMao/utils/`
- 管理后台组件: `marriageAdmin-vue/src/components/`
- 管理后台页面: `marriageAdmin-vue/src/views/`

### 数据库脚本
- 各服务SQL脚本: `service/*/src/main/resources/sql/`

---

## 🔍 问题诊断指南

### 常见问题
1. **跨域问题**: 检查网关CORS配置
2. **路由404**: 检查网关路由配置顺序
3. **Token失效**: 检查Redis连接和Token过期时间
4. **API调用失败**: 检查服务端口和网关路由
5. **文件上传失败**: 检查MinIO配置和权限

### 调试建议
1. 开启网关DEBUG日志查看路由转发
2. 检查各服务日志文件
3. 使用Postman测试API接口
4. 检查Redis和MySQL连接状态
5. 查看小程序网络请求日志

---

## 📚 相关文档

项目包含丰富的文档：
- API接口说明文档
- 第三方API集成指南
- 功能说明文档
- 问题诊断文档
- 样式优化文档

---

**报告生成时间**: 2025-01-27  
**分析范围**: 项目整体架构、技术栈、功能模块、数据库设计

