增加demo模块。优化提示词文档

2026-01-22 17:56:09 +08:00
parent 2863c963ca
commit cd5093d602
24 changed files with 2899 additions and 28 deletions
--- a/doc/后端开发文档.md
+++ b/doc/后端开发文档.md
@@ -828,16 +828,224 @@ lyzsys:

 ---

+## Demo 示例模块
+
+### 模块简介
+
+**lyzsys-module-demo** 是一个完整的业务模块示例，展示了如何在 Lyzsys 系统中快速创建一个新的业务模块。该模块实现了项目管理的完整 CRUD 功能，包括增删改查和 Excel 导出。
+
+### 功能特性
+
+- ✅ 完整的 CRUD 接口（增删改查）
+- ✅ 分页查询支持
+- ✅ 批量删除功能
+- ✅ Excel 导出功能
+- ✅ 业务字段唯一性校验
+- ✅ 权限控制
+- ✅ 前后端完整实现
+
+### 模块结构
+
+```
+lyzsys-module-demo/
+├── pom.xml                                    # Maven 配置
+└── src/main/java/cn/iocoder/lyzsys/module/demo/
+    ├── controller/admin/project/              # 控制器层
+    │   ├── ProjectController.java            # 项目控制器
+    │   └── vo/                               # VO 对象
+    │       ├── ProjectPageReqVO.java         # 分页查询请求
+    │       ├── ProjectRespVO.java            # 响应 VO
+    │       └── ProjectSaveReqVO.java         # 保存请求 VO
+    ├── service/project/                       # 服务层
+    │   ├── ProjectService.java               # 服务接口
+    │   └── ProjectServiceImpl.java           # 服务实现
+    ├── dal/                                   # 数据访问层
+    │   ├── dataobject/project/               # 数据对象
+    │   │   └── ProjectDO.java                # 项目实体类
+    │   └── mysql/project/                    # Mapper 接口
+    │       └── ProjectMapper.java            # 项目 Mapper
+    └── enums/                                 # 枚举类
+        └── ErrorCodeConstants.java           # 错误码常量
+```
+
+### 核心代码示例
+
+#### 实体类（ProjectDO）
+
+```java
+@TableName("demo_project")
+@Data
+@EqualsAndHashCode(callSuper = true)
+public class ProjectDO extends BaseDO {
+    @TableId
+    private Long id;
+
+    // 遵循命名规范：第一个单词不能只有一个字母
+    private String projectName;      // ✅ 正确（而非 pName）
+    private String projectCode;      // ✅ 正确（而非 pCode）
+    private LocalDateTime establishDate;  // ✅ 正确（而非 eDate）
+}
+```
+
+#### Controller 示例
+
+```java
+@Tag(name = "管理后台 - 项目管理")
+@RestController
+@RequestMapping("/demo/project")
+public class ProjectController {
+
+    @PostMapping("/create")
+    @Operation(summary = "创建项目")
+    @PreAuthorize("@ss.hasPermission('demo:project:create')")
+    public CommonResult<Long> createProject(@Valid @RequestBody ProjectSaveReqVO createReqVO) {
+        return success(projectService.createProject(createReqVO));
+    }
+
+    // 其他 CRUD 方法...
+}
+```
+
+### 数据库设计
+
+```sql
+CREATE TABLE `demo_project` (
+  `id` bigint NOT NULL AUTO_INCREMENT COMMENT '项目ID',
+  `project_name` varchar(100) NOT NULL COMMENT '项目名称',
+  `project_code` varchar(50) NOT NULL COMMENT '项目编号',
+  `establish_date` datetime NULL COMMENT '立项时间',
+  -- 标准字段
+  `creator` varchar(64) DEFAULT '' COMMENT '创建者',
+  `create_time` datetime NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
+  `updater` varchar(64) DEFAULT '' COMMENT '更新者',
+  `update_time` datetime NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
+  `deleted` bit(1) NOT NULL DEFAULT b'0' COMMENT '是否删除',
+  `tenant_id` bigint NOT NULL DEFAULT 0 COMMENT '租户编号',
+  PRIMARY KEY (`id`)
+) ENGINE=InnoDB COMMENT='项目管理表';
+```
+
+### 菜单配置
+
+Demo 模块的菜单结构：
+
+```
+项目管理（一级菜单，sort: 1）
+  └── 项目列表（二级菜单，sort: 1）
+      ├── 项目查询（demo:project:query）
+      ├── 项目新增（demo:project:create）
+      ├── 项目修改（demo:project:update）
+      ├── 项目删除（demo:project:delete）
+      └── 项目导出（demo:project:export）
+```
+
+### 前端实现
+
+前端代码位置：
+- API 接口：`src/api/demo/project/index.ts`
+- 列表页面：`src/views/demo/project/index.vue`
+- 表单组件：`src/views/demo/project/ProjectForm.vue`
+
+### 作为参考模板
+
+Demo 模块可以作为新业务模块开发的参考模板，包含了：
+
+1. **标准的代码结构** - 遵循项目分层架构
+2. **完整的业务逻辑** - 包括校验、异常处理等
+3. **规范的命名方式** - 遵循驼峰命名规范
+4. **权限控制示例** - 展示如何配置权限
+5. **前后端联调** - 完整的前后端交互流程
+
+**详细开发指南请参考**：
+- [新模块开发指南](./新模块开发指南.md) - 基于 demo 模块的完整开发教程
+- [编码规范](./编码规范.md) - 命名规范、菜单结构规范等
+
+---
+
+## 开发规范
+
+为确保代码质量和团队协作效率，Lyzsys 项目制定了一系列开发规范。
+
+### 核心规范文档
+
+1. **[编码规范](./编码规范.md)** - 必读 ⭐⭐⭐⭐⭐
+   - 驼峰命名规范（重要：第一个单词不能只有一个字母）
+   - 菜单结构规范
+   - 代码结构规范
+   - 数据库设计规范
+   - API 接口规范
+   - 前端开发规范
+
+2. **[新模块开发指南](./新模块开发指南.md)** - 实战教程 ⭐⭐⭐⭐⭐
+   - 快速开始
+   - 创建后端模块（完整步骤）
+   - 创建前端页面
+   - 配置菜单权限
+   - 以 Demo 模块为参考示例
+
+### 关键规范要点
+
+#### 命名规范核心原则
+
+⚠️ **重要**：所有字段名、类名的驼峰命名中，**第一个单词不能只有一个字母**
+
+```java
+// ✅ 正确示例
+private String projectId;        // 而非 pId
+private String projectName;      // 而非 pName
+private String establishDate;    // 而非 eDate
+
+// ❌ 错误示例
+private String pId;              // 单字母开头，可能导致 MyBatis Plus 映射问题
+private String mType;            // 单字母开头
+```
+
+#### 菜单结构规范
+
+业务功能菜单优先展示，系统管理功能放在最后：
+
+```
+1-90.  业务菜单（项目管理、客户管理等）
+98.    系统管理
+99.    基础设施
+```
+
+#### 权限标识格式
+
+```
+格式：{模块名}:{业务}:{操作}
+
+示例：
+demo:project:query      # 查询
+demo:project:create     # 新增
+demo:project:update     # 修改
+demo:project:delete     # 删除
+demo:project:export     # 导出
+```
+
+### 开发流程建议
+
+1. **阅读规范文档** → 了解编码规范和开发流程
+2. **参考 Demo 模块** → 理解标准的实现方式
+3. **按照开发指南** → 逐步创建新模块
+4. **代码评审** → 确保符合规范要求
+
+---
+
 ## 附录

 ### 常见问题

 #### Q1: 如何添加新的业务模块？

-1. 在 `lyzsys-module-xxx` 目录下创建新模块
-2. 按照标准模块结构创建包和类
-3. 在 `lyzsys-server/pom.xml` 中添加模块依赖
-4. 在 `application.yaml` 中配置模块扫描路径
+**推荐方式**：参考 [新模块开发指南](./新模块开发指南.md)，以 Demo 模块为模板创建新模块。
+
+**快速步骤**：
+1. 创建 Maven 模块和目录结构
+2. 编写数据库表（遵循命名规范）
+3. 按照 Demo 模块的结构创建后端代码
+4. 创建前端页面和 API 接口
+5. 配置菜单和权限

 #### Q2: 如何自定义异常？