# 投注游戏平台 - AI 上下文文档

## 变更记录 (Changelog)

### 2026-01-08 (当前更新)
- 增量更新：新增前台控制器模块文档 (`App/Controllers/Web/CLAUDE.md`)
- 完善模块索引：添加前台控制器模块
- 更新模块结构图：添加前台控制器节点
- 覆盖率提升：从 75% 提升至 85%

### 2026-01-08 12:51:57
- 初始化 AI 上下文文档
- 完成全仓清点与模块扫描
- 生成根级与模块级文档

---

## 项目愿景

这是一个基于 PHP 的在线投注游戏平台，主要提供骰子类游戏的投注服务。平台采用插件化架构设计，支持动态扩展功能，包含完整的用户管理、游戏管理、投注结算、财务管理等核心功能。

**核心特性**：
- 实时游戏投注与结算
- 插件化扩展机制（微信分享、二维码、短链接等）
- 完整的权限管理（前台用户/后台管理员）
- 视频直播集成（CKPlayer 支持多种流媒体格式）
- 事务安全的资金管理

---

## 架构总览

### 技术栈
- **后端**: PHP 7.4+ (OOP, Namespace)
- **数据库**: MySQL (通过 Medoo ORM)
- **前端框架**: Layui (UI 组件库)
- **视频播放**: CKPlayer (支持 HLS/FLV/MPEGTS)
- **架构模式**: MVC + 插件化

### 核心设计模式
1. **路由系统**: 自定义路由器，支持参数路由、依赖注入、路由组
2. **插件机制**:
   - 基于配置文件的插件声明 (`mian.php`)
   - 自动路由注册与冲突检测
   - 数据库表冲突检测
   - 插件生命周期钩子 (init/activate/deactivate)
3. **依赖注入**: 构造函数级别的依赖注入
4. **数据库事务**: 关键操作（投注、余额调整）使用 PDO 事务保证原子性

---

## 模块结构图

```mermaid
graph TD
    A["(根) 投注游戏平台"] --> B["App"];
    B --> C["Core (核心框架)"];
    B --> D["Controllers (控制器)"];
    B --> E["Plugins (插件系统)"];
    B --> F["Views (视图)"];

    D --> G["Admin (后台管理)"];
    D --> H["Web (前台)"];
    D --> I["Api (API接口)"];

    E --> J["WxShare (微信分享)"];
    E --> K["WxGCode (微信二维码)"];
    E --> L["SoUrl (短链接)"];

    A --> M["Db (数据库层)"];
    A --> N["Static (静态资源)"];
    A --> O["Models (数据模型)"];
    A --> P["Core (旧版核心)"];

    N --> Q["layui (UI框架)"];
    N --> R["ckplayer (视频播放)"];

    click C "./App/Core/CLAUDE.md" "查看核心框架文档"
    click G "./App/Controllers/Admin/CLAUDE.md" "查看后台管理文档"
    click H "./App/Controllers/Web/CLAUDE.md" "查看前台文档"
    click E "./App/Plugins/CLAUDE.md" "查看插件系统文档"
    click M "./Db/CLAUDE.md" "查看数据库层文档"
```

---

## 模块索引

| 模块路径 | 职责 | 语言 | 入口文件 | 状态 |
|---------|------|------|---------|------|
| `App/Core` | 核心框架层（路由、控制器基类、插件管理） | PHP | `Router.php`, `PluginManager.php` | ✅ 完整 |
| `App/Controllers/Admin` | 后台管理功能 | PHP | `*Controller.php` | ✅ 完整 |
| `App/Controllers/Web` | 前台用户功能 | PHP | `HomeController.php`, `BetController.php` | ✅ 完整 |
| `App/Plugins/WxShare` | 微信分享插件 | PHP | `mian.php` | ✅ 完整 |
| `App/Plugins/WxGCode` | 微信二维码插件 | PHP | `mian.php` | ✅ 完整 |
| `App/Plugins/SoUrl` | 短链接插件 | PHP | `mian.php` | ✅ 完整 |
| `Db` | 数据库访问层 | PHP | `Database.php`, `Medoo.php` | ✅ 完整 |
| `Static` | 静态资源（CSS/JS/图片/UI框架） | HTML/CSS/JS | `layui/`, `ckplayer/` | ✅ 完整 |
| `Models` | 数据模型（可能废弃） | PHP | `User.php`, `Game.php`, `Draw.php` | ⚠️ 部分 |
| `Core` | 旧版核心（可能废弃） | PHP | `Router.php`, `Database.php` | ⚠️ 部分 |

---

## 运行与开发

### 环境要求
- PHP >= 7.4
- MySQL >= 5.7
- Apache/Nginx (需配置 URL Rewrite)
- PHP 扩展: PDO, PDO_MySQL, JSON, MBString

### 安装步骤

1. **部署代码**
   ```bash
   # 将项目放置到 Web 服务器目录
   # 确保 Storage/log/ 目录可写
   chmod -R 755 /path/to/touzi/Storage
   ```

2. **配置数据库**
   ```bash
   # 编辑 Db/config.php
   # 修改数据库连接信息
   ```

3. **初始化数据库**
   ```bash
   # 访问安装页面
   http://yourdomain.com/install
   ```

4. **Apache 配置**
   - 项目根目录包含 `.htaccess` 文件
   - 确保启用 `mod_rewrite` 模块

5. **Nginx 配置**
   ```nginx
   location / {
       try_files $uri $uri/ /index.php?$query_string;
   }
   ```

### 目录权限
```
Storage/log/          # 日志目录（可写）
Db/installed.lock     # 安装锁文件（可写）
```

### 默认入口
- **前台**: `http://yourdomain.com/`
- **后台**: `http://yourdomain.com/admin`
- **安装**: `http://yourdomain.com/install`

---

## 测试策略

### 当前状态
⚠️ **未发现测试目录或测试文件**

建议的测试覆盖：
1. **单元测试**:
   - 插件管理器（路由冲突检测、表冲突检测）
   - 路由解析与匹配
   - 余额计算逻辑

2. **集成测试**:
   - 投注流程（下注 → 扣款 → 记录）
   - 期号开奖与结算
   - 插件安装与卸载

3. **安全测试**:
   - SQL 注入防护（目前使用 Medoo 的参数化查询）
   - XSS 防护（视图层需增强）
   - CSRF 防护（未发现 Token 机制）
   - 会话劫持防护（已实现 IP + UA 校验）

---

## 编码规范

### PHP 编码规范
1. **命名空间**: 遵循 PSR-4 规范
   - `App\Controllers\Admin\GameController`
   - `Db\Database`

2. **类命名**: PascalCase
   - `GameController`, `PluginManager`

3. **方法命名**: camelCase
   - `checkLogin()`, `loadEnabledPlugins()`

4. **数据库操作**: 统一使用 Medoo ORM
   ```php
   $db->select('users', '*', ['status' => 1]);
   ```

5. **事务处理**: 关键操作必须使用事务
   ```php
   $db->medoo->pdo->beginTransaction();
   try {
       // 操作
       $db->medoo->pdo->commit();
   } catch (\Exception $e) {
       $db->medoo->pdo->rollBack();
   }
   ```

### 插件开发规范
参见 `App/Plugins/CLAUDE.md`

---

## AI 使用指引

### 常见任务模式

#### 1. 添加新的后台功能
```
1. 创建控制器: App/Controllers/Admin/XxxController.php
2. 继承 AdminBaseController
3. 在 routes.php 注册路由
4. 创建视图: App/Views/Admin/xxx.php
5. 在主模板添加菜单项
```

#### 2. 修改投注逻辑
```
关键文件:
- App/Controllers/Web/BetController.php (投注入口)
- App/Controllers/Admin/PeriodController.php (开奖结算)
- App/Controllers/Admin/GameController.php (赔率配置)

⚠️ 必须使用事务保证原子性
⚠️ 必须锁定用户行防止并发扣款 (SELECT FOR UPDATE)
```

#### 3. 开发新插件
```
1. 在 App/Plugins/ 创建目录
2. 创建 mian.php 配置文件（必须包含元信息注释）
3. 定义 route_group、tables、init/activate/deactivate 钩子
4. 创建 Controllers/、Views/ 子目录
5. 通过后台插件管理安装
```

#### 4. 数据库迁移
```
当前没有迁移机制，数据库变更方式：
1. 插件: 通过 activate 钩子创建表
2. 核心表: 手动执行 SQL 或通过安装程序
```

### 安全注意事项
1. **不要直接拼接 SQL**: 使用 Medoo 的参数化查询
2. **敏感数据不输出**: 密码、token 等不要返回到前端
3. **权限检查**: 所有后台方法必须调用 `$this->checkLogin()` 或 `$this->checkAdmin()`
4. **金额运算**: 使用 `floatval()` 强制转换，避免精度问题
5. **并发控制**: 资金操作必须使用 `SELECT FOR UPDATE` 锁定

### 已知问题
1. **双重架构**: 存在 `App/` 和根目录两套 `Core/`、`Controllers/`，可能是迁移遗留
2. **缺少 CSRF 防护**: POST 请求未验证 Token
3. **缺少 API 限流**: 投注等接口容易被刷
4. **密码明文记录**: 某些日志可能包含敏感信息
5. **缺少单元测试**: 无自动化测试覆���

---

## 相关资源

- **Medoo 文档**: https://medoo.in/doc
- **Layui 文档**: https://layui.dev/
- **CKPlayer 文档**: https://www.ckplayer.com/

---

**最后更新**: 2026-01-08
**文档版本**: 1.1.0
**扫描覆盖率**: 约 85%（核心代码已扫描，部分静态资源未详查）

## 下一步建议

### 高优先级
1. **补充测试覆盖**: 为投注流程（BetController）编写单元测试和集成测试
2. **CSRF 防护**: 为所有 POST 请求添加 Token 验证
3. **API 限流**: 为投注接口添加频率限制（防止刷单）

### 中优先级
4. **清理双重架构**: 确认并删除废弃的 `Core/`、`Models/` 目录
5. **日志脱敏**: 确保日志不包含密码、Token 等敏感信息
6. **错误处理**: 统一错误响应格式，避免暴露内部信息

### 低优先级
7. **数据库迁移机制**: 引入迁移工具（如 Phinx）管理数据库变更
8. **代码规范检查**: 引入 PHP_CodeSniffer 或 PHPStan
9. **性能优化**: 添加 Redis 缓存层（游戏列表、赔率配置等）