# usmf-projects

**Repository Path**: hfddlu/usmf-projects

## Basic Information

- **Project Name**: usmf-projects
- **Description**: 通用saas微服务双网关系统
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-28
- **Last Updated**: 2026-07-28

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# USMF Projects

USMF 是一套面向多租户 SaaS 的微服务骨架项目，当前仓库同时包含后端平台和两个前端后台应用。

## 仓库定位

本仓库不是单一后端工程。它由三部分组成：

- `usmf-backend`：基于 Spring Boot 3.5.0 + JDK 25 的企业级多租户微服务骨架。
- `usmf-frontend-web/saas-web`：运营侧 SaaS 管理端，面向平台员工。
- `usmf-frontend-web/tenant-web`：租户端后台，面向租户内业务用户和管理员。

后端详细状态以 [usmf-backend/README.md](./usmf-backend/README.md) 为准；两个前端应用分别以各自目录下的 README 为准。

## 技术栈

### 后端

| 分类 | 技术选型 |
|------|----------|
| 语言 / 字节码目标 | Java 25 |
| 构建 / 运行 JDK | JDK 25+ |
| 框架 | Spring Boot 3.5.0, Spring Cloud 2025.0.0, Spring Cloud Alibaba 2025.0.0.0 |
| ORM | MyBatis-Flex |
| 安全 | Sa-Token, JJWT |
| 数据库 | MySQL 8.0+ |
| 缓存 | Redis 7.0+ |
| 注册中心 | Nacos 2.3+ |
| 消息队列 | RabbitMQ |
| 构建 | Maven 3.8+ |
| 架构守护 | ArchUnit |

后端 Maven 编译目标已统一为 Java 25 bytecode。根聚合 POM 位于 `usmf-backend/pom.xml`，当前递归包含 37 个 Maven project。

### 前端

| 应用 | 定位 | 技术栈 | 默认端口 |
|------|------|--------|----------|
| `saas-web` | 运营侧管理端 | Vue 3, Vite 8, TypeScript 6, Element Plus, Tailwind CSS, Pinia, Vue Router, Axios | `3311` |
| `tenant-web` | 租户端后台 | Vue 3, Vite 8, TypeScript 6, Element Plus, Tailwind CSS, Pinia, Vue Router, Axios | `3316` |

前端使用 Node.js 22+ 和 pnpm 10+。具体依赖版本以各前端应用的 `package.json` / lockfile 为准。

## 当前能力

### 后端已落地

- 多租户上下文、统一响应、持久层、Web 入口、安全、缓存、MQ、审计、Excel 等 starter。
- Contract 纯 DTO 契约层，服务间调用不把 HTTP `Result` 泄漏到 Feign 契约。
- 租户侧主链路：`usmf-tenant-gateway`、`usmf-tenant-iam`、`usmf-tenant-order`、`usmf-tenant-system`、`usmf-tenant-audit`。
- 运营侧主链路：`usmf-ops-gateway`、`usmf-ops-tenant`、`usmf-ops-iam`、`usmf-ops-system`、`usmf-ops-audit`。
- Tenant / Ops 身份域隔离、Gateway 本地验签、Redis 黑名单、权限版本检查、可信 Header 注入。
- PowerShell 本地进程脚本、Docker Compose 开发资产、轻量 HTTP smoke 脚本。

### 前端已落地

- 两个 Vite + Vue 3 + TypeScript 后台应用骨架。
- 登录态、菜单态、权限态、动态路由、侧边栏过滤和权限守卫。
- SaaS 管理端覆盖平台员工、角色、菜单、部门、岗位、租户、套餐、模板、审计、系统字典等页面样板。
- 租户端覆盖租户用户、角色、菜单、部门、岗位、订单、系统字典、审计、个人中心等页面样板。

### 待深化

- 前后端真实接口联调深度、异常反馈、复杂页面联动和性能验证。
- 完整微服务自动落地、正式 SQL 自动合入、CI/CD 工作流、完整 HTTP Collection、Helm/K8s、覆盖率阈值和 nightly IT。
- Docker Compose 已提供开发资产；是否完成实机启动验证以 `usmf-backend/README.md` 的最新说明为准。

## 快速开始

### 后端

```powershell
cd usmf-backend

# 构建并测试全部 Maven 模块
mvn test

# 初始化本地 MySQL schema
.\scripts\local\init-db.ps1

# 本地进程模式启动、验证、停止
.\scripts\local\start-all.ps1
.\scripts\local\verify-flow.ps1
.\scripts\local\verify-ops-flow.ps1
.\scripts\local\verify-http-smoke.ps1
.\scripts\local\stop-all.ps1 -WaitForPorts
```

Docker Compose 开发模式：

```powershell
cd usmf-backend
mvn -DskipTests package
docker compose up --build -d
docker compose ps
```

更多后端运行说明见 [usmf-backend/README.md](./usmf-backend/README.md) 和 [usmf-backend/deploy/compose/README.md](./usmf-backend/deploy/compose/README.md)。

### SaaS 管理端

```powershell
cd usmf-frontend-web/saas-web
pnpm install
pnpm dev
```

默认开发地址：`http://localhost:3311`。本地默认通过 Vite 同源代理访问运营侧网关 `http://localhost:8223`。

### 租户端

```powershell
cd usmf-frontend-web/tenant-web
pnpm install
pnpm dev
```

默认开发地址：`http://localhost:3316`。本地默认访问租户侧网关 `http://localhost:8220`。

## 创建模块或服务

新增业务模块或微服务时，优先使用后端内置的 create-service 工作流：

- 服务模型目录：[usmf-backend/docs/service-models](./usmf-backend/docs/service-models)
- 使用手册：[usmf-backend/docs/CREATE-SERVICE-MANUAL.md](./usmf-backend/docs/CREATE-SERVICE-MANUAL.md)
- 工具模块：[usmf-backend/usmf-tools/usmf-create-service](./usmf-backend/usmf-tools/usmf-create-service)

推荐流程是先编写需求文档，再映射服务模型 YAML，运行 `create-service --plan` 生成开发计划、任务清单和 SQL 参考草案；正式 Java / Vue / SQL 仍按项目规范和当前代码实现，并由人 review。

## 关键文档

- [后端总览](./usmf-backend/README.md)
- [后端架构设计](./usmf-backend/docs/ARCHITECTURE.md)
- [后端项目状态](./usmf-backend/docs/PROJECT-STATUS.md)
- [迭代计划](./usmf-backend/docs/ITERATION-PLAN.md)
- [SaaS 管理端 README](./usmf-frontend-web/saas-web/README.md)
- [租户端 README](./usmf-frontend-web/tenant-web/README.md)

## 目录结构

```text
.
├── usmf-backend/
│   ├── usmf-bom/              # 后端依赖版本管理
│   ├── usmf-starters/         # 后端核心 starter
│   ├── usmf-contracts/        # 服务间 API 契约
│   ├── usmf-tenant-side/      # 租户侧服务
│   ├── usmf-ops-side/         # 运营侧服务
│   ├── usmf-tools/            # create-service 等工具
│   ├── scripts/               # SQL 与本地运维脚本
│   ├── docs/                  # 架构、规范、状态和服务模型文档
│   └── docker-compose.yml     # 后端本地开发 Compose 资产
├── usmf-frontend-web/
│   ├── saas-web/              # 运营侧管理端前端
│   └── tenant-web/            # 租户端前端
├── README.md
├── README.en.md
└── LICENSE
```

## 贡献指南

- 后端改动遵守 `usmf-backend/docs/conventions/` 和 `usmf-backend/CLAUDE.md`。
- 前端改动遵守对应应用下的 `docs/conventions/`、`AGENTS.md` 和 `CLAUDE.md`。
- 后端提交前至少运行相关 Maven 测试；涉及架构边界的改动需补充或更新 ArchUnit 规则。
- 前端提交前至少运行对应应用的 `pnpm check`；如果 pnpm 提示需要清理或重建 `node_modules`，先停止并确认维护窗口。
- 含中文文件统一使用 UTF-8。

## 许可证

本项目基于 [LICENSE](./LICENSE) 开源协议。