From fca3326e34dd041224f842ad37251e92fdbc4a14 Mon Sep 17 00:00:00 2001 From: MengStack Dev Date: Sat, 3 Oct 2026 01:55:55 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E5=AE=98=E7=BD=91=E6=96=87=E6=A1=A3?= =?UTF-8?q?=E5=85=A8=E9=9D=A2=E6=9B=B4=E6=96=B0=20=E2=80=94=20M2-M8=20?= =?UTF-8?q?=E6=8C=87=E5=8D=97=20+=20API=20=E5=8F=82=E8=80=83=20+=20v0.2.0?= =?UTF-8?q?=20=E6=9B=B4=E6=96=B0=E6=97=A5=E5=BF=97?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 更新 changelog.md: v0.2.0 记录 M2-M8 全部完成，路线图更新 - 新增 5 篇指南: RBAC、组织管理、审计日志、通知模块、质量横切 - 新增 5 篇 API 文档: RBAC(11)、Org(5)、Audit(1)、Settings(7)、Notification(7) - 更新 api/overview.md: 完整 37 端点列表 - 更新 config.ts: 侧边栏分组 + 11 页 SEO 元数据 --- .vitepress/config.ts | 69 +++++++++++++- api/audit.md | 60 ++++++++++++ api/notification.md | 137 +++++++++++++++++++++++++++ api/org.md | 118 +++++++++++++++++++++++ api/overview.md | 79 ++++++++++++++-- api/rbac.md | 212 ++++++++++++++++++++++++++++++++++++++++++ api/settings.md | 118 +++++++++++++++++++++++ changelog.md | 100 +++++++++++++++----- guide/audit.md | 99 ++++++++++++++++++++ guide/notification.md | 119 ++++++++++++++++++++++++ guide/org.md | 92 ++++++++++++++++++ guide/quality.md | 145 +++++++++++++++++++++++++++++ guide/rbac.md | 101 ++++++++++++++++++++ 13 files changed, 1414 insertions(+), 35 deletions(-) create mode 100644 api/audit.md create mode 100644 api/notification.md create mode 100644 api/org.md create mode 100644 api/rbac.md create mode 100644 api/settings.md create mode 100644 guide/audit.md create mode 100644 guide/notification.md create mode 100644 guide/org.md create mode 100644 guide/quality.md create mode 100644 guide/rbac.md diff --git a/.vitepress/config.ts b/.vitepress/config.ts index 71b3c69..84d6818 100644 --- a/.vitepress/config.ts +++ b/.vitepress/config.ts @@ -28,8 +28,8 @@ const seoPages: Record全局>默认，完整API参考。', + keywords: '配置管理API,Go配置接口,运行时配置,MengStack接口文档', + }, + '/api/notification': { + title: '通知 API | 用户通知管理接口 - MengStack官方文档', + description: 'MengStack通知接口文档，包含通知创建、查询、标记已读、全部已读、未读计数、删除7个API端点，完整请求/响应示例。', + keywords: '通知API,Go通知接口,未读消息API,MengStack接口文档', + }, } function getPagePath(relativePath: string) { @@ -131,10 +181,20 @@ export default defineConfig({ text: '核心功能', items: [ { text: '认证与授权', link: '/guide/auth' }, + { text: 'RBAC 权限模型', link: '/guide/rbac' }, { text: '多租户系统', link: '/guide/multi-tenancy' }, + { text: '组织管理', link: '/guide/org' }, + { text: '审计日志', link: '/guide/audit' }, + { text: '通知模块', link: '/guide/notification' }, { text: '配置管理', link: '/guide/configuration' }, ], }, + { + text: '质量保障', + items: [ + { text: '安全基线与中间件', link: '/guide/quality' }, + ], + }, { text: '部署', items: [ @@ -149,6 +209,11 @@ export default defineConfig({ items: [ { text: '概览', link: '/api/overview' }, { text: '认证接口', link: '/api/auth' }, + { text: 'RBAC 接口', link: '/api/rbac' }, + { text: '组织管理接口', link: '/api/org' }, + { text: '审计日志接口', link: '/api/audit' }, + { text: '配置管理接口', link: '/api/settings' }, + { text: '通知接口', link: '/api/notification' }, { text: '系统接口', link: '/api/system' }, ], }, diff --git a/api/audit.md b/api/audit.md new file mode 100644 index 0000000..559e020 --- /dev/null +++ b/api/audit.md @@ -0,0 +1,60 @@ +--- +title: 审计日志 API | 操作审计查询接口 - MengStack官方文档 +--- + +# 审计日志接口 + +所有接口需要认证，并携带 `X-Tenant-ID` 头。 + +## 查询审计日志 + +**`GET /api/v1/audit/logs`** + +### 查询参数 + +| 参数 | 类型 | 必填 | 说明 | +|------|------|------|------| +| `user_id` | int | 否 | 按操作人 ID 筛选 | +| `action` | string | 否 | 按操作类型筛选（create / update / delete / login / assign） | +| `resource` | string | 否 | 按资源类型筛选（user / role / tenant / setting / auth） | +| `page` | int | 否 | 页码，默认 1 | +| `page_size` | int | 否 | 每页条数，默认 20 | + +### 响应 + +```json +{ + "code": 0, + "data": { + "items": [ + { + "id": 1, + "tenant_id": "550e8400-...", + "user_id": 1, + "action": "create", + "resource": "role", + "resource_id": "5", + "detail": "{\"name\":\"editor\"}", + "ip": "192.168.1.100", + "created_at": "2026-10-03T10:00:00+08:00" + } + ], + "total": 42, + "page": 1 + } +} +``` + +### 示例 + +```bash +# 查询所有删除操作 +curl "http://localhost:2222/api/v1/audit/logs?action=delete" \ + -H "Authorization: Bearer " \ + -H "X-Tenant-ID: " + +# 查询指定用户的日志 +curl "http://localhost:2222/api/v1/audit/logs?user_id=1&page_size=10" \ + -H "Authorization: Bearer " \ + -H "X-Tenant-ID: " +``` diff --git a/api/notification.md b/api/notification.md new file mode 100644 index 0000000..493664d --- /dev/null +++ b/api/notification.md @@ -0,0 +1,137 @@ +--- +title: 通知 API | 用户通知管理接口 - MengStack官方文档 +--- + +# 通知接口 + +所有接口需要认证，并携带 `X-Tenant-ID` 头。 + +## 创建通知 + +**`POST /api/v1/notifications`** + +### 请求体 + +```json +{ + "user_id": 1, + "title": "欢迎加入", + "content": "您的账号已成功创建。", + "type": "info" +} +``` + +| 字段 | 类型 | 必填 | 说明 | +|------|------|------|------| +| `user_id` | int | 是 | 接收用户 ID | +| `title` | string | 是 | 通知标题 | +| `content` | string | 否 | 通知内容 | +| `type` | string | 否 | 类型：info / success / warning / error，默认 info | + +### 响应 + +返回 `NotificationDTO`。 + +--- + +## 获取通知详情 + +**`GET /api/v1/notifications/:id`** + +### 路径参数 + +| 参数 | 类型 | 说明 | +|------|------|------| +| `id` | int | 通知 ID | + +--- + +## 获取用户通知列表 + +**`GET /api/v1/notifications/user/:userId`** + +### 路径参数 + +| 参数 | 类型 | 说明 | +|------|------|------| +| `userId` | int | 用户 ID | + +### 查询参数 + +| 参数 | 类型 | 必填 | 说明 | +|------|------|------|------| +| `page` | int | 否 | 页码，默认 1 | +| `page_size` | int | 否 | 每页条数，默认 20 | + +### 响应 + +```json +{ + "code": 0, + "data": { + "items": [ + { + "id": 1, + "tenant_id": "550e8400-...", + "user_id": 1, + "title": "欢迎加入", + "content": "您的账号已成功创建。", + "type": "info", + "is_read": false, + "created_at": "2026-10-03T10:00:00+08:00" + } + ], + "total": 15, + "page": 1 + } +} +``` + +--- + +## 标记通知已读 + +**`PUT /api/v1/notifications/:id/read`** + +### 路径参数 + +| 参数 | 类型 | 说明 | +|------|------|------| +| `id` | int | 通知 ID | + +--- + +## 全部标记已读 + +**`PUT /api/v1/notifications/read-all`** + +将当前用户（从 JWT 提取）的所有通知标记为已读。 + +--- + +## 获取未读数量 + +**`GET /api/v1/notifications/unread-count`** + +### 响应 + +```json +{ + "code": 0, + "data": { + "count": 5 + } +} +``` + +--- + +## 删除通知 + +**`DELETE /api/v1/notifications/:id`** + +### 路径参数 + +| 参数 | 类型 | 说明 | +|------|------|------| +| `id` | int | 通知 ID | diff --git a/api/org.md b/api/org.md new file mode 100644 index 0000000..84ce4b8 --- /dev/null +++ b/api/org.md @@ -0,0 +1,118 @@ +--- +title: 组织管理 API | 租户 CRUD 接口 - MengStack官方文档 +--- + +# 组织管理接口 + +所有接口需要认证。 + +## 创建租户 + +**`POST /api/v1/org/tenants`** + +### 请求体 + +```json +{ + "name": "示例科技有限公司", + "slug": "example-tech" +} +``` + +| 字段 | 类型 | 必填 | 约束 | +|------|------|------|------| +| `name` | string | 是 | 最长 128 字符 | +| `slug` | string | 是 | 最长 64 字符，唯一 | + +### 响应 + +```json +{ + "code": 0, + "data": { + "id": "550e8400-e29b-41d4-a716-446655440000", + "name": "示例科技有限公司", + "slug": "example-tech", + "status": 1, + "created_at": "2026-10-03T10:00:00+08:00", + "updated_at": "2026-10-03T10:00:00+08:00" + } +} +``` + +### 错误 + +| 状态码 | 说明 | +|--------|------| +| 400 | 参数校验失败 | +| 409 | slug 已存在 | + +--- + +## 列出所有租户 + +**`GET /api/v1/org/tenants`** + +### 响应 + +返回 `TenantDTO` 数组。 + +--- + +## 获取租户详情 + +**`GET /api/v1/org/tenants/:id`** + +### 路径参数 + +| 参数 | 类型 | 说明 | +|------|------|------| +| `id` | string | 租户 UUID | + +### 响应 + +返回 `TenantDTO`。 + +--- + +## 更新租户 + +**`PUT /api/v1/org/tenants/:id`** + +### 请求体 + +```json +{ + "name": "新名称", + "slug": "new-slug", + "status": 0 +} +``` + +| 字段 | 类型 | 必填 | 说明 | +|------|------|------|------| +| `name` | string | 否 | 新名称 | +| `slug` | string | 否 | 新 slug | +| `status` | int | 否 | 1=启用, 0=禁用 | + +--- + +## 删除租户 + +**`DELETE /api/v1/org/tenants/:id`** + +### 路径参数 + +| 参数 | 类型 | 说明 | +|------|------|------| +| `id` | string | 租户 UUID | + +### 响应 + +```json +{ + "code": 0, + "message": "success", + "data": null +} +``` diff --git a/api/overview.md b/api/overview.md index e51c820..a464e96 100644 --- a/api/overview.md +++ b/api/overview.md @@ -58,15 +58,78 @@ X-Tenant-ID: ## 接口列表 -| 模块 | 端点 | 说明 | +### 认证模块 + +| 方法 | 端点 | 说明 | |------|------|------| -| 认证 | `POST /auth/register` | 用户注册，详见[认证接口](/api/auth) | -| 认证 | `POST /auth/login` | 用户登录，详见[认证接口](/api/auth) | -| 认证 | `POST /auth/refresh` | 刷新令牌，详见[认证接口](/api/auth) | -| 认证 | `POST /password` | 修改密码，详见[认证接口](/api/auth) | -| 认证 | `GET /profile` | 获取当前用户，详见[认证接口](/api/auth) | -| 系统 | `GET /health` | 健康检查，详见[系统接口](/api/system) | -| 系统 | `GET /ping` | 连通性测试，详见[系统接口](/api/system) | +| POST | `/auth/register` | 用户注册，详见[认证接口](/api/auth) | +| POST | `/auth/login` | 用户登录，详见[认证接口](/api/auth) | +| POST | `/auth/refresh` | 刷新令牌，详见[认证接口](/api/auth) | +| POST | `/password` | 修改密码，详见[认证接口](/api/auth) | +| GET | `/profile` | 获取当前用户，详见[认证接口](/api/auth) | + +### RBAC 权限模块 + +| 方法 | 端点 | 说明 | +|------|------|------| +| GET | `/api/v1/rbac/permissions` | 列出权限，详见[RBAC 接口](/api/rbac) | +| POST | `/api/v1/rbac/roles` | 创建角色 | +| GET | `/api/v1/rbac/roles` | 列出角色 | +| GET | `/api/v1/rbac/roles/:id` | 获取角色详情 | +| PUT | `/api/v1/rbac/roles/:id` | 更新角色 | +| DELETE | `/api/v1/rbac/roles/:id` | 删除角色 | +| PUT | `/api/v1/rbac/roles/:id/permissions` | 设置角色权限 | +| GET | `/api/v1/rbac/roles/:id/permissions` | 获取角色权限 | +| POST | `/api/v1/rbac/users/:userId/roles` | 分配角色给用户 | +| DELETE | `/api/v1/rbac/users/:userId/roles/:roleId` | 移除用户角色 | +| GET | `/api/v1/rbac/users/:userId/roles` | 获取用户角色 | + +### 组织管理模块 + +| 方法 | 端点 | 说明 | +|------|------|------| +| POST | `/api/v1/org/tenants` | 创建租户，详见[组织管理接口](/api/org) | +| GET | `/api/v1/org/tenants` | 列出所有租户 | +| GET | `/api/v1/org/tenants/:id` | 获取租户详情 | +| PUT | `/api/v1/org/tenants/:id` | 更新租户 | +| DELETE | `/api/v1/org/tenants/:id` | 删除租户 | + +### 审计日志模块 + +| 方法 | 端点 | 说明 | +|------|------|------| +| GET | `/api/v1/audit/logs` | 查询审计日志，详见[审计日志接口](/api/audit) | + +### 配置管理模块 + +| 方法 | 端点 | 说明 | +|------|------|------| +| GET | `/api/v1/settings` | 列出全局配置，详见[配置管理接口](/api/settings) | +| GET | `/api/v1/settings/global/:key` | 获取全局配置 | +| PUT | `/api/v1/settings/global/:key` | 更新全局配置 | +| GET | `/api/v1/settings/tenant` | 列出租户配置 | +| GET | `/api/v1/settings/tenant/:key` | 获取租户配置 | +| PUT | `/api/v1/settings/tenant/:key` | 更新租户配置 | +| DELETE | `/api/v1/settings/tenant/:key` | 删除租户配置 | + +### 通知模块 + +| 方法 | 端点 | 说明 | +|------|------|------| +| POST | `/api/v1/notifications` | 创建通知，详见[通知接口](/api/notification) | +| GET | `/api/v1/notifications/:id` | 获取通知详情 | +| GET | `/api/v1/notifications/user/:userId` | 获取用户通知列表 | +| PUT | `/api/v1/notifications/:id/read` | 标记通知已读 | +| PUT | `/api/v1/notifications/read-all` | 全部标记已读 | +| GET | `/api/v1/notifications/unread-count` | 获取未读数量 | +| DELETE | `/api/v1/notifications/:id` | 删除通知 | + +### 系统模块 + +| 方法 | 端点 | 说明 | +|------|------|------| +| GET | `/health` | 健康检查，详见[系统接口](/api/system) | +| GET | `/ping` | 连通性测试，详见[系统接口](/api/system) | ## Swagger UI diff --git a/api/rbac.md b/api/rbac.md new file mode 100644 index 0000000..592d4ab --- /dev/null +++ b/api/rbac.md @@ -0,0 +1,212 @@ +--- +title: RBAC API | 角色权限管理接口 - MengStack官方文档 +--- + +# RBAC 接口 + +所有接口需要认证，并携带 `X-Tenant-ID` 头。 + +## 列出权限 + +**`GET /api/v1/rbac/permissions`** + +### 查询参数 + +| 参数 | 类型 | 必填 | 说明 | +|------|------|------|------| +| `module` | string | 否 | 按模块筛选 | + +### 响应 + +```json +{ + "code": 0, + "data": [ + { + "id": 1, + "code": "auth:user:read", + "name": "查看用户", + "module": "auth", + "description": "查看用户列表和详情" + } + ] +} +``` + +--- + +## 创建角色 + +**`POST /api/v1/rbac/roles`** + +### 请求体 + +```json +{ + "name": "editor", + "description": "内容编辑者" +} +``` + +| 字段 | 类型 | 必填 | +|------|------|------| +| `name` | string | 是 | +| `description` | string | 否 | + +### 响应 + +返回 `RoleDTO`（含 `permissions` 数组）。 + +### 错误 + +| 状态码 | 说明 | +|--------|------| +| 400 | 参数校验失败 | +| 409 | 角色名已存在 | + +--- + +## 列出角色 + +**`GET /api/v1/rbac/roles`** + +### 响应 + +```json +{ + "code": 0, + "data": [ + { + "id": 1, + "tenant_id": "550e8400-...", + "name": "admin", + "description": "系统管理员", + "is_system": true, + "permissions": [...] + } + ] +} +``` + +--- + +## 获取角色详情 + +**`GET /api/v1/rbac/roles/:id`** + +### 路径参数 + +| 参数 | 类型 | 说明 | +|------|------|------| +| `id` | int | 角色 ID | + +### 响应 + +返回 `RoleDTO`。 + +--- + +## 更新角色 + +**`PUT /api/v1/rbac/roles/:id`** + +### 请求体 + +```json +{ + "name": "senior-editoror", + "description": "高级编辑" +} +``` + +| 字段 | 类型 | 必填 | +|------|------|------| +| `name` | string | 否 | +| `description` | string | 否 | + +--- + +## 删除角色 + +**`DELETE /api/v1/rbac/roles/:id`** + +### 错误 + +| 状态码 | 说明 | +|--------|------| +| 403 | 系统角色不可删除 | + +--- + +## 设置角色权限 + +**`PUT /api/v1/rbac/roles/:id/permissions`** + +### 请求体 + +```json +{ + "permission_ids": [1, 2, 3, 5] +} +``` + +覆盖该角色的全部权限。 + +--- + +## 获取角色权限 + +**`GET /api/v1/rbac/roles/:id/permissions`** + +### 响应 + +返回 `PermissionDTO` 数组。 + +--- + +## 分配角色给用户 + +**`POST /api/v1/rbac/users/:userId/roles`** + +### 路径参数 + +| 参数 | 类型 | 说明 | +|------|------|------| +| `userId` | int | 用户 ID | + +### 请求体 + +```json +{ + "role_id": 2 +} +``` + +### 错误 + +| 状态码 | 说明 | +|--------|------| +| 409 | 用户已拥有该角色 | + +--- + +## 移除用户角色 + +**`DELETE /api/v1/rbac/users/:userId/roles/:roleId`** + +### 路径参数 + +| 参数 | 类型 | 说明 | +|------|------|------| +| `userId` | int | 用户 ID | +| `roleId` | int | 角色 ID | + +--- + +## 获取用户角色 + +**`GET /api/v1/rbac/users/:userId/roles`** + +### 响应 + +返回 `RoleDTO` 数组，包含该用户在此租户下的所有角色及权限。 diff --git a/api/settings.md b/api/settings.md new file mode 100644 index 0000000..66668c9 --- /dev/null +++ b/api/settings.md @@ -0,0 +1,118 @@ +--- +title: 配置管理 API | 全局与租户配置接口 - MengStack官方文档 +--- + +# 配置管理接口 + +配置分为两级：全局配置（所有租户共享）和租户配置（覆盖全局默认）。 + +所有接口需要认证，并携带 `X-Tenant-ID` 头。 + +## 全局配置 + +### 列出全局配置 + +**`GET /api/v1/settings`** + +#### 响应 + +```json +{ + "code": 0, + "data": [ + { + "id": 1, + "tenant_id": "", + "key": "site_name", + "value": "MengStack", + "type": "string", + "scope": "global", + "updated_by": 1, + "updated_at": "2026-10-03T10:00:00+08:00" + } + ] +} +``` + +### 获取全局配置 + +**`GET /api/v1/settings/global/:key`** + +#### 路径参数 + +| 参数 | 类型 | 说明 | +|------|------|------| +| `key` | string | 配置键名 | + +#### 响应 + +返回 `SettingDTO`。 + +### 更新全局配置 + +**`PUT /api/v1/settings/global/:key`** + +#### 请求体 + +```json +{ + "value": "新值", + "type": "string" +} +``` + +| 字段 | 类型 | 必填 | 说明 | +|------|------|------|------| +| `value` | string | 是 | 配置值 | +| `type` | string | 否 | 类型标记（string / number / boolean / json），默认 string | + +--- + +## 租户配置 + +### 列出租户配置 + +**`GET /api/v1/settings/tenant`** + +返回当前租户的所有配置项。 + +### 获取租户配置 + +**`GET /api/v1/settings/tenant/:key`** + +#### 路径参数 + +| 参数 | 类型 | 说明 | +|------|------|------| +| `key` | string | 配置键名 | + +### 更新租户配置 + +**`PUT /api/v1/settings/tenant/:key`** + +#### 请求体 + +```json +{ + "value": "租户级覆盖值", + "type": "string" +} +``` + +如果该 key 不存在，自动创建（upsert 语义）。 + +### 删除租户配置 + +**`DELETE /api/v1/settings/tenant/:key`** + +删除后，该租户将回退到全局默认值。 + +--- + +## 配置优先级 + +``` +租户配置 > 全局配置 > 默认值 +``` + +读取配置时，应用层按此优先级合并。 diff --git a/changelog.md b/changelog.md index 06bbd55..8d1370c 100644 --- a/changelog.md +++ b/changelog.md @@ -4,6 +4,68 @@ title: 更新日志 | 版本迭代记录与路线图 - MengStack开源框架 # 更新日志 +## v0.2.0 (2026-10-03) + +**全模块完成** — M2 至 M8 全部交付，框架能力齐备 + +### 新增 + +- **RBAC 权限模型 (M3)**： + - Permission / Role / UserRole 四表设计 + - 角色 CRUD + 权限批量绑定 + - 用户角色分配与移除 + - RBAC 中间件：基于权限码的接口级鉴权 + - 种子数据：预置 admin / editor / viewer 角色及基础权限 + +- **组织管理 (M4)**： + - 租户 CRUD（UUID 主键） + - 租户状态管理（启用 / 禁用） + +- **审计日志 (M4)**： + - 自动记录关键操作（用户、动作、资源、IP） + - 分页查询 + 多维筛选（用户 / 操作 / 资源类型） + +- **通知模块 (M6)**： + - 通知 CRUD + - 按用户分页查询 + - 单条 / 全部标记已读 + - 未读计数 + +- **配置管理增强 (M5)**： + - 运行时配置 API（全局 + 租户两级） + - 租户级配置覆盖全局默认 + - 配置类型标记（string / number / boolean / json） + +- **Docker + CI/CD (M7)**： + - 多阶段 Dockerfile（golang:1.23-alpine → alpine:3.20） + - .dockerignore 安全排除 + - Gitea Actions CI 流水线（lint → vet → test → build） + - docker-compose.yml 增加 restart 策略 + - Makefile 增加 docker-build 目标 + +- **质量横切 (M8)**： + - IP 限流中间件（100 次/分钟，内存 + 自动清理） + - 安全响应头（X-Content-Type-Options、X-Frame-Options、X-XSS-Protection、Referrer-Policy、CSP） + - 请求体大小限制（10MB） + - Zap 结构化请求日志（status / method / path / latency / trace_id） + - 自定义 Recovery 中间件（panic 捕获 + Zap 记录） + - 优雅停机（10 秒超时） + - 测试工具包（testutil）+ 11 个中间件单元测试 + - PostgreSQL DSN 增加 TimeZone=Asia/Shanghai + +- **Swagger 全量注解**： + - 37 个 handler 方法全部添加 godoc 注解 + - 6 个模块 API 文档自动生成 + +### 技术栈（新增依赖） + +| 组件 | 版本 | 说明 | +|------|------|------| +| swaggo/swag | latest | Swagger 注解解析 | +| gin-swagger | latest | Swagger UI 中间件 | + +--- + ## v0.1.0 (2026-10-02) **初始版本** — 项目骨架 + 认证模块 @@ -16,7 +78,7 @@ title: 更新日志 | 版本迭代记录与路线图 - MengStack开源框架 - **配置管理**：Viper 分层配置，支持 YAML + 环境变量覆盖 - **结构化日志**：Zap 结构化输出，请求级 trace_id - **多租户支持**：基于 X-Tenant-ID 的租户隔离中间件 -- **认证模块**： +- **认证模块 (M2)**： - 用户注册（邮箱 + 用户名 + 密码） - 用户登录（邮箱 + 密码） - JWT 双 Token 机制（Access + Refresh） @@ -48,34 +110,22 @@ title: 更新日志 | 版本迭代记录与路线图 - MengStack开源框架 ## 路线图 -### v0.2.0 — RBAC 权限模型 +### v0.3.0 — 插件接口预留 -- Role / Permission 数据模型 -- 用户角色分配 -- RBAC 中间件 -- 权限校验装饰器 +- Plugin 生命周期接口定义 +- 插件注册 / 发现机制 +- 示例插件（日志增强 / 自定义鉴权） -### v0.3.0 — 组织管理 + 审计日志 +### v0.4.0 — 客户端前台 (Nuxt 3) -- 组织 CRUD -- 用户-组织关系 -- 操作审计日志 - -### v0.4.0 — 配置管理增强 - -- 运行时配置 API -- 全局默认 + 租户覆盖 -- 配置变更历史 - -### v0.5.0 — 用户示例模块 - -- 完整用户 CRUD -- 单元测试 + 集成测试 -- 示例代码 +- 14 页演示站 UI（首页、登录、注册、Dashboard、通知中心等） +- API 对接层（Pinia + composables） +- 暗色模式 + 响应式适配 ### v1.0.0 — 正式发布 -- 完整测试覆盖 -- 安全审计 +- 完整测试覆盖（单元 + 集成 > 80%） +- 安全审计（OWASP Top 10 检查） - 性能基准测试 -- 生产部署文档 +- 生产部署文档完善 +- 插件生态首批社区贡献 diff --git a/guide/audit.md b/guide/audit.md new file mode 100644 index 0000000..011549a --- /dev/null +++ b/guide/audit.md @@ -0,0 +1,99 @@ +--- +title: 审计日志 | 操作追踪与合规记录 - MengStack官方文档 +--- + +# 审计日志 + +审计日志模块自动记录系统中的关键操作，支持多维筛选和分页查询，满足合规审计需求。 + +## 数据模型 + +```go +type AuditLog struct { + ID uint // 自增主键 + TenantID string // 租户 ID + UserID uint // 操作人 ID + Action string // 操作类型（create / update / delete / login 等） + Resource string // 资源类型（user / role / tenant 等） + ResourceID string // 资源 ID + Detail string // 操作详情（JSON 格式） + IP string // 操作人 IP 地址 + CreatedAt time.Time // 操作时间 +} +``` + +## 记录时机 + +审计日志在以下场景自动写入： + +| 场景 | Action | Resource | +|------|--------|----------| +| 用户注册 | `create` | `user` | +| 用户登录 | `login` | `auth` | +| 修改密码 | `update` | `user` | +| 创建角色 | `create` | `role` | +| 删除角色 | `delete` | `role` | +| 分配角色 | `assign` | `user_role` | +| 创建租户 | `create` | `tenant` | +| 修改配置 | `update` | `setting` | + +## 查询方式 + +支持按用户、操作类型、资源类型筛选，并支持分页： + +```bash +# 查询所有审计日志 +curl http://localhost:2222/api/v1/audit/logs \ + -H "Authorization: Bearer " \ + -H "X-Tenant-ID: " + +# 按用户筛选 +curl "http://localhost:2222/api/v1/audit/logs?user_id=1" \ + -H "Authorization: Bearer " \ + -H "X-Tenant-ID: " + +# 按操作类型筛选 + 分页 +curl "http://localhost:2222/api/v1/audit/logs?action=delete&page=1&page_size=10" \ + -H "Authorization: Bearer " \ + -H "X-Tenant-ID: " +``` + +## 响应格式 + +```json +{ + "code": 0, + "message": "success", + "data": { + "items": [ + { + "id": 1, + "tenant_id": "550e8400-...", + "user_id": 1, + "action": "create", + "resource": "role", + "resource_id": "5", + "detail": "{\"name\":\"editor\"}", + "ip": "192.168.1.100", + "created_at": "2026-10-03T10:00:00+08:00" + } + ], + "total": 42, + "page": 1 + } +} +``` + +## 安全特性 + +- 审计日志按 `tenant_id` 严格隔离，租户只能查看自己的日志 +- 日志记录不可修改、不可删除（只写不删） +- IP 地址从请求上下文中自动提取 + +## API 端点 + +| 方法 | 路径 | 说明 | +|------|------|------| +| GET | `/api/v1/audit/logs` | 分页查询审计日志 | + +详细接口参数见 [审计日志 API 参考](/api/audit)。 diff --git a/guide/notification.md b/guide/notification.md new file mode 100644 index 0000000..f277ca8 --- /dev/null +++ b/guide/notification.md @@ -0,0 +1,119 @@ +--- +title: 通知模块 | 用户通知的发送与管理 - MengStack官方文档 +--- + +# 通知模块 + +通知模块提供用户级别的消息推送和管理能力，支持多种通知类型和已读状态管理。 + +## 数据模型 + +```go +type Notification struct { + ID uint // 自增主键 + TenantID string // 租户 ID + UserID uint // 接收用户 ID + Title string // 通知标题 + Content string // 通知内容 + Type string // 通知类型（info / warning / error / success） + IsRead bool // 是否已读 + CreatedAt time.Time + UpdatedAt time.Time +} +``` + +## 通知类型 + +| 类型 | 用途 | 建议样式 | +|------|------|----------| +| `info` | 一般信息通知 | 蓝色图标 | +| `success` | 操作成功通知 | 绿色图标 | +| `warning` | 警告通知 | 黄色图标 | +| `error` | 错误通知 | 红色图标 | + +## 核心能力 + +| 能力 | 说明 | +|------|------| +| 发送通知 | 向指定用户创建通知 | +| 查询通知 | 按用户分页查询通知列表 | +| 标记已读 | 单条或全部标记为已读 | +| 未读计数 | 获取用户未读通知数量 | +| 删除通知 | 删除指定通知 | + +## 使用方式 + +### 发送通知 + +```bash +curl -X POST http://localhost:2222/api/v1/notifications \ + -H "Authorization: Bearer " \ + -H "X-Tenant-ID: " \ + -H "Content-Type: application/json" \ + -d '{ + "user_id": 1, + "title": "欢迎加入", + "content": "您的账号已成功创建，请完善个人资料。", + "type": "info" + }' +``` + +### 获取用户通知列表 + +```bash +curl "http://localhost:2222/api/v1/notifications/user/1?page=1&page_size=20" \ + -H "Authorization: Bearer " \ + -H "X-Tenant-ID: " +``` + +### 获取未读数量 + +```bash +curl http://localhost:2222/api/v1/notifications/unread-count \ + -H "Authorization: Bearer " \ + -H "X-Tenant-ID: " +``` + +响应： + +```json +{ + "code": 0, + "message": "success", + "data": { + "count": 5 + } +} +``` + +### 全部标记已读 + +```bash +curl -X PUT http://localhost:2222/api/v1/notifications/read-all \ + -H "Authorization: Bearer " \ + -H "X-Tenant-ID: " +``` + +## 扩展方向 + +当前通知模块为基础版本，后续可扩展： + +- WebSocket 实时推送 +- 通知模板引擎 +- 邮件 / 短信多渠道通知 +- 通知分组与标签 +- 定时通知与批量发送 + +## API 端点 + +| 方法 | 路径 | 说明 | +|------|------|------| +| POST | `/api/v1/notifications` | 创建通知 | +| GET | `/api/v1/notifications/:id` | 获取通知详情 | +| GET | `/api/v1/notifications/user/:userId` | 获取用户通知列表 | +| PUT | `/api/v1/notifications/:id/read` | 标记通知已读 | +| PUT | `/api/v1/notifications/read-all` | 全部标记已读 | +| GET | `/api/v1/notifications/unread-count` | 获取未读数量 | +| DELETE | `/api/v1/notifications/:id` | 删除通知 | + +详细接口参数见 [通知 API 参考](/api/notification)。 diff --git a/guide/org.md b/guide/org.md new file mode 100644 index 0000000..27fe29c --- /dev/null +++ b/guide/org.md @@ -0,0 +1,92 @@ +--- +title: 组织管理 | 多租户 CRUD 与状态管理 - MengStack官方文档 +--- + +# 组织管理 + +组织管理模块提供租户（Tenant）的完整生命周期管理，是多租户系统的基础。 + +## 数据模型 + +```go +type Tenant struct { + ID string // UUID 主键 + Name string // 组织名称 + Slug string // 唯一标识符（用于 URL 友好展示） + Status int // 1=启用, 0=禁用 + Settings string // JSON 扩展配置 + CreatedAt time.Time + UpdatedAt time.Time +} +``` + +## 核心能力 + +| 能力 | 说明 | +|------|------| +| 创建租户 | 自动生成 UUID，需提供 name 和 slug | +| 查询租户 | 支持列表查询和单条详情查询 | +| 更新租户 | 可修改名称、slug、状态 | +| 删除租户 | 级联清理关联数据 | +| 状态管理 | 启用 / 禁用租户，禁用后该租户用户无法登录 | + +## 使用方式 + +### 创建租户 + +```bash +curl -X POST http://localhost:2222/api/v1/org/tenants \ + -H "Authorization: Bearer " \ + -H "Content-Type: application/json" \ + -d '{ + "name": "示例科技有限公司", + "slug": "example-tech" + }' +``` + +响应： + +```json +{ + "code": 0, + "message": "success", + "data": { + "id": "550e8400-e29b-41d4-a716-446655440000", + "name": "示例科技有限公司", + "slug": "example-tech", + "status": 1, + "created_at": "2026-10-03T10:00:00+08:00", + "updated_at": "2026-10-03T10:00:00+08:00" + } +} +``` + +### 禁用租户 + +```bash +curl -X PUT http://localhost:2222/api/v1/org/tenants/550e8400-e29b-41d4-a716-446655440000 \ + -H "Authorization: Bearer " \ + -H "Content-Type: application/json" \ + -d '{"status": 0}' +``` + +## 与多租户中间件的关系 + +组织管理模块负责租户数据的 CRUD，而多租户中间件（`X-Tenant-ID` header）负责在请求级别隔离数据。两者配合实现完整的多租户能力： + +1. 通过 **组织管理 API** 创建租户 +2. 用户登录时通过 **X-Tenant-ID** 指定所属租户 +3. 中间件自动验证租户状态并注入上下文 +4. 后续所有数据库操作自动按 `tenant_id` 过滤 + +## API 端点 + +| 方法 | 路径 | 说明 | +|------|------|------| +| POST | `/api/v1/org/tenants` | 创建租户 | +| GET | `/api/v1/org/tenants` | 列出所有租户 | +| GET | `/api/v1/org/tenants/:id` | 获取租户详情 | +| PUT | `/api/v1/org/tenants/:id` | 更新租户 | +| DELETE | `/api/v1/org/tenants/:id` | 删除租户 | + +详细接口参数见 [组织管理 API 参考](/api/org)。 diff --git a/guide/quality.md b/guide/quality.md new file mode 100644 index 0000000..35a6ea4 --- /dev/null +++ b/guide/quality.md @@ -0,0 +1,145 @@ +--- +title: 质量横切 | 安全基线、限流、日志与优雅停机 - MengStack官方文档 +--- + +# 质量横切 + +M8 为框架添加了生产级质量基线，覆盖安全、限流、日志、容错和测试基础设施。 + +## 中间件链 + +所有请求经过以下中间件链（按顺序）： + +``` +RequestID → RequestLogger → SecurityHeaders → CORS → RateLimit → BodyLimit → Recovery +``` + +## IP 限流 + +基于内存的 IP 限流中间件，自动清理过期记录： + +```go +// 每个 IP 每分钟最多 100 次请求 +r.Use(middleware.RateLimit(100, time.Minute)) +``` + +| 特性 | 说明 | +|------|------| +| 限流维度 | 客户端 IP | +| 存储方式 | 内存 map + sync.Mutex | +| 自动清理 | 后台 goroutine 每分钟清理过期记录 | +| 超限响应 | HTTP 429 + `RATE_LIMITED` 错误码 | + +::: warning +内存限流适合单机部署。多实例部署建议替换为 Redis 限流。 +::: + +## 安全响应头 + +自动为所有响应添加安全头： + +| Header | 值 | 作用 | +|--------|------|------| +| `X-Content-Type-Options` | `nosniff` | 防止 MIME 类型嗅探 | +| `X-Frame-Options` | `DENY` | 防止点击劫持 | +| `X-XSS-Protection` | `1; mode=block` | 浏览器 XSS 过滤 | +| `Referrer-Policy` | `strict-origin-when-cross-origin` | 控制 Referer 泄露 | +| `Content-Security-Policy` | `default-src 'self'` | 限制资源加载来源 | + +## 请求体限制 + +限制请求体最大为 10MB，防止大文件攻击： + +```go +r.Use(middleware.BodyLimit(10 << 20)) // 10 MB +``` + +- 先检查 `Content-Length` header，超限直接返回 413 +- 再通过 `http.MaxBytesReader` 限制实际读取大小 + +## 结构化请求日志 + +使用 Zap 替代 fmt，输出结构化 JSON 日志： + +```json +{ + "level": "info", + "msg": "request", + "status": 200, + "method": "GET", + "path": "/api/v1/profile", + "query": "", + "ip": "192.168.1.100", + "user-agent": "Mozilla/5.0", + "latency_ms": 12, + "trace_id": "req-abc-123" +} +``` + +日志级别按状态码自动选择： + +| 状态码范围 | 日志级别 | +|-----------|---------| +| < 400 | INFO | +| 400-499 | WARN | +| >= 500 | ERROR | + +## 自定义 Recovery + +替代 `gin.Recovery()`，panic 信息通过 Zap 记录而非 stdout： + +```go +r.Use(middleware.Recovery(log)) +``` + +记录的字段：panic 内容、stack trace、请求方法、路径、trace_id。 + +## 优雅停机 + +应用收到终止信号后，等待最多 10 秒处理完进行中的请求： + +```go +// app.go +OnStop: func(ctx context.Context) error { + shutdownCtx, cancel := context.WithTimeout(context.Background(), 10*time.Second) + defer cancel() + return srv.Shutdown(shutdownCtx) +} +``` + +## 测试基础设施 + +### testutil 包 + +```go +import "mengstack/internal/kernel/testutil" + +func TestSomething(t *testing.T) { + log := testutil.TestLogger(t) // 测试专用 Zap logger + cfg := testutil.TestConfig() // 最小化测试配置 +} +``` + +### 中间件测试 + +内置 11 个单元测试覆盖所有中间件： + +```bash +go test ./internal/app/middleware/ -v +``` + +| 测试 | 覆盖场景 | +|------|----------| +| TestRequestID_GeneratesNew | 无 trace_id 时自动生成 | +| TestRequestID_PreservesExisting | 已有 trace_id 时保留 | +| TestSecurityHeaders | 5 个安全头全部设置 | +| TestRateLimit_AllowsWithinLimit | 限额内请求正常通过 | +| TestRateLimit_BlocksOverLimit | 超限额返回 429 | +| TestRequestLogger_DoesNotPanic | 日志中间件不 panic | +| TestRecovery_HandlesPanic | 捕获 panic 并记录 | +| TestBodyLimit_RejectsLargeBody | 超大 body 返回 413 | +| TestBodyLimit_AllowsSmallBody | 正常 body 通过 | + +## 数据库时区 + +PostgreSQL DSN 默认携带 `TimeZone=Asia/Shanghai`，确保时间字段按中国时区存储和返回。 diff --git a/guide/rbac.md b/guide/rbac.md new file mode 100644 index 0000000..21de977 --- /dev/null +++ b/guide/rbac.md @@ -0,0 +1,101 @@ +--- +title: RBAC 权限模型 | 角色权限管理与中间件鉴权 - MengStack官方文档 +--- + +# RBAC 权限模型 + +MengStack 内置基于角色的访问控制（RBAC）模块，支持多租户隔离下的权限管理。 + +## 数据模型 + +RBAC 由 4 张核心表组成： + +| 表 | 说明 | 关键字段 | +|------|------|----------| +| `permissions` | 权限定义 | code（唯一码）、name、module | +| `roles` | 角色定义 | tenant_id、name、is_system | +| `role_permissions` | 角色-权限关联（多对多） | role_id、permission_id | +| `user_roles` | 用户-角色关联 | user_id、tenant_id、role_id | + +``` +Permission ←→ Role ←→ User + (M:N) (M:N) +``` + +## 权限码规范 + +权限码采用 `模块:资源:动作` 三段式命名： + +``` +auth:user:read # 查看用户 +auth:user:write # 编辑用户 +rbac:role:manage # 管理角色 +org:tenant:manage # 管理租户 +notification:send # 发送通知 +``` + +## 种子数据 + +框架启动时自动创建预置角色和权限： + +| 角色 | 说明 | 权限范围 | +|------|------|----------| +| `admin` | 管理员（系统角色，不可删除） | 全部权限 | +| `editor` | 编辑者 | 内容读写 + 通知 | +| `viewer` | 查看者 | 只读权限 | + +## 使用方式 + +### 1. 给用户分配角色 + +```bash +curl -X POST http://localhost:2222/api/v1/rbac/users/1/roles \ + -H "Authorization: Bearer " \ + -H "X-Tenant-ID: " \ + -H "Content-Type: application/json" \ + -d '{"role_id": 1}' +``` + +### 2. 为角色设置权限 + +```bash +curl -X PUT http://localhost:2222/api/v1/rbac/roles/1/permissions \ + -H "Authorization: Bearer " \ + -H "X-Tenant-ID: " \ + -H "Content-Type: application/json" \ + -d '{"permission_ids": [1, 2, 3]}' +``` + +### 3. 在路由中使用权限中间件 + +```go +// 在 routes.go 中 +rbac.GET("/users", h.ListUsers, permMW.Require("auth:user:read")) +rbac.POST("/users", h.CreateUser, permMW.Require("auth:user:write")) +``` + +`permMW.Require()` 会从 JWT 中提取用户 ID 和租户 ID，查询该用户在此租户下的所有角色权限并集，判断是否包含所需权限码。 + +## 多租户隔离 + +- 角色按 `tenant_id` 隔离，不同租户的角色互不影响 +- 用户角色关联也按 `tenant_id` 隔离，同一用户在不同租户可拥有不同角色 +- 权限定义是全局共享的（不区分租户） + +## API 端点 + +| 方法 | 路径 | 说明 | +|------|------|------| +| GET | `/api/v1/rbac/permissions` | 列出权限（可按 module 筛选） | +| POST | `/api/v1/rbac/roles` | 创建角色 | +| GET | `/api/v1/rbac/roles` | 列出角色 | +| GET | `/api/v1/rbac/roles/:id` | 获取角色详情 | +| PUT | `/api/v1/rbac/roles/:id` | 更新角色 | +| DELETE | `/api/v1/rbac/roles/:id` | 删除角色 | +| PUT | `/api/v1/rbac/roles/:id/permissions` | 设置角色权限 | +| GET | `/api/v1/rbac/roles/:id/permissions` | 获取角色权限 | +| POST | `/api/v1/rbac/users/:userId/roles` | 分配角色给用户 | +| DELETE | `/api/v1/rbac/users/:userId/roles/:roleId` | 移除用户角色 | +| GET | `/api/v1/rbac/users/:userId/roles` | 获取用户角色 | + +详细接口参数见 [RBAC API 参考](/api/rbac)。