vtj/docs/llms/settings.md

VTJ 应用设置 — AI 配置指南

本文档帮助 AI 理解如何通过工具方法配置应用级别的全局设置。 设计器的"应用设置"面板提供 9 个配置项，覆盖 3 大类：全局配置、请求配置、路由守卫。 这些配置最终存储在 project.globals 中，由渲染引擎在初始化时按顺序执行。

---

一、数据流全貌

设计器面板                          项目数据                         渲染引擎
globals/index.vue  ──setGloblas()──▶  project.globals  ──initRuntimeGlobals()──▶  运行时生效
    (UI)                              (GlobalConfig)                              (globals.ts)

关键流程：

1. 通过工具方法设置 → 存入 project.globals（GlobalConfig 类型）
2. 应用启动时 Provider.install() → 调用 initGlobals() → 调用 initRuntimeGlobals()
3. 渲染引擎按固定顺序初始化各项配置

注意： 设计模式（Design Mode）下 initGlobals 不会被调用，仅在预览/运行时生效。

---

二、配置项与工具方法对照表

设计器面板项	配置键名	设置工具	查询工具	值类型
应用全局「CSS」	css	setGlobalCss	getGlobalCss	CSS 字符串
应用状态「Pinia」	store	setGlobalStore	getGlobalStore	JS 函数
权限控制「Access」	access	setGlobalAccess	getGlobalAccess	JS 函数
应用增强「JS」	enhance	⚠️ 暂无工具	⚠️ 暂无工具	JS 函数
请求配置「IRequestOptions」	axios	setGlobalAxios	getGlobalAxios	JS 函数
请求拦截器	request	setGlobalRequestInterceptor	getGlobalRequestInterceptor	JS 函数
响应拦截器	response	setGlobalResponseInterceptor	getGlobalResponseInterceptor	JS 函数
前置守卫「beforeEach」	beforeEach	setGlobalBeforeEach	getGlobalBeforeEach	JS 函数
后置守卫「afterEach」	afterEach	setGlobalAfterEach	getGlobalAfterEach	JS 函数

⚠️ enhance（应用增强 JS） 目前没有对应的工具方法，暂无法通过 AI 工具配置。

---

三、渲染引擎初始化顺序

initRuntimeGlobals() 严格按以下顺序执行，顺序不可更改，配置时需注意依赖关系：

1. CSS（全局样式）         ── adoptedStyleSheets 注入
    │
2. Store（Pinia 状态）     ── 创建 Pinia 实例，注册 $store
    │
3. Axios + 拦截器          ── 先设基础配置，再设请求拦截器，最后设响应拦截器
    │
4. Access（权限控制）      ── 创建 Access 实例，连接 router/request
    │
5. 路由守卫                ── 先 beforeEach，后 afterEach
    │
6. Enhance（应用增强）     ── 最后执行，可访问全部已初始化的 libs 和 app

含义：

• store 中的状态可在 access、路由守卫、拦截器中通过 app.config.globalProperties.$store 访问
• access 实例挂载后，路由守卫可通过 app.config.globalProperties.$access 访问
• enhance 最后执行，可访问所有已初始化的资源（store、access、router 等）

---

四、各配置项详细说明

4.1 应用全局 CSS — css

对应工具： setGlobalCss / getGlobalCss

直接传入 CSS 代码字符串，会在应用启动时注入为全局样式表。

示例：

{
  "action": "setGlobalCss",
  "parameters": [
    "body { margin: 0; padding: 0; font-family: 'Helvetica Neue', sans-serif; }\n.page-container { min-height: 100vh; }"
  ]
}

设计器默认值： 空字符串（不注入额外 CSS）

---

4.2 应用状态 Pinia — store

对应工具： setGlobalStore / getGlobalStore

定义应用的全局 Pinia Store，函数必须返回一个标准 Pinia Store 配置对象。

函数签名： (app) => ({ state, getters, actions })

参数	说明
app	Vue 应用实例，可用于获取全局属性如 app.config.globalProperties

设计器默认模板：

(app) => {
  return {
    state: () => {
      return {
        // 定义状态
      };
    },
    getters: {
      // 计算属性
    },
    actions: {
      // 方法
    }
  };
};

完整示例：

{
  "action": "setGlobalStore",
  "parameters": [
    "(app) => {\n  return {\n    state: () => ({\n      user: null,\n      token: '',\n      permissions: []\n    }),\n    getters: {\n      isLogined: (state) => !!state.token,\n      userName: (state) => state.user?.name || '游客'\n    },\n    actions: {\n      login(data) {\n        this.token = data.token\n        this.user = data.user\n        this.permissions = data.permissions || []\n      },\n      logout() {\n        this.token = ''\n        this.user = null\n        this.permissions = []\n      },\n      hasPermission(code) {\n        return this.permissions.includes(code)\n      }\n    }\n  }\n}"
  ]
}

运行时访问： 组件中通过 __store.xxx 访问：

const user = __store.user;
__store.login({ token: 'xxx', user: { name: '张三' } });

---

4.3 权限控制 Access — access

对应工具： setGlobalAccess / getGlobalAccess

配置应用的权限控制插件，函数返回 AccessOptions 配置对象。

函数签名： (app) => AccessOptions

设计器默认模板：

(app) => {
  return {
    // session: false,
    // authKey: 'Authorization',
    // storageKey: 'ACCESS_STORAGE',
    // auth: '/#/login',
    // whiteList: (to) => true,
    // redirectParam: 'r',
    // unauthorizedCode: 401,
    // unauthorizedMessage: '登录已经失效，请重新登录！',
    // noPermissionMessage: '无权限访问该页面',
    // statusKey: 'code'
  };
};

AccessOptions 配置项说明：

配置项	类型	默认值	说明
session	boolean	false	是否开启 session 存储（关闭浏览器即失效），false 使用 localStorage
authKey	string	Authorization	请求头和 cookie 中 token 的键名
storagePrefix	string	__VTJ_	本地缓存 key 前缀
storageKey	string	ACCESS_STORAGE	本地缓存的键名
auth	string	/#/login	登录页面的 hash 路径
unauthorized	string	-	未授权页面的路由路径（如 /403），默认走 auth 跳转到登录页
isAuth	function	-	自定义判断是否为登录页面的函数
whiteList	function	(to) => false	路由白名单，返回 true 跳过权限校验，接收 to 路由对象
redirectParam	string	r	登录后重定向的参数名
unauthorizedCode	number	401	未登录时后端返回的状态码
unauthorizedMessage	string	登录已失效...	未登录时的提示消息
noPermissionMessage	string	无权限...	无权限时的提示消息
alert	function	-	自定义提示消息弹窗方法，接收 (message, options?) => Promise
privateKey	string	-	RSA 解密私钥，用于解密加密的接口响应数据
appName	string	''	应用编码，权限码前缀，实现多应用权限隔离
statusKey	string	code	响应数据中状态码的字段名

运行时访问： 组件中通过 __access 访问：

// 检查是否已登录
__access.isLogined();

// 检查是否拥有指定权限
__access.can('user:edit');

// 检查是否至少有一个权限
__access.some(['user:edit', 'user:view']);

// 获取当前 token
__access.getToken();

// 获取登录用户数据
__access.getData();

// 登录
__access.login({
  token: 'xxx',
  user: { name: '张三' },
  permissions: ['user:view']
});

// 登出
__access.logout();

---

4.4 应用增强 JS — enhance

⚠️ 尚无对应工具方法。

该配置允许在应用初始化的最后阶段注入自定义增强逻辑，函数接收 app（Vue 应用实例）和 libs（所有注册的第三方库集合）。

设计器默认模板：

(app) => {
  // 在此添加增强代码
};

执行时机： 在所有其他全局配置（CSS、Store、Axios、Access、路由守卫）初始化完成后执行。

---

4.5 请求配置 IRequestOptions — axios

对应工具： setGlobalAxios / getGlobalAxios
UI 标签中也称 getGlobalAxios，设置时使用 setGlobalAxios。

配置 Axios 请求工具的基础选项（baseURL、超时、响应校验等）。

函数签名： (app) => IRequestOptions

设计器默认模板：

(app) => {
  return {
    // baseURL: '/',
    // timeout: 60000,
    // settings: {
    //   type: 'form',
    //   validSuccess: false,
    //   originResponse: true,
    //   loading: true,
    //   failMessage: true,
    //   validate: (res) => {
    //     return res.data?.code === 0 || !!res.data?.success;
    //   }
    // }
  };
};

IRequestOptions 常见配置项：

配置项	类型	说明
baseURL	string	请求的基础 URL 前缀
timeout	number	请求超时时间（毫秒）
settings.type	string	请求数据类型：form（表单）、json（JSON）、data（FormData）
settings.validSuccess	boolean	是否校验响应是否成功
settings.originResponse	boolean	是否返回原始 Axios 响应对象
settings.loading	boolean	请求时是否显示全局 loading
settings.failMessage	boolean	请求失败时是否显示错误提示
settings.validate	function	自定义响应成功校验函数，接收 res 返回 boolean

完整示例：

{
  "action": "setGlobalAxios",
  "parameters": [
    "(app) => {\n  return {\n    baseURL: 'https://api.example.com',\n    timeout: 30000,\n    settings: {\n      type: 'json',\n      validSuccess: true,\n      originResponse: false,\n      loading: true,\n      failMessage: true,\n      validate: (res) => {\n        return res.data?.code === 0\n      }\n    }\n  }\n}"
  ]
}

---

4.6 请求拦截器 — request

对应工具： setGlobalRequestInterceptor / getGlobalRequestInterceptor

在每次请求发送前执行，常用于注入 token、设置请求头等。

函数签名： (config, app) => config

参数	说明
config	Axios 请求配置对象
app	Vue 应用实例

必须返回请求配置对象 config。

设计器默认模板：

(config, app) => {
  return config;
};

典型示例（自动注入 token）：

(config, app) => {
  const access = app.config.globalProperties.$access;
  if (access?.getToken()) {
    config.headers['Authorization'] = `Bearer ${access.getToken()}`;
  }
  return config;
};

---

4.7 响应拦截器 — response

对应工具： setGlobalResponseInterceptor / getGlobalResponseInterceptor

在每次请求收到响应后执行，常用于统一处理响应数据、错误处理等。

函数签名： (res, app) => res

参数	说明
res	Axios 原始响应对象
app	Vue 应用实例

必须返回响应对象 res。

设计器默认模板：

(res, app) => {
  return res;
};

典型示例（统一错误处理）：

(res, app) => {
  if (res.data?.code === 401) {
    const access = app.config.globalProperties.$access;
    if (access) {
      access.logout();
    }
  }
  return res;
};

---

4.8 前置路由守卫 beforeEach — beforeEach

对应工具： setGlobalBeforeEach / getGlobalBeforeEach

在路由跳转前执行，常用于权限校验、登录拦截等。

函数签名： (to, from, next, app) => void

参数	说明
to	即将进入的目标路由对象
from	当前正要离开的路由对象
next	执行跳转的函数（与 vue-router beforeEach 一致）
app	Vue 应用实例

设计器默认模板：

(to, from, next, app) => {
  next();
};

典型示例（登录校验）：

(to, from, next, app) => {
  const access = app.config.globalProperties.$access;
  const isPublic = access?.options?.whiteList?.(to);
  if (!isPublic && !access?.isLogined()) {
    next('/login');
  } else {
    next();
  }
};

---

4.9 后置路由守卫 afterEach — afterEach

对应工具： setGlobalAfterEach / getGlobalAfterEach

在路由跳转完成后执行，常用于页面标题更新、埋点上报等。

函数签名： (to, from, failure, app) => void

参数	说明
to	进入的目标路由对象
from	离开的路由对象
failure	导航失败信息，成功时为 undefined
app	Vue 应用实例

设计器默认模板：

(to, from, failure, app) => {};

典型示例（埋点上报）：

(to, from, failure, app) => {
  if (!failure) {
    // 页面浏览埋点
    console.log('Page view:', to.path);
  }
};

---

五、配置建议与注意事项

5.1 典型配置流程

当 AI 需要配置应用级别功能时，建议按以下顺序调用工具：

1. setGlobalCss        → 设置全局样式
2. setGlobalStore      → 定义全局 Pinia 状态
3. setGlobalAxios      → 配置请求基础选项
4. setGlobalRequestInterceptor  → 设置请求拦截（如注入 token）
5. setGlobalResponseInterceptor → 设置响应拦截（如统一错误处理）
6. setGlobalAccess     → 配置权限控制插件
7. setGlobalBeforeEach → 设置前置路由守卫（登录校验等）
8. setGlobalAfterEach  → 设置后置路由守卫（埋点等）

这个顺序与渲染引擎内部初始化顺序一致，可以保证依赖关系正确。

5.2 重要约定

1. 值类型： css 为普通字符串，其余 7 项（store、access、enhance、axios、request、response、beforeEach、afterEach）均为 JS 函数代码字符串，不是 JSON 对象

2. 工具参数格式： 所有 set 类工具的配置内容均作为单个字符串参数传入（即 parameters 数组的第一个元素），不要在字符串外额外包裹对象

3. enhance 暂无工具： 如需初始化后执行自定义逻辑，目前只能通过设计器面板手动编辑，无对应 AI 工具方法

4. 运行时不直接调用： 工具方法只负责存储配置到项目中，配置的实际生效发生在应用启动时，不影响当前打开的预览窗口（可调用 refresh 刷新查看效果）

5. 设计模式不生效： 设计器内编辑页面时，全局配置不会立即在页面渲染中生效（initGlobals 仅在非设计模式下执行）

6. 函数内可访问全局属性：

   • app.config.globalProperties.$store — Pinia store 实例
   • app.config.globalProperties.$access — 权限控制实例
   • app.config.globalProperties.$router — 路由实例
   • app.config.globalProperties.$provider — Provider 实例

5.3 查询已有配置

在修改配置前，建议先调用对应的 get 工具查看已有内容，避免覆盖：

getGlobalCss      → 查看当前全局 CSS
getGlobalStore    → 查看当前 Pinia store 代码
getGlobalAccess   → 查看当前权限配置
getGlobalAxios    → 查看当前请求基础配置
getGlobalRequestInterceptor  → 查看当前请求拦截器
getGlobalResponseInterceptor → 查看当前响应拦截器
getGlobalBeforeEach → 查看当前前置路由守卫
getGlobalAfterEach  → 查看当前后置路由守卫