ai-engineering-init 1.1.0

package/.claude/docs//345/220/216/347/253/257/345/274/200/345/217/221/346/214/207/345/215/227.md

@@ -0,0 +1,726 @@
+# 后端开发指南
+
+> **重要提示**: 本项目是 RuoYi-Vue-Plus **纯后端项目**，采用**三层架构**。
+> 严格遵循本规范，参考 `ruoyi-demo` 模块的 TestDemo 实现。
+
+最后更新: 2026-02-09
+
+---
+
+## 🏗️ 核心架构（必须牢记）
+
+| 项目 | 规范 |
+|------|------|
+| **包名** | `org.dromara.*`（禁止 `com.ruoyi.*`、`plus.ruoyi.*`） |
+| **架构** | 三层：Controller → Service → Mapper（**无 DAO 层**） |
+| **查询构建** | Service 层 `buildQueryWrapper()` |
+| **Mapper 继承** | `BaseMapperPlus<Entity, VO>` |
+| **对象转换** | `MapstructUtils.convert()`（禁止 BeanUtils） |
+| **Entity 基类** | `TenantEntity`（多租户） |
+| **BO 映射** | `@AutoMapper` 注解（**单数**，不是 `@AutoMappers`） |
+| **主键策略** | 雪花 ID（不用 AUTO_INCREMENT） |
+| **Controller 基类** | `extends BaseController` |
+
+---
+
+## 📁 项目结构
+
+```
+RuoYi-Vue-Plus/
+├── ruoyi-admin/                      # 后端启动入口
+│   └── src/main/resources/
+│       ├── application.yml           # 主配置
+│       └── application-dev.yml       # 开发环境配置
+│
+├── ruoyi-common/                     # 通用工具模块（24个子模块）
+│   ├── ruoyi-common-core/           # 核心工具（MapstructUtils, StringUtils）
+│   ├── ruoyi-common-mybatis/        # MyBatis-Plus 扩展（BaseMapperPlus）
+│   ├── ruoyi-common-tenant/         # 多租户（TenantEntity）
+│   ├── ruoyi-common-redis/          # Redis 缓存
+│   ├── ruoyi-common-satoken/        # 权限认证
+│   └── ...                          # 其他模块
+│
+├── ruoyi-modules/                    # 业务功能模块
+│   ├── ruoyi-system/                # 系统管理模块（sys_*）
+│   ├── ruoyi-demo/                  # 演示模块（test_*）⭐ 参考实现
+│   ├── ruoyi-generator/             # 代码生成器
+│   ├── ruoyi-job/                   # 定时任务（SnailJob）
+│   └── ruoyi-workflow/              # 工作流（WarmFlow）
+│
+└── script/sql/                      # 数据库脚本
+    └── ry_vue_5.X.sql              # 系统表初始化
+```
+
+---
+
+## 📐 三层架构详解
+
+### 架构流程图
+
+```
+┌──────────────────────────────────────────────────────────────┐
+│                    Controller 层                              │
+│     • 接收 HTTP 请求、参数校验、返回 R<T> 响应               │
+│     • 路由：/list, /{id}, POST, PUT, DELETE/{ids}           │
+│     • 权限：@SaCheckPermission                               │
+└──────────────────────────────┬───────────────────────────────┘
+                               │
+                               ▼
+┌──────────────────────────────────────────────────────────────┐
+│                      Service 层                               │
+│     • 业务逻辑处理、事务管理                                  │
+│     • buildQueryWrapper() 查询条件构建 ⭐                    │
+│     • 使用 MapstructUtils.convert() 对象转换                 │
+│     • 直接注入 Mapper（无 DAO 层）                           │
+└──────────────────────────────┬───────────────────────────────┘
+                               │
+                               ▼
+┌──────────────────────────────────────────────────────────────┐
+│                      Mapper 层                                │
+│     • extends BaseMapperPlus<Entity, Vo>                     │
+│     • 提供 selectVoById、selectVoPage、selectVoList 等方法   │
+└──────────────────────────────────────────────────────────────┘
+```
+
+### 标准模块结构
+
+```
+ruoyi-modules/ruoyi-xxx/src/main/java/org/dromara/xxx/
+├── controller/
+│   └── XxxController.java          # @RestController, extends BaseController
+├── service/
+│   ├── IXxxService.java            # 服务接口
+│   └── impl/
+│       └── XxxServiceImpl.java     # 服务实现（包含 buildQueryWrapper）
+├── mapper/
+│   └── XxxMapper.java              # extends BaseMapperPlus<Xxx, XxxVo>
+└── domain/
+    ├── Xxx.java                    # Entity（extends TenantEntity）
+    ├── bo/
+    │   └── XxxBo.java              # 业务对象（@AutoMapper）
+    └── vo/
+        └── XxxVo.java              # 视图对象
+```
+
+---
+
+## 📋 代码模板
+
+### 1. Entity 实体类
+
+```java
+package org.dromara.demo.domain;
+
+import com.baomidou.mybatisplus.annotation.*;
+import lombok.Data;
+import lombok.EqualsAndHashCode;
+import org.dromara.common.tenant.core.TenantEntity;
+import java.io.Serial;
+
+/**
+ * XXX 对象
+ */
+@Data
+@EqualsAndHashCode(callSuper = true)
+@TableName("test_xxx")
+public class Xxx extends TenantEntity {  // ✅ 继承 TenantEntity
+
+    @Serial
+    private static final long serialVersionUID = 1L;
+
+    /**
+     * 主键 ID
+     */
+    @TableId(value = "id")
+    private Long id;
+
+    /**
+     * 名称
+     */
+    private String xxxName;
+
+    /**
+     * 状态（0停用 1正常）
+     */
+    private String status;
+}
+```
+
+**关键点**：
+- ✅ 继承 `TenantEntity`（包含租户ID、审计字段、逻辑删除）
+- ✅ `@TableId(value = "id")` 使用雪花ID（全局配置）
+- ✅ 字段名使用驼峰命名，自动映射蛇形数据库字段
+
+---
+
+### 2. BO 业务对象
+
+```java
+package org.dromara.demo.domain.bo;
+
+import io.github.linpeilie.annotations.AutoMapper;
+import jakarta.validation.constraints.*;
+import lombok.Data;
+import lombok.EqualsAndHashCode;
+import org.dromara.common.core.validate.AddGroup;
+import org.dromara.common.core.validate.EditGroup;
+import org.dromara.common.mybatis.core.domain.BaseEntity;
+import org.dromara.demo.domain.Xxx;
+
+/**
+ * XXX 业务对象
+ */
+@Data
+@EqualsAndHashCode(callSuper = true)
+@AutoMapper(target = Xxx.class, reverseConvertGenerate = false)  // ✅ 单数！
+public class XxxBo extends BaseEntity {
+
+    @NotNull(message = "ID不能为空", groups = {EditGroup.class})
+    private Long id;
+
+    @NotBlank(message = "名称不能为空", groups = {AddGroup.class, EditGroup.class})
+    private String xxxName;
+
+    private String status;
+}
+```
+
+**关键点**：
+- ✅ `@AutoMapper`（**单数**，不是 `@AutoMappers`）
+- ✅ 继承 `BaseEntity`（包含 params 查询参数）
+- ✅ 使用分组校验：`AddGroup`、`EditGroup`
+
+---
+
+### 3. VO 视图对象
+
+```java
+package org.dromara.demo.domain.vo;
+
+import cn.idev.excel.annotation.ExcelIgnoreUnannotated;
+import cn.idev.excel.annotation.ExcelProperty;
+import io.github.linpeilie.annotations.AutoMapper;
+import lombok.Data;
+import org.dromara.demo.domain.Xxx;
+import java.io.Serial;
+import java.io.Serializable;
+import java.util.Date;
+
+/**
+ * XXX 视图对象
+ */
+@Data
+@ExcelIgnoreUnannotated
+@AutoMapper(target = Xxx.class)
+public class XxxVo implements Serializable {
+
+    @Serial
+    private static final long serialVersionUID = 1L;
+
+    @ExcelProperty(value = "ID")
+    private Long id;
+
+    @ExcelProperty(value = "名称")
+    private String xxxName;
+
+    @ExcelProperty(value = "状态")
+    private String status;
+
+    @ExcelProperty(value = "创建时间")
+    private Date createTime;
+}
+```
+
+---
+
+### 4. Mapper 接口
+
+```java
+package org.dromara.demo.mapper;
+
+import org.dromara.common.mybatis.core.mapper.BaseMapperPlus;
+import org.dromara.demo.domain.Xxx;
+import org.dromara.demo.domain.vo.XxxVo;
+
+/**
+ * XXX Mapper 接口
+ */
+public interface XxxMapper extends BaseMapperPlus<Xxx, XxxVo> {
+    // ✅ 继承 BaseMapperPlus，已提供 selectVoById、selectVoPage 等方法
+}
+```
+
+**BaseMapperPlus 提供的方法**：
+
+| 方法 | 说明 |
+|------|------|
+| `selectVoById(id)` | 根据ID查询VO |
+| `selectVoList(wrapper)` | 查询VO列表 |
+| `selectVoPage(page, wrapper)` | 分页查询VO |
+| `selectByIds(ids)` | 批量查询Entity |
+| `deleteByIds(ids)` | 批量删除 |
+| `exists(wrapper)` | 判断是否存在 |
+
+---
+
+### 5. Service 接口
+
+```java
+package org.dromara.demo.service;
+
+import org.dromara.common.mybatis.core.page.PageQuery;
+import org.dromara.common.mybatis.core.page.TableDataInfo;
+import org.dromara.demo.domain.bo.XxxBo;
+import org.dromara.demo.domain.vo.XxxVo;
+import java.util.Collection;
+import java.util.List;
+
+/**
+ * XXX 服务接口
+ */
+public interface IXxxService {
+
+    XxxVo queryById(Long id);
+
+    TableDataInfo<XxxVo> queryPageList(XxxBo bo, PageQuery pageQuery);
+
+    List<XxxVo> queryList(XxxBo bo);
+
+    Boolean insertByBo(XxxBo bo);
+
+    Boolean updateByBo(XxxBo bo);
+
+    Boolean deleteByIds(Collection<Long> ids);
+}
+```
+
+---
+
+### 6. Service 实现类（⭐ 核心）
+
+```java
+package org.dromara.demo.service.impl;
+
+import com.baomidou.mybatisplus.core.conditions.query.LambdaQueryWrapper;
+import com.baomidou.mybatisplus.core.toolkit.Wrappers;
+import com.baomidou.mybatisplus.extension.plugins.pagination.Page;
+import lombok.RequiredArgsConstructor;
+import org.springframework.stereotype.Service;
+import org.dromara.common.core.exception.ServiceException;
+import org.dromara.common.core.utils.MapstructUtils;
+import org.dromara.common.core.utils.StringUtils;
+import org.dromara.common.mybatis.core.page.PageQuery;
+import org.dromara.common.mybatis.core.page.TableDataInfo;
+import org.dromara.demo.domain.Xxx;
+import org.dromara.demo.domain.bo.XxxBo;
+import org.dromara.demo.domain.vo.XxxVo;
+import org.dromara.demo.mapper.XxxMapper;
+import org.dromara.demo.service.IXxxService;
+import java.util.Collection;
+import java.util.List;
+import java.util.Map;
+
+/**
+ * XXX 服务实现
+ */
+@Service
+@RequiredArgsConstructor
+public class XxxServiceImpl implements IXxxService {  // ✅ 不继承任何基类
+
+    private final XxxMapper baseMapper;  // ✅ 直接注入 Mapper（无 DAO 层）
+
+    @Override
+    public XxxVo queryById(Long id) {
+        return baseMapper.selectVoById(id);
+    }
+
+    @Override
+    public TableDataInfo<XxxVo> queryPageList(XxxBo bo, PageQuery pageQuery) {
+        LambdaQueryWrapper<Xxx> lqw = buildQueryWrapper(bo);  // ✅ Service 层构建查询
+        Page<XxxVo> result = baseMapper.selectVoPage(pageQuery.build(), lqw);
+        return TableDataInfo.build(result);
+    }
+
+    @Override
+    public List<XxxVo> queryList(XxxBo bo) {
+        return baseMapper.selectVoList(buildQueryWrapper(bo));
+    }
+
+    @Override
+    public Boolean insertByBo(XxxBo bo) {
+        Xxx add = MapstructUtils.convert(bo, Xxx.class);  // ✅ MapstructUtils 转换
+        validEntityBeforeSave(add);
+        return baseMapper.insert(add) > 0;
+    }
+
+    @Override
+    public Boolean updateByBo(XxxBo bo) {
+        Xxx update = MapstructUtils.convert(bo, Xxx.class);
+        validEntityBeforeSave(update);
+        return baseMapper.updateById(update) > 0;
+    }
+
+    @Override
+    public Boolean deleteByIds(Collection<Long> ids) {
+        return baseMapper.deleteByIds(ids) > 0;
+    }
+
+    /**
+     * 构建查询条件
+     * ⭐ 在 Service 层构建（不是 DAO 层）
+     */
+    private LambdaQueryWrapper<Xxx> buildQueryWrapper(XxxBo bo) {
+        Map<String, Object> params = bo.getParams();
+        LambdaQueryWrapper<Xxx> lqw = Wrappers.lambdaQuery();
+
+        // 精确匹配
+        lqw.eq(bo.getId() != null, Xxx::getId, bo.getId());
+        lqw.eq(StringUtils.isNotBlank(bo.getStatus()), Xxx::getStatus, bo.getStatus());
+
+        // 模糊匹配
+        lqw.like(StringUtils.isNotBlank(bo.getXxxName()), Xxx::getXxxName, bo.getXxxName());
+
+        // 时间范围
+        lqw.between(params.get("beginCreateTime") != null && params.get("endCreateTime") != null,
+            Xxx::getCreateTime, params.get("beginCreateTime"), params.get("endCreateTime"));
+
+        // 排序
+        lqw.orderByDesc(Xxx::getCreateTime);
+        return lqw;
+    }
+
+    /**
+     * 保存前验证
+     */
+    private void validEntityBeforeSave(Xxx entity) {
+        // 业务校验，如唯一性检查
+        if (isNameExists(entity.getXxxName(), entity.getId())) {
+            throw new ServiceException("名称已存在");
+        }
+    }
+
+    private boolean isNameExists(String name, Long excludeId) {
+        return baseMapper.exists(Wrappers.<Xxx>lambdaQuery()
+            .eq(Xxx::getXxxName, name)
+            .ne(excludeId != null, Xxx::getId, excludeId));
+    }
+}
+```
+
+**关键点**：
+- ✅ **不继承任何基类**（`implements IXxxService`）
+- ✅ **直接注入 Mapper**（无 DAO 层）
+- ✅ **buildQueryWrapper() 在 Service 层**
+- ✅ 使用 `MapstructUtils.convert()` 转换对象
+
+---
+
+### 7. Controller 控制器
+
+```java
+package org.dromara.demo.controller;
+
+import cn.dev33.satoken.annotation.SaCheckPermission;
+import jakarta.servlet.http.HttpServletResponse;
+import jakarta.validation.constraints.*;
+import lombok.RequiredArgsConstructor;
+import org.dromara.common.core.domain.R;
+import org.dromara.common.core.validate.AddGroup;
+import org.dromara.common.core.validate.EditGroup;
+import org.dromara.common.excel.utils.ExcelUtil;
+import org.dromara.common.log.annotation.Log;
+import org.dromara.common.log.enums.BusinessType;
+import org.dromara.common.mybatis.core.page.PageQuery;
+import org.dromara.common.mybatis.core.page.TableDataInfo;
+import org.dromara.common.web.core.BaseController;
+import org.dromara.demo.domain.bo.XxxBo;
+import org.dromara.demo.domain.vo.XxxVo;
+import org.dromara.demo.service.IXxxService;
+import org.springframework.validation.annotation.Validated;
+import org.springframework.web.bind.annotation.*;
+import java.util.List;
+
+/**
+ * XXX 管理控制器
+ */
+@Validated
+@RequiredArgsConstructor
+@RestController
+@RequestMapping("/demo/xxx")
+public class XxxController extends BaseController {  // ✅ 继承 BaseController
+
+    private final IXxxService xxxService;
+
+    /**
+     * 查询列表
+     */
+    @SaCheckPermission("demo:xxx:list")
+    @GetMapping("/list")  // ✅ 标准路径
+    public TableDataInfo<XxxVo> list(XxxBo bo, PageQuery pageQuery) {
+        return xxxService.queryPageList(bo, pageQuery);
+    }
+
+    /**
+     * 获取详情
+     */
+    @SaCheckPermission("demo:xxx:query")
+    @GetMapping("/{id}")  // ✅ 标准路径
+    public R<XxxVo> getInfo(@NotNull(message = "ID不能为空") @PathVariable Long id) {
+        return R.ok(xxxService.queryById(id));
+    }
+
+    /**
+     * 新增
+     */
+    @SaCheckPermission("demo:xxx:add")
+    @Log(title = "XXX管理", businessType = BusinessType.INSERT)
+    @PostMapping  // ✅ 空路径
+    public R<Void> add(@Validated(AddGroup.class) @RequestBody XxxBo bo) {
+        return toAjax(xxxService.insertByBo(bo));
+    }
+
+    /**
+     * 修改
+     */
+    @SaCheckPermission("demo:xxx:edit")
+    @Log(title = "XXX管理", businessType = BusinessType.UPDATE)
+    @PutMapping  // ✅ 空路径
+    public R<Void> edit(@Validated(EditGroup.class) @RequestBody XxxBo bo) {
+        return toAjax(xxxService.updateByBo(bo));
+    }
+
+    /**
+     * 删除
+     */
+    @SaCheckPermission("demo:xxx:remove")
+    @Log(title = "XXX管理", businessType = BusinessType.DELETE)
+    @DeleteMapping("/{ids}")  // ✅ 标准路径
+    public R<Void> remove(@NotEmpty(message = "ID不能为空") @PathVariable Long[] ids) {
+        return toAjax(xxxService.deleteByIds(List.of(ids)));
+    }
+
+    /**
+     * 导出
+     */
+    @SaCheckPermission("demo:xxx:export")
+    @Log(title = "XXX管理", businessType = BusinessType.EXPORT)
+    @PostMapping("/export")
+    public void export(XxxBo bo, HttpServletResponse response) {
+        List<XxxVo> list = xxxService.queryList(bo);
+        ExcelUtil.exportExcel(list, "XXX数据", XxxVo.class, response);
+    }
+}
+```
+
+**API 路径规范**：
+
+| 操作 | HTTP方法 | 路径格式 |
+|------|---------|---------|
+| 分页查询 | GET | `/list` |
+| 获取详情 | GET | `/{id}` |
+| 新增 | POST | `/`（空） |
+| 修改 | PUT | `/`（空） |
+| 删除 | DELETE | `/{ids}` |
+| 导出 | POST | `/export` |
+
+---
+
+## 🔧 核心工具类
+
+### 对象转换（必须使用）
+
+```java
+import org.dromara.common.core.utils.MapstructUtils;
+
+// ✅ 单个对象转换
+XxxVo vo = MapstructUtils.convert(entity, XxxVo.class);
+Xxx entity = MapstructUtils.convert(bo, Xxx.class);
+
+// ✅ 集合转换
+List<XxxVo> voList = MapstructUtils.convert(entityList, XxxVo.class);
+
+// ❌ 禁止使用 BeanUtils
+// BeanUtils.copyProperties(source, target);  // 禁止！
+```
+
+### 字符串判空
+
+```java
+import org.dromara.common.core.utils.StringUtils;
+
+// 推荐使用
+StringUtils.isBlank(str);      // null / "" / 空白 都返回 true
+StringUtils.isNotBlank(str);
+StringUtils.isEmpty(str);      // null / "" 返回 true
+StringUtils.isNotEmpty(str);
+```
+
+### 业务异常
+
+```java
+import org.dromara.common.core.exception.ServiceException;
+
+// 抛出业务异常
+throw new ServiceException("用户不存在");
+throw new ServiceException("用户 {} 不存在", userId);
+```
+
+### 集合判空
+
+```java
+import cn.hutool.core.collection.CollUtil;
+
+CollUtil.isEmpty(list);
+CollUtil.isNotEmpty(list);
+```
+
+---
+
+## 📊 数据库规范
+
+### 建表模板
+
+```sql
+CREATE TABLE test_xxx (
+    -- 主键（雪花 ID，不用 AUTO_INCREMENT）
+    id              BIGINT(20)    NOT NULL COMMENT '主键ID',
+
+    -- 多租户字段（必须）
+    tenant_id       VARCHAR(20)   DEFAULT '000000' COMMENT '租户ID',
+
+    -- 业务字段
+    xxx_name        VARCHAR(100)  NOT NULL COMMENT '名称',
+    status          CHAR(1)       DEFAULT '1' COMMENT '状态(0停用 1正常)',
+
+    -- 审计字段（必须）
+    create_dept     BIGINT(20)    DEFAULT NULL COMMENT '创建部门',
+    create_by       BIGINT(20)    DEFAULT NULL COMMENT '创建人',
+    create_time     DATETIME      DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
+    update_by       BIGINT(20)    DEFAULT NULL COMMENT '更新人',
+    update_time     DATETIME      DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
+
+    -- 逻辑删除（必须）
+    del_flag        CHAR(1)       DEFAULT '0' COMMENT '删除标志(0正常 1已删除)',
+
+    PRIMARY KEY (id),
+    INDEX idx_tenant_id (tenant_id)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='XXX表';
+```
+
+### 模块与表前缀
+
+| 模块 | 表前缀 | 包路径 |
+|------|--------|--------|
+| system | `sys_` | `org.dromara.system` |
+| demo | `test_` | `org.dromara.demo` |
+| workflow | `flow_` | `org.dromara.workflow` |
+| 自定义 | 自定义 | `org.dromara.xxx` |
+
+---
+
+## ✅ 开发检查清单
+
+### 代码规范检查
+
+- [ ] **包名是否是 `org.dromara.*`**？
+- [ ] **Service 是否不继承任何基类**？
+- [ ] **Service 是否直接注入 Mapper（无 DAO 层）**？
+- [ ] **buildQueryWrapper() 是否在 Service 层**？
+- [ ] **Entity 是否继承 `TenantEntity`**？
+- [ ] **BO 是否使用 `@AutoMapper`（单数）**？
+- [ ] **是否使用 `MapstructUtils.convert()` 转换对象**？
+- [ ] **Mapper 是否继承 `BaseMapperPlus<Entity, VO>`**？
+- [ ] **Controller 是否继承 `BaseController`**？
+- [ ] **API 路径是否使用标准 RESTful 格式**？
+
+### 数据库检查
+
+- [ ] **主键是否使用雪花 ID（无 AUTO_INCREMENT）**？
+- [ ] **是否包含 `tenant_id` 字段**？
+- [ ] **是否包含审计字段**？
+- [ ] **是否包含 `del_flag` 逻辑删除字段**？
+
+---
+
+## ❌ 常见错误
+
+### 禁止的写法
+
+```java
+// ❌ 错误1: 错误的包名
+package com.ruoyi.xxx;      // 禁止！
+package plus.ruoyi.xxx;    // 禁止！
+// ✅ 正确: org.dromara.xxx
+
+// ❌ 错误2: 使用 DAO 层（本项目无 DAO 层）
+private final IXxxDao xxxDao;  // 禁止！
+// ✅ 正确: private final XxxMapper baseMapper;
+
+// ❌ 错误3: 使用 BeanUtils
+BeanUtil.copyProperties(bo, entity);  // 禁止！
+// ✅ 正确: MapstructUtils.convert(bo, Xxx.class);
+
+// ❌ 错误4: Service 继承基类
+public class XxxServiceImpl extends ServiceImpl<XxxMapper, Xxx> { }  // 禁止！
+// ✅ 正确: public class XxxServiceImpl implements IXxxService { }
+
+// ❌ 错误5: 使用 @AutoMappers（复数）
+@AutoMappers({@AutoMapper(target = Xxx.class)})  // 禁止！
+// ✅ 正确: @AutoMapper(target = Xxx.class)
+
+// ❌ 错误6: 使用 Map 传递业务数据
+public Map<String, Object> getXxx() { ... }  // 禁止！
+// ✅ 正确: public XxxVo getXxx() { ... }
+
+// ❌ 错误7: 使用完整类型引用
+public org.dromara.common.core.domain.R<XxxVo> getXxx()  // 禁止！
+// ✅ 正确: 先 import，再使用短类名
+import org.dromara.common.core.domain.R;
+public R<XxxVo> getXxx()
+
+// ❌ 错误8: 错误的 API 路径
+@GetMapping("/pageXxxs")     // 禁止！
+@GetMapping("/getXxx/{id}")  // 禁止！
+// ✅ 正确: @GetMapping("/list"), @GetMapping("/{id}")
+
+// ❌ 错误9: 使用自增 ID
+id BIGINT(20) AUTO_INCREMENT  // 禁止！
+// ✅ 正确: id BIGINT(20) NOT NULL（使用雪花ID）
+```
+
+---
+
+## 📚 参考实现
+
+查看项目中的标准实现：
+
+| 类型 | 参考文件 |
+|------|---------|
+| Entity | `org.dromara.demo.domain.TestDemo` |
+| BO | `org.dromara.demo.domain.bo.TestDemoBo` |
+| VO | `org.dromara.demo.domain.vo.TestDemoVo` |
+| Mapper | `org.dromara.demo.mapper.TestDemoMapper` |
+| Service | `org.dromara.demo.service.impl.TestDemoServiceImpl` |
+| Controller | `org.dromara.demo.controller.TestDemoController` |
+
+---
+
+## 🎯 总结
+
+**核心原则**：
+
+```
+1️⃣ 包名是 org.dromara.*
+2️⃣ 三层架构：Controller → Service → Mapper（无 DAO 层）
+3️⃣ Service 直接注入 Mapper
+4️⃣ buildQueryWrapper() 在 Service 层
+5️⃣ 使用 MapstructUtils.convert() 转换对象
+6️⃣ 主键使用雪花 ID
+7️⃣ RESTful API 路径规范
+```
+
+**开发流程**：
+
+```
+需求分析 → 数据库设计 → Entity → BO/VO → Mapper → Service → Controller → 测试
+```