## 牵手婚恋网站（qianshou）项目分析

---

### 一、项目概览

**牵手婚恋网站** 是一个用原生 PHP 8 构建的婚恋交友平台，采用 **MVC 架构**，不使用任何第三方框架，完全自主开发。项目运行在 LAMP 环境下（Linux + Apache + MySQL 8 + PHP 8+），使用 `.htaccess` 实现 URL 重写。

---

### 二、目录结构分析

```
qianshou/
├── app/                        # 应用核心目录（MVC 三层 + 配置）
│   ├── config/                 # 配置文件
│   │   ├── const.php           # 路径常量定义（PROJECT_ROOT, DOCUMENT_ROOT 等）
│   │   └── database.php        # 数据库连接工厂（ConnectDB 类），PDO 驱动
│   ├── controllers/            # 控制器层
│   │   ├── home/IndexController.php  # 前台页面控制器（首页、会员展示、更新日志）
│   │   ├── user/UserController.php   # 用户认证控制器（注册登录登出、个人中心路由）
│   │   └── admin/              # 后台管理控制器（IndexController, MemberController, ChangelogController）
│   ├── enums/                  # 枚举类
│   │   └── UpdateType.php      # 更新类型枚举
│   ├── helpers/                # 工具函数
│   │   ├── Func.php            # 递归文件查找函数（autoload 核心）
│   │   └── SessionHelper.php   # Session 辅助类（登录/登出/isLoggedIn 等静态方法）
│   ├── middleware/             # 中间件
│   │   ├── Auth.php            # 通用登录验证（requireLogin / check）
│   │   ├── AdminAuth.php       # 管理员鉴权中间件
│   │   └── MemberAuth.php      # 会员鉴权中间件
│   ├── models/                 # 模型层（数据访问）
│   │   ├── UserModel.php       # 用户认证模型（注册 bcrypt+盐值、登录验证、锁定机制）
│   │   ├── MemberModel.php     # 会员模型（会员编号生成、按 ID 查询）
│   │   └── ChangelogModel.php  # 更新日志模型
│   └── views/                  # 视图层（PHP 模板）
│       ├── home/               # 前台页面（首页 index、登录、注册、更新日志）
│       ├── user/pages/         # 用户个人中心（会员/家长/红娘/员工四种角色共用三套模板）
│       ├── admin/              # 后台管理页面
│       └── partials/           # 可复用部件
├── public/                     # Web 根目录（Apache DocumentRoot 指向此处）
│   ├── .htaccess               # URL 重写（将所有请求导向 index.php）
│   ├── index.php               # 入口文件（autoload + 路由分发 + 控制器调用）
│   └── assets/                 # 静态资源（css/js/fonts/images）
├── qianshou-db/                # 数据库备份目录
│   └── dump-qianshou-*.sql     # MySQL 导出文件
├── uploads/                    # 用户上传文件目录
│   ├── avatar/                 # 头像（含默认头像）
│   ├── photo/                  # 照片（已有 28 张用户照片）
│   ├── certificate/            # 证书
│   ├── idcard/                 # 身份证
│   └── others/                 # 其他文件
├── seed-demo-data.php          # 演示数据种子：管理员+红娘+会员王菲+家长张国立+家长成龙（含 5 个子会员）+员工关晓彤
├── seed-stars.php              # 明星种子脚本：10 位明星会员（刘德华/周杰伦/范冰冰/林志玲/张柏芝/杨幂/吴奇隆/李冰冰/陈冠希/马伊琍）
└── seed-matches.php            # 配对种子脚本：10 位新会员 + 21 条配对记录 + 80 条跟进记录
```

---

### 三、架构设计分析

#### 3.1 路由设计

项目使用 **单一入口模式** + **URL 参数路由**：

| URL 参数 | 含义 | 示例 |
|---|---|---|
| `s` | 控制器子目录（模块） | `home`, `user`, `admin` |
| `c` | 控制器类名（不含 `Controller` 后缀） | `Index` → `IndexController` |
| `a` | 方法名 | `login`, `register`, `profile` |

所有请求通过 `.htaccess` 规则 `RewriteRule ^(.*)$ index.php` 汇聚到 `public/index.php`，由 autoload 机制动态加载对应的控制器文件并调用方法。

#### 3.2 Autoload 自动加载

使用 `spl_autoload_register` 注册自定义加载器：
- 只搜索 `CONTROLLER_PATH/{s参数子目录}/` 下的文件
- 使用 `findFileRecursively()` 函数递归搜索多级子目录
- URL 参数 `s` 经过 `preg_replace('[^a-zA-Z0-9_/-]')` 严格过滤，防止目录遍历攻击

#### 3.3 MVC 层次结构

| 层 | 职责 | 关键文件 |
|---|---|---|
| **入口文件** | 启动会话、加载配置、路由分发 | `public/index.php` |
| **Controller** | 接收请求、校验参数、调用 Model、加载 View | `UserController.php` (~338行) |
| **Model** | PDO 数据库操作、业务逻辑封装 | `UserModel.php` (~159行) |
| **View** | PHP 原生模板（直接 `require_once` 引入 .php 文件） | `views/home/pages/*.php` |
| **Middleware** | 登录拦截、角色鉴权 | `Auth.php`, `AdminAuth.php`, `MemberAuth.php` |
| **Helper** | Session 管理、递归文件查找 | `SessionHelper.php`, `Func.php` |

#### 3.4 用户角色体系

项目定义了 **5 种角色**（`users.role` 字段）：

| role | 角色 | 关联表 | 说明 |
|---|---|---|---|
| 1 | 会员（征婚本人） | `member_base` | 自己找对象 |
| 2 | 家长/代理人 | `agents` + `member_base` | 替子女征婚，在 `agents` 表登记，同时为征婚人在 `member_base` 建记录 |
| 3 | 红娘 | `matchmakers` | 婚恋中介撮合 |
| 4 | 员工 | `staff` (role_level=1) | 服务男女会员 |
| 5 | 管理员 | `staff` (role_level=4) | 超级管理员 |

#### 3.5 安全机制

1. **密码加密**：`bcrypt` + 随机 16 字节盐值 `password_hash($password.$salt, PASSWORD_BCRYPT)`
2. **登录锁定**：连续失败 5 次自动锁定账号（`status=3`）
3. **Session 安全**：登录时 `session_regenerate_id(true)` 防止 Session 固定攻击
4. **目录遍历防护**：URL 参数严格过滤 `[^a-zA-Z0-9_/-]`
5. **SQL 注入防护**：全部使用 PDO 预编译语句参数绑定

#### 3.6 数据库设计概览（从种子脚本推理）

核心业务表：
- `users` — 统一用户认证表（phone, password_hash, salt, role, status, login_attempts）
- `staff` — 员工/管理员信息表
- `matchmakers` — 红娘信息表
- `agents` — 家长/代理人信息表
- `member_base` — 会员基本信息（含会员编号、自我简介等 30+ 字段）
- `member_marriage_end` — 婚姻终结记录（离异/丧偶）
- `member_marriage_end_child` — 子女信息
- `member_career` — 职业信息
- `member_education` — 教育经历
- `member_family` — 家庭背景
- `member_appearance` — 外貌信息
- `member_asset` — 资产状况
- `member_hobby` — 兴趣爱好
- `member_lifestyle` — 生活方式
- `member_personality_value` — 性格三观
- `member_requirement` — 择偶要求
- `match_pair` — 相亲配对记录
- `match_followup` — 相亲跟进记录

**会员资料采用 12 张子表（member_*）分散存储**，通过 `member_id` 与 `member_base` 一对一或一对多关联。

#### 3.7 视图模板策略

个人中心按角色分发到 **3 套共享模板**：
- `profile-member.php` — role=1（会员）和 role=2（家长）共享
- `profile-matchmaker.php` — role=3 红娘专用
- `profile-staff.php` — role=4（员工）和 role=5（管理员）共享

---

### 四、种子数据处理

| 脚本 | 内容 |
|---|---|
| `seed-demo-data.php` | 管理员潘乃让(role=5)、红娘周一本(role=3)、会员王菲(role=1, 两段婚姻两女儿)、家长张国立(role=2→儿子张默)、家长成龙(role=2→房祖名/刘诗雅/陈雨萱)、员工关晓彤(role=4) |
| `seed-stars.php` | 10 位明星会员：刘德华、周杰伦、范冰冰、林志玲、张柏芝、杨幂、吴奇隆、李冰冰、陈冠希、马伊琍——覆盖未婚/已婚/离异三种婚姻状态 |
| `seed-matches.php` | 10 位虚构会员 + 21 条配对记录 + ~80 条跟进记录——覆盖 2021~2026 年，管理员/红娘/员工三位不同操作者 |

种子脚本展示了**多角色协同操作**：管理员、红娘、员工各为不同的会员牵线配对，在 `match_pair` 表中通过 `operator_role` 和 `operator_user_id` 区分。

---

### 五、项目特点总结

1. **纯原生 PHP 开发**：无框架依赖，代码清晰可读
2. **严格的 PHP 8 类型声明**：所有文件使用 `declare(strict_types=1)`
3. **完善的会员资料体系**：12 张子表覆盖外貌、职业、教育、家庭、资产、兴趣爱好、生活方式、性格三观、择偶要求等
4. **区分"本人登记"和"家长代征婚"** 两种注册模式（`registrant_type`）
5. **成熟的配对跟进系统**：`match_pair` + `match_followup` 双表支撑完整的相亲流程管理
6. **细致的种子数据**：不只创建用户，还包含完整的婚姻史、教育经历、家庭背景等高质量演示数据