new_sdk_wu/AGENTS.md

AGENTS.md — new_sdk

项目概述

游戏SDK平台 — 基于 ThinkPHP 5.0 的多模块应用，涵盖游戏渠道SDK对接、支付回调、公会管理和官网。PHP 7.0–7.2。

路径约定：

• 仓库根目录：以当前检出的项目目录为准，即包含本 AGENTS.md 的目录；禁止在说明、脚本或结论中写死某台机器上的绝对路径。
• 应用根目录：<仓库根目录>/www/new_sdk/。
• 除非特别标注为“仓库根目录相对路径”，本文中的应用代码路径均相对于 www/new_sdk/。
• 执行检查前先确认当前工作目录和实际文件位置，不要根据历史目录名推断项目路径。

架构

多模块 ThinkPHP 应用，通过域名路由将子域名映射到模块（application/route.php）：

子域名前缀	模块	用途
admin	admin/	后台管理
sdkapi / t	api/	支付回调 + SDK API
cpsapi / sdkcpsapi	guildapi/	公会API
mcpsapi	mcpsapi/	MCPS API
jhgame	complex/	渠道SDK对接
www	home/	官网 (PC)
m	mobile/	手机端

核心目录：

• application/common/ — 共享代码：model/（151个模型）、logic/、library/、controller/Base.php
• application/service/ — 顶层服务类（PayService、GamePayService 等）
• application/crontab/ — 定时任务源码，注册在 application/command.php；只允许阅读分析，禁止实际执行对应 php think <command>
• application/extra/ — 扩展配置：queue.php（Redis队列）、kafka.php、operatelog.php
• extend/ — 第三方SDK：alipay、alipay_wap、DouYinGameOpen、LdzfPay、XiTaiYouPay、Obs（华为）、tree
• public/ — Web根目录，入口文件 index.php
• think — CLI入口（类似 artisan）

入口文件

• Web: public/index.php — 加载 constants.php → constants/<APP_STATUS>.php → thinkphp/start.php
• CLI: think — 加载 public/constants.php → public/constants/<APP_STATUS>.php → thinkphp/console.php

环境配置

public/constants.php 是运行环境入口，负责定义 APP_STATUS。当前项目默认使用：

define('APP_STATUS', 'test');

因此 Web 和 CLI 默认都会继续加载：

public/constants/test.php

环境对应关系：

APP_STATUS	加载的常量配置
test	public/constants/test.php
dev	public/constants/dev.php
stable	public/constants/stable.php

除非用户明确要求切换环境，否则保持 APP_STATUS=test，不要修改为 dev 或 stable。

数据库、Redis、外部服务密钥等环境变量由应用根目录下的 .env 加载，ThinkPHP 通过 Env::get() 读取。.env 中可能包含真实凭据，读取和输出时必须脱敏，不要将密钥、密码或令牌写入回复、日志或新文档。

Docker Compose 中普通的 APP_ENV 不会自动修改 APP_STATUS；判断当前环境时必须以 public/constants.php 的实际定义为准。

开发命令

# 安装依赖
composer install
# 如果系统没有 composer，可以用仓库中已提交的 composer.phar
php composer.phar install

# PHPUnit（tests/ 目录目前不存在）
vendor/bin/phpunit

没有配置 lint、typecheck 或 codegen 命令，没有 CI 工作流。

仓库虽然提供 think CLI 入口，但根据本文“禁止操作”，不得执行任何 php think 命令。

关键约定

• PSR-4 自动加载：app\ 命名空间映射到 application/（composer.json）
• 模型命名：application/common/model/ 下使用 ThinkPHP 约定（如 app\common\model\Members）
• 控制器模式：每个模块有独立的 controller/、model/、validate/、view/ 目录
• 配置加载：模块级配置通过各模块目录下的 config.php；扩展配置在 application/extra/
• 队列：Redis 驱动（application/extra/queue.php），使用 db select 3
• Kafka：用于事件流（application/extra/kafka.php、application/command/KafkaConsumer.php）
• Session：API 模块使用 Redis 存储
• CORS：public/index.php 中完全开放（Access-Control-Allow-Origin: *）
• 响应码：100=登录失效, 110=参数有误, 120=处理提示, 130=执行异常, 200=正常

外部服务

• MySQL、Redis（具体服务端版本以当前部署配置和数据兼容性检查为准）
• 阿里云OSS / 华为云OBS（文件存储）
• 支付宝（SDK 在 extend/alipay/、extend/alipay_wap/）
• 微信支付（application/common/library/WeixinPay.php）
• 钉钉机器人（告警）
• 阿里云短信
• 抖音游戏开放平台（extend/DouYinGameOpen/）
• Kafka（事件流）
• GatewayWorker/WebSocket（application/common/logic/Websocket.php）

关联仓库

本仓库是五个仓库之一，其余不在本目录内：

• new_sdk_cps-admin — CPS后台
• new_sdk_cps-py — CPS打包（Python，被 application/common/logic/SubPackage.php 引用）
• new_sdk_ws — 通知服务（WebSocket）
• new_sdk_go — Excel导出 & 游戏礼包发放（Go，被 application/common/library/MakeReportGo.php 引用）

注意事项

• public/constants.php 及 public/constants/test.php、dev.php、stable.php 当前均存在；默认按 test 环境分析和运行。
• 路径必须以当前仓库根目录为基准，不能引用其他检出目录或历史机器上的绝对地址。
• application/common.php 约2000行全局辅助函数（auth_code、curl_post 等）— 所有模块都在用。
• 应用使用根目录下的 .env；其中可能包含真实凭据，检查时必须脱敏，并避免提交或复制到文档。
• composer.phar 已提交到仓库 — 系统没有 composer 时可以直接用。
• phpunit.xml 引用的 tests/ 目录在仓库中不存在。
• application/service/ 中有 _bak 文件（GamePayService_bak.php、MemberCoinService_bak.php）。

禁止操作

• 禁止启动定时任务 — 不要创建、启动或修改任何 cron / scheduled task（包括 crontab、systemd timer、Windows 计划任务、PHP 定时脚本等）。
• 禁止执行 php think 命令 — 不要运行仓库内的任何 php think <command>。涉及定时任务、队列消费、数据迁移等操作一律禁止。需要调试或了解某命令行为时，只能阅读源码，不可实际执行。