299 lines
8.8 KiB
Markdown
Executable File
299 lines
8.8 KiB
Markdown
Executable File
# 投注游戏平台 - 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 缓存层（游戏列表、赔率配置等）
|