LJYX

KaungAdmin Copilot 使用说明

项目概述

KaungAdmin 是一个基于 Vue 3 + Element Plus 的管理后台仪表盘，集成了后台管理常用功能。它遵循标准化的 RESTful API 模式，并包含用于系统设置、库存管理、采购管理等的专用功能。

架构与关键模式

API 结构

所有端点都遵循定义的一致性 RESTful 模式，后端的实体会有deleteMark、createDate、createUserName、updateDate、updateUserName等通用的字段，在搜索或者列表可展示(deleteMark不能展示以及不能传递)。修改或者新增的时候无需展示以及传递给后端这些字段，后端将会自动处理。标准的增删改查(CRUD)的后端接口参考如下：

• 参数：POST /ResourceName/Paginator（获取或者设置分页/排序、展示列/宽度/搜索/类型等参数，该接口也可以获取或者设置所有字段）
• 搜索：POST /ResourceName/Search（带分页/排序参数）
• 创建：POST /ResourceName
• 更新：PUT /ResourceName/Id
• 删除：DELETE /ResourceName/Id
• 详情：GET /ResourceName/Id

使用 kaung.js 工具进行 API 调用：

// 为资源初始化 API 助手
const api = this.$kaung.init('ResourceName');
// 带分页的搜索
api.search(params);
// 提交（根据 ID 自动检测创建与更新）
api.submit({ id: itemId, data: formData });

组件架构

• 通用布局：src/layout/index.vue - 带有可折叠侧边栏的主仪表盘布局
• 表格组件：src/components/basic-table.vue - 具有分页、排序、选择功能的标准化表格（static-table组件已弃用，请使用basic-table组件）
• 弹框组件：src/components/static-dialog.vue - 可重用的模态对话框

表格组件

• 使用 basic-table 组件显示数据网格，支持分页和排序。组件定义了标准的表格数据格式，其默认的分页参数可以通过后端实体接口的Paginator进行获取。参考如下：

  query: {
  keyword: "",
  columns: [
      { type: "selection", width: "55" },
      { type: "index", label: "序号" },
  
      { prop: "fieldName", label: "字段展示名称", sortable: true, searchable: true, width: "130",showOverflowTooltip: true },
      { type: "template", prop: "status", label: "状态", sortable: true, width: "110", },
  
      { prop: "createUserName", label: "创建人", searchable: true, width: "90", showOverflowTooltip: true },
      { prop: "createDate", label: "创建时间", sortable: true, width: "160", showOverflowTooltip: true },
      { prop: "updateUserName", label: "更新人", searchable: true, width: "90", showOverflowTooltip: true },
      { prop: "updateDate", label: "更新时间", sortable: true, width: "160", showOverflowTooltip: true },
  
      { type: "toolbar", label: "操作", width: "220", fixed: "right" },
  ],
  filters: [{name: "fieldName",value: '过滤测试值',operate: 0}],
  sidx: "sortCode",
  sord: "asc"
  }
  

• 关键词搜索：使用 keyword 参数进行模糊搜索，后端会自动将所有searchable=true的字段进行模糊搜索。

• 数据过滤：使用 filters 数组参数进行过滤，基于页面输入的过滤条件进行过滤，支持多条件组合。数组子对象包含name、value、operate、not字段，name为字段名称，value为字段值，operate为操作符（0：等于=，1：大于>，2：大于等于>=，3：小于 <，4：小于等于<=，5：模糊搜索like，6：包含in，其他后续扩展）。

• 排序：使用 sidx 和 sord 参数进行默认的排序，后端会自动将所有sortable=true的字段进行排序。如果设置了sortable=true的字段，前端表格列头会显示可点击的排序图标，用户点击后会自动更新sidx和sord参数并重新请求数据。

• 分页：前端传递page页索引、rows页大小进行分页，后端返回 total 页数和 records总数，前端表格会自动将这两个参数进行分页。

弹框组件

• 使用 static-dialog 组件显示模态对话框，支持自定义内容和操作按钮。

表单组件

• el-form的rules="rules"校验。例如金额price:[ {required: true,message: '请输入对应金额',trigger: 'blur'}, {pattern: /^(([1-9]{1}\d{0,9})|(0{1}))(.\d{1,2})?$/,message: "请输入合法的金额数字，最多两位小数",trigger: "blur"} ];

环境配置

通过 npm 脚本支持多环境模式：

• npm run serve - 开发环境（使用 .env.serve）
• npm run test - 测试环境（使用 .env.test）
• npm run prod - 生产预览环境（使用 .env.prod）
• npm run buildprod - 生产环境构建

所有环境都需要 NODE_OPTIONS=--openssl-legacy-provider 以确保兼容性。

状态管理

Vuex 存储（src/store/index.js）管理：

• 具有会话持久性的用户信息
• 网站设置和配置
• 集中式状态，通过 getter 访问：$store.getters.getUserInfo、$store.getters.getWebSetting

开发指南

文件命名与结构

• 视图：按模块组织在 src/views/ 中（例如 sys/、stock/、workflow/）
• API：基于模块组织在 src/api/ 中，与后端资源对应
• 资源：工作流资源位于 src/assets/workflow/，包含流程元素的 SVG 图标

通用模式

• 对所有数据网格使用具有标准分页的 basic-table 组件
• 导入 util 和 kaung 工具库进行通用操作
• 通过 process.env.VUE_APP_BASEURL 访问环境变量
• 日期格式化：this.$util.fmtDate(date, format)

认证流程

• Token 存储在 sessionStorage 中，键名为 access_token 和 token_type
• src/utils/request.js 中的请求拦截器自动添加 Authorization 头
• 登录路由：/login 和 /oauth2（无需认证）

专用功能

• 打印功能：使用 print-js 库进行文档打印
• Office 文档查看器：@vue-office/docx、@vue-office/excel、@vue-office/pdf
• 图表：使用 ECharts 进行数据可视化

添加新功能时，请遵循以下既定模式：基于资源的路由、通过 kaung 工具进行的标准化 API 调用、一致性的组件结构以及使用 basic-table 进行数据展示。

其他参考：

Project setup

npm install

Compiles and hot-reloads for development

npm run serve

Compiles and minifies for production

npm run build
    package scripts：【npm run buildprod】

Customize configuration

See Configuration Reference.

替换成国内镜像

npm install -g cnpm --registry=https://registry.npmmirror.com

Step

1：vue create element-plus
2：npm install element-plus --sav
3：npm install babel-plugin-component -D
4：npm install axios

更新各引用包

1、修改package里的版本号 2、npm update

参考地址：

https://element-plus.gitee.io/#/zh-CN/component/layout
http://beautiful.panm.cn/vue-admin-beautiful-element-plus/?hmsr=github&hmpl=&hmcu=&hmkw=&hmci=#/index
https://adminpro.iviewui.com/system/menu
http://manage.vue.pro.javaweb.vip/

https://github.com/501351981/vue-office

docx文档预览组件

npm install @vue-office/docx vue-demi@0.13.11

excel文档预览组件

npm install @vue-office/excel vue-demi@0.13.11

pdf文档预览组件

npm install @vue-office/pdf vue-demi@0.13.11

如果出现如下错误，可在node_modules对应的下面增加style.css的文件 ERROR Failed to compile with 1 error 10:19:39 This dependency was not found:

• element-plus/lib/style.css in ./src/main.js To install it, you can run: npm install --save element-plus/lib/style.css