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

## Docker数据库部署约定

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

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

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

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

## 开发命令

```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）。


## 禁止操作

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