fengshao1227/pk10

Fork 0

Files

T

li 77ca2cc8b3 Initial commit: 投注游戏平台初始化

2026-02-25 01:26:58 +08:00

8.8 KiB

Executable File

Raw Permalink Blame History

投注游戏平台 - 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 + 插件化

核心设计模式

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

模块结构图

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

安装步骤

部署代码

# 将项目放置到 Web 服务器目录
# 确保 Storage/log/ 目录可写
chmod -R 755 /path/to/touzi/Storage

配置数据库

# 编辑 Db/config.php
# 修改数据库连接信息

初始化数据库

# 访问安装页面
http://yourdomain.com/install

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

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

测试策略

当前状态

⚠️ 未发现测试目录或测试文件

建议的测试覆盖：

单元测试:
- 插件管理器（路由冲突检测、表冲突检测）
- 路由解析与匹配
- 余额计算逻辑
集成测试:
- 投注流程（下注 → 扣款 → 记录）
- 期号开奖与结算
- 插件安装与卸载
安全测试:
- SQL 注入防护（目前使用 Medoo 的参数化查询）
- XSS 防护（视图层需增强）
- CSRF 防护（未发现 Token 机制）
- 会话劫持防护（已实现 IP + UA 校验）

编码规范

PHP 编码规范

命名空间: 遵循 PSR-4 规范
- App\Controllers\Admin\GameController
- Db\Database
类命名: PascalCase
- GameController, PluginManager
方法命名: camelCase
- checkLogin(), loadEnabledPlugins()

数据库操作: 统一使用 Medoo ORM

$db->select('users', '*', ['status' => 1]);

事务处理: 关键操作必须使用事务

$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 或通过安装程序

安全注意事项

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

已知问题

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

下一步建议

高优先级

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

中优先级

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

低优先级

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

8.8 KiB Executable File Raw Permalink Blame History Unescape Escape