Files
2026-05-18 09:28:15 +08:00

181 lines
6.1 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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)