# 第三阶段：架构设计审查报告

## 审查概述

| 项目 | 详情 |
|------|------|
| 审查日期 | 2026年5月19日 |
| 审查范围 | 模块划分、路由设计、数据库设计、多租户隔离、设计模式 |
| 发现问题数 | **32个** |
| 高风险 | 8个 |
| 中风险 | 15个 |
| 低风险 | 9个 |

---

## 1. 模块架构分析

### 1.1 模块结构总览

| 模块 | 域名映射 | 职责 | 控制器数 | 完整度 |
|------|----------|------|----------|--------|
| **admin** | admin.* | 后台管理系统 | 99 | ✅ 完整 |
| **api** | sdkapi.* | SDK客户端接口 | 79 | ⚠️ 缺Service |
| **common** | 禁止访问 | 公共基础层 | - | ✅ 完整 |
| **complex** | jhgame.* | 聚合渠道接入 | 19 | ❌ 缺Model/Service |
| **guildapi** | cpsapi.* | CPS渠道商API | 28 | ❌ 缺Model/Service |
| **mcpsapi** | mcpsapi.* | MCPS渠道商API | 16 | ❌ 缺Model/Service |
| **home** | www.* | PC官网 | 16 | ✅ 完整 |
| **mobile** | m.* | 移动端官网 | 14 | ✅ 完整 |
| **service** | - | 独立服务层 | - | ✅ 12个服务 |
| **crontab** | - | 定时任务 | 3 | ⚠️ 简单 |
| **command** | - | 命令行入口 | 1 | ⚠️ 简单 |

### 1.2 模块依赖关系

```
                    ┌─────────────────────────────────────┐
                    │          common (公共基础层)          │
                    │  Model(140+) / Logic / Library /     │
                    │  Service / Factory / Contracts       │
                    └──────────┬──────────────────────────┘
                               │
        ┌──────────┬───────────┼───────────┬──────────┬──────────┐
        ▼          ▼           ▼           ▼          ▼          ▼
    ┌──────┐  ┌────────┐  ┌────────┐  ┌────────┐  ┌──────┐  ┌───────┐
    │admin │  │  api   │  │guildapi│  │mcpsapi │  │ home │  │mobile │
    └──────┘  └────────┘  └────────┘  └────────┘  └──────┘  └───────┘
                               │
                               ▼
                    ┌──────────────────┐
                    │    complex       │
                    │  (53个渠道适配器) │
                    └──────────────────┘
```

### 🔴 高风险问题

#### 1.1 guildapi 与 mcpsapi 大量重复代码
- **问题**：两个模块有 **14+ 个同名控制器**，代码几乎相同
- **重复控制器**：Account, Alliance, ChannelRebind, ChannelRecharge, ChannelSettle, ChannelTrade, CoinTransfer, Game, Guild, Login, Member 等
- **影响**：修改一处需同步修改另一处，维护成本高
- **建议**：提取公共 Guild 基类到 common，差异通过配置实现

#### 1.2 common 模块职责过重（上帝模块）
- **问题**：
  - `common/model` 包含 **140+ 个模型**，承载全部业务模型
  - `common.php` 包含 **1800+ 行**全局函数
  - 混杂渠道/支付/加密/通知等各种逻辑
- **影响**：代码难以理解、测试和维护
- **建议**：按业务域拆分到各模块

#### 1.3 complex 模块只有 Controller
- **问题**：19 个渠道控制器直接操作数据库，无独立业务层
- **影响**：渠道接入逻辑散落在 controller 中，难以维护
- **建议**：增加统一的渠道接入 service，使用策略模式

### 🟡 中风险问题

#### 1.4 api 模块 service 层薄弱
- **问题**：79 个 controller 但只有 4 个 service 文件
- **影响**：大量业务逻辑直接写在 controller 中
- **建议**：将业务逻辑下沉到 service 层

#### 1.5 home 与 mobile 模块高度重复
- **问题**：两个模块有 **12 个同名控制器**，View 目录结构几乎一致
- **影响**：维护成本高，修改需同步两处
- **建议**：使用响应式设计或提取共享 controller/service

#### 1.6 存在 .bak 备份文件和废弃代码
- **位置**：
  - `guildapi/ChannelSettle.php.bak`
  - `guildapi/ChannelWithdraw.php.bak`
  - `service/GamePayService_bak.php`
  - `service/MemberCoinService_bak.php`
- **建议**：清理废弃代码，使用版本控制管理历史

---

## 2. 路由设计分析

### 2.1 子域名映射

| 域名 | 模块 | 用途 |
|------|------|------|
| sdkapi.* | api | SDK核心接口 |
| t.* | api | 推广短链 |
| cpsapi.* | guildapi | CPS API |
| mcpsapi.* | mcpsapi | MCPS API |
| jhgame.* | complex | 聚合游戏 |
| www.* | home | PC官网 |
| m.* | mobile | 手机端 |
| admin.* | admin | 后台管理 |
| * | home | 默认（通配） |

### 🔴 高风险问题

#### 2.1 测试路由生产环境暴露
**文件**：`route.php:156-157`
```php
Route::get('test_pay', 'Api/Index/pay');    // 测试支付！
Route::get('notify', 'Api/Index/notify');   // 通知回调！
```
- **风险**：无域名约束，任何域名都可访问
- **建议**：立即移除或添加环境判断

#### 2.2 路由文件中直接查询数据库
**文件**：`route.php:68,87`
```php
$arrAlias = db('nw_promotion_short_link')->where([...])->find();
```
- **风险**：数据库异常会导致整个路由系统崩溃
- **建议**：迁移到中间件或服务层

#### 2.3 `*` 通配域名风险
**文件**：`route.php:27`
```php
'*' => 'home'
```
- **风险**：任意子域名都会路由到 home 模块
- **建议**：移除通配或添加白名单验证

### 🟡 中风险问题

#### 2.4 v1/v2 API 无显式路由
- **问题**：api 模块 45+ 个 v1 控制器、21 个 v2 控制器，但**没有定义任何显式路由**
- **影响**：
  - 访问路径为 `/{controller}/{action}` 格式
  - 无版本前缀保护
  - 控制器方法直接暴露为路由
- **建议**：添加版本前缀路由 + 认证中间件

#### 2.5 路由文件过于臃肿
- **问题**：445 行全部集中在一个文件
- **影响**：PC 端 + Mobile 端 + API + 短链逻辑混杂
- **建议**：按模块拆分为多个路由文件

#### 2.6 路由命名不规范
**问题示例**：
```php
'/tgy'      → "推广页"拼音缩写
'syxy'      → "使用协议"拼音缩写
'zhaq'      → "账户安全"拼音缩写
'kf'/'kc'   → "客服"/"课程"拼音缩写
```
- **建议**：统一使用英文命名

#### 2.7 路由冲突
**问题**：`gift/index` 路由在第 248 行直接覆盖了第 202 行的定义

### 🟢 低风险

#### 2.8 域名判断使用 HTTP_HOST
- **风险**：存在 Host Header Injection 风险
- **建议**：使用可信域名白名单

#### 2.9 支付相关接口无域名约束
- **位置**：`mp/get_wxmp_code`, `mp/get_pay` 等
- **建议**：添加 domain 限制

---

## 3. 数据库设计分析

### 3.1 模型分类统计

| 分类 | 数量 | 代表模型 |
|------|------|----------|
| 游戏相关 | 32 | Game, GameInfo, GameServer |
| 渠道相关 | 28 | Channel, ChannelGame, ChannelDivide |
| 用户/会员 | 15 | Members, MemberCoinInfo |
| 支付/财务 | 18 | Pay, PayCpinfo, CoinTransfer |
| 福利系统 | 8 | Welfare, WelfareGrant |
| 系统配置 | 12 | Setting, Admin, Department |
| 日志记录 | 10 | Loginlog, Operatelog |
| Complex聚合 | 8 | ComplexMembers, ComplexPay |
| 其他业务 | 16 | SdkGameList, Libao, Gift |

### 3.2 表前缀分布

```
cy_* 前缀: 约 95 个表 (游戏核心业务)
nw_* 前缀: 约 56 个表 (渠道/扩展业务)
```

### 🔴 高风险问题

#### 3.1 无统一基类
- **问题**：151 个模型直接继承 `\think\Model`，无自定义基类
- **影响**：无法统一管理公共行为（软删除、时间戳、日志等）
- **建议**：创建 BaseModel 统一公共行为

#### 3.2 关联关系严重缺失
- **现状**：仅 **4 个模型**定义了关联关系
- **问题**：大量使用手动 JOIN，代码冗余
- **建议**：为核心模型定义关联关系

```php
// 当前：手动 JOIN
->join('cy_gameinfo b', 'a.id=b.game_id')

// 建议：模型关联
public function gameInfo() {
    return $this->hasOne('GameInfo', 'game_id');
}
```

### 🟡 中风险问题

#### 3.3 软删除实现不一致
| 方式 | 使用情况 |
|------|----------|
| SoftDelete trait | 仅 1 处（已注释） |
| `isdelete` 字段 | 部分模型 |
| `flag` 字段 | 部分模型 |
| 无软删除 | 大部分模型 |

#### 3.4 时间戳处理混乱
| 方式 | 模型数量 |
|------|----------|
| autoWriteTimestamp=true | ~20 |
| dateFormat=false | ~15 |
| 手动 getter 转换 | ~30 |
| 无时间戳处理 | ~86 |

#### 3.5 字段命名不一致
- `game_id` vs `gameid`
- `create_time` vs `createtime`
- `channel_id` vs `channelid`

#### 3.6 表前缀混乱
- `cy_*` 和 `nw_*` 混用
- 缺乏统一命名规范

### 3.7 核心表关系图

```
┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│   Channel   │────▶│  Members    │────▶│     Pay     │
│  (渠道表)   │     │  (用户表)   │     │  (支付表)   │
└─────────────┘     └─────────────┘     └─────────────┘
       │                   │                   │
       ▼                   ▼                   ▼
┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│ ChannelGame │     │MemberCoinInfo│    │  PayCpinfo  │
│ (渠道游戏)  │     │ (平台币记录)│     │(支付回调)   │
└─────────────┘     └─────────────┘     └─────────────┘
       │
       ▼
┌─────────────┐     ┌─────────────┐
│    Game     │────▶│  GameInfo   │
│  (游戏表)   │     │ (游戏详情) │
└─────────────┘     └─────────────┘
       │
       ▼
┌─────────────┐
│ GameServer  │
│  (区服表)   │
└─────────────┘
```

---

## 4. 多租户隔离分析

### 4.1 隔离字段

```php
// 渠道ID隔离 - 出现在约 40+ 个表中
channel_id

// 游戏ID隔离 - 出现在约 50+ 个表中
game_id / gameid
```

### 4.2 实现方式

```php
// 查询时手动添加条件
->where('channel_id', $channelId)
->where(['game_id' => $gameid])

// 渠道层级查询
->where(['channel.id_path' => ['LIKE', '%,' . $channelId . ',%']])
```

### 4.3 渠道层级结构

```
Channel表字段:
- id
- parent_id (父渠道)
- level (1=会长, 2=子会长, 3=推广员)
- id_path (路径: ,1,2,3,)
```

### 🟡 中风险问题

#### 4.1 多租户隔离依赖手动 WHERE
- **问题**：每个查询都需要手动添加 `channel_id` 和 `game_id` 条件
- **风险**：遗漏条件会导致数据泄露
- **建议**：使用 Trait 或全局作用域自动注入

```php
// 建议：创建 MultiTenant Trait
trait MultiTenant {
    public function scopeChannel($query, $channelId) {
        return $query->where('channel_id', $channelId);
    }
    
    public function scopeGame($query, $gameId) {
        return $query->where('game_id', $gameId);
    }
}
```

---

## 5. 设计模式分析

### 5.1 工厂模式 ⭐⭐⭐⭐

**实现位置**：`common/factory/Pay.php`

```
Pay::createPayment($way) → switch-case 创建支付实例
├── LdysPay (联动优势)
├── QzlPay  (趣支付)
├── YyYbPay (优亿支付)
├── XtyPay  (喜钛游)
├── SywPay  (十一玩)
└── AliPay  (支付宝)
```

**问题**：
- 使用 `switch-case` 硬编码，违反开闭原则
- 新增支付方式需修改工厂类

**建议**：改为注册式工厂

### 5.2 策略模式 ⭐⭐⭐⭐

**实现位置**：`api/complex/ComplexInterface.php` + 50+ 个渠道实现类

```
ComplexInterface (接口)
├── checkLogin()   - 登录验证
├── paySign()      - 签名验证
├── getData()      - 数据转换
├── getFail()      - 失败响应
└── getSuccess()   - 成功响应
```

**问题**：
- 接口方法不完整，部分实现类有额外方法
- 缺少抽象基类，各实现类有重复代码

### 5.3 服务层模式 ⭐⭐⭐

**实现位置**：`service/` 目录（12 个服务类）

| 服务类 | 职责 | 行数 |
|--------|------|------|
| GamePayService | 游戏支付业务 | 629 |
| PayService | 支付渠道对接 | 943 |
| MemberCoinService | 平台币充值 | - |
| RetaineService | 留存数据统计 | - |

**问题**：
- 职责过重：PayService 943 行
- 代码重复：支付渠道随机选择逻辑重复

### 5.4 异常处理 ⭐⭐

**实现位置**：`common/exception/Http.php`

**问题**：
- 钉钉通知代码被注释掉
- 只处理 HTTP 异常，业务异常分散
- 缺少自定义业务异常类

### 5.5 日志处理 ⭐⭐⭐

**实现位置**：`common.php` 中的 `log_message()` 函数

**使用情况**：418 处调用，按模块分目录存储

**问题**：
- 每次调用都重新初始化 Log 配置
- 日志格式不统一
- 缺少请求 ID 追踪

### 5.6 事件/观察者模式 ⭐⭐

**现状**：
- `tags.php` 定义了行为钩子，但全部为空数组
- 支付成功、登录成功等关键节点未使用事件驱动

---

## 6. 设计模式总体评估

| 维度 | 评分 | 说明 |
|------|------|------|
| 架构分层 | ⭐⭐⭐ | Controller → Service → Logic → Model，但层次混乱 |
| 设计模式运用 | ⭐⭐⭐ | 工厂+策略模式较好，但缺少 Repository、Event |
| 代码复用 | ⭐⭐ | 大量重复代码（支付初始化、渠道选择） |
| 可测试性 | ⭐ | 直接依赖实例化，无依赖注入 |
| 异常处理 | ⭐⭐ | 分散处理，无统一错误码 |

---

## 7. 问题汇总

### 按风险等级分类

#### 🔴 高风险
| 序号 | 问题 | 位置 |
|------|------|------|
| 1 | 测试路由生产环境暴露 | `route.php:156-157` |
| 2 | 路由文件中直接查询数据库 | `route.php:68,87` |
| 3 | guildapi 与 mcpsapi 大量重复 | 14+ 个同名控制器 |
| 4 | common 模块职责过重 | 1800+ 行全局函数 |
| 5 | complex 模块缺少 Model/Service | 19 个控制器直接操作数据库 |
| 6 | 无统一模型基类 | 151 个模型各自为政 |
| 7 | 关联关系严重缺失 | 仅 4 个模型定义关联 |
| 8 | `*` 通配域名风险 | `route.php:27` |

#### 🟡 中风险
| 序号 | 问题 | 数量/位置 |
|------|------|----------|
| 1 | v1/v2 API 无显式路由 | api 模块 |
| 2 | 路由文件臃肿 | 445 行 |
| 3 | 路由命名不规范 | 多处拼音缩写 |
| 4 | 路由冲突 | `gift/index` |
| 5 | api 模块 service 层薄弱 | 79 controller / 4 service |
| 6 | home/mobile 高度重复 | 12 个同名控制器 |
| 7 | 软删除不一致 | 多种方式并存 |
| 8 | 时间戳处理混乱 | 4 种方式并存 |
| 9 | 字段命名不一致 | game_id vs gameid |
| 10 | 多租户隔离手动 WHERE | 全局 |
| 11 | 工厂模式违反开闭原则 | Pay.php |
| 12 | 策略模式缺少抽象基类 | ComplexInterface |
| 13 | 服务层职责过重 | PayService 943 行 |
| 14 | 异常处理不统一 | 全局 |
| 15 | 事件机制未启用 | tags.php |

#### 🟢 低风险
| 序号 | 问题 |
|------|------|
| 1 | 域名判断使用 HTTP_HOST |
| 2 | 支付接口无域名约束 |
| 3 | 存在 .bak 备份文件 |
| 4 | 日志格式不统一 |
| 5 | 缺少请求 ID 追踪 |
| 6 | 表前缀混乱 |
| 7 | 缺少 Repository 层 |
| 8 | 缺少依赖注入 |
| 9 | MLBB 下载路由无参数验证 |

---

## 8. 改进建议

### 第一优先级（架构层面）
1. **合并 guildapi 与 mcpsapi**：提取公共 Guild 基类
2. **拆分 common.php**：按职责拆分到独立类
3. **移除测试路由**：删除 `test_pay` 和 `notify` 路由
4. **路由文件拆分**：按模块拆分为多个文件

### 第二优先级（设计层面）
5. **创建统一模型基类**：BaseModel 统一公共行为
6. **定义核心模型关联关系**：Game、Members、Pay 等
7. **增加 api 的 service 层**：业务逻辑下沉
8. **启用事件机制**：支付成功、登录成功使用事件驱动

### 第三优先级（规范层面）
9. **统一命名规范**：字段名、表名、路由名
10. **统一软删除实现**：使用 SoftDelete trait
11. **统一时间戳处理**：autoWriteTimestamp
12. **清理废弃代码**：删除 .bak 文件

### 第四优先级（长期规划）
13. **引入 Repository 层**：解耦 Model 与业务逻辑
14. **依赖注入**：使用容器管理依赖
15. **RESTful API 改造**：新 API 按 RESTful 规范设计
16. **home/mobile 合并**：使用响应式设计

---

## 9. 参考架构

### 推荐目录结构
```
application/
├── common/
│   ├── model/          # 仅共享模型（10-20个）
│   ├── base/           # BaseController, BaseModel, BaseLogic
│   ├── trait/          # MultiTenant, SoftDelete 等
│   ├── event/          # 事件定义
│   └── exception/      # 业务异常类
├── admin/
│   ├── controller/
│   ├── model/          # Admin 专属模型
│   ├── service/
│   └── validate/
├── api/
│   ├── v1/
│   │   ├── controller/
│   │   └── service/
│   ├── v2/
│   │   ├── controller/
│   │   └── service/
│   └── complex/        # 渠道适配器
├── guildapi/           # 合并 mcpsapi
│   ├── controller/
│   └── service/
└── route/
    ├── route.php       # 入口
    ├── route_api.php
    ├── route_admin.php
    ├── route_home.php
    └── route_guild.php
```

---

*审查报告生成时间：2026年5月19日*