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 的实际定义为准。

Docker数据库部署约定

Docker部署时，数据库只能选择以下一种模式，禁止混用：

本地数据库模式：启动 Compose 中的 MySQL，并使用仓库根目录相对路径 qita/sql/new_sdk.sql 初始化本地 new_sdk 数据库；应用数据库主机应使用 Compose 服务名 mysql，不能使用 127.0.0.1，也不能同时连接测试服数据库。
测试服数据库模式：不执行本地SQL初始化，应用直接使用测试环境已有的数据库连接配置；不得将 new_sdk.sql 自动导入测试服，也不得在未得到用户明确授权时修改测试服表结构或数据。

执行Docker部署、修改 Compose 或调整数据库配置前，必须先确认当前采用哪一种模式，并在结果中明确说明。若用户未指定，只能检查和说明两种方案，不得擅自连接测试服或执行SQL导入。

public/constants/test.php 提供 APP_STATUS=test 对应的平台常量配置；数据库连接参数仍由应用根目录 .env 中的 [database] 配置提供。测试服连接信息属于敏感数据，读取和输出时必须脱敏。

开发命令

# 安装依赖
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）。

禁止操作

禁止执行 php think 命令 — 不要运行仓库内的任何 php think <command>。涉及定时任务、队列消费、数据迁移等操作一律禁止。需要调试或了解某命令行为时，只能阅读源码，不可实际执行。
禁止启动队列和事件消费者 — 不要启动、重启、监听或后台运行任何 Queue Worker、queue:work、queue:listen、Kafka Consumer、Redis队列消费者、Workerman、GatewayWorker或其他常驻消费进程。允许为Web应用启动MySQL、Redis等基础依赖服务，但不得同时启动任何消费程序。
需要分析定时任务、队列、消费者或框架命令行为时，只能阅读源码和配置，允许进行不触发业务执行的静态检查；不得实际运行、试跑或连接后开始消费。

AGENTS.md 7.8 KB Permalink History Raw