266 lines
5.0 KiB
Markdown
266 lines
5.0 KiB
Markdown
# 进销存数据开放平台 - 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. 安装依赖
|
||
```bash
|
||
composer install
|
||
```
|
||
|
||
### 3. 配置环境变量
|
||
编辑 `.env` 文件，配置数据库连接等信息：
|
||
|
||
```ini
|
||
[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. 创建数据库表
|
||
```bash
|
||
mysql -u root -p jc_open_platform < database.sql
|
||
```
|
||
|
||
### 5. 启动服务
|
||
```bash
|
||
php think run
|
||
```
|
||
|
||
服务将在 `http://localhost:8000` 启动。
|
||
|
||
## API文档
|
||
|
||
### 系统接口
|
||
|
||
#### 健康检查
|
||
```
|
||
GET /health
|
||
```
|
||
|
||
响应：
|
||
```json
|
||
{
|
||
"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
|
||
```
|
||
|
||
响应：
|
||
```json
|
||
{
|
||
"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
|
||
```
|
||
|
||
请求体：
|
||
```json
|
||
{
|
||
"username": "admin",
|
||
"password": "admin123"
|
||
}
|
||
```
|
||
|
||
响应：
|
||
```json
|
||
{
|
||
"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 + '×tamp=' + timestamp
|
||
```
|
||
|
||
### 2. 计算签名
|
||
```
|
||
signature = HMAC-SHA256(stringToSign, apiSecret)
|
||
```
|
||
|
||
### PHP示例
|
||
```php
|
||
$params = ['start_date' => '2026-01-01', 'page' => '1'];
|
||
ksort($params);
|
||
$queryString = http_build_query($params);
|
||
$stringToSign = $queryString . '×tamp=' . 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 |