# VSCMS 开发文档（接口参考）

> 版本 v1.0 ｜ 协议：HTTP/JSON ｜ 认证：`Authorization: Bearer <JWT>`
> 统一响应：`{"code":0,"msg":"ok","data":{}}`；分页：`{"list":[],"total":0,"page":1,"pageSize":20}`

## 一、客户后台（/adminapi）

### 认证
| 方法 | 路径 | 说明 |
| --- | --- | --- |
| POST | /auth/login | 登录 `{username,password}` → `{token,user}` |
| GET | /auth/me | 当前用户 + 权限 + 菜单 |
| PUT | /auth/password | 修改密码 |

### 站点 / 页面
| 方法 | 路径 | 说明 |
| --- | --- | --- |
| GET/POST | /site | 站点列表 / 新建 |
| GET/PUT/DELETE | /site/:id | 详情 / 更新 / 删除 |
| GET | /page?site_id= | 页面列表 |
| POST | /page | 新建 `{site_id,title,path,template}` |
| POST | /page/:id/blocks | 保存区块编排（自动版本快照） |
| GET | /page/:id/versions | 版本列表；POST /page/:id/rollback/:vid 回滚 |

### 栏目 / 内容 / 留言 / 媒体
| 方法 | 路径 | 说明 |
| --- | --- | --- |
| GET | /column/presets | 12 套栏目预设 |
| GET/POST | /column | 栏目列表 / 新建 |
| GET/POST | /content | 内容列表 / 新建（自定义字段在 `data`） |
| GET | /category?column_id= | 分类；POST /category 新建 |
| GET | /form/data | 留言列表；POST /form/submit 公开提交 |
| GET | /media | 媒体库；POST /media/upload 上传 |
| GET/POST | /media/folder | 文件夹 |

### 源码编辑（Monaco）
| 方法 | 路径 | 说明 |
| --- | --- | --- |
| GET | /code/tree?site_id= | 文件树（自定义/区块/栏目模板） |
| GET | /code/file?site_id=&path= | 读取（优先站点覆盖） |
| POST | /code/save | 保存并生成版本 |
| GET | /code/versions | 版本；POST /code/rollback 回滚；POST /code/delete 恢复内置 |

### AI 建站
| 方法 | 路径 | 说明 |
| --- | --- | --- |
| POST | /ai/site-plan | 一句话建站 `{requirement,site_id?,site_name?}` |
| POST | /ai/site-apply | 应用方案 `{task_id,site_id?}` |
| POST | /ai/column-plan /ai/column-apply | AI 建栏目 |
| POST | /ai/design-parse | 设计图解析（multipart：file, site_id） |
| POST | /ai/design-apply | 应用设计图 |
| GET | /ai/tasks /ai/task/:id | 任务与用量 |

### 发布
| 方法 | 路径 | 说明 |
| --- | --- | --- |
| GET | /publish?site_id= | 发布记录 + 当前版本 + 域名状态 |
| POST | /publish | 执行发布 |
| POST | /publish/rollback | 回滚 `{site_id,publish_id}` |
| POST | /publish/bind /publish/unbind | 绑定/解绑域名（自动 SSL） |
| GET | /preview/page/:id?token= | 登录态整页预览 |

## 二、官方总控（/official/api）

| 方法 | 路径 | 鉴权 | 说明 |
| --- | --- | --- | --- |
| POST | /api/activate | 授权码+域名 | 在线激活 → `{token,license,gateway,config}` |
| POST | /api/heartbeat | Bearer token + X-License-Domain | 心跳、上报用量、下发模型配置 |
| POST | /api/ai/v1/chat/completions | 同上 | AI 网关（OpenAI 兼容，Key 不出官方） |

## 三、环境变量（server/.env）

```ini
DB_TYPE = mysql
DB_HOST = 127.0.0.1
DB_NAME = www_vscms_com
DB_USER = www_vscms_com
DB_PASS = ******
DB_PREFIX = cms_
JWT_SECRET = <64位hex>
DATA_KEY   = <64位hex>
# 可选：AI 直连模式
AI_BASE_URL = https://api.deepseek.com
AI_MODEL    = deepseek-flash
AI_API_KEY  = sk-******
```

## 四、运维命令

```bash
php think cms:migrate        # 数据库迁移
php think cms:seed           # 初始化数据（含区块库同步）
php think cms:heartbeat      # 官方心跳（建议 cron 每 6 小时）
php think cms:demo --reset   # 重建演示数据
php deploy/license-tool.php issue ...   # 离线授权签发（服务商侧）
```