# MengStack Core

[![Go](https://img.shields.io/badge/Go-1.23+-00ADD8?logo=go)](https://go.dev)
[![PostgreSQL](https://img.shields.io/badge/PostgreSQL-16+-336791?logo=postgresql)](https://www.postgresql.org)
[![Redis](https://img.shields.io/badge/Redis-7+-DC382D?logo=redis)](https://redis.io)
[![License](https://img.shields.io/badge/License-Apache--2.0-blue)](LICENSE)

MengStack（软盟开发框架）是一个面向多租户 SaaS 应用的 Go 通用底座。把账号、权限、租户、组织、审计、配置、消息、插件等所有 Web 应用共享的能力一次性做好，让你只专注于业务逻辑。

## 为什么选择 MengStack

- **多租户内建** — 共享表 + `tenant_id` 显式过滤，可选 Schema 隔离与 PG 行级安全（RLS）兜底
- **插件架构** — 通过扩展点和 `.mengplugin` 包格式扩展功能，不改动内核代码
- **四层分层** — domain → application → infrastructure → interfaces，职责清晰、可测试
- **编译期依赖注入** — 基于 Uber fx，依赖错误在编译时暴露，不是运行时
- **安全默认** — JWT 双 Token、RBAC 权限、bcrypt 密码、参数化查询、XSS 过滤、三级限流
- **可观测性** — Zap 结构化日志（含 trace_id / tenant_id）、健康检查、就绪探针

## 快速开始

### 前置条件

- Go 1.23+
- PostgreSQL 16+
- Redis 7+

### 1. 克隆项目

```bash
git clone https://mengstackgit.softunis.com/softunis/mengstack-api.git
cd mengstack-api
```

### 2. 配置环境

```bash
cp .env.example .env
# 编辑 .env，填入数据库密码和 JWT 密钥
```

### 3. 启动依赖服务

```bash
docker-compose up -d postgres redis
```

### 4. 启动服务

```bash
# 安装依赖
go mod download

# 运行迁移 + 启动
make run
```

服务启动后：

| 端点 | 地址 |
|------|------|
| API | `http://localhost:2222` |
| 健康检查 | `http://localhost:2222/health` |
| 就绪探针 | `http://localhost:2222/readyz` |
| Swagger 文档 | `http://localhost:2222/swagger/index.html` |

### 或者用 Docker 一键启动

```bash
cp .env.example .env
docker-compose up -d
docker-compose logs -f api
```

## 项目结构

```
.
├── cmd/
│   ├── server/          # 主服务入口
│   ├── migrate/         # 数据库迁移工具
│   └── smrm/            # CLI 脚手架工具
├── internal/
│   ├── app/             # 应用基础设施
│   │   ├── cache/       #   Redis 连接
│   │   ├── database/    #   PostgreSQL 连接
│   │   ├── health/      #   健康检查 & 就绪探针
│   │   ├── middleware/  #   请求 ID、认证、多租户、i18n
│   │   ├── migrate/     #   迁移执行器
│   │   └── upgrade/     #   在线升级预留
│   ├── config/          # Viper 配置加载
│   ├── kernel/          # ★ 内核（开源部分）
│   │   ├── errors/      #   统一错误码
│   │   ├── response/    #   统一响应格式
│   │   ├── tenant/      #   多租户抽象
│   │   ├── model/       #   公共基础实体
│   │   ├── plugin/      #   插件接口 & 沙箱
│   │   ├── eventbus/    #   事件总线
│   │   ├── storage/     #   存储抽象
│   │   ├── cache/       #   缓存工具
│   │   ├── jobs/        #   后台任务调度
│   │   ├── i18n/        #   国际化框架
│   │   └── websocket/   #   WebSocket 推送
│   ├── logger/          # Zap 结构化日志
│   └── modules/         # 业务模块
│       ├── auth/        #   认证（注册/登录/刷新）
│       ├── rbac/        #   角色权限
│       ├── org/         #   组织架构
│       ├── audit/       #   审计日志
│       ├── settings/    #   配置管理
│       ├── notification/#   消息通知
│       └── example/     #   示例插件
├── migrations/          # 核心数据库迁移脚本
├── configs/             # 分层配置模板
├── docs/                # Swagger 生成文档
├── test/                # 测试工具
├── AGENTS.md            # AI 辅助开发规范
└── Makefile             # 常用命令
```

## 核心能力

### 多租户

```go
// 请求头传入租户 ID
// X-Tenant-ID: tenant-abc-123

// 框架自动解析并注入上下文
tenantID := tenant.FromContext(c.Request.Context())
```

支持三种隔离策略，通过配置切换：
- **共享表 + tenant_id**（默认，适合大多数场景）
- **Schema 隔离**（高安全需求）
- **独立数据库**（企业级隔离）

### 插件系统

每个插件是一个独立的模块，声明所需权限，运行时由沙箱强制执行：

```go
func (p *MyPlugin) Permissions() plugin.Permissions {
    return plugin.Permissions{
        Database: []string{"my_table"},     // 只能访问声明的表
        Events:   []string{"order.created"}, // 只能发射声明的事件
        Routes:   []string{"/api/v1/orders/*"},
    }
}
```

插件 panic 不会影响主进程 — 沙箱通过 `recover` 隔离故障。

创建新插件：

```bash
go run ./cmd/smrm new module order
```

### 统一响应

```json
{
  "code": 0,
  "message": "success",
  "data": { ... },
  "trace_id": "abc-123"
}
```

错误码体系：业务错误返回具体码 + 国际化消息，5xx 统一返回"服务器内部错误"，原文只进日志。

### 配置分层

优先级从低到高：

1. `configs/config.yaml` — 基础默认值
2. `configs/config.{mode}.yaml` — 环境覆盖（dev / prod）
3. `MENGSTACK_` 环境变量 — 最高优先级

```bash
MENGSTACK_DATABASE_PASSWORD=secret
MENGSTACK_JWT_SECRET=your-jwt-key
```

## 开发规范

### 四层分层

| 层 | 文件 | 职责 | 禁止 |
|----|------|------|------|
| Domain | `model.go` | 实体、领域接口 | import gorm/http/redis |
| Application | `service.go` | 用例编排、事务 | 直接操作数据库 |
| Infrastructure | `repo.go` | 数据库/缓存实现 | 含业务逻辑 |
| Interfaces | `handler.go` | 参数校验、调 service | 写业务逻辑 |

### 十条铁律

1. 内核绝不装业务语义（无 article / order / goods）
2. 依赖只能由外向内（domain 层零外部依赖）
3. 跨模块只走接口（禁止直接 import 其他模块的 repo）
4. 依赖方向单调：modules → kernel，禁止反向
5. tenantID 显式传递（禁止 context 隐式透传）
6. 统一响应格式与错误码
7. 所有数据库变更走迁移脚本
8. 禁止 SELECT *、禁止字符串拼接 SQL
9. 品牌写法统一：MengStack + 软盟开发框架
10. 插件只能通过扩展点接入，内核不依赖任何插件

### 规范自检

```bash
# 检查内核纯净性（禁止业务语义泄漏）
go run ./cmd/smrm check
```

## 常用命令

```bash
make build        # 编译
make run          # 启动开发服务
make test         # 运行测试
make test-cover   # 测试覆盖率
make lint         # 代码检查
make swagger      # 重新生成 Swagger 文档
make migrate      # 运行数据库迁移
make docker-up    # Docker 启动全部服务
make docker-down  # Docker 停止所有服务
```

## 演示站

- API：https://mengstackdemo.softunis.com
- Swagger：https://mengstackdemo.softunis.com/swagger/index.html

## 技术栈

| 组件 | 选型 | 说明 |
|------|------|------|
| 语言 | Go 1.23+ | 编译为单文件，部署极简 |
| Web 框架 | Gin | 高性能 HTTP 路由 |
| ORM | GORM v2 | PostgreSQL 数据访问 |
| 数据库 | PostgreSQL 16 | 多租户原生 + 许可可闭源 |
| 缓存 | Redis 7 | 会话 / 缓存 / 队列 |
| 依赖注入 | Uber fx | 编译期装配，生命周期管理 |
| 配置 | Viper | 分层配置 + 环境变量 |
| 日志 | Zap | 结构化高性能日志 |
| 认证 | JWT | Access + Refresh 双 Token |
| 迁移 | golang-migrate | 版本化数据库变更 |
| API 文档 | Swag | 注解自动生成 Swagger |

## 许可证

[Apache License 2.0](LICENSE)

Copyright 2026 SoftUnis（软盟）