ai-engineering-init 1.1.0

package/.claude/docs//346/226/260/351/241/271/347/233/256/345/274/200/345/217/221/346/265/201/347/250/213.md

@@ -0,0 +1,365 @@
+# 新项目开发流程指南
+
+> 基于 RuoYi-Vue-Plus 框架的标准开发流程
+> **注意**：本项目是纯后端项目，前端项目独立维护。
+
+最后更新: 2026-02-09
+
+---
+
+## 🎯 核心理念
+
+### 框架 ≠ 业务
+
+| 类型 | 说明 | 是否统计进度 |
+|------|------|------------|
+| **框架代码** | 系统管理、代码生成器、通用工具库等 | ❌ 不统计（已完成） |
+| **业务代码** | 你要开发的项目功能模块 | ✅ 只统计业务 |
+
+**关键点**：
+- 框架代码是**固定的**、**已完成的**，不需要重复扫描
+- 进度统计**只看业务模块**，不看框架
+- 全新项目进度是 **0%**，不是 100%
+
+---
+
+## 📁 项目结构速览
+
+### 后端结构
+
+```
+RuoYi-Vue-Plus/
+├── ruoyi-admin/               # 启动入口（配置文件）
+├── ruoyi-common/              # 通用工具库（24个子模块）
+│   ├── ruoyi-common-core/     # 核心工具（MapstructUtils, StringUtils）
+│   ├── ruoyi-common-mybatis/  # MyBatis-Plus 扩展
+│   ├── ruoyi-common-redis/    # Redis 缓存
+│   ├── ruoyi-common-satoken/  # 权限认证
+│   └── ...                    # 其他模块
+└── ruoyi-modules/             # 业务功能模块
+    ├── ruoyi-system/          ❌ 框架（系统管理）
+    ├── ruoyi-generator/       ❌ 框架（代码生成器）
+    ├── ruoyi-demo/            ⚠️ 演示模块（可参考）
+    ├── ruoyi-job/             ❌ 框架（定时任务）
+    ├── ruoyi-workflow/        ❌ 框架（工作流）
+    └── ruoyi-{你的业务}/      ✅ 创建你的业务模块
+```
+
+### 业务模块标准结构（三层架构）
+
+```
+ruoyi-modules/ruoyi-mall/src/main/java/org/dromara/mall/
+├── 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              # 视图对象
+```
+
+**关键点**：
+- 包名必须是 `org.dromara.*`（禁止使用 `com.ruoyi.*` 或 `plus.ruoyi.*`）
+- 三层架构：Controller → Service → Mapper（**无 DAO 层**）
+- Service 直接注入 Mapper，`buildQueryWrapper()` 在 Service 实现类中
+
+---
+
+## 🚀 标准开发流程
+
+### 阶段 1: 项目初始化（第一次使用）
+
+#### 1.1 克隆或创建项目
+
+```bash
+git clone <your-project-url>
+cd RuoYi-Vue-Plus
+```
+
+#### 1.2 查看项目状态
+
+```bash
+/start
+```
+
+**预期输出**（全新项目）：
+```
+👋 欢迎使用 RuoYi-Vue-Plus 框架
+
+🎯 这是一个全新项目
+
+框架状态: ✅ 已就绪
+业务模块: ⏳ 尚未开发（检测到 0 个业务模块）
+
+快速开始:
+- 查看框架说明: .claude/docs/框架说明.md
+- 开始开发: /dev 或 /crud
+```
+
+#### 1.3 了解框架（可选）
+
+查看 `.claude/docs/框架说明.md` 了解：
+- 哪些是框架模块（已完成）
+- 哪些是业务开发区域（需要开发）
+- 进度统计规则
+
+---
+
+### 阶段 2: 开发第一个业务功能
+
+#### 方式 1: 使用 /dev 命令（推荐）
+
+```bash
+/dev
+```
+
+**Claude 会引导你**：
+1. 需求分析
+2. 数据库设计
+3. 后端代码生成（Entity、BO、VO、Service、Mapper、Controller）
+4. 测试和优化
+
+#### 方式 2: 使用 /crud 命令（快速）
+
+```bash
+/crud
+```
+
+快速生成标准 CRUD 功能。
+
+#### 方式 3: 使用代码生成器
+
+**步骤**：
+1. 设计数据库表
+2. 访问代码生成器页面（系统工具 → 代码生成）
+3. 导入表
+4. 配置生成选项：
+   - 模块名：如 `mall`
+   - 包路径：`org.dromara.mall`（必须是 org.dromara 开头）
+   - 业务名：如 `goods`（商品）
+   - 表前缀：如 `m_`
+5. 一键生成代码
+
+**生成内容**：
+- Entity、BO、VO
+- Controller、Service、Mapper
+- 菜单 SQL
+
+---
+
+### 阶段 3: 查看进度
+
+#### 3.1 查看详细进度
+
+```bash
+/progress
+```
+
+**输出示例**：
+```
+📊 项目进度报告
+
+后端模块（按 Maven 模块统计）
+
+🔹 ruoyi-mall（已实现 2 个功能）
+1. ✅ 商品管理 - Goods
+   - 完整度: 100%
+2. 🚧 订单管理 - Order
+   - 完整度: 75%
+   - 缺失: OrderVo.java
+
+框架状态: ✅ 稳定（不统计进度）
+业务进度: 35%
+```
+
+#### 3.2 查看下一步建议
+
+```bash
+/next
+```
+
+---
+
+### 阶段 4: 持续开发循环
+
+```
+/start → 查看今天的状态
+   ↓
+/next → 获取开发建议
+   ↓
+/dev 或 /crud → 开发新功能
+   ↓
+/check → 代码规范检查
+   ↓
+git commit → 提交代码
+   ↓
+返回 /start（新的一天）
+```
+
+---
+
+## 📋 常用命令速查
+
+| 命令 | 用途 | 使用场景 |
+|------|------|---------|
+| `/start` | 查看项目状态 | 每天开始工作时 |
+| `/dev` | 开发新功能 | 需要完整引导的功能开发 |
+| `/crud` | 快速生成CRUD | 标准增删改查功能 |
+| `/progress` | 查看详细进度 | 了解业务模块完成情况 |
+| `/next` | 获取开发建议 | 不知道下一步做什么时 |
+| `/check` | 代码规范检查 | 提交前检查代码质量 |
+
+---
+
+## 💡 最佳实践
+
+### 1. 模块命名规范
+
+**后端模块**：
+| 业务领域 | 模块目录 | 包路径 | 表前缀 |
+|---------|---------|--------|--------|
+| 商城 | `ruoyi-modules/ruoyi-mall/` | `org.dromara.mall` | `m_` |
+| 物联网 | `ruoyi-modules/ruoyi-iot/` | `org.dromara.iot` | `iot_` |
+| 客户管理 | `ruoyi-modules/ruoyi-crm/` | `org.dromara.crm` | `crm_` |
+| 自定义 | `ruoyi-modules/ruoyi-xxx/` | `org.dromara.xxx` | `xxx_` |
+
+### 2. 不要修改框架代码
+
+**禁止修改**：
+- `ruoyi-common/*` - 通用工具
+- `ruoyi-admin` - 启动入口
+- `ruoyi-modules/ruoyi-system` - 系统管理
+- `ruoyi-modules/ruoyi-generator` - 代码生成器
+- `ruoyi-modules/ruoyi-job` - 定时任务
+- `ruoyi-modules/ruoyi-workflow` - 工作流
+
+**原因**：
+- 框架升级时会有冲突
+- 影响项目的一致性
+
+**如需扩展**：
+- 继承框架类并重写
+- 在业务模块中封装
+- 通过配置文件调整
+
+### 3. 遵循三层架构
+
+```
+Controller → Service → Mapper（无 DAO 层）
+```
+
+**关键点**：
+- Service 实现类不继承任何基类
+- `buildQueryWrapper()` 方法在 Service 实现类中
+- 使用 `MapstructUtils.convert()` 进行对象转换（禁止 BeanUtils）
+
+### 4. 合理使用代码生成器
+
+**适合使用代码生成器**：
+- 标准的 CRUD 功能
+- 单表、树表、主子表
+- 快速原型开发
+
+**不适合使用代码生成器**：
+- 复杂的业务逻辑
+- 需要自定义的查询
+- 特殊的数据处理
+
+**生成后要做的**：
+- 检查生成的代码
+- 补充业务逻辑
+- 优化查询性能
+
+---
+
+## 🤔 常见问题
+
+### Q1: 为什么执行 /progress 显示 0%？
+
+**答**：因为你还没有开发任何业务模块。框架模块不参与进度统计。
+当你创建第一个业务模块后，进度就会开始统计。
+
+### Q2: 我可以在 ruoyi-system 中添加功能吗？
+
+**不建议**。ruoyi-system 是系统管理模块，属于框架。
+- 如果是通用的系统功能，考虑添加
+- 如果是业务相关的功能，应该放到业务模块
+
+### Q3: 包名必须是 org.dromara 吗？
+
+**是的**。本项目统一使用 `org.dromara.*` 包名。
+
+```java
+// ✅ 正确
+package org.dromara.mall.controller;
+
+// ❌ 错误
+package com.ruoyi.mall.controller;
+package plus.ruoyi.mall.controller;
+```
+
+### Q4: 为什么项目没有 DAO 层？
+
+本项目采用三层架构：Controller → Service → Mapper
+- Service 直接注入 Mapper
+- `buildQueryWrapper()` 方法在 Service 实现类中
+- 更简洁、更少的样板代码
+
+### Q5: 如何判断哪些代码是框架、哪些是业务？
+
+**框架模块**（不要修改）：
+- `ruoyi-common/*` - 通用工具库
+- `ruoyi-admin` - 启动入口
+- `ruoyi-modules/ruoyi-system` - 系统管理
+- `ruoyi-modules/ruoyi-generator` - 代码生成器
+- `ruoyi-modules/ruoyi-demo` - 演示模块
+- `ruoyi-modules/ruoyi-job` - 定时任务
+- `ruoyi-modules/ruoyi-workflow` - 工作流
+
+**业务模块**（你要开发的）：
+- `ruoyi-modules/ruoyi-{你的业务}/` - 自定义业务模块
+
+---
+
+## 📚 相关文档
+
+| 文档 | 位置 | 说明 |
+|------|------|------|
+| 框架说明 | `.claude/docs/框架说明.md` | 框架模块清单、业务开发区域 |
+| 开发规范 | `CLAUDE.md` | 完整的开发规范和架构 |
+| 技能库 | `.claude/skills/` | 各功能开发指南 |
+
+---
+
+## 🎯 总结
+
+### 记住 3 个核心点
+
+1. **框架 ≠ 业务**
+   - 框架代码已完成，不参与进度统计
+   - 只统计你开发的业务模块
+
+2. **全新项目进度是 0%**
+   - 不是 100%（那是框架完成度）
+   - 开发业务功能后进度才会增长
+
+3. **遵循三层架构**
+   - Controller → Service → Mapper（无 DAO 层）
+   - 包名必须是 `org.dromara.*`
+
+### 开发流程总结
+
+```
+克隆项目 → /start 查看状态 → /dev 开发业务功能 → /check 检查代码 → git commit 提交代码
+```
+
+### 下一步
+
+执行 `/start` 开始你的第一个业务功能开发！