feat: initial commit

This commit is contained in:
admin committed 2026-05-18 09:28:15 +08:00
commit 539b115e38
232 files changed
+31223

No files matched your search

+461
View File
@@ -0,0 +1,461 @@
# 后端扩展开发模式
> 基于 jnpf-extend 模块的 Controller → Service → Mapper → Entity 分层架构
> 源码分析时间:2026-04-01
---
## 一、目录结构
```
jnpf-extend/
├── jnpf-extend-controller/ # 控制层
│ └── src/main/java/jnpf/controller/{Xxx}Controller.java
├── jnpf-extend-biz/ # 业务层
│ ├── src/main/java/jnpf/service/{Xxx}Service.java # 接口
│ ├── src/main/java/jnpf/service/impl/{Xxx}ServiceImpl.java
│ └── src/main/java/jnpf/mapper/{Xxx}Mapper.java
└── jnpf-extend-entity/ # 实体层
├── src/main/java/jnpf/entity/{Xxx}Entity.java
└── src/main/java/jnpf/model/{module}/*{VO,Form}.java
```
---
## 二、Entity 层
### 2.1 实体类模板
```java
package jnpf.entity;
import com.baomidou.mybatisplus.annotation.TableField;
import com.baomidou.mybatisplus.annotation.TableName;
import jnpf.base.entity.SuperExtendEntity;
import lombok.Data;
import lombok.EqualsAndHashCode;
import java.math.BigDecimal;
import java.util.Date;
@EqualsAndHashCode(callSuper = true)
@Data
@TableName("Xxx") // 表名:PascalCase 无前缀
public class XxxEntity extends SuperExtendEntity<String> {
@TableField("f_fieldName")
private String fieldName;
@TableField("f_amount")
private BigDecimal amount; // 金额用 BigDecimal
@TableField("f_createTime")
private Date createTime;
}
```
### 2.2 命名规范
| 类型 | 规范 | 示例 |
|------|------|------|
| 表名 | PascalCase 无前缀 | `TableExample` |
| 字段 | `f_` 前缀 + PascalCase | `f_projectName` |
| Java字段 | 驼峰命名 | `projectName` |
### 2.3 主键策略
- 主键类型:`String` (UUID)
- 主键生成:`RandomUtil.uuId()`
- 排序码:`RandomUtil.parses()`
### 2.4 审计字段
继承 `SuperExtendEntity` 自动获得:
- `creatorTime` / `creatorUserId` - 创建人
- `lastModifyTime` / `lastModifyUserId` - 修改人
- `sortCode` - 排序码
- `deleteMark` - 删除标记
---
## 三、Mapper 层
### 3.1 Mapper 接口模板
```java
package jnpf.mapper;
import com.baomidou.mybatisplus.core.conditions.query.QueryWrapper;
import com.baomidou.mybatisplus.extension.plugins.pagination.Page;
import jnpf.base.mapper.SuperMapper;
import jnpf.entity.XxxEntity;
import jnpf.model.PaginationXxx;
import jnpf.util.RandomUtil;
import jnpf.util.UserProvider;
import org.apache.ibatis.annotations.Mapper;
import java.util.Date;
@Mapper
public interface XxxMapper extends SuperMapper<XxxEntity> {
// ========== CRUD ==========
default XxxEntity getInfo(String id) {
return this.selectById(id);
}
default void create(XxxEntity entity) {
entity.setId(RandomUtil.uuId());
entity.setSortCode(RandomUtil.parses());
entity.setCreatorTime(new Date());
entity.setCreatorUserId(UserProvider.getUser().getUserId());
this.insert(entity);
}
default boolean update(String id, XxxEntity entity) {
entity.setId(id);
entity.setLastModifyTime(new Date());
entity.setLastModifyUserId(UserProvider.getUser().getUserId());
return this.updateById(entity) > 0;
}
default void delete(XxxEntity entity) {
this.deleteById(entity.getId());
}
// ========== 分页查询 ==========
default Page<XxxEntity> getList(PaginationXxx pagination) {
QueryWrapper<XxxEntity> wrapper = new QueryWrapper<>();
// 关键字查询
if (!StringUtils.isEmpty(pagination.getKeyword())) {
wrapper.lambda()
.like(XxxEntity::getFieldName, pagination.getKeyword());
}
// 排序
wrapper.lambda().orderByDesc(XxxEntity::getCreatorTime);
Page<XxxEntity> page = new Page<>(
pagination.getCurrentPage(),
pagination.getPageSize()
);
return this.selectPage(page, wrapper);
}
}
```
### 3.2 QueryWrapper 常用模式
```java
// 关键字模糊查询
wrapper.lambda()
.like(Entity::getField, keyword)
.or()
.like(Entity::getField2, keyword);
// 精确查询
wrapper.lambda().eq(Entity::getField, value);
// 范围查询
wrapper.lambda().between(Entity::getTime, start, end);
// IN 查询
wrapper.lambda().in(Entity::getId, list);
// 分页
Page<Entity> page = new Page<>(current, pageSize);
IPage<Entity> result = this.selectPage(page, wrapper);
```
---
## 四、Service 层
### 4.1 Service 接口
```java
package jnpf.service;
import jnpf.entity.XxxEntity;
import jnpf.model.PaginationXxx;
import java.util.List;
public interface XxxService {
List<XxxEntity> getList();
List<XxxEntity> getList(PaginationXxx pagination);
XxxEntity getInfo(String id);
void create(XxxEntity entity);
boolean update(String id, XxxEntity entity);
void delete(XxxEntity entity);
}
```
### 4.2 Service 实现
```java
package jnpf.service.impl;
@Service
public class XxxServiceImpl extends SuperServiceImpl<XxxMapper, XxxEntity>
implements XxxService {
@Override
public List<XxxEntity> getList() {
return this.baseMapper.getList();
}
@Override
public List<XxxEntity> getList(PaginationXxx pagination) {
return this.baseMapper.getList(pagination);
}
@Override
public XxxEntity getInfo(String id) {
return this.baseMapper.getInfo(id);
}
@Override
public void create(XxxEntity entity) {
this.baseMapper.create(entity);
}
@Override
public boolean update(String id, XxxEntity entity) {
return this.baseMapper.update(id, entity);
}
@Override
public void delete(XxxEntity entity) {
this.baseMapper.delete(entity);
}
}
```
---
## 五、Controller 层
### 5.1 Controller 模板
```java
package jnpf.controller;
@Tag(name = "功能名称", description = "Xxx")
@RestController
@RequestMapping("/api/extend/Xxx")
@RequiredArgsConstructor
public class XxxController extends SuperController<XxxService, XxxEntity> {
private final XxxService xxxService;
// ========== CRUD ==========
@Operation(summary = "获取列表")
@GetMapping
@SaCheckPermission("extend.xxx.list")
public ActionResult<PageListVO<XxxListVO>> list(PaginationXxx pagination) {
List<XxxEntity> data = xxxService.getList(pagination);
List<XxxListVO> list = JsonUtil.getJsonToList(data, XxxListVO.class);
return ActionResult.page(list, JsonUtil.getJsonToBean(pagination, PaginationVO.class));
}
@Operation(summary = "获取信息")
@GetMapping("/{id}")
@SaCheckPermission("extend.xxx.list")
public ActionResult<XxxInfoVO> info(@PathVariable("id") String id) {
XxxEntity entity = xxxService.getInfo(id);
return ActionResult.success(JsonUtil.getJsonToBean(entity, XxxInfoVO.class));
}
@Operation(summary = "新建")
@PostMapping
@SaCheckPermission("extend.xxx.list")
public ActionResult create(@RequestBody @Valid XxxCrForm form) {
XxxEntity entity = JsonUtil.getJsonToBean(form, XxxEntity.class);
xxxService.create(entity);
return ActionResult.success(MsgCode.SU001.get());
}
@Operation(summary = "更新")
@PutMapping("/{id}")
@SaCheckPermission("extend.xxx.list")
public ActionResult update(@PathVariable("id") String id,
@RequestBody @Valid XxxUpForm form) {
XxxEntity entity = JsonUtil.getJsonToBean(form, XxxEntity.class);
boolean flag = xxxService.update(id, entity);
return flag ? ActionResult.success(MsgCode.SU004.get())
: ActionResult.fail(MsgCode.FA002.get());
}
@Operation(summary = "删除")
@DeleteMapping("/{id}")
@SaCheckPermission("extend.xxx.list")
public ActionResult delete(@PathVariable("id") String id) {
XxxEntity entity = xxxService.getInfo(id);
if (entity != null) {
xxxService.delete(entity);
return ActionResult.success(MsgCode.SU003.get());
}
return ActionResult.fail(MsgCode.FA003.get());
}
}
```
### 5.2 接口定义模式
| 操作 | 注解 | 路径 | 权限 |
|------|------|------|------|
| 列表 | `@GetMapping` | `/api/extend/Xxx` | `@SaCheckPermission` |
| 详情 | `@GetMapping("/{id}")` | `/{id}` | `@SaCheckPermission` |
| 创建 | `@PostMapping` | `/api/extend/Xxx` | `@SaCheckPermission` |
| 更新 | `@PutMapping("/{id}")` | `/{id}` | `@SaCheckPermission` |
| 删除 | `@DeleteMapping("/{id}")` | `/{id}` | `@SaCheckPermission` |
### 5.3 参数获取方式
```java
@PathVariable("id") // URL 路径参数
@RequestBody @Valid // 请求体 + JSR-303 校验
@RequestParam("name") // 查询参数
```
### 5.4 统一返回值
```java
ActionResult.success(vo) // 成功
ActionResult.fail(MsgCode.XX.get()) // 失败
ActionResult.page(list, paginationVO) // 分页
```
---
## 六、Model 类
### 6.1 分页模型
```java
package jnpf.model;
@Data
public class PaginationXxx extends Page {
private String keyword; // 关键字
private String field; // 字段过滤
// ... 业务特定字段
}
```
### 6.2 VO 模型
```java
package jnpf.model;
// 列表 VO
@Data
public class XxxListVO {
private String id;
private String fieldName;
// 仅包含需要返回的字段
}
// 详情 VO
@Data
public class XxxInfoVO {
private String id;
private String fieldName;
private BigDecimal amount;
// 包含所有字段
}
```
### 6.3 Form 模型
```java
package jnpf.model;
// 创建表单
@Data
public class XxxCrForm {
@NotBlank(message = "字段不能为空")
private String fieldName;
}
// 更新表单
@Data
public class XxxUpForm {
private String fieldName;
}
```
---
## 七、导入导出模式(参考 EmployeeController)
### 7.1 导出 Excel
```java
@GetMapping("/ExportData")
public ActionResult<DownloadVO> exportData(PaginationXxx pagination) {
List<XxxEntity> list = xxxService.getList(pagination);
List<XxxExportVO> voList = JsonUtil.getJsonToList(list, XxxExportVO.class);
// 构建导出列
List<ExcelExportEntity> entitys = new ArrayList<>();
entitys.add(new ExcelExportEntity("列名", "field"));
ExportParams params = new ExportParams(null, "标题");
Workbook workbook = ExcelExportUtil.exportExcel(params, entitys, voList);
// 上传并返回
String fileName = "导出_" + DateUtil.dateNow("yyyyMMddHHmmss") + ".xlsx";
// ... 上传逻辑
return ActionResult.success(vo);
}
```
### 7.2 导入预览
```java
@GetMapping("/ImportPreview")
public ActionResult importPreview(@RequestParam("fileName") String fileName) {
// 下载文件并解析
List<XxxModel> list = ExcelUtil.importExcelByInputStream(inputStream, 0, 1, XxxModel.class);
return ActionResult.success(xxxService.importPreview(list));
}
```
### 7.3 导入数据
```java
@PostMapping("/ImportData")
public ActionResult importData(@RequestBody XxxModel data) {
List<XxxEntity> list = JsonUtil.getJsonToList(data.getList(), XxxEntity.class);
// ... 处理并插入
return ActionResult.success(result);
}
```
---
## 八、关键配置项
| 配置项 | 值 |
|--------|-----|
| 表名 | PascalCase 无前缀 |
| 字段前缀 | `f_` |
| 主键类型 | String (UUID) |
| 主键生成 | `RandomUtil.uuId()` |
| 审计字段 | 自动从 `SuperExtendEntity` 继承 |
| API 路径 | `/api/extend/Xxx` |
| 权限格式 | `extend.xxx.yyy` |
---
## 九、参考示例
| 示例 | 路径 | 说明 |
|------|------|------|
| TableExample | `jnpf-extend/.../TableExample*` | 完整 CRUD + 特殊操作 |
| Employee | `jnpf-extend/.../Employee*` | 导入导出完整流程 |
| Order | `jnpf-extend/.../Order*` | 主子表结构 |
| ProjectGantt | `jnpf-extend/.../ProjectGantt*` | 树形+复杂结构 |
+395
View File
@@ -0,0 +1,395 @@
# 前端扩展开发模式
> 基于 views/extend 示例的 Vue 3 + TypeScript 前端开发指南
> 源码分析时间:2026-04-01
---
## 一、前端目录结构
```
web/apps/jnpf-web-apps-main/src/
├── views/extend/ # 扩展示例
│ ├── barCode/ # 条形码
│ ├── importAndExport/ # 导入导出 ★
│ ├── tableDemo/ # 表格示例 ★
│ └── ...
└── api/extend/ # API 接口定义
├── employee.ts
├── table.ts
└── ...
```
---
## 二、API 接口定义
### 2.1 API 文件模板
```typescript
// #/api/extend/xxx.ts
import { defHttp } from '#/api/request';
enum Api {
Prefix = '/api/extend/Xxx', // 后端接口路径
}
// 获取列表
export function getXxxList(data) {
return defHttp.get({ url: Api.Prefix, data });
}
// 获取详情
export function getInfo(id) {
return defHttp.get({ url: `${Api.Prefix}/${id}` });
}
// 创建
export function createXxx(data) {
return defHttp.post({ url: Api.Prefix, data });
}
// 更新
export function updateXxx(data: { id }) {
return defHttp.put({ url: `${Api.Prefix}/${data.id}`, data });
}
// 删除
export function delXxx(id) {
return defHttp.delete({ url: `${Api.Prefix}/${id}` });
}
// 导出Excel
export function exportExcel(data) {
return defHttp.get({ url: `${Api.Prefix}/ExportData`, data });
}
// 导入预览
export function importPreview(data) {
return defHttp.get({ url: `${Api.Prefix}/ImportPreview`, data });
}
// 导入数据
export function importData(data) {
return defHttp.post({ url: `${Api.Prefix}/ImportData`, data });
}
```
### 2.2 HTTP 方法对应
| 操作 | 前端方法 | 后端注解 |
|------|----------|----------|
| 获取列表 | `defHttp.get({ url: Prefix, data })` | `@GetMapping` |
| 获取详情 | `defHttp.get({ url: `${Prefix}/${id}` })` | `@GetMapping("/{id}")` |
| 创建 | `defHttp.post({ url: Prefix, data })` | `@PostMapping` |
| 更新 | `defHttp.put({ url: `${Prefix}/${id}`, data })` | `@PutMapping("/{id}")` |
| 删除 | `defHttp.delete({ url: `${Prefix}/${id}` })` | `@DeleteMapping("/{id}")` |
---
## 三、Vue 组件模式
### 3.1 基础列表页面(使用 useVxeTable)
```vue
<script lang="ts" setup>
import type { BasicColumn } from '@jnpf/ui/vxeTable';
import { useMessage } from '@jnpf/hooks';
import { BasicVxeTable, useVxeTable } from '@jnpf/ui/vxeTable';
import { getXxxList, delXxx } from '#/api/extend/xxx';
defineOptions({ name: 'ExtendXxxDemo' });
const { createMessage, createConfirm } = useMessage();
// 列表列定义
const columns: BasicColumn[] = [
{ title: '字段1', dataIndex: 'field1', width: 120 },
{ title: '字段2', dataIndex: 'field2', width: 120 },
{ title: '创建时间', dataIndex: 'creatorTime', width: 150, format: 'date|YYYY-MM-DD' },
];
// 使用 useVxeTable
const [registerTable, { reload, getSelectRows }] = useVxeTable({
api: getXxxList, // 数据接口
columns, // 列定义
useSearchForm: true, // 启用搜索表单
formConfig: { // 搜索表单配置
schemas: [
{
field: 'keyword',
label: '关键词',
component: 'Input',
componentProps: { placeholder: '请输入' }
}
]
},
rowSelection: { type: 'checkbox' }, // 多选
});
// 操作按钮
function getTableActions(record): ActionItem[] {
return [
{ label: '编辑', onClick: handleEdit.bind(null, record) },
{ label: '删除', color: 'error', modelConfirm: { onOk: handleDel.bind(null, record.id) } }
];
}
// 编辑
function handleEdit(record) {
// 打开编辑弹窗
}
// 删除
function handleDel(id) {
delXxx(id).then(res => {
createMessage.success(res.msg);
reload();
});
}
</script>
<template>
<BasicVxeTable @register="registerTable">
<template #tableTitle>
<a-button type="primary" @click="handleAdd">新增</a-button>
</template>
<template #action="{ record }">
<TableAction :actions="getTableActions(record)" />
</template>
</BasicVxeTable>
</template>
```
### 3.2 搜索表单配置
```javascript
function getFormConfig(): Partial<FormProps> {
return {
schemas: [
{
field: 'field1',
label: '字段1',
component: 'Input',
componentProps: { placeholder: '请输入' }
},
{
field: 'field2',
label: '字段2',
component: 'Select',
componentProps: {
placeholder: '请选择',
options: [
{ id: 1, fullName: '选项1' },
{ id: 2, fullName: '选项2' }
]
}
}
]
};
}
```
### 3.3 列配置
```typescript
const columns: BasicColumn[] = [
{ title: '序号', dataIndex: 'index', width: 60, customRender: ({ index }) => index + 1 },
{ title: '编码', dataIndex: 'code', width: 150, fixed: 'left' },
{ title: '名称', dataIndex: 'name', minWidth: 150 },
{ title: '金额', dataIndex: 'amount', width: 120, format: 'money' },
{ title: '日期', dataIndex: 'date', width: 120, format: 'date|YYYY-MM-DD' },
{ title: '状态', dataIndex: 'status', width: 80, slots: { default: 'status' } },
{ title: '操作', dataIndex: 'action', width: 150, fixed: 'right' },
];
```
### 3.4 弹窗表单
```vue
<script lang="ts" setup>
import { useModal } from '@jnpf/ui/modal';
import { BasicModal } from '@jnpf/ui/modal';
const [registerModal, { openModal, closeModal }] = useModal();
// 打开弹窗
function handleAdd() {
openModal(true, { id: null });
}
// 提交
function handleSubmit() {
const data = { /* 表单数据 */ };
createXxx(data).then(res => {
createMessage.success(res.msg);
closeModal();
emit('reload');
});
}
</script>
<template>
<BasicModal @register="registerModal" title="标题" @ok="handleSubmit">
<!-- 表单内容 -->
</BasicModal>
</template>
```
---
## 四、useVxeTable 钩子
### 4.1 核心方法
```typescript
const [registerTable, {
reload, // 刷新数据
setColumns, // 设置列
getSelectRows, // 获取选中行
clearSelectedRowKeys, // 清空选择
getFetchParams, // 获取查询参数
}] = useVxeTable(options);
```
### 4.2 常用配置
```typescript
const options = {
api: getList, // 数据接口(必填)
columns, // 列定义(必填)
useSearchForm: true, // 是否显示搜索表单
formConfig, // 搜索表单配置
rowSelection: { type: 'checkbox' }, // 行选择
pagination: { pageSize: 20 }, // 分页配置
afterFetch: (data) => { // 数据处理钩子
return data.map(item => ({
...item,
// 处理数据
}));
},
};
```
---
## 五、主子表模式(参考 saleOrder)
```vue
<script lang="ts" setup>
// 主表
const [registerTable, { reload, getSelectRows }] = useVxeTable({
api: getOrderList,
columns: mainColumns,
rowClick: ({ record }) => {
// 点击主表行加载子表数据
state.activeId = record.id;
getProductEntry(record.id).then(res => {
state.productList = res.data.list;
});
}
});
// 子表
const [registerProductTable] = useVxeTable({
columns: productColumns,
useSearchForm: false,
pagination: false,
});
</script>
<template>
<div class="h-full">
<!-- 主表 -->
<BasicVxeTable @register="registerTable" />
<!-- 子表 -->
<div class="footer">
<BasicVxeTable @register="registerProductTable" :data-source="productList" />
</div>
</div>
</template>
```
---
## 六、导入导出模式(参考 importAndExport)
### 6.1 导出组件
```vue
<script lang="ts" setup>
import { useModal } from '@jnpf/ui/modal';
import { exportExcel } from '#/api/extend/xxx';
import { downloadByUrl } from '@jnpf/utils';
const [registerModal, { openModal }] = useModal();
function handleExport() {
openModal(true, { listQuery: getFetchParams() });
}
function handleSubmit() {
const query = {
...listQuery.value,
selectKey: checkedList.value.join(','),
};
exportExcel(query).then(res => {
downloadByUrl({ url: res.data.url });
closeModal();
});
}
</script>
```
### 6.2 导入组件
```vue
<script lang="ts" setup>
import { importData, importPreview } from '#/api/extend/xxx';
function handleFileChange({ file }) {
if (file.response?.code === 200) {
state.fileName = file.response.data.name;
}
}
function handlePreview() {
importPreview({ fileName: state.fileName }).then(res => {
state.list = res.data.dataRow || [];
});
}
function handleImport() {
importData({ list: state.list }).then(res => {
// 处理结果
});
}
</script>
```
---
## 七、常用组件
| 组件 | 引入 | 用途 |
|------|------|------|
| `BasicVxeTable` | `@jnpf/ui/vxeTable` | 高级表格 |
| `useVxeTable` | `@jnpf/ui/vxeTable` | 表格状态管理 |
| `TableAction` | `@jnpf/ui/vxeTable` | 表格操作按钮 |
| `BasicModal` | `@jnpf/ui/modal` | 弹窗 |
| `useModal` | `@jnpf/ui/modal` | 弹窗状态管理 |
| `useMessage` | `@jnpf/hooks` | 消息提示 |
| `usePopup` | `@jnpf/ui/popup` | 弹出页面 |
| `downloadByUrl` | `@jnpf/utils` | 文件下载 |
---
## 八、关键配置
| 配置 | 说明 |
|------|------|
| API 路径前缀 | `/api/extend/Xxx` |
| 组件 name | `ExtendXxxDemo` |
| 表格列配置 | `BasicColumn[]` |
| 搜索表单 | `formConfig.schemas` |
| 操作按钮 | `getTableActions()` |
+190
View File
@@ -0,0 +1,190 @@
# 示例目录与功能对照表
> 基于 `views/extend` 和 `jnpf-extend` 模块的完整示例索引
> 整理时间:2026-04-01
---
## 一、前端扩展示例
### 1.1 表格示例 (tableDemo)
| 示例 | 路径 | 功能说明 |
|------|------|----------|
| 普通表格 | `tableDemo/commonTable` | 基础 CRUD 操作 |
| 树形表格 | `tableDemo/treeTable` | 树形数据展示 |
| 复杂表头 | `tableDemo/complexHeader` | 多层表头合并 |
| 合并单元格 | `tableDemo/mergeTable` | 行列合并 |
| 分组表格 | `tableDemo/groupingTable` | 数据分组 |
| 锁定表格 | `tableDemo/lockTable` | 列冻结 |
| 编辑表格 | `tableDemo/redactTable` | 行内编辑 |
| 签字表格 | `tableDemo/signTable` | 手写签字 |
| 批注表格 | `tableDemo/postilTable` | 单元格批注 |
| 扩展表格 | `tableDemo/extension` | 行政区划联动 |
| 统计表格 | `tableDemo/statisticsTable` | 数据统计 |
**后端对应**:`TableExampleController` (`/api/extend/TableExample`)
### 1.2 图表示例 (graphDemo)
| 示例 | 路径 | 图表类型 |
|------|------|----------|
| 柱状图 | `graphDemo/echartsBar` | Bar |
| 折线图 | `graphDemo/echartsLine` | Line |
| 饼图 | `graphDemo/echartsPie` | Pie |
| 仪表盘 | `graphDemo/echartsGauge` | Gauge |
| 散点图 | `graphDemo/echartsScatter` | Scatter |
| 树图 | `graphDemo/echartsTree` | Tree |
| 漏斗图 | `graphDemo/echartsFunnel` | Funnel |
| K线图 | `graphDemo/echartsCandlestick` | Candlestick |
| 柱状折线混合 | `graphDemo/echartsLineBar` | Line+Bar |
| 面积图 | `graphDemo/echartsLineArea` | Line Area |
### 1.3 表单示例 (formDemo)
| 示例 | 路径 | 控件类型 |
|------|------|----------|
| fieldForm1 | `formDemo/fieldForm1` | 文本、数值、日期 |
| fieldForm2 | `formDemo/fieldForm2` | 下拉、树形 |
| fieldForm3 | `formDemo/fieldForm3` | 弹窗选择 |
| fieldForm4 | `formDemo/fieldForm4` | 文件上传 |
| fieldForm5 | `formDemo/fieldForm5` | 开关、复选框 |
| fieldForm6 | `formDemo/fieldForm6` | 定位、地图 |
| verifyForm | `formDemo/verifyForm` | 表单验证 |
### 1.4 其他示例
| 示例 | 路径 | 功能说明 |
|------|------|----------|
| 导入导出 | `importAndExport` | Excel 导入导出 ★ |
| 订单管理 | `order` | 主从表结构 |
| 销售订单 | `saleOrder` | 复杂业务表单 ★ |
| 项目甘特图 | `projectGantt` | 甘特图组件 ★ |
| 邮件 | `email` | 邮件发送接收 ★ |
| 条形码 | `barCode` | 条形码生成 |
| 印章 | `signet` | 电子印章 |
| 手写签名 | `signature` | 手写签名 |
| 文档预览 | `documentPreview` | 多格式文档预览 |
| 地图 | `map` | 百度/高德地图 |
| 大数据 | `bigData` | 大数据量表格 |
---
## 二、后端模块对照
### 2.1 Controller 层
| Controller | 路径 | 功能说明 |
|------------|------|----------|
| `TableExampleController` | `/api/extend/TableExample` | 表格 CRUD + 特殊操作 |
| `EmployeeController` | `/api/extend/Employee` | 职员管理 + 导入导出 ★ |
| `SalesOrderController` | `/api/extend/saleOrder` | 销售订单 ★ |
| `OrderController` | `/api/extend/Order` | 订单管理 |
| `ProjectGanttController` | `/api/extend/ProjectGantt` | 项目甘特图 |
| `EmailController` | `/api/extend/Email` | 邮件收发 |
| `BigDataController` | `/api/extend/BigData` | 大数据表格 |
| `BarCodeController` | `/api/extend/BarCode` | 条形码生成 |
| `DocumentPreviewController` | `/api/extend/DocumentPreview` | 文档预览 |
| `CustomerController` | `/api/extend/Customer` | 客户管理 |
| `ProductController` | `/api/extend/Product` | 产品管理 |
| `WorkLogController` | `/api/extend/WorkLog` | 工作日志 |
| `LeaveApplyController` | `/api/extend/LeaveApply` | 请假申请 |
### 2.2 Entity 层
| Entity | 表名 | 说明 |
|--------|------|------|
| `TableExampleEntity` | `table_example` | 表格示例 |
| `EmployeeEntity` | `employee` | 职员信息 |
| `SalesOrderEntity` | `sales_order` | 销售订单 |
| `OrderEntity` | `order` | 订单 |
| `ProjectGanttEntity` | `project_gantt` | 项目甘特图 |
| `EmailSendEntity` | `email_send` | 邮件发送 |
| `BigDataEntity` | `big_data` | 大数据 |
| `CustomerEntity` | `customer` | 客户 |
| `ProductEntity` | `product` | 产品 |
| `WorkLogEntity` | `work_log` | 工作日志 |
### 2.3 Service 层
| Service | 说明 |
|---------|------|
| `TableExampleService` | 表格 CRUD |
| `EmployeeService` | 职员 + 导入导出 |
| `SalesOrderService` | 销售订单 |
| `OrderService` | 订单 |
| `ProjectGanttService` | 甘特图 |
| `EmailSendService` | 邮件发送 |
| `BigDataService` | 大数据 |
---
## 三、示例功能分类
### 3.1 完整流程示例 ★★★
| 示例 | 说明 | 关键代码位置 |
|------|------|--------------|
| **Employee** | 导入导出完整流程 | `EmployeeController` 完整导入导出 |
| **TableExample** | CRUD + 特殊操作 | `TableExampleController` 批注/行编辑 |
| **saleOrder** | 主子表 | `saleOrder/index.vue` + `SalesOrderController` |
### 3.2 特殊功能示例
| 示例 | 功能 | 说明 |
|------|------|------|
| `projectGantt` | 甘特图 | 任务树 + 时间轴 |
| `email` | 邮件 | 发送/接收/配置 |
| `importAndExport` | 导入导出 | Excel/Word/PDF |
| `barCode` | 条形码 | 生成打印 |
| `documentPreview` | 文档预览 | Office/PDF/图片 |
---
## 四、源码位置速查
### 前端
```
web/apps/jnpf-web-apps-main/src/
├── views/extend/
│ ├── importAndExport/ # 导入导出 ★
│ │ ├── index.vue # 主页面
│ │ ├── ImportModal.vue # 导入弹窗
│ │ └── ExportModal.vue # 导出弹窗
│ ├── saleOrder/ # 销售订单 ★
│ │ ├── index.vue # 主页面
│ │ └── Form.vue # 表单弹窗
│ ├── tableDemo/ # 表格示例
│ ├── projectGantt/ # 甘特图
│ └── ...
└── api/extend/
├── employee.ts # 职员 API
├── saleOrder.ts # 销售订单 API
├── table.ts # 表格 API
└── ...
```
### 后端
```
jnpf/后端/jnpf-java-boot/jnpf-extend/
├── jnpf-extend-controller/src/main/java/jnpf/controller/
│ ├── EmployeeController.java # 导入导出 ★
│ ├── TableExampleController.java # CRUD ★
│ ├── SalesOrderController.java # 销售订单 ★
│ └── ...
├── jnpf-extend-biz/src/main/java/jnpf/
│ ├── service/impl/ # Service 实现
│ └── mapper/ # Mapper
└── jnpf-extend-entity/src/main/java/jnpf/
├── entity/ # Entity
└── model/ # VO/Form
```
---
## 五、推荐学习路径
1. **入门**:TableExample → CRUD 最基础
2. **进阶**:Employee → 导入导出完整流程
3. **复杂**:saleOrder → 主子表操作
4. **扩展**:projectGantt → 甘特图组件
+431
View File
@@ -0,0 +1,431 @@
# 导入导出实现详解
> 基于 EmployeeController 和 importAndExport 示例的完整导入导出流程
> 源码分析时间:2026-04-01
---
## 一、功能概述
职员管理示例是最完整的导入导出参考,包含:
- Excel 导出(可选字段)
- Excel 导入(预览 + 确认)
- Word 导出
- PDF 导出
---
## 二、前端实现
### 2.1 API 定义(employee.ts)
```typescript
import { defHttp } from '#/api/request';
enum Api {
Prefix = '/api/extend/Employee',
}
// 获取列表
export function getEmployeeList(data) {
return defHttp.get({ url: Api.Prefix, data });
}
// 删除
export function delEmployee(id) {
return defHttp.delete({ url: `${Api.Prefix}/${id}` });
}
// 导出Excel(可选字段)
export function exportExcel(data) {
return defHttp.get({ url: `${Api.Prefix}/ExportData`, data });
}
// 模板下载
export function templateDownload() {
return defHttp.get({ url: `${Api.Prefix}/TemplateDownload` });
}
// 导入
export function importData(data) {
return defHttp.post({ url: `${Api.Prefix}/ImportData`, data });
}
// 导入预览
export function importPreview(data) {
return defHttp.get({ url: `${Api.Prefix}/ImportPreview`, data });
}
```
### 2.2 导出弹窗(ExportModal.vue)
```vue
<script lang="ts" setup>
import { ref } from 'vue';
import { useModal } from '@jnpf/ui/modal';
import { exportExcel } from '#/api/extend/employee';
import { downloadByUrl } from '@jnpf/utils';
const [registerModal, { openModal, closeModal, changeOkLoading }] = useModal();
const checkedList = ref<string[]>([]);
// 可选字段列表
const columnList = ref([
{ fullName: '工号', id: 'enCode' },
{ fullName: '姓名', id: 'fullName' },
{ fullName: '性别', id: 'gender' },
{ fullName: '部门', id: 'departmentName' },
// ...
]);
function handleSubmit() {
changeOkLoading(true);
const query = {
...listQuery.value,
dataType: dataType.value, // 0=当前页, 1=全部
selectKey: checkedList.value.join(','), // 选中的字段
};
exportExcel(query).then(res => {
downloadByUrl({ url: res.data.url });
closeModal();
}).finally(() => {
changeOkLoading(false);
});
}
</script>
<template>
<BasicModal @register="registerModal" title="导出" @ok="handleSubmit">
<!-- 导出范围 -->
<a-radio-group v-model:value="dataType">
<a-radio :value="0">当前页面数据</a-radio>
<a-radio :value="1">全部页面数据</a-radio>
</a-radio-group>
<!-- 字段选择 -->
<a-checkbox v-for="item in columnList" :key="item.id" :value="item.id">
{{ item.fullName }}
</a-checkbox>
</BasicModal>
</template>
```
### 2.3 导入弹窗(ImportModal.vue)
```vue
<script lang="ts" setup>
import { ref, reactive } from 'vue';
import { useModal } from '@jnpf/ui/modal';
import { importPreview, importData, templateDownload } from '#/api/extend/employee';
import { downloadByUrl } from '@jnpf/utils';
const state = reactive({
activeStep: 0, // 0=上传, 1=预览, 2=结果
fileName: '',
fileList: [],
list: [], // 预览数据
result: {}, // 导入结果
skipPreview: false, // 跳过预览
});
const getAction = computed(() => `${globSetting.apiURL}/api/extend/Employee/Uploader`);
function handleFileChange({ file }) {
if (file.response?.code === 200) {
state.fileName = file.response.data.name;
}
}
function handlePreview() {
importPreview({ fileName: state.fileName }).then(res => {
state.list = res.data.dataRow || [];
state.activeStep = 1;
});
}
function handleImport() {
importData({ list: state.list }).then(res => {
state.result = res.data;
state.activeStep = 2;
});
}
function handleTemplateDownload() {
templateDownload().then(res => {
downloadByUrl({ url: res.data?.url });
});
}
</script>
<template>
<BasicModal @register="registerModal" title="批量导入">
<!-- 步骤条 -->
<a-steps :current="activeStep">
<a-step title="上传文件" />
<a-step title="数据预览" />
<a-step title="导入结果" />
</a-steps>
<!-- 步骤1:上传 -->
<div v-show="activeStep === 0">
<a-upload :action="getAction" @change="handleFileChange">
<a-button>上传文件</a-button>
</a-upload>
<a-button @click="handleTemplateDownload">下载模板</a-button>
<a-switch v-model:checked="skipPreview" />
</div>
<!-- 步骤2:预览 -->
<div v-show="activeStep === 1">
<a-table :data-source="list" :columns="columns" />
</div>
<!-- 步骤3:结果 -->
<div v-show="activeStep === 2">
<p>成功: {{ result.snum }}条</p>
<p>失败: {{ result.fnum }}条</p>
</div>
</BasicModal>
</template>
```
### 2.4 主页面(index.vue)
```vue
<script lang="ts" setup>
import { useVxeTable } from '@jnpf/ui/vxeTable';
import ExportModal from './ExportModal.vue';
import ImportModal from './ImportModal.vue';
const [registerExportModal, { openModal: openExportModal }] = useModal();
const [registerImportModal, { openModal: openImportModal }] = useModal();
const [registerTable, { reload, getFetchParams }] = useVxeTable({
api: getEmployeeList,
columns,
});
function handleExport() {
openExportModal(true, { listQuery: getFetchParams() });
}
function handleImport() {
openImportModal(true, {});
}
</script>
<template>
<BasicVxeTable @register="registerTable">
<template #tableTitle>
<a-button @click="handleExport">导出</a-button>
<a-button @click="handleImport">导入</a-button>
</template>
</BasicVxeTable>
<ExportModal @register="registerExportModal" />
<ImportModal @register="registerImportModal" @reload="reload" />
</template>
```
---
## 三、后端实现
### 3.1 导出 Excel(可选字段)
```java
@GetMapping("/ExportData")
public ActionResult<DownloadVO> exportExcelData(PaginationEmployee paginationEmployee) {
String dataType = paginationEmployee.getDataType();
String selectKey = paginationEmployee.getSelectKey();
// 根据类型获取数据
List<EmployeeEntity> entityList = "0".equals(dataType)
? employeeService.getList(paginationEmployee)
: employeeService.getList();
// 构建导出数据
List<EmployeeModel> modeList = new ArrayList<>();
for (EmployeeEntity entity : entityList) {
EmployeeModel mode = new EmployeeModel();
mode.setEnCode(entity.getEnCode());
mode.setFullName(entity.getFullName());
// ... 映射字段
modeList.add(mode);
}
// 根据选中的字段构建导出列
List<ExcelExportEntity> entitys = new ArrayList<>();
String[] splitData = selectKey.split(",");
for (String key : splitData) {
if ("enCode".equals(key)) {
entitys.add(new ExcelExportEntity("工号", "enCode"));
}
if ("fullName".equals(key)) {
entitys.add(new ExcelExportEntity("姓名", "fullName"));
}
// ... 其他字段
}
// 导出
ExportParams exportParams = new ExportParams(null, "职员信息");
exportParams.setType(ExcelType.XSSF);
Workbook workbook = ExcelExportUtil.exportExcel(exportParams, entitys, modeList);
// 上传文件
String fileName = "职员信息_" + DateUtil.dateNow("yyyyMMddHHmmss") + ".xlsx";
MultipartFile multipartFile = ExcelUtil.workbookToCommonsMultipartFile(workbook, fileName);
FileInfo fileInfo = FileUploadUtils.uploadFile(
new FileParameter(FileTypeConstant.TEMPORARY, fileName), multipartFile);
// 返回
DownloadVO vo = new DownloadVO();
vo.setName(fileName);
vo.setUrl(UploaderUtil.uploaderFile(fileName + "#" + FileTypeConstant.TEMPORARY));
return ActionResult.success(vo);
}
```
### 3.2 导入预览
```java
@GetMapping("/ImportPreview")
public ActionResult<Object> importPreview(@RequestParam("fileName") String fileName) {
AtomicReference<Map<String, Object>> map = new AtomicReference<>();
FileUploadUtils.downloadFile(new FileParameter(FileTypeConstant.TEMPORARY, fileName),
inputStream -> {
// 解析 Excel
List<EmployeeModel> personList = ExcelUtil.importExcelByInputStream(
inputStream, 0, 1, EmployeeModel.class);
// 返回预览数据
map.set(employeeService.importPreview(personList));
});
return ActionResult.success(map.get());
}
```
### 3.3 导入数据
```java
@PostMapping("/ImportData")
public ActionResult<EmployeeImportVO> importData(@RequestBody EmployeeModel data) {
List<EmployeeModel> dataList;
if (data.isType()) {
// 跳过预览,直接导入
ActionResult<Object> result = importPreview(data.getFileName());
Map<String, Object> dataMap = (Map<String, Object>) result.getData();
dataList = JsonUtil.getJsonToList(dataMap.get("dataRow"), EmployeeModel.class);
} else {
dataList = data.getList();
}
// 执行导入
EmployeeImportVO result = employeeService.importData(dataList);
return ActionResult.success(result);
}
```
### 3.4 Service 导入逻辑
```java
@Override
public EmployeeImportVO importData(List<EmployeeModel> dt) {
// 日期格式处理
for (EmployeeModel model : dt) {
model.setAttendWorkTime(DateUtil.cstFormat(model.getAttendWorkTime()));
model.setBirthday(DateUtil.cstFormat(model.getBirthday()));
model.setGraduationTime(DateUtil.cstFormat(model.getGraduationTime()));
}
List<EmployeeEntity> entitys = JsonUtil.getJsonToList(dt, EmployeeEntity.class);
int sum = 0; // 成功数
int num = 0; // 失败数
List<EmployeeEntity> errList = new ArrayList<>();
for (EmployeeEntity entity : entitys) {
entity.setId(RandomUtil.uuId());
entity.setCreatorUserId(UserProvider.getLoginUserId());
entity.setCreatorTime(new Date());
try {
this.baseMapper.insert(entity);
sum++;
} catch (Exception e) {
errList.add(entity);
num++;
}
}
// 返回结果
EmployeeImportVO vo = new EmployeeImportVO();
vo.setSnum(sum);
vo.setFnum(num);
vo.setResultType(num > 0 ? 1 : 0);
if (num > 0) {
vo.setFailResult(JsonUtil.getJsonToList(errList, EmployeeModel.class));
}
return vo;
}
```
---
## 四、关键工具类
| 工具类 | 用途 |
|--------|------|
| `ExcelExportUtil` | EasyPOI 导出 |
| `ExcelUtil.importExcelByInputStream` | Excel 解析 |
| `UploaderUtil.uploaderFile` | 文件上传 |
| `FileUploadUtils.uploadFile` | 文件存储 |
| `DateUtil.cstFormat` | 日期格式转换 |
---
## 五、文件上传接口
```java
@PostMapping("/Uploader")
public ActionResult<DownloadVO> uploader() {
List<MultipartFile> list = UpUtil.getFileAll();
MultipartFile file = list.get(0);
if (!file.isEmpty()) {
String fileName = RandomUtil.uuId() + "." + UpUtil.getFileType(file);
FileInfo fileInfo = FileUploadUtils.uploadFile(
new FileParameter(FileTypeConstant.TEMPORARY, fileName), file);
DownloadVO vo = new DownloadVO();
vo.setName(fileInfo.getFilename());
return ActionResult.success(vo);
}
return ActionResult.fail(MsgCode.ETD110.get());
}
```
---
## 六、导入导出结果模型
```java
@Data
public class EmployeeImportVO {
private Integer snum; // 成功数量
private Integer fnum; // 失败数量
private Integer resultType; // 结果类型 0=全部成功, 1=部分失败
private List<EmployeeModel> failResult; // 失败数据
}
```
---
## 七、完整流程图
```
导出:
用户点击导出 → 打开导出弹窗 → 选择范围和字段 → 调用 ExportData
→ Service 查询数据 → 构建 Excel → 上传文件 → 返回下载地址
导入:
用户点击导入 → 打开导入弹窗 → 上传文件 → 调用 Uploader
→ 文件上传到临时目录 → 调用 ImportPreview → 预览数据
→ 用户确认 → 调用 ImportData → Service 批量插入 → 返回结果
```
+169
View File
@@ -0,0 +1,169 @@
# 表格操作示例
> 基于 TableExampleController 和 tableDemo 的 CRUD + 特殊操作
> 源码分析时间:2026-04-01
---
## 一、功能概述
TableExample 是最完整的 CRUD 参考,包含:
- 基础 CRUD
- 树形表格
- 批注功能
- 行编辑
- 标记功能
---
## 二、后端实现
### 2.1 列表查询
```java
@GetMapping
@SaCheckPermission("extend.tableDemo.commonTable")
public ActionResult<PageListVO<TableExampleListVO>> list(PaginationTableExample pagination) {
List<TableExampleEntity> data = tableExampleService.getList(pagination);
List<TableExampleListVO> list = JsonUtil.getJsonToList(data, TableExampleListVO.class);
// 处理用户信息
List<String> userIds = list.stream().map(TableExampleListVO::getRegistrant).collect(Collectors.toList());
List<UserEntity> userList = userService.getUserName(userIds);
for (TableExampleListVO vo : list) {
UserEntity user = userList.stream()
.filter(t -> t.getId().equals(vo.getRegistrant()))
.findFirst().orElse(null);
vo.setRegistrant(user != null ? user.getRealName() + "/" + user.getAccount() : "");
}
return ActionResult.page(list, JsonUtil.getJsonToBean(pagination, PaginationVO.class));
}
```
### 2.2 创建
```java
@PostMapping
@SaCheckPermission("extend.tableDemo.commonTable")
public ActionResult create(@RequestBody @Valid TableExampleCrForm form) {
TableExampleEntity entity = JsonUtil.getJsonToBean(form, TableExampleEntity.class);
// 默认值处理
entity.setCostAmount(entity.getCostAmount() == null ? new BigDecimal("0") : entity.getCostAmount());
entity.setSign("0000000"); // 标记初始化
tableExampleService.create(entity);
return ActionResult.success(MsgCode.SU001.get());
}
```
### 2.3 批注功能
```java
// 发送批注
@PostMapping("/{id}/Postil")
public ActionResult<Object> sendPostil(@PathVariable("id") String id, @RequestBody PostilSendForm form) {
TableExampleEntity entity = tableExampleService.getInfo(id);
// 构建批注
PostilModel model = new PostilModel();
model.setCreatorTime(DateUtil.getNow("+8"));
model.setText(form.getText());
model.setUserId(UserProvider.getUser().getUserName() + "/" + UserProvider.getUser().getUserAccount());
List<PostilModel> list = new ArrayList<>();
list.add(model);
// 合并已有批注
if (!StringUtil.isEmpty(entity.getPostilJson())) {
list.addAll(JsonUtil.getJsonToList(entity.getPostilJson(), PostilModel.class));
}
entity.setPostilJson(JsonUtil.getObjectToString(list));
entity.setPostilCount(list.size());
tableExampleService.update(id, entity);
return ActionResult.success(MsgCode.SU012.get());
}
// 获取批注
@GetMapping("/{id}/Actions/Postil")
public ActionResult<PostilInfoVO> getPostil(@PathVariable("id") String id) {
TableExampleEntity entity = tableExampleService.getInfo(id);
PostilInfoVO vo = new PostilInfoVO();
vo.setPostilJson(entity.getPostilJson());
return ActionResult.success(vo);
}
```
### 2.4 行编辑
```java
@PutMapping("/{id}/Actions/RowsEdit")
public ActionResult<Object> rowEditing(@PathVariable("id") String id, @RequestBody @Valid TableExampleRowUpForm form) {
TableExampleEntity entity = JsonUtil.getJsonToBean(form, TableExampleEntity.class);
// 默认值处理
entity.setCostAmount(entity.getCostAmount() == null ? new BigDecimal("0") : entity.getCostAmount());
entity.setId(id);
boolean flag = tableExampleService.rowEditing(entity);
return flag ? ActionResult.success(MsgCode.SU004.get()) : ActionResult.fail(MsgCode.FA002.get());
}
```
---
## 三、Mapper 查询模式
```java
// 关键字模糊查询
default List<Entity> getList(String keyword) {
QueryWrapper<Entity> wrapper = new QueryWrapper<>();
if (!StringUtils.isEmpty(keyword)) {
wrapper.lambda()
.and(t -> t.like(Entity::getCustomerName, keyword)
.or().like(Entity::getProjectName, keyword));
}
wrapper.lambda().orderByDesc(Entity::getRegisterDate);
return this.selectList(wrapper);
}
// 标签查询
default List<Entity> getList(Pagination pagination) {
QueryWrapper<Entity> wrapper = new QueryWrapper<>();
String sign = pagination.getFSign();
if (!StringUtils.isEmpty(sign)) {
String[] arraySign = sign.split(",");
for (int i = 0; i < arraySign.length; i++) {
String item = arraySign[i];
if (i == 0) {
wrapper.lambda().like(Entity::getProjectCode, item);
} else {
wrapper.lambda().or(t -> t.like(Entity::getProjectCode, item));
}
}
}
// 排序
if (StringUtils.isEmpty(pagination.getSidx())) {
wrapper.lambda().orderByDesc(Entity::getRegisterDate);
} else {
wrapper.lambda().orderByDesc(pagination.getSidx());
}
return this.selectList(wrapper);
}
```
---
## 四、参考文件
| 文件 | 说明 |
|------|------|
| `TableExampleController.java` | 完整 CRUD + 批注/行编辑 |
| `TableExampleMapper.java` | QueryWrapper 查询模式 |
| `TableExampleServiceImpl.java` | 业务逻辑 |
| `tableDemo/commonTable` | 基础列表 |
| `tableDemo/postilTable` | 批注表格 |
| `tableDemo/redactTable` | 行编辑表格 |
+203
View File
@@ -0,0 +1,203 @@
# 图表示例
> 基于 graphDemo 的 ECharts 图表实现
> 源码分析时间:2026-04-01
---
## 一、图表类型
| 类型 | 路径 | ECharts 类型 |
|------|------|-------------|
| 柱状图 | `graphDemo/echartsBar` | Bar |
| 折线图 | `graphDemo/echartsLine` | Line |
| 饼图 | `graphDemo/echartsPie` | Pie |
| 仪表盘 | `graphDemo/echartsGauge` | Gauge |
| 散点图 | `graphDemo/echartsScatter` | Scatter |
| 树图 | `graphDemo/echartsTree` | Tree |
| 漏斗图 | `graphDemo/echartsFunnel` | Funnel |
| K线图 | `graphDemo/echartsCandlestick` | Candlestick |
| 柱状折线混合 | `graphDemo/echartsLineBar` | Line + Bar |
| 面积图 | `graphDemo/echartsLineArea` | Line Area |
---
## 二、柱状图示例
```vue
<script lang="ts" setup>
import { ref, onMounted } from 'vue';
import * as echarts from 'echarts';
const chartRef = ref();
onMounted(() => {
const chart = echarts.init(chartRef.value);
const option = {
tooltip: { trigger: 'axis' },
legend: { data: ['销量', '销售额'] },
xAxis: {
type: 'category',
data: ['衬衫', '裤子', '外套', '领带', '袜子']
},
yAxis: [
{ type: 'value', name: '销量' },
{ type: 'value', name: '销售额' }
],
series: [
{
name: '销量',
type: 'bar',
data: [5, 20, 36, 10, 10]
},
{
name: '销售额',
type: 'bar',
data: [50, 200, 360, 100, 100]
}
]
};
chart.setOption(option);
});
</script>
<template>
<div ref="chartRef" style="width: 100%; height: 400px;"></div>
</template>
```
---
## 三、饼图示例
```vue
<script lang="ts" setup>
import * as echarts from 'echarts';
const chartRef = ref();
onMounted(() => {
const chart = echarts.init(chartRef.value);
const option = {
tooltip: { trigger: 'item' },
legend: { bottom: '5%', left: 'center' },
series: [
{
type: 'pie',
radius: ['40%', '70%'],
avoidLabelOverlap: false,
itemStyle: { borderRadius: 10, borderColor: '#fff', borderWidth: 2 },
label: { show: false, position: 'center' },
emphasis: {
label: { show: true, fontSize: 20, fontWeight: 'bold' }
},
data: [
{ value: 1048, name: '搜索引擎' },
{ value: 735, name: '直接访问' },
{ value: 580, name: '邮件营销' },
{ value: 484, name: '联盟广告' },
{ value: 300, name: '视频广告' }
]
}
]
};
chart.setOption(option);
});
</script>
```
---
## 四、仪表盘示例
```vue
<script lang="ts" setup>
const chartRef = ref();
onMounted(() => {
const chart = echarts.init(chartRef.value);
const option = {
series: [
{
type: 'gauge',
startAngle: 180,
endAngle: 0,
min: 0,
max: 100,
splitNumber: 8,
axisLine: {
lineStyle: {
width: 6,
color: [
[0.25, '#FD1050'],
[0.5, '#FCC635'],
[0.75, '#0BB634'],
[1, '#2C82BE']
]
}
},
pointer: { icon: 'path://M12.8,0.7l12,40.1H0.7L12.8,0.7z', length: '12%', width: 20, offsetCenter: [0, '-60%'] },
axisTick: { length: 12, lineStyle: { color: 'auto', width: 2 } },
splitLine: { length: 20, lineStyle: { color: 'auto', width: 5 } },
axisLabel: { color: '#464646', fontSize: 18, distance: -60 },
title: { offsetCenter: [0, '-10%'], fontSize: 16 },
detail: { fontSize: 30, offsetCenter: [0, '-35%'], valueAnimation: true },
data: [{ value: 42, name: '完成率' }]
}
]
};
chart.setOption(option);
});
</script>
```
---
## 五、通用配置
### 5.1 响应式处理
```vue
<script lang="ts" setup>
import { ref, onMounted, onUnmounted } from 'vue';
const chartRef = ref();
let chart = null;
onMounted(() => {
chart = echarts.init(chartRef.value);
chart.setOption(option);
window.addEventListener('resize', handleResize);
});
onUnmounted(() => {
window.removeEventListener('resize', handleResize);
chart?.dispose();
});
function handleResize() {
chart?.resize();
}
</script>
```
### 5.2 常用主题
```javascript
// 暗色主题
import { use } from 'echarts/core';
import { DARK_THEME } from 'echarts/themes/dark';
use(DARK_THEME);
```
---
## 六、源码位置
| 文件 | 说明 |
|------|------|
| `graphDemo/echartsBar/index.vue` | 柱状图 |
| `graphDemo/echartsPie/index.vue` | 饼图 |
| `graphDemo/echartsGauge/index.vue` | 仪表盘 |
| `graphDemo/echartsLine/index.vue` | 折线图 |
+189
View File
@@ -0,0 +1,189 @@
# 表单控件示例
> 基于 formDemo 的 Vue 3 表单控件使用指南
> 源码分析时间:2026-04-01
---
## 一、表单控件类型
| 示例 | 路径 | 控件类型 |
|------|------|----------|
| fieldForm1 | `formDemo/fieldForm1` | 文本、数值、日期 |
| fieldForm2 | `formDemo/fieldForm2` | 下拉、树形 |
| fieldForm3 | `formDemo/fieldForm3` | 弹窗选择 |
| fieldForm4 | `formDemo/fieldForm4` | 文件上传 |
| fieldForm5 | `formDemo/fieldForm5` | 开关、复选框 |
| fieldForm6 | `formDemo/fieldForm6` | 定位、地图 |
| verifyForm | `formDemo/verifyForm` | 表单验证 |
---
## 二、文本输入
```vue
<a-form-item label="普通文本框">
<a-input v-model:value="dataForm.CommonText" />
</a-form-item>
<a-form-item label="座机号码">
<a-input v-model:value="dataForm.TelePhone" />
</a-form-item>
```
---
## 三、数值输入
```vue
<!-- 普通数值 -->
<a-input-number v-model:value="dataForm.Natural" />
<!-- 带后缀 -->
<a-input-number v-model:value="dataForm.Reimbursement" addon-after="元" />
<!-- 带自定义按钮 -->
<a-input-number v-model:value="dataForm.ProductPrice">
<template #addonAfter>
<span @click="handleRandomValue">随机设定</span>
</template>
</a-input-number>
```
---
## 四、日期选择
```vue
<!-- 日期 -->
<jnpf-date-picker v-model:value="dataForm.ProductionDate" format="YYYY-MM-DD" />
<!-- 日期时间 -->
<jnpf-date-picker v-model:value="dataForm.ReturnMoneyDate" format="YYYY-MM-DD HH:mm:ss" />
<!-- 月份 -->
<jnpf-date-picker v-model:value="dataForm.StatisticalMonth" format="YYYY-MM" />
<!-- 日期范围 -->
<jnpf-date-range v-model:value="dataForm.Dates" format="YYYY-MM-DD HH:mm:ss" />
```
---
## 五、下拉选择
```vue
<a-select v-model:value="dataForm.category" placeholder="请选择">
<a-select-option value="1">选项1</a-select-option>
<a-select-option value="2">选项2</a-select-option>
</a-select>
<!-- 带搜索 -->
<a-select v-model:value="dataForm.category" show-search :filter-option="filterOption">
<a-select-option value="1">选项1</a-select-option>
</a-select>
```
---
## 六、文件上传
```vue
<a-upload :before-upload="beforeUpload" @change="handleChange">
<a-button>
<UploadOutlined /> 点击上传
</a-button>
</a-upload>
<script>
function beforeUpload(file) {
const isXls = file.type === 'application/vnd.ms-excel' || file.name.endsWith('.xlsx');
if (!isXls) {
createMessage.error('只能上传 Excel 文件');
}
return isXls;
}
</script>
```
---
## 七、开关和复选框
```vue
<!-- 开关 -->
<a-switch v-model:checked="dataForm.enabled" />
<!-- 单个复选框 -->
<a-checkbox v-model:checked="dataForm.agree">同意协议</a-checkbox>
<!-- 复选框组 -->
<a-checkbox-group v-model:value="dataForm.hobbies">
<a-checkbox value="1">读书</a-checkbox>
<a-checkbox value="2">运动</a-checkbox>
<a-checkbox value="3">旅游</a-checkbox>
</a-checkbox-group>
```
---
## 八、表单验证
```vue
<a-form ref="formRef" :model="dataForm" :rules="rules">
<a-form-item label="名称" name="name">
<a-input v-model:value="dataForm.name" />
</a-form-item>
</a-form>
<script setup>
const rules = {
name: [
{ required: true, message: '请输入名称', trigger: 'blur' },
{ min: 3, max: 20, message: '长度在 3-20 个字符', trigger: 'blur' }
],
email: [
{ required: true, message: '请输入邮箱', trigger: 'blur' },
{ type: 'email', message: '邮箱格式不正确', trigger: 'blur' }
]
};
</script>
```
---
## 九、表单布局
```vue
<a-form
ref="formRef"
:model="dataForm"
:label-col="{ style: { width: '110px' } }"
:colon="false"
>
<a-divider orientation="left">分组标题</a-divider>
<a-form-item label="字段1">
<a-input v-model:value="dataForm.field1" />
</a-form-item>
</a-form>
<style>
/* 固定宽度 */
.ant-input,
.ant-picker,
.ant-input-number {
width: 300px !important;
}
</style>
```
---
## 十、参考文件
| 文件 | 说明 |
|------|------|
| `formDemo/fieldForm1` | 文本、数值、日期 |
| `formDemo/fieldForm2` | 下拉、树形 |
| `formDemo/verifyForm` | 表单验证 |
+289
View File
@@ -0,0 +1,289 @@
# 特殊功能示例
> 甘特图、订单、邮件等复杂业务功能
> 源码分析时间:2026-04-01
---
## 一、销售订单(saleOrder)
### 1.1 功能特点
- 主子表结构(订单 + 明细)
- 右侧产品选择弹窗
- 订单状态管理
### 1.2 前端实现
```vue
<script lang="ts" setup>
// 主表
const [registerTable, { reload, getSelectRows }] = useVxeTable({
api: getOrderList,
columns: mainColumns,
rowClick: ({ record }) => {
// 点击主表行加载子表
state.activeId = record.id;
getProductEntry(record.id).then(res => {
state.productList = res.data.list;
});
}
});
// 子表
const [registerProductTable] = useVxeTable({
columns: productColumns,
useSearchForm: false,
pagination: false,
});
</script>
<template>
<div class="h-full">
<!-- 主表 -->
<BasicVxeTable @register="registerTable" />
<!-- 子表 -->
<div class="footer">
<BasicVxeTable @register="registerProductTable" :data-source="productList" />
</div>
</div>
</template>
```
### 1.3 后端 API
```typescript
// saleOrder.ts
export function getOrderList(data) {
return defHttp.get({ url: '/api/extend/saleOrder/Product', data });
}
export function getProductEntry(id) {
return defHttp.get({ url: `/api/extend/saleOrder/Product/ProductEntry/${id}` });
}
```
---
## 二、项目甘特图(projectGantt)
### 2.1 功能特点
- 树形任务结构
- 甘特图时间轴
- 任务依赖关系
### 2.2 前端组件
```
projectGantt/
├── index.vue # 主页面
├── Task.vue # 任务组件
├── TaskForm.vue # 任务表单
└── Form.vue # 甘特图配置
```
### 2.3 后端 Controller
```java
// ProjectGanttController
@GetMapping
public ActionResult<ListVO<ProjectGanttListVO>> list() { }
@GetMapping("/{id}")
public ActionResult<ProjectGanttInfoVO> info(@PathVariable("id") String id) { }
@PostMapping
public ActionResult create(@RequestBody @Valid ProjectGanttCrForm form) { }
@PutMapping("/{id}")
public ActionResult update(@PathVariable("id") String id, @RequestBody ProjectGanttUpForm form) { }
```
---
## 三、邮件功能(email)
### 3.1 功能模块
- 邮件发送(EmailSend)
- 邮件接收(EmailReceive)
- 邮件配置(EmailConfig)
### 3.2 前端结构
```
email/
├── index.vue # 邮件列表
├── Form.vue # 发送表单
├── Detail.vue # 邮件详情
├── Config.vue # 配置页面
├── DetailPage.vue # 详情页面
└── DetailMain.vue # 详情主体
```
### 3.3 后端 Controller
```java
// EmailController
@GetMapping
public ActionResult list() { }
@PostMapping
public ActionResult create(@RequestBody EmailSendEntity entity) { }
@GetMapping("/{id}")
public ActionResult info(@PathVariable("id") String id) { }
```
---
## 四、大数据表格(bigData)
### 4.1 特点
- 虚拟滚动
- 分页加载
- 大量数据处理
### 4.2 实现参考
```vue
<script lang="ts" setup>
const [registerTable] = useVxeTable({
api: getBigDataList,
columns,
pagination: { pageSize: 100, showSizeChanger: true },
scroll: { y: 600 },
});
</script>
```
---
## 五、条形码(barCode)
### 5.1 前端实现
```vue
<script lang="ts" setup>
import { barcode } from '@jnpf/utils';
const generateBarcode = () => {
barcode(document.getElementById('barcode'), '123456789', {
displayValue: true,
fontSize: 14,
height: 60
});
};
</script>
<template>
<div id="barcode"></div>
</template>
```
### 5.2 后端 Controller
```java
@GetMapping("/{content}")
public ActionResult<String> generate(@PathVariable("content") String content) {
// 返回条形码图片
}
```
---
## 六、文档预览(documentPreview)
### 6.1 支持格式
- PDF
- Office 文档(Word、Excel、PPT)
- 图片
- 文本文件
### 6.2 实现方式
```vue
<script lang="ts" setup>
import { previewFile } from '@jnpf/utils';
function handlePreview(file) {
previewFile(file.url, file.name);
}
</script>
```
---
## 七、源码位置
| 功能 | 前端路径 | 后端 Controller |
|------|----------|-----------------|
| 销售订单 | `saleOrder/` | `SalesOrderController` |
| 项目甘特图 | `projectGantt/` | `ProjectGanttController` |
| 邮件 | `email/` | `EmailController` |
| 大数据 | `bigData/` | `BigDataController` |
| 条形码 | `barCode/` | `BarCodeController` |
| 文档预览 | `documentPreview/` | `DocumentPreviewController` |
---
## 八、主子表开发模板
### 8.1 前端主子表
```vue
<template>
<div>
<!-- 主表 -->
<BasicVxeTable
@register="registerMainTable"
@row-click="handleRowClick"
/>
<!-- 子表 -->
<BasicVxeTable
@register="registerSubTable"
:data-source="subList"
/>
</div>
</template>
<script setup>
const [registerMainTable, { reload }] = useVxeTable({
api: getMainList,
columns: mainColumns,
});
const [registerSubTable] = useVxeTable({
columns: subColumns,
useSearchForm: false,
pagination: false,
});
function handleRowClick({ record }) {
getSubList(record.id).then(res => {
subList.value = res.data;
});
}
</script>
```
### 8.2 后端主子表
```java
// 主表查询
@GetMapping
public ActionResult list(Pagination pagination) {
List<MainEntity> list = mainService.getList(pagination);
return ActionResult.page(list, pagination);
}
// 子表查询
@GetMapping("/{id}/Entries")
public ActionResult<ListVO<SubEntity>> getEntries(@PathVariable("id") String id) {
List<SubEntity> list = subService.getListByMainId(id);
return ActionResult.success(list);
}
```
+250
View File
@@ -0,0 +1,250 @@
# 快速开发模板
> 基于 JNPF 扩展开发的完整代码模板
> 整理时间:2026-04-01
---
## 一、后端快速模板
### 1.1 Entity
```java
package jnpf.entity;
import com.baomidou.mybatisplus.annotation.TableField;
import com.baomidou.mybatisplus.annotation.TableName;
import jnpf.base.entity.SuperExtendEntity;
import lombok.Data;
import lombok.EqualsAndHashCode;
import java.math.BigDecimal;
@EqualsAndHashCode(callSuper = true)
@Data
@TableName("Xxx")
public class XxxEntity extends SuperExtendEntity<String> {
@TableField("f_name")
private String name;
@TableField("f_amount")
private BigDecimal amount;
}
```
### 1.2 Mapper
```java
package jnpf.mapper;
import com.baomidou.mybatisplus.core.conditions.query.QueryWrapper;
import jnpf.base.mapper.SuperMapper;
import jnpf.entity.XxxEntity;
import jnpf.util.RandomUtil;
import jnpf.util.UserProvider;
import org.apache.ibatis.annotations.Mapper;
import java.util.Date;
@Mapper
public interface XxxMapper extends SuperMapper<XxxEntity> {
default XxxEntity getInfo(String id) {
return this.selectById(id);
}
default void create(XxxEntity entity) {
entity.setId(RandomUtil.uuId());
entity.setSortCode(RandomUtil.parses());
entity.setCreatorTime(new Date());
entity.setCreatorUserId(UserProvider.getUser().getUserId());
this.insert(entity);
}
default boolean update(String id, XxxEntity entity) {
entity.setId(id);
entity.setLastModifyTime(new Date());
entity.setLastModifyUserId(UserProvider.getUser().getUserId());
return this.updateById(entity) > 0;
}
default void delete(XxxEntity entity) {
this.deleteById(entity.getId());
}
}
```
### 1.3 Service
```java
// 接口
package jnpf.service;
public interface XxxService {}
// 实现
package jnpf.service.impl;
@Service
public class XxxServiceImpl extends SuperServiceImpl<XxxMapper, XxxEntity> implements XxxService {}
```
### 1.4 Controller
```java
package jnpf.controller;
@Tag(name = "功能名称", description = "Xxx")
@RestController
@RequestMapping("/api/extend/Xxx")
@RequiredArgsConstructor
public class XxxController extends SuperController<XxxService, XxxEntity> {
private final XxxService xxxService;
@Operation(summary = "列表")
@GetMapping
@SaCheckPermission("extend.xxx.list")
public ActionResult<PageListVO<XxxListVO>> list(PaginationXxx pagination) {
List<XxxEntity> data = xxxService.getList(pagination);
return ActionResult.page(JsonUtil.getJsonToList(data, XxxListVO.class),
JsonUtil.getJsonToBean(pagination, PaginationVO.class));
}
@Operation(summary = "详情")
@GetMapping("/{id}")
public ActionResult<XxxInfoVO> info(@PathVariable("id") String id) {
return ActionResult.success(JsonUtil.getJsonToBean(xxxService.getInfo(id), XxxInfoVO.class));
}
@Operation(summary = "新建")
@PostMapping
public ActionResult create(@RequestBody @Valid XxxCrForm form) {
xxxService.create(JsonUtil.getJsonToBean(form, XxxEntity.class));
return ActionResult.success(MsgCode.SU001.get());
}
@Operation(summary = "更新")
@PutMapping("/{id}")
public ActionResult update(@PathVariable("id") String id, @RequestBody @Valid XxxUpForm form) {
boolean flag = xxxService.update(id, JsonUtil.getJsonToBean(form, XxxEntity.class));
return flag ? ActionResult.success(MsgCode.SU004.get()) : ActionResult.fail(MsgCode.FA002.get());
}
@Operation(summary = "删除")
@DeleteMapping("/{id}")
public ActionResult delete(@PathVariable("id") String id) {
XxxEntity entity = xxxService.getInfo(id);
if (entity != null) {
xxxService.delete(entity);
return ActionResult.success(MsgCode.SU003.get());
}
return ActionResult.fail(MsgCode.FA003.get());
}
}
```
---
## 二、前端快速模板
### 2.1 API
```typescript
// #/api/extend/xxx.ts
import { defHttp } from '#/api/request';
enum Api { Prefix = '/api/extend/Xxx' }
export const getXxxList = (data) => defHttp.get({ url: Api.Prefix, data });
export const getInfo = (id) => defHttp.get({ url: `${Api.Prefix}/${id}` });
export const createXxx = (data) => defHttp.post({ url: Api.Prefix, data });
export const updateXxx = (data) => defHttp.put({ url: `${Api.Prefix}/${data.id}`, data });
export const delXxx = (id) => defHttp.delete({ url: `${Api.Prefix}/${id}` });
```
### 2.2 列表页面
```vue
<script lang="ts" setup>
import { useVxeTable } from '@jnpf/ui/vxeTable';
import { getXxxList, delXxx } from '#/api/extend/xxx';
const columns = [
{ title: '名称', dataIndex: 'name', width: 150 },
{ title: '金额', dataIndex: 'amount', width: 120 },
{ title: '时间', dataIndex: 'creatorTime', width: 150, format: 'date|YYYY-MM-DD' },
];
const [registerTable, { reload }] = useVxeTable({
api: getXxxList,
columns,
useSearchForm: true,
formConfig: {
schemas: [{ field: 'keyword', label: '关键词', component: 'Input' }]
}
});
const { createMessage, createConfirm } = useMessage();
function handleDel(id) {
createConfirm({
iconType: 'warning', title: '提示', content: '确认删除?',
onOk: () => { delXxx(id).then(res => { createMessage.success(res.msg); reload(); }); }
});
}
</script>
<template>
<BasicVxeTable @register="registerTable">
<template #tableTitle>
<a-button type="primary" @click="handleAdd">新增</a-button>
</template>
<template #action="{ record }">
<TableAction :actions="[
{ label: '编辑', onClick: handleEdit.bind(null, record) },
{ label: '删除', color: 'error', modelConfirm: { onOk: handleDel.bind(null, record.id) } }
]" />
</template>
</BasicVxeTable>
</template>
```
---
## 三、数据库表结构
```sql
CREATE TABLE Xxx (
f_id VARCHAR(50) PRIMARY KEY,
f_name VARCHAR(100) COMMENT '名称',
f_amount DECIMAL(18,2) COMMENT '金额',
f_sortCode INT COMMENT '排序码',
f_creatorTime DATETIME COMMENT '创建时间',
f_creatorUser VARCHAR(50) COMMENT '创建人',
f_modifyTime DATETIME COMMENT '修改时间',
f_modifyUser VARCHAR(50) COMMENT '修改人',
f_deleteMark INT DEFAULT 0 COMMENT '删除标记'
);
```
---
## 四、关键配置清单
| 项目 | 配置 |
|------|------|
| 表名 | `Xxx` |
| 字段前缀 | `f_` |
| 主键 | `f_id` VARCHAR(50) |
| Controller 路径 | `/api/extend/Xxx` |
| 权限标识 | `extend.xxx.list` |
| 主键生成 | `RandomUtil.uuId()` |
| 审计字段 | 自动继承 |
---
## 五、参考示例
| 示例 | 路径 | 用途 |
|------|------|------|
| Employee | `EmployeeController` | 导入导出 |
| TableExample | `TableExampleController` | CRUD |
| saleOrder | `saleOrder/` | 主子表 |
| projectGantt | `projectGantt/` | 甘特图 |
+180
View File
@@ -0,0 +1,180 @@
# JNPF 扩展开发文档 (codedev)
> 基于 JNPF 平台扩展模块(jnpf-extend)的系统性开发指南
> 整理时间:2026-04-01
---
## 文档结构
| 文档 | 说明 |
|------|------|
| **[README.md](README.md)** | 本文档,速查与索引 |
| **[01-backend-pattern.md](01-backend-pattern.md)** | 后端扩展开发模式(Controller/Service/Mapper/Entity) |
| **[02-frontend-pattern.md](02-frontend-pattern.md)** | 前端扩展开发模式(Vue 组件/API 调用) |
| **[03-examples-index.md](03-examples-index.md)** | 示例目录与功能对照表 |
| **[04-import-export.md](04-import-export.md)** | 导入导出实现(Employee 示例) |
| **[05-table-operation.md](05-table-operation.md)** | 表格操作示例(TableExample 示例) |
| **[06-chart-examples.md](06-chart-examples.md)** | 图表示例(ECharts) |
| **[07-form-examples.md](07-form-examples.md)** | 表单控件示例 |
| **[08-special-features.md](08-special-features.md)** | 特殊功能(甘特图、订单、邮件等) |
| **[09-quick-start.md](09-quick-start.md)** | 快速开发模板 |
---
## VisualDev vs codedev 适用场景
**优先使用 VisualDev(低代码表单)**:通用 CRUD、表单+列表、简单审批流程、数据管理
**必须使用 codedev(扩展开发)**:
- 复杂业务逻辑(多个外部 API 调用、数据转换)
- 自定义算法(统计、分析、调度)
- 非标准交互(特殊控件、复杂验证规则)
- 性能敏感操作(批量处理、大数据量操作)
- 需要直接操作数据库的场景
- 需要调用第三方服务的场景
**典型选择**:
| 场景 | 推荐方式 |
|------|----------|
| 通用表单+列表 | VisualDev |
| 简单审批流程 | VisualDev + workflow |
| 复杂表单(多步骤、联动计算) | codedev |
| 图表分析页面 | codedev |
| 导入导出(复杂格式) | codedev |
| 定时任务/批处理 | codedev |
---
## 核心规则速查
### 后端命名规范
| 类型 | 规范 | 示例 |
|------|------|------|
| 表名 | PascalCase 无前缀 | `TableExample` |
| 字段 | `f_` 前缀 + PascalCase | `f_projectName` |
| Java字段 | 驼峰命名 | `projectName` |
| Controller路径 | `/api/extend/Xxx` | `/api/extend/Employee` |
| 权限标识 | `extend.xxx.yyy` | `extend.tableDemo.commonTable` |
| 主键 | String (UUID) | `RandomUtil.uuId()` |
### 前端命名规范
| 类型 | 规范 | 示例 |
|------|------|------|
| API文件 | `#/api/extend/xxx` | `#/api/extend/employee` |
| 组件路径 | `views/extend/xxx` | `views/extend/importAndExport` |
| 组件name | `ExtendXxx` | `ExtendImportAndExport` |
### 关键 API 路径
| 功能 | 路径 | 方法 |
|------|------|------|
| 列表 | `/api/extend/Xxx` | GET |
| 详情 | `/api/extend/Xxx/{id}` | GET |
| 创建 | `/api/extend/Xxx` | POST |
| 更新 | `/api/extend/Xxx/{id}` | PUT |
| 删除 | `/api/extend/Xxx/{id}` | DELETE |
| 导出 | `/api/extend/Xxx/ExportData` | GET |
| 导入预览 | `/api/extend/Xxx/ImportPreview` | GET |
| 导入数据 | `/api/extend/Xxx/ImportData` | POST |
---
## 源码位置索引
### 前端示例
```
web/apps/jnpf-web-apps-main/src/views/extend/
├── barCode/ # 条形码
├── bigData/ # 大数据表格
├── documentPreview/ # 文档预览
├── email/ # 邮件发送
├── formDemo/ # 表单控件(6种)
├── graphDemo/ # 图表(10种ECharts)
├── importAndExport/ # 导入导出 ★
├── map/ # 地图
├── order/ # 订单管理
├── projectGantt/ # 项目甘特图
├── saleOrder/ # 销售订单
├── signature/ # 手写签名
├── signet/ # 印章
└── tableDemo/ # 表格控件(10种) ★
```
### 前端 API
```
前端/.../src/api/extend/
├── employee.ts # 职员管理(含导入导出)
├── table.ts # 表格示例
├── saleOrder.ts # 销售订单
├── order.ts # 订单
├── email.ts # 邮件
├── bigData.ts # 大数据
├── documentPreview.ts # 文档预览
└── projectGantt.ts # 项目甘特图
```
### 后端模块
```
jnpf/后端/jnpf-java-boot/jnpf-extend/
├── jnpf-extend-controller/ # Controller 层
│ └── jnpf/controller/*.java
├── jnpf-extend-biz/ # Service + Mapper 层
│ ├── jnpf/service/impl/*.java
│ └── jnpf/mapper/*.java
└── jnpf-extend-entity/ # Entity + Model 层
├── jnpf/entity/*.java
└── jnpf/model/**/*.java
```
---
## 示例功能对照表
| 示例 | 前端入口 | 后端Controller | 关键功能 |
|------|----------|----------------|----------|
| 职员管理 | importAndExport | EmployeeController | 导入导出Excel/Word/PDF |
| 表格示例 | tableDemo/* | TableExampleController | CRUD、树形、批注、行编辑 |
| 销售订单 | saleOrder | SalesOrderController | 主子表、明细表 |
| 项目甘特图 | projectGantt | ProjectGanttController | 甘特图、任务管理 |
| 邮件 | email | EmailController | 发送、接收、配置 |
| 大数据 | bigData | BigDataController | 分页、大数据量 |
| 条形码 | barCode | BarCodeController | 条形码生成 |
| 文档预览 | documentPreview | DocumentPreviewController | 多格式文档预览 |
---
## 开发流程
### 1. 后端开发
```
1. 创建 Entity (jnpf-extend-entity)
2. 创建 Mapper (jnpf-extend-biz)
3. 创建 Service 接口 + 实现
4. 创建 Controller
5. 添加权限配置
```
### 2. 前端开发
```
1. 创建 API 文件 (#/api/extend/xxx)
2. 创建 Vue 组件 (views/extend/xxx)
3. 使用 useVxeTable 或 BasicVxeTable
4. 注册到菜单系统
```
### 3. 完整示例参考
- 职员管理(importAndExport):导入导出完整流程
- 表格示例(tableDemo):CRUD + 特殊操作
- 销售订单(saleOrder):主子表操作
---
## 相关文档
- [AIBridge API 参考](../../api-reference.md)
- [表单开发指南](../form-development/)
- [工作流开发指南](../workflow/)
- [平台机制](../platform-guide.md)