# 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`。当前项目默认使用：

```php
define('APP_STATUS', 'test');
```

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

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

## 开发命令

```bash
# 安装依赖
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>`。涉及定时任务、队列消费、数据迁移等操作一律禁止。需要调试或了解某命令行为时，只能阅读源码，不可实际执行。