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

+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)