联犀开发者文档

平台前端开发

约 1333 字大约 4 分钟

2026-10-16

本页说明修改平台的控制台、IoT 管理端和公共前端包。开发自己的 Web/mobile 应用时使用应用业务开发。

目录归属

内容位置规则
单一平台应用页面apps/web/apps/<应用>/页面、路由及专属组合组件归本应用
自有共享业务能力apps/web/packages/saas/ 等有实际复用需求再抽取
平台 API 客户端apps/web/packages/api/从 OpenAPI 生成，不手写接口模型
Vben 上游基础设施@core、effects保持兼容，项目业务不继续下沉

先读 apps/AGENTS.md 和 apps/web/docs/前端当前生效规则.md，确认当前使用的组件和权限模式。新增管理页使用项目现行 shadcn 组件及语义颜色，不从历史页面复制整套过时 UI。

增加一个页面

  1. 在所属应用的 views 中实现业务页面，加载、空数据、错误和无权状态均有反馈。
  2. 在该应用路由模块注册页面，组件懒加载；路由扫描目录不放测试或辅助脚本。
  3. 配置匹配的应用菜单、角色和动作权限，核对当前宿主是前端菜单还是后端菜单模式。
  4. 用生成的 @vben/api 客户端发请求，复用统一请求器和认证上下文。
  5. 修改成功后刷新受影响的列表、统计、树及当前详情；切换项目时丢弃旧响应。

隐藏按钮或菜单只能改善交互，真实权限仍由服务端执行。普通成员直接输入 URL、打开详情链接和构造 API 请求时都要验证。

接口与共享组件

后端合同变更后，按接口合同维护生成前端客户端。大整数 ID 使用字符串，核对空值与时间单位，不通过原始 fetch 绕开已认证接口的统一请求链路。

共享功能提供窄入口，避免把图表、地图、大屏、富文本等重依赖带入 bootstrap 和布局启动链路。业务页路由或组件按需加载，不使用一个宽泛 vendor 分组吸入全部依赖。

生成与引入平台接口

后端修改合同后先运行对应服务 build.sh，确认 backend/.swagger/ 的聚合定义已按仓库流程更新，再在前端生成指定模块：

cd apps/web
pnpm --filter @vben/api codegen --model core-api

模块名以实际 Swagger 文件去掉 .json 为准。@vben/api 导出 CoreApi、ThingsApi 等命名空间，客户端使用宿主已配置的统一 requestClient。下面示例调用当前字典明细接口：

// 本文件通过平台生成客户端加载启用的字典选项。
import { CoreApi } from '@vben/api';

/** 读取指定字典的启用选项，复用宿主认证与统一错误处理。 */
export async function loadOptions(dictCode: string) {
  return CoreApi.postApiV1SystemDictDetailGetList({ dictCode, status: 1 });
}

响应由统一请求器解包，按生成函数的返回类型使用，不凭经验再取一层 data.data。需要组合多个请求时在页面专属 API/composable 层编排，不能修改生成文件实现业务。

大整数 ID 保留字符串，空值与时间字段以合同为准。接口返回空列表时呈现空状态，认证失败交给统一链路；业务错误不能全部静默转成空数组。

路由与菜单示例

在所属应用 src/router/routes/modules/ 注册路由，组件实际创建在 views 下。示意文件：

// 本文件注册演示业务路由，权限和菜单需按宿主配置同步。
import type { RouteRecordRaw } from 'vue-router';

/** 演示业务页面，组件按需加载。 */
const routes: RouteRecordRaw[] = [
  {
    name: 'DemoInfo',
    path: '/demo/info',
    component: () => import('#/views/demo/info/index.vue'),
    meta: { title: '业务示例' },
  },
];
export default routes;

路由、应用菜单和角色授权分别配置。详情页隐藏菜单时需指定对应列表高亮规则；返回、刷新直达、无权访问都要验证。不要从旧 qiankun 或 Ant 页面教程推断当前 Vben/shadcn 宿主行为。

表单、字典与项目切换

  • 表单字段定义对齐生成模型，创建/更新的必填与可清空语义分别处理。
  • 下拉字典复用共享能力，扩展字段见字典专题。
  • 项目切换后使旧请求失效并重载范围数据，详情、树、统计与实时订阅一并核对。
  • WebSocket 使用共享连接管理，订阅成功后才显示实时状态；取消和重连见WebSocket。

本地运行与验证

从主仓根目录进入前端 workspace：

cd apps/web
pnpm install --frozen-lockfile
BACKEND_URL=http://127.0.0.1:7850 pnpm dev:iot
# 仅构建受影响的应用。
pnpm run build --filter=iot
# 示例：运行已存在的相关测试。
pnpm exec vitest run packages/saas/src/store/auth-scope.test.ts

示例中的地址应与本机后端一致。菜单/路由、认证及跨项目变化选择对应浏览器场景；仅文案或局部样式修改按风险检查，不机械增加整站 E2E。

触及首屏链路或分包规则时，使用项目现有首屏检查命令验证实际入口依赖。提交包含生成客户端和锁文件的必要变化，不能顺手升级无关依赖。

更新日志

2026/10/16 19:46
查看所有更新日志
  • b3b4d-docs(平台开发): 恢复有效专题并更新当前实现示例于
  • 1a4a7-docs(开发指南): 重建平台与应用开发路线于