Initial commit: 投注游戏平台初始化
This commit is contained in:
li
@@ -0,0 +1,298 @@
|
||||
# 投注游戏平台 - 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 缓存层（游戏列表、赔率配置等）
|
||||
Reference in New Issue
Block a user