feat: 完成 NestJS 后端核心底座开发 (M1-M6) 和 Ant Design Vue 前端迁移
主要更新： 1. 后端核心底座完成 (M1-M6)： - 健康检查、指标监控、分布式锁 - 事件总线、队列系统、事务管理 - 安全守卫、多租户隔离、存储适配器 - 审计日志、配置管理、多语言支持 2. 前端迁移到 Ant Design Vue： - 从 Element Plus 迁移到 Ant Design Vue - 完善 system 模块 (role/menu/dept) - 修复依赖和配置问题 3. 文档完善： - AI 开发工作流文档 - 架构约束和开发规范 - 项目进度跟踪 4. 其他改进： - 修复编译错误和类型问题 - 完善测试用例 - 优化项目结构
This commit is contained in:
万物街
@@ -35,7 +35,7 @@ export const shared = defineConfig({
|
||||
srcDir: 'src',
|
||||
themeConfig: {
|
||||
i18nRouting: true,
|
||||
logo: 'https://unpkg.com/@vbenjs/static-source@0.1.7/source/logo-v1.webp',
|
||||
logo: 'https://t.wanwujie.cn/img/1/2025/08/24/68aacf5d544a4.webp',
|
||||
search: {
|
||||
options: {
|
||||
locales: {
|
||||
@@ -44,12 +44,12 @@ export const shared = defineConfig({
|
||||
},
|
||||
provider: 'local',
|
||||
},
|
||||
siteTitle: 'Vben Admin',
|
||||
siteTitle: 'WWJCloud',
|
||||
socialLinks: [
|
||||
{ icon: 'github', link: 'https://github.com/vbenjs/vue-vben-admin' },
|
||||
],
|
||||
},
|
||||
title: 'Vben Admin',
|
||||
title: 'WWJCloud Admin',
|
||||
vite: {
|
||||
build: {
|
||||
chunkSizeWarningLimit: Infinity,
|
||||
|
||||
@@ -5,7 +5,7 @@ import { defineConfig } from 'vitepress';
|
||||
import { version } from '../../../package.json';
|
||||
|
||||
export const zh = defineConfig({
|
||||
description: 'Vben Admin & 企业级管理系统框架',
|
||||
description: 'WWJCloud & 企业级管理系统框架',
|
||||
lang: 'zh-Hans',
|
||||
themeConfig: {
|
||||
darkModeSwitchLabel: '主题',
|
||||
@@ -20,7 +20,7 @@ export const zh = defineConfig({
|
||||
text: '在 GitHub 上编辑此页面',
|
||||
},
|
||||
footer: {
|
||||
copyright: `Copyright © 2020-${new Date().getFullYear()} Vben`,
|
||||
copyright: `Copyright © 2024-${new Date().getFullYear()} WWJCloud`,
|
||||
message: '基于 MIT 许可发布.',
|
||||
},
|
||||
langMenuLabel: '多语言',
|
||||
@@ -42,7 +42,8 @@ export const zh = defineConfig({
|
||||
sidebar: {
|
||||
'/commercial/': { base: '/commercial/', items: sidebarCommercial() },
|
||||
'/components/': { base: '/components/', items: sidebarComponents() },
|
||||
'/guide/': { base: '/guide/', items: sidebarGuide() },
|
||||
'/vben/guide/': { base: '/vben/guide/', items: sidebarGuide() },
|
||||
'/wwjcloud/': { base: '/wwjcloud/', items: sidebarWwjcloud() },
|
||||
},
|
||||
sidebarMenuLabel: '菜单',
|
||||
},
|
||||
@@ -201,16 +202,23 @@ function sidebarComponents(): DefaultTheme.SidebarItem[] {
|
||||
];
|
||||
}
|
||||
|
||||
|
||||
|
||||
function nav(): DefaultTheme.NavItem[] {
|
||||
return [
|
||||
{
|
||||
activeMatch: '^/(guide|components)/',
|
||||
activeMatch: '^/(vben/guide|components|wwjcloud)/',
|
||||
text: '文档',
|
||||
items: [
|
||||
{
|
||||
activeMatch: '^/guide/',
|
||||
link: '/guide/introduction/vben',
|
||||
text: '指南',
|
||||
activeMatch: '^/wwjcloud/',
|
||||
link: '/wwjcloud/',
|
||||
text: 'WWJCloud',
|
||||
},
|
||||
{
|
||||
activeMatch: '^/vben/guide/',
|
||||
link: '/vben/guide/introduction/vben',
|
||||
text: 'Vben Admin',
|
||||
},
|
||||
{
|
||||
activeMatch: '^/components/',
|
||||
@@ -313,6 +321,66 @@ function nav(): DefaultTheme.NavItem[] {
|
||||
];
|
||||
}
|
||||
|
||||
function sidebarWwjcloud(): DefaultTheme.SidebarItem[] {
|
||||
return [
|
||||
{
|
||||
text: '快速开始',
|
||||
items: [
|
||||
{ link: '/', text: '框架概览' },
|
||||
{ link: 'guide/introduction', text: '框架介绍' },
|
||||
{ link: 'guide/quick-start', text: '快速开始' },
|
||||
{ link: 'guide/concepts', text: '基础概念' },
|
||||
],
|
||||
},
|
||||
{
|
||||
text: '核心架构',
|
||||
items: [
|
||||
{ link: 'structure/overview', text: '整体架构' },
|
||||
{ link: 'architecture/constraints', text: '架构约束' },
|
||||
{ link: 'gateway/index', text: '网关系统' },
|
||||
],
|
||||
},
|
||||
{
|
||||
text: 'API 规范',
|
||||
items: [
|
||||
{ link: 'openapi/standards/restful', text: 'RESTful API 设计' },
|
||||
{ link: 'openapi/standards/response', text: '响应格式规范' },
|
||||
{ link: 'openapi/standards/error-codes', text: '错误码规范' },
|
||||
],
|
||||
},
|
||||
{
|
||||
text: 'API 文档',
|
||||
items: [
|
||||
{ link: 'openapi/api/index', text: 'API 总览' },
|
||||
{
|
||||
text: '前台 API',
|
||||
items: [
|
||||
{ link: 'openapi/api/frontend/index', text: '前台 API 概览' },
|
||||
],
|
||||
},
|
||||
{
|
||||
text: '后台 API',
|
||||
items: [
|
||||
{ link: 'openapi/api/adminapi/index', text: '后台 API 概览' },
|
||||
],
|
||||
},
|
||||
],
|
||||
},
|
||||
{
|
||||
text: '发展规划',
|
||||
items: [
|
||||
{ link: 'project/roadmap', text: 'Roadmap' },
|
||||
],
|
||||
},
|
||||
{
|
||||
text: '对比与选型',
|
||||
items: [
|
||||
{ link: 'project/comparison', text: '方案对比' },
|
||||
],
|
||||
},
|
||||
];
|
||||
}
|
||||
|
||||
export const search: DefaultTheme.AlgoliaSearchOptions['locales'] = {
|
||||
root: {
|
||||
placeholder: '搜索文档',
|
||||
|
||||
@@ -1,726 +0,0 @@
|
||||
# Niucloud 前端迁移到 Vben Admin 规划文档
|
||||
|
||||
## 1. 项目概述
|
||||
|
||||
### 1.1 迁移目标
|
||||
将 Niucloud PHP 项目的管理后台前端功能迁移到基于 Vben Admin 框架的现代化管理面板中。
|
||||
|
||||
### 1.2 架构层级映射
|
||||
|
||||
#### Niucloud 架构层级
|
||||
- **app**: 核心业务功能模块（用户、权限、菜单、系统设置等）
|
||||
- **addons**: 插件扩展模块（可选功能模块）
|
||||
- **app (业务)**: 具体业务应用模块
|
||||
|
||||
#### WWJCloud 架构层级
|
||||
- **common**: 框架通用服务层（对应 Niucloud 的 app）
|
||||
- **addon**: 插件扩展层（对应 Niucloud 的 addons）
|
||||
- **app**: 业务开发层（对应 Niucloud 的业务 app）
|
||||
|
||||
#### 层级映射关系
|
||||
```
|
||||
Niucloud → WWJCloud
|
||||
├── app/ ├── common/ (核心功能：用户、权限、设置等)
|
||||
├── addons/ ├── addon/ (插件扩展：可选功能模块)
|
||||
└── app(业务)/ └── app/ (具体业务：电商、CRM、ERP等)
|
||||
```
|
||||
|
||||
### 1.3 技术栈对比
|
||||
|
||||
| 项目 | Niucloud Admin | Vben Admin (目标) |
|
||||
|------|----------------|-------------------|
|
||||
| 框架 | Vue 3 + TypeScript | Vue 3 + TypeScript |
|
||||
| UI库 | Element Plus | Element Plus |
|
||||
| 构建工具 | Vite | Vite |
|
||||
| 状态管理 | Pinia | Pinia |
|
||||
| 路由 | Vue Router | Vue Router |
|
||||
| 样式 | SCSS + Tailwind | SCSS + Tailwind |
|
||||
|
||||
## 2. 目录结构对比分析
|
||||
|
||||
### 2.1 Niucloud Admin 结构
|
||||
```
|
||||
src/
|
||||
├── app/ # 应用层
|
||||
│ ├── api/ # API 接口定义
|
||||
│ ├── assets/ # 静态资源
|
||||
│ ├── components/ # 业务组件
|
||||
│ ├── lang/ # 国际化
|
||||
│ └── views/ # 页面视图
|
||||
│ ├── app/ # 应用管理
|
||||
│ ├── auth/ # 权限管理
|
||||
│ ├── channel/ # 渠道管理
|
||||
│ ├── dict/ # 字典管理
|
||||
│ ├── diy/ # 自定义页面
|
||||
│ ├── finance/ # 财务管理
|
||||
│ ├── home/ # 首页
|
||||
│ ├── marketing/ # 营销管理
|
||||
│ ├── member/ # 会员管理
|
||||
│ ├── setting/ # 系统设置
|
||||
│ └── tools/ # 工具管理
|
||||
├── components/ # 通用组件
|
||||
├── layout/ # 布局组件
|
||||
├── router/ # 路由配置
|
||||
├── stores/ # 状态管理
|
||||
├── styles/ # 样式文件
|
||||
├── types/ # 类型定义
|
||||
└── utils/ # 工具函数
|
||||
```
|
||||
|
||||
### 2.2 Vben Admin 结构
|
||||
```
|
||||
src/
|
||||
├── adapter/ # 适配器层
|
||||
├── api/ # API 接口
|
||||
├── layouts/ # 布局组件
|
||||
├── locales/ # 国际化
|
||||
├── router/ # 路由配置
|
||||
│ └── routes/ # 路由模块
|
||||
│ └── modules/ # 路由模块文件
|
||||
├── store/ # 状态管理
|
||||
└── views/ # 页面视图
|
||||
├── _core/ # 核心页面
|
||||
├── dashboard/ # 仪表板
|
||||
└── demos/ # 示例页面
|
||||
```
|
||||
|
||||
## 3. 功能模块映射方案
|
||||
|
||||
### 3.1 功能模块映射（全部迁移到 Common 层）
|
||||
|
||||
根据项目实际情况，所有 Niucloud 功能模块都将迁移到 WWJCloud 的 Common 层，作为框架底层通用功能。
|
||||
|
||||
#### 3.1.1 核心管理功能（高优先级）
|
||||
|
||||
| Niucloud 模块 | WWJCloud Common 位置 | 迁移优先级 | 功能说明 |
|
||||
|---------------|---------------------|------------|----------|
|
||||
| 用户管理 (user) | `common/user` | 高 | 用户账户管理 |
|
||||
| 角色权限 (auth) | `common/rbac` | 高 | RBAC 权限控制 |
|
||||
| 菜单管理 (menu) | `common/rbac/menu` | 高 | 动态菜单管理 |
|
||||
| 系统设置 (setting) | `common/settings` | 高 | 系统配置管理 |
|
||||
| 字典管理 (dict) | `common/dict` | 高 | 数据字典管理 |
|
||||
| 文件管理 (file) | `common/file` | 高 | 文件上传管理 |
|
||||
| 站点管理 (site) | `common/settings/site` | 高 | 站点基础配置 |
|
||||
|
||||
#### 3.1.2 业务管理功能（中优先级）
|
||||
|
||||
| Niucloud 模块 | WWJCloud Common 位置 | 迁移优先级 | 功能说明 |
|
||||
|---------------|---------------------|------------|----------|
|
||||
| 会员管理 (member) | `common/member` | 中 | 会员系统管理 |
|
||||
| 营销工具 (marketing) | `common/marketing` | 中 | 营销活动管理 |
|
||||
| 财务管理 (finance) | `common/finance` | 中 | 财务数据管理 |
|
||||
| 渠道管理 (channel) | `common/channel` | 中 | 销售渠道管理 |
|
||||
| 应用管理 (app) | `common/app` | 中 | 应用配置管理 |
|
||||
| 首页管理 (home) | `common/dashboard` | 中 | 仪表板管理 |
|
||||
|
||||
#### 3.1.3 扩展功能模块（低优先级）
|
||||
|
||||
| Niucloud 模块 | WWJCloud Common 位置 | 迁移优先级 | 功能说明 |
|
||||
|---------------|---------------------|------------|----------|
|
||||
| 海报管理 (poster) | `common/poster` | 低 | 海报设计工具 |
|
||||
| 打印管理 (printer) | `common/printer` | 低 | 打印模板管理 |
|
||||
| 微信平台 (wxoplatform) | `common/wechat` | 低 | 微信生态集成 |
|
||||
| 工具集 (tools) | `common/tools` | 低 | 辅助工具集合 |
|
||||
| DIY 页面 (diy) | `common/diy` | 低 | 自定义页面构建 |
|
||||
| DIY 表单 (diy_form) | `common/diy-form` | 低 | 自定义表单构建 |
|
||||
|
||||
### 3.2 详细页面映射（全部映射到 Common 层）
|
||||
|
||||
#### 3.2.1 权限管理模块 (auth/)
|
||||
```
|
||||
Niucloud: app/views/auth/
|
||||
├── user.vue → views/common/auth/user/index.vue
|
||||
├── role.vue → views/common/auth/role/index.vue
|
||||
├── menu.vue → views/common/auth/menu/index.vue
|
||||
├── site_menu.vue → views/common/auth/site-menu/index.vue
|
||||
└── log.vue → views/common/auth/log/index.vue
|
||||
```
|
||||
|
||||
#### 3.2.2 系统设置模块 (setting/)
|
||||
```
|
||||
Niucloud: app/views/setting/
|
||||
├── system.vue → views/common/setting/basic/index.vue
|
||||
├── adminlogin.vue → views/common/setting/login/index.vue
|
||||
├── sms.vue → views/common/setting/sms/index.vue
|
||||
├── pay.vue → views/common/setting/payment/index.vue
|
||||
├── storage.vue → views/common/setting/storage/index.vue
|
||||
├── notice.vue → views/common/setting/notification/index.vue
|
||||
├── map.vue → views/common/setting/map/index.vue
|
||||
└── member.vue → views/common/setting/member/index.vue
|
||||
```
|
||||
|
||||
#### 3.2.3 会员管理模块 (member/)
|
||||
```
|
||||
Niucloud: app/views/member/
|
||||
├── member.vue → views/common/member/list/index.vue
|
||||
├── member_detail.vue → views/common/member/detail/index.vue
|
||||
├── level.vue → views/common/member/level/index.vue
|
||||
├── label.vue → views/common/member/label/index.vue
|
||||
├── balance.vue → views/common/member/balance/index.vue
|
||||
├── point.vue → views/common/member/point/index.vue
|
||||
└── commission.vue → views/common/member/commission/index.vue
|
||||
```
|
||||
|
||||
#### 3.2.4 应用管理模块 (app/)
|
||||
```
|
||||
Niucloud: app/views/app/
|
||||
├── app.vue → views/common/app/list/index.vue
|
||||
├── app_detail.vue → views/common/app/detail/index.vue
|
||||
└── config.vue → views/common/app/config/index.vue
|
||||
```
|
||||
|
||||
#### 3.2.5 营销管理模块 (marketing/)
|
||||
```
|
||||
Niucloud: app/views/marketing/
|
||||
├── activity.vue → views/common/marketing/activity/index.vue
|
||||
├── coupon.vue → views/common/marketing/coupon/index.vue
|
||||
└── promotion.vue → views/common/marketing/promotion/index.vue
|
||||
```
|
||||
|
||||
#### 3.2.6 财务管理模块 (finance/)
|
||||
```
|
||||
Niucloud: app/views/finance/
|
||||
├── account.vue → views/common/finance/account/index.vue
|
||||
├── transaction.vue → views/common/finance/transaction/index.vue
|
||||
└── report.vue → views/common/finance/report/index.vue
|
||||
```
|
||||
|
||||
#### 3.2.7 渠道管理模块 (channel/)
|
||||
```
|
||||
Niucloud: app/views/channel/
|
||||
├── channel.vue → views/common/channel/list/index.vue
|
||||
├── config.vue → views/common/channel/config/index.vue
|
||||
└── statistics.vue → views/common/channel/statistics/index.vue
|
||||
```
|
||||
|
||||
#### 3.2.8 字典管理模块 (dict/)
|
||||
```
|
||||
Niucloud: app/views/dict/
|
||||
├── dict.vue → views/common/dict/list/index.vue
|
||||
├── dict_data.vue → views/common/dict/data/index.vue
|
||||
└── dict_type.vue → views/common/dict/type/index.vue
|
||||
```
|
||||
|
||||
#### 3.2.9 文件管理模块 (file/)
|
||||
```
|
||||
Niucloud: app/views/file/
|
||||
├── file.vue → views/common/file/list/index.vue
|
||||
├── upload.vue → views/common/file/upload/index.vue
|
||||
└── config.vue → views/common/file/config/index.vue
|
||||
```
|
||||
|
||||
#### 3.2.10 扩展功能模块
|
||||
```
|
||||
Niucloud: app/views/poster/
|
||||
├── poster.vue → views/common/poster/list/index.vue
|
||||
└── template.vue → views/common/poster/template/index.vue
|
||||
|
||||
Niucloud: app/views/printer/
|
||||
├── printer.vue → views/common/printer/list/index.vue
|
||||
└── template.vue → views/common/printer/template/index.vue
|
||||
|
||||
Niucloud: app/views/wxoplatform/
|
||||
├── config.vue → views/common/wechat/config/index.vue
|
||||
└── menu.vue → views/common/wechat/menu/index.vue
|
||||
|
||||
Niucloud: app/views/tools/
|
||||
├── generator.vue → views/common/tools/generator/index.vue
|
||||
└── backup.vue → views/common/tools/backup/index.vue
|
||||
|
||||
Niucloud: app/views/diy/
|
||||
├── page.vue → views/common/diy/page/index.vue
|
||||
└── component.vue → views/common/diy/component/index.vue
|
||||
|
||||
Niucloud: app/views/diy_form/
|
||||
├── form.vue → views/common/diy-form/list/index.vue
|
||||
└── builder.vue → views/common/diy-form/builder/index.vue
|
||||
```
|
||||
|
||||
## 4. 组件迁移策略
|
||||
|
||||
### 4.1 通用组件映射
|
||||
|
||||
| Niucloud 组件 | 功能 | Vben 替代方案 |
|
||||
|---------------|------|---------------|
|
||||
| upload-image | 图片上传 | VbenUpload + 自定义适配 |
|
||||
| upload-file | 文件上传 | VbenUpload + 自定义适配 |
|
||||
| upload-video | 视频上传 | VbenUpload + 自定义适配 |
|
||||
| editor | 富文本编辑器 | VbenEditor 或 第三方编辑器 |
|
||||
| select-icon | 图标选择器 | VbenIconPicker |
|
||||
| select-area | 地区选择器 | VbenAreaPicker 或 自定义 |
|
||||
| heat-map | 热力图 | 自定义组件 + ECharts |
|
||||
| video-player | 视频播放器 | 第三方播放器组件 |
|
||||
|
||||
### 4.2 布局组件迁移
|
||||
|
||||
Niucloud 有多套布局主题：
|
||||
- admin (默认)
|
||||
- admin_simplicity (简洁)
|
||||
- bussiness (商务)
|
||||
- darkside (暗色)
|
||||
- profession (专业)
|
||||
|
||||
**迁移策略**: 统一使用 Vben Admin 的主题系统，通过配置实现多主题切换。
|
||||
|
||||
## 5. 路由配置迁移
|
||||
|
||||
### 5.1 路由结构对比
|
||||
|
||||
**Niucloud 路由特点**:
|
||||
- 基于文件系统的路由
|
||||
- 支持动态路由加载
|
||||
- 权限路由集成
|
||||
|
||||
**Vben Admin 路由特点**:
|
||||
- 模块化路由配置
|
||||
- 支持路由懒加载
|
||||
- 内置权限控制
|
||||
|
||||
### 5.2 路由迁移示例
|
||||
|
||||
```typescript
|
||||
// src/router/routes/modules/common.ts
|
||||
import type { RouteRecordRaw } from 'vue-router';
|
||||
|
||||
const routes: RouteRecordRaw[] = [
|
||||
{
|
||||
path: '/common',
|
||||
name: 'Common',
|
||||
component: () => import('@/layouts/basic.vue'),
|
||||
meta: {
|
||||
title: '框架管理',
|
||||
icon: 'common',
|
||||
orderNo: 1000,
|
||||
},
|
||||
children: [
|
||||
{
|
||||
path: 'system',
|
||||
name: 'CommonSystem',
|
||||
meta: { title: '系统管理' },
|
||||
children: [
|
||||
{
|
||||
path: 'auth',
|
||||
name: 'CommonSystemAuth',
|
||||
meta: { title: '权限管理' },
|
||||
children: [
|
||||
{
|
||||
path: 'user',
|
||||
name: 'CommonSystemAuthUser',
|
||||
component: () => import('@/views/common/auth/user/index.vue'),
|
||||
meta: { title: '用户管理' },
|
||||
},
|
||||
{
|
||||
path: 'role',
|
||||
name: 'CommonSystemAuthRole',
|
||||
component: () => import('@/views/common/auth/role/index.vue'),
|
||||
meta: { title: '角色管理' },
|
||||
},
|
||||
{
|
||||
path: 'menu',
|
||||
name: 'CommonSystemAuthMenu',
|
||||
component: () => import('@/views/common/auth/menu/index.vue'),
|
||||
meta: { title: '菜单管理' },
|
||||
},
|
||||
],
|
||||
},
|
||||
{
|
||||
path: 'setting',
|
||||
name: 'CommonSystemSetting',
|
||||
meta: { title: '系统设置' },
|
||||
children: [
|
||||
{
|
||||
path: 'basic',
|
||||
name: 'CommonSystemSettingBasic',
|
||||
component: () => import('@/views/common/setting/basic/index.vue'),
|
||||
meta: { title: '基础设置' },
|
||||
},
|
||||
{
|
||||
path: 'sms',
|
||||
name: 'CommonSystemSettingSms',
|
||||
component: () => import('@/views/common/setting/sms/index.vue'),
|
||||
meta: { title: '短信设置' },
|
||||
},
|
||||
{
|
||||
path: 'payment',
|
||||
name: 'CommonSystemSettingPayment',
|
||||
component: () => import('@/views/common/setting/payment/index.vue'),
|
||||
meta: { title: '支付设置' },
|
||||
},
|
||||
{
|
||||
path: 'storage',
|
||||
name: 'CommonSystemSettingStorage',
|
||||
component: () => import('@/views/common/setting/storage/index.vue'),
|
||||
meta: { title: '存储设置' },
|
||||
},
|
||||
],
|
||||
},
|
||||
{
|
||||
path: 'member',
|
||||
name: 'CommonSystemMember',
|
||||
meta: { title: '会员管理' },
|
||||
children: [
|
||||
{
|
||||
path: 'list',
|
||||
name: 'CommonSystemMemberList',
|
||||
component: () => import('@/views/common/member/list/index.vue'),
|
||||
meta: { title: '会员列表' },
|
||||
},
|
||||
{
|
||||
path: 'level',
|
||||
name: 'CommonSystemMemberLevel',
|
||||
component: () => import('@/views/common/member/level/index.vue'),
|
||||
meta: { title: '会员等级' },
|
||||
},
|
||||
],
|
||||
},
|
||||
],
|
||||
},
|
||||
{
|
||||
path: 'file',
|
||||
name: 'CommonFile',
|
||||
meta: { title: '文件管理' },
|
||||
children: [
|
||||
{
|
||||
path: 'list',
|
||||
name: 'CommonFileList',
|
||||
component: () => import('@/views/common/file/list/index.vue'),
|
||||
meta: { title: '文件列表' },
|
||||
},
|
||||
{
|
||||
path: 'upload',
|
||||
name: 'CommonFileUpload',
|
||||
component: () => import('@/views/common/file/upload/index.vue'),
|
||||
meta: { title: '文件上传' },
|
||||
},
|
||||
],
|
||||
},
|
||||
],
|
||||
},
|
||||
];
|
||||
|
||||
export default routes;
|
||||
```
|
||||
|
||||
## 6. API 接口迁移
|
||||
|
||||
### 6.1 API 结构对比
|
||||
|
||||
**Niucloud API 特点**:
|
||||
- RESTful 风格
|
||||
- 统一响应格式
|
||||
- 内置权限验证
|
||||
|
||||
**目标 API 结构**:
|
||||
- 对接后端 NestJS API
|
||||
- 保持 RESTful 风格
|
||||
- JWT 认证
|
||||
|
||||
### 6.2 API 迁移示例
|
||||
|
||||
```typescript
|
||||
// src/api/auth.ts
|
||||
import { request } from '@/api/request';
|
||||
|
||||
export interface UserListParams {
|
||||
page?: number;
|
||||
limit?: number;
|
||||
keyword?: string;
|
||||
}
|
||||
|
||||
export interface UserInfo {
|
||||
id: number;
|
||||
username: string;
|
||||
nickname: string;
|
||||
email: string;
|
||||
status: number;
|
||||
created_at: string;
|
||||
}
|
||||
|
||||
// 获取用户列表
|
||||
export function getUserList(params: UserListParams) {
|
||||
return request<{
|
||||
list: UserInfo[];
|
||||
total: number;
|
||||
}>('/api/users', {
|
||||
method: 'GET',
|
||||
params,
|
||||
});
|
||||
}
|
||||
|
||||
// 创建用户
|
||||
export function createUser(data: Partial<UserInfo>) {
|
||||
return request('/api/users', {
|
||||
method: 'POST',
|
||||
data,
|
||||
});
|
||||
}
|
||||
|
||||
// 更新用户
|
||||
export function updateUser(id: number, data: Partial<UserInfo>) {
|
||||
return request(`/api/users/${id}`, {
|
||||
method: 'PUT',
|
||||
data,
|
||||
});
|
||||
}
|
||||
|
||||
// 删除用户
|
||||
export function deleteUser(id: number) {
|
||||
return request(`/api/users/${id}`, {
|
||||
method: 'DELETE',
|
||||
});
|
||||
}
|
||||
```
|
||||
|
||||
## 7. 状态管理迁移
|
||||
|
||||
### 7.1 Store 结构对比
|
||||
|
||||
**Niucloud Stores**:
|
||||
- app.ts (应用状态)
|
||||
- user.ts (用户状态)
|
||||
- system.ts (系统状态)
|
||||
- style.ts (样式状态)
|
||||
- tabbar.ts (标签栏状态)
|
||||
|
||||
**Vben Admin Stores**:
|
||||
- auth.ts (认证状态)
|
||||
- 其他业务状态按需添加
|
||||
|
||||
### 7.2 状态迁移示例
|
||||
|
||||
```typescript
|
||||
// src/store/modules/system.ts
|
||||
import { defineStore } from 'pinia';
|
||||
|
||||
export interface SystemState {
|
||||
settings: {
|
||||
siteName: string;
|
||||
logo: string;
|
||||
copyright: string;
|
||||
};
|
||||
dictData: Record<string, any[]>;
|
||||
}
|
||||
|
||||
export const useSystemStore = defineStore('system', {
|
||||
state: (): SystemState => ({
|
||||
settings: {
|
||||
siteName: '',
|
||||
logo: '',
|
||||
copyright: '',
|
||||
},
|
||||
dictData: {},
|
||||
}),
|
||||
|
||||
getters: {
|
||||
getSiteName: (state) => state.settings.siteName,
|
||||
getDictByType: (state) => (type: string) => state.dictData[type] || [],
|
||||
},
|
||||
|
||||
actions: {
|
||||
async fetchSettings() {
|
||||
// 获取系统设置
|
||||
},
|
||||
|
||||
async fetchDictData() {
|
||||
// 获取字典数据
|
||||
},
|
||||
},
|
||||
});
|
||||
```
|
||||
|
||||
## 8. 样式迁移策略
|
||||
|
||||
### 8.1 样式文件迁移
|
||||
|
||||
**保留的样式**:
|
||||
- 业务相关的自定义样式
|
||||
- 品牌色彩定义
|
||||
- 特殊组件样式
|
||||
|
||||
**替换的样式**:
|
||||
- 基础布局样式 (使用 Vben 内置)
|
||||
- 通用组件样式 (使用 Element Plus)
|
||||
- 响应式断点 (使用 Vben 配置)
|
||||
|
||||
### 8.2 主题配置
|
||||
|
||||
```typescript
|
||||
// src/preferences.ts
|
||||
export const preferences = {
|
||||
theme: {
|
||||
colorPrimary: '#1890ff', // 主色调
|
||||
mode: 'light', // 主题模式
|
||||
},
|
||||
layout: {
|
||||
sidebar: {
|
||||
collapsed: false,
|
||||
width: 240,
|
||||
},
|
||||
header: {
|
||||
height: 64,
|
||||
},
|
||||
},
|
||||
};
|
||||
```
|
||||
|
||||
## 9. 迁移实施计划
|
||||
|
||||
### 9.1 阶段一：目录结构搭建（1周）
|
||||
|
||||
#### 所有功能模块统一在 Common 层目录创建
|
||||
```
|
||||
src/views/
|
||||
├── common/ # 框架通用功能层（所有 Niucloud 功能迁移到此层）
|
||||
│ └── # 系统管理模块
|
||||
│ ├── auth/ # 权限管理
|
||||
│ │ ├── user/ # 用户管理
|
||||
│ │ ├── role/ # 角色管理
|
||||
│ │ ├── menu/ # 菜单管理
|
||||
│ │ ├── site-menu/ # 站点菜单管理
|
||||
│ │ └── log/ # 操作日志
|
||||
│ ├── setting/ # 系统设置
|
||||
│ │ ├── basic/ # 基础设置
|
||||
│ │ ├── login/ # 登录设置
|
||||
│ │ ├── sms/ # 短信设置
|
||||
│ │ ├── payment/ # 支付设置
|
||||
│ │ ├── storage/ # 存储设置
|
||||
│ │ ├── notification/ # 通知设置
|
||||
│ │ ├── map/ # 地图设置
|
||||
│ │ └── member/ # 会员设置
|
||||
│ ├── member/ # 会员管理
|
||||
│ │ ├── list/ # 会员列表
|
||||
│ │ ├── detail/ # 会员详情
|
||||
│ │ ├── level/ # 会员等级
|
||||
│ │ ├── label/ # 会员标签
|
||||
│ │ ├── balance/ # 余额管理
|
||||
│ │ ├── point/ # 积分管理
|
||||
│ │ └── commission/ # 佣金管理
|
||||
│ ├── marketing/ # 营销管理
|
||||
│ │ ├── activity/ # 营销活动
|
||||
│ │ ├── coupon/ # 优惠券
|
||||
│ │ └── promotion/ # 促销活动
|
||||
│ ├── finance/ # 财务管理
|
||||
│ │ ├── account/ # 账户管理
|
||||
│ │ ├── transaction/ # 交易记录
|
||||
│ │ └── report/ # 财务报表
|
||||
│ ├── channel/ # 渠道管理
|
||||
│ │ ├── list/ # 渠道列表
|
||||
│ │ ├── config/ # 渠道配置
|
||||
│ │ └── statistics/ # 渠道统计
|
||||
│ ├── app/ # 应用管理
|
||||
│ │ ├── list/ # 应用列表
|
||||
│ │ ├── detail/ # 应用详情
|
||||
│ │ └── config/ # 应用配置
|
||||
│ ├── dict/ # 字典管理
|
||||
│ │ ├── list/ # 字典列表
|
||||
│ │ ├── data/ # 字典数据
|
||||
│ │ └── type/ # 字典类型
|
||||
│ ├── file/ # 文件管理
|
||||
│ │ ├── list/ # 文件列表
|
||||
│ │ ├── upload/ # 文件上传
|
||||
│ │ └── config/ # 文件配置
|
||||
│ ├── poster/ # 海报管理
|
||||
│ │ ├── list/ # 海报列表
|
||||
│ │ └── template/ # 海报模板
|
||||
│ ├── printer/ # 打印管理
|
||||
│ │ ├── list/ # 打印机列表
|
||||
│ │ └── template/ # 打印模板
|
||||
│ ├── wechat/ # 微信平台
|
||||
│ │ ├── config/ # 微信配置
|
||||
│ │ └── menu/ # 微信菜单
|
||||
│ ├── tools/ # 工具集
|
||||
│ │ ├── generator/ # 代码生成
|
||||
│ │ └── backup/ # 数据备份
|
||||
│ ├── diy/ # DIY 页面
|
||||
│ │ ├── page/ # 页面管理
|
||||
│ │ └── component/ # 组件管理
|
||||
│ └── diy-form/ # DIY 表单
|
||||
│ ├── list/ # 表单列表
|
||||
│ └── builder/ # 表单构建器
|
||||
```
|
||||
|
||||
### 9.2 阶段二：Common 层核心功能迁移（2-3周）
|
||||
- [ ] 用户管理系统 (`user`)
|
||||
- [ ] 角色权限管理 (`rbac`)
|
||||
- [ ] 菜单管理系统 (`rbac/menu`)
|
||||
- [ ] 系统设置模块 (`settings`)
|
||||
- [ ] 数据字典管理 (`dict`)
|
||||
- [ ] 文件管理系统 (`file`)
|
||||
|
||||
### 9.3 阶段三：App 层业务功能迁移（3-4周）
|
||||
- [ ] 会员管理系统 (`crm/member`)
|
||||
- [ ] 营销工具模块 (`marketing`)
|
||||
- [ ] 财务管理模块 (`erp/finance`)
|
||||
- [ ] 渠道管理系统 (`channel`)
|
||||
|
||||
### 9.4 阶段四：Addon 层扩展功能迁移（2-3周）
|
||||
- [ ] 海报管理工具 (`addons/poster`)
|
||||
- [ ] 打印模板管理 (`addons/printer`)
|
||||
- [ ] 微信平台集成 (`addons/wechat`)
|
||||
- [ ] 辅助工具集合 (`addons/tools`)
|
||||
|
||||
### 9.5 阶段五：优化和测试（2周）
|
||||
- [ ] 性能优化和代码重构
|
||||
- [ ] 跨浏览器兼容性测试
|
||||
- [ ] 用户体验优化
|
||||
- [ ] 技术文档完善
|
||||
|
||||
### 9.2 开发规范
|
||||
|
||||
1. **组件开发**:
|
||||
- 优先使用 Vben 封装组件
|
||||
- 其次使用 Element Plus 原生组件
|
||||
- 必要时开发自定义组件
|
||||
|
||||
2. **代码规范**:
|
||||
- 遵循 Vben Admin 代码规范
|
||||
- 使用 TypeScript 严格模式
|
||||
- 统一的 ESLint 和 Prettier 配置
|
||||
|
||||
3. **测试策略**:
|
||||
- 单元测试覆盖核心业务逻辑
|
||||
- E2E 测试覆盖关键用户流程
|
||||
- 兼容性测试确保多浏览器支持
|
||||
|
||||
## 10. 风险评估与应对
|
||||
|
||||
### 10.1 技术风险
|
||||
|
||||
| 风险项 | 影响程度 | 应对策略 |
|
||||
|--------|----------|----------|
|
||||
| 组件兼容性 | 中 | 提前验证，准备降级方案 |
|
||||
| 性能问题 | 中 | 代码分割，懒加载优化 |
|
||||
| 数据迁移 | 高 | 制定详细的数据映射方案 |
|
||||
| 用户体验差异 | 中 | 保持核心交互逻辑一致 |
|
||||
|
||||
### 10.2 进度风险
|
||||
|
||||
- **人力资源**: 确保有经验的前端开发人员参与
|
||||
- **时间安排**: 预留充足的测试和调试时间
|
||||
- **需求变更**: 建立变更控制流程
|
||||
|
||||
## 11. 验收标准
|
||||
|
||||
### 11.1 功能验收
|
||||
- [ ] 所有原有功能正常运行
|
||||
- [ ] 用户权限控制正确
|
||||
- [ ] 数据操作无误
|
||||
- [ ] 响应式布局适配
|
||||
|
||||
### 11.2 性能验收
|
||||
- [ ] 首屏加载时间 < 3s
|
||||
- [ ] 页面切换流畅
|
||||
- [ ] 大数据量列表渲染正常
|
||||
|
||||
### 11.3 兼容性验收
|
||||
- [ ] Chrome/Firefox/Safari 最新版本
|
||||
- [ ] 移动端适配
|
||||
- [ ] 不同分辨率屏幕适配
|
||||
|
||||
---
|
||||
|
||||
**文档版本**: v1.0
|
||||
**创建时间**: 2025-01-22
|
||||
**更新时间**: 2025-01-22
|
||||
**负责人**: 开发团队
|
||||
**审核人**: 项目经理
|
||||
@@ -1,11 +1,13 @@
|
||||
{
|
||||
"name": "@vben/docs",
|
||||
"version": "5.5.9",
|
||||
"version": "5.5.8",
|
||||
"private": true,
|
||||
"scripts": {
|
||||
"build": "vitepress build",
|
||||
"dev": "vitepress dev",
|
||||
"docs:preview": "vitepress preview"
|
||||
"docs:preview": "vitepress preview",
|
||||
"generate-api": "node scripts/generate-api-docs.js",
|
||||
"generate-api:dev": "BACKEND_URL=http://localhost:3000 node scripts/generate-api-docs.js"
|
||||
},
|
||||
"imports": {
|
||||
"#/*": {
|
||||
@@ -20,6 +22,7 @@
|
||||
"@vben/plugins": "workspace:*",
|
||||
"@vben/styles": "workspace:*",
|
||||
"ant-design-vue": "catalog:",
|
||||
"axios": "^1.11.0",
|
||||
"lucide-vue-next": "catalog:",
|
||||
"medium-zoom": "catalog:",
|
||||
"radix-vue": "catalog:",
|
||||
|
||||
BIN
admin/docs/public/logos/logo.png
Normal file
BIN
admin/docs/public/logos/logo.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 17 KiB |
3
admin/docs/public/logos/mysql.svg
Normal file
3
admin/docs/public/logos/mysql.svg
Normal file
@@ -0,0 +1,3 @@
|
||||
<svg width="24" height="24" viewBox="0 0 24 24" fill="none" xmlns="http://www.w3.org/2000/svg">
|
||||
<path d="M12 2C6.48 2 2 6.48 2 12s4.48 10 10 10 10-4.48 10-10S17.52 2 12 2zm-2 15l-5-5 1.41-1.41L10 14.17l7.59-7.59L19 8l-9 9z" fill="#4479A1"/>
|
||||
</svg>
|
||||
|
After Width: | Height: | Size: 250 B |
3
admin/docs/public/logos/nestjs.svg
Normal file
3
admin/docs/public/logos/nestjs.svg
Normal file
@@ -0,0 +1,3 @@
|
||||
<svg width="24" height="24" viewBox="0 0 24 24" fill="none" xmlns="http://www.w3.org/2000/svg">
|
||||
<path d="M16.287 3.83a.5.5 0 0 1 .5.5v2.5a.5.5 0 0 1-.5.5h-2.5a.5.5 0 0 1-.5-.5v-2.5a.5.5 0 0 1 .5-.5h2.5zm-5 0a.5.5 0 0 1 .5.5v2.5a.5.5 0 0 1-.5.5h-2.5a.5.5 0 0 1-.5-.5v-2.5a.5.5 0 0 1 .5-.5h2.5zm5 5a.5.5 0 0 1 .5.5v2.5a.5.5 0 0 1-.5.5h-2.5a.5.5 0 0 1-.5-.5v-2.5a.5.5 0 0 1 .5-.5h2.5zm-5 0a.5.5 0 0 1 .5.5v2.5a.5.5 0 0 1-.5.5h-2.5a.5.5 0 0 1-.5-.5v-2.5a.5.5 0 0 1 .5-.5h2.5zm5 5a.5.5 0 0 1 .5.5v2.5a.5.5 0 0 1-.5.5h-2.5a.5.5 0 0 1-.5-.5v-2.5a.5.5 0 0 1 .5-.5h2.5zm-5 0a.5.5 0 0 1 .5.5v2.5a.5.5 0 0 1-.5.5h-2.5a.5.5 0 0 1-.5-.5v-2.5a.5.5 0 0 1 .5-.5h2.5z" fill="#E0234E"/>
|
||||
</svg>
|
||||
|
After Width: | Height: | Size: 678 B |
4
admin/docs/public/logos/redis.svg
Normal file
4
admin/docs/public/logos/redis.svg
Normal file
@@ -0,0 +1,4 @@
|
||||
<svg width="24" height="24" viewBox="0 0 24 24" fill="none" xmlns="http://www.w3.org/2000/svg">
|
||||
<path d="M12 2L2 7v10l10 5 10-5V7L12 2zm0 2.236L19.5 8v8L12 20.764 4.5 16V8L12 4.236z" fill="#DC382D"/>
|
||||
<path d="M12 6L6 9v6l6 3 6-3V9l-6-3z" fill="#DC382D"/>
|
||||
</svg>
|
||||
|
After Width: | Height: | Size: 266 B |
4
admin/docs/public/logos/typeorm.svg
Normal file
4
admin/docs/public/logos/typeorm.svg
Normal file
@@ -0,0 +1,4 @@
|
||||
<svg width="24" height="24" viewBox="0 0 24 24" fill="none" xmlns="http://www.w3.org/2000/svg">
|
||||
<path d="M12 2L2 7v10l10 5 10-5V7L12 2zm0 2.236L19.5 8v8L12 20.764 4.5 16V8L12 4.236z" fill="#FCA326"/>
|
||||
<path d="M12 6L6 9v6l6 3 6-3V9l-6-3z" fill="#FCA326"/>
|
||||
</svg>
|
||||
|
After Width: | Height: | Size: 266 B |
43
admin/docs/public/logos/wwjcloud.svg
Normal file
43
admin/docs/public/logos/wwjcloud.svg
Normal file
@@ -0,0 +1,43 @@
|
||||
<svg width="120" height="120" viewBox="0 0 120 120" fill="none" xmlns="http://www.w3.org/2000/svg">
|
||||
<!-- 定义渐变和阴影 -->
|
||||
<defs>
|
||||
<linearGradient id="bgGradient" x1="0%" y1="0%" x2="100%" y2="100%">
|
||||
<stop offset="0%" style="stop-color:#3B82F6;stop-opacity:1" />
|
||||
<stop offset="50%" style="stop-color:#2563EB;stop-opacity:1" />
|
||||
<stop offset="100%" style="stop-color:#1E40AF;stop-opacity:1" />
|
||||
</linearGradient>
|
||||
<filter id="shadow" x="-20%" y="-20%" width="140%" height="140%">
|
||||
<feDropShadow dx="2" dy="4" stdDeviation="3" flood-color="#000000" flood-opacity="0.15"/>
|
||||
</filter>
|
||||
<filter id="glow" x="-50%" y="-50%" width="200%" height="200%">
|
||||
<feGaussianBlur stdDeviation="2" result="coloredBlur"/>
|
||||
<feMerge>
|
||||
<feMergeNode in="coloredBlur"/>
|
||||
<feMergeNode in="SourceGraphic"/>
|
||||
</feMerge>
|
||||
</filter>
|
||||
</defs>
|
||||
|
||||
<!-- 背景圆形 -->
|
||||
<circle cx="60" cy="60" r="55" fill="url(#bgGradient)" filter="url(#shadow)"/>
|
||||
|
||||
<!-- 云朵形状 - 主形状 -->
|
||||
<path d="M20 50 Q10 40 20 30 Q30 20 40 30 Q50 20 60 30 Q70 20 80 30 Q90 40 80 50 Q90 60 80 70 Q70 80 60 70 Q50 80 40 70 Q30 80 20 70 Q10 60 20 50"
|
||||
fill="white" opacity="0.95" filter="url(#glow)"/>
|
||||
|
||||
<!-- 字母 W - 主要标识 -->
|
||||
<path d="M25 45 L35 65 L45 50 L55 65 L65 45"
|
||||
stroke="white" stroke-width="5" fill="none" stroke-linecap="round" stroke-linejoin="round"/>
|
||||
|
||||
<!-- 装饰点 -->
|
||||
<circle cx="15" cy="15" r="2.5" fill="white" opacity="0.9"/>
|
||||
<circle cx="105" cy="15" r="2.5" fill="white" opacity="0.9"/>
|
||||
<circle cx="15" cy="105" r="2.5" fill="white" opacity="0.9"/>
|
||||
<circle cx="105" cy="105" r="2.5" fill="white" opacity="0.9"/>
|
||||
|
||||
<!-- 中心装饰 -->
|
||||
<circle cx="60" cy="60" r="4" fill="white" opacity="0.7"/>
|
||||
|
||||
<!-- 外圈装饰 -->
|
||||
<circle cx="60" cy="60" r="50" stroke="white" stroke-width="1" fill="none" opacity="0.3"/>
|
||||
</svg>
|
||||
|
After Width: | Height: | Size: 1.9 KiB |
168
admin/docs/scripts/README.md
Normal file
168
admin/docs/scripts/README.md
Normal file
@@ -0,0 +1,168 @@
|
||||
# 文档脚本说明
|
||||
|
||||
## API 文档自动生成脚本
|
||||
|
||||
### 功能说明
|
||||
|
||||
`generate-api-docs.js` 脚本用于从后端的 Swagger API 自动生成前端文档。
|
||||
|
||||
### 使用方法
|
||||
|
||||
#### 1. 安装依赖
|
||||
|
||||
```bash
|
||||
cd admin/docs
|
||||
npm install
|
||||
```
|
||||
|
||||
#### 2. 运行自动生成脚本
|
||||
|
||||
```bash
|
||||
# 使用默认配置（http://localhost:3000）
|
||||
npm run generate-api
|
||||
|
||||
# 指定后端服务地址
|
||||
BACKEND_URL=http://your-backend-url npm run generate-api
|
||||
|
||||
# 开发环境快捷命令
|
||||
npm run generate-api:dev
|
||||
```
|
||||
|
||||
#### 3. 查看生成结果
|
||||
|
||||
生成完成后，会在以下目录生成文档：
|
||||
|
||||
```
|
||||
admin/docs/src/wwjcloud/openapi/api/
|
||||
├── api/ # 前台 API (对应后端 /api/)
|
||||
│ ├── index.md # 前台 API 概览
|
||||
│ ├── member.md # 会员管理 API (自动生成)
|
||||
│ ├── auth.md # 认证 API (自动生成)
|
||||
│ └── ... # 其他模块 API
|
||||
└── adminapi/ # 后台 API (对应后端 /adminapi/)
|
||||
├── index.md # 后台 API 概览
|
||||
├── member.md # 会员管理 API (自动生成)
|
||||
├── admin.md # 管理员 API (自动生成)
|
||||
└── ... # 其他模块 API
|
||||
```
|
||||
|
||||
### 配置说明
|
||||
|
||||
#### 环境变量
|
||||
|
||||
- `BACKEND_URL`: 后端服务地址，默认为 `http://localhost:3000`
|
||||
|
||||
#### API 分组配置
|
||||
|
||||
脚本会自动处理以下 API 分组：
|
||||
|
||||
- **前台 API**: `/api-json` (对应后端 `/api/` 路径)
|
||||
- **后台 API**: `/adminapi-json` (对应后端 `/adminapi/` 路径)
|
||||
|
||||
### 自动生成内容
|
||||
|
||||
生成的文档包含：
|
||||
|
||||
- **API 接口列表**: 按模块自动分组
|
||||
- **请求参数说明**: 自动解析 Swagger 参数定义
|
||||
- **响应示例**: 统一的响应格式
|
||||
- **接口描述**: 从 Swagger 自动提取
|
||||
- **在线测试链接**: 指向后端 Swagger UI
|
||||
|
||||
### 目录结构对齐
|
||||
|
||||
前端文档目录结构与后端保持一致：
|
||||
|
||||
```
|
||||
后端路径 前端文档路径
|
||||
/api/ → /api/
|
||||
/adminapi/ → /adminapi/
|
||||
```
|
||||
|
||||
### 注意事项
|
||||
|
||||
1. **后端服务必须运行**: 确保后端服务已启动并可访问
|
||||
2. **Swagger 配置**: 确保后端已正确配置 Swagger 文档
|
||||
3. **网络连接**: 确保能够访问后端服务地址
|
||||
4. **权限问题**: 某些 API 可能需要认证才能访问
|
||||
|
||||
### 故障排除
|
||||
|
||||
#### 1. 连接失败
|
||||
|
||||
```bash
|
||||
# 检查后端服务是否运行
|
||||
curl http://localhost:3000/api-json
|
||||
|
||||
# 检查网络连接
|
||||
ping localhost
|
||||
```
|
||||
|
||||
#### 2. 权限问题
|
||||
|
||||
如果 API 需要认证，可以在脚本中添加认证头：
|
||||
|
||||
```javascript
|
||||
// 在 generate-api-docs.js 中修改
|
||||
const response = await axios.get(url, {
|
||||
headers: {
|
||||
'Authorization': 'Bearer your-token'
|
||||
}
|
||||
});
|
||||
```
|
||||
|
||||
#### 3. 文档生成失败
|
||||
|
||||
检查输出目录权限：
|
||||
|
||||
```bash
|
||||
# 确保目录存在且有写权限
|
||||
ls -la admin/docs/src/wwjcloud/openapi/api/
|
||||
```
|
||||
|
||||
### 自定义配置
|
||||
|
||||
如需自定义配置，可以修改 `generate-api-docs.js` 中的 `config` 对象：
|
||||
|
||||
```javascript
|
||||
const config = {
|
||||
// 修改后端服务地址
|
||||
backendUrl: process.env.BACKEND_URL || 'http://localhost:3000',
|
||||
|
||||
// 修改输出目录
|
||||
docsDir: path.join(__dirname, '../src/wwjcloud/openapi/api'),
|
||||
|
||||
// 添加新的 API 分组
|
||||
apiGroups: {
|
||||
// ... 现有配置
|
||||
custom: {
|
||||
name: '自定义 API',
|
||||
swaggerPath: '/custom-json',
|
||||
outputDir: 'custom',
|
||||
prefix: '/custom'
|
||||
}
|
||||
}
|
||||
};
|
||||
```
|
||||
|
||||
### 集成到 CI/CD
|
||||
|
||||
可以将自动生成脚本集成到 CI/CD 流程中：
|
||||
|
||||
```yaml
|
||||
# GitHub Actions 示例
|
||||
- name: Generate API Docs
|
||||
run: |
|
||||
cd admin/docs
|
||||
npm install
|
||||
npm run generate-api
|
||||
env:
|
||||
BACKEND_URL: ${{ secrets.BACKEND_URL }}
|
||||
```
|
||||
|
||||
### 相关文件
|
||||
|
||||
- `generate-api-docs.js`: 主自动生成脚本
|
||||
- `package.json`: 脚本命令配置
|
||||
- `src/wwjcloud/openapi/api/`: 生成的文档目录
|
||||
- `.vitepress/config/zh.mts`: 侧边栏配置
|
||||
186
admin/docs/scripts/generate-api-docs.js
Normal file
186
admin/docs/scripts/generate-api-docs.js
Normal file
@@ -0,0 +1,186 @@
|
||||
#!/usr/bin/env node
|
||||
|
||||
/**
|
||||
* API 文档自动生成脚本
|
||||
* 从后端 Swagger 自动生成前端文档
|
||||
*/
|
||||
|
||||
const fs = require('fs');
|
||||
const path = require('path');
|
||||
const axios = require('axios');
|
||||
|
||||
// 配置
|
||||
const config = {
|
||||
backendUrl: process.env.BACKEND_URL || 'http://localhost:3000',
|
||||
docsDir: path.join(__dirname, '../src/wwjcloud/openapi/api'),
|
||||
apiGroups: {
|
||||
unified: {
|
||||
name: '统一 API',
|
||||
swaggerPath: '/docs-json',
|
||||
outputDir: 'unified',
|
||||
prefix: ''
|
||||
}
|
||||
}
|
||||
};
|
||||
|
||||
/**
|
||||
* 获取 Swagger JSON
|
||||
*/
|
||||
async function getSwaggerJson(group) {
|
||||
try {
|
||||
const url = `${config.backendUrl}${group.swaggerPath}`;
|
||||
console.log(`获取 ${group.name} API: ${url}`);
|
||||
const response = await axios.get(url);
|
||||
return response.data;
|
||||
} catch (error) {
|
||||
console.error(`获取失败: ${error.message}`);
|
||||
return null;
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* 生成模块文档
|
||||
*/
|
||||
function generateModuleDoc(group, tag, paths) {
|
||||
const moduleName = tag.name;
|
||||
let markdown = `---
|
||||
title: ${moduleName} API
|
||||
description: ${tag.description || `${moduleName} 相关接口`}
|
||||
---
|
||||
|
||||
# ${moduleName} API
|
||||
|
||||
::: info ${moduleName}
|
||||
|
||||
${tag.description || `${moduleName} 相关接口`}
|
||||
|
||||
:::
|
||||
|
||||
## API 列表
|
||||
|
||||
`;
|
||||
|
||||
// 查找该标签下的接口
|
||||
Object.keys(paths).forEach(path => {
|
||||
Object.keys(paths[path]).forEach(method => {
|
||||
const operation = paths[path][method];
|
||||
if (operation.tags && operation.tags.includes(tag.name)) {
|
||||
markdown += generateApiDoc(path, method, operation);
|
||||
}
|
||||
});
|
||||
});
|
||||
|
||||
return markdown;
|
||||
}
|
||||
|
||||
/**
|
||||
* 生成单个 API 文档
|
||||
*/
|
||||
function generateApiDoc(path, method, operation) {
|
||||
const summary = operation.summary || operation.operationId || '未命名接口';
|
||||
|
||||
let doc = `### ${summary}\n\n`;
|
||||
doc += `**接口**: \`${method.toUpperCase()} ${path}\`\n\n`;
|
||||
|
||||
if (operation.description) {
|
||||
doc += `**描述**: ${operation.description}\n\n`;
|
||||
}
|
||||
|
||||
// 请求参数
|
||||
if (operation.parameters && operation.parameters.length > 0) {
|
||||
doc += `**参数**:\n\n`;
|
||||
doc += `| 参数 | 类型 | 必填 | 说明 |\n`;
|
||||
doc += `|------|------|------|------|\n`;
|
||||
|
||||
operation.parameters.forEach(param => {
|
||||
const required = param.required ? '是' : '否';
|
||||
const type = param.type || param.schema?.type || 'string';
|
||||
doc += `| ${param.name} | ${type} | ${required} | ${param.description || ''} |\n`;
|
||||
});
|
||||
doc += `\n`;
|
||||
}
|
||||
|
||||
// 请求体
|
||||
if (operation.requestBody) {
|
||||
doc += `**请求体**:\n\n`;
|
||||
doc += `\`\`\`json\n`;
|
||||
doc += `{\n`;
|
||||
doc += ` // 请求数据\n`;
|
||||
doc += `}\n`;
|
||||
doc += `\`\`\`\n\n`;
|
||||
}
|
||||
|
||||
// 响应
|
||||
doc += `**响应**:\n\n`;
|
||||
doc += `\`\`\`json\n`;
|
||||
doc += `{\n`;
|
||||
doc += ` "code": 200,\n`;
|
||||
doc += ` "message": "success",\n`;
|
||||
doc += ` "data": {\n`;
|
||||
doc += ` // 响应数据\n`;
|
||||
doc += ` }\n`;
|
||||
doc += `}\n`;
|
||||
doc += `\`\`\`\n\n`;
|
||||
doc += `---\n\n`;
|
||||
|
||||
return doc;
|
||||
}
|
||||
|
||||
/**
|
||||
* 保存文档
|
||||
*/
|
||||
function saveDocument(outputPath, content) {
|
||||
try {
|
||||
const dir = path.dirname(outputPath);
|
||||
if (!fs.existsSync(dir)) {
|
||||
fs.mkdirSync(dir, { recursive: true });
|
||||
}
|
||||
fs.writeFileSync(outputPath, content, 'utf8');
|
||||
console.log(`已保存: ${outputPath}`);
|
||||
} catch (error) {
|
||||
console.error(`保存失败: ${error.message}`);
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* 主函数
|
||||
*/
|
||||
async function main() {
|
||||
console.log('开始自动生成 API 文档...\n');
|
||||
|
||||
for (const [key, group] of Object.entries(config.apiGroups)) {
|
||||
console.log(`处理 ${group.name}...`);
|
||||
|
||||
const swaggerData = await getSwaggerJson(group);
|
||||
if (!swaggerData) {
|
||||
console.log(`跳过 ${group.name}\n`);
|
||||
continue;
|
||||
}
|
||||
|
||||
const tags = swaggerData.tags || [];
|
||||
const paths = swaggerData.paths || {};
|
||||
|
||||
// 为每个标签生成文档
|
||||
for (const tag of tags) {
|
||||
const moduleName = tag.name.toLowerCase().replace(/\s+/g, '-');
|
||||
const content = generateModuleDoc(group, tag, paths);
|
||||
const outputPath = path.join(config.docsDir, group.outputDir, `${moduleName}.md`);
|
||||
saveDocument(outputPath, content);
|
||||
}
|
||||
|
||||
console.log(`${group.name} 完成\n`);
|
||||
}
|
||||
|
||||
console.log('API 文档生成完成！');
|
||||
console.log('访问: http://localhost:6173/wwjcloud/openapi/api/');
|
||||
}
|
||||
|
||||
// 运行
|
||||
if (require.main === module) {
|
||||
main().catch(error => {
|
||||
console.error('执行失败:', error);
|
||||
process.exit(1);
|
||||
});
|
||||
}
|
||||
|
||||
module.exports = { config, getSwaggerJson, generateModuleDoc };
|
||||
419
admin/docs/scripts/sync-api-docs.js
Normal file
419
admin/docs/scripts/sync-api-docs.js
Normal file
@@ -0,0 +1,419 @@
|
||||
#!/usr/bin/env node
|
||||
|
||||
/**
|
||||
* API 文档自动生成脚本
|
||||
* 使用 OpenAPI 从后端 Swagger 自动生成前端文档
|
||||
*/
|
||||
|
||||
const fs = require('fs');
|
||||
const path = require('path');
|
||||
const axios = require('axios');
|
||||
|
||||
// 配置
|
||||
const config = {
|
||||
// 后端服务地址
|
||||
backendUrl: process.env.BACKEND_URL || 'http://localhost:3000',
|
||||
|
||||
// 文档输出目录
|
||||
docsDir: path.join(__dirname, '../src/wwjcloud/openapi/api'),
|
||||
|
||||
// API 分组配置
|
||||
apiGroups: {
|
||||
api: {
|
||||
name: '前台 API',
|
||||
swaggerPath: '/api/api-json',
|
||||
outputDir: 'frontend',
|
||||
description: '前台用户访问的 API 接口',
|
||||
prefix: '/api'
|
||||
},
|
||||
adminapi: {
|
||||
name: '后台 API',
|
||||
swaggerPath: '/api/adminapi-json',
|
||||
outputDir: 'adminapi',
|
||||
description: '后台管理员访问的 API 接口',
|
||||
prefix: '/adminapi'
|
||||
}
|
||||
}
|
||||
};
|
||||
|
||||
/**
|
||||
* 获取 Swagger JSON
|
||||
*/
|
||||
async function getSwaggerJson(group) {
|
||||
try {
|
||||
const url = `${config.backendUrl}${group.swaggerPath}`;
|
||||
console.log(`正在获取 ${group.name} API 文档: ${url}`);
|
||||
|
||||
const response = await axios.get(url);
|
||||
return response.data;
|
||||
} catch (error) {
|
||||
console.error(`获取 ${group.name} API 文档失败:`, error.message);
|
||||
return null;
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* 生成 API 概览文档
|
||||
*/
|
||||
function generateOverview(group) {
|
||||
return `---
|
||||
title: ${group.name}
|
||||
description: ${group.description}
|
||||
---
|
||||
|
||||
# ${group.name}
|
||||
|
||||
::: info ${group.name} 说明
|
||||
|
||||
${group.description}
|
||||
|
||||
:::
|
||||
|
||||
## API 基础信息
|
||||
|
||||
- **基础路径**: \`${group.prefix}/\`
|
||||
- **认证方式**: JWT Bearer Token
|
||||
- **内容类型**: \`application/json\`
|
||||
- **字符编码**: \`UTF-8\`
|
||||
|
||||
## 模块列表
|
||||
|
||||
::: tip 自动生成
|
||||
|
||||
此文档由后端 Swagger 自动生成，包含最新的 API 接口信息。
|
||||
|
||||
:::
|
||||
|
||||
## 认证流程
|
||||
|
||||
### 获取 Token
|
||||
|
||||
\`\`\`http
|
||||
POST ${group.prefix}/auth/login
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"username": "user@example.com",
|
||||
"password": "password123"
|
||||
}
|
||||
\`\`\`
|
||||
|
||||
## 响应格式
|
||||
|
||||
所有 API 都遵循统一的响应格式：
|
||||
|
||||
\`\`\`json
|
||||
{
|
||||
"code": 200,
|
||||
"message": "success",
|
||||
"data": {
|
||||
// 具体数据
|
||||
}
|
||||
}
|
||||
\`\`\`
|
||||
|
||||
## 错误处理
|
||||
|
||||
API 错误响应格式：
|
||||
|
||||
\`\`\`json
|
||||
{
|
||||
"code": 400,
|
||||
"message": "参数错误",
|
||||
"data": null
|
||||
}
|
||||
\`\`\`
|
||||
|
||||
## 状态码说明
|
||||
|
||||
| 状态码 | 说明 |
|
||||
|--------|------|
|
||||
| 200 | 请求成功 |
|
||||
| 201 | 创建成功 |
|
||||
| 400 | 请求参数错误 |
|
||||
| 401 | 未授权 |
|
||||
| 403 | 禁止访问 |
|
||||
| 404 | 资源不存在 |
|
||||
| 500 | 服务器内部错误 |
|
||||
|
||||
## 开发工具
|
||||
|
||||
### Swagger UI
|
||||
|
||||
访问 \`${config.backendUrl}${group.prefix}\` 查看完整的 API 文档和在线测试功能。
|
||||
|
||||
### 在线测试
|
||||
|
||||
每个 API 分组都提供 Swagger UI 界面，支持：
|
||||
|
||||
- API 文档查看
|
||||
- 在线测试
|
||||
- 参数验证
|
||||
- 响应示例
|
||||
`;
|
||||
}
|
||||
|
||||
/**
|
||||
* 生成模块 API 文档
|
||||
*/
|
||||
function generateModuleDoc(group, tag, paths) {
|
||||
const moduleName = tag.name.toLowerCase().replace(/\s+/g, '-');
|
||||
const moduleDesc = tag.description || `${moduleName} 相关接口`;
|
||||
|
||||
let markdown = `---
|
||||
title: ${moduleName} API
|
||||
description: ${moduleDesc}
|
||||
---
|
||||
|
||||
# ${moduleName} API
|
||||
|
||||
::: info ${moduleName} API
|
||||
|
||||
${moduleDesc}
|
||||
|
||||
:::
|
||||
|
||||
## 基础信息
|
||||
|
||||
- **模块路径**: \`${group.prefix}/${moduleName.toLowerCase()}/\`
|
||||
- **认证方式**: JWT Bearer Token（部分接口需要）
|
||||
- **内容类型**: \`application/json\`
|
||||
|
||||
## API 列表
|
||||
|
||||
`;
|
||||
|
||||
// 查找该标签下的所有接口
|
||||
Object.keys(paths).forEach(path => {
|
||||
Object.keys(paths[path]).forEach(method => {
|
||||
const operation = paths[path][method];
|
||||
|
||||
if (operation.tags && operation.tags.includes(tag.name)) {
|
||||
markdown += generateApiDoc(path, method, operation, group.prefix);
|
||||
}
|
||||
});
|
||||
});
|
||||
|
||||
return markdown;
|
||||
}
|
||||
|
||||
/**
|
||||
* 生成单个 API 文档
|
||||
*/
|
||||
function generateApiDoc(path, method, operation, prefix) {
|
||||
const summary = operation.summary || operation.operationId || '未命名接口';
|
||||
const description = operation.description || '';
|
||||
|
||||
let doc = `### ${summary}\n\n`;
|
||||
|
||||
// 接口地址
|
||||
doc += `**接口地址**: \`${method.toUpperCase()} ${path}\`\n\n`;
|
||||
|
||||
// 接口描述
|
||||
if (description) {
|
||||
doc += `**接口描述**: ${description}\n\n`;
|
||||
}
|
||||
|
||||
// 请求参数
|
||||
if (operation.parameters && operation.parameters.length > 0) {
|
||||
doc += `**请求参数**:\n\n`;
|
||||
|
||||
if (method === 'get') {
|
||||
doc += `| 参数 | 类型 | 必填 | 说明 |\n`;
|
||||
doc += `|------|------|------|------|\n`;
|
||||
|
||||
operation.parameters.forEach(param => {
|
||||
const required = param.required ? '是' : '否';
|
||||
const type = param.type || param.schema?.type || 'string';
|
||||
doc += `| ${param.name} | ${type} | ${required} | ${param.description || ''} |\n`;
|
||||
});
|
||||
doc += `\n`;
|
||||
} else {
|
||||
doc += `\`\`\`json\n`;
|
||||
doc += `{\n`;
|
||||
operation.parameters.forEach((param, index) => {
|
||||
const comma = index < operation.parameters.length - 1 ? ',' : '';
|
||||
const type = param.type || param.schema?.type || 'string';
|
||||
doc += ` "${param.name}": "${type}"${comma}\n`;
|
||||
});
|
||||
doc += `}\n`;
|
||||
doc += `\`\`\`\n\n`;
|
||||
}
|
||||
}
|
||||
|
||||
// 请求体
|
||||
if (operation.requestBody) {
|
||||
doc += `**请求体**:\n\n`;
|
||||
doc += `\`\`\`json\n`;
|
||||
if (operation.requestBody.content && operation.requestBody.content['application/json']) {
|
||||
const schema = operation.requestBody.content['application/json'].schema;
|
||||
if (schema && schema.properties) {
|
||||
doc += `{\n`;
|
||||
Object.keys(schema.properties).forEach((prop, index) => {
|
||||
const comma = index < Object.keys(schema.properties).length - 1 ? ',' : '';
|
||||
const type = schema.properties[prop].type || 'string';
|
||||
doc += ` "${prop}": "${type}"${comma}\n`;
|
||||
});
|
||||
doc += `}\n`;
|
||||
} else {
|
||||
doc += `{\n`;
|
||||
doc += ` // 请求体内容\n`;
|
||||
doc += `}\n`;
|
||||
}
|
||||
} else {
|
||||
doc += `{\n`;
|
||||
doc += ` // 请求体内容\n`;
|
||||
doc += `}\n`;
|
||||
}
|
||||
doc += `\`\`\`\n\n`;
|
||||
}
|
||||
|
||||
// 响应示例
|
||||
if (operation.responses) {
|
||||
doc += `**响应示例**:\n\n`;
|
||||
const successResponse = operation.responses['200'] || operation.responses['201'];
|
||||
if (successResponse) {
|
||||
doc += `\`\`\`json\n`;
|
||||
doc += `{\n`;
|
||||
doc += ` "code": 200,\n`;
|
||||
doc += ` "message": "success",\n`;
|
||||
doc += ` "data": {\n`;
|
||||
if (successResponse.content && successResponse.content['application/json']) {
|
||||
const schema = successResponse.content['application/json'].schema;
|
||||
if (schema && schema.properties) {
|
||||
Object.keys(schema.properties).forEach((prop, index) => {
|
||||
const comma = index < Object.keys(schema.properties).length - 1 ? ',' : '';
|
||||
const type = schema.properties[prop].type || 'string';
|
||||
doc += ` "${prop}": "${type}"${comma}\n`;
|
||||
});
|
||||
} else {
|
||||
doc += ` // 响应数据\n`;
|
||||
}
|
||||
} else {
|
||||
doc += ` // 响应数据\n`;
|
||||
}
|
||||
doc += ` }\n`;
|
||||
doc += `}\n`;
|
||||
doc += `\`\`\`\n\n`;
|
||||
}
|
||||
}
|
||||
|
||||
doc += `---\n\n`;
|
||||
return doc;
|
||||
}
|
||||
|
||||
/**
|
||||
* 保存文档到文件
|
||||
*/
|
||||
function saveDocument(outputPath, content) {
|
||||
try {
|
||||
// 确保目录存在
|
||||
const dir = path.dirname(outputPath);
|
||||
if (!fs.existsSync(dir)) {
|
||||
fs.mkdirSync(dir, { recursive: true });
|
||||
}
|
||||
|
||||
fs.writeFileSync(outputPath, content, 'utf8');
|
||||
console.log(`文档已保存: ${outputPath}`);
|
||||
} catch (error) {
|
||||
console.error(`保存文档失败: ${outputPath}`, error.message);
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* 更新侧边栏配置
|
||||
*/
|
||||
function updateSidebar(group, tags) {
|
||||
const sidebarPath = path.join(__dirname, '../.vitepress/config/zh.mts');
|
||||
let sidebarContent = fs.readFileSync(sidebarPath, 'utf8');
|
||||
|
||||
// 生成模块链接
|
||||
const moduleLinks = tags.map(tag => {
|
||||
const moduleName = tag.name.toLowerCase().replace(/\s+/g, '-');
|
||||
return ` { link: 'openapi/api/${group.outputDir}/${moduleName}', text: '${tag.name} API' }`;
|
||||
}).join(',\n');
|
||||
|
||||
// 更新侧边栏配置
|
||||
const sidebarPattern = new RegExp(`(text: '${group.name}',\\s*items: \\[\\s*\\{[^}]+\\},?\\s*)(\\])`, 's');
|
||||
const replacement = `$1,\n${moduleLinks}\n $2`;
|
||||
|
||||
if (sidebarContent.match(sidebarPattern)) {
|
||||
sidebarContent = sidebarContent.replace(sidebarPattern, replacement);
|
||||
fs.writeFileSync(sidebarPath, sidebarContent, 'utf8');
|
||||
console.log(`侧边栏配置已更新: ${group.name}`);
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* 主函数
|
||||
*/
|
||||
async function main() {
|
||||
console.log('开始自动生成 API 文档...\n');
|
||||
|
||||
for (const [key, group] of Object.entries(config.apiGroups)) {
|
||||
console.log(`处理 ${group.name}...`);
|
||||
|
||||
// 获取 Swagger JSON（统一）
|
||||
const swaggerData = await getSwaggerJson(group);
|
||||
if (!swaggerData) {
|
||||
console.log(`跳过 ${group.name}，无法获取数据\n`);
|
||||
continue;
|
||||
}
|
||||
|
||||
// 基于分组前缀过滤 paths
|
||||
const filterByPrefix = (doc, prefix) => {
|
||||
const cloned = JSON.parse(JSON.stringify(doc));
|
||||
const filteredPaths = {};
|
||||
Object.keys(cloned.paths || {}).forEach((p) => {
|
||||
if (p.startsWith(prefix)) filteredPaths[p] = cloned.paths[p];
|
||||
});
|
||||
cloned.paths = filteredPaths;
|
||||
return cloned;
|
||||
};
|
||||
|
||||
const filtered = filterByPrefix(swaggerData, group.prefix + '/');
|
||||
|
||||
// 生成概览文档
|
||||
const overviewContent = generateOverview(group);
|
||||
const overviewPath = path.join(config.docsDir, group.outputDir, 'index.md');
|
||||
saveDocument(overviewPath, overviewContent);
|
||||
|
||||
// 按标签生成模块文档
|
||||
const tags = filtered.tags || [];
|
||||
const paths = filtered.paths || {};
|
||||
|
||||
for (const tag of tags) {
|
||||
const moduleName = tag.name.toLowerCase().replace(/\s+/g, '-');
|
||||
const moduleContent = generateModuleDoc(group, tag, paths);
|
||||
const modulePath = path.join(config.docsDir, group.outputDir, `${moduleName}.md`);
|
||||
saveDocument(modulePath, moduleContent);
|
||||
}
|
||||
|
||||
// 更新侧边栏配置
|
||||
updateSidebar(group, tags);
|
||||
|
||||
console.log(`${group.name} 处理完成\n`);
|
||||
}
|
||||
|
||||
console.log('API 文档自动生成完成！');
|
||||
console.log('\n下一步：');
|
||||
console.log('1. 启动文档服务: npm run dev');
|
||||
console.log('2. 访问: http://localhost:6173/wwjcloud/openapi/api/');
|
||||
}
|
||||
|
||||
// 运行脚本
|
||||
if (require.main === module) {
|
||||
main().catch(error => {
|
||||
console.error('脚本执行失败:', error);
|
||||
process.exit(1);
|
||||
});
|
||||
}
|
||||
|
||||
module.exports = {
|
||||
config,
|
||||
getSwaggerJson,
|
||||
generateOverview,
|
||||
generateModuleDoc,
|
||||
saveDocument,
|
||||
updateSidebar
|
||||
};
|
||||
@@ -90,52 +90,30 @@ import { h } from 'vue';
|
||||
import { globalShareState, IconPicker } from '@vben/common-ui';
|
||||
import { $t } from '@vben/locales';
|
||||
|
||||
const AutoComplete = defineAsyncComponent(
|
||||
() => import('ant-design-vue/es/auto-complete'),
|
||||
);
|
||||
const Button = defineAsyncComponent(() => import('ant-design-vue/es/button'));
|
||||
const Checkbox = defineAsyncComponent(
|
||||
() => import('ant-design-vue/es/checkbox'),
|
||||
);
|
||||
const CheckboxGroup = defineAsyncComponent(() =>
|
||||
import('ant-design-vue/es/checkbox').then((res) => res.CheckboxGroup),
|
||||
);
|
||||
const DatePicker = defineAsyncComponent(
|
||||
() => import('ant-design-vue/es/date-picker'),
|
||||
);
|
||||
const Divider = defineAsyncComponent(() => import('ant-design-vue/es/divider'));
|
||||
const Input = defineAsyncComponent(() => import('ant-design-vue/es/input'));
|
||||
const InputNumber = defineAsyncComponent(
|
||||
() => import('ant-design-vue/es/input-number'),
|
||||
);
|
||||
const InputPassword = defineAsyncComponent(() =>
|
||||
import('ant-design-vue/es/input').then((res) => res.InputPassword),
|
||||
);
|
||||
const Mentions = defineAsyncComponent(
|
||||
() => import('ant-design-vue/es/mentions'),
|
||||
);
|
||||
const Radio = defineAsyncComponent(() => import('ant-design-vue/es/radio'));
|
||||
const RadioGroup = defineAsyncComponent(() =>
|
||||
import('ant-design-vue/es/radio').then((res) => res.RadioGroup),
|
||||
);
|
||||
const RangePicker = defineAsyncComponent(() =>
|
||||
import('ant-design-vue/es/date-picker').then((res) => res.RangePicker),
|
||||
);
|
||||
const Rate = defineAsyncComponent(() => import('ant-design-vue/es/rate'));
|
||||
const Select = defineAsyncComponent(() => import('ant-design-vue/es/select'));
|
||||
const Space = defineAsyncComponent(() => import('ant-design-vue/es/space'));
|
||||
const Switch = defineAsyncComponent(() => import('ant-design-vue/es/switch'));
|
||||
const Textarea = defineAsyncComponent(() =>
|
||||
import('ant-design-vue/es/input').then((res) => res.Textarea),
|
||||
);
|
||||
const TimePicker = defineAsyncComponent(
|
||||
() => import('ant-design-vue/es/time-picker'),
|
||||
);
|
||||
const TreeSelect = defineAsyncComponent(
|
||||
() => import('ant-design-vue/es/tree-select'),
|
||||
);
|
||||
const Upload = defineAsyncComponent(() => import('ant-design-vue/es/upload'));
|
||||
|
||||
import {
|
||||
AutoComplete,
|
||||
Button,
|
||||
Checkbox,
|
||||
CheckboxGroup,
|
||||
DatePicker,
|
||||
Divider,
|
||||
Input,
|
||||
InputNumber,
|
||||
InputPassword,
|
||||
Mentions,
|
||||
notification,
|
||||
Radio,
|
||||
RadioGroup,
|
||||
RangePicker,
|
||||
Rate,
|
||||
Select,
|
||||
Space,
|
||||
Switch,
|
||||
Textarea,
|
||||
TimePicker,
|
||||
TreeSelect,
|
||||
Upload,
|
||||
} from 'ant-design-vue';
|
||||
|
||||
const withDefaultPlaceholder = <T extends Component>(
|
||||
component: T,
|
||||
@@ -326,12 +304,10 @@ useVbenForm 返回的第二个参数，是一个对象，包含了一些表单
|
||||
|
||||
| 属性名 | 描述 | 类型 | 默认值 |
|
||||
| --- | --- | --- | --- |
|
||||
| layout | 表单项布局 | `'horizontal' \| 'vertical'\| 'inline'` | `horizontal` |
|
||||
| layout | 表单项布局 | `'horizontal' \| 'vertical'` | `horizontal` |
|
||||
| showCollapseButton | 是否显示折叠按钮 | `boolean` | `false` |
|
||||
| wrapperClass | 表单的布局，基于tailwindcss | `any` | - |
|
||||
| actionWrapperClass | 表单操作区域class | `any` | - |
|
||||
| actionLayout | 表单操作按钮位置 | `'newLine' \| 'rowEnd' \| 'inline'` | `rowEnd` |
|
||||
| actionPosition | 表单操作按钮对齐方式 | `'left' \| 'center' \| 'right'` | `right` |
|
||||
| handleReset | 表单重置回调 | `(values: Record<string, any>,) => Promise<void> \| void` | - |
|
||||
| handleSubmit | 表单提交回调 | `(values: Record<string, any>,) => Promise<void> \| void` | - |
|
||||
| handleValuesChange | 表单值变化回调 | `(values: Record<string, any>, fieldsChanged: string[]) => void` | - |
|
||||
|
||||
76
admin/docs/src/en/veben/index.md
Normal file
76
admin/docs/src/en/veben/index.md
Normal file
@@ -0,0 +1,76 @@
|
||||
---
|
||||
# https://vitepress.dev/reference/default-theme-home-page
|
||||
layout: home
|
||||
sidebar: false
|
||||
|
||||
hero:
|
||||
name: Vben Admin
|
||||
text: Enterprise-Level Management System Framework
|
||||
tagline: Fully Upgraded, Ready to Use, Simple and Efficient
|
||||
image:
|
||||
src: https://unpkg.com/@vbenjs/static-source@0.1.7/source/logo-v1.webp
|
||||
alt: Vben Admin
|
||||
actions:
|
||||
- theme: brand
|
||||
text: Get Started ->
|
||||
link: /en/guide/introduction/vben
|
||||
- theme: alt
|
||||
text: Live Preview
|
||||
link: https://www.vben.pro
|
||||
- theme: alt
|
||||
text: View on GitHub
|
||||
link: https://github.com/vbenjs/vue-vben-admin
|
||||
|
||||
features:
|
||||
- icon: 🚀
|
||||
title: Latest Technology Stack
|
||||
details: Based on the latest technology stack, including Vue3, Pinia, Vue Router, TypeScript, etc.
|
||||
link: /en/guide/introduction/quick-start
|
||||
linkText: Get Started
|
||||
- icon: 🦄
|
||||
title: Rich Configurations
|
||||
details: An enterprise-level frontend solution for middle and back-end systems, offering a wealth of components, templates, and various preference settings.
|
||||
link: /en/guide/essentials/settings
|
||||
linkText: Configuration Documentation
|
||||
- icon: 🎨
|
||||
title: Theme Customization
|
||||
details: Easily switch between various themes through simple configurations, catering to personalized needs.
|
||||
link: /en/guide/in-depth/theme
|
||||
linkText: Theme Documentation
|
||||
- icon: 🌐
|
||||
title: Internationalization
|
||||
details: Built-in internationalization support with multiple languages to meet global needs.
|
||||
link: /en/guide/in-depth/locale
|
||||
linkText: Internationalization Documentation
|
||||
- icon: 🔐
|
||||
title: Access Control
|
||||
details: Built-in access control solutions supporting various permission management methods to meet different access requirements.
|
||||
link: /en/guide/in-depth/access
|
||||
linkText: Access Documentation
|
||||
- title: Vite
|
||||
icon:
|
||||
src: /logos/vite.svg
|
||||
details: Modern frontend build tool with fast cold start and instant hot updates.
|
||||
link: https://vitejs.dev/
|
||||
linkText: Official Site
|
||||
- title: Shadcn UI
|
||||
icon:
|
||||
src: /logos/shadcn-ui.svg
|
||||
details: Core built on Shadcn UI + Tailwindcss, with business support for any UI framework.
|
||||
link: https://www.shadcn-vue.com/
|
||||
linkText: Official Site
|
||||
- title: Turbo Repo
|
||||
icon:
|
||||
src: /logos/turborepo.svg
|
||||
details: Standardized monorepo architecture using pnpm + monorepo + turbo for enterprise-level development standards.
|
||||
link: https://turbo.build/
|
||||
linkText: Official Site
|
||||
- title: Nitro Mock Server
|
||||
icon:
|
||||
src: /logos/nitro.svg
|
||||
details: Built-in Nitro Mock service makes your mock service more powerful.
|
||||
link: https://nitro.unjs.io/
|
||||
linkText: Official Site
|
||||
---
|
||||
|
||||
<VbenContributors />
|
||||
@@ -4,108 +4,84 @@ layout: home
|
||||
sidebar: false
|
||||
|
||||
hero:
|
||||
name: Vben Admin
|
||||
name: WWJCloud-Admin
|
||||
text: 企业级管理系统框架
|
||||
tagline: 全新升级，开箱即用，简单高效
|
||||
image:
|
||||
src: https://unpkg.com/@vbenjs/static-source@0.1.7/source/logo-v1.webp
|
||||
alt: Vben Admin
|
||||
src: https://t.wanwujie.cn/img/1/2025/08/24/68aad11c8deb7.webp
|
||||
alt: wwjcloud
|
||||
actions:
|
||||
- theme: brand
|
||||
text: 快速开始 ->
|
||||
link: /guide/introduction/vben
|
||||
link: /wwjcloud/guide/quick-start
|
||||
- theme: alt
|
||||
text: 在线预览
|
||||
link: https://www.vben.pro
|
||||
text: API 文档
|
||||
link: /wwjcloud/openapi/standards/restful
|
||||
- theme: alt
|
||||
text: 在 GitHub 查看
|
||||
link: https://github.com/vbenjs/vue-vben-admin
|
||||
- theme: alt
|
||||
text: DeepWiki 文档
|
||||
link: https://deepwiki.com/vbenjs/vue-vben-admin
|
||||
text: Vben Admin
|
||||
link: /guide/introduction/vben
|
||||
|
||||
features:
|
||||
- icon: 🚀
|
||||
title: 最新技术栈
|
||||
details: 基于 Vue3、Pinia、Vue Router、TypeScript、等最新技术栈。
|
||||
link: /guide/introduction/quick-start
|
||||
title: 现代化技术栈
|
||||
details: 基于 NestJS、TypeScript、TypeORM 等最新技术栈，提供企业级后端解决方案。
|
||||
link: /wwjcloud/guide/quick-start
|
||||
linkText: 快速开始
|
||||
- icon: 🦄
|
||||
title: 丰富的配置
|
||||
details: 企业级中后台前端解决方案，提供丰富的组件和模板以及 N 种偏好设置组合方案。
|
||||
link: /guide/essentials/settings
|
||||
linkText: 配置文档
|
||||
- icon: 🎨
|
||||
title: 主题定制
|
||||
details: 通过简单的配置，即可实现各种主题切换，满足个性化需求。
|
||||
link: /guide/in-depth/theme
|
||||
linkText: 主题文档
|
||||
- icon: 🔄
|
||||
title: Saas+独立版双架构
|
||||
details: 支持Saas多租户和独立部署两种架构模式，满足不同业务场景需求，提供灵活的部署选择。
|
||||
link: /wwjcloud/guide/architecture
|
||||
linkText: 架构说明
|
||||
- icon: 🏗️
|
||||
title: 开箱即用，内置模块化功能
|
||||
details: 采用分层架构设计，已搭建模块化架构系统开发底层，为业务开发提供完整的底层支撑。
|
||||
link: /wwjcloud/guide/development
|
||||
linkText: 开发指南
|
||||
- icon: 🌐
|
||||
title: 国际化
|
||||
details: 内置国际化方案，支持多语言切换，满足国际化需求。
|
||||
link: /guide/in-depth/locale
|
||||
linkText: 国际化文档
|
||||
title: 多语言支持
|
||||
details: 内置多语言系统，支持动态语言包加载，满足国际化需求。
|
||||
link: /wwjcloud/guide/concepts
|
||||
linkText: 基础概念
|
||||
- icon: 🔐
|
||||
title: 权限管理
|
||||
details: 内置权限管理方案，支持多种权限控制方式，满足各种权限需求。
|
||||
link: /guide/in-depth/access
|
||||
linkText: 权限文档
|
||||
- title: Vite
|
||||
details: 内置 RBAC 权限管理方案，支持多种权限控制方式，满足各种权限需求。
|
||||
link: /wwjcloud/guide/concepts
|
||||
linkText: 基础概念
|
||||
- icon: 📱
|
||||
title: 支持多端管理
|
||||
details: 基于UniAppX多平台，支持原生App、小程序、PC等多端统一管理和开发，一套代码多端运行。
|
||||
link: /wwjcloud/guide/multi-platform
|
||||
linkText: 多端开发
|
||||
- title: TypeORM
|
||||
icon:
|
||||
src: /logos/vite.svg
|
||||
details: 现代化的前端构建工具，快速冷启动，瞬间热更新。
|
||||
link: https://vitejs.dev/
|
||||
src: https://unpkg.com/wwjcloud@latest/source/icons/typeorm.svg
|
||||
details: 强大的 TypeScript ORM，支持多种数据库，提供完整的数据库操作功能。
|
||||
link: https://typeorm.io/
|
||||
linkText: 官方站点
|
||||
- title: Shadcn UI
|
||||
- title: 多应用+插件组合安装
|
||||
icon:
|
||||
src: /logos/shadcn-ui.svg
|
||||
details: 核心基于 Shadcn UI + Tailwindcss，业务可支持任意的 UI 框架。
|
||||
link: https://www.shadcn-vue.com/
|
||||
linkText: 官方站点
|
||||
- title: Turbo Repo
|
||||
src: https://unpkg.com/wwjcloud@latest/source/icons/mysql.svg
|
||||
details: 支持业务自定义和应用插件热插拔，提供灵活的应用扩展和插件管理功能。
|
||||
link: /wwjcloud/guide/plugins
|
||||
linkText: 插件开发
|
||||
- title: 自建编译服务
|
||||
icon:
|
||||
src: /logos/turborepo.svg
|
||||
details: 规范且标准的大仓架构，使用 pnpm + monorepo + turbo 工程管理模式，提供企业级开发规范。
|
||||
link: https://turbo.build/
|
||||
linkText: 官方站点
|
||||
- title: Nitro Mock Server
|
||||
icon:
|
||||
src: /logos/nitro.svg
|
||||
details: 内置 Nitro Mock 服务，让你的 mock 服务更加强大。
|
||||
link: https://nitro.unjs.io/
|
||||
linkText: 官方站点
|
||||
src: https://unpkg.com/wwjcloud@latest/source/icons/redis.svg
|
||||
details: 提供完整的编译服务搭建方案，支持自定义编译环境和构建流程，满足不同项目的编译需求。
|
||||
link: /wwjcloud/guide/build-service
|
||||
linkText: 编译服务
|
||||
---
|
||||
|
||||
<!-- <script setup>
|
||||
import {
|
||||
VPTeamPage,
|
||||
VPTeamPageTitle,
|
||||
VPTeamMembers,
|
||||
VPTeamPageSection
|
||||
} from 'vitepress/theme';
|
||||
<style>
|
||||
:root {
|
||||
--vp-home-hero-image-background-image: linear-gradient(
|
||||
-45deg,
|
||||
#78d8d1 50%,
|
||||
#5f6eed 50%
|
||||
);
|
||||
}
|
||||
|
||||
const members = [
|
||||
{
|
||||
avatar: 'https://avatars.githubusercontent.com/u/28132598?v=4',
|
||||
name: 'Vben',
|
||||
title: '创建者',
|
||||
desc: 'Vben Admin以及相关生态的作者，负责项目的整体开发。',
|
||||
links: [
|
||||
{ icon: 'github', link: 'https://github.com/anncwb' },
|
||||
]
|
||||
},
|
||||
]
|
||||
</script>
|
||||
|
||||
<VPTeamPage>
|
||||
<VPTeamPageTitle>
|
||||
<template #title>
|
||||
核心成员介绍
|
||||
</template>
|
||||
</VPTeamPageTitle>
|
||||
<VPTeamMembers
|
||||
:members="members"
|
||||
/>
|
||||
</VPTeamPage> -->
|
||||
|
||||
<VbenContributors />
|
||||
</style>
|
||||
|
||||
113
admin/docs/src/vben/guide/index.md
Normal file
113
admin/docs/src/vben/guide/index.md
Normal file
@@ -0,0 +1,113 @@
|
||||
---
|
||||
# https://vitepress.dev/reference/default-theme-home-page
|
||||
layout: home
|
||||
sidebar: false
|
||||
|
||||
hero:
|
||||
name: Vben Admin
|
||||
text: 企业级管理系统框架
|
||||
tagline: 全新升级，开箱即用，简单高效
|
||||
image:
|
||||
src: https://unpkg.com/@vbenjs/static-source@0.1.7/source/logo-v1.webp
|
||||
alt: Vben Admin
|
||||
actions:
|
||||
- theme: brand
|
||||
text: 快速开始 ->
|
||||
link: /guide/introduction/vben
|
||||
- theme: alt
|
||||
text: 在线预览
|
||||
link: https://www.vben.pro
|
||||
- theme: alt
|
||||
text: 在 GitHub 查看
|
||||
link: https://github.com/vbenjs/vue-vben-admin
|
||||
- theme: alt
|
||||
text: DeepWiki 文档
|
||||
link: https://deepwiki.com/vbenjs/vue-vben-admin
|
||||
|
||||
features:
|
||||
- icon: 🚀
|
||||
title: 最新技术栈
|
||||
details: 基于 Vue3、Pinia、Vue Router、TypeScript、等最新技术栈。
|
||||
link: /guide/introduction/quick-start
|
||||
linkText: 快速开始
|
||||
- icon: 🦄
|
||||
title: 丰富的配置
|
||||
details: 企业级中后台前端解决方案，提供丰富的组件和模板以及 N 种偏好设置组合方案。
|
||||
link: /guide/essentials/settings
|
||||
linkText: 配置文档
|
||||
- icon: 🎨
|
||||
title: 主题定制
|
||||
details: 通过简单的配置，即可实现各种主题切换，满足个性化需求。
|
||||
link: /guide/in-depth/theme
|
||||
linkText: 主题文档
|
||||
- icon: 🌐
|
||||
title: 国际化
|
||||
details: 内置国际化方案，支持多语言切换，满足国际化需求。
|
||||
link: /guide/in-depth/locale
|
||||
linkText: 国际化文档
|
||||
- icon: 🔐
|
||||
title: 权限管理
|
||||
details: 内置权限管理方案，支持多种权限控制方式，满足各种权限需求。
|
||||
link: /guide/in-depth/access
|
||||
linkText: 权限文档
|
||||
- title: Vite
|
||||
icon:
|
||||
src: /logos/vite.svg
|
||||
details: 现代化的前端构建工具，快速冷启动，瞬间热更新。
|
||||
link: https://vitejs.dev/
|
||||
linkText: 官方站点
|
||||
- title: Shadcn UI
|
||||
icon:
|
||||
src: /logos/shadcn-ui.svg
|
||||
details: 核心基于 Shadcn UI + Tailwindcss，业务可支持任意的 UI 框架。
|
||||
link: https://www.shadcn-vue.com/
|
||||
linkText: 官方站点
|
||||
- title: Turbo Repo
|
||||
icon:
|
||||
src: /logos/turborepo.svg
|
||||
details: 规范且标准的大仓架构，使用 pnpm + monorepo + turbo 工程管理模式，提供企业级开发规范。
|
||||
link: https://turbo.build/
|
||||
linkText: 官方站点
|
||||
- title: Nitro Mock Server
|
||||
icon:
|
||||
src: /logos/nitro.svg
|
||||
details: 内置 Nitro Mock 服务，让你的 mock 服务更加强大。
|
||||
link: https://nitro.unjs.io/
|
||||
linkText: 官方站点
|
||||
---
|
||||
|
||||
<!-- <script setup>
|
||||
import {
|
||||
VPTeamPage,
|
||||
VPTeamPageTitle,
|
||||
VPTeamMembers,
|
||||
VPTeamPageSection
|
||||
} from 'vitepress/theme';
|
||||
|
||||
const members = [
|
||||
{
|
||||
avatar: 'https://avatars.githubusercontent.com/u/28132598?v=4',
|
||||
name: 'Vben',
|
||||
title: '创建者',
|
||||
desc: 'Vben Admin以及相关生态的作者，负责项目的整体开发。',
|
||||
links: [
|
||||
{ icon: 'github', link: 'https://github.com/anncwb' },
|
||||
]
|
||||
},
|
||||
]
|
||||
</script>
|
||||
|
||||
<VPTeamPage>
|
||||
<VPTeamPageTitle>
|
||||
<template #title>
|
||||
核心成员介绍
|
||||
</template>
|
||||
</VPTeamPageTitle>
|
||||
<VPTeamMembers
|
||||
:members="members"
|
||||
/>
|
||||
</VPTeamPage> -->
|
||||
|
||||
<VbenContributors />
|
||||
|
||||
|
||||
21
admin/docs/src/wwjcloud/ai/checklists.md
Normal file
21
admin/docs/src/wwjcloud/ai/checklists.md
Normal file
@@ -0,0 +1,21 @@
|
||||
## 执行检查清单（给智能体）
|
||||
|
||||
### 开发前
|
||||
- [ ] 对齐 PHP 模块/接口/字段
|
||||
- [ ] 核对 DB 结构（表/字段/类型/索引）
|
||||
- [ ] 明确路由分端（/adminapi, /api）与守卫
|
||||
|
||||
### 开发中
|
||||
- [ ] 目录分层到位（Controller/Application/Core/Infrastructure/Entities/DTO）
|
||||
- [ ] 实体字段与 DB 一致；配置表仅用 `value(JSON)`
|
||||
- [ ] Controller 只路由+DTO 校验；不写业务/不碰 ORM
|
||||
- [ ] Application 负责编排与事务；Core 写规则；Infra 实现仓储与适配
|
||||
- [ ] 管理端控制器接 `JwtAuthGuard + RolesGuard`
|
||||
- [ ] 启用必要 Pipes（JSON/Timestamp）
|
||||
- [ ] 用例完成发布事件；耗时逻辑入队
|
||||
|
||||
### 开发后
|
||||
- [ ] `npm run build` 通过（无类型警告）
|
||||
- [ ] 单测/集成/e2e 通过；关键路径有覆盖
|
||||
- [ ] Swagger 注解完整
|
||||
- [ ] 变更清单与迁移说明
|
||||
21
admin/docs/src/wwjcloud/ai/index.md
Normal file
21
admin/docs/src/wwjcloud/ai/index.md
Normal file
@@ -0,0 +1,21 @@
|
||||
## WWJCloud AI 文档总览
|
||||
|
||||
### 目标
|
||||
- **统一规范**: 用 NestJS 的方式实现，与 PHP 业务/数据100%对齐。
|
||||
- **智能体协作**: 多个智能体基于同一规则、流程与工具偏好执行任务。
|
||||
|
||||
### 文档导航
|
||||
- 工作流程: ./workflow.md
|
||||
- 工具偏好: ./tooling.md
|
||||
- 规则规范: ./rules.md
|
||||
- 执行清单: ./checklists.md
|
||||
- 基础能力集成: ./integration.md
|
||||
|
||||
### 适用范围
|
||||
- 仓库: `wwjcloud/` 主后端及 `admin/apps/*` 示例
|
||||
- 模块: `common/*`, `core/*`, `config/*`, `vendor/*`
|
||||
|
||||
### 约定
|
||||
- 管理端路由: `/adminapi/{module}/...`
|
||||
- 前台端路由: `/api/{module}/...`
|
||||
- 配置表: `sys_config.value(JSON)`，禁止使用不存在字段（如 `config_value`, `app_type`）
|
||||
154
admin/docs/src/wwjcloud/ai/integration.md
Normal file
154
admin/docs/src/wwjcloud/ai/integration.md
Normal file
@@ -0,0 +1,154 @@
|
||||
## 基础能力集成（Kafka / Redis / 队列 / 事务）
|
||||
|
||||
### 总览
|
||||
- 目标: 将事件、任务、缓存、事务能力以统一规范接入 App/Core/Infrastructure 三层，替代“散落式调用”。
|
||||
- 约束: 由 Application 发起流程；Core 编排业务规则且不直接依赖外设；Infrastructure 提供具体实现。
|
||||
|
||||
### 1) 事务（TypeORM）
|
||||
- 发起层: Application（用例级事务边界）
|
||||
- 使用方式:
|
||||
```ts
|
||||
// application/xxx.app.service.ts
|
||||
constructor(private readonly dataSource: DataSource, private readonly core: XxxCoreService) {}
|
||||
|
||||
async runUseCase(dto: Dto) {
|
||||
return await this.dataSource.transaction(async (manager) => {
|
||||
// 将 manager 注入到仓储实现（通过请求域注入或方法透传）
|
||||
await this.core.handle(dto); // Core 内仅调用仓储接口
|
||||
});
|
||||
}
|
||||
```
|
||||
- 规范:
|
||||
- 事务只在 Application 层开启；Core 不直接操作事务对象
|
||||
- 多仓储参与时基于同一 `EntityManager`
|
||||
|
||||
### 2) 队列（Bull/BullMQ 或 DB 队列）
|
||||
- 发起层: Application（用例结束后入队）
|
||||
- 接入点: `UnifiedQueueService` 或具体 Provider（如 `BullQueueProvider`/`DatabaseQueueProvider`）
|
||||
```ts
|
||||
// application/xxx.app.service.ts
|
||||
constructor(private readonly queue: UnifiedQueueService) {}
|
||||
|
||||
await this.queue.addJob('media', 'generateThumbnail', { attId }, { attempts: 3, delay: 0 });
|
||||
```
|
||||
- 处理器建议放置:
|
||||
- `infrastructure/queues/xxx.processor.ts` 或独立消费模块
|
||||
- 规范:
|
||||
- 入队数据为最小必要字段（ID/键）；大对象存储DB再查
|
||||
|
||||
### 3) 事件（Kafka / DB Outbox）
|
||||
- 发起层: Application（领域事件在用例完成后发布）
|
||||
- 接入点: `DomainEventService`（绑定 `IEventBus`，默认 DB Outbox，可切 Kafka）
|
||||
```ts
|
||||
// application/xxx.app.service.ts
|
||||
constructor(private readonly events: DomainEventService) {}
|
||||
|
||||
await this.events.publishEvent(
|
||||
'system.settings.storage.updated',
|
||||
String(siteId),
|
||||
String(siteId),
|
||||
{ storageType },
|
||||
);
|
||||
```
|
||||
- 配置切换:
|
||||
- 通过 `EventBusModule` 的 provider 切换 `DatabaseEventBusProvider` ⇄ `KafkaEventBusProvider`
|
||||
- 规范:
|
||||
- 事件名格式: `domain.aggregate.action`
|
||||
- 载荷仅含必要业务字段，带上 `tenantId/siteId`
|
||||
|
||||
### 4) Redis（缓存/限流/幂等）
|
||||
- 发起层: Application（流程性控制）或 Infrastructure（技术性实现）
|
||||
- 接入点: `RedisProvider`（`vendor/redis`）
|
||||
- 常见场景:
|
||||
- 读多写少配置缓存：`sys_config` 读取后短缓存
|
||||
- 上传限流/防刷：基于 IP/UID 的计数器
|
||||
- 幂等：`SETNX` + 过期控制
|
||||
|
||||
### 5) 存储（本地/云）
|
||||
- 发起层: Application 调用 Core 规则后，委托 Infrastructure Provider 落地
|
||||
- 接入点: `infrastructure/providers/*` 或 `vendor/storage/*`（如 `LocalStorageAdapter`）
|
||||
- 规范:
|
||||
- Provider 通过接口注入，便于切换 OSS/COS/Qiniu
|
||||
|
||||
### 6) 在三层中的放置原则
|
||||
- Application: 事务、入队、发事件、协调多 Core 服务
|
||||
- Core: 纯业务规则/策略与仓储接口；不直接依赖 Kafka/Redis/队列
|
||||
- Infrastructure: 队列消费者、存储/HTTP/Redis 具体实现、TypeORM 仓储实现
|
||||
|
||||
### 7) 示例：Upload 模块接入
|
||||
- 用例: 上传完成 → 入库附件 → 入队生成缩略图
|
||||
```ts
|
||||
// application/upload.app.service.ts
|
||||
await this.dataSource.transaction(async (manager) => {
|
||||
const att = await this.core.validateAndPlan(fileMeta);
|
||||
await this.attachmentRepo.withManager(manager).save(att);
|
||||
});
|
||||
await this.queue.addJob('media', 'generateThumbnail', { attId: att.id });
|
||||
```
|
||||
|
||||
### 8) 示例：Settings.Storage 接入
|
||||
- 用例: 切换默认存储 → 写 `sys_config` → 发布事件 → 入队校验可用性
|
||||
```ts
|
||||
// application/storage-settings.app.service.ts
|
||||
await this.dataSource.transaction(async (manager) => {
|
||||
await this.core.ensureExclusiveDefault(type);
|
||||
await this.sysConfigRepo.withManager(manager).setValue(key, value);
|
||||
});
|
||||
await this.events.publishEvent('system.settings.storage.updated', String(siteId), String(siteId), { type });
|
||||
await this.queue.addJob('ops', 'validateStorage', { type, siteId });
|
||||
```
|
||||
|
||||
### 9) 配置与健康
|
||||
- 配置在 `VendorModule`/`EventBusModule` 注入；通过 `ConfigService` 读取连接信息
|
||||
- 健康检查：将 Redis/队列/事件写入健康聚合输出
|
||||
|
||||
### 10) 方案B：vendor/storage 标准结构（平台外设）
|
||||
```
|
||||
vendor/storage/
|
||||
├── index.ts # 统一导出(接口、Token、模块、适配器)
|
||||
├── storage.module.ts # 可配置模块(选择具体实现)
|
||||
├── tokens.ts # 注入Token常量(如 STORAGE_ADAPTER)
|
||||
├── interfaces/
|
||||
│ ├── storage-adapter.ts # 适配器接口(平台标准)
|
||||
│ └── types.ts # 通用类型(上传结果、签名参数等)
|
||||
├── adapters/
|
||||
│ ├── local.adapter.ts # 本地实现
|
||||
│ ├── aliyun-oss.adapter.ts # 阿里云实现
|
||||
│ ├── qcloud-cos.adapter.ts # 腾讯云实现
|
||||
│ └── qiniu.adapter.ts # 七牛云实现
|
||||
├── providers/
|
||||
│ ├── storage.provider.ts # 工厂: 按配置/站点解析适配器
|
||||
│ └── registry.ts # 多实例注册表 Map<siteId, adapter> + TTL
|
||||
├── health/storage.health.ts # 健康检查(各实现可选实现)
|
||||
├── config/schema.ts # 配置Schema(必需项校验)
|
||||
└── __tests__/
|
||||
├── storage.contract.spec.ts # 契约测试(接口一致性)
|
||||
└── adapters/*.spec.ts # 各实现最小测试
|
||||
```
|
||||
|
||||
- Token
|
||||
```ts
|
||||
export const STORAGE_ADAPTER = 'STORAGE_ADAPTER';
|
||||
```
|
||||
- 接口
|
||||
```ts
|
||||
export interface StorageAdapter {
|
||||
upload(params: { key: string; content: Buffer | NodeJS.ReadableStream; mime?: string }): Promise<{ url: string; key: string }>;
|
||||
delete(key: string): Promise<void>;
|
||||
signUpload?(params: { key: string; expiresSec?: number; mime?: string }): Promise<{ url: string; headers?: Record<string,string>; fields?: Record<string,string> }>;
|
||||
healthCheck?(): Promise<boolean>;
|
||||
}
|
||||
```
|
||||
- 按 site_id 解析（站点启用 > 跟随系统 > local 兜底）
|
||||
```ts
|
||||
function resolveAdapter(siteId: number): StorageAdapter {
|
||||
const enabled = readSiteEnabled(siteId); // storage_xxx with is_use
|
||||
const type = enabled?.type ?? readPlatformDefault();
|
||||
const options = enabled?.options ?? readPlatformOptions(type) ?? {};
|
||||
return registry.getOrCreate(siteId, type, options);
|
||||
}
|
||||
```
|
||||
- 本地隔离路径：`upload/site_{siteId}/...`
|
||||
- 健康检查：对活跃站点适配器定期 `healthCheck()` 并聚合到 Health
|
||||
|
||||
> 说明：方案B 将“三方存储”视为外设，接口与实现均在 vendor；业务通过 Token 注入与按站点解析工厂使用，core 无需暴露存储端口。
|
||||
98
admin/docs/src/wwjcloud/ai/mapping.md
Normal file
98
admin/docs/src/wwjcloud/ai/mapping.md
Normal file
@@ -0,0 +1,98 @@
|
||||
## 模块关系映射（PHP ↔ NestJS）
|
||||
|
||||
### 1) 职责映射总览
|
||||
|
||||
| 职责 | PHP（ThinkPHP风格） | NestJS（规范分层） | 备注 |
|
||||
|---|---|---|---|
|
||||
| 控制器 | `app/admin/controller/*`、`app/api/controller/*` | `controllers/adminapi/*`、`controllers/api/*` | 仅路由与DTO校验（Nest特有：Guards/Pipes/Interceptors） |
|
||||
| 用例编排/流程 | `app/*/service/*`（可分 admin/api） | `application/*`（可分 `AdminXxxAppService`/`ApiXxxAppService`） | 事务、聚合领域规则、发事件/入队 |
|
||||
| 通用业务规则 | `core/*` 或被两端复用的 service | `core/services/*` | 不依赖外设（DDD） |
|
||||
| 仓储接口 | 与模型耦合在一起 | `domain/repositories/*` | 定义端口（接口） |
|
||||
| 仓储实现 | 模型(Model)直连DB | `infrastructure/repositories/*.typeorm.repository.ts` | TypeORM 实现，注入接口 |
|
||||
| 实体/模型 | `app/*/model/*` | `entities/*`（TypeORM 实体） | 字段与DB 100%一致 |
|
||||
| 外部适配 | SDK/Driver 封装 | `infrastructure/providers/*` 或 `vendor/*` | 存储/HTTP/SMS等 |
|
||||
| 配置中心 | `sys_config` + 配置文件 | `settings/*` 统一读写 `sys_config.value(JSON)` | 禁止 `config_value`、`app_type` |
|
||||
|
||||
### 2) 目录映射（标准化）
|
||||
```
|
||||
your-module/
|
||||
├── your-module.module.ts # 模块定义（Nest特有）
|
||||
├── controllers/
|
||||
│ ├── adminapi/ # 后台控制器（/adminapi）
|
||||
│ └── api/ # 前台控制器（/api）
|
||||
├── application/ # 用例编排（admin/api可分）
|
||||
├── core/
|
||||
│ ├── services/ # 通用规则/策略（≈ PHP core）
|
||||
│ ├── repositories/ # 仓储接口（端口）
|
||||
│ └── models|policies/ # 值对象/策略（可选）
|
||||
├── infrastructure/
|
||||
│ ├── repositories/ # TypeORM 实现
|
||||
│ └── providers/ # 外部系统适配
|
||||
├── entities/ # TypeORM实体（DB一致）
|
||||
└── dto/ # DTO（class-validator）
|
||||
```
|
||||
|
||||
### 3) 命名映射规则
|
||||
- 应用层：`XxxAppService`（如 `AdminUploadAppService` / `ApiUploadAppService`）
|
||||
- Core层：`XxxCoreService`
|
||||
- 仓储接口：`XxxRepository`
|
||||
- 仓储实现：`XxxTypeormRepository`
|
||||
- 控制器：`XxxController`（位于 `controllers/adminapi|api`）
|
||||
- 配置键：常量化，如 `UPLOAD_CONFIG_KEY = 'upload'`，`STORAGE_LOCAL_KEY = 'storage_local'`
|
||||
|
||||
### 4) 映射示例：Upload 模块
|
||||
- PHP 心智：
|
||||
- admin/api 控制器 → 上传服务 → 模型写库（附件表）
|
||||
- NestJS 对应：
|
||||
- 控制器：`controllers/adminapi/upload.controller.ts`、`controllers/api/upload.controller.ts`
|
||||
- 应用：`application/upload.app.service.ts`（编排上传 → 领域校验 → Provider 落地 → 入库）
|
||||
- Core：`core/services/upload.core.service.ts`（类型/大小/命名/路径策略）
|
||||
- 仓储接口：`core/repositories/attachment.repository.ts`
|
||||
- 仓储实现：`infrastructure/repositories/attachment.typeorm.repository.ts`
|
||||
- 实体：`entities/sys-attachment.entity.ts`（严格对齐 `sys_attachment`）
|
||||
- 适配：`infrastructure/providers/local.storage.provider.ts`（或 `vendor/storage/*`）
|
||||
|
||||
流程：Controller → AppService（事务/编排） → CoreService（校验策略） → StorageProvider（落地） → AttachmentRepository（入库）
|
||||
|
||||
### 5) 映射示例：Settings.Storage 模块
|
||||
- PHP 心智：
|
||||
- admin 控制器（配置） → 服务 → `sys_config` 读写（键：`storage_*`）
|
||||
- NestJS 对应：
|
||||
- 控制器：`settings/storage/controllers/storage-settings.controller.ts`
|
||||
- 应用：`settings/storage/application/storage-settings.app.service.ts`
|
||||
- Core：`settings/storage/core/services/storage-config.core.service.ts`（唯一启用策略、键名规范）
|
||||
- 仓储接口：`settings/storage/core/repositories/sys-config.repository.ts`
|
||||
- 仓储实现：`settings/storage/infrastructure/sys-config.typeorm.repository.ts`
|
||||
- 实体：`settings/entities/sys-config.entity.ts`（对齐 `sys_config`，字段名：`value`）
|
||||
|
||||
流程：Controller → AppService → CoreService（校验/策略） → SysConfigRepository（读写 `value(JSON)`） → 发布事件/入队
|
||||
|
||||
### 6) 约束速查（强制对齐）
|
||||
- DB 字段：实体字段名/类型/时间戳/软删与 SQL 100%一致
|
||||
- `sys_config`：统一使用 `value(JSON)`；禁止 `config_value`、`app_type`
|
||||
- 路由前缀：管理端 `/adminapi`，前台 `/api`
|
||||
- 守卫：管理端控制器统一 `JwtAuthGuard + RolesGuard`
|
||||
- DTO：`class-validator`，必要时 `JsonTransformPipe`、`TimestampPipe`
|
||||
- 事件/队列：用例完成后发布 `system.settings.*` 等领域事件，耗时逻辑入队
|
||||
|
||||
### 7) 反模式（避免踩坑）
|
||||
- 在 Controller 中写业务或直接操作 ORM
|
||||
- 跳过 Application 层，直接由 Controller 调 Domain/Repository
|
||||
- Domain 依赖具体 ORM/外设实现
|
||||
- 在 `upload` 模块中放置“配置管理”代码（应全部在 `settings` 模块）
|
||||
- `sys_config` 使用不存在字段（如 `config_value`）、添加 `app_type` 过滤
|
||||
|
||||
### 8) 决策树（智能体选路）
|
||||
- 这是接口/路由吗？→ 放 `controllers`，只做 DTO 校验与调用 AppService
|
||||
- 这是业务流程/事务/聚合？→ 放 `application`，完成后发事件/入队
|
||||
- 这是纯业务规则/策略？→ 放 `domain/services`
|
||||
- 需要访问数据库？→ 定义 `domain/repositories` 接口，在 `infrastructure/repositories` 实现
|
||||
- 需要调用外部系统？→ 放 `infrastructure/providers`（或 `vendor/*`），通过接口注入
|
||||
- 是系统配置？→ 放 `settings/*`，读写 `sys_config.value(JSON)`，键按约定常量化
|
||||
|
||||
### 命名优先级（重要）
|
||||
- 在不违反 NestJS 规范与 TypeScript 命名习惯的前提下，**优先沿用 PHP 的业务命名**（含服务方法名、DTO 字段名、配置键名）
|
||||
- NestJS 特有文件/类名按规范命名（如 `*.module.ts`, `*.controller.ts`, `*.app.service.ts`, `*.core.service.ts`）
|
||||
|
||||
---
|
||||
以上映射可直接用于指导模块落地与代码评审，智能体在执行任务前请先对照本表完成“位置与职责”的选择。
|
||||
80
admin/docs/src/wwjcloud/ai/planner.md
Normal file
80
admin/docs/src/wwjcloud/ai/planner.md
Normal file
@@ -0,0 +1,80 @@
|
||||
## AI 规划师：底座完善路线图（面向微服务的一次性落地）
|
||||
|
||||
### 目标
|
||||
- 一次性补齐“微服务刚需底座”，保证当前单体可用、未来可无感切分。
|
||||
- 全程遵循项目约束：与 PHP 业务/数据一致；与 NestJS 规范一致；最小可行改动。
|
||||
|
||||
### 阶段划分与里程碑
|
||||
- M1 基础通信与契约（D1-D2）
|
||||
- 统一错误码与异常过滤器（全局 Filter）
|
||||
- 统一响应包装（Interceptor）
|
||||
- API 版本化（v1/v2）与 Swagger 分组（/api、/adminapi）
|
||||
- 配置中心 Schema 校验（Joi/Zod），启动即校验
|
||||
- 验收：/docs OK；错误码/响应统一；配置校验失败阻断启动
|
||||
|
||||
- M2 事务与数据访问（D2-D3）
|
||||
- 事务助手（Application 开启，共享 EntityManager）
|
||||
- 仓储基类（withManager、分页/排序/过滤白名单）
|
||||
- 分布式锁（Redis Lock + 看门狗）
|
||||
- 验收：示例用例通过；并发压测无脏写；锁可重入/续租
|
||||
|
||||
- M3 安全与多租（D3）
|
||||
- SiteIdScopeGuard（多租隔离）
|
||||
- 幂等（Idempotency-Key + Redis SETNX + TTL）
|
||||
- 限流（IP/UID/接口级 令牌桶）
|
||||
- 审计日志最小版（配置/权限/删除变更）
|
||||
- 验收：关键接口具备限流/幂等；审计写入成功
|
||||
|
||||
- M4 事件与队列（D4）
|
||||
- 事件总线：DB Outbox 默认，Kafka 可切换；事件契约（事件名/版本/载荷 Schema）
|
||||
- 任务队列：Bull/BullMQ 或 DB Jobs；重试/死信/命名规范
|
||||
- Saga/补偿基类（占位）
|
||||
- 验收：发布/消费示例跑通；切 Kafka 仅改配置；死信与重试可观测
|
||||
|
||||
- M5 可观测与稳定性（D4-D5）
|
||||
- 健康聚合（DB/Redis/队列/事件/对象存储）
|
||||
- 指标（Prometheus）：HTTP/DB/队列/事件/存储基础指标
|
||||
- 追踪（OpenTelemetry）：HTTP↔队列↔事件 traceparent 贯通
|
||||
- 结构化日志（JSON + traceId + site_id + 采样）
|
||||
- 验收：/health 聚合齐全；/metrics 输出基础指标；trace 在链路可见
|
||||
|
||||
- M6 vendor 外设标准（并行推进）
|
||||
- storage（方案B）：接口+adapters(local/aliyun/qcloud/qiniu)+按 site_id 解析工厂+契约测试
|
||||
- providers/registry：多实例缓存 Map<siteId, adapter> + TTL
|
||||
- 健康与 Schema：厂商配置校验与健康钩子
|
||||
- 验收：站点启用 > 跟随系统 > 本地兜底 生效；契约测试通过
|
||||
|
||||
### 目录落位（仅技术底座）
|
||||
- core/
|
||||
- config/{schema.ts, feature-flags.service.ts}
|
||||
- http/{filters/http-exception.filter.ts, interceptors/response.interceptor.ts, client/http.client.ts}
|
||||
- database/{transaction.manager.ts, base-repository.ts, redis-lock.service.ts}
|
||||
- security/{site-scope.guard.ts, idempotency.service.ts, rate-limit.service.ts}
|
||||
- event-bus/{outbox.provider.ts, kafka.provider.ts, contracts/*.schema.ts}
|
||||
- queue/{bull.provider.ts, db-queue.provider.ts, naming.ts, dead-letter.ts}
|
||||
- observability/{health/aggregator.ts, metrics/http.metrics.ts, tracing/otel.ts, logging/logger.ts}
|
||||
- vendor/
|
||||
- storage/（接口+adapters+providers+health+schema+tests）
|
||||
|
||||
### 执行顺序（对齐多智能体 S1-S9）
|
||||
- S1/S2 分析与架构：冻结上述目录与规范
|
||||
- S3 基建接入体：落地 core 与 vendor 骨架；接入 Kafka/Redis/队列/事务
|
||||
- S4 开发执行体：实现各模块最小能力与示例接入（settings/storage、upload）
|
||||
- S5 安全基线体：多租/限流/幂等/权限核查
|
||||
- S6 质量门禁体：lint/ts/test/e2e/覆盖率阈值
|
||||
- S7 规范审计体：对照 checklists 差异清单
|
||||
- S8 发布：变更/迁移/回滚说明
|
||||
- S9 性能优化体：缓存/异步化/批量化建议
|
||||
|
||||
### 验收清单（通过即视为底座完成）
|
||||
- /health、/metrics、/docs 与追踪链路可用；错误码+响应统一
|
||||
- 事务助手/仓储基类/锁/限流/幂等 有实例与测试
|
||||
- 事件总线 Outbox→Kafka 可切；队列有重试/死信与可视化
|
||||
- vendor/storage 支持站点启用/平台默认/本地兜底；契约测试通过
|
||||
|
||||
### 依赖与风险
|
||||
- 依赖：Redis、数据库可用；Kafka 按需
|
||||
- 风险：配置校验与权限基线放开可能影响旧路由；需灰度启用与回滚脚本
|
||||
|
||||
### 文档联动
|
||||
- 参见：`./workflow.md`（S1-S9）、`./integration.md`（能力接入）、`../project/vendor.md`（vendor 规范）
|
||||
28
admin/docs/src/wwjcloud/ai/rules.md
Normal file
28
admin/docs/src/wwjcloud/ai/rules.md
Normal file
@@ -0,0 +1,28 @@
|
||||
## 规则与规范（AI 执行细则）
|
||||
|
||||
### 总则
|
||||
- 框架层: 按 NestJS 规范；业务/数据层: 与 PHP 项目 100% 一致
|
||||
- 禁止自创 DB 字段/索引；实体必须与 `sql/wwjcloud.sql` 一致
|
||||
|
||||
### 分层与依赖
|
||||
- 目录: Controller / Application / Core / Infrastructure / Entities / DTO
|
||||
- 依赖方向: App → Common → Core → Vendor（严格单向）
|
||||
- Repository: 接口在 Core，实现放 Infrastructure；Controller 不直接用 ORM
|
||||
|
||||
### 路由与权限
|
||||
- 管理端: `/adminapi/{module}/...`，前台: `/api/{module}/...`
|
||||
- 管理端控制器统一: `JwtAuthGuard + RolesGuard`
|
||||
|
||||
### 数据与配置
|
||||
- 配置表: `sys_config.value(JSON)`；禁止 `config_value`、`app_type`
|
||||
- 时间戳: int；软删: `is_del`, `delete_time`; JSON: `@Column('json')` 或 text + JSON 序列化
|
||||
|
||||
### 验证与错误
|
||||
- DTO: `class-validator` 必须；必要时启用 `JsonTransformPipe`、`TimestampPipe`
|
||||
- 异常: 全局过滤器统一错误响应；拦截器记录 request-id/trace
|
||||
|
||||
### 事件与队列
|
||||
- 用例完成后发布领域事件（如 `system.settings.*`）；耗时逻辑入队处理
|
||||
|
||||
### 文档与测试
|
||||
- Swagger 注解完善；单测/集成/e2e 覆盖关键用例；`npm run build` 必须通过
|
||||
20
admin/docs/src/wwjcloud/ai/tooling.md
Normal file
20
admin/docs/src/wwjcloud/ai/tooling.md
Normal file
@@ -0,0 +1,20 @@
|
||||
## 工具偏好与使用约定
|
||||
|
||||
### 首选工具
|
||||
- 代码检索: 语义检索优先，其次精确 `grep`（限定范围/文件类型）
|
||||
- 文件读取: 分段读取，避免大文件全量；聚焦导入/实体/控制器/服务、测试
|
||||
- 编辑变更: 小步、原地最小改动；优先迁移后删除，避免职责重复
|
||||
- 运行与测试: `npm run build`，`npm run test`（单测/集成），e2e 按 `playground` 配置
|
||||
|
||||
### 偏好策略
|
||||
- 并行检索: 控制器/服务/实体/DTO/模块定义并行查看
|
||||
- 批量对齐: 字段/命名统一替换前先定位所有引用
|
||||
- 规范优先: 不因快捷而破坏分层与依赖约束
|
||||
|
||||
### 常用检查点
|
||||
- DB 对齐: 实体字段名、类型、软删、时间戳
|
||||
- 配置统一: `sys_config.value(JSON)`，无 `config_value`、无 `app_type`
|
||||
- 路由前缀: `/adminapi` 与 `/api`
|
||||
- 守卫: 管理端 `JwtAuthGuard + RolesGuard`
|
||||
- DTO: `class-validator`，必要时 `Pipes`（JSON/Timestamp）
|
||||
- 事件/队列: 用例完成后发布事件、必要时入队
|
||||
96
admin/docs/src/wwjcloud/ai/workflow.md
Normal file
96
admin/docs/src/wwjcloud/ai/workflow.md
Normal file
@@ -0,0 +1,96 @@
|
||||
## 智能体工作流程（多智能体协作)
|
||||
|
||||
### 角色定义（按执行顺序标注）
|
||||
- S1 需求分析体(Analyzer): 解析需求、对应 PHP/Nest 规范、输出任务切分与验收标准
|
||||
- S2 架构治理体(Architect): 校验分层/依赖/目录规范，给出重构建议与边界清单
|
||||
- S3 基建接入体(InfraOperator): 接入/校验 Kafka、Redis、队列、事务与配置，提供接入差异与示例
|
||||
- S4 开发执行体(Developer): 按规范编码、编写测试、修复构建
|
||||
- S5 安全基线体(SecurityGuard): 检查守卫、跨租户(site_id)隔离、敏感信息暴露（开发中与提测前各执行一次）
|
||||
- S6 质量门禁体(QualityGate): 聚合 ESLint/TS/覆盖率/e2e 结果，低于阈值阻断合并
|
||||
- S7 规范审计体(Auditor): 按清单逐项核查，出具差异报告与修复项
|
||||
- S8 上线管控体(Release): 构建、变更说明、灰度计划与回滚预案
|
||||
- S9 性能优化体(PerfTuner): 建议缓存/异步化/批处理，识别大对象传输与 N+1（开发后期与上线后持续执行）
|
||||
|
||||
### 串联流程（带顺序）
|
||||
1) S1 Analyzer
|
||||
- 输入: 业务需求/接口变更/对齐 PHP 的说明
|
||||
- 输出: 模块划分、路由表、DTO、实体字段清单、与 DB/ThinkPHP 对照
|
||||
|
||||
2) S2 Architect
|
||||
- 校验: 模块目录、分层(Application/Core/Infrastructure)、依赖方向(App→Common→Core→Vendor)
|
||||
- 输出: 设计说明、端口(Repository/Provider)定义、删除/迁移建议
|
||||
|
||||
3) S3 InfraOperator
|
||||
- 接入: Kafka/Redis/队列/事务的工程化接入与配置
|
||||
- 产物: 接入差异与示例代码（见 integration.md），健康检查/配置项校验清单
|
||||
|
||||
4) S4 Developer
|
||||
- 实现: Controller 仅路由+DTO校验；AppService 编排；Core 规则；Infra 实现；Entity 对齐 DB
|
||||
- 接入: 守卫(RBAC)、Pipes(JSON/Timestamp)、拦截器(请求日志)、事件与队列
|
||||
- 测试: 单测/集成/e2e，构建通过
|
||||
|
||||
5) S5 SecurityGuard（第一次，开发阶段）
|
||||
- 检查: 控制器守卫、site_id 隔离、敏感字段输出、配置权限
|
||||
|
||||
6) S6 QualityGate（CI 阶段）
|
||||
- 指标: ESLint/TS 无报错；覆盖率≥阈值；e2e 关键路径通过
|
||||
- 动作: 不达标阻断合并
|
||||
|
||||
7) S7 Auditor（提测前）
|
||||
- 检查: 规范清单(见 checklists.md)，字段/命名/路由/守卫/事务/队列/事件 与 PHP/DB 对齐
|
||||
- 产物: 差异报告与修复任务
|
||||
|
||||
8) S5 SecurityGuard（第二次，提测前）
|
||||
- 复检: 重要接口的鉴权/越权/敏感输出
|
||||
|
||||
9) S9 PerfTuner（并行/持续）
|
||||
- 建议: 缓存、异步化、批量化、索引与查询优化；识别 N+1、大对象传输
|
||||
|
||||
10) S8 Release
|
||||
- 产出: 变更日志、部署步骤、数据迁移脚本、回滚预案
|
||||
|
||||
### 关键约束
|
||||
- 与 PHP 业务/数据100%一致；与 NestJS 规范100%匹配
|
||||
- 禁止创建 DB 不存在字段；`sys_config.value(JSON)` 统一
|
||||
- 管理端路由 `/adminapi`，前台 `/api`；统一守卫与响应格式
|
||||
|
||||
### 基础能力检查点（Kafka / Redis / 队列 / 事务)
|
||||
- 事务: 仅在 Application 开启；多仓储共享同一 EntityManager；Core 不直接操作事务对象
|
||||
- 队列: 用例完成后入队；载荷仅传关键 ID；处理器在 Infrastructure；按队列名分域
|
||||
- 事件: 统一用 DomainEventService；事件名 `domain.aggregate.action`；默认 DB Outbox，可切 Kafka
|
||||
- Redis: 短缓存配置读取、上传限流/防刷（计数器）、幂等(SETNX+TTL)
|
||||
|
||||
### 命名与对齐
|
||||
- PHP 业务命名优先（不违反 Nest/TS 规范前提下），包括服务方法、DTO 字段、配置键
|
||||
- Nest 特有类型按规范命名：`*.module.ts`、`*.controller.ts`、`*.app.service.ts`、`*.core.service.ts`
|
||||
|
||||
### 核心链接
|
||||
- 模块映射: `./mapping.md`
|
||||
- 能力集成: `./integration.md`
|
||||
- 规则与清单: `./rules.md`、`./checklists.md`
|
||||
|
||||
### 执行与验收（CI/PR 建议)
|
||||
- PR 必须通过: build、单测/集成/e2e
|
||||
- 审计体根据 `checklists.md` 自动评论差异（字段/命名/路由/守卫/事务/队列/事件）
|
||||
- 安全基线: 管理端控制器统一 `JwtAuthGuard + RolesGuard`；/adminapi 与 /api 路由前缀
|
||||
|
||||
### 目录职能速查（防误用）
|
||||
- common/（框架通用服务层）
|
||||
- 放可被业务复用的通用功能：用户/权限/菜单/上传/通知/设置等模块
|
||||
- 内部模块按 Controller / Application / Core / Infrastructure / Entities / DTO 分层
|
||||
- 禁止依赖 App 层；允许依赖 core/, config/, vendor/
|
||||
- config/（配置与适配）
|
||||
- 环境变量、数据库/HTTP/安全/队列/第三方等配置模块与注入工厂
|
||||
- 仅存放配置与适配代码，不放业务逻辑
|
||||
- core/（核心基础设施与通用规则）
|
||||
- 通用规则/策略与仓储接口（Core 层），以及全局基础设施（如队列、事件、健康、拦截器）
|
||||
- 不直接依赖业务模块；面向 common/app 提供能力
|
||||
- vendor/（第三方适配层）
|
||||
- 外部服务适配：存储/支付/短信/HTTP/Kafka/Redis 等 Provider
|
||||
- 通过接口注入到 Infrastructure 或 Application，避免在 Controller 直接使用
|
||||
- lang/（多语言）
|
||||
- 多语言资源与语言包，供接口/异常/文案统一输出
|
||||
- 智能体在涉及文案/错误消息时，优先调用多语言键值而非写死文本
|
||||
- test/（测试）
|
||||
- 单元/集成/e2e 测试，包含关键业务与基础能力（事务/队列/事件/权限）覆盖
|
||||
- PR 必须通过测试基线，质量门禁体(QualityGate)据此决策
|
||||
133
admin/docs/src/wwjcloud/architecture/constraints.md
Normal file
133
admin/docs/src/wwjcloud/architecture/constraints.md
Normal file
@@ -0,0 +1,133 @@
|
||||
# 架构约束规则
|
||||
|
||||
## 🏗️ 分层架构
|
||||
|
||||
```
|
||||
┌─────────────────┐
|
||||
│ App │ ← 业务开发层（用户自定义业务模块）
|
||||
│ (用户业务) │ 电商、CRM、ERP等具体业务逻辑
|
||||
└─────────────────┘
|
||||
↓
|
||||
┌─────────────────┐
|
||||
│ Common │ ← 框架通用服务层（企业级通用功能）
|
||||
│ (框架通用服务) │ 用户管理、权限管理、菜单管理
|
||||
└─────────────────┘ 文件上传、通知服务、系统设置
|
||||
↓ 数据字典、缓存服务、队列服务
|
||||
┌─────────────────┐
|
||||
│ Core │ ← 核心基础设施层（底层基础设施）
|
||||
│ (基础设施) │ 认证核心、数据库核心、验证核心
|
||||
└─────────────────┘ HTTP核心、缓存核心、队列核心
|
||||
↓
|
||||
┌─────────────────┐
|
||||
│ Vendor │ ← 第三方服务适配层
|
||||
│ (外部集成) │ 存储、支付、通信、云服务适配
|
||||
└─────────────────┘
|
||||
|
||||
┌─────────────────┐
|
||||
│ Addons │ ← 插件扩展层（可插拔功能模块）
|
||||
│ (插件扩展) │ 扩展框架功能，不影响核心稳定性
|
||||
└─────────────────┘
|
||||
|
||||
┌─────────────────┐
|
||||
│ Test │ ← 测试代码层（独立测试模块）
|
||||
│ (测试代码) │ 单元测试、集成测试、E2E测试
|
||||
└─────────────────┘
|
||||
```
|
||||
|
||||
## 📋 依赖约束规则
|
||||
|
||||
### 1. **Core 层（最底层）**
|
||||
- ✅ **允许依赖**：无（最底层基础设施）
|
||||
- ❌ **禁止依赖**：Common、App、Vendor 层
|
||||
- 📁 **位置**：`src/core/`
|
||||
- 🎯 **职责**：提供最基础的抽象和接口
|
||||
|
||||
### 2. **Vendor 层（第三方适配）**
|
||||
- ✅ **允许依赖**：Core 层
|
||||
- ❌ **禁止依赖**：Common、App 层
|
||||
- 📁 **位置**：`src/vendor/`
|
||||
- 🎯 **职责**：第三方服务适配，实现 Core 层抽象
|
||||
|
||||
### 3. **Common 层（通用服务）**
|
||||
- ✅ **允许依赖**：Core 层
|
||||
- ❌ **禁止依赖**：App、Vendor 层
|
||||
- 📁 **位置**：`src/common/`
|
||||
- 🎯 **职责**：企业级通用功能，基于 Core 层构建
|
||||
|
||||
### 4. **App 层（业务应用）**
|
||||
- ✅ **允许依赖**：Common、Core 层
|
||||
- ❌ **禁止依赖**：Vendor 层（通过 Common 层抽象）
|
||||
- 📁 **位置**：`src/app/`
|
||||
- 🎯 **职责**：具体业务逻辑实现
|
||||
|
||||
### 5. **Test 层（测试代码）**
|
||||
- ✅ **允许依赖**：所有层（测试需要）
|
||||
- 📁 **位置**：`test/`（项目根目录）
|
||||
- ❌ **禁止位置**：`src/` 目录下
|
||||
- 🎯 **职责**：测试所有层的功能
|
||||
|
||||
## 🚫 禁止的依赖关系
|
||||
|
||||
```typescript
|
||||
// ❌ 错误：Common 层依赖 App 层
|
||||
// src/common/auth/auth.service.ts
|
||||
import { AppService } from '../../app/app.service'; // 禁止！
|
||||
|
||||
// ❌ 错误：Core 层依赖 Common 层
|
||||
// src/core/database/database.service.ts
|
||||
import { UserService } from '../../common/user/user.service'; // 禁止！
|
||||
|
||||
// ❌ 错误：App 层直接依赖 Vendor 层
|
||||
// src/app/payment/payment.service.ts
|
||||
import { AlipayProvider } from '../../vendor/payment/alipay.provider'; // 禁止！
|
||||
|
||||
// ❌ 错误：在 src 目录下创建测试代码
|
||||
// src/test/test.service.ts - 禁止！
|
||||
```
|
||||
|
||||
## ✅ 正确的依赖关系
|
||||
|
||||
```typescript
|
||||
// ✅ 正确：Common 层依赖 Core 层
|
||||
// src/common/auth/auth.service.ts
|
||||
import { JwtService } from '../../core/auth/jwt.service';
|
||||
|
||||
// ✅ 正确：App 层依赖 Common 层
|
||||
// src/app/user/user.controller.ts
|
||||
import { AuthService } from '../../common/auth/auth.service';
|
||||
|
||||
// ✅ 正确：Vendor 层依赖 Core 层
|
||||
// src/vendor/payment/alipay.provider.ts
|
||||
import { PaymentProvider } from '../../core/payment/payment.provider';
|
||||
|
||||
// ✅ 正确：测试代码依赖所有层
|
||||
// test/auth.test.ts
|
||||
import { AuthService } from '../src/common/auth/auth.service';
|
||||
```
|
||||
|
||||
## 🔧 ESLint 规则
|
||||
|
||||
项目已配置严格的 ESLint 规则来强制执行这些约束：
|
||||
|
||||
1. **分层依赖检查**：自动检测违反依赖方向的导入
|
||||
2. **测试代码位置检查**：禁止在 src 目录下创建测试代码
|
||||
3. **路径别名检查**：强制使用相对路径，避免路径别名
|
||||
4. **内部实现检查**：禁止依赖其他模块的内部实现
|
||||
|
||||
## 📝 开发建议
|
||||
|
||||
1. **设计时先确定层级**：新功能应该放在哪一层？
|
||||
2. **依赖时检查方向**：确保依赖关系符合架构约束
|
||||
3. **测试代码统一管理**：所有测试代码放在 `test/` 目录
|
||||
4. **定期运行 ESLint**：`npm run lint` 检查架构约束
|
||||
5. **代码审查时关注架构**：确保新代码符合分层原则
|
||||
|
||||
## 🚨 常见错误
|
||||
|
||||
1. **在 Core 层导入业务逻辑**
|
||||
2. **Common 层直接调用第三方服务**
|
||||
3. **App 层绕过 Common 层直接使用 Vendor**
|
||||
4. **测试代码放在 src 目录下**
|
||||
5. **使用绝对路径或路径别名导入**
|
||||
|
||||
遵循这些约束规则，可以确保 WWJCloud 的架构清晰、依赖关系正确，为未来的微服务拆分奠定坚实基础。
|
||||
769
admin/docs/src/wwjcloud/gateway/architecture.md
Normal file
769
admin/docs/src/wwjcloud/gateway/architecture.md
Normal file
@@ -0,0 +1,769 @@
|
||||
# 网关技术架构详解
|
||||
|
||||
> 深入理解 WWJCloud 网关系统的技术架构和实现原理
|
||||
|
||||
## 🏗️ **架构设计原则**
|
||||
|
||||
### **核心原则**
|
||||
1. **分层架构**: 清晰的层次结构，职责分离
|
||||
2. **模块化设计**: 高内聚、低耦合的模块组织
|
||||
3. **可扩展性**: 支持水平扩展和垂直扩展
|
||||
4. **高可用性**: 故障隔离和自动恢复机制
|
||||
5. **可观测性**: 完整的监控、追踪和日志
|
||||
6. **安全性**: 多层次的安全防护策略
|
||||
|
||||
---
|
||||
|
||||
## 🌐 **整体架构设计**
|
||||
|
||||
### **架构层次图**
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ 接入层 (Access Layer) │
|
||||
├─────────────────────────────────────────────────────────────┤
|
||||
│ CDN │ DNS │ 负载均衡器 │ 反向代理 │ 防火墙 │
|
||||
└─────────────────────┬───────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ API网关层 (API Gateway Layer) │
|
||||
├─────────────────────────────────────────────────────────────┤
|
||||
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
|
||||
│ │ 路由管理 │ │ 限流控制 │ │ 安全策略 │ │
|
||||
│ │ │ │ │ │ │ │
|
||||
│ │ • 动态路由 │ │ • 用户限流 │ │ • 访问控制 │ │
|
||||
│ │ • 路由版本 │ │ • IP限流 │ │ • 流量控制 │ │
|
||||
│ │ • 路由策略 │ │ • API限流 │ │ • 安全防护 │ │
|
||||
│ └─────────────┘ └─────────────┘ └─────────────┘ │
|
||||
└─────────────────────┬───────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ 微服务网关层 (Microservice Gateway) │
|
||||
├─────────────────────────────────────────────────────────────┤
|
||||
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
|
||||
│ │ 服务发现 │ │ 负载均衡 │ │ 熔断器 │ │
|
||||
│ │ │ │ │ │ │ │
|
||||
│ │ • 服务注册 │ │ • 轮询算法 │ │ • 状态管理 │ │
|
||||
│ │ • 服务发现 │ │ • 权重算法 │ │ • 策略配置 │ │
|
||||
│ │ • 健康检查 │ │ • 一致性哈希│ │ • 自动恢复 │ │
|
||||
│ └─────────────┘ └─────────────┘ └─────────────┘ │
|
||||
└─────────────────────┬───────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ 服务网格层 (Service Mesh) │
|
||||
├─────────────────────────────────────────────────────────────┤
|
||||
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
|
||||
│ │ 流量管理 │ │ 安全策略 │ │ 可观测性 │ │
|
||||
│ │ │ │ │ │ │ │
|
||||
│ │ • 流量路由 │ │ • 身份认证 │ │ • 指标收集 │ │
|
||||
│ │ • 流量分割 │ │ • 授权策略 │ │ • 日志聚合 │ │
|
||||
│ │ • 流量镜像 │ │ • 加密通信 │ │ • 链路追踪 │ │
|
||||
│ └─────────────┘ └─────────────┘ └─────────────┘ │
|
||||
└─────────────────────┬───────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ 业务服务层 (Business Service Layer) │
|
||||
├─────────────────────────────────────────────────────────────┤
|
||||
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
|
||||
│ │ 用户服务 │ │ 权限服务 │ │ 文件服务 │ │
|
||||
│ │ │ │ │ │ │ │
|
||||
│ │ • 会员管理 │ │ • 角色管理 │ │ • 文件上传 │ │
|
||||
│ │ • 管理员 │ │ • 菜单管理 │ │ • 文件管理 │ │
|
||||
│ │ • 认证授权 │ │ • 权限控制 │ │ • 存储适配 │ │
|
||||
│ └─────────────┘ └─────────────┘ └─────────────┘ │
|
||||
└─────────────────────┬───────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ 数据存储层 (Data Storage Layer) │
|
||||
├─────────────────────────────────────────────────────────────┤
|
||||
│ MySQL集群 │ Redis集群 │ 对象存储 │ 时序数据库 │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔧 **核心组件架构**
|
||||
|
||||
### **1. API网关组件**
|
||||
|
||||
#### **1.1 路由管理组件**
|
||||
```typescript
|
||||
// 路由管理核心接口
|
||||
interface RouteManager {
|
||||
// 路由注册
|
||||
registerRoute(route: Route): Promise<void>;
|
||||
|
||||
// 路由查找
|
||||
findRoute(path: string, method: string): Route | null;
|
||||
|
||||
// 路由更新
|
||||
updateRoute(routeId: string, updates: Partial<Route>): Promise<void>;
|
||||
|
||||
// 路由删除
|
||||
deleteRoute(routeId: string): Promise<void>;
|
||||
|
||||
// 路由列表
|
||||
listRoutes(filters?: RouteFilters): Route[];
|
||||
}
|
||||
|
||||
// 路由定义
|
||||
interface Route {
|
||||
id: string;
|
||||
name: string;
|
||||
path: string;
|
||||
method: string;
|
||||
target: string;
|
||||
middleware: string[];
|
||||
rateLimit: RateLimitConfig;
|
||||
security: SecurityConfig;
|
||||
version: string;
|
||||
enabled: boolean;
|
||||
createdAt: Date;
|
||||
updatedAt: Date;
|
||||
}
|
||||
```
|
||||
|
||||
#### **1.2 限流控制组件**
|
||||
```typescript
|
||||
// 限流器接口
|
||||
interface RateLimiter {
|
||||
// 检查是否允许请求
|
||||
isAllowed(key: string, limit: RateLimit): Promise<boolean>;
|
||||
|
||||
// 获取当前使用量
|
||||
getCurrentUsage(key: string): Promise<number>;
|
||||
|
||||
// 重置限流器
|
||||
reset(key: string): Promise<void>;
|
||||
}
|
||||
|
||||
// 限流配置
|
||||
interface RateLimit {
|
||||
// 时间窗口（秒）
|
||||
window: number;
|
||||
|
||||
// 最大请求数
|
||||
max: number;
|
||||
|
||||
// 限流策略
|
||||
strategy: 'fixed' | 'sliding' | 'token-bucket' | 'leaky-bucket';
|
||||
|
||||
// 限流键类型
|
||||
keyType: 'ip' | 'user' | 'api' | 'custom';
|
||||
}
|
||||
```
|
||||
|
||||
### **2. 微服务网关组件**
|
||||
|
||||
#### **2.1 服务发现组件**
|
||||
```typescript
|
||||
// 服务发现接口
|
||||
interface ServiceDiscovery {
|
||||
// 服务注册
|
||||
registerService(service: ServiceInfo): Promise<void>;
|
||||
|
||||
// 服务发现
|
||||
discoverService(serviceName: string): Promise<ServiceInstance[]>;
|
||||
|
||||
// 服务注销
|
||||
unregisterService(serviceId: string): Promise<void>;
|
||||
|
||||
// 健康检查
|
||||
checkHealth(serviceId: string): Promise<HealthStatus>;
|
||||
|
||||
// 服务列表
|
||||
listServices(): ServiceInfo[];
|
||||
}
|
||||
|
||||
// 服务信息
|
||||
interface ServiceInfo {
|
||||
id: string;
|
||||
name: string;
|
||||
version: string;
|
||||
host: string;
|
||||
port: number;
|
||||
protocol: string;
|
||||
metadata: Record<string, any>;
|
||||
tags: string[];
|
||||
status: ServiceStatus;
|
||||
lastHeartbeat: Date;
|
||||
}
|
||||
```
|
||||
|
||||
#### **2.2 负载均衡组件**
|
||||
```typescript
|
||||
// 负载均衡器接口
|
||||
interface LoadBalancer {
|
||||
// 选择服务实例
|
||||
selectInstance(instances: ServiceInstance[]): ServiceInstance;
|
||||
|
||||
// 更新实例状态
|
||||
updateInstanceStatus(instanceId: string, status: InstanceStatus): void;
|
||||
|
||||
// 获取负载均衡策略
|
||||
getStrategy(): LoadBalanceStrategy;
|
||||
|
||||
// 设置负载均衡策略
|
||||
setStrategy(strategy: LoadBalanceStrategy): void;
|
||||
}
|
||||
|
||||
// 负载均衡策略
|
||||
enum LoadBalanceStrategy {
|
||||
ROUND_ROBIN = 'round-robin',
|
||||
WEIGHTED_ROUND_ROBIN = 'weighted-round-robin',
|
||||
LEAST_CONNECTIONS = 'least-connections',
|
||||
WEIGHTED_LEAST_CONNECTIONS = 'weighted-least-connections',
|
||||
CONSISTENT_HASH = 'consistent-hash',
|
||||
IP_HASH = 'ip-hash',
|
||||
RANDOM = 'random'
|
||||
}
|
||||
```
|
||||
|
||||
#### **2.3 熔断器组件**
|
||||
```typescript
|
||||
// 熔断器接口
|
||||
interface CircuitBreaker {
|
||||
// 执行请求
|
||||
execute<T>(fn: () => Promise<T>): Promise<T>;
|
||||
|
||||
// 获取状态
|
||||
getStatus(): CircuitBreakerStatus;
|
||||
|
||||
// 手动重置
|
||||
reset(): void;
|
||||
|
||||
// 获取统计信息
|
||||
getStats(): CircuitBreakerStats;
|
||||
}
|
||||
|
||||
// 熔断器状态
|
||||
enum CircuitBreakerStatus {
|
||||
CLOSED = 'closed', // 关闭状态，正常处理请求
|
||||
OPEN = 'open', // 开启状态，拒绝所有请求
|
||||
HALF_OPEN = 'half-open' // 半开状态，允许部分请求
|
||||
}
|
||||
```
|
||||
|
||||
### **3. 服务网格组件**
|
||||
|
||||
#### **3.1 Istio集成组件**
|
||||
```typescript
|
||||
// Istio 客户端接口
|
||||
interface IstioClient {
|
||||
// 创建虚拟服务
|
||||
createVirtualService(vs: VirtualService): Promise<void>;
|
||||
|
||||
// 创建目标规则
|
||||
createDestinationRule(dr: DestinationRule): Promise<void>;
|
||||
|
||||
// 创建网关
|
||||
createGateway(gateway: Gateway): Promise<void>;
|
||||
|
||||
// 创建服务入口
|
||||
createServiceEntry(se: ServiceEntry): Promise<void>;
|
||||
|
||||
// 获取服务配置
|
||||
getServiceConfig(serviceName: string): Promise<ServiceConfig>;
|
||||
}
|
||||
|
||||
// 虚拟服务配置
|
||||
interface VirtualService {
|
||||
apiVersion: string;
|
||||
kind: string;
|
||||
metadata: {
|
||||
name: string;
|
||||
namespace: string;
|
||||
};
|
||||
spec: {
|
||||
hosts: string[];
|
||||
gateways?: string[];
|
||||
http: HttpRoute[];
|
||||
tcp?: TcpRoute[];
|
||||
tls?: TlsRoute[];
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
### **4. 监控追踪组件**
|
||||
|
||||
#### **4.1 分布式追踪组件**
|
||||
```typescript
|
||||
// 追踪器接口
|
||||
interface Tracer {
|
||||
// 开始追踪
|
||||
startSpan(name: string, options?: SpanOptions): Span;
|
||||
|
||||
// 注入追踪上下文
|
||||
inject(span: Span, format: string, carrier: any): void;
|
||||
|
||||
// 提取追踪上下文
|
||||
extract(format: string, carrier: any): SpanContext | null;
|
||||
|
||||
// 获取当前活跃的Span
|
||||
getCurrentSpan(): Span | null;
|
||||
}
|
||||
|
||||
// Span接口
|
||||
interface Span {
|
||||
// 获取上下文
|
||||
context(): SpanContext;
|
||||
|
||||
// 设置标签
|
||||
setTag(key: string, value: any): this;
|
||||
|
||||
// 记录事件
|
||||
log(event: LogEvent): this;
|
||||
|
||||
// 设置状态
|
||||
setStatus(status: SpanStatus): this;
|
||||
|
||||
// 完成Span
|
||||
finish(finishTime?: number): void;
|
||||
}
|
||||
```
|
||||
|
||||
#### **4.2 性能监控组件**
|
||||
```typescript
|
||||
// 性能监控接口
|
||||
interface PerformanceMonitor {
|
||||
// 记录请求开始
|
||||
recordRequestStart(requestId: string, metadata: RequestMetadata): void;
|
||||
|
||||
// 记录请求结束
|
||||
recordRequestEnd(requestId: string, responseTime: number, status: number): void;
|
||||
|
||||
// 记录错误
|
||||
recordError(requestId: string, error: Error): void;
|
||||
|
||||
// 获取性能指标
|
||||
getMetrics(timeRange: TimeRange): PerformanceMetrics;
|
||||
|
||||
// 设置告警规则
|
||||
setAlertRule(rule: AlertRule): void;
|
||||
}
|
||||
|
||||
// 性能指标
|
||||
interface PerformanceMetrics {
|
||||
// 请求总数
|
||||
totalRequests: number;
|
||||
|
||||
// 成功请求数
|
||||
successfulRequests: number;
|
||||
|
||||
// 失败请求数
|
||||
failedRequests: number;
|
||||
|
||||
// 平均响应时间
|
||||
averageResponseTime: number;
|
||||
|
||||
// 95%分位响应时间
|
||||
p95ResponseTime: number;
|
||||
|
||||
// 99%分位响应时间
|
||||
p99ResponseTime: number;
|
||||
|
||||
// 吞吐量 (QPS)
|
||||
throughput: number;
|
||||
|
||||
// 错误率
|
||||
errorRate: number;
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📊 **性能优化策略**
|
||||
|
||||
### **1. 缓存策略**
|
||||
```typescript
|
||||
// 多级缓存接口
|
||||
interface MultiLevelCache {
|
||||
// 获取缓存
|
||||
get<T>(key: string): Promise<T | null>;
|
||||
|
||||
// 设置缓存
|
||||
set<T>(key: string, value: T, ttl?: number): Promise<void>;
|
||||
|
||||
// 删除缓存
|
||||
delete(key: string): Promise<void>;
|
||||
|
||||
// 清空缓存
|
||||
clear(): Promise<void>;
|
||||
|
||||
// 获取缓存统计
|
||||
getStats(): CacheStats;
|
||||
}
|
||||
|
||||
// 多级缓存实现
|
||||
class MultiLevelCacheImpl implements MultiLevelCache {
|
||||
constructor(
|
||||
private l1Cache: Cache, // L1: 内存缓存
|
||||
private l2Cache: Cache, // L2: Redis缓存
|
||||
private l3Cache: Cache // L3: 数据库缓存
|
||||
) {}
|
||||
|
||||
async get<T>(key: string): Promise<T | null> {
|
||||
// L1 缓存查找
|
||||
let value = await this.l1Cache.get<T>(key);
|
||||
if (value !== null) {
|
||||
return value;
|
||||
}
|
||||
|
||||
// L2 缓存查找
|
||||
value = await this.l2Cache.get<T>(key);
|
||||
if (value !== null) {
|
||||
// 回填 L1 缓存
|
||||
await this.l1Cache.set(key, value);
|
||||
return value;
|
||||
}
|
||||
|
||||
// L3 缓存查找
|
||||
value = await this.l3Cache.get<T>(key);
|
||||
if (value !== null) {
|
||||
// 回填 L1 和 L2 缓存
|
||||
await Promise.all([
|
||||
this.l1Cache.set(key, value),
|
||||
this.l2Cache.set(key, value)
|
||||
]);
|
||||
return value;
|
||||
}
|
||||
|
||||
return null;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### **2. 连接池管理**
|
||||
```typescript
|
||||
// 连接池接口
|
||||
interface ConnectionPool<T> {
|
||||
// 获取连接
|
||||
acquire(): Promise<T>;
|
||||
|
||||
// 释放连接
|
||||
release(connection: T): void;
|
||||
|
||||
// 关闭连接池
|
||||
close(): Promise<void>;
|
||||
|
||||
// 获取池状态
|
||||
getStatus(): PoolStatus;
|
||||
}
|
||||
|
||||
// 数据库连接池实现
|
||||
class DatabaseConnectionPool implements ConnectionPool<DatabaseConnection> {
|
||||
private pool: Pool<DatabaseConnection>;
|
||||
private config: PoolConfig;
|
||||
|
||||
constructor(config: PoolConfig) {
|
||||
this.config = config;
|
||||
this.pool = new Pool({
|
||||
host: config.host,
|
||||
port: config.port,
|
||||
user: config.user,
|
||||
password: config.password,
|
||||
database: config.database,
|
||||
connectionLimit: config.maxConnections,
|
||||
acquireTimeout: config.acquireTimeout,
|
||||
timeout: config.timeout,
|
||||
queueLimit: config.queueLimit
|
||||
});
|
||||
}
|
||||
|
||||
async acquire(): Promise<DatabaseConnection> {
|
||||
return this.pool.getConnection();
|
||||
}
|
||||
|
||||
release(connection: DatabaseConnection): void {
|
||||
connection.release();
|
||||
}
|
||||
|
||||
async close(): Promise<void> {
|
||||
await this.pool.end();
|
||||
}
|
||||
|
||||
getStatus(): PoolStatus {
|
||||
return {
|
||||
totalConnections: this.pool.config.connectionLimit,
|
||||
activeConnections: this.pool._allConnections.length,
|
||||
idleConnections: this.pool._freeConnections.length,
|
||||
waitingRequests: this.pool._connectionQueue.length
|
||||
};
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🚀 **部署架构**
|
||||
|
||||
### **容器化部署**
|
||||
```yaml
|
||||
# docker-compose.yml
|
||||
version: '3.8'
|
||||
services:
|
||||
gateway:
|
||||
build: .
|
||||
ports:
|
||||
- "3001:3001"
|
||||
environment:
|
||||
- NODE_ENV=production
|
||||
- DB_HOST=mysql
|
||||
- REDIS_HOST=redis
|
||||
depends_on:
|
||||
- mysql
|
||||
- redis
|
||||
networks:
|
||||
- gateway-network
|
||||
deploy:
|
||||
replicas: 3
|
||||
resources:
|
||||
limits:
|
||||
cpus: '1.0'
|
||||
memory: 1G
|
||||
reservations:
|
||||
cpus: '0.5'
|
||||
memory: 512M
|
||||
restart_policy:
|
||||
condition: on-failure
|
||||
delay: 5s
|
||||
max_attempts: 3
|
||||
|
||||
mysql:
|
||||
image: mysql:8.0
|
||||
environment:
|
||||
MYSQL_ROOT_PASSWORD: ${DB_PASSWORD}
|
||||
MYSQL_DATABASE: ${DB_NAME}
|
||||
volumes:
|
||||
- mysql_data:/var/lib/mysql
|
||||
networks:
|
||||
- gateway-network
|
||||
|
||||
redis:
|
||||
image: redis:6.2-alpine
|
||||
command: redis-server --requirepass ${REDIS_PASSWORD}
|
||||
volumes:
|
||||
- redis_data:/data
|
||||
networks:
|
||||
- gateway-network
|
||||
|
||||
networks:
|
||||
gateway-network:
|
||||
driver: bridge
|
||||
|
||||
volumes:
|
||||
mysql_data:
|
||||
redis_data:
|
||||
```
|
||||
|
||||
### **Kubernetes部署**
|
||||
```yaml
|
||||
# gateway-deployment.yaml
|
||||
apiVersion: apps/v1
|
||||
kind: Deployment
|
||||
metadata:
|
||||
name: gateway
|
||||
namespace: wwjcloud
|
||||
spec:
|
||||
replicas: 3
|
||||
selector:
|
||||
matchLabels:
|
||||
app: gateway
|
||||
template:
|
||||
metadata:
|
||||
labels:
|
||||
app: gateway
|
||||
spec:
|
||||
containers:
|
||||
- name: gateway
|
||||
image: wwjcloud/gateway:latest
|
||||
ports:
|
||||
- containerPort: 3001
|
||||
env:
|
||||
- name: NODE_ENV
|
||||
value: "production"
|
||||
- name: DB_HOST
|
||||
valueFrom:
|
||||
configMapKeyRef:
|
||||
name: gateway-config
|
||||
key: db_host
|
||||
resources:
|
||||
requests:
|
||||
memory: "512Mi"
|
||||
cpu: "500m"
|
||||
limits:
|
||||
memory: "1Gi"
|
||||
cpu: "1000m"
|
||||
livenessProbe:
|
||||
httpGet:
|
||||
path: /health
|
||||
port: 3001
|
||||
initialDelaySeconds: 30
|
||||
periodSeconds: 10
|
||||
readinessProbe:
|
||||
httpGet:
|
||||
path: /ready
|
||||
port: 3001
|
||||
initialDelaySeconds: 5
|
||||
periodSeconds: 5
|
||||
---
|
||||
apiVersion: v1
|
||||
kind: Service
|
||||
metadata:
|
||||
name: gateway-service
|
||||
namespace: wwjcloud
|
||||
spec:
|
||||
selector:
|
||||
app: gateway
|
||||
ports:
|
||||
- protocol: TCP
|
||||
port: 80
|
||||
targetPort: 3001
|
||||
type: LoadBalancer
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔍 **监控和告警**
|
||||
|
||||
### **监控指标**
|
||||
```typescript
|
||||
// 监控指标收集器
|
||||
@Injectable()
|
||||
export class MetricsCollector {
|
||||
private metrics = new Map<string, Metric>();
|
||||
|
||||
// 记录计数器
|
||||
incrementCounter(name: string, labels: Record<string, string> = {}): void {
|
||||
const key = this.buildKey(name, labels);
|
||||
const metric = this.metrics.get(key) || { name, type: 'counter', value: 0, labels };
|
||||
metric.value++;
|
||||
this.metrics.set(key, metric);
|
||||
}
|
||||
|
||||
// 记录直方图
|
||||
recordHistogram(name: string, value: number, labels: Record<string, string> = {}): void {
|
||||
const key = this.buildKey(name, labels);
|
||||
const metric = this.metrics.get(key) || {
|
||||
name,
|
||||
type: 'histogram',
|
||||
buckets: new Map(),
|
||||
labels
|
||||
};
|
||||
|
||||
if (metric.type === 'histogram') {
|
||||
const bucket = this.getBucket(value);
|
||||
metric.buckets.set(bucket, (metric.buckets.get(bucket) || 0) + 1);
|
||||
}
|
||||
|
||||
this.metrics.set(key, metric);
|
||||
}
|
||||
|
||||
// 记录仪表盘
|
||||
setGauge(name: string, value: number, labels: Record<string, string> = {}): void {
|
||||
const key = this.buildKey(name, labels);
|
||||
this.metrics.set(key, { name, type: 'gauge', value, labels });
|
||||
}
|
||||
|
||||
// 获取所有指标
|
||||
getMetrics(): Metric[] {
|
||||
return Array.from(this.metrics.values());
|
||||
}
|
||||
|
||||
private buildKey(name: string, labels: Record<string, string>): string {
|
||||
const labelStr = Object.entries(labels)
|
||||
.map(([k, v]) => `${k}="${v}"`)
|
||||
.join(',');
|
||||
return labelStr ? `${name}{${labelStr}}` : name;
|
||||
}
|
||||
|
||||
private getBucket(value: number): string {
|
||||
const buckets = [0.1, 0.5, 1, 2, 5, 10, 30, 60, 120, 300, 600];
|
||||
for (const bucket of buckets) {
|
||||
if (value <= bucket) {
|
||||
return `le="${bucket}"`;
|
||||
}
|
||||
}
|
||||
return 'le="+Inf"';
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### **告警规则**
|
||||
```typescript
|
||||
// 告警规则引擎
|
||||
@Injectable()
|
||||
export class AlertingEngine {
|
||||
private rules: AlertRule[] = [];
|
||||
private alertManager: AlertManager;
|
||||
|
||||
constructor(alertManager: AlertManager) {
|
||||
this.alertManager = alertManager;
|
||||
}
|
||||
|
||||
// 添加告警规则
|
||||
addRule(rule: AlertRule): void {
|
||||
this.rules.push(rule);
|
||||
}
|
||||
|
||||
// 评估告警规则
|
||||
evaluateRules(metrics: Metric[]): void {
|
||||
for (const rule of this.rules) {
|
||||
if (this.evaluateRule(rule, metrics)) {
|
||||
this.triggerAlert(rule);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
private evaluateRule(rule: AlertRule, metrics: Metric[]): boolean {
|
||||
const metric = metrics.find(m => m.name === rule.metricName);
|
||||
if (!metric) return false;
|
||||
|
||||
switch (rule.operator) {
|
||||
case 'gt':
|
||||
return metric.value > rule.threshold;
|
||||
case 'gte':
|
||||
return metric.value >= rule.threshold;
|
||||
case 'lt':
|
||||
return metric.value < rule.threshold;
|
||||
case 'lte':
|
||||
return metric.value <= rule.threshold;
|
||||
case 'eq':
|
||||
return metric.value === rule.threshold;
|
||||
case 'ne':
|
||||
return metric.value !== rule.threshold;
|
||||
default:
|
||||
return false;
|
||||
}
|
||||
}
|
||||
|
||||
private triggerAlert(rule: AlertRule): void {
|
||||
const alert: Alert = {
|
||||
id: uuidv4(),
|
||||
ruleId: rule.id,
|
||||
severity: rule.severity,
|
||||
message: rule.message,
|
||||
timestamp: new Date(),
|
||||
status: 'firing'
|
||||
};
|
||||
|
||||
this.alertManager.sendAlert(alert);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📚 **下一步**
|
||||
|
||||
- [查看开发计划](./development-plan.md) - 了解详细的开发路线图
|
||||
- [开始快速上手](./quick-start.md) - 立即开始使用网关系统
|
||||
- [查看API参考](./api-reference.md) - 完整的API接口文档
|
||||
|
||||
---
|
||||
|
||||
> **提示**: 本文档提供了网关系统的技术架构详解，如需了解具体实现细节，请查看相应的代码示例和API文档。
|
||||
496
admin/docs/src/wwjcloud/gateway/development-plan.md
Normal file
496
admin/docs/src/wwjcloud/gateway/development-plan.md
Normal file
@@ -0,0 +1,496 @@
|
||||
# WWJCloud 网关系统待开发功能分析
|
||||
|
||||
> 本文档详细分析了 WWJCloud 网关系统的当前状态、缺失功能和开发计划
|
||||
|
||||
## 📋 **当前网关系统状态概览**
|
||||
|
||||
### **已实现功能** ✅
|
||||
- **基础路由网关**: 完整的路由定义和管理
|
||||
- **中间件系统**: 全局中间件、路由中间件
|
||||
- **认证授权**: JWT、OAuth2.0、RBAC权限
|
||||
- **网络安全**: HTTPS、CORS、CSRF防护
|
||||
- **基础监控**: 健康检查、基础日志
|
||||
- **文件上传**: 多文件上传、文件管理
|
||||
|
||||
### **缺失功能** ❌
|
||||
- **微服务网关**: 服务发现、服务注册、负载均衡
|
||||
- **服务网格**: Istio、Envoy集成
|
||||
- **分布式追踪**: 链路追踪、性能分析
|
||||
- **高级负载均衡**: 一致性哈希、熔断器
|
||||
- **API网关管理**: 路由配置、限流配置
|
||||
- **监控告警**: 性能监控、错误告警
|
||||
|
||||
---
|
||||
|
||||
## 🚨 **严重缺失功能（必须实现）**
|
||||
|
||||
### **1. 微服务网关** 🔴 **优先级：最高**
|
||||
|
||||
#### **1.1 服务发现系统**
|
||||
```typescript
|
||||
// 待实现：服务发现模块
|
||||
@Module({
|
||||
imports: [DiscoveryModule],
|
||||
providers: [ServiceDiscoveryService],
|
||||
exports: [ServiceDiscoveryService],
|
||||
})
|
||||
export class ServiceDiscoveryModule {}
|
||||
|
||||
// 核心功能需求：
|
||||
// - 服务注册 (Service Registration)
|
||||
// - 服务发现 (Service Discovery)
|
||||
// - 健康检查 (Health Check)
|
||||
// - 服务元数据管理 (Service Metadata)
|
||||
```
|
||||
|
||||
#### **1.2 服务注册系统**
|
||||
```typescript
|
||||
// 待实现：服务注册模块
|
||||
@Module({
|
||||
imports: [RegistryModule],
|
||||
providers: [ServiceRegistryService],
|
||||
exports: [ServiceRegistryService],
|
||||
})
|
||||
export class ServiceRegistryModule {}
|
||||
|
||||
// 核心功能需求：
|
||||
// - 自动服务注册 (Auto Registration)
|
||||
// - 服务心跳检测 (Heartbeat Detection)
|
||||
// - 服务状态管理 (Service Status Management)
|
||||
// - 服务版本管理 (Service Version Management)
|
||||
```
|
||||
|
||||
#### **1.3 负载均衡系统**
|
||||
```typescript
|
||||
// 待实现：负载均衡模块
|
||||
@Module({
|
||||
imports: [LoadBalancerModule],
|
||||
providers: [LoadBalancerService],
|
||||
exports: [LoadBalancerService],
|
||||
})
|
||||
export class LoadBalancerModule {}
|
||||
|
||||
// 核心功能需求：
|
||||
// - 轮询负载均衡 (Round Robin)
|
||||
// - 权重负载均衡 (Weighted)
|
||||
// - 最少连接负载均衡 (Least Connections)
|
||||
// - 一致性哈希负载均衡 (Consistent Hashing)
|
||||
// - 健康检查负载均衡 (Health Check)
|
||||
```
|
||||
|
||||
### **2. 服务网格支持** 🔴 **优先级：最高**
|
||||
|
||||
#### **2.1 Istio集成**
|
||||
```typescript
|
||||
// 待实现：Istio集成模块
|
||||
@Module({
|
||||
imports: [IstioModule],
|
||||
providers: [IstioService],
|
||||
exports: [IstioService],
|
||||
})
|
||||
export class IstioModule {}
|
||||
|
||||
// 核心功能需求：
|
||||
// - 流量管理 (Traffic Management)
|
||||
// - 安全策略 (Security Policies)
|
||||
// - 可观测性 (Observability)
|
||||
// - 策略执行 (Policy Enforcement)
|
||||
```
|
||||
|
||||
#### **2.2 Envoy代理集成**
|
||||
```typescript
|
||||
// 待实现：Envoy代理模块
|
||||
@Module({
|
||||
imports: [EnvoyModule],
|
||||
providers: [EnvoyService],
|
||||
exports: [EnvoyService],
|
||||
})
|
||||
export class EnvoyModule {}
|
||||
|
||||
// 核心功能需求：
|
||||
// - 代理配置管理 (Proxy Configuration)
|
||||
// - 动态配置更新 (Dynamic Configuration)
|
||||
// - 流量路由 (Traffic Routing)
|
||||
// - 负载均衡 (Load Balancing)
|
||||
```
|
||||
|
||||
### **3. 分布式追踪系统** 🔴 **优先级：最高**
|
||||
|
||||
#### **3.1 链路追踪**
|
||||
```typescript
|
||||
// 待实现：链路追踪模块
|
||||
@Module({
|
||||
imports: [TracingModule],
|
||||
providers: [TracingService],
|
||||
exports: [TracingService],
|
||||
})
|
||||
export class TracingModule {}
|
||||
|
||||
// 核心功能需求：
|
||||
// - 请求链路追踪 (Request Tracing)
|
||||
// - 跨服务追踪 (Cross-Service Tracing)
|
||||
// - 性能分析 (Performance Analysis)
|
||||
// - 错误追踪 (Error Tracing)
|
||||
```
|
||||
|
||||
#### **3.2 性能监控**
|
||||
```typescript
|
||||
// 待实现：性能监控模块
|
||||
@Module({
|
||||
imports: [PerformanceModule],
|
||||
providers: [PerformanceService],
|
||||
exports: [PerformanceService],
|
||||
})
|
||||
export class PerformanceModule {}
|
||||
|
||||
// 核心功能需求：
|
||||
// - 响应时间监控 (Response Time Monitoring)
|
||||
// - 吞吐量监控 (Throughput Monitoring)
|
||||
// - 资源使用监控 (Resource Usage Monitoring)
|
||||
// - 性能指标聚合 (Performance Metrics Aggregation)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## ⚠️ **部分缺失功能（建议补充）**
|
||||
|
||||
### **4. API网关管理** 🟡 **优先级：高**
|
||||
|
||||
#### **4.1 路由配置管理**
|
||||
```typescript
|
||||
// 待实现：路由配置管理模块
|
||||
@Module({
|
||||
imports: [RouteConfigModule],
|
||||
providers: [RouteConfigService],
|
||||
exports: [RouteConfigService],
|
||||
})
|
||||
export class RouteConfigModule {}
|
||||
|
||||
// 核心功能需求：
|
||||
// - 动态路由配置 (Dynamic Route Configuration)
|
||||
// - 路由规则管理 (Route Rule Management)
|
||||
// - 路由策略配置 (Route Policy Configuration)
|
||||
// - 路由版本管理 (Route Version Management)
|
||||
```
|
||||
|
||||
#### **4.2 限流配置管理**
|
||||
```typescript
|
||||
// 待实现：限流配置管理模块
|
||||
@Module({
|
||||
imports: [RateLimitModule],
|
||||
providers: [RateLimitService],
|
||||
exports: [RateLimitService],
|
||||
})
|
||||
export class RateLimitModule {}
|
||||
|
||||
// 核心功能需求：
|
||||
// - 基于用户的限流 (User-Based Rate Limiting)
|
||||
// - 基于IP的限流 (IP-Based Rate Limiting)
|
||||
// - 基于API的限流 (API-Based Rate Limiting)
|
||||
// - 动态限流配置 (Dynamic Rate Limit Configuration)
|
||||
```
|
||||
|
||||
### **5. 监控告警系统** 🟡 **优先级：高**
|
||||
|
||||
#### **5.1 性能监控**
|
||||
```typescript
|
||||
// 待实现：性能监控模块
|
||||
@Module({
|
||||
imports: [MonitoringModule],
|
||||
providers: [MonitoringService],
|
||||
exports: [MonitoringService],
|
||||
})
|
||||
export class MonitoringModule {}
|
||||
|
||||
// 核心功能需求：
|
||||
// - 实时性能监控 (Real-Time Performance Monitoring)
|
||||
// - 历史性能分析 (Historical Performance Analysis)
|
||||
// - 性能趋势分析 (Performance Trend Analysis)
|
||||
// - 性能报告生成 (Performance Report Generation)
|
||||
```
|
||||
|
||||
#### **5.2 告警系统**
|
||||
```typescript
|
||||
// 待实现：告警系统模块
|
||||
@Module({
|
||||
imports: [AlertingModule],
|
||||
providers: [AlertingService],
|
||||
exports: [AlertingService],
|
||||
})
|
||||
export class AlertingModule {}
|
||||
|
||||
// 核心功能需求：
|
||||
// - 告警规则配置 (Alert Rule Configuration)
|
||||
// - 告警触发机制 (Alert Trigger Mechanism)
|
||||
// - 告警通知渠道 (Alert Notification Channels)
|
||||
// - 告警升级策略 (Alert Escalation Strategy)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## ✨ **高级特性功能（可选实现）**
|
||||
|
||||
### **6. 高级负载均衡** 🟢 **优先级：中**
|
||||
|
||||
#### **6.1 熔断器模式**
|
||||
```typescript
|
||||
// 待实现：熔断器模块
|
||||
@Module({
|
||||
imports: [CircuitBreakerModule],
|
||||
providers: [CircuitBreakerService],
|
||||
exports: [CircuitBreakerService],
|
||||
})
|
||||
export class CircuitBreakerModule {}
|
||||
|
||||
// 核心功能需求：
|
||||
// - 熔断器状态管理 (Circuit Breaker State Management)
|
||||
// - 熔断器策略配置 (Circuit Breaker Policy Configuration)
|
||||
// - 熔断器监控 (Circuit Breaker Monitoring)
|
||||
// - 自动恢复机制 (Auto Recovery Mechanism)
|
||||
```
|
||||
|
||||
#### **6.2 重试机制**
|
||||
```typescript
|
||||
// 待实现：重试机制模块
|
||||
@Module({
|
||||
imports: [RetryModule],
|
||||
providers: [RetryService],
|
||||
exports: [RetryService],
|
||||
})
|
||||
export class RetryModule {}
|
||||
|
||||
// 核心功能需求：
|
||||
// - 重试策略配置 (Retry Policy Configuration)
|
||||
// - 指数退避算法 (Exponential Backoff)
|
||||
// - 重试次数限制 (Retry Count Limitation)
|
||||
// - 重试条件配置 (Retry Condition Configuration)
|
||||
```
|
||||
|
||||
### **7. 缓存网关** 🟢 **优先级：中**
|
||||
|
||||
#### **7.1 响应缓存**
|
||||
```typescript
|
||||
// 待实现：响应缓存模块
|
||||
@Module({
|
||||
imports: [ResponseCacheModule],
|
||||
providers: [ResponseCacheService],
|
||||
exports: [ResponseCacheService],
|
||||
})
|
||||
export class ResponseCacheModule {}
|
||||
|
||||
// 核心功能需求：
|
||||
// - 响应缓存策略 (Response Caching Strategy)
|
||||
// - 缓存失效管理 (Cache Invalidation Management)
|
||||
// - 缓存预热机制 (Cache Warming Mechanism)
|
||||
// - 缓存统计监控 (Cache Statistics Monitoring)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📅 **开发计划时间表**
|
||||
|
||||
### **第一阶段：核心微服务网关（3-6个月）**
|
||||
|
||||
#### **第1个月：服务发现系统**
|
||||
- [ ] 设计服务发现架构
|
||||
- [ ] 实现服务注册功能
|
||||
- [ ] 实现服务发现功能
|
||||
- [ ] 添加健康检查机制
|
||||
- [ ] 编写单元测试
|
||||
|
||||
#### **第2个月：负载均衡系统**
|
||||
- [ ] 设计负载均衡架构
|
||||
- [ ] 实现基础负载均衡算法
|
||||
- [ ] 实现一致性哈希算法
|
||||
- [ ] 添加健康检查负载均衡
|
||||
- [ ] 编写单元测试
|
||||
|
||||
#### **第3个月：服务注册系统**
|
||||
- [ ] 设计服务注册架构
|
||||
- [ ] 实现自动服务注册
|
||||
- [ ] 实现服务心跳检测
|
||||
- [ ] 实现服务状态管理
|
||||
- [ ] 编写单元测试
|
||||
|
||||
### **第二阶段：服务网格集成（6-9个月）**
|
||||
|
||||
#### **第4个月：Istio集成**
|
||||
- [ ] 研究Istio架构
|
||||
- [ ] 实现Istio客户端
|
||||
- [ ] 集成流量管理功能
|
||||
- [ ] 集成安全策略功能
|
||||
- [ ] 编写集成测试
|
||||
|
||||
#### **第5个月：Envoy代理集成**
|
||||
- [ ] 研究Envoy架构
|
||||
- [ ] 实现Envoy客户端
|
||||
- [ ] 集成代理配置管理
|
||||
- [ ] 集成动态配置更新
|
||||
- [ ] 编写集成测试
|
||||
|
||||
#### **第6个月：服务网格功能**
|
||||
- [ ] 实现流量路由功能
|
||||
- [ ] 实现负载均衡功能
|
||||
- [ ] 实现安全策略功能
|
||||
- [ ] 实现可观测性功能
|
||||
- [ ] 编写集成测试
|
||||
|
||||
### **第三阶段：分布式追踪（9-12个月）**
|
||||
|
||||
#### **第7个月：链路追踪基础**
|
||||
- [ ] 设计链路追踪架构
|
||||
- [ ] 实现请求链路追踪
|
||||
- [ ] 实现跨服务追踪
|
||||
- [ ] 实现追踪数据收集
|
||||
- [ ] 编写单元测试
|
||||
|
||||
#### **第8个月：性能监控**
|
||||
- [ ] 设计性能监控架构
|
||||
- [ ] 实现响应时间监控
|
||||
- [ ] 实现吞吐量监控
|
||||
- [ ] 实现资源使用监控
|
||||
- [ ] 编写单元测试
|
||||
|
||||
#### **第9个月：错误追踪**
|
||||
- [ ] 设计错误追踪架构
|
||||
- [ ] 实现错误收集功能
|
||||
- [ ] 实现错误分析功能
|
||||
- [ ] 实现错误报告功能
|
||||
- [ ] 编写单元测试
|
||||
|
||||
### **第四阶段：高级特性（12-15个月）**
|
||||
|
||||
#### **第10个月：API网关管理**
|
||||
- [ ] 设计API网关管理架构
|
||||
- [ ] 实现动态路由配置
|
||||
- [ ] 实现路由规则管理
|
||||
- [ ] 实现路由策略配置
|
||||
- [ ] 编写单元测试
|
||||
|
||||
#### **第11个月：监控告警系统**
|
||||
- [ ] 设计监控告警架构
|
||||
- [ ] 实现性能监控功能
|
||||
- [ ] 实现告警规则配置
|
||||
- [ ] 实现告警通知功能
|
||||
- [ ] 编写单元测试
|
||||
|
||||
#### **第12个月：高级负载均衡**
|
||||
- [ ] 设计高级负载均衡架构
|
||||
- [ ] 实现熔断器模式
|
||||
- [ ] 实现重试机制
|
||||
- [ ] 实现高级算法
|
||||
- [ ] 编写单元测试
|
||||
|
||||
---
|
||||
|
||||
## 🛠️ **技术实现建议**
|
||||
|
||||
### **推荐技术栈**
|
||||
|
||||
#### **微服务框架**
|
||||
- **服务发现**: Consul、Eureka、Zookeeper
|
||||
- **负载均衡**: Ribbon、LoadBalancer
|
||||
- **熔断器**: Hystrix、Resilience4j
|
||||
- **重试机制**: Retry4j、Spring Retry
|
||||
|
||||
#### **服务网格**
|
||||
- **Istio**: 服务网格控制平面
|
||||
- **Envoy**: 高性能代理
|
||||
- **Linkerd**: 轻量级服务网格
|
||||
- **Consul Connect**: 基于Consul的服务网格
|
||||
|
||||
#### **监控追踪**
|
||||
- **Jaeger**: 分布式追踪系统
|
||||
- **Zipkin**: 分布式追踪系统
|
||||
- **Prometheus**: 监控系统
|
||||
- **Grafana**: 可视化平台
|
||||
|
||||
#### **API网关**
|
||||
- **Kong**: 高性能API网关
|
||||
- **Traefik**: 现代HTTP反向代理
|
||||
- **Ambassador**: Kubernetes原生API网关
|
||||
- **Gloo**: 功能丰富的API网关
|
||||
|
||||
### **架构设计原则**
|
||||
|
||||
1. **模块化设计**: 每个功能模块独立，便于维护和扩展
|
||||
2. **接口标准化**: 定义清晰的接口规范，便于集成
|
||||
3. **配置外部化**: 支持外部配置，便于部署和运维
|
||||
4. **监控可观测**: 全面的监控和追踪能力
|
||||
5. **高可用设计**: 支持故障转移和自动恢复
|
||||
6. **性能优化**: 支持高并发和低延迟
|
||||
|
||||
---
|
||||
|
||||
## 📊 **成功指标**
|
||||
|
||||
### **功能完整性指标**
|
||||
- [ ] 微服务网关功能完整度 ≥ 90%
|
||||
- [ ] 服务网格集成完整度 ≥ 80%
|
||||
- [ ] 分布式追踪完整度 ≥ 85%
|
||||
- [ ] 监控告警完整度 ≥ 80%
|
||||
|
||||
### **性能指标**
|
||||
- [ ] 网关延迟 ≤ 10ms
|
||||
- [ ] 支持并发请求 ≥ 10,000 QPS
|
||||
- [ ] 服务发现响应时间 ≤ 100ms
|
||||
- [ ] 负载均衡响应时间 ≤ 5ms
|
||||
|
||||
### **可靠性指标**
|
||||
- [ ] 系统可用性 ≥ 99.9%
|
||||
- [ ] 故障恢复时间 ≤ 30秒
|
||||
- [ ] 数据一致性 ≥ 99.99%
|
||||
- [ ] 错误率 ≤ 0.1%
|
||||
|
||||
---
|
||||
|
||||
## 🔍 **风险评估**
|
||||
|
||||
### **技术风险**
|
||||
- **微服务复杂性**: 微服务架构增加了系统复杂性
|
||||
- **服务网格学习成本**: Istio等工具学习成本较高
|
||||
- **分布式系统挑战**: 分布式追踪和监控实现复杂
|
||||
|
||||
### **资源风险**
|
||||
- **开发时间**: 预计需要15个月完成所有功能
|
||||
- **技术人才**: 需要具备微服务和云原生经验的开发人员
|
||||
- **测试资源**: 需要大量的测试环境和测试数据
|
||||
|
||||
### **运维风险**
|
||||
- **部署复杂性**: 微服务部署比单体应用复杂
|
||||
- **监控复杂性**: 分布式系统监控比单体系统复杂
|
||||
- **故障排查**: 分布式系统故障排查难度增加
|
||||
|
||||
---
|
||||
|
||||
## 📚 **参考资料**
|
||||
|
||||
### **官方文档**
|
||||
- [NestJS 官方文档](https://nestjs.com/)
|
||||
- [Istio 官方文档](https://istio.io/)
|
||||
- [Envoy 官方文档](https://www.envoyproxy.io/)
|
||||
- [Consul 官方文档](https://www.consul.io/)
|
||||
|
||||
### **技术博客**
|
||||
- [微服务架构设计模式](https://microservices.io/)
|
||||
- [服务网格最佳实践](https://servicemesh.io/)
|
||||
- [分布式追踪实现指南](https://opentracing.io/)
|
||||
|
||||
### **开源项目**
|
||||
- [NestJS 微服务示例](https://github.com/nestjs/nest/tree/master/sample)
|
||||
- [Istio 示例项目](https://github.com/istio/istio/tree/master/samples)
|
||||
- [Envoy 示例配置](https://github.com/envoyproxy/envoy/tree/master/examples)
|
||||
|
||||
---
|
||||
|
||||
## 📝 **更新日志**
|
||||
|
||||
| 版本 | 日期 | 更新内容 | 更新人 |
|
||||
|------|------|----------|--------|
|
||||
| v1.0.0 | 2025-08-25 | 初始版本，基础功能分析 | 系统分析员 |
|
||||
| v1.1.0 | - | 待更新 | - |
|
||||
| v1.2.0 | - | 待更新 | - |
|
||||
|
||||
---
|
||||
|
||||
> **注意**: 本文档将根据开发进度和需求变化持续更新，请定期查看最新版本。
|
||||
100
admin/docs/src/wwjcloud/gateway/index.md
Normal file
100
admin/docs/src/wwjcloud/gateway/index.md
Normal file
@@ -0,0 +1,100 @@
|
||||
# WWJCloud 网关系统文档
|
||||
|
||||
> 本文档集合涵盖了 WWJCloud 网关系统的完整技术文档
|
||||
|
||||
## 📚 **文档导航**
|
||||
|
||||
### **🚀 快速开始**
|
||||
- [网关系统概览](./overview.md) - 了解网关系统的基本概念和架构
|
||||
- [快速开始指南](./quick-start.md) - 快速上手网关系统开发
|
||||
|
||||
### **🏗️ 架构设计**
|
||||
- [技术架构详解](./architecture.md) - 深入理解网关系统的技术架构
|
||||
- [组件设计说明](./components.md) - 了解各个组件的设计原理
|
||||
|
||||
### **📋 开发指南**
|
||||
- [开发计划](./development-plan.md) - 详细的开发时间表和任务分解
|
||||
- [API 参考](./api-reference.md) - 网关系统的 API 接口文档
|
||||
- [配置指南](./configuration.md) - 系统配置和参数说明
|
||||
|
||||
### **🔧 运维指南**
|
||||
- [部署指南](./deployment.md) - 系统部署和安装说明
|
||||
- [监控告警](./monitoring.md) - 系统监控和告警配置
|
||||
- [故障排查](./troubleshooting.md) - 常见问题解决方案
|
||||
|
||||
### **📊 性能优化**
|
||||
- [性能调优](./performance.md) - 系统性能优化指南
|
||||
- [负载均衡](./load-balancing.md) - 负载均衡策略和配置
|
||||
- [缓存策略](./caching.md) - 缓存机制和优化方案
|
||||
|
||||
---
|
||||
|
||||
## 🌟 **核心特性**
|
||||
|
||||
### **微服务网关**
|
||||
- **服务发现**: 自动服务注册和发现
|
||||
- **负载均衡**: 多种负载均衡算法支持
|
||||
- **熔断器**: 服务保护机制
|
||||
- **重试机制**: 智能重试策略
|
||||
|
||||
### **服务网格**
|
||||
- **Istio 集成**: 完整的服务网格解决方案
|
||||
- **Envoy 代理**: 高性能代理支持
|
||||
- **流量管理**: 灵活的流量路由策略
|
||||
- **安全策略**: 多层次安全防护
|
||||
|
||||
### **监控追踪**
|
||||
- **分布式追踪**: 完整的请求链路追踪
|
||||
- **性能监控**: 实时性能指标监控
|
||||
- **告警系统**: 智能告警和通知
|
||||
- **日志聚合**: 集中化日志管理
|
||||
|
||||
---
|
||||
|
||||
## 🎯 **适用场景**
|
||||
|
||||
- **企业级应用**: 大型分布式系统
|
||||
- **微服务架构**: 服务间通信管理
|
||||
- **云原生部署**: 容器化和 Kubernetes 支持
|
||||
- **高并发系统**: 高性能网关需求
|
||||
- **多租户系统**: SaaS 应用支持
|
||||
|
||||
---
|
||||
|
||||
## 🚀 **快速体验**
|
||||
|
||||
### **环境要求**
|
||||
- Node.js >= 18.0.0
|
||||
- NestJS >= 11.0.0
|
||||
- Docker >= 20.0.0
|
||||
- Kubernetes >= 1.20.0
|
||||
|
||||
### **快速启动**
|
||||
```bash
|
||||
# 克隆项目
|
||||
git clone <repository-url>
|
||||
cd wwjcloud-nestjs
|
||||
|
||||
# 安装依赖
|
||||
npm install
|
||||
|
||||
# 启动开发环境
|
||||
npm run start:dev
|
||||
```
|
||||
|
||||
### **访问地址**
|
||||
- **API 文档**: http://localhost:3001/docs
|
||||
- **健康检查**: http://localhost:3001/health
|
||||
- **监控面板**: http://localhost:3001/monitoring
|
||||
|
||||
---
|
||||
|
||||
## 📞 **技术支持**
|
||||
|
||||
- **文档问题**: 在 GitHub 上提交 Issue
|
||||
- **技术交流**: 加入技术交流群
|
||||
- **商业支持**: 联系技术支持团队
|
||||
|
||||
---
|
||||
|
||||
> **注意**: 本文档将根据开发进度持续更新，请定期查看最新版本。
|
||||
37
admin/docs/src/wwjcloud/gateway/kong/README.md
Normal file
37
admin/docs/src/wwjcloud/gateway/kong/README.md
Normal file
@@ -0,0 +1,37 @@
|
||||
# Kong decK 使用说明
|
||||
|
||||
## 前置
|
||||
- 已安装并启动 Kong（DB 模式，推荐 Postgres）
|
||||
- 安装 decK：参考官方文档
|
||||
|
||||
## 目录
|
||||
- 配置文件：`deck.yaml`
|
||||
|
||||
## 常用命令
|
||||
```bash
|
||||
# 校验配置
|
||||
deck validate --state deck.yaml
|
||||
|
||||
# 直接导入（会覆盖已有同名资源）
|
||||
deck sync --state deck.yaml
|
||||
|
||||
# 以 diff 方式查看变更
|
||||
deck diff --state deck.yaml
|
||||
```
|
||||
|
||||
## 本地开发说明
|
||||
- services.host 使用 `host.docker.internal:3001` 将请求转发到宿主机运行的 NestJS
|
||||
- 若 Kong 与后端同在宿主机，可将 host 改为 `localhost`
|
||||
|
||||
## 插件
|
||||
- correlation-id：统一请求 ID（上游未传则生成），下游透传
|
||||
- rate-limiting：示例每分钟 300 次，可据环境覆盖
|
||||
- prometheus：开启 Kong 指标，抓取地址 `:8001/metrics`
|
||||
|
||||
## 环境差异化
|
||||
- 建议按环境拆分 `deck.dev.yaml`、`deck.prod.yaml` 或使用 CI 注入变量
|
||||
- 关键变量：上游 host/port、限流阈值、超时、JWT 公钥/密钥
|
||||
|
||||
## 与后端配合
|
||||
- 后端会记录并透传 `X-Request-ID` / `traceparent`
|
||||
- Kong 可作为北向入口，/api 与 /adminapi 分流
|
||||
73
admin/docs/src/wwjcloud/gateway/kong/deck.yaml
Normal file
73
admin/docs/src/wwjcloud/gateway/kong/deck.yaml
Normal file
@@ -0,0 +1,73 @@
|
||||
_format_version: "3.0"
|
||||
_transform: true
|
||||
|
||||
info:
|
||||
select_tags:
|
||||
- wwjcloud
|
||||
|
||||
services:
|
||||
- name: wwjcloud-backend
|
||||
host: host.docker.internal
|
||||
port: 3001
|
||||
protocol: http
|
||||
routes:
|
||||
- name: wwjcloud-api
|
||||
paths:
|
||||
- /api
|
||||
strip_path: false
|
||||
methods:
|
||||
- GET
|
||||
- POST
|
||||
- PUT
|
||||
- PATCH
|
||||
- DELETE
|
||||
- OPTIONS
|
||||
tags: [wwjcloud]
|
||||
- name: wwjcloud-adminapi
|
||||
paths:
|
||||
- /adminapi
|
||||
strip_path: false
|
||||
methods:
|
||||
- GET
|
||||
- POST
|
||||
- PUT
|
||||
- PATCH
|
||||
- DELETE
|
||||
- OPTIONS
|
||||
tags: [wwjcloud]
|
||||
tags: [wwjcloud]
|
||||
|
||||
plugins:
|
||||
# 统一关联请求 ID（如果上游没传则生成）
|
||||
- name: correlation-id
|
||||
config:
|
||||
header_name: X-Request-ID
|
||||
generator: uuid
|
||||
echo_downstream: true
|
||||
tags: [wwjcloud]
|
||||
|
||||
# 速率限制（示例：每分钟 300 次）
|
||||
- name: rate-limiting
|
||||
config:
|
||||
minute: 300
|
||||
policy: local
|
||||
fault_tolerant: true
|
||||
hide_client_headers: false
|
||||
tags: [wwjcloud]
|
||||
|
||||
# Prometheus 指标
|
||||
- name: prometheus
|
||||
tags: [wwjcloud]
|
||||
|
||||
# 上游超时（毫秒）
|
||||
- name: upstream-timeout
|
||||
enabled: false
|
||||
config:
|
||||
connect_timeout: 6000
|
||||
send_timeout: 30000
|
||||
read_timeout: 30000
|
||||
tags: [wwjcloud]
|
||||
|
||||
consumers: []
|
||||
|
||||
jwt_secrets: []
|
||||
230
admin/docs/src/wwjcloud/gateway/overview.md
Normal file
230
admin/docs/src/wwjcloud/gateway/overview.md
Normal file
@@ -0,0 +1,230 @@
|
||||
# 网关系统概览
|
||||
|
||||
> 了解 WWJCloud 网关系统的基本概念、架构和特性
|
||||
|
||||
## 🌟 **什么是网关系统**
|
||||
|
||||
网关系统是 WWJCloud 框架的核心组件，负责处理所有进入系统的请求，提供路由、负载均衡、认证授权、监控追踪等核心功能。它是连接前端应用和后端服务的桥梁，确保系统的高可用性、安全性和可观测性。
|
||||
|
||||
### **核心作用**
|
||||
- **统一入口**: 为所有服务提供统一的访问入口
|
||||
- **流量管理**: 智能路由和负载均衡
|
||||
- **安全防护**: 认证授权和安全策略
|
||||
- **性能优化**: 缓存、限流、熔断等机制
|
||||
- **监控追踪**: 完整的可观测性支持
|
||||
|
||||
---
|
||||
|
||||
## 🏗️ **系统架构**
|
||||
|
||||
### **整体架构图**
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ 用户请求层 │
|
||||
├─────────────────────────────────────────────────────────────┤
|
||||
│ Web浏览器 │ 移动应用 │ API客户端 │ 第三方系统 │
|
||||
└─────────────────────┬───────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ CDN + 负载均衡层 │
|
||||
├─────────────────────────────────────────────────────────────┤
|
||||
│ 全球CDN │ 智能DNS │ 负载均衡器 │ 健康检查 │
|
||||
└─────────────────────┬───────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ API网关层 (Kong/Envoy) │
|
||||
├─────────────────────────────────────────────────────────────┤
|
||||
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
|
||||
│ │ 路由管理 │ │ 限流控制 │ │ 安全策略 │ │
|
||||
│ │ │ │ │ │ │ │
|
||||
│ │ • 动态路由 │ │ • 用户限流 │ │ • 访问控制 │ │
|
||||
│ │ • 路由版本 │ │ • IP限流 │ │ • 流量控制 │ │
|
||||
│ │ • 路由策略 │ │ • API限流 │ │ • 安全防护 │ │
|
||||
│ └─────────────┘ └─────────────┘ └─────────────┘ │
|
||||
└─────────────────────┬───────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ NestJS 微服务网关层 │
|
||||
├─────────────────────────────────────────────────────────────┤
|
||||
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
|
||||
│ │ 服务发现 │ │ 负载均衡 │ │ 熔断器 │ │
|
||||
│ │ │ │ │ │ │ │
|
||||
│ │ • 服务注册 │ │ • 轮询算法 │ │ • 状态管理 │ │
|
||||
│ │ • 服务发现 │ │ • 权重算法 │ │ • 策略配置 │ │
|
||||
│ │ • 健康检查 │ │ • 一致性哈希│ │ • 自动恢复 │ │
|
||||
│ └─────────────┘ └─────────────┘ └─────────────┘ │
|
||||
└─────────────────────┬───────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ 服务网格层 (Istio) │
|
||||
├─────────────────────────────────────────────────────────────┤
|
||||
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
|
||||
│ │ 流量管理 │ │ 安全策略 │ │ 可观测性 │ │
|
||||
│ │ │ │ │ │ │ │
|
||||
│ │ • 流量路由 │ │ • 身份认证 │ │ • 指标收集 │ │
|
||||
│ │ • 流量分割 │ │ • 授权策略 │ │ • 日志聚合 │ │
|
||||
│ │ • 流量镜像 │ │ • 加密通信 │ │ • 链路追踪 │ │
|
||||
│ └─────────────┘ └─────────────┘ └─────────────┘ │
|
||||
└─────────────────────┬───────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ 微服务层 │
|
||||
├─────────────────────────────────────────────────────────────┤
|
||||
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
|
||||
│ │ 用户服务 │ │ 权限服务 │ │ 文件服务 │ │
|
||||
│ │ │ │ │ │ │ │
|
||||
│ │ • 会员管理 │ │ • 角色管理 │ │ • 文件上传 │ │
|
||||
│ │ • 管理员 │ │ • 菜单管理 │ │ • 文件管理 │ │
|
||||
│ │ • 认证授权 │ │ • 权限控制 │ │ • 存储适配 │ │
|
||||
│ └─────────────┘ └─────────────┘ └─────────────┘ │
|
||||
└─────────────────────┬───────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ 数据存储层 │
|
||||
├─────────────────────────────────────────────────────────────┤
|
||||
│ MySQL集群 │ Redis集群 │ 对象存储 │ 时序数据库 │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔧 **核心组件**
|
||||
|
||||
### **1. API网关层**
|
||||
- **Kong**: 高性能API网关，提供丰富的插件生态
|
||||
- **Envoy**: 现代HTTP代理，支持动态配置
|
||||
- **功能**: 路由管理、限流控制、安全策略
|
||||
|
||||
### **2. 微服务网关层**
|
||||
- **服务发现**: 自动服务注册和发现机制
|
||||
- **负载均衡**: 多种负载均衡算法支持
|
||||
- **熔断器**: 服务保护和服务降级
|
||||
- **重试机制**: 智能重试和指数退避
|
||||
|
||||
### **3. 服务网格层**
|
||||
- **Istio**: 完整的服务网格解决方案
|
||||
- **流量管理**: 灵活的流量路由策略
|
||||
- **安全策略**: 多层次安全防护
|
||||
- **可观测性**: 完整的监控和追踪
|
||||
|
||||
### **4. 监控追踪层**
|
||||
- **Prometheus**: 指标收集和告警
|
||||
- **Jaeger**: 分布式链路追踪
|
||||
- **Grafana**: 数据可视化和仪表板
|
||||
- **ELK Stack**: 日志聚合和分析
|
||||
|
||||
---
|
||||
|
||||
## 🚀 **核心特性**
|
||||
|
||||
### **微服务支持**
|
||||
- **服务发现**: 支持多种服务发现机制
|
||||
- **负载均衡**: 轮询、权重、一致性哈希等算法
|
||||
- **熔断器**: 自动故障检测和恢复
|
||||
- **重试机制**: 智能重试策略
|
||||
|
||||
### **安全防护**
|
||||
- **认证授权**: JWT、OAuth2.0、RBAC
|
||||
- **访问控制**: 基于角色的权限控制
|
||||
- **流量控制**: 限流、熔断、降级
|
||||
- **加密通信**: TLS/SSL 加密支持
|
||||
|
||||
### **性能优化**
|
||||
- **缓存机制**: 多级缓存策略
|
||||
- **连接池**: 数据库和外部服务连接池
|
||||
- **异步处理**: 非阻塞异步处理
|
||||
- **资源管理**: 智能资源分配
|
||||
|
||||
### **可观测性**
|
||||
- **指标监控**: 实时性能指标
|
||||
- **链路追踪**: 完整的请求链路
|
||||
- **日志聚合**: 集中化日志管理
|
||||
- **告警通知**: 智能告警机制
|
||||
|
||||
---
|
||||
|
||||
## 📊 **性能指标**
|
||||
|
||||
### **响应时间**
|
||||
- **网关延迟**: ≤ 10ms
|
||||
- **服务发现**: ≤ 100ms
|
||||
- **负载均衡**: ≤ 5ms
|
||||
- **链路追踪**: ≤ 50ms
|
||||
|
||||
### **吞吐量**
|
||||
- **并发处理**: ≥ 10,000 QPS
|
||||
- **连接数**: ≥ 100,000 并发连接
|
||||
- **缓存命中率**: ≥ 95%
|
||||
- **系统可用性**: ≥ 99.9%
|
||||
|
||||
---
|
||||
|
||||
## 🎯 **应用场景**
|
||||
|
||||
### **企业级应用**
|
||||
- **大型分布式系统**: 支持数百个微服务
|
||||
- **高并发场景**: 支持数万并发用户
|
||||
- **多租户系统**: SaaS 应用支持
|
||||
- **混合云部署**: 跨云平台部署
|
||||
|
||||
### **微服务架构**
|
||||
- **服务治理**: 完整的服务生命周期管理
|
||||
- **流量管理**: 灵活的流量路由策略
|
||||
- **故障隔离**: 服务间故障隔离
|
||||
- **弹性伸缩**: 自动扩缩容支持
|
||||
|
||||
### **云原生应用**
|
||||
- **容器化部署**: Docker 和 Kubernetes 支持
|
||||
- **服务网格**: Istio 和 Envoy 集成
|
||||
- **DevOps**: 自动化部署和运维
|
||||
- **监控告警**: 完整的可观测性
|
||||
|
||||
---
|
||||
|
||||
## 🚀 **快速开始**
|
||||
|
||||
### **环境要求**
|
||||
- Node.js >= 18.0.0
|
||||
- NestJS >= 11.0.0
|
||||
- Docker >= 20.0.0
|
||||
- Kubernetes >= 1.20.0
|
||||
|
||||
### **安装步骤**
|
||||
```bash
|
||||
# 1. 克隆项目
|
||||
git clone <repository-url>
|
||||
cd wwjcloud-nestjs
|
||||
|
||||
# 2. 安装依赖
|
||||
npm install
|
||||
|
||||
# 3. 配置环境
|
||||
cp .env.example .env
|
||||
# 编辑 .env 文件
|
||||
|
||||
# 4. 启动服务
|
||||
npm run start:dev
|
||||
```
|
||||
|
||||
### **验证安装**
|
||||
- **健康检查**: http://localhost:3001/health
|
||||
- **API 文档**: http://localhost:3001/docs
|
||||
- **监控面板**: http://localhost:3001/monitoring
|
||||
|
||||
---
|
||||
|
||||
## 📚 **下一步**
|
||||
|
||||
- [查看技术架构](./architecture.md) - 深入了解技术实现
|
||||
- [阅读开发计划](./development-plan.md) - 了解开发路线图
|
||||
- [开始快速上手](./quick-start.md) - 立即开始使用
|
||||
|
||||
---
|
||||
|
||||
> **提示**: 本文档提供了网关系统的基本概览，如需深入了解特定功能，请查看相应的详细文档。
|
||||
Some files were not shown because too many files have changed in this diff Show More
Reference in New Issue
Block a user