SQLBot/docs/agents/frontend.md

前端 Agent 说明

技术与运行

• 技术栈：Vue 3、TypeScript strict mode、Vite、Pinia、Vue Router、Element Plus / element-plus-secondary、Less。
• 路径别名 @/ 指向 frontend/src/。
• 构建目标是 Chrome 81，并启用 Vite legacy 插件；不要只按最新浏览器能力选择 API。
• 常用命令：

cd frontend
npm run dev
npm run build

dev 和 build 都会先运行 vue-tsc -b。依赖变更只手动修改 package.json；package-lock.json 由 npm 命令自动生成且不入库，不要手工编辑或强制加入提交，也不要提交私有 registry 配置。

代码组织

内容	位置
后端接口封装	src/api/<domain>.ts
仅单个业务域使用的类型和模型	跟随对应 src/api/<domain>.ts
跨页面/跨模块共享实体与配置	src/entity/
Pinia 状态	src/stores/<domain>.ts
路由	src/router/index.ts、dynamic.ts、watch.ts
页面级视图	src/views/<domain>/
业务域私有子组件	对应 src/views/<domain>/ 子目录
跨业务复用组件	src/components/<component>/
工具函数	src/utils/
用户可见文案	src/i18n/ 五种语言 JSON

组件目录常使用 index.ts 加 src/ 的形式。新增复用组件时优先参考相邻组件结构；仅单个页面使用的组件不要提前提升到全局 components/。

API 调用

• 不要在视图组件中直接使用 axios；统一通过 @/utils/request.ts 的 request 实例。
• 新接口放入对应 src/api/<domain>.ts，导出类似 xxxApi 的对象，并复用既有命名风格。
• 普通请求使用 request.get/post/put/delete/patch；SSE 使用 request.fetchStream 并传入 AbortController。
• 不要手工添加认证 token、助手 token、证书、语言或 xpack 静态资源头。普通请求的头由 request interceptor 统一处理；SSE 走 request.fetchStream（原生 fetch，不经过 axios interceptor），头部在 fetchStream 内单独拼装（当前不含 Accept-Language），新增请求头时两条路径都要核对。
• 下载类 blob 请求沿用：

request.get('/path', {
  responseType: 'blob',
  requestOptions: { customError: true },
})

• 后端统一响应中 code === 0 时 interceptor 会返回 data；调用方不要重复解包。
• 外部请求失败需要自定义处理时使用 customError 或 silent，不要绕开统一请求封装。

类型

• 新增代码优先使用具体 interface/type 或从 API 模块导出的模型；不要扩大 any 的使用范围。
• 后端返回结构复杂且已有转换函数时，参考 src/api/chat.ts 的模型类和 toXxx 转换函数模式。
• 共享类型放 src/entity/，业务专属类型跟随业务模块，避免相同 DTO 在多个视图中重复声明。
• 修改类型后必须运行 npm run build，让 vue-tsc 检查模板和引用。

状态管理

• 新 store 放 src/stores/<domain>.ts，使用 Pinia options API 风格：state、getters、actions。
• 为 state 定义 interface；getter 命名沿用 getXxx，action 命名表达业务行为。
• 需要在 setup 外使用的 store，参考现有模块通过 stores/index.ts 的 store 实例导出包装函数。
• 用户、语言、工作空间、助手上下文等状态已有 store；不要在组件里复制派生状态或直接改缓存键。

路由与权限

• 静态路由主要在 src/router/index.ts；由许可证或管理员能力控制的动态路由在 dynamic.ts 与 xpack 的 LicenseGenerator.generateRouters 中处理。
• 修改 watch.ts 时必须核对：
  • 普通登录和管理员登录白名单；
  • /assistant、/embeddedPage、/embeddedCommon、/401 助手白名单；
  • userStore.isAdmin 与 isSpaceAdmin 的路由差异；
  • xpack 静态脚本加载失败路径：LicenseGenerator 是无类型声明的 window 全局，登录/改密加密（sqlbotEncrypt）和动态路由注册都硬依赖它，脚本加载失败只提示并中断导航，没有降级。
• 新路由必须配置名称、标题 i18n 和正确父布局；不要绕过已有访问控制。

视图、组件与样式

• 页面组件使用 Vue 3 组合式 API；新组件优先使用 <script setup lang="ts">。
• Element Plus / element-plus-secondary 组件由插件自动导入；除非相邻代码已有显式导入，否则不要添加不必要的组件导入。
• 样式优先使用 scoped Less，并复用邻近页面的布局类、间距类和 flex-gap-fallback 模式。
• 只在有全局设计理由时修改 src/style.less 或跨页面公共样式；不要用行内样式解决可复用布局问题。
• 图表逻辑优先复用 src/views/chat/component/ 和 dashboard 现有封装，不要直接散落 G2/S2 配置。

国际化与安全

• 用户可见文案必须使用 vue-i18n，并同步：
  • en.json
  • zh-CN.json
  • zh-TW.json
  • ko-KR.json
  • th-TH.json
• 新增语言时按 docs/agents/i18n.md 的完整链路检查，不要只添加 JSON 或漏掉文档更新。
• 不要在组件中硬编码新文案；枚举和 supplier 配置可保留 i18n key。
• 渲染模型输出或第三方内容时走既有 markdown/XSS 工具与安全指令；不要新增未净化的 v-html。
• 不要削弱助手 postMessage 证书流程、请求头、token 存储和嵌入白名单逻辑。

验证

cd frontend
npm run build

只检查改动文件时可运行：

cd frontend
npx eslint <changed-file...> --fix

不要默认执行 npm run lint，它会修复整个前端，容易产生无关变更。当前没有独立前端单测框架；跨前端结构或安全约定由 backend/tests/ 中的守卫测试保护，必要时新增或更新对应守卫。