181 lines
6.1 KiB
Markdown
181 lines
6.1 KiB
Markdown
# 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)
|