# 使用说明

## 1. 部署方式

本程序现在支持两种部署方式：

### 方式 A：零配置部署（推荐新手）

- 直接把整套源码上传到站点根目录。
- 不需要把站点目录改到 `public`。
- 不需要配置伪静态。
- 上传解压后，直接访问你的域名即可进入安装页。

这种方式下，系统会默认使用 `index.php?r=路由` 形式访问页面和接口。

常用入口示例：

- 登录页：`https://你的域名/`
- 后台首页：`https://你的域名/index.php?r=dashboard`
- 系统设置：`https://你的域名/index.php?r=admin/system`
- 查卡页面：`https://你的域名/index.php?r=query-key`
- API 心跳：`https://你的域名/index.php?r=api/v1/ping`

### 方式 B：美化地址部署（进阶可选）

- 站点目录指向 `public`
- 配置伪静态

这种方式下可以直接使用更短的路径，例如：

- `https://你的域名/login`
- `https://你的域名/dashboard`
- `https://你的域名/api/v1/ping`

如果你只是想让用户“上传解压就能用”，请直接使用方式 A。

## 2. 安装流程

1. 上传整套源码到站点目录。
2. 访问域名根目录，例如 `https://你的域名/`。
3. 在安装页填写数据库信息与管理员账号信息。
4. 先测试数据库连接，再点击安装。
5. 安装完成后，按页面按钮进入后台。

安装完成后，系统会自动生成：

- `config/database.php`
- `storage/install.lock`
- `storage/install.permanent.lock`

如果你确实需要重新安装，需要手动删除以上锁文件和数据库配置文件。

## 3. 默认后台入口

零配置部署下，推荐使用以下入口：

- 登录页：`/`
- 显式登录地址：`/index.php?r=login`
- 后台首页：`/index.php?r=dashboard`

如果你已经启用了美化地址模式，则可以直接访问：

- `/login`
- `/dashboard`

## 4. 常用页面

- 个人设置：`/index.php?r=settings`
- 卡密列表：`/index.php?r=keys`
- 生成卡密：`/index.php?r=keys/generate`
- 用户管理：`/index.php?r=admin/users`
- 数据统计：`/index.php?r=admin/stats`
- 系统设置与更新：`/index.php?r=admin/system`
- 对接示例：`/index.php?r=connect/demo`
- 查卡页面：`/index.php?r=query-key`

## 5. API 对接

零配置部署下，请优先使用带 `index.php?r=` 的接口地址。

### 心跳接口

- `GET /index.php?r=api/v1/ping`

### 登录 / 验证接口

- `POST /index.php?r=api/v1/login`

请求参数：

- `game`：项目标识
- `user_key` 或 `key`：卡密
- `serial`：设备码，可选

### 查询卡密

- `POST /index.php?r=api/v1/key/query`

### 自助解绑

- `POST /index.php?r=api/v1/key/unbind`

### 云端公告

- `GET /index.php?r=api/v1/notices`

如果你已经使用了美化地址模式，可以把以上地址改成：

- `/api/v1/ping`
- `/api/v1/login`
- `/api/v1/key/query`
- `/api/v1/key/unbind`
- `/api/v1/notices`

## 6. 对接示例

### cURL

```bash
curl -X POST "https://你的域名/index.php?r=api/v1/login" \
  -d "game=PUBG" \
  -d "user_key=YOUR_KEY"
```

### PHP

```php
<?php
$url = 'https://你的域名/index.php?r=api/v1/login';
$post = [
    'game' => 'PUBG',
    'user_key' => 'YOUR_KEY',
];

$ch = curl_init();
curl_setopt_array($ch, [
    CURLOPT_URL => $url,
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => http_build_query($post),
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 10,
]);

$resp = curl_exec($ch);
$err = curl_error($ch);
curl_close($ch);

if ($resp === false) {
    exit('请求失败：' . $err);
}

$json = json_decode($resp, true);
if (!is_array($json) || empty($json['status'])) {
    exit('登录失败：' . ($json['message'] ?? '未知错误'));
}

echo '登录成功';
```

## 7. 更新与云端说明

- 前端已支持云端更新检测与在线更新。
- 系统设置页不会直接展示远程授权站域名明文。
- 如果未配置美化地址，也不影响更新功能。

## 8. 常见问题

### 访问 `/login` 打不开

这是正常情况。你当前大概率使用的是零配置部署模式，请改用：

- `https://你的域名/`
- `https://你的域名/index.php?r=login`

### API 地址返回 404

如果你没有配置伪静态，请不要直接调用 `/api/v1/...`，请改用：

- `/index.php?r=api/v1/...`

### 想重新安装

手动删除以下文件后再访问安装页：

- `config/database.php`
- `storage/install.lock`
- `storage/install.permanent.lock`
