预览端接口

CatPull 预览端（catpull-uni）用于渲染项目页面，支持 H5 和小程序多端部署。预览端使用与设计器相同的认证体系，通过 app_id + app_key 获取 JWT 签名后访问设计器内置接口。

认证流程

预览端的所有接口请求都需要先通过 /sign/token 获取 JWT 签名，然后在后续请求的 Header 中携带 app_id 和 sign。

1. POST /sign/token  →  获取 app_id + sign
2. GET /pages/list   →  Header: app_id + sign
3. GET /pages/get    →  Header: app_id + sign

权限规则

身份	凭证	项目访问范围
管理员	app_id + app_key	任意项目
普通租户	app_id + app_key	仅自身项目

管理员判定

管理员由后端环境变量 APP_ADMIN_USER 指定，其 app_id 对应的账号拥有全局项目访问权限。

接口列表

获取认证签名

获取指定项目的 JWT 签名参数，用于后续接口的认证。

请求

POST /sign/token

参数

参数	类型	必填	说明
app_id	string	✅	应用ID
app_key	string	✅	应用密钥
app_uid	string	✅	项目UID

响应

{
  "status": 200,
  "message": "success",
  "data": {
    "app_id": "6001a07e84ab801351143019b1c07049",
    "app_platform": "uniapp",
    "sign": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }
}

错误码

错误信息	说明
缺少参数	app_id、app_key、app_uid 任一缺失
应用不存在	app_id 无效
应用密钥无效	app_key 不匹配
密钥未启用	普通账号密钥被禁用（管理员不受限制）
项目不存在	app_uid 无效
无权访问该项目	普通账号访问非自身项目

---

获取页面列表

获取指定项目下的所有页面列表。

请求

GET /pages/list

Header

Header	类型	必填	说明
app_id	string	✅	应用ID
sign	string	✅	JWT 签名

响应

{
  "status": 200,
  "message": "success",
  "data": {
    "pages": [
      {
        "page_uid": "page_a1b2c3d4",
        "app_uid": "app_mmt2z8rf",
        "page_name": "首页",
        "page_description": "",
        "is_home": 1,
        "page_schema": null,
        "create_time": 1712822400,
        "update_time": 1712822400
      }
    ]
  }
}

---

获取页面详情

获取单个页面的完整数据，包含页面结构（page_schema）和工作流（workflow_schema）。

请求

GET /pages/get?page_uid=xxx

Header

Header	类型	必填	说明
app_id	string	✅	应用ID
sign	string	✅	JWT 签名

参数

参数	类型	必填	说明
page_uid	string	✅	页面UID

响应

{
  "status": 200,
  "message": "success",
  "data": {
    "page": {
      "page_uid": "page_a1b2c3d4",
      "app_uid": "app_mmt2z8rf",
      "page_name": "首页",
      "page_description": "",
      "is_home": 1,
      "page_schema": {
        "page_content": { "children": [], "css": "" }
      },
      "workflow_schema": {
        "workflow_content": { "nodes": [], "edges": [] }
      },
      "create_time": 1712822400,
      "update_time": 1712822400
    }
  }
}

URL 参数说明

预览端通过 URL 参数指定要预览的项目和页面：

URL	说明
?app_uid=app_xxx	预览项目的首页（自动查找 is_home=1 的页面）
?app_uid=app_xxx&page_uid=page_xxx	预览项目的指定页面
无参数	预览 .env 中 VITE_APP_UID 指定的项目