# 星澜云 API - 快速对接文档

> 把这个项目改名为「星澜云」并配套做了 **统一 API 入口** + **GUI 后台**,对接软件只需记一个地址。

## 🚀 快速对接

**统一入口**:`/api/index.php?type=xxx&do=xxx` (GET 或 POST)

> 旧接口(`reg.php`/`login.php`/`ft.php` 等)继续可用,新接口只是更规范。

## 📦 三个模块

### 1. 用户模块 `type=user`

| do | 参数 | 说明 |
|---|---|---|
| `register` | `user pass name touxiang` | 注册 |
| `login` | `user pass` | 登录,返回 token + info |
| `info` | `user` | 查用户完整信息 |
| `update` | `user field value` | 通用改字段(无验证,仅供管理员) |
| **`update_profile`** | `user + name/qianming/chenghao/touxiang/background` | **客户端改资料(带安全过滤)** ⭐ |
| **`upload_avatar`** | `user + image=base64` | **上传头像(返回 URL)** ⭐ |
| `addmoney` | `user money` | 加减金币(money 可负) |
| `addjingyan` | `user jingyan` | 加减经验 |
| `fh` | `user cz`(Title=封/Unsealing=解) | 封号/解封 |
| `qd` | `user` | 签到 |
| `dengji` | `user` | 升级(自动扣经验) |
| `guanzhu` | `user id` | 关注/取关 |
| `yaoqing` | `user yaoqing` | 邀请 |

#### 用户自定义资料(对接重点) ⭐

**两种方式任选其一:**

**方式 1: 客户端传图片 URL(最简单)**
```http
POST /api/index.php?type=user&do=update_profile
user=test001
touxiang=https://example.com/avatar.jpg
name=我的昵称
qianming=我的个性签名
```
**返回:**
```json
{"code":0,"msg":"资料已更新","data":{"touxiang":"https://...","name":"我的昵称","qianming":"..."}}
```

**方式 2: 上传本地图片(base64)**
```http
POST /api/index.php?type=user&do=upload_avatar
user=test001
image=data:image/png;base64,iVBORw0KGgo...
```
**返回:**
```json
{"code":0,"msg":"头像已上传","data":{"url":"res/avatars/test001_a3b8f2c1.png","size":12345}}
```

**字段白名单 + 长度限制:**
| 字段 | 最大长度 | 说明 |
|---|---|---|
| `name` | 30 字 | 昵称(自动过滤"admin""系统"等禁词) |
| `qianming` | 100 字 | 个性签名 |
| `chenghao` | 20 字 | 称号 |
| `touxiang` | 500 字 | 头像 URL(必须 http/https 或 base64) |
| `background` | 500 字 | 主页背景 URL |

**安全限制:**
- 图片最大 2MB
- 仅支持 png/jpg/jpeg/gif/webp
- 必须是真实图片(用 `getimagesizefromstring` 校验,防 PHP 木马上传)
- 禁词过滤:普通用户的 name 自动替换"admin""系统"等
- URL 协议过滤:禁止 `javascript:` `vbscript:` `file:` 等危险协议

**Android 端对接示例(Kotlin):**
```kotlin
// 上传头像
val bitmap = ... // 用户选择的图片
val baos = ByteArrayOutputStream()
bitmap.compress(Bitmap.CompressFormat.PNG, 90, baos)
val b64 = "data:image/png;base64," + Base64.encodeToString(baos.toByteArray(), Base64.NO_WRAP)

val params = mapOf(
    "user" to currentUser,
    "image" to b64
)
val result = api.post("type=user&do=upload_avatar", params)
// result.data.url 就是头像 URL
```

**示例:**
```
POST /api/index.php?type=user&do=login
user=test&pass=123456
→ {"code":0,"msg":"登录成功","data":{"user":"test","token":"xxx","info":{...}}}
```

### 2. 帖子/应用模块 `type=post`

| do | 参数 | 说明 |
|---|---|---|
| `ft` | `user id title content bankuai jietu name shenfen chenghao touxiang biaoqian renzheng` | 发帖(进审核) |
| `appfb` | `user id title content bankuai jietu url baoname name renzheng biaoqian` | 发应用(进审核) |
| `list` | `bankuai page` | 板块帖子列表(按时间倒序,每页20) |
| `read` | `bankuai id` | 读单个帖子详情 |
| `pending_list` | `type`(tiezi/app) | 待审核列表 |
| `shenhe_yes` | `bankuai id user` | 审核通过(自动搬到正式板块+用户金币+10) |
| `shenhe_no` | `bankuai id reason` | 审核拒绝 |
| `delete` | `id bankuai user` | 删帖(需管理员) |
| `ftqx` | `on`(true/false) | 全站开关:禁止/允许发帖 |
| `appqx` | `on`(true/false) | 全站开关:禁止/允许发应用 |
| `gg` | `gg` | 写公告(无 gg 参数时为读) |
| `dianzan` | `bankuai id` | 点赞 +1 |
| `liulan` | `bankuai id` | 浏览量 +1 |
| `pl_add` | `bankuai id zh nr dcim` | 发评论 |
| `pl_list` | `bankuai id` | 读评论列表 |

### 3. 统计模块 `type=stats`

| do | 说明 |
|---|---|
| `total` | 全站统计(用户数/帖子数/启动量/在线/今日活跃) |
| `bankuai` | 板块列表 + 各板块帖子数 |
| `online` | 在线用户列表 |
| `heartbeat` | 客户端心跳(原 qd.php)+ 上报启动量/今日活跃 |

## 🖥️ GUI 后台

浏览器打开:`/admin.php`

**默认登录密码**:`admin123` ← **第一次登录后请立即修改!**

**功能模块:**
- 📊 仪表盘(实时统计)
- 👥 用户管理(列表/编辑/封禁/重置密码)
- 📝 帖子审核(待审核列表/通过/拒绝)
- 📦 应用审核
- 📢 公告管理
- ⚙️ 系统设置(发帖开关/应用开关/网站信息/改密码)
- 📈 数据总览(用户/帖子/启动量)

## ⚠️ 兼容性

- ✅ 旧 `reg.php`/`login.php`/`ft.php` 等接口**完全保留**,老客户端可以继续用
- ✅ 旧 `shenhe.php` 帖子审核后台**继续保留**
- ✅ 旧 `usergl.php` 用户管理后台**继续保留**
- ✅ 新增了 `/api/index.php` 统一入口(推荐对接用)
- ✅ 新增了 `/admin.php` 全新 GUI 后台

## 🔧 第一次部署

1. 整个 `服务器/` 目录放到 PHP 环境(Apache/Nginx/PHP Built-in/KSWEB)
2. 确保 `user/`、`res/`、`pending/`、`appshen/` 目录可写(权限 755)
3. 浏览器打开 `index.php` 看首页
4. 打开 `admin.php`,默认密码 `admin123` 进入后台
5. 在「系统设置」里改默认密码、改网站名称/公告

## 📝 注意事项

- 旧代码 `reg.php` 里的 `if(1==2){ 禁止注册 }` 已通过 `api/user.php` 的 register 绕开,新接口可正常注册
- 旧 `reg.php` 文件本身**未删除**,如要彻底关闭旧注册可自行删掉该文件
- 所有数据仍然存为 TXT 文件,**不要把整个 user/ 目录清空**,否则所有用户数据丢失