Ecology 模块 API 文档

概述

Ecology 模块提供生态系统相关的 API 接口，支持用户信息查询、团队关系管理和下级统计等功能。所有接口都采用 AES-256-CBC 加密算法保证数据传输安全。

基础信息

模块路径: app/Module/Ecology
API 基础路径: /api/ecology
路由前缀: ecology
加密算法: AES-256-CBC
签名算法: SHA256
数据有效期: 300秒（5分钟）

路由列表

1. 测试接口

1.1 测试加密接口

路径: GET /api/ecology/test-encrypt
控制器: TestController@testEncrypt
中间件: 无
描述: 测试数据加密功能

1.2 测试解密接口

路径: POST /api/ecology/{ecology_id}/test-decrypt
控制器: TestController@testDecrypt
中间件: EncryptionMiddleware
描述: 测试数据解密功能（用于调试）

2. 业务接口

2.1 获取用户信息

路径: POST /api/ecology/{ecology_id}/userInfo
控制器: EcologyController@getUserInfo
中间件: EncryptionMiddleware
描述: 根据用户密钥获取用户ID

2.2 获取用户团队关系

路径: POST /api/ecology/{ecology_id}/userTeam
控制器: EcologyController@getUserTeam
中间件: EncryptionMiddleware
描述: 获取用户的3级上级关系链

2.3 获取用户下级统计

路径: POST /api/ecology/{ecology_id}/userLevelCount
控制器: EcologyController@getLevelCount
中间件: EncryptionMiddleware
描述: 获取用户下级人数统计（支持1级和3级）

加密机制

加密算法

算法: AES-256-CBC
密钥来源: ecology_config 表的 app_key 字段
IV向量: 随机生成16字节，每次请求不同
签名: SHA256(data + iv + timestamp + app_key)

请求格式

{
    "data": "加密后的请求数据(Base64编码)",
    "iv": "IV向量(Base64编码)",
    "timestamp": 1234567890,
    "sign": "数据签名(SHA256)"
}

响应格式

{
    "data": "加密后的响应数据(Base64编码)",
    "iv": "IV向量(Base64编码)",
    "timestamp": 1234567890,
    "sign": "数据签名(SHA256)"
}

加密流程

获取生态配置中的 app_key
生成随机IV向量（16字节）
使用AES-256-CBC加密原始JSON数据
对加密结果进行Base64编码
生成签名：SHA256(data + iv + timestamp + app_key)
组装最终请求数据

解密流程

验证时间戳有效性（默认5分钟有效期）
验证签名：SHA256(data + iv + timestamp + app_key) == sign
使用IV和app_key解密数据
解析解密后的JSON数据

API 接口详情

1. 测试加密接口

接口地址: GET /api/ecology/test-encrypt

请求参数:

支持任意GET参数，用于测试加密功能
示例：userId=10002&level=1

响应示例:

{
    "data": "eyJzdGF0dXMiOiJzdWNjZXNzIn0=",
    "iv": "MTIzNDU2Nzg5MGFiY2RlZg==",
    "timestamp": 1234567890,
    "sign": "a1b2c3d4e5f6..."
}

错误响应:

{
    "error": "加密失败: 错误信息"
}

2. 测试解密接口

接口地址: POST /api/ecology/{ecology_id}/test-decrypt

路径参数:

ecology_id: 生态ID（整数）

请求参数:

加密的请求数据（通过中间件自动解密）

响应:

直接输出解密后的数据（用于调试）

3. 获取用户信息接口

接口地址: POST /api/ecology/{ecology_id}/userInfo

路径参数:

ecology_id: 生态ID（整数）

请求参数（解密后）:

{
    "userKey": "用户密钥（字符串，必填）"
}

成功响应:

{
    "userId": 12345
}

错误响应:

{
    "code": 400,
    "message": "参数错误",
    "errors": {
        "userKey": ["userKey字段是必填的"]
    }
}

4. 获取用户团队关系接口

接口地址: POST /api/ecology/{ecology_id}/userTeam

路径参数:

ecology_id: 生态ID（整数）

请求参数（解密后）:

{
    "userId": 12345
}

成功响应:

{
    "team": {
        "1": 10001,
        "2": 10002,
        "3": 10003
    }
}

响应说明:

team 对象的键表示级别（1、2、3级上级）
值为对应级别的上级用户ID
如果某级别没有上级，值为 null

错误响应:

{
    "code": 400,
    "message": "参数错误",
    "errors": {
        "userId": ["userId字段是必填的"]
    }
}

5. 获取用户下级统计接口

接口地址: POST /api/ecology/{ecology_id}/userLevelCount

路径参数:

ecology_id: 生态ID（整数）

请求参数（解密后）:

{
    "userId": 12345,
    "level": 1
}

参数说明:

userId: 用户ID（整数，必填）
level: 统计级别（整数，必填，只能是1或3）

成功响应:

{
    "level": 1,
    "count": 25
}

响应说明:

level: 请求的统计级别
count: 对应级别的下级人数

错误响应:

{
    "code": 400,
    "message": "参数错误：level只能是1或3",
    "errors": {
        "level": ["level字段必须是1或3"]
    }
}

服务类说明

EcologyService 服务类

主要方法

1. getEcologyLink($userId, $ecologyId)

功能: 生成生态链接
参数:
- $userId: 用户ID
- $ecologyId: 生态ID
返回: 生态链接字符串
异常: 当生态配置不存在时抛出异常

2. getUserInfo($userKey)

功能: 根据用户密钥获取用户ID
参数: $userKey - 用户密钥
返回: 用户ID

3. getUserTeam($userId)

功能: 获取用户上级关系链（3级）
参数: $userId - 用户ID
返回: 数组，包含1、2、3级上级用户ID

4. getLevelCount($userId, $level)

功能: 获取用户下级人数统计
参数:
- $userId: 用户ID
- $level: 统计级别
返回: 下级人数

5. getEcologyList($userId)

功能: 获取用户的生态列表及地址
参数: $userId - 用户ID
返回: 生态列表数组

6. getCoinType($ecologyId)

功能: 获取生态交互币种
参数: $ecologyId - 生态ID
返回: 币种类型

7. callExternalService($url, $params, $method, $appKey)

功能: 调用外部生态服务
参数:
- $url: 服务地址
- $params: 请求参数
- $method: 请求方法（GET/POST）
- $appKey: 应用密钥
返回: 解密后的响应数据

CryptoService 加密服务类

主要方法

1. __construct($key, $timeout = 300)

功能: 构造函数
参数:
- $key: 加密密钥
- $timeout: 数据有效期（秒，默认300秒）

2. encrypt($data)

功能: 加密数据
参数: $data - 要加密的数据数组
返回: 包含加密数据和元信息的数组
异常: 加密失败时抛出 RuntimeException

3. decrypt($encryptedData)

功能: 解密数据
参数: $encryptedData - 加密数据数组
返回: 解密后的原始数据
异常: 数据过期、签名验证失败或解密失败时抛出异常

4. setKey($key)

功能: 设置加密密钥
参数: $key - 新的加密密钥

5. encryptResponse($response)

功能: 加密响应数据
参数: $response - 响应对象
返回: 包含加密数据的JSON响应

中间件说明

EncryptionMiddleware 加密中间件

功能

自动解密POST请求数据
自动加密成功的JSON响应
验证请求签名和时间戳
缓存生态密钥配置

处理流程

从路由参数获取 ecology_id
从缓存或数据库获取对应的 app_key
设置加密服务的密钥
解密POST请求数据并存入 decrypted 字段
执行后续请求处理
对成功的JSON响应进行加密

错误处理

密钥未配置：返回 RuntimeException
解密失败：返回相应错误信息
签名验证失败：返回401状态码

数据模型

EcologyConfig 生态配置模型

表名: ecology_config

主要字段（基于代码推断）:

id: 主键ID
name: 生态名称
link: 生态链接
address_prefix: 地址前缀
app_key: 应用密钥
coin_type: 交互币种

EcologyUser 生态用户模型

表名: ecology_user

主要字段（基于代码推断）:

id: 主键ID
ecology_id: 生态ID
user_id: 用户ID
user_key: 用户密钥
created_at: 创建时间
updated_at: 更新时间
deleted_at: 删除时间（软删除）

错误码规范

错误码	说明
200	请求成功
400	请求参数错误
401	签名验证失败
403	无权限访问
408	请求超时
500	服务器内部错误

使用注意事项

密钥配置: 确保 ecology_config 表中配置了正确的 app_key
时间同步: 客户端和服务端时间差不能超过5分钟
签名验证: 每个加密请求必须包含正确的签名
数据格式: 所有加密数据都使用Base64编码
缓存机制: 生态密钥会被缓存1小时，提高性能
安全性: 生产环境应定期轮换密钥
日志记录: 建议记录加密失败日志用于排查问题

开发调试

测试加密功能

# 测试加密接口
curl -X GET "http://your-domain/api/ecology/test-encrypt?userId=10002&level=1"

测试解密功能

# 需要先通过加密接口获取加密数据，然后发送到解密接口
curl -X POST "http://your-domain/api/ecology/1/test-decrypt" \
  -H "Content-Type: application/json" \
  -d '{"data":"...","iv":"...","timestamp":...,"sign":"..."}'

完整的业务接口调用示例

# 获取用户信息
curl -X POST "http://your-domain/api/ecology/1/userInfo" \
  -H "Content-Type: application/json" \
  -d '{"data":"...","iv":"...","timestamp":...,"sign":"..."}'

# 获取用户团队关系
curl -X POST "http://your-domain/api/ecology/1/userTeam" \
  -H "Content-Type: application/json" \
  -d '{"data":"...","iv":"...","timestamp":...,"sign":"..."}'

# 获取用户下级统计
curl -X POST "http://your-domain/api/ecology/1/userLevelCount" \
  -H "Content-Type: application/json" \
  -d '{"data":"...","iv":"...","timestamp":...,"sign":"..."}'

文档版本: v1.0 最后更新: 2025-06-14 维护者: Ecology 模块开发团队

Api.md 10 KB Pysyvä linkki Historia Raaka

Ecology 模块 API 文档

概述

基础信息

路由列表

1. 测试接口

1.1 测试加密接口

1.2 测试解密接口

2. 业务接口

2.1 获取用户信息

2.2 获取用户团队关系

2.3 获取用户下级统计

加密机制

加密算法

请求格式

响应格式

加密流程

解密流程

API 接口详情

1. 测试加密接口

2. 测试解密接口

3. 获取用户信息接口

4. 获取用户团队关系接口

5. 获取用户下级统计接口

服务类说明

EcologyService 服务类

主要方法

1. getEcologyLink($userId, $ecologyId)

2. getUserInfo($userKey)

3. getUserTeam($userId)

4. getLevelCount($userId, $level)

5. getEcologyList($userId)

6. getCoinType($ecologyId)

7. callExternalService($url, $params, $method, $appKey)

CryptoService 加密服务类

主要方法

1. __construct($key, $timeout = 300)

2. encrypt($data)

3. decrypt($encryptedData)

4. setKey($key)

5. encryptResponse($response)

中间件说明

EncryptionMiddleware 加密中间件

功能

处理流程

错误处理

数据模型

EcologyConfig 生态配置模型

EcologyUser 生态用户模型

错误码规范

使用注意事项

开发调试

测试加密功能

测试解密功能

完整的业务接口调用示例

Api.md 10 KB

Pysyvä linkki Historia Raaka