# mm-cloud

**Repository Path**: meirui/mm-cloud

## Basic Information

- **Project Name**: mm-cloud
- **Description**: 最后一舞
- **Primary Language**: Java
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2024-11-09
- **Last Updated**: 2026-05-02

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# CLAUDE.md

本文件为 Claude Code 提供项目上下文和编码规范指引。

## 项目概述

mm-cloud 是一个基于 Spring Cloud 的租赁管理微服务平台，Java 17，Spring Boot 3.1.7。

## 构建与运行

```bash
# 全量构建
mvn clean package

# 构建单个模块
mvn clean package -pl mm-modules/mm-sys
mvn clean package -pl mm-modules/mm-lease
mvn clean package -pl mm-gateway

# 跳过测试构建
mvn clean package -DskipTests
```

运行前需启动：Nacos(8848)、MySQL(3306)、Redis(6379)、RabbitMQ(5672)。

服务端口：Gateway 8009、mm-sys 9000。

API 文档：http://localhost:9000/doc.html (Knife4j)

## 模块结构

```
mm-cloud
├── mm-common/                  # 公共模块
│   ├── mm-common-core/         # 基础类、枚举、异常、Result 封装
│   ├── mm-common-redis/        # Redis + Redisson 缓存层
│   ├── mm-common-security/     # 认证鉴权（自定义 @PreAuthorize）
│   └── mm-common-mq/          # RabbitMQ 消息队列（MqProducer / AbstractMqConsumer）
├── mm-gateway/                 # Spring Cloud Gateway（路由、CORS）
├── mm-modules/                 # 业务服务
│   ├── mm-sys/                 # 系统管理服务（用户、角色、权限、字典）
│   └── mm-lease/               # 租赁业务服务（房东 landlord、租客 tenant 子域）
├── mm-feign-api/               # Feign 远程调用接口
│   └── mm-feign-sys-api/
├── mcp-code-generator/         # MCP 代码生成服务（TypeScript/Node.js）
└── mm-app/                     # 前端应用（Vue 3 + Element Plus）
```

## 架构与规范

### 分层架构

Controller → ApplicationService → Service → Mapper → Database

- Controller：接收请求，调用 ApplicationService，返回 `Result<T>`
- ApplicationService：业务编排层，组合多个 Service 完成复杂业务
- Service：单一领域的业务逻辑
- Mapper：MyBatis-Plus 数据访问，XML 文件在 `src/main/resources/mapper/`

### 编码规范

- Entity 继承 `BaseEntity`（id, createTime, updateTime, createrId, updaterId, isDelete）
- 主键策略：`IdType.AUTO`（数据库自增）
- 逻辑删除字段：`is_delete`（0-未删除 1-删除 2-回收站删除）
- 时间类型统一使用 `LocalDateTime`
- DTO 分为 query（查询）、form（表单提交），VO 用于返回展示
- Controller 使用 `@AllArgsConstructor` 构造器注入
- API 注解：`@Tag(name=)` + `@Operation(summary=)` (OpenAPI 3 / Knife4j)
- 权限控制：自定义 `@PreAuthorize(hasAuthorize = "ROLE_XXX")`
- 所有接口统一返回 `Result<T>` 包装

### 网关路由

- `/sys-api/**` → mm-sys 服务（StripPrefix=1）
- `/lease-api/**` → mm-lease 服务（StripPrefix=1）
- 白名单：`/sys-api/login`, `/sys-api/logout`

### mm-lease 领域结构

mm-lease 按业务子域划分包结构：
- `landlord/` — 房东相关（房源、房间、支出）
- `tenant/` — 租客相关（租客、收入、押金）

每个子域内部同样遵循 controller → application → service → mapper 分层。

### MQ 消息队列

涉及 RabbitMQ 消息队列相关业务时，必须遵循 `.claude/skills/mq.md` 中的规范执行。

核心架构：
- 队列定义：枚举实现 `MqQueue` 接口，放在业务模块 `core/mq/` 包下，配合 `MqQueueProvider` 注册
- 发送消息：注入 `MqProducer`，调用 `mqProducer.send(SysQueue.XXX, payload)`
- 消费消息：继承 `AbstractMqConsumer<T>`，实现 `getPayloadType()` + `handle()` + `@RabbitListener` 的 `onMessage()`
- 队列/交换机/绑定由 `QueueRegistrar` 启动时自动声明，不要手动创建
- 统一消息模型 `MqMessage<T>`，内置幂等（Redis SETNX）、追踪（traceId）、泛型类型转换
- 重试机制使用 Spring Retry 配置，不要手动 nack 重入队

禁止使用已删除的旧类：`IMqService`、`RabbitMessage`、`CustomMessage`、`ExchangeEnum`、`RoutingKeyEnum`、`QueueEnum`、`QueueConstants`

## 技术栈

| 组件 | 版本 |
|------|------|
| Spring Boot | 3.1.7 |
| Spring Cloud | 2022.0.4 |
| Spring Cloud Alibaba | 2022.0.0.0 |
| MyBatis-Plus | 3.5.12 |
| Nacos | 服务发现 + 配置中心 |
| Druid | 1.2.25 |
| Redisson | 3.29.0 |
| Knife4j | 4.4.0 |
| Seata | 2.0.0（分布式事务） |
| Hutool | 5.8.20 |
| Lombok | 1.18.22 |

## MCP 代码生成器

`mcp-code-generator/` 是一个 MCP (Model Context Protocol) 服务，用于数据库建表和 Java 代码生成。

### 安装与运行

```bash
cd mcp-code-generator
npm install
npm run build
npm start        # 运行编译后的服务
npm run dev      # 编译 + 运行
```

### MCP 工具

| 工具 | 用途 |
|------|------|
| `execute_sql` | 在 mm_sys 或 mm_lease 库执行 SQL（DDL） |
| `generate_entity` | 根据表结构生成 Entity 类 |
| `generate_mapper` | 生成 Mapper 接口 + XML |
| `generate_service` | 生成 Service 接口 + 实现类 |
| `generate_full_code` | 一键生成完整代码（Entity/Mapper/Service/ApplicationService/Controller/DTO/VO） |

### 建表规范

每张表必须包含以下基础字段：
- `id` BIGINT PRIMARY KEY AUTO_INCREMENT
- `company_id` BIGINT（多租户隔离）
- `create_time` DATETIME
- `update_time` DATETIME
- `creater_id` BIGINT
- `updater_id` BIGINT
- `is_delete` TINYINT DEFAULT 0

### 数据库连接

- mm_sys: `127.0.0.1:3306/mm_sys` (root/root)
- mm_lease: `127.0.0.1:3306/mm_lease` (root/root)

### 类型映射

varchar/char/text → String, int → Integer, bigint → Long, tinyint → Byte, decimal → BigDecimal, datetime → LocalDateTime, date → LocalDate

## mm-app（前端）

`mm-app/` 是基于 Vue 3 + TypeScript + Element Plus 的管理后台前端。

### 技术栈

- Vue 3.4 + TypeScript 5.3
- Vite 5 构建
- Element Plus 2.5 组件库
- Pinia 状态管理
- Vue Router 动态路由（根据用户权限从后端加载）
- Axios HTTP 客户端
- Sass 预处理器

### 开发命令

```bash
cd mm-app
npm install
npm run dev       # 开发服务器 http://localhost:3000
npm run build     # 类型检查 + 生产构建
npm run preview   # 预览生产构建
```

### API 代理配置

开发环境通过 Vite 代理转发请求到 Gateway（8009）：
- `/sys-api` → `http://localhost:8009`
- `/lease-api` → `http://localhost:8009`

### 前端目录结构

```
src/
├── api/           # API 服务层（按业务模块拆分：auth, user, role, tenant...）
├── stores/        # Pinia 状态（auth, dialog, tabs）
├── views/         # 页面组件（system/, lease/）
├── components/    # 可复用组件（表单、分页等）
├── layouts/       # 布局组件（MainLayout）
├── router/        # 路由配置 + 守卫
├── composables/   # 组合式函数（useTablePagination）
├── utils/         # 工具函数（request, auth, route）
└── styles/        # 全局样式
```