# XINxiangqin 代码结构详解

> 详细的代码组织结构说明，帮助快速定位代码位置

---

## 📂 一、项目根目录结构

```
XINxiangqin/
├── gateway/                    # API网关服务
├── common/                     # 公共模块
├── service/                    # 业务服务模块（Maven聚合）
│   ├── login/                 # 登录服务
│   ├── homePage/              # 首页服务
│   ├── dynamic/               # 动态服务
│   ├── websocket/             # WebSocket聊天服务
│   ├── randomMatch/           # 随机匹配服务
│   ├── Essential/             # 基础服务
│   ├── Recommend/            # 推荐服务
│   └── admin/                 # 管理端服务
├── LiangZhiYUMao/             # 小程序前端（uni-app）
├── marriageAdmin-vue/         # 管理后台（Vue 3）
├── pom.xml                    # Maven父项目配置
└── 项目文档/                   # 项目文档目录
```

---

## 🔧 二、后端代码结构

### 2.1 Gateway服务结构

```
gateway/
├── src/
│   ├── main/
│   │   ├── java/
│   │   │   └── com/zhentao/
│   │   │       └── gateway/
│   │   │           ├── GatewayApplication.java    # 启动类
│   │   │           └── config/
│   │   │               └── CorsConfig.java        # CORS配置
│   │   └── resources/
│   │       └── application.yml                    # 网关路由配置（重要！）
│   └── test/
```

**关键文件**:
- `application.yml` - 所有路由规则、CORS配置、WebSocket支持

### 2.2 Common公共模块结构

```
common/
├── src/
│   ├── main/
│   │   ├── java/
│   │   │   └── com/zhentao/
│   │   │       ├── pojo/                         # 公共实体类
│   │   │       │   ├── Users.java                # 用户实体
│   │   │       │   ├── PartnerRequirement.java   # 择偶要求实体
│   │   │       │   └── MatchmakerApply.java      # 红娘申请实体
│   │   │       ├── mapper/                       # 数据访问层
│   │   │       │   ├── UsersMapper.java
│   │   │       │   ├── PartnerRequirementMapper.java
│   │   │       │   └── MatchmakerApplyMapper.java
│   │   │       └── service/                      # 公共服务接口
│   │   │           ├── UsersService.java
│   │   │           ├── PartnerRequirementService.java
│   │   │           └── MatchmakerApplyService.java
│   │   └── resources/
│   └── test/
```

**关键文件**:
- `pojo/` - 所有服务共享的实体类
- `mapper/` - MyBatis Mapper接口
- `service/` - 公共服务接口和实现

### 2.3 业务服务标准结构

每个业务服务（login、homePage、dynamic等）都遵循相同的结构：

```
service/{module}/
├── src/
│   ├── main/
│   │   ├── java/
│   │   │   └── com/zhentao/
│   │   │       ├── controller/                   # 控制器层（REST API）
│   │   │       │   └── XxxController.java        # 处理HTTP请求
│   │   │       ├── service/                       # 服务层（业务逻辑）
│   │   │       │   ├── XxxService.java           # 服务接口
│   │   │       │   └── impl/
│   │   │       │       └── XxxServiceImpl.java  # 服务实现
│   │   │       ├── mapper/                        # 数据访问层
│   │   │       │   └── XxxMapper.java            # MyBatis Mapper接口
│   │   │       ├── pojo/                          # 实体类（本服务专用）
│   │   │       │   └── Xxx.java
│   │   │       ├── config/                        # 配置类
│   │   │       │   ├── RedisConfig.java          # Redis配置
│   │   │       │   ├── MinIOConfig.java          # MinIO配置
│   │   │       │   └── MybatisPlusConfig.java    # MyBatis-Plus配置
│   │   │       └── {Module}Application.java      # 启动类
│   │   └── resources/
│   │       ├── application.yml                    # 服务配置（数据库、Redis等）
│   │       ├── mapper/                            # MyBatis XML映射文件
│   │       │   └── XxxMapper.xml
│   │       └── sql/                               # SQL脚本
│   │           └── xxx.sql
│   └── test/
├── pom.xml                                        # Maven配置
└── target/                                        # 编译输出
```

### 2.4 各服务详细说明

#### HomePage服务 (端口: 8081)
```
service/homePage/
├── controller/
│   ├── ActivityController.java        # 活动管理
│   ├── BannerController.java         # 轮播图
│   ├── AnnouncementController.java    # 公告
│   ├── MatchmakerController.java      # 红娘
│   ├── CourseController.java         # 课程
│   └── SuccessCaseController.java    # 成功案例
└── ...
```

#### Dynamic服务 (端口: 8086)
```
service/dynamic/
├── controller/
│   ├── DynamicController.java         # 动态管理
│   ├── CommentController.java         # 评论
│   ├── LikeController.java            # 点赞
│   └── ReportController.java          # 举报
└── ...
```

#### WebSocket服务 (端口: 1004)
```
service/websocket/
├── controller/
│   ├── ChatController.java            # 聊天REST API
│   ├── OnlineController.java         # 在线状态
│   └── IMController.java              # 腾讯云IM
├── config/
│   └── WebSocketConfig.java          # WebSocket配置
└── ...
```

#### Essential服务 (端口: 1005)
```
service/Essential/
├── controller/
│   ├── UserController.java            # 用户信息
│   ├── ProfileController.java         # 用户资料
│   ├── VipController.java             # VIP管理
│   ├── CheckinController.java         # 签到
│   └── FeedbackController.java        # 反馈
└── ...
```

#### Admin服务 (端口: 8088)
```
service/admin/
├── controller/
│   ├── AdminUserController.java       # 管理员管理
│   ├── DashboardController.java       # 数据面板
│   ├── DynamicAuditController.java    # 动态审核
│   └── ReportController.java          # 举报处理
└── ...
```

---

## 📱 三、前端代码结构

### 3.1 小程序端结构 (LiangZhiYUMao)

```
LiangZhiYUMao/
├── pages/                              # 页面目录
│   ├── index/                          # 首页
│   │   └── index.vue
│   ├── match/                          # 匹配
│   │   └── index.vue
│   ├── recommend/                      # 推荐
│   │   ├── index.vue
│   │   ├── user-detail.vue
│   │   └── user-dynamics.vue
│   ├── plaza/                          # 动态广场
│   │   ├── index.vue
│   │   ├── detail.vue
│   │   ├── publish.vue
│   │   └── report.vue
│   ├── message/                        # 消息
│   │   ├── index.vue
│   │   ├── chat.vue
│   │   └── system.vue
│   ├── astrology/                      # 星命运算
│   │   ├── index.vue
│   │   ├── zodiac.vue                  # 属相
│   │   ├── constellation.vue           # 星座
│   │   ├── constellation-match.vue     # 星座配对
│   │   ├── bazi.vue                    # 八字
│   │   ├── bazi-match.vue              # 八字配对
│   │   └── mbti.vue                    # MBTI
│   ├── matchmaker-workbench/           # 红娘工作台
│   │   ├── index.vue
│   │   ├── my-resources.vue
│   │   ├── resource-input.vue
│   │   ├── client-detail.vue
│   │   ├── precise-match.vue
│   │   ├── quality-resources.vue
│   │   ├── points-mall.vue
│   │   ├── courses.vue
│   │   ├── ranking.vue
│   │   ├── message.vue
│   │   ├── system-messages.vue
│   │   └── audit-records.vue
│   ├── activities/                     # 活动
│   │   ├── list.vue
│   │   └── detail.vue
│   ├── matchmakers/                     # 红娘
│   │   ├── list.vue
│   │   └── detail.vue
│   ├── courses/                         # 课程
│   │   ├── list.vue
│   │   └── detail.vue
│   ├── success-case/                    # 成功案例
│   │   ├── list.vue
│   │   └── detail.vue
│   ├── profile/                         # 个人资料
│   │   └── index.vue
│   ├── mine/                            # 我的
│   │   ├── index.vue
│   │   ├── my-activities.vue
│   │   └── my-dynamics.vue
│   ├── settings/                        # 设置
│   │   ├── index.vue
│   │   ├── id-verification.vue
│   │   └── phone-binding.vue
│   ├── vip/                             # VIP
│   │   └── index.vue
│   ├── customize/                       # 私人定制
│   │   └── index.vue
│   ├── blacklist/                       # 黑名单
│   │   └── index.vue
│   ├── feedback/                        # 反馈
│   │   └── index.vue
│   └── partner-requirement/             # 择偶要求
│       └── index.vue
├── components/                          # 组件
│   └── butlogin.vue                     # 登录按钮组件
├── utils/                               # 工具函数
│   ├── api.js                           # API封装（重要！）
│   ├── chat-api.js                      # 聊天API
│   ├── userAuth.js                      # 用户认证
│   ├── tim-manager.js                   # 腾讯云IM管理
│   ├── tim-presence-manager.js          # 在线状态管理
│   ├── websocket.js                     # WebSocket封装
│   ├── bazi.js                          # 八字工具
│   ├── constellation.js                 # 星座工具
│   ├── mbti.js                          # MBTI工具
│   ├── zodiac.js                       # 生肖工具
│   ├── zodiac-api.js                   # 生肖API
│   ├── zodiac-enhanced.js              # 生肖增强
│   └── util.js                         # 通用工具
├── config/                              # 配置文件
│   ├── api-config.js                   # API配置（重要！）
│   ├── match-config.js                 # 匹配配置
│   └── index.js                        # 主配置
├── store/                               # 状态管理
│   └── index.js
├── pages.json                           # 页面路由配置（重要！）
├── manifest.json                        # 应用配置
├── App.vue                              # 根组件
└── main.js                              # 入口文件
```

**关键文件说明**:
- `utils/api.js` - 所有API请求的封装，包含Token处理、错误处理
- `config/api-config.js` - 第三方API配置（天行数据、极速数据）
- `pages.json` - 页面路由配置，定义所有页面路径和导航栏
- `utils/tim-manager.js` - 腾讯云IM SDK封装

### 3.2 管理后台结构 (marriageAdmin-vue)

```
marriageAdmin-vue/
├── src/
│   ├── views/                           # 页面组件
│   │   ├── Login.vue                    # 登录页
│   │   ├── Dashboard.vue                # 数据面板
│   │   ├── banner/                       # 轮播图管理
│   │   │   └── BannerList.vue
│   │   ├── announcement/                # 公告管理
│   │   │   └── AnnouncementList.vue
│   │   ├── activity/                    # 活动管理
│   │   │   ├── ActivityList.vue
│   │   │   ├── ActivityForm.vue
│   │   │   └── ActivityRegistrations.vue
│   │   ├── matchmaker/                  # 红娘管理
│   │   │   ├── MatchmakerList.vue
│   │   │   ├── MatchmakerForm.vue
│   │   │   ├── MatchmakerAudit.vue
│   │   │   ├── CaseAudit.vue
│   │   │   ├── PointsOrderList.vue
│   │   │   └── ResourceList.vue
│   │   ├── course/                      # 课程管理
│   │   │   ├── CourseList.vue
│   │   │   ├── CourseForm.vue
│   │   │   └── CourseDetail.vue
│   │   ├── success-case/                # 成功案例
│   │   │   ├── SuccessCaseList.vue
│   │   │   └── SuccessCaseForm.vue
│   │   ├── user/                        # 用户管理
│   │   │   ├── UserList.vue
│   │   │   └── UserVipList.vue
│   │   ├── vip/                         # VIP管理
│   │   │   └── VipPackageList.vue
│   │   ├── dynamic/                     # 动态管理
│   │   │   ├── DynamicList.vue
│   │   │   └── DynamicDetail.vue
│   │   ├── report/                      # 举报管理
│   │   │   └── ReportList.vue
│   │   ├── admin/                       # 管理员管理
│   │   │   └── AdminUserList.vue
│   │   └── 404.vue                      # 404页面
│   ├── components/                      # 通用组件
│   │   ├── MainLayout.vue               # 主布局
│   │   ├── Sidebar.vue                  # 侧边栏
│   │   ├── Header.vue                   # 头部
│   │   └── ...
│   ├── router/                          # 路由配置
│   │   └── index.js                     # 路由定义和守卫（重要！）
│   ├── stores/                          # Pinia状态管理
│   │   ├── user.js                      # 用户状态（重要！）
│   │   └── counter.js
│   ├── utils/                           # 工具函数
│   │   └── request.js                   # Axios封装（重要！）
│   ├── config/                          # 配置文件
│   │   └── api.js                       # API端点定义（重要！）
│   ├── assets/                          # 静态资源
│   │   ├── css/                         # 样式文件
│   │   └── images/                      # 图片
│   ├── layouts/                         # 布局组件
│   │   └── MainLayout.vue
│   ├── App.vue                          # 根组件
│   └── main.js                          # 入口文件
├── public/                              # 公共资源
├── vite.config.js                       # Vite配置
├── package.json                         # 依赖配置
└── README.md                            # 说明文档
```

**关键文件说明**:
- `src/config/api.js` - 所有API端点定义
- `src/utils/request.js` - Axios请求封装，包含Token处理、错误处理
- `src/router/index.js` - 路由配置和权限守卫
- `src/stores/user.js` - 用户状态管理（Token、用户信息、权限）

---

## 🔍 四、代码查找指南

### 4.1 如何查找功能代码

#### 查找API接口
1. **小程序端**: 查看 `LiangZhiYUMao/utils/api.js`
2. **管理后台**: 查看 `marriageAdmin-vue/src/config/api.js`
3. **后端接口**: 查看对应服务的 `controller/` 目录

#### 查找业务逻辑
1. **后端**: 查看对应服务的 `service/impl/` 目录
2. **前端**: 查看对应页面的 `.vue` 文件

#### 查找数据库操作
1. **Mapper接口**: 查看 `mapper/` 目录
2. **SQL映射**: 查看 `resources/mapper/` 目录
3. **SQL脚本**: 查看 `resources/sql/` 目录

#### 查找配置
1. **网关路由**: `gateway/src/main/resources/application.yml`
2. **服务配置**: `service/{module}/src/main/resources/application.yml`
3. **前端API配置**: `LiangZhiYUMao/config/api-config.js` 或 `marriageAdmin-vue/src/config/api.js`

### 4.2 常见功能代码位置

| 功能 | 后端位置 | 前端位置 |
|------|---------|---------|
| 用户登录 | `service/login/` | `LiangZhiYUMao/utils/userAuth.js` |
| 用户信息 | `service/Essential/controller/UserController.java` | `LiangZhiYUMao/pages/profile/` |
| 动态管理 | `service/dynamic/controller/DynamicController.java` | `LiangZhiYUMao/pages/plaza/` |
| 聊天功能 | `service/websocket/` | `LiangZhiYUMao/pages/message/` |
| 匹配推荐 | `service/randomMatch/` | `LiangZhiYUMao/pages/match/` |
| 活动管理 | `service/homePage/controller/ActivityController.java` | `LiangZhiYUMao/pages/activities/` |
| 管理后台登录 | `service/admin/controller/AdminAuthController.java` | `marriageAdmin-vue/src/views/Login.vue` |
| 数据面板 | `service/admin/controller/DashboardController.java` | `marriageAdmin-vue/src/views/Dashboard.vue` |

---

## 📝 五、代码组织规范

### 5.1 后端代码规范

#### Controller层
- 职责: 处理HTTP请求，参数校验，调用Service
- 命名: `XxxController.java`
- 注解: `@RestController`, `@RequestMapping`

#### Service层
- 职责: 业务逻辑处理
- 命名: `XxxService.java` (接口), `XxxServiceImpl.java` (实现)
- 注解: `@Service`

#### Mapper层
- 职责: 数据库操作
- 命名: `XxxMapper.java` (接口), `XxxMapper.xml` (SQL映射)
- 注解: `@Mapper` 或继承 `BaseMapper<T>`

#### Pojo层
- 职责: 实体类定义
- 命名: 实体名（如 `User.java`）
- 注解: `@Data`, `@TableName`, `@TableId` 等

### 5.2 前端代码规范

#### 小程序端
- 页面: `pages/` 目录下，使用 `.vue` 文件
- 组件: `components/` 目录下
- 工具: `utils/` 目录下
- 配置: `config/` 目录下

#### 管理后台
- 页面: `src/views/` 目录下
- 组件: `src/components/` 目录下
- 工具: `src/utils/` 目录下
- 配置: `src/config/` 目录下
- 状态: `src/stores/` 目录下（Pinia）

---

## 🎯 六、开发建议

### 6.1 添加新功能

#### 后端
1. 在对应服务的 `pojo/` 创建实体类
2. 在 `mapper/` 创建Mapper接口
3. 在 `resources/mapper/` 创建SQL映射文件
4. 在 `service/` 创建Service接口和实现
5. 在 `controller/` 创建Controller
6. 在网关 `application.yml` 添加路由（如需要）

#### 前端（小程序）
1. 在 `pages/` 创建页面文件
2. 在 `pages.json` 添加路由配置
3. 在 `utils/api.js` 添加API方法
4. 在页面中调用API

#### 前端（管理后台）
1. 在 `src/views/` 创建页面组件
2. 在 `src/router/index.js` 添加路由
3. 在 `src/config/api.js` 添加API端点
4. 在页面中调用API

### 6.2 修改现有功能

1. **定位代码**: 使用本文档的"代码查找指南"
2. **理解结构**: 查看相关文件，理解代码组织
3. **修改代码**: 遵循现有代码规范
4. **测试验证**: 修改后充分测试

---

## 📚 七、相关文档

- `项目全面分析报告.md` - 详细的项目分析
- `项目快速参考手册.md` - 快速查找参考
- `项目架构分析报告.md` - 架构设计说明
- `技术栈快速参考.md` - 技术栈清单

---

**最后更新**: 2025-01-27