docs/thinkphp/README.md

进销存数据开放平台 - ThinkPHP 6.1.4

为上下游合作伙伴提供安全的出入库数据查询API服务。

功能特性

对外API (/api/v1/*)

• 销售数据接口：GET /api/v1/chuku
• 入库数据接口：GET /api/v1/ruku
• 支持分页、日期范围查询
• 需要签名验证：X-API-Key、X-Timestamp、X-Sign

后台管理 (/api/admin/*)

• 认证管理：管理员登录、JWT验证
• 客户管理：创建/更新/启用/禁用客户
• API密钥管理：生成API Key和Secret
• 权限管理：配置接口访问权限、数据隔离规则
• 日志管理：查看API调用记录
• 仪表盘：统计数据、调用趋势

安全机制

• 签名验证（HMAC-SHA256）
• 时间戳防重放攻击
• 限流保护（按分钟/按天）
• 数据隔离（根据客户类型自动过滤）
• 账号状态管理

安装步骤

1. 环境要求

• PHP >= 7.2.5
• MySQL >= 5.7
• SQL Server 2008 R2+ (业务数据库)
• Redis (用于限流)
• Composer

2. 安装依赖

composer install

3. 配置环境变量

编辑 .env 文件，配置数据库连接等信息：

[DATABASE]
TYPE = mysql
HOSTNAME = 127.0.0.1
DATABASE = jc_open_platform
USERNAME = root
PASSWORD = root
HOSTPORT = 3306
CHARSET = utf8

[MSSQL]
HOSTNAME = 192.168.1.100
DATABASE = 进销存数据库
USERNAME = readonly_user
PASSWORD = your_password_here
HOSTPORT = 1433

[JWT]
SECRET_KEY = change-this-to-a-random-32-char-string!
ALGORITHM = HS256
EXPIRE_HOURS = 24

[RATE_LIMIT]
DEFAULT_PER_MINUTE = 60
DEFAULT_PER_DAY = 5000
MAX_PAGE_SIZE = 500

[SIGNATURE]
EXPIRE_SECONDS = 604800

4. 创建数据库表

mysql -u root -p jc_open_platform < database.sql

5. 启动服务

php think run

服务将在 http://localhost:8000 启动。

API文档

系统接口

健康检查

GET /health

响应：

{
  "status": "ok",
  "sql_server": "connected"
}

对外API接口

销售数据查询

GET /api/v1/chuku?start_date=2026-01-01&end_date=2026-12-31&page=1&limit=50

请求头：

X-API-Key: ak_xxxxxxxxxxxxxxxxxxxx
X-Timestamp: 1234567890
X-Sign: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

响应：

{
  "code": 200,
  "msg": "success",
  "total": 100,
  "data": [...]
}

入库数据查询

GET /api/v1/ruku?start_date=2026-01-01&end_date=2026-12-31&page=1&limit=50

请求头同上。

后台管理接口

管理员登录

POST /api/admin/auth/login

请求体：

{
  "username": "admin",
  "password": "admin123"
}

响应：

{
  "code": 200,
  "msg": "登录成功",
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "username": "admin"
  }
}

客户管理

GET /api/admin/clients
POST /api/admin/clients
PUT /api/admin/clients/{id}
PATCH /api/admin/clients/{id}/toggle

API密钥管理

POST /api/admin/clients/{id}/api-keys
GET /api/admin/clients/{id}/api-keys
DELETE /api/admin/api-keys/{keyId}

权限管理

GET /api/admin/permissions/{id}
PUT /api/admin/permissions/{id}

日志管理

GET /api/admin/logs
GET /api/admin/logs/{id}
GET /api/admin/logs/stats

仪表盘

GET /api/admin/dashboard/stats
GET /api/admin/dashboard/trend

签名算法

1. 构建待签名字符串

queryString = 按键名排序后的查询字符串
stringToSign = queryString + '&timestamp=' + timestamp

2. 计算签名

signature = HMAC-SHA256(stringToSign, apiSecret)

PHP示例

$params = ['start_date' => '2026-01-01', 'page' => '1'];
ksort($params);
$queryString = http_build_query($params);
$stringToSign = $queryString . '&timestamp=' . time();
$signature = hash_hmac('sha256', $stringToSign, $apiSecret);

数据隔离策略

1. 全量数据权限

• allow_full_data = 1
• 不加任何过滤条件

2. 按客户名称自动过滤

• data_mode = 'filter'
• 销售接口：过滤 销方全称 = 客户名称
• 入库接口：过滤 供方全称 = 客户名称

3. 自定义过滤规则

• data_mode = 'custom'
• 手动配置 filter_field 和 filter_values
• 支持多值 IN 查询

默认账户

• 管理员：admin / admin123

目录结构

thinkphp/
├── app/
│   ├── controller/
│   │   ├── api/
│   │   │   ├── v1/          # 对外API控制器
│   │   │   └── admin/       # 后台管理控制器
│   ├── middleware/          # 中间件
│   ├── model/              # 数据模型
│   └── service/            # 服务层
├── config/                 # 配置文件
├── route/                  # 路由配置
├── database.sql           # 数据库表结构
└── .env                   # 环境变量配置

注意事项

1. 生产环境请修改JWT密钥和数据库密码
2. SQL Server连接失败时会自动返回模拟数据
3. 限流功能需要Redis支持
4. API Secret仅在生成时可见一次，请妥善保存

许可证

Apache-2.0