===============================================
开放接口 PHP 客户端 - 快速使用指南
===============================================

📁 文件清单
--------------
✅ OpenApiClient.php              - PHP 客户端类（核心）
✅ quickstart.php                 - 快速开始示例
✅ openapi-student-list-test.php  - 完整测试示例
✅ README.md                      - 详细使用文档
✅ 使用说明.txt                   - 本文件

===============================================
🚀 快速开始（3 步）
===============================================

步骤 1：获取应用凭证
-------------------
1. 打开浏览器访问：http://localhost:80
2. 登录管理后台
3. 进入【应用管理】菜单
4. 新增或查看应用，获取：
   - 应用编码（AppCode）：如 YY000001
   - 应用密钥（AppSecret）：如 2221c3d6f00c4baabfabfd4f679693f1

步骤 2：修改配置
-------------------
编辑 quickstart.php 文件，修改以下配置：

$config = [
    'baseUrl' => 'http://localhost:8080',
    'appCode' => 'YY000001',        ← 替换为您的应用编码
    'appSecret' => 'xxxxx...',      ← 替换为您的应用密钥
];

步骤 3：运行测试
-------------------
在终端执行：

cd /Users/felix/pgWorkSpace/pangu-user-platform/scripts/test
php quickstart.php

或使用命令行参数：

php openapi-student-list-test.php YY000001 your-app-secret

===============================================
📖 使用示例
===============================================

示例 1：基础调用
-------------------
<?php
require_once 'OpenApiClient.php';

$client = new OpenApiClient(
    'http://localhost:8080',
    'YY000001',
    'your-app-secret',
    false  // 调试模式
);

$result = $client->get('/open/api/student/list', [
    'pageNum' => 1,
    'pageSize' => 10
]);

if ($result['code'] === 200) {
    echo "总记录数: {$result['total']}\n";
}
?>

示例 2：带条件查询
-------------------
$result = $client->get('/open/api/student/list', [
    'pageNum' => 1,
    'pageSize' => 10,
    'studentName' => '张',  // 姓名模糊查询
    'schoolId' => 1,        // 按学校筛选
    'gradeId' => 2,         // 按年级筛选
    'classId' => 3          // 按班级筛选
]);

示例 3：开启调试模式
-------------------
$client = new OpenApiClient(
    'http://localhost:8080',
    'YY000001',
    'your-app-secret',
    true  // 开启调试，查看签名计算过程
);

===============================================
🔐 签名算法说明
===============================================

PHP 实现：
-----------
function calculateSign($params, $appSecret) {
    ksort($params);  // 1. 排序
    
    $signStr = '';
    foreach ($params as $key => $value) {
        if ($signStr) $signStr .= '&';
        $signStr .= $key . '=' . $value;
    }
    
    $signStr .= '&appSecret=' . $appSecret;  // 2. 追加密钥
    
    return strtoupper(md5($signStr));  // 3. MD5 + 大写
}

示例：
-----------
参数：pageNum=1, pageSize=10
密钥：a1b2c3d4e5f6789012345678901234ab

签名字符串：
pageNum=1&pageSize=10&appSecret=a1b2c3d4e5f6789012345678901234ab

MD5 结果（大写）：
A1B2C3D4E5F6G7H8I9J0K1L2M3N4O5P6

===============================================
❌ 常见错误处理
===============================================

1. 签名验证失败
   原因：appSecret 错误或签名计算错误
   解决：开启调试模式检查签名计算过程

2. 请求已过期
   原因：时间戳超过 5 分钟
   解决：同步服务器时间

3. 无权访问该接口
   原因：应用未授权该接口
   解决：在管理后台配置接口授权

4. 应用已停用
   原因：应用状态为停用
   解决：在管理后台启用应用

===============================================
📚 接口文档
===============================================

接口路径：/open/api/student/list
请求方法：GET

请求参数：
  - pageNum      [必填] 页码
  - pageSize     [必填] 每页条数
  - studentName  [可选] 学生姓名（模糊）
  - schoolId     [可选] 学校ID
  - gradeId      [可选] 年级ID
  - classId      [可选] 班级ID

响应字段：
  - studentId    学生ID
  - studentCode  学号
  - studentName  学生姓名（已脱敏）
  - gender       性别（0未知 1男 2女）
  - schoolName   学校名称
  - gradeName    年级名称
  - className    班级名称

===============================================
🔗 相关资源
===============================================

- 详细文档：README.md
- 技术方案：/docs/应用管理-需求与技术设计方案.md
- 实现说明：/docs/开放接口实现说明.md
- Swagger：http://localhost:8080/doc.html

===============================================
📞 技术支持
===============================================

如有问题，请查看：
1. README.md 详细文档
2. /tmp/pangu-admin.log 后端日志
3. 开启调试模式查看请求详情

pangu
2026-02-04
===============================================