@nebula-skills/nebula-code-standards 0.1.0

package/skill/full-crud-example.md

@@ -0,0 +1,608 @@
+# 完整 CRUD 代码示例
+
+> 以 `t_demo` 表（示例管理）为蓝本，展示 Nebula 框架标准 CRUD 完整实现。
+> 新建业务模块时，将 `Demo`/`demo` 替换为实际业务名即可。
+
+---
+
+## 后端完整实现
+
+### 1. 数据库建表脚本（Flyway）
+
+文件：`nebula-{domain}-server/src/main/resources/db/migration/V1.0.0__init_t_demo.sql`
+
+```sql
+CREATE TABLE IF NOT EXISTS `t_demo`
+(
+    `id`             BIGINT       NOT NULL COMMENT '主键（雪花算法）',
+    `tenant_id`      BIGINT                DEFAULT NULL COMMENT '租户ID',
+    `create_user_id` BIGINT                DEFAULT NULL COMMENT '创建人ID',
+    `creator`        VARCHAR(100)          DEFAULT NULL COMMENT '创建人用户名',
+    `create_time`    DATETIME              DEFAULT NULL COMMENT '创建时间',
+    `modify_user_id` BIGINT                DEFAULT NULL COMMENT '最后修改人ID',
+    `updater`        VARCHAR(100)          DEFAULT NULL COMMENT '最后修改人用户名',
+    `modify_time`    DATETIME              DEFAULT NULL COMMENT '最后修改时间',
+    `delete_flag`    INT          NOT NULL DEFAULT 0 COMMENT '逻辑删除（0:未删除 1:已删除）',
+    `remark`         VARCHAR(500)          DEFAULT NULL COMMENT '备注',
+    `custom_fields`  TEXT                  DEFAULT NULL COMMENT '自定义扩展字段（JSON）',
+    `demo_name`      VARCHAR(100) NOT NULL COMMENT '示例名称',
+    `demo_code`      VARCHAR(50)  NOT NULL COMMENT '示例编码（租户内唯一）',
+    `status`         INT          NOT NULL DEFAULT 0 COMMENT '状态（0:正常 1:禁用）',
+    PRIMARY KEY (`id`),
+    UNIQUE KEY `uk_tenant_demo_code` (`tenant_id`, `demo_code`),
+    KEY `idx_demo_name` (`demo_name`),
+    KEY `idx_status` (`status`)
+) ENGINE = InnoDB DEFAULT CHARSET = utf8mb4 COMMENT ='示例表（nebula CRUD 演示）';
+```
+
+---
+
+### 2. 实体类（DemoDO）
+
+```java
+package com.huida.{domain}.{domain}.demo.entity;
+
+@Data
+@EqualsAndHashCode(callSuper = true)
+@TableName("t_demo")
+@Schema(description = "示例实体")
+public class DemoDO extends BaseEntity {
+
+    @Schema(description = "示例名称")
+    private String demoName;
+
+    @Schema(description = "示例编码（租户内唯一）")
+    private String demoCode;
+
+    @Schema(description = "状态（0:正常 1:禁用）")
+    private Integer status;
+}
+```
+
+---
+
+### 3. VO 类
+
+**分页入参（DemoPageParamVO）：**
+
+```java
+package com.huida.{domain}.{domain}.demo.vo.param;
+
+@Data
+@EqualsAndHashCode(callSuper = true)
+@Schema(description = "示例分页查询参数")
+public class DemoPageParamVO extends PageParam {
+
+    @Schema(description = "示例名称（支持模糊匹配）")
+    private String demoName;
+
+    @Schema(description = "状态（0:正常 1:禁用）")
+    private Integer status;
+}
+```
+
+**新增/修改入参（DemoSaveParamVO）：**
+
+```java
+package com.huida.{domain}.{domain}.demo.vo.param;
+
+@Data
+@Schema(description = "示例新增/修改参数")
+public class DemoSaveParamVO implements Serializable {
+
+    public interface UpdateGroup {}
+
+    @NotNull(groups = UpdateGroup.class, message = "修改时主键 id 不能为空")
+    @Schema(description = "主键（新增时不传，修改时必填）")
+    private Long id;
+
+    @NotBlank(message = "示例名称不能为空")
+    @Size(max = 100, message = "示例名称长度不能超过 100 个字符")
+    @Schema(description = "示例名称", requiredMode = Schema.RequiredMode.REQUIRED)
+    private String demoName;
+
+    @NotBlank(message = "示例编码不能为空")
+    @Size(max = 50, message = "示例编码长度不能超过 50 个字符")
+    @Schema(description = "示例编码", requiredMode = Schema.RequiredMode.REQUIRED)
+    private String demoCode;
+
+    @Schema(description = "备注")
+    private String remark;
+
+    public boolean isNew() { return id == null; }
+}
+```
+
+**列表响应（DemoRespVO）：**
+
+```java
+package com.huida.{domain}.{domain}.demo.vo.resp;
+
+@Data
+@Schema(description = "示例列表项")
+public class DemoRespVO implements Serializable {
+    @Schema(description = "主键ID")       private Long id;
+    @Schema(description = "示例名称")     private String demoName;
+    @Schema(description = "示例编码")     private String demoCode;
+    @Schema(description = "状态")         private Integer status;
+    @Schema(description = "创建人")       private String creator;
+    @Schema(description = "创建时间")     private LocalDateTime createTime;
+    @Schema(description = "最后修改时间") private LocalDateTime modifyTime;
+}
+```
+
+**详情响应（DemoDetailVO）：**
+
+```java
+package com.huida.{domain}.{domain}.demo.vo.resp;
+
+@Data
+@Schema(description = "示例详情")
+public class DemoDetailVO implements Serializable {
+    @Schema(description = "主键ID")           private Long id;
+    @Schema(description = "示例名称")         private String demoName;
+    @Schema(description = "示例编码")         private String demoCode;
+    @Schema(description = "状态")             private Integer status;
+    @Schema(description = "备注")             private String remark;
+    @Schema(description = "自定义扩展字段")   private String customFields;
+    @Schema(description = "创建人")           private String creator;
+    @Schema(description = "创建时间")         private LocalDateTime createTime;
+    @Schema(description = "创建人ID")         private Long createUserId;
+    @Schema(description = "最后修改人用户名") private String updater;
+    @Schema(description = "最后修改人ID")     private Long modifyUserId;
+    @Schema(description = "最后修改时间")     private LocalDateTime modifyTime;
+}
+```
+
+---
+
+### 4. 对象转换（DemoConvert）
+
+```java
+package com.huida.{domain}.{domain}.demo.convert;
+
+@Mapper(config = BaseMapperConfig.class)
+public interface DemoConvert {
+
+    DemoConvert INSTANCE = Mappers.getMapper(DemoConvert.class);
+
+    DemoRespVO doToRespVO(DemoDO demoDO);
+    DemoDetailVO doToDetailVO(DemoDO demoDO);
+    DemoDO saveParamToDo(DemoSaveParamVO saveParam);
+    void saveParamMergeToDo(DemoSaveParamVO saveParam, @MappingTarget DemoDO demoDO);
+}
+```
+
+---
+
+### 5. Mapper 接口（DemoMapper）
+
+```java
+package com.huida.{domain}.{domain}.demo.mapper;
+
+@Mapper
+public interface DemoMapper extends BaseMapper<DemoDO> {
+    // BaseMapper 已提供 save / removeById / updateById / selectById / selectPage 等
+    // 如需固定 SQL 查询，在此添加带 @Select 注解的方法
+}
+```
+
+---
+
+### 6. 动态查询扩展（DemoMapperExt）
+
+```java
+package com.huida.{domain}.{domain}.demo.mapper;
+
+/**
+ * 示例动态查询扩展
+ *
+ * <p>分页采用「先 count，再 fetch」两段式，count=0 时短路，避免无效的 LIMIT 查询。
+ */
+@Repository
+@RequiredArgsConstructor
+public class DemoMapperExt {
+
+    private final DemoMapper demoMapper;
+
+    public PageResult<DemoDO> pageQuery(DemoPageParamVO query) {
+        LambdaQueryWrapper<DemoDO> wrapper = buildPageWrapper(query);
+
+        Long count = demoMapper.selectCount(wrapper);
+        if (count == null || count == 0) {
+            return PageResult.empty(query);
+        }
+
+        Page<DemoDO> mpPage = new Page<>(query.getPageNo(), query.getPageSize(), false);
+        applySort(mpPage, query);
+        Page<DemoDO> result = demoMapper.selectPage(mpPage, wrapper);
+        return PageResult.of(result.getRecords(), count, query);
+    }
+
+    public boolean existsByCode(String demoCode, Long excludeId) {
+        return demoMapper.selectCount(
+            new LambdaQueryWrapper<DemoDO>()
+                .eq(DemoDO::getDemoCode, demoCode)
+                .ne(excludeId != null, DemoDO::getId, excludeId)
+        ) > 0;
+    }
+
+    private LambdaQueryWrapper<DemoDO> buildPageWrapper(DemoPageParamVO query) {
+        return new LambdaQueryWrapper<DemoDO>()
+            .like(StringUtils.hasText(query.getDemoName()), DemoDO::getDemoName, query.getDemoName())
+            .eq(query.getStatus() != null, DemoDO::getStatus, query.getStatus())
+            .orderByDesc(DemoDO::getCreateTime);
+    }
+
+    private void applySort(Page<DemoDO> mpPage, DemoPageParamVO query) {
+        if (!query.hasSorts()) return;
+        for (SortItem sortItem : query.getSorts()) {
+            String col = camelToSnake(sortItem.getColumn());
+            mpPage.addOrder(sortItem.isAscending() ? OrderItem.asc(col) : OrderItem.desc(col));
+        }
+    }
+
+    private static String camelToSnake(String camel) {
+        StringBuilder sb = new StringBuilder();
+        for (int i = 0; i < camel.length(); i++) {
+            char c = camel.charAt(i);
+            if (Character.isUpperCase(c) && i > 0) sb.append('_');
+            sb.append(Character.toLowerCase(c));
+        }
+        return sb.toString();
+    }
+}
+```
+
+---
+
+### 7. Service 接口（IDemoService）
+
+```java
+package com.huida.{domain}.{domain}.demo.service;
+
+public interface IDemoService extends BaseService<DemoDO> {
+
+    PageResult<DemoRespVO> pageDemo(DemoPageParamVO query);
+
+    DemoDetailVO getDemoById(Long id);
+
+    Long createDemo(DemoSaveParamVO saveParam);
+
+    void updateDemo(DemoSaveParamVO saveParam);
+
+    void deleteDemo(List<Long> ids);
+
+    void enableDemo(Long id);
+
+    void disableDemo(Long id);
+}
+```
+
+---
+
+### 8. Service 实现（DemoServiceImpl）
+
+```java
+package com.huida.{domain}.{domain}.demo.service.impl;
+
+@Slf4j
+@Service
+@RequiredArgsConstructor
+public class DemoServiceImpl extends BaseServiceImpl<DemoMapper, DemoDO>
+        implements IDemoService {
+
+    private final DemoMapperExt demoMapperExt;
+
+    @Override
+    public PageResult<DemoRespVO> pageDemo(DemoPageParamVO query) {
+        PageResult<DemoDO> pageResult = demoMapperExt.pageQuery(query);
+        return pageResult.convert(DemoConvert.INSTANCE::doToRespVO);
+    }
+
+    @Override
+    public DemoDetailVO getDemoById(Long id) {
+        DemoDO demoDO = getByIdOrThrow(id);
+        return DemoConvert.INSTANCE.doToDetailVO(demoDO);
+    }
+
+    @Override
+    @Transactional(rollbackFor = Exception.class)
+    public Long createDemo(DemoSaveParamVO saveParam) {
+        checkDemoCodeUnique(saveParam.getDemoCode(), null);
+        DemoDO demoDO = DemoConvert.INSTANCE.saveParamToDo(saveParam);
+        save(demoDO);
+        log.info("新增示例成功，id={}，code={}", demoDO.getId(), demoDO.getDemoCode());
+        return demoDO.getId();
+    }
+
+    @Override
+    @Transactional(rollbackFor = Exception.class)
+    public void updateDemo(DemoSaveParamVO saveParam) {
+        DemoDO demoDO = getByIdOrThrow(saveParam.getId());
+        checkDemoCodeUnique(saveParam.getDemoCode(), saveParam.getId());
+        DemoConvert.INSTANCE.saveParamMergeToDo(saveParam, demoDO);
+        updateById(demoDO);
+        log.info("修改示例成功，id={}", saveParam.getId());
+    }
+
+    @Override
+    @Transactional(rollbackFor = Exception.class)
+    public void deleteDemo(List<Long> ids) {
+        if (ids == null || ids.isEmpty()) return;
+        removeByIds(ids);
+        log.info("批量逻辑删除示例成功，ids={}", ids);
+    }
+
+    @Override
+    @Transactional(rollbackFor = Exception.class)
+    public void enableDemo(Long id) {
+        getByIdOrThrow(id);
+        DemoDO update = new DemoDO();
+        update.setId(id);
+        update.setStatus(0);
+        updateById(update);
+        log.info("启用示例成功，id={}", id);
+    }
+
+    @Override
+    @Transactional(rollbackFor = Exception.class)
+    public void disableDemo(Long id) {
+        getByIdOrThrow(id);
+        DemoDO update = new DemoDO();
+        update.setId(id);
+        update.setStatus(1);
+        updateById(update);
+        log.info("禁用示例成功，id={}", id);
+    }
+
+    /** 唯一性校验（修改时 excludeId 传入自身 id） */
+    private void checkDemoCodeUnique(String demoCode, Long excludeId) {
+        if (demoMapperExt.existsByCode(demoCode, excludeId)) {
+            throw new BusinessException(GlobalErrorCode.PARAM_INVALID.getCode(),
+                    "示例编码 [" + demoCode + "] 已存在，请更换编码");
+        }
+    }
+}
+```
+
+---
+
+### 9. Controller（DemoController）
+
+```java
+package com.huida.{domain}.{domain}.demo.controller;
+
+@Tag(name = "示例管理", description = "t_demo 增删改查演示接口")
+@Validated
+@RestController
+@RequestMapping("/{domain}/demo")
+@RequiredArgsConstructor
+public class DemoController {
+
+    private final IDemoService demoService;
+
+    @Operation(summary = "分页查询示例列表")
+    @PostMapping("/page")
+    public R<PageResult<DemoRespVO>> pageDemo(@RequestBody DemoPageParamVO query) {
+        return R.ok(demoService.pageDemo(query));
+    }
+
+    @Operation(summary = "查询示例详情")
+    @Parameter(name = "id", description = "示例主键ID", required = true)
+    @GetMapping("/{id}")
+    public R<DemoDetailVO> getDemoById(@PathVariable Long id) {
+        return R.ok(demoService.getDemoById(id));
+    }
+
+    @Operation(summary = "新增示例")
+    @PostMapping
+    public R<Long> createDemo(@Valid @RequestBody DemoSaveParamVO saveParam) {
+        return R.ok(demoService.createDemo(saveParam));
+    }
+
+    @Operation(summary = "修改示例")
+    @PutMapping
+    public R<Void> updateDemo(
+            @Validated(DemoSaveParamVO.UpdateGroup.class) @RequestBody DemoSaveParamVO saveParam) {
+        demoService.updateDemo(saveParam);
+        return R.ok();
+    }
+
+    @Operation(summary = "批量逻辑删除示例")
+    @DeleteMapping
+    public R<Void> deleteDemo(@RequestBody List<Long> ids) {
+        demoService.deleteDemo(ids);
+        return R.ok();
+    }
+
+    @Operation(summary = "启用示例")
+    @Parameter(name = "id", description = "示例主键ID", required = true)
+    @PatchMapping("/{id}/v")
+    public R<Void> enableDemo(@PathVariable Long id) {
+        demoService.enableDemo(id);
+        return R.ok();
+    }
+
+    @Operation(summary = "禁用示例")
+    @Parameter(name = "id", description = "示例主键ID", required = true)
+    @PatchMapping("/{id}/x")
+    public R<Void> disableDemo(@PathVariable Long id) {
+        demoService.disableDemo(id);
+        return R.ok();
+    }
+}
+```
+
+---
+
+## 前端完整实现
+
+### 1. TypeScript 类型定义
+
+文件：`src/api/types/demo.ts`（或直接写在 `src/api/{domain}.ts` 顶部）
+
+```typescript
+// 分页入参
+export interface DemoPageParam {
+  pageNo?: number
+  pageSize?: number
+  demoName?: string
+  status?: number
+}
+
+// 新增/修改入参
+export interface DemoSaveParam {
+  id?: number           // 新增不传，修改必传
+  demoName: string
+  demoCode: string
+  remark?: string
+}
+
+// 列表项
+export interface DemoRespVO {
+  id: number
+  demoName: string
+  demoCode: string
+  status: number        // 0: 正常, 1: 禁用
+  creator: string
+  createTime: string
+  modifyTime: string
+}
+
+// 详情
+export interface DemoDetailVO extends DemoRespVO {
+  remark?: string
+  customFields?: string
+  createUserId?: number
+  updater?: string
+  modifyUserId?: number
+}
+```
+
+### 2. API 函数
+
+文件：`src/api/{domain}.ts`
+
+```typescript
+import { {domain}Request } from './index'
+import type { PageResult } from '@nebula-web/types'
+import type { DemoPageParam, DemoSaveParam, DemoRespVO, DemoDetailVO } from './types/demo'
+
+// 分页查询
+export function getDemoPage(data: DemoPageParam): Promise<PageResult<DemoRespVO>> {
+  return {domain}Request.post('/{domain}/demo/page', data)
+}
+
+// 查询详情
+export function getDemoById(id: number): Promise<DemoDetailVO> {
+  return {domain}Request.get(`/{domain}/demo/${id}`)
+}
+
+// 新增（返回新 id）
+export function createDemo(data: DemoSaveParam): Promise<number> {
+  return {domain}Request.post('/{domain}/demo', data)
+}
+
+// 修改
+export function updateDemo(data: DemoSaveParam): Promise<void> {
+  return {domain}Request.put('/{domain}/demo', data)
+}
+
+// 批量删除
+export function deleteDemo(ids: number[]): Promise<void> {
+  return {domain}Request.delete('/{domain}/demo', { data: ids })
+}
+
+// 启用
+export function enableDemo(id: number): Promise<void> {
+  return {domain}Request.patch(`/{domain}/demo/${id}/v`)
+}
+
+// 禁用
+export function disableDemo(id: number): Promise<void> {
+  return {domain}Request.patch(`/{domain}/demo/${id}/x`)
+}
+```
+
+### 3. 路由注册
+
+文件：`src/router/routes.ts`
+
+```typescript
+{
+  path: '/demo',
+  name: 'Demo',
+  component: () => import('@/pages/demo/index.vue'),
+  meta: { title: '示例管理' },
+},
+```
+
+### 4. 页面组件使用示例
+
+文件：`src/pages/demo/index.vue`
+
+```vue
+<script setup lang="ts">
+import { ref, onMounted } from 'vue'
+import { ElMessage, ElMessageBox } from 'element-plus'
+import { getDemoPage, deleteDemo, enableDemo, disableDemo } from '@/api/{domain}'
+import type { DemoPageParam, DemoRespVO } from '@/api/types/demo'
+import type { PageResult } from '@nebula-web/types'
+
+// 查询参数
+const queryForm = ref<DemoPageParam>({ pageNo: 1, pageSize: 10 })
+
+// 分页数据
+const pageData = ref<PageResult<DemoRespVO>>({
+  records: [],
+  total: 0,
+  pageNo: 1,
+  pageSize: 10,
+  pages: 0,
+})
+const loading = ref(false)
+
+// 加载分页数据
+async function loadPage() {
+  loading.value = true
+  try {
+    pageData.value = await getDemoPage(queryForm.value)
+  } catch (err: any) {
+    ElMessage.error(err.message)
+  } finally {
+    loading.value = false
+  }
+}
+
+// 删除
+async function handleDelete(ids: number[]) {
+  await ElMessageBox.confirm('确认删除所选数据？', '提示', { type: 'warning' })
+  await deleteDemo(ids)
+  ElMessage.success('删除成功')
+  loadPage()
+}
+
+onMounted(() => loadPage())
+</script>
+```
+
+---
+
+## 菜单初始化 SQL
+
+文件：`nebula-system-server/src/main/resources/db/migration/V1.x.x__init_{domain}_demo_menu.sql`
+
+```sql
+-- 示例功能菜单
+INSERT INTO sys_menu (id, parent_id, menu_type, menu_name, perms, path, sort_order, visible, status)
+VALUES (40001, 40000, 'C', '示例管理', '{domain}:demo:query', '/{domain}app/demo', 1, 1, 1);
+
+-- 权限按钮
+INSERT INTO sys_menu (id, parent_id, menu_type, menu_name, perms, sort_order)
+VALUES (40010, 40001, 'F', '新增', '{domain}:demo:create', 1);
+INSERT INTO sys_menu (id, parent_id, menu_type, menu_name, perms, sort_order)
+VALUES (40011, 40001, 'F', '修改', '{domain}:demo:update', 2);
+INSERT INTO sys_menu (id, parent_id, menu_type, menu_name, perms, sort_order)
+VALUES (40012, 40001, 'F', '删除', '{domain}:demo:delete', 3);
+```