QXJ 项目文档

简体中文

English
日本語

简体中文

English
日本語

主题

管理前端 qxj-frontend-admin ​

仓库定位 ​

QXJ 管理后台前端，基于开源模板 Art Design Pro 二开（包名沿用模板 art-design-pro），是 QXJ 国密认证平台的管理端 Web，与后端 qxj-backend-admin（端口 4607）配套，同时提供 PC 与移动端两套 UI （移动端路由 /m/*，断点 768px）。当前分支 feature/admin-full-crud-mobile-20261004。

前端整体架构（模块划分、状态流）见站内 前端架构 页； 接口契约见 API 文档。

技术栈明细 ​

类别依赖（版本）
框架Vue 3.5（^3.5.21）+ TypeScript ~5.6.3 + Vite ^7.1.5
UIElement Plus ^2.11.2（@element-plus/icons-vue 2.3）+ Tailwind CSS ^4.1.14（@tailwindcss/vite）
图表ECharts ^6.0.0
状态Pinia ^3.0.3 + pinia-plugin-persistedstate ^4.3.0
路由 / 国际化vue-router ^4.5.1、vue-i18n ^9.14.0
HTTPaxios ^1.12.2
工具库@vueuse/core ^13.9、@iconify/vue ^5、crypto-js ^4.2、xlsx ^0.18.5、file-saver、qrcode.vue、highlight.js、mitt、ohash、nprogress
业务组件@wangeditor/editor 5.1、xgplayer ^3.0.20、vue-draggable-plus
QXJ SDKqxj-frontend-sdk: file:./vendor/qxj-frontend-sdk-0.2.3.tgz（本地 tarball）
构建 / 质量vue-tsc ~2.1.6、terser、javascript-obfuscator、unplugin-auto-import、unplugin-vue-components、vite-plugin-compression、rollup-plugin-visualizer、ESLint 9 / Prettier 3 / Stylelint 16 / Husky / lint-staged / cz-git

环境要求：Node ≥ 20.19、pnpm ≥ 8.8（包管理器必须用 pnpm）。

功能页面清单（src/views） ​

分组页面
auth/login（滑块 + 阿里云验证码）、register、forget-password
qxj/（PC 业务页）home（通用工作台）、dashboard（安全概览）、user（编辑/密码/角色三弹窗）、role、role-auth（三关联表授权）、device、device-type、device-key、geofence、time-rule、security-log（详情抽屉）、server-key、token
mobile/（移动 UI，路由 /m/*）login、register、reset-password、auxiliary-register、layout、home、profile、device（manage/info/verify）、user（manage/info）、role/manage、access-control、location/manage、time/manage、security-log、server-key、key/manage、token/manage
模板自带（收纳进「模板参考」）dashboard（analysis/console/ecommerce）、examples、article、system/menu、safeguard、change/log、install、exception（403/404/500/wrong-device）、result
  • 业务页统一「ArtSearchBar 搜索栏 + ArtTable 表格 + 弹窗」模式；
  • 菜单六组：工作台 /overview/dashboard、系统管理（users/roles）、设备管理 （list/public-keys）、访问策略（geofence/time-rule/role-auth）、安全审计 （security-log）、模板参考 /reference/...；
  • 登录页（PC + 移动）均支持加密帧登录与 JSON 两种认证模式。

命令表 ​

命令用途
pnpm install安装依赖（失败时 pnpm install --ignore-scripts）
pnpm dev开发（vite --open，端口 5173）
pnpm build独立构建：vue-tsc --noEmit && vite build，产物进本仓 dist/
pnpm build:backend一体化构建：vue-tsc --noEmit && vite build --outDir ../qxj-backend-admin/frontend_dist --emptyOutDir，产物直接写入后端目录，由 Django/Gunicorn 同源托管
pnpm servevite preview 预览构建产物
pnpm clean:dev精简脚本：移除模板演示数据，得到可开发的基础项目
pnpm lint / pnpm fixESLint 检查 / 自动修复
pnpm lint:prettier / pnpm lint:stylelintPrettier / Stylelint 格式化
pnpm commitgit-cz 交互式提交

build 与 build:backend 的区别仅在输出目录：前者独立部署（需自行托管静态资源 并解决跨域），后者配合后端 frontend_dist/ 实现前后端同端口一体化部署，生产 API 走同源 /api/v3/，无需修改主机 IP。

/api/v3 代理配置 ​

  • .env.development：VITE_API_PROXY_URL=http://127.0.0.1:4607， VITE_API_MOCK_URL 指向 Apifox mock；
  • vite.config.ts 开发双代理（顺序关键）：
    • /api/v3 → VITE_API_PROXY_URL（真实 DRF 后端，必须排在 /api 前面）；
    • /api → Apifox mock（仅供「模板参考」演示页）；
  • 生产环境不走代理：一体化部署后前端与 API 同源，请求直接发 /api/v3/。

HTTP 层（src/utils/http/index.ts）按 URL 是否含 /api/v3/ 双分支：

  • v3 请求按 DRF 标准：HTTP 2xx 透传完整 body、分页识别 results/count （page/page_size）、错误取 detail / message / 字段数组；
  • 非 v3 走模板 mock 的 {code,msg,data} 结构；
  • 支持 patch、POST/PUT/PATCH 自动包参、blob（CSV 导出）直接返回 res.data。

SDK 集成（JSBridge 已迁移到统一 SDK） ​

  • 依赖："qxj-frontend-sdk": "file:./vendor/qxj-frontend-sdk-0.2.3.tgz"；
  • 引用 5 处：PC/mobile login 页、utils/http（getAccess/refresh）、路由守卫 （可用性检测）、user store（logout）；
  • JSBridge 模式下登录消费 SDK 调 window.jsbridgeHandle，token 由客户端持久化与 刷新；每次请求前 await jsBridgeGetAccess() 注入 Bearer，401 时 jsBridgeRefresh 重试一次；
  • 双认证模式：
模式链路
JSON 明文登录前后端 ALLOW_JSON_LOGIN 开关同时放开；DEBUG 下后端 WEB_LOGIN_SMS_BYPASS 免短信，前端固定传 verification_code:''、device_id:''
Pad JSBridge 加密登录SM4-GCM 加密帧走 POST /api/v3/user/login/，token 由 SDK 持久化与刷新
  • src/config/qxj.ts 只放业务开关（不含桥接实现）：HOME_LINKS 工作台快捷入口、 ENABLE_MOBILE_UI / ENABLE_PC_UI、LOGIN_ROUTE_NAME 自适应、USE_JSBRIDGE、 ALLOW_JSON_LOGIN、REQUIRE_DEDICATED_DEVICE（整站锁定 Pad，其他浏览器进 wrong-device）、ENABLE_INSTALL_PAGE；MOBILE_BREAKPOINT = 768。

API 层（src/api） ​

  • auth.ts：POST /api/v3/user/login/、GET /api/v3/users/me/、 POST /api/v3/user/logout/、POST /api/v3/token/refresh/、 POST /api/v3/sms/send_code/、PATCH /api/v3/users/me/；
  • qxj/：users / roles / associations（user_roles、role_geofences、 role_time_rules）/ devices / geofences / time-rules / security-logs / server-keys，BASE /api/v3/admin/；
  • mobile/：9 个模块的薄包装（聚合入口 @/api/mobile），复用 qxj/ 与 auth.ts；
  • 类型契约 src/types/api/qxj.d.ts（命名空间 Api.Qxj.*）：字段 snake_case 与后端 序列化器对齐，枚举一律用后端返回的 *_display 展示，前端不硬编码中文映射。

状态与路由 ​

  • Pinia stores：user（loginMode: jsbridge/json，localStorage 持久化）、menu、 setting、table、worktab；
  • 路由：静态 + 动态菜单（core 下 MenuProcessor / RouteRegistry / IframeRouteManager），守卫按 is_superuser / role_type 映射角色权限 （is_superuser 或 role_type=0 → ['R_SUPER','R_ADMIN']，1 → R_USER， 其余 R_GUEST）。

目录结构 ​

qxj-frontend-admin/
├── src/
│   ├── api/              # auth.ts + qxj/（v3 接口）+ mobile/（移动端薄包装）
│   ├── assets/           # 静态资源（图标、样式、图片）
│   ├── components/       # 业务与模板组件
│   ├── config/           # qxj.ts（QXJ 业务开关）等全局配置
│   ├── directives/       # 自定义指令
│   ├── enums/            # 枚举
│   ├── hooks/            # 组合式 hooks（core/useChart 等）
│   ├── locales/          # vue-i18n 语言包
│   ├── router/           # 路由模块（modules/ 六组菜单）+ 守卫（guards/）
│   ├── store/            # Pinia stores（user/menu/setting/table/worktab）
│   ├── types/            # 类型声明（types/api/qxj.d.ts 等）
│   ├── utils/            # http（v3 双分支封装）、table、校验等工具
│   └── views/            # auth/ + qxj/（PC 业务页）+ mobile/（移动 UI）+ 模板演示页
├── vendor/               # qxj-frontend-sdk-0.2.3.tgz（本地 SDK tarball）
├── scripts/              # clean-dev.ts 精简脚本
├── agent_docs/           # 交接文档（qxj-frontend-integration.md、mobile-migration.md 等）
├── vite.config.ts        # 双代理 / 构建 / 混淆配置
├── package.json
└── .env.development / .env.production

环境变量 ​

变量说明
VITE_API_PROXY_URL开发代理目标，默认 http://127.0.0.1:4607（/api/v3）
VITE_API_MOCK_URLApifox mock 地址（/api，仅供模板演示页）
VITE_ENABLE_OBFUSCATORproduction 且 ≠ 'false' 时启用自研 vite-obfuscator 混淆（只处理业务 chunk，排除大 vendor，单文件 >1.6MB 跳过；曾因混淆后页面尺寸异常被关闭）

Vite 构建要点 ​

  • terser（drop_console）、cssCodeSplit:false、动态导入仅限 src/views；
  • pnpm build:backend 一键输出到 ../qxj-backend-admin/frontend_dist/ 同源部署 （--emptyOutDir 会先清空该目录）。

文档现状

仓内 README 上半部分为 QXJ 定制说明，下半部分仍是上游 Art Design Pro 模板说明； 更细的对接知识在 agent_docs/qxj-frontend-integration.md（v3 契约、枚举、菜单结构、 useTable 多实例 / echarts 懒加载等踩坑）与 agent_docs/mobile-migration.md。

最近更新