wanwu/wwjcloud-nest-v1
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: 完成 NestJS 后端核心底座开发 (M1-M6) 和 Ant Design Vue 前端迁移

Browse Source 
主要更新：
1. 后端核心底座完成 (M1-M6)：
   - 健康检查、指标监控、分布式锁
   - 事件总线、队列系统、事务管理
   - 安全守卫、多租户隔离、存储适配器
   - 审计日志、配置管理、多语言支持

2. 前端迁移到 Ant Design Vue：
   - 从 Element Plus 迁移到 Ant Design Vue
   - 完善 system 模块 (role/menu/dept)
   - 修复依赖和配置问题

3. 文档完善：
   - AI 开发工作流文档
   - 架构约束和开发规范
   - 项目进度跟踪

4. 其他改进：
   - 修复编译错误和类型问题
   - 完善测试用例
   - 优化项目结构
This commit is contained in:
万物街
2025-08-27 11:24:22 +08:00
parent be07b9ffec
commit 1cd5d3bdef
696 changed files with 36708 additions and 16868 deletions
Download Patch File Download Diff File Expand all files Collapse all files

74
admin/docs/src/components/common-ui/vben-form.md
View File

@@ -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` | - |

0
admin/docs/src/en/guide/essentials/build.md → admin/docs/src/en/veben/guide/essentials/build.md
View File

0
admin/docs/src/en/guide/essentials/concept.md → admin/docs/src/en/veben/guide/essentials/concept.md
View File

0
admin/docs/src/en/guide/essentials/development.md → admin/docs/src/en/veben/guide/essentials/development.md
View File

0
admin/docs/src/en/guide/essentials/external-module.md → admin/docs/src/en/veben/guide/essentials/external-module.md
View File

0
admin/docs/src/en/guide/essentials/icons.md → admin/docs/src/en/veben/guide/essentials/icons.md
View File

0
admin/docs/src/en/guide/essentials/route.md → admin/docs/src/en/veben/guide/essentials/route.md
View File

0
admin/docs/src/en/guide/essentials/server.md → admin/docs/src/en/veben/guide/essentials/server.md
View File

0
admin/docs/src/en/guide/essentials/settings.md → admin/docs/src/en/veben/guide/essentials/settings.md
View File

0
admin/docs/src/en/guide/essentials/styles.md → admin/docs/src/en/veben/guide/essentials/styles.md
View File

0
admin/docs/src/en/guide/in-depth/access.md → admin/docs/src/en/veben/guide/in-depth/access.md
View File

0
admin/docs/src/en/guide/in-depth/check-updates.md → admin/docs/src/en/veben/guide/in-depth/check-updates.md
View File

0
admin/docs/src/en/guide/in-depth/features.md → admin/docs/src/en/veben/guide/in-depth/features.md
View File

0
admin/docs/src/en/guide/in-depth/layout.md → admin/docs/src/en/veben/guide/in-depth/layout.md
View File

0
admin/docs/src/en/guide/in-depth/loading.md → admin/docs/src/en/veben/guide/in-depth/loading.md
View File

0
admin/docs/src/en/guide/in-depth/locale.md → admin/docs/src/en/veben/guide/in-depth/locale.md
View File

0
admin/docs/src/en/guide/in-depth/login.md → admin/docs/src/en/veben/guide/in-depth/login.md
View File

0
admin/docs/src/en/guide/in-depth/theme.md → admin/docs/src/en/veben/guide/in-depth/theme.md
View File

0
admin/docs/src/en/guide/in-depth/ui-framework.md → admin/docs/src/en/veben/guide/in-depth/ui-framework.md
View File

0
admin/docs/src/en/guide/introduction/changelog.md → admin/docs/src/en/veben/guide/introduction/changelog.md
View File

0
admin/docs/src/en/guide/introduction/quick-start.md → admin/docs/src/en/veben/guide/introduction/quick-start.md
View File

0
admin/docs/src/en/guide/introduction/roadmap.md → admin/docs/src/en/veben/guide/introduction/roadmap.md
View File

0
admin/docs/src/en/guide/introduction/thin.md → admin/docs/src/en/veben/guide/introduction/thin.md
View File

0
admin/docs/src/en/guide/introduction/vben.md → admin/docs/src/en/veben/guide/introduction/vben.md
View File

0
admin/docs/src/en/guide/introduction/why.md → admin/docs/src/en/veben/guide/introduction/why.md
View File

0
admin/docs/src/en/guide/other/faq.md → admin/docs/src/en/veben/guide/other/faq.md
View File

0
admin/docs/src/en/guide/other/project-update.md → admin/docs/src/en/veben/guide/other/project-update.md
View File

0
admin/docs/src/en/guide/other/remove-code.md → admin/docs/src/en/veben/guide/other/remove-code.md
View File

0
admin/docs/src/en/guide/project/changeset.md → admin/docs/src/en/veben/guide/project/changeset.md
View File

0
admin/docs/src/en/guide/project/cli.md → admin/docs/src/en/veben/guide/project/cli.md
View File

0
admin/docs/src/en/guide/project/dir.md → admin/docs/src/en/veben/guide/project/dir.md
View File

0
admin/docs/src/en/guide/project/standard.md → admin/docs/src/en/veben/guide/project/standard.md
View File

0
admin/docs/src/en/guide/project/tailwindcss.md → admin/docs/src/en/veben/guide/project/tailwindcss.md
View File

0
admin/docs/src/en/guide/project/test.md → admin/docs/src/en/veben/guide/project/test.md
View File

0
admin/docs/src/en/guide/project/vite.md → admin/docs/src/en/veben/guide/project/vite.md
View File

76
admin/docs/src/en/veben/index.md Normal file
View 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 />

136
admin/docs/src/index.md
View File

@@ -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>

0
admin/docs/src/guide/essentials/build.md → admin/docs/src/vben/guide/essentials/build.md
View File

0
admin/docs/src/guide/essentials/concept.md → admin/docs/src/vben/guide/essentials/concept.md
View File

0
admin/docs/src/guide/essentials/development.md → admin/docs/src/vben/guide/essentials/development.md
View File

0
admin/docs/src/guide/essentials/external-module.md → admin/docs/src/vben/guide/essentials/external-module.md
View File

0
admin/docs/src/guide/essentials/icons.md → admin/docs/src/vben/guide/essentials/icons.md
View File

0
admin/docs/src/guide/essentials/route.md → admin/docs/src/vben/guide/essentials/route.md
View File

0
admin/docs/src/guide/essentials/server.md → admin/docs/src/vben/guide/essentials/server.md
View File

0
admin/docs/src/guide/essentials/settings.md → admin/docs/src/vben/guide/essentials/settings.md
View File

0
admin/docs/src/guide/essentials/styles.md → admin/docs/src/vben/guide/essentials/styles.md
View File

0
admin/docs/src/guide/in-depth/access.md → admin/docs/src/vben/guide/in-depth/access.md
View File

0
admin/docs/src/guide/in-depth/check-updates.md → admin/docs/src/vben/guide/in-depth/check-updates.md
View File

0
admin/docs/src/guide/in-depth/features.md → admin/docs/src/vben/guide/in-depth/features.md
View File

0
admin/docs/src/guide/in-depth/layout.md → admin/docs/src/vben/guide/in-depth/layout.md
View File

0
admin/docs/src/guide/in-depth/loading.md → admin/docs/src/vben/guide/in-depth/loading.md
View File

0
admin/docs/src/guide/in-depth/locale.md → admin/docs/src/vben/guide/in-depth/locale.md
View File

0
admin/docs/src/guide/in-depth/login.md → admin/docs/src/vben/guide/in-depth/login.md
View File

0
admin/docs/src/guide/in-depth/theme.md → admin/docs/src/vben/guide/in-depth/theme.md
View File

0
admin/docs/src/guide/in-depth/ui-framework.md → admin/docs/src/vben/guide/in-depth/ui-framework.md
View File

113
admin/docs/src/vben/guide/index.md Normal file
View 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 />

0
admin/docs/src/guide/introduction/changelog.md → admin/docs/src/vben/guide/introduction/changelog.md
View File

0
admin/docs/src/guide/introduction/quick-start.md → admin/docs/src/vben/guide/introduction/quick-start.md
View File

0
admin/docs/src/guide/introduction/roadmap.md → admin/docs/src/vben/guide/introduction/roadmap.md
View File

0
admin/docs/src/guide/introduction/thin.md → admin/docs/src/vben/guide/introduction/thin.md
View File

0
admin/docs/src/guide/introduction/vben.md → admin/docs/src/vben/guide/introduction/vben.md
View File

0
admin/docs/src/guide/introduction/why.md → admin/docs/src/vben/guide/introduction/why.md
View File

0
admin/docs/src/guide/other/faq.md → admin/docs/src/vben/guide/other/faq.md
View File

0
admin/docs/src/guide/other/project-update.md → admin/docs/src/vben/guide/other/project-update.md
View File

0
admin/docs/src/guide/other/remove-code.md → admin/docs/src/vben/guide/other/remove-code.md
View File

0
admin/docs/src/guide/project/changeset.md → admin/docs/src/vben/guide/project/changeset.md
View File

0
admin/docs/src/guide/project/cli.md → admin/docs/src/vben/guide/project/cli.md
View File

0
admin/docs/src/guide/project/dir.md → admin/docs/src/vben/guide/project/dir.md
View File

0
admin/docs/src/guide/project/standard.md → admin/docs/src/vben/guide/project/standard.md
View File

0
admin/docs/src/guide/project/tailwindcss.md → admin/docs/src/vben/guide/project/tailwindcss.md
View File

0
admin/docs/src/guide/project/test.md → admin/docs/src/vben/guide/project/test.md
View File

0
admin/docs/src/guide/project/vite.md → admin/docs/src/vben/guide/project/vite.md
View File

21
admin/docs/src/wwjcloud/ai/checklists.md Normal file
View 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
View 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
View 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
View 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
View 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
View 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
View 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
View 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
View 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
View 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
View 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
View 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
View 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
View 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
View 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) - 立即开始使用
---
> **提示**: 本文档提供了网关系统的基本概览，如需深入了解特定功能，请查看相应的详细文档。

375
admin/docs/src/wwjcloud/gateway/quick-start.md Normal file
View File

@@ -0,0 +1,375 @@
# 快速开始指南
> 快速上手 WWJCloud 网关系统，从零开始搭建完整的网关环境
## 🚀 **环境准备**
### **系统要求**
- **操作系统**: Windows 10+, macOS 10.15+, Ubuntu 18.04+
- **Node.js**: >= 18.0.0
- **npm**: >= 8.0.0 或 pnpm >= 7.0.0
- **Docker**: >= 20.0.0 (可选)
- **Kubernetes**: >= 1.20.0 (可选)
### **开发工具**
- **代码编辑器**: VS Code (推荐)
- **API 测试**: Postman 或 Apifox
- **数据库管理**: MySQL Workbench 或 phpMyAdmin
- **容器管理**: Docker Desktop
---
## 📦 **安装步骤**
### **1. 克隆项目**
```bash
# 克隆项目到本地
git clone <your-repository-url>
cd wwjcloud-nestjs
# 检查项目结构
ls -la
```
### **2. 安装依赖**
```bash
# 使用 npm 安装
npm install
# 或使用 pnpm (推荐)
pnpm install
# 检查安装结果
npm list --depth=0
```
### **3. 环境配置**
```bash
# 复制环境配置文件
cp .env.example .env
# 编辑环境配置
nano .env
```
**环境配置示例**:
```env
# 应用配置
NODE_ENV=development
PORT=3001
# 数据库配置
DB_HOST=localhost
DB_PORT=3306
DB_USERNAME=root
DB_PASSWORD=your_password
DB_DATABASE=wwjcloud
# Redis配置
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_PASSWORD=
# JWT配置
JWT_SECRET=your_jwt_secret_key
JWT_EXPIRES_IN=7d
# 日志配置
LOG_LEVEL=info
```
### **4. 数据库准备**
```bash
# 启动 MySQL 服务
sudo systemctl start mysql
# 创建数据库
mysql -u root -p
CREATE DATABASE wwjcloud CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
EXIT;
# 导入数据库结构
mysql -u root -p wwjcloud < sql/wwjcloud.sql
```
### **5. 启动服务**
```bash
# 开发模式启动
npm run start:dev
# 或使用 pnpm
pnpm start:dev
```
---
## ✅ **验证安装**
### **健康检查**
```bash
# 检查服务状态
curl http://localhost:3001/health
# 预期响应
{
"status": "ok",
"timestamp": "2025-08-25T02:36:55.746Z",
"uptime": 123.456
}
```
### **API 文档**
- **访问地址**: http://localhost:3001/docs
- **功能**: 查看所有可用的 API 接口
- **测试**: 在线测试 API 功能
### **服务状态**
```bash
# 检查端口占用
netstat -tulpn | grep :3001
# 检查进程状态
ps aux | grep node
```
---
## 🔧 **基础配置**
### **路由配置**
```typescript
// src/app.module.ts
@Module({
imports: [
// 基础模块
ConfigModule.forRoot({
isGlobal: true,
load: [configuration],
}),
// 网关模块
GatewayModule,
// 业务模块
UserModule,
AuthModule,
],
})
export class AppModule {}
```
### **中间件配置**
```typescript
// src/main.ts
async function bootstrap() {
const app = await NestFactory.create(AppModule);
// 全局中间件
app.useGlobalPipes(new ValidationPipe());
app.useGlobalInterceptors(new TransformInterceptor());
// CORS 配置
app.enableCors({
origin: ['http://localhost:3000', 'http://localhost:8080'],
credentials: true,
});
// 启动服务
await app.listen(3001);
}
```
### **环境变量配置**
```typescript
// src/config/index.ts
export default () => ({
nodeEnv: process.env.NODE_ENV || 'development',
port: parseInt(process.env.PORT || '3000', 10),
// 网关配置
gateway: {
enabled: process.env.GATEWAY_ENABLED === 'true',
timeout: parseInt(process.env.GATEWAY_TIMEOUT || '30000', 10),
retries: parseInt(process.env.GATEWAY_RETRIES || '3', 10),
},
// 负载均衡配置
loadBalancer: {
algorithm: process.env.LB_ALGORITHM || 'round-robin',
healthCheck: process.env.LB_HEALTH_CHECK === 'true',
},
});
```
---
## 🧪 **测试网关功能**
### **1. 基础路由测试**
```bash
# 测试用户注册
curl -X POST http://localhost:3001/api/member/register \
-H "Content-Type: application/json" \
-d '{
"username": "testuser",
"email": "test@example.com",
"password": "password123"
}'
# 测试用户登录
curl -X POST http://localhost:3001/api/member/login \
-H "Content-Type: application/json" \
-d '{
"username": "testuser",
"password": "password123"
}'
```
### **2. 认证测试**
```bash
# 获取 JWT Token
TOKEN=$(curl -s -X POST http://localhost:3001/api/member/login \
-H "Content-Type: application/json" \
-d '{"username": "testuser", "password": "password123"}' \
| jq -r '.access_token')
# 使用 Token 访问受保护的接口
curl -X GET http://localhost:3001/api/member/profile \
-H "Authorization: Bearer $TOKEN"
```
### **3. 负载均衡测试**
```bash
# 模拟并发请求
for i in {1..10}; do
curl -s http://localhost:3001/api/member/profile \
-H "Authorization: Bearer $TOKEN" &
done
wait
```
---
## 📊 **监控和日志**
### **日志查看**
```bash
# 查看应用日志
tail -f logs/app-$(date +%Y-%m-%d).log
# 查看错误日志
grep "ERROR" logs/app-$(date +%Y-%m-%d).log
# 查看性能日志
grep "PERFORMANCE" logs/app-$(date +%Y-%m-%d).log
```
### **性能监控**
```bash
# 检查内存使用
ps -o pid,ppid,%mem,%cpu,cmd -p $(pgrep node)
# 检查网络连接
netstat -an | grep :3001 | wc -l
# 检查响应时间
curl -w "@curl-format.txt" -o /dev/null -s http://localhost:3001/health
```
**curl-format.txt 内容**:
```
time_namelookup: %{time_namelookup}\n
time_connect: %{time_connect}\n
time_appconnect: %{time_appconnect}\n
time_pretransfer: %{time_pretransfer}\n
time_redirect: %{time_redirect}\n
time_starttransfer: %{time_starttransfer}\n
----------\n
time_total: %{time_total}\n
```
---
## 🚨 **常见问题**
### **1. 端口被占用**
```bash
# 查找占用端口的进程
lsof -i :3001
# 杀死进程
kill -9 <PID>
# 或者修改端口
export PORT=3002
npm run start:dev
```
### **2. 数据库连接失败**
```bash
# 检查 MySQL 服务状态
sudo systemctl status mysql
# 检查数据库连接
mysql -u root -p -h localhost
# 检查防火墙设置
sudo ufw status
```
### **3. 依赖安装失败**
```bash
# 清理缓存
npm cache clean --force
# 删除 node_modules
rm -rf node_modules package-lock.json
# 重新安装
npm install
```
---
## 🔄 **下一步操作**
### **开发模式**
- [ ] 熟悉项目结构和代码组织
- [ ] 了解各个模块的功能和接口
- [ ] 开始开发新的功能模块
- [ ] 编写单元测试和集成测试
### **生产部署**
- [ ] 配置生产环境变量
- [ ] 设置数据库和缓存
- [ ] 配置负载均衡和反向代理
- [ ] 设置监控和告警
### **高级功能**
- [ ] 实现微服务网关功能
- [ ] 集成服务网格技术
- [ ] 添加分布式追踪
- [ ] 优化性能和可靠性
---
## 📚 **相关文档**
- [网关系统概览](./overview.md) - 了解系统架构和特性
- [技术架构详解](./architecture.md) - 深入理解技术实现
- [开发计划](./development-plan.md) - 查看开发路线图
- [API 参考](./api-reference.md) - 完整的 API 文档
---
## 💡 **提示和建议**
1. **开发环境**: 建议使用 VS Code 和相关的 NestJS 插件
2. **版本控制**: 定期提交代码，保持良好的版本管理习惯
3. **测试驱动**: 先写测试，再写代码，确保代码质量
4. **文档更新**: 及时更新文档，保持文档与代码同步
5. **性能优化**: 关注性能指标，持续优化系统性能
---
> **注意**: 如果遇到问题，请查看日志文件或提交 Issue 到项目仓库。

218
admin/docs/src/wwjcloud/guide/concepts.md Normal file
View File

@@ -0,0 +1,218 @@
# 基础概念
::: info 理解 wwjcloud 框架
为了更好地理解和使用 wwjcloud 框架，我们需要了解一些基础概念。
:::
## 核心概念
### 🏗️ 基础架构
wwjcloud 框架基于 NestJS 构建，采用了分层架构设计：
```mermaid
graph TB
A[Controller 控制器层] --> B[Service 服务层]
B --> C[Repository 数据访问层]
C --> D[Database 数据库]
E[BaseEntity] --> F[BaseService]
F --> G[BaseController]
```
### 📦 模块化设计
框架采用模块化设计，每个业务功能都是一个独立的模块：
```
src/
├── core/ # 核心模块
│ ├── base/ # 基础类
│ ├── lang/ # 多语言系统
│ └── utils/ # 工具函数
├── common/ # 业务模块
│ ├── member/ # 会员模块
│ ├── notice/ # 通知模块
│ ├── schedule/ # 定时任务
│ ├── rbac/ # 权限管理
│ └── admin/ # 管理模块
└── config/ # 配置文件
```
## 基础类
### 🔧 BaseEntity
所有实体的基类，提供通用字段和功能：
```typescript
export abstract class BaseEntity {
@Column({ name: 'site_id', type: 'int', default: 0 })
site_id: number;
@Column({ name: 'create_time', type: 'int', default: 0 })
create_time: number;
@Column({ name: 'update_time', type: 'int', default: 0 })
update_time: number;
@Column({ name: 'is_del', type: 'tinyint', default: 0 })
is_del: number;
@Column({ name: 'delete_time', type: 'int', default: 0 })
delete_time: number;
}
```
**特点：**
- **通用字段**：包含所有实体都需要的字段
- **软删除**：统一的软删除机制
- **时间戳**：自动管理创建和更新时间
- **站点隔离**：支持多站点部署
### 🛠️ BaseService
提供通用的 CRUD 操作和业务逻辑：
```typescript
export abstract class BaseService<T> {
constructor(protected readonly repository: Repository<T>) {}
async findAll(): Promise<T[]> {
return this.repository.find({
where: { is_del: 0 } as any
});
}
async findById(id: number): Promise<T | null> {
return this.repository.findOne({
where: { id, is_del: 0 } as any
});
}
async create(data: Partial<T>): Promise<T> {
const entity = this.repository.create(data);
return this.repository.save(entity);
}
}
```
**特点：**
- **通用 CRUD**：提供标准的增删改查操作
- **软删除**：自动处理软删除逻辑
- **查询过滤**：自动过滤已删除的数据
- **错误处理**：统一的错误处理机制
### 🎮 BaseController
提供标准的 API 端点：
```typescript
export abstract class BaseController<T> {
constructor(protected readonly service: BaseService<T>) {}
@Get()
async getList() {
const data = await this.service.findAll();
return {
code: 200,
message: '获取成功',
data
};
}
@Post()
async create(@Body() data: Partial<T>) {
const result = await this.service.create(data);
return {
code: 200,
message: '创建成功',
data: result
};
}
}
```
**特点：**
- **标准端点**：提供 RESTful API 标准端点
- **统一响应**：统一的响应格式
- **参数验证**：自动参数验证
- **错误处理**：统一的错误处理
## 软删除机制
### 🗑️ 双字段策略
wwjcloud 采用双字段软删除策略：
```typescript
// 软删除字段
@Column({ name: 'is_del', type: 'tinyint', default: 0 })
is_del: number; // 0: 正常, 1: 已删除
@Column({ name: 'delete_time', type: 'int', default: 0 })
delete_time: number; // 删除时间戳
```
**优势：**
- **查询效率**：`is_del` 字段便于快速查询
- **时间记录**：`delete_time` 记录删除时间
- **恢复功能**：支持数据恢复
- **兼容性**：与 PHP 框架保持一致
## 多语言系统
### 🌐 动态加载
支持运行时动态加载语言包：
```typescript
// 语言包目录结构
src/
├── common/lang/ # 通用语言包
│ ├── zh-cn/
│ │ ├── common.json
│ │ └── member.json
│ └── en/
│ ├── common.json
│ └── member.json
├── app/lang/ # 应用语言包
└── addons/*/lang/ # 插件语言包
```
## 统一响应格式
### 📊 标准格式
所有 API 响应都遵循统一格式：
```typescript
interface ApiResponse<T = any> {
code: number; // 状态码
message: string; // 消息
data: T; // 数据
timestamp: number; // 时间戳
}
```
## 下一步
::: tip 深入学习
1. **查看架构文档**：了解整体架构设计
2. **阅读 API 规范**：了解接口设计规范
3. **参考开发规范**：遵循开发规范
4. **查看最佳实践**：学习最佳实践
:::
::: warning 注意事项
- 所有实体都应该继承 BaseEntity
- 所有服务都应该继承 BaseService
- 遵循统一的命名规范
- 使用统一的响应格式
:::

230
admin/docs/src/wwjcloud/guide/introduction.md Normal file
View File

@@ -0,0 +1,230 @@
# 框架介绍
::: info 你正在阅读的是 [wwjcloud](https://github.com/vbenjs/vue-vben-admin) 框架文档！
wwjcloud 是一个基于 NestJS 的现代化后端框架，专为 PHP 项目迁移而设计。我们致力于提供一个平滑的迁移路径，让您能够轻松地从 PHP 迁移到现代化的 Node.js 技术栈。
- 如果你只是想体验一下，你可以查看[快速开始](./quick-start.md)。
- 如发现文档有误，欢迎提交 [issue](https://github.com/vbenjs/vue-vben-admin/issues) 帮助我们改进。
:::
## 设计理念
### 🎯 核心目标
- **平滑迁移**：保持与 PHP 框架的数据库一致性和业务逻辑兼容性
- **现代化**：采用最新的 Node.js 技术栈，提供更好的性能和开发体验
- **企业级**：内置多语言、权限管理、软删除等企业级功能
- **开箱即用**：提供完整的开发规范和最佳实践
### 🔄 迁移友好
我们深知从 PHP 迁移到 Node.js 的挑战，因此 wwjcloud 框架在设计时特别考虑了：
- **数据库一致性**：保持与 PHP 框架相同的数据库结构
- **软删除机制**：统一的双字段软删除策略 (`is_del` + `delete_time`)
- **命名规范**：保持与 PHP 框架一致的字段命名和表结构
- **业务逻辑**：核心业务逻辑与 PHP 框架保持一致
## 技术架构
### 🏗️ 整体架构
```mermaid
graph TB
A[前端应用] --> B[API Gateway]
B --> C[wwjcloud 后端]
C --> D[数据库层]
C --> E[缓存层]
C --> F[文件存储]
subgraph "wwjcloud 核心"
G[BaseEntity] --> H[BaseService]
H --> I[BaseController]
J[多语言系统] --> K[权限管理]
L[软删除] --> M[统一响应]
end
C --> G
C --> J
C --> L
```
### 🧩 核心组件
::: grid
```md
### BaseEntity
- 统一的基础实体类
- 包含通用字段 (site_id, create_time, update_time)
- 软删除机制 (is_del, delete_time)
- 时间戳管理
```
```md
### BaseService
- 通用 CRUD 操作
- 软删除处理
- 查询条件构建
- 错误处理
```
```md
### BaseController
- 标准 API 端点
- 统一响应格式
- 参数验证
- 错误处理
```
```md
### 多语言系统
- 动态语言包加载
- 缓存机制
- 模块化语言包
- 支持 common/app/addons
```
:::
## 技术栈
### 🛠️ 核心技术
- **NestJS** - 现代化 Node.js 框架
- **TypeScript** - 强类型 JavaScript
- **TypeORM** - 数据库 ORM
- **MySQL** - 主数据库
- **Redis** - 缓存存储
- **JWT** - 身份认证
### 📦 开发工具
- **ESLint** - 代码规范检查
- **Prettier** - 代码格式化
- **Swagger** - API 文档生成
- **Jest** - 单元测试
- **Docker** - 容器化部署
## 目录结构
```
wwjcloud/
├── src/
│ ├── core/ # 核心模块
│ │ ├── base/ # 基础类
│ │ ├── lang/ # 多语言系统
│ │ └── utils/ # 工具函数
│ ├── common/ # 业务模块
│ │ ├── member/ # 会员模块
│ │ ├── notice/ # 通知模块
│ │ ├── schedule/ # 定时任务
│ │ ├── rbac/ # 权限管理
│ │ └── admin/ # 管理模块
│ ├── config/ # 配置文件
│ ├── vendor/ # 第三方服务
│ └── migrations/ # 数据库迁移
├── test/ # 测试文件
├── docs/ # 文档
└── docker/ # Docker 配置
```
## 核心特性
### 🔐 权限管理
- **RBAC 模型**：基于角色的访问控制
- **动态权限**：支持动态权限配置
- **按钮级权限**：细粒度的权限控制
- **菜单权限**：动态菜单显示
### 🌐 多语言支持
- **动态加载**：支持运行时语言包加载
- **模块化**：按业务模块组织语言包
- **缓存机制**：提高语言包加载性能
- **扩展性**：支持插件语言包
### 🗑️ 软删除机制
- **双字段策略**：`is_del` + `delete_time`
- **统一处理**：BaseService 自动处理软删除
- **查询过滤**：自动过滤已删除数据
- **恢复功能**：支持数据恢复
### 📊 统一响应格式
```typescript
{
code: 200,
message: "操作成功",
data: {},
timestamp: 1640995200
}
```
## 开发规范
### 📝 命名规范
- **数据库字段**：使用下划线命名法 (`snake_case`)
- **TypeScript 属性**：使用下划线命名法 (`snake_case`)
- **方法名**：使用驼峰命名法 (`camelCase`)
- **文件名**：使用帕斯卡命名法 (`PascalCase`)
### 🏗️ 架构规范
- **模块化设计**：按业务功能划分模块
- **依赖注入**：使用 NestJS 的依赖注入
- **接口分离**：遵循接口隔离原则
- **单一职责**：每个类只负责一个功能
### 🔧 代码规范
- **TypeScript**：严格类型检查
- **ESLint**：代码质量检查
- **Prettier**：代码格式化
- **注释规范**：完整的代码注释
## 迁移优势
### 🚀 性能提升
- **异步处理**：Node.js 的异步非阻塞特性
- **内存优化**：更好的内存管理
- **并发处理**：更高的并发处理能力
- **缓存策略**：Redis 缓存提升性能
### 🛠️ 开发效率
- **TypeScript**：强类型支持，减少错误
- **热重载**：开发时自动重载
- **调试工具**：丰富的调试工具
- **生态丰富**：npm 生态丰富
### 🔒 安全性
- **JWT 认证**：无状态的认证机制
- **参数验证**：严格的参数验证
- **SQL 注入防护**：ORM 自动防护
- **XSS 防护**：内置安全防护
## 下一步
::: tip 开始使用
1. **阅读快速开始**：了解如何快速搭建项目
2. **查看基础概念**：理解框架的核心概念
3. **参考 API 文档**：了解可用的 API 接口
4. **查看迁移指南**：了解如何从 PHP 迁移
:::
::: warning 注意事项
- 确保 Node.js 版本 >= 16
- 数据库需要 MySQL 5.7+ 或 8.0+
- 建议使用 Docker 进行部署
- 请遵循开发规范进行开发
:::

184
admin/docs/src/wwjcloud/guide/quick-start.md Normal file
View File

@@ -0,0 +1,184 @@
# 快速开始
::: info 快速上手 wwjcloud 框架
本指南将帮助您快速搭建一个 wwjcloud 项目，并运行第一个 API 接口。
:::
## 环境要求
### 📋 系统要求
- **Node.js** >= 16.0.0
- **MySQL** >= 5.7 或 8.0
- **Redis** >= 6.0 (可选，用于缓存)
- **Git** >= 2.0
### 🔧 开发工具
- **VS Code** (推荐)
- **Postman** 或 **Apifox** (API 测试)
- **MySQL Workbench** (数据库管理)
## 项目初始化
### 1. 克隆项目
```bash
# 克隆项目到本地
git clone <your-repository-url>
cd wwjcloud-nestjs
```
### 2. 安装依赖
```bash
# 安装项目依赖
npm install
```
### 3. 环境配置
复制环境配置文件：
```bash
# 复制环境配置文件
cp .env.example .env
```
编辑 `.env` 文件，配置数据库连接：
```env
# 数据库配置
DB_HOST=localhost
DB_PORT=3306
DB_USERNAME=root
DB_PASSWORD=your_password
DB_DATABASE=wwjcloud
# JWT 配置
JWT_SECRET=your_jwt_secret_key
JWT_EXPIRES_IN=7d
# 应用配置
PORT=3000
NODE_ENV=development
```
### 4. 启动项目
```bash
# 开发模式启动
npm run start:dev
```
项目启动后，访问以下地址：
- **API 文档**：http://localhost:3000/api-docs
- **健康检查**：http://localhost:3000/health
## 第一个 API
### 1. 创建实体
在 `src/common/member/entities/Member.ts` 中：
```typescript
import { Entity, PrimaryGeneratedColumn, Column } from 'typeorm';
import { BaseEntity } from '../../../core/base/BaseEntity';
@Entity('member')
export class Member extends BaseEntity {
@PrimaryGeneratedColumn()
id: number;
@Column({ name: 'username', type: 'varchar', length: 50 })
username: string;
@Column({ name: 'email', type: 'varchar', length: 100 })
email: string;
@Column({ name: 'status', type: 'tinyint', default: 1 })
status: number;
}
```
### 2. 创建服务
在 `src/common/member/services/core/CoreMemberService.ts` 中：
```typescript
import { Injectable } from '@nestjs/common';
import { BaseService } from '../../../../core/base/BaseService';
import { Member } from '../entities/Member';
@Injectable()
export class CoreMemberService extends BaseService<Member> {
constructor() {
super(Member);
}
// 自定义业务方法
async getActiveMembers() {
return this.repository.find({
where: { status: 1, is_del: 0 }
});
}
}
```
### 3. 创建控制器
在 `src/common/member/controllers/api/MemberController.ts` 中：
```typescript
import { Controller, Get, Post, Body, Param } from '@nestjs/common';
import { CoreMemberService } from '../../services/core/CoreMemberService';
import { Member } from '../../entities/Member';
@Controller('api/member')
export class MemberController {
constructor(private readonly memberService: CoreMemberService) {}
@Get()
async getMembers() {
const members = await this.memberService.findAll();
return {
code: 200,
message: '获取成功',
data: members
};
}
@Post()
async createMember(@Body() memberData: Partial<Member>) {
const member = await this.memberService.create(memberData);
return {
code: 200,
message: '创建成功',
data: member
};
}
}
```
## 下一步
::: tip 深入学习
1. **阅读框架介绍**：了解框架的设计理念
2. **查看基础概念**：理解核心概念
3. **参考 API 文档**：了解可用的 API
4. **查看开发规范**：遵循开发规范
:::
::: warning 注意事项
- 确保所有依赖都正确安装
- 检查环境配置是否正确
- 遵循开发规范进行开发
- 定期备份数据库
:::

87
admin/docs/src/wwjcloud/index.md Normal file
View File

@@ -0,0 +1,87 @@
---
# https://vitepress.dev/reference/default-theme-home-page
layout: home
sidebar: false
hero:
name: WWJCloud-Admin
text: 企业级管理系统框架
tagline: 全新升级，开箱即用，简单高效
image:
src: https://t.wanwujie.cn/img/1/2025/08/24/68aad11c8deb7.webp
alt: wwjcloud
actions:
- theme: brand
text: 快速开始 ->
link: /wwjcloud/guide/quick-start
- theme: alt
text: API 文档
link: /wwjcloud/openapi/standards/restful
- theme: alt
text: 在 GitHub 查看
link: https://github.com/vbenjs/vue-vben-admin
- theme: alt
text: Vben Admin
link: /guide/introduction/vben
features:
- icon: 🚀
title: 现代化技术栈
details: 基于 NestJS、TypeScript、TypeORM 等最新技术栈，提供企业级后端解决方案。
link: /wwjcloud/guide/quick-start
linkText: 快速开始
- icon: 🔄
title: Saas+独立版双架构
details: 支持Saas多租户和独立部署两种架构模式，满足不同业务场景需求，提供灵活的部署选择。
link: /wwjcloud/guide/architecture
linkText: 架构说明
- icon: 🏗️
title: 开箱即用，内置模块化功能
details: 采用分层架构设计，已搭建模块化架构系统开发底层，为业务开发提供完整的底层支撑。
link: /wwjcloud/guide/development
linkText: 开发指南
- icon: 🌐
title: 多语言支持
details: 内置多语言系统，支持动态语言包加载，满足国际化需求。
link: /wwjcloud/guide/concepts
linkText: 基础概念
- icon: 🔐
title: 权限管理
details: 内置 RBAC 权限管理方案，支持多种权限控制方式，满足各种权限需求。
link: /wwjcloud/guide/concepts
linkText: 基础概念
- icon: 📱
title: 支持多端管理
details: 基于UniAppX多平台，支持原生App、小程序、PC等多端统一管理和开发，一套代码多端运行。
link: /wwjcloud/guide/multi-platform
linkText: 多端开发
- title: TypeORM
icon:
src: https://unpkg.com/wwjcloud@latest/source/icons/typeorm.svg
details: 强大的 TypeScript ORM，支持多种数据库，提供完整的数据库操作功能。
link: https://typeorm.io/
linkText: 官方站点
- title: 多应用+插件组合安装
icon:
src: https://unpkg.com/wwjcloud@latest/source/icons/mysql.svg
details: 支持业务自定义和应用插件热插拔，提供灵活的应用扩展和插件管理功能。
link: /wwjcloud/guide/plugins
linkText: 插件开发
- title: 自建编译服务
icon:
src: https://unpkg.com/wwjcloud@latest/source/icons/redis.svg
details: 提供完整的编译服务搭建方案，支持自定义编译环境和构建流程，满足不同项目的编译需求。
link: /wwjcloud/guide/build-service
linkText: 编译服务
---
<style>
:root {
--vp-home-hero-image-background-image: linear-gradient(
-45deg,
#78d8d1 50%,
#5f6eed 50%
);
}
</style>

482
admin/docs/src/wwjcloud/openapi/api/adminapi/index.md Normal file
View File

@@ -0,0 +1,482 @@
---
title: 后台 API
description: WWJCloud 后台管理员访问的 API 接口文档
---
# 后台 API
::: info 后台 API 说明
后台 API 是面向系统管理员的接口，提供会员管理、系统配置、权限管理等功能。
:::
## API 基础信息
- **基础路径**: `/adminapi/`
- **认证方式**: JWT Bearer Token
- **内容类型**: `application/json`
- **字符编码**: `UTF-8`
- **权限要求**: 管理员权限
## 模块列表
### 👥 会员管理 (`/adminapi/member/`)
后台会员管理功能：
- **会员列表** - 获取会员列表，支持分页和搜索
- **会员详情** - 查看会员详细信息
- **创建会员** - 后台创建新会员
- **更新会员** - 修改会员信息
- **删除会员** - 删除会员（软删除）
- **批量操作** - 批量删除、状态更新、等级分配
- **积分管理** - 调整会员积分
- **余额管理** - 调整会员余额
### 🔧 管理员管理 (`/adminapi/admin/`)
系统管理员管理功能：
- **管理员列表** - 获取管理员列表
- **创建管理员** - 创建新的管理员账户
- **更新管理员** - 修改管理员信息
- **删除管理员** - 删除管理员账户
- **权限分配** - 为管理员分配权限
- **登录日志** - 查看管理员登录记录
### 🔐 权限管理 (`/adminapi/rbac/`)
基于角色的访问控制：
- **角色管理** - 角色的增删改查
- **权限管理** - 权限的增删改查
- **角色权限** - 为角色分配权限
- **用户角色** - 为用户分配角色
- **权限验证** - 验证用户权限
### ⚙️ 系统管理 (`/adminapi/system/`)
系统配置管理：
- **菜单管理** - 系统菜单配置
- **系统设置** - 系统参数配置
- **数据字典** - 系统数据字典
- **操作日志** - 系统操作日志
- **系统监控** - 系统运行状态
### 📢 通知管理 (`/adminapi/notice/`)
通知消息管理：
- **消息模板** - 消息模板管理
- **推送记录** - 消息推送历史
- **微信通知** - 微信消息推送
- **短信通知** - 短信消息推送
## 认证流程
### 1. 管理员登录
```http
POST /adminapi/admin/login
Content-Type: application/json
{
"username": "admin",
"password": "admin123",
"captcha": "1234"
}
```
**响应示例**:
```json
{
"code": 200,
"message": "登录成功",
"data": {
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"expires_in": 7200,
"admin_info": {
"admin_id": 1,
"username": "admin",
"nickname": "超级管理员",
"role": "super_admin",
"permissions": ["member:list", "member:create", "member:update", "member:delete"]
}
}
}
```
### 2. 获取会员列表
```http
GET /adminapi/member?page=1&limit=10&keyword=test&status=1
Authorization: Bearer <your-jwt-token>
```
**响应示例**:
```json
{
"code": 200,
"message": "获取成功",
"data": {
"list": [
{
"member_id": 1001,
"username": "user@example.com",
"nickname": "用户昵称",
"phone": "13800138000",
"email": "user@example.com",
"status": 1,
"points": 1000,
"balance": 99.99,
"level": {
"level_id": 1,
"level_name": "普通会员"
},
"create_time": 1640995200,
"last_login_time": 1640995200
}
],
"total": 100,
"page": 1,
"limit": 10,
"pages": 10
}
}
```
### 3. 创建会员
```http
POST /adminapi/member
Authorization: Bearer <your-jwt-token>
Content-Type: application/json
{
"username": "newuser@example.com",
"password": "password123",
"nickname": "新用户",
"phone": "13800138001",
"email": "newuser@example.com",
"level_id": 1
}
```
**响应示例**:
```json
{
"code": 201,
"message": "创建成功",
"data": {
"member_id": 1002,
"username": "newuser@example.com",
"nickname": "新用户",
"create_time": 1640995200
}
}
```
## 权限控制
### 权限验证
所有后台 API 都需要验证管理员权限：
```typescript
// 权限装饰器示例
@Roles('admin', 'super_admin')
@UseGuards(JwtAuthGuard, RolesGuard)
@Controller('adminapi/member')
export class MemberController {
// ...
}
```
### 权限级别
| 权限级别 | 说明 | 示例 |
|----------|------|------|
| super_admin | 超级管理员 | 所有权限 |
| admin | 普通管理员 | 部分管理权限 |
| operator | 操作员 | 只读权限 |
### 权限检查
```javascript
// 前端权限检查示例
const checkPermission = (permission) => {
const userPermissions = getUserPermissions();
return userPermissions.includes(permission);
};
// 使用示例
if (checkPermission('member:create')) {
// 显示创建按钮
}
```
## 查询参数
### 通用查询参数
所有列表接口支持以下查询参数：
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| page | number | 否 | 页码，默认 1 |
| limit | number | 否 | 每页数量，默认 10，最大 100 |
| keyword | string | 否 | 关键词搜索 |
| status | number | 否 | 状态筛选 |
| start_time | number | 否 | 开始时间（时间戳） |
| end_time | number | 否 | 结束时间（时间戳） |
| sort | string | 否 | 排序字段 |
| order | string | 否 | 排序方向，asc/desc |
### 高级查询
支持复杂的查询条件：
```http
GET /adminapi/member?page=1&limit=20&keyword=test&status=1&level_id=2&start_time=1640995200&end_time=1641081600&sort=create_time&order=desc
```
## 批量操作
### 批量删除
```http
POST /adminapi/member/batch-delete
Authorization: Bearer <your-jwt-token>
Content-Type: application/json
{
"member_ids": [1001, 1002, 1003]
}
```
### 批量更新状态
```http
POST /adminapi/member/batch-update-status
Authorization: Bearer <your-jwt-token>
Content-Type: application/json
{
"member_ids": [1001, 1002, 1003],
"status": 0
}
```
### 批量分配等级
```http
POST /adminapi/member/batch-assign-level
Authorization: Bearer <your-jwt-token>
Content-Type: application/json
{
"member_ids": [1001, 1002, 1003],
"level_id": 2
}
```
## 数据导出
### 导出会员列表
```http
GET /adminapi/member/export?format=excel&keyword=test&status=1
Authorization: Bearer <your-jwt-token>
```
**支持格式**:
- Excel (.xlsx)
- CSV (.csv)
- PDF (.pdf)
## 错误处理
### 权限错误
```json
{
"code": 403,
"message": "权限不足",
"data": {
"required_permission": "member:delete",
"current_permissions": ["member:list", "member:view"]
}
}
```
### 参数验证错误
```json
{
"code": 400,
"message": "参数验证失败",
"data": {
"errors": [
{
"field": "username",
"message": "用户名已存在"
},
{
"field": "password",
"message": "密码长度不能少于6位"
}
]
}
}
```
## 操作日志
所有后台操作都会记录操作日志：
```json
{
"log_id": 1001,
"admin_id": 1,
"action": "member:create",
"target": "member",
"target_id": 1002,
"description": "创建会员：newuser@example.com",
"ip": "192.168.1.100",
"user_agent": "Mozilla/5.0...",
"create_time": 1640995200
}
```
## 开发建议
### 1. 权限管理
```javascript
// 权限管理工具函数
const PermissionManager = {
// 检查是否有权限
hasPermission(permission) {
const permissions = this.getUserPermissions();
return permissions.includes(permission);
},
// 检查是否有任意一个权限
hasAnyPermission(permissions) {
const userPermissions = this.getUserPermissions();
return permissions.some(p => userPermissions.includes(p));
},
// 检查是否有所有权限
hasAllPermissions(permissions) {
const userPermissions = this.getUserPermissions();
return permissions.every(p => userPermissions.includes(p));
}
};
```
### 2. 请求封装
```javascript
// API 请求封装
const adminApi = {
// 获取会员列表
async getMemberList(params) {
return await request.get('/adminapi/member', { params });
},
// 创建会员
async createMember(data) {
return await request.post('/adminapi/member', data);
},
// 更新会员
async updateMember(id, data) {
return await request.put(`/adminapi/member/${id}`, data);
},
// 删除会员
async deleteMember(id) {
return await request.delete(`/adminapi/member/${id}`);
},
// 批量操作
async batchOperation(action, data) {
return await request.post(`/adminapi/member/batch-${action}`, data);
}
};
```
### 3. 错误处理
```javascript
// 统一错误处理
const handleApiError = (error) => {
if (error.response) {
const { status, data } = error.response;
switch (status) {
case 401:
// Token 过期，跳转登录
router.push('/login');
break;
case 403:
// 权限不足
ElMessage.error('权限不足');
break;
case 429:
// 请求过于频繁
ElMessage.error('请求过于频繁，请稍后再试');
break;
default:
ElMessage.error(data.message || '请求失败');
}
}
};
```
## 测试工具
### Swagger UI
访问 `http://localhost:3000/api/admin` 查看完整的后台 API 文档和在线测试功能。
### Postman 集合
可以导入以下 Postman 集合进行测试：
```json
{
"info": {
"name": "WWJCloud 后台 API",
"description": "后台管理 API 接口集合"
},
"item": [
{
"name": "会员管理",
"item": [
{
"name": "获取会员列表",
"request": {
"method": "GET",
"url": "{{base_url}}/adminapi/member"
}
},
{
"name": "创建会员",
"request": {
"method": "POST",
"url": "{{base_url}}/adminapi/member"
}
}
]
}
]
}
```

94
admin/docs/src/wwjcloud/openapi/api/frontend/index.md Normal file
View File

@@ -0,0 +1,94 @@
---
title: 前台 API
description: 前台用户访问的 API 接口
---
# 前台 API
::: info 前台 API 说明
前台用户访问的 API 接口，提供用户注册、登录、个人资料管理等功能。
:::
## API 基础信息
- **基础路径**: `/api/`
- **认证方式**: JWT Bearer Token
- **内容类型**: `application/json`
- **字符编码**: `UTF-8`
## 模块列表
::: tip 自动生成
此文档由后端 Swagger 自动生成，包含最新的 API 接口信息。
:::
## 认证流程
### 获取 Token
```http
POST /api/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
访问后端 Swagger UI 查看完整的 API 文档和在线测试功能。
### 在线测试
每个 API 分组都提供 Swagger UI 界面，支持：
- API 文档查看
- 在线测试
- 参数验证
- 响应示例

184
admin/docs/src/wwjcloud/openapi/api/index.md Normal file
View File

@@ -0,0 +1,184 @@
---
title: API 总览
description: WWJCloud 框架 API 接口总览
---
# API 总览
::: info API 文档说明
WWJCloud 框架提供完整的 RESTful API 接口，支持前台用户访问和后台管理功能。
:::
## API 分类
### 🎯 前台 API (`/api/`)
前台用户访问的 API 接口，提供用户端功能：
- **会员管理** - 用户注册、登录、个人资料管理
- **认证授权** - JWT 认证、权限验证
- **业务功能** - 各种业务模块的前台接口
### 🔧 后台 API (`/adminapi/`)
后台管理员访问的 API 接口，提供管理功能：
- **会员管理** - 会员列表、详情、状态管理
- **管理员管理** - 管理员账户、权限管理
- **系统管理** - 系统配置、菜单管理、权限管理
## API 访问地址
### 开发环境
```bash
# 前台 API 文档
http://localhost:3000/api/frontend
# 后台 API 文档
http://localhost:3000/api/admin
# 统一 API 文档
http://localhost:3000/api
```
### 生产环境
```bash
# 前台 API 文档
https://your-domain.com/api/frontend
# 后台 API 文档
https://your-domain.com/api/admin
# 统一 API 文档
https://your-domain.com/api
```
## 认证方式
### JWT 认证
所有需要认证的 API 都使用 JWT Token：
```http
Authorization: Bearer <your-jwt-token>
```
### 获取 Token
#### 前台用户登录
```http
POST /api/member/login
Content-Type: application/json
{
"username": "user@example.com",
"password": "password123"
}
```
#### 后台管理员登录
```http
POST /adminapi/admin/login
Content-Type: application/json
{
"username": "admin",
"password": "admin123"
}
```
## 响应格式
所有 API 都遵循统一的响应格式：
```json
{
"code": 200,
"message": "success",
"data": {
// 具体数据
}
}
```
## 错误处理
API 错误响应格式：
```json
{
"code": 400,
"message": "参数错误",
"data": null
}
```
## 分页查询
支持分页的 API 使用统一的查询参数：
```http
GET /api/member?page=1&limit=10&sort=create_time&order=desc
```
## 状态码说明
| 状态码 | 说明 |
|--------|------|
| 200 | 请求成功 |
| 201 | 创建成功 |
| 400 | 请求参数错误 |
| 401 | 未授权 |
| 403 | 禁止访问 |
| 404 | 资源不存在 |
| 500 | 服务器内部错误 |
## 开发工具
### Swagger UI
每个 API 分组都提供 Swagger UI 界面，支持：
- API 文档查看
- 在线测试
- 参数验证
- 响应示例
### Postman 集合
可以导入 Postman 集合进行 API 测试：
```bash
# 导出 Swagger JSON
curl http://localhost:3000/api-json > api.json
```
## 版本控制
当前 API 版本：`v1.0.0`
版本控制策略：
- 向后兼容的更新：小版本号递增
- 破坏性更新：大版本号递增
- 通过 URL 路径进行版本控制：`/api/v1/`
## 限流策略
API 访问限流规则：
- **前台 API**：1000 次/小时/用户
- **后台 API**：5000 次/小时/管理员
- **登录接口**：10 次/分钟/IP
## 监控和日志
- **访问日志**：记录所有 API 访问
- **错误日志**：记录 API 错误信息
- **性能监控**：API 响应时间监控
- **使用统计**：API 调用频率统计

242
admin/docs/src/wwjcloud/openapi/standards/error-codes.md Normal file
View File

@@ -0,0 +1,242 @@
# 错误码规范
::: info 错误码定义
本文档定义了 wwjcloud 框架的错误码规范，确保错误处理的一致性和可维护性。
:::
## 错误码分类
### 📋 错误码结构
错误码采用分层设计，便于分类和管理：
```typescript
interface ErrorCode {
code: number; // 错误码
message: string; // 错误消息
category: string; // 错误分类
}
```
### 🎯 错误码范围
- **1000-1999**：用户相关错误
- **2000-2999**：权限相关错误
- **3000-3999**：数据相关错误
- **4000-4999**：业务相关错误
- **5000-5999**：系统相关错误
## HTTP 状态码
### ✅ 成功状态码
```typescript
200: 'OK' // 请求成功
201: 'Created' // 资源创建成功
204: 'No Content' // 请求成功，无返回内容
```
### ❌ 客户端错误
```typescript
400: 'Bad Request' // 请求参数错误
401: 'Unauthorized' // 未授权访问
403: 'Forbidden' // 禁止访问
404: 'Not Found' // 资源不存在
409: 'Conflict' // 资源冲突
422: 'Unprocessable Entity' // 请求格式正确但语义错误
```
### 🔧 服务器错误
```typescript
500: 'Internal Server Error' // 服务器内部错误
502: 'Bad Gateway' // 网关错误
503: 'Service Unavailable' // 服务不可用
```
## 业务错误码
### 👤 用户相关错误 (1000-1999)
```typescript
// 用户认证
1001: '用户不存在'
1002: '用户名或密码错误'
1003: '用户已被禁用'
// 用户信息
1010: '用户名已存在'
1011: '邮箱已存在'
1012: '用户名格式不正确'
1013: '邮箱格式不正确'
```
### 🔐 权限相关错误 (2000-2999)
```typescript
// 权限验证
2001: '权限不足'
2002: '角色不存在'
2003: 'Token 无效'
2004: 'Token 已过期'
// 角色管理
2010: '角色名已存在'
2011: '角色已被使用'
```
### 💾 数据相关错误 (3000-3999)
```typescript
// 数据操作
3001: '数据不存在'
3002: '数据已存在'
3003: '数据状态错误'
// 数据库操作
3010: '数据库连接失败'
3011: '数据库查询失败'
```
### 🏢 业务相关错误 (4000-4999)
```typescript
// 会员管理
4001: '会员不存在'
4002: '会员状态错误'
4003: '会员等级不存在'
// 订单管理
4010: '订单不存在'
4011: '订单状态错误'
```
## 错误响应格式
### 📊 标准错误响应
```typescript
interface ErrorResponse {
code: number; // 错误码
message: string; // 错误消息
data: {
error_code: number; // 业务错误码
error_message: string; // 业务错误消息
};
timestamp: number; // 时间戳
}
```
### 📝 错误响应示例
**参数验证错误：**
```json
{
"code": 400,
"message": "请求参数错误",
"data": {
"error_code": 1013,
"error_message": "用户名格式不正确"
},
"timestamp": 1640995200
}
```
**权限不足错误：**
```json
{
"code": 403,
"message": "禁止访问",
"data": {
"error_code": 2001,
"error_message": "权限不足"
},
"timestamp": 1640995200
}
```
## 错误处理实现
### 🔧 业务异常类
```typescript
export class BusinessException extends HttpException {
constructor(
private readonly errorCode: number,
private readonly errorMessage: string,
status: number = 400
) {
super(errorMessage, status);
}
getErrorCode(): number {
return this.errorCode;
}
getErrorMessage(): string {
return this.errorMessage;
}
}
```
### 📝 使用示例
```typescript
@Controller('api/members')
export class MemberController {
@Post()
async createMember(@Body() memberData: CreateMemberDto) {
// 检查用户名是否存在
const existingMember = await this.memberService.findByUsername(memberData.username);
if (existingMember) {
throw new BusinessException(1010, '用户名已存在');
}
// 创建会员
const member = await this.memberService.create(memberData);
return {
code: 200,
message: '创建成功',
data: member,
timestamp: Math.floor(Date.now() / 1000)
};
}
}
```
## 最佳实践
### ✅ 推荐做法
1. **统一错误码**：使用统一的错误码规范
2. **详细错误信息**：提供详细的错误信息
3. **错误分类**：按功能模块分类错误码
4. **错误日志**：记录错误日志便于排查
### ❌ 避免做法
1. **不要暴露敏感信息**：错误信息不要包含敏感数据
2. **不要返回不一致的格式**：保持错误响应格式一致
3. **不要忽略错误处理**：所有错误都要有相应的处理
## 下一步
::: tip 深入学习
1. **查看响应格式规范**：了解统一的响应格式
2. **阅读 API 设计规范**：了解 API 设计原则
3. **参考开发规范**：遵循开发规范
:::
::: warning 注意事项
- 严格遵循错误码规范
- 提供详细的错误信息
- 实现统一的错误处理
- 记录错误日志便于排查
:::

223
admin/docs/src/wwjcloud/openapi/standards/response.md Normal file
View File

@@ -0,0 +1,223 @@
# 响应格式规范
::: info 统一响应格式
本文档定义了 wwjcloud 框架的统一响应格式，确保所有 API 返回的数据格式一致。
:::
## 响应结构
### 📊 基础响应格式
所有 API 响应都遵循以下统一格式：
```typescript
interface ApiResponse<T = any> {
code: number; // 状态码
message: string; // 消息
data: T; // 数据
timestamp: number; // 时间戳
}
```
## 响应类型
### ✅ 成功响应
**基础成功响应：**
```json
{
"code": 200,
"message": "操作成功",
"data": null,
"timestamp": 1640995200
}
```
**返回单个对象：**
```json
{
"code": 200,
"message": "获取成功",
"data": {
"id": 123,
"username": "john_doe",
"email": "john@example.com",
"status": 1
},
"timestamp": 1640995200
}
```
**返回列表数据：**
```json
{
"code": 200,
"message": "获取成功",
"data": {
"list": [
{
"id": 123,
"username": "john_doe",
"email": "john@example.com"
}
],
"total": 100,
"page": 1,
"size": 10
},
"timestamp": 1640995200
}
```
### ❌ 错误响应
**参数错误：**
```json
{
"code": 400,
"message": "请求参数错误",
"data": null,
"timestamp": 1640995200
}
```
**未授权访问：**
```json
{
"code": 401,
"message": "未授权访问",
"data": null,
"timestamp": 1640995200
}
```
**资源不存在：**
```json
{
"code": 404,
"message": "资源不存在",
"data": null,
"timestamp": 1640995200
}
```
## 状态码规范
### 📋 状态码定义
**成功状态码：**
```typescript
200: '操作成功'
201: '创建成功'
204: '删除成功'
```
**客户端错误：**
```typescript
400: '请求参数错误'
401: '未授权访问'
403: '禁止访问'
404: '资源不存在'
409: '资源冲突'
422: '请求格式正确但语义错误'
```
**服务器错误：**
```typescript
500: '服务器内部错误'
502: '网关错误'
503: '服务不可用'
```
## 分页响应
### 📄 分页格式
**标准分页响应：**
```json
{
"code": 200,
"message": "获取成功",
"data": {
"list": [
{
"id": 123,
"username": "john_doe",
"email": "john@example.com"
}
],
"total": 100,
"page": 1,
"size": 10,
"pages": 10
},
"timestamp": 1640995200
}
```
## 实现示例
### 🔧 Controller 实现
```typescript
@Controller('api/members')
export class MemberController {
constructor(private readonly memberService: MemberService) {}
@Get()
async getMembers(@Query() query: GetMembersDto) {
try {
const result = await this.memberService.findAll(query);
return {
code: 200,
message: '获取成功',
data: result,
timestamp: Math.floor(Date.now() / 1000)
};
} catch (error) {
return {
code: 500,
message: '获取失败',
data: null,
timestamp: Math.floor(Date.now() / 1000)
};
}
}
}
```
## 最佳实践
### ✅ 推荐做法
1. **统一格式**：所有 API 都使用统一的响应格式
2. **状态码规范**：使用标准的 HTTP 状态码
3. **错误处理**：提供详细的错误信息
4. **分页支持**：列表接口支持分页
5. **时间戳**：包含响应时间戳
### ❌ 避免做法
1. **不要暴露敏感信息**：错误信息不要包含敏感数据
2. **不要返回不一致的格式**：保持响应格式一致
3. **不要忽略错误处理**：所有错误都要有相应的响应
## 下一步
::: tip 深入学习
1. **查看错误码规范**：了解错误码定义
2. **阅读 API 设计规范**：了解 API 设计原则
3. **参考开发规范**：遵循开发规范
:::
::: warning 注意事项
- 严格遵循统一的响应格式
- 提供详细的错误信息
- 实现适当的错误处理
:::

505
admin/docs/src/wwjcloud/openapi/standards/restful.md Normal file
View File

@@ -0,0 +1,505 @@
# RESTful API 设计规范
::: info API 设计规范
本文档定义了 wwjcloud 框架的 RESTful API 设计规范，确保 API 的一致性、可读性和可维护性。
:::
## 基本原则
### 🎯 设计原则
- **资源导向**：API 应该围绕资源进行设计
- **无状态**：每个请求都应该包含完整的信息
- **统一接口**：使用标准的 HTTP 方法
- **可缓存**：支持缓存机制
- **分层系统**：支持分层架构
### 📝 命名规范
- **URL 使用小写字母**：`/api/member/list`
- **单词间使用连字符**：`/api/user-profile`
- **避免使用下划线**：不推荐 `/api/user_profile`
- **使用复数形式**：`/api/members` 而不是 `/api/member`
## HTTP 方法
### 🔍 GET - 获取资源
**用途：** 获取资源列表或单个资源
```http
# 获取资源列表
GET /api/members
# 获取单个资源
GET /api/members/123
# 获取资源的子资源
GET /api/members/123/orders
# 查询参数
GET /api/members?page=1&size=10&status=active
```
**响应示例：**
```json
{
"code": 200,
"message": "获取成功",
"data": {
"list": [...],
"total": 100,
"page": 1,
"size": 10
},
"timestamp": 1640995200
}
```
### ➕ POST - 创建资源
**用途：** 创建新资源
```http
# 创建资源
POST /api/members
# 请求体
{
"username": "john_doe",
"email": "john@example.com",
"status": 1
}
```
**响应示例：**
```json
{
"code": 200,
"message": "创建成功",
"data": {
"id": 123,
"username": "john_doe",
"email": "john@example.com",
"status": 1,
"create_time": 1640995200
},
"timestamp": 1640995200
}
```
### ✏️ PUT - 更新资源
**用途：** 完整更新资源
```http
# 更新资源
PUT /api/members/123
# 请求体
{
"username": "john_doe_updated",
"email": "john_updated@example.com",
"status": 1
}
```
**响应示例：**
```json
{
"code": 200,
"message": "更新成功",
"data": {
"id": 123,
"username": "john_doe_updated",
"email": "john_updated@example.com",
"status": 1,
"update_time": 1640995200
},
"timestamp": 1640995200
}
```
### 🔄 PATCH - 部分更新
**用途：** 部分更新资源
```http
# 部分更新资源
PATCH /api/members/123
# 请求体
{
"status": 0
}
```
**响应示例：**
```json
{
"code": 200,
"message": "更新成功",
"data": {
"id": 123,
"status": 0,
"update_time": 1640995200
},
"timestamp": 1640995200
}
```
### 🗑️ DELETE - 删除资源
**用途：** 删除资源
```http
# 删除资源
DELETE /api/members/123
# 批量删除
DELETE /api/members?ids=123,124,125
```
**响应示例：**
```json
{
"code": 200,
"message": "删除成功",
"data": null,
"timestamp": 1640995200
}
```
## URL 设计
### 📋 资源命名
**使用名词而非动词：**
```http
# ✅ 正确
GET /api/members
POST /api/members
PUT /api/members/123
DELETE /api/members/123
# ❌ 错误
GET /api/getMembers
POST /api/createMember
PUT /api/updateMember
DELETE /api/deleteMember
```
### 🔗 嵌套资源
**表示资源间的关系：**
```http
# 获取用户的订单
GET /api/members/123/orders
# 获取用户的特定订单
GET /api/members/123/orders/456
# 为用户创建订单
POST /api/members/123/orders
```
### 🔍 查询参数
**用于过滤、排序、分页：**
```http
# 过滤
GET /api/members?status=active&type=vip
# 排序
GET /api/members?sort=create_time&order=desc
# 分页
GET /api/members?page=1&size=10
# 搜索
GET /api/members?keyword=john
# 组合使用
GET /api/members?status=active&page=1&size=10&sort=create_time&order=desc
```
## 状态码规范
### ✅ 成功状态码
```http
200 OK # 请求成功
201 Created # 资源创建成功
204 No Content # 请求成功，无返回内容
```
### ❌ 客户端错误
```http
400 Bad Request # 请求参数错误
401 Unauthorized # 未授权访问
403 Forbidden # 禁止访问
404 Not Found # 资源不存在
405 Method Not Allowed # 方法不允许
409 Conflict # 资源冲突
422 Unprocessable Entity # 请求格式正确但语义错误
```
### 🔧 服务器错误
```http
500 Internal Server Error # 服务器内部错误
502 Bad Gateway # 网关错误
503 Service Unavailable # 服务不可用
```
## 请求头规范
### 📋 常用请求头
```http
# 内容类型
Content-Type: application/json
# 授权信息
Authorization: Bearer <token>
# 接受的内容类型
Accept: application/json
# 用户代理
User-Agent: wwjcloud-client/1.0.0
# 语言设置
Accept-Language: zh-CN,zh;q=0.9,en;q=0.8
```
### 🔐 认证头
```http
# JWT Token
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
# API Key
X-API-Key: your-api-key
# 自定义认证
X-Auth-Token: your-auth-token
```
## 响应格式
### 📊 统一响应结构
```typescript
interface ApiResponse<T = any> {
code: number; // 状态码
message: string; // 消息
data: T; // 数据
timestamp: number; // 时间戳
}
```
### 📝 响应示例
**成功响应：**
```json
{
"code": 200,
"message": "操作成功",
"data": {
"id": 123,
"username": "john_doe",
"email": "john@example.com"
},
"timestamp": 1640995200
}
```
**错误响应：**
```json
{
"code": 400,
"message": "请求参数错误",
"data": null,
"timestamp": 1640995200
}
```
**列表响应：**
```json
{
"code": 200,
"message": "获取成功",
"data": {
"list": [
{
"id": 123,
"username": "john_doe",
"email": "john@example.com"
}
],
"total": 100,
"page": 1,
"size": 10
},
"timestamp": 1640995200
}
```
## 版本控制
### 🔢 版本策略
**URL 版本控制：**
```http
# 版本 1
GET /api/v1/members
# 版本 2
GET /api/v2/members
```
**请求头版本控制：**
```http
GET /api/members
Accept: application/vnd.wwjcloud.v1+json
```
### 📋 版本命名
- **主版本**：重大变更，不兼容
- **次版本**：新功能，向后兼容
- **修订版本**：Bug 修复，向后兼容
## 错误处理
### 🚨 错误响应格式
```json
{
"code": 400,
"message": "请求参数错误",
"data": {
"errors": [
{
"field": "email",
"message": "邮箱格式不正确"
},
{
"field": "username",
"message": "用户名不能为空"
}
]
},
"timestamp": 1640995200
}
```
### 📝 错误码规范
**业务错误码：**
```typescript
// 成功
200: '操作成功'
201: '创建成功'
// 客户端错误
400: '请求参数错误'
401: '未授权访问'
403: '禁止访问'
404: '资源不存在'
409: '资源冲突'
// 服务器错误
500: '服务器内部错误'
502: '网关错误'
503: '服务不可用'
```
## 最佳实践
### ✅ 推荐做法
1. **使用 HTTPS**：所有 API 都应该使用 HTTPS
2. **参数验证**：严格验证所有输入参数
3. **错误处理**：提供详细的错误信息
4. **文档化**：提供完整的 API 文档
5. **版本控制**：使用版本控制管理 API 变更
6. **限流控制**：实现 API 限流机制
7. **监控日志**：记录 API 调用日志
### ❌ 避免做法
1. **不要使用动词**：URL 应该使用名词
2. **不要暴露内部错误**：不要返回敏感的错误信息
3. **不要过度设计**：保持 API 简单易用
4. **不要忽略缓存**：合理使用缓存机制
5. **不要忽略安全**：实现适当的安全措施
## 示例
### 📋 完整的 API 示例
**会员管理 API：**
```http
# 获取会员列表
GET /api/v1/members?page=1&size=10&status=active
# 获取单个会员
GET /api/v1/members/123
# 创建会员
POST /api/v1/members
Content-Type: application/json
Authorization: Bearer <token>
{
"username": "john_doe",
"email": "john@example.com",
"status": 1
}
# 更新会员
PUT /api/v1/members/123
Content-Type: application/json
Authorization: Bearer <token>
{
"username": "john_doe_updated",
"email": "john_updated@example.com",
"status": 1
}
# 删除会员
DELETE /api/v1/members/123
Authorization: Bearer <token>
```
## 下一步
::: tip 深入学习
1. **查看响应格式规范**：了解统一的响应格式
2. **阅读错误码规范**：了解错误码定义
3. **参考开发规范**：遵循开发规范
4. **查看最佳实践**：学习最佳实践
:::
::: warning 注意事项
- 严格遵循 RESTful 设计原则
- 保持 API 的一致性和可读性
- 提供完整的错误处理
- 实现适当的安全措施
:::

68
admin/docs/src/wwjcloud/progress.md Normal file
View File

@@ -0,0 +1,68 @@
# 开发进度（按日期 & 里程碑）
> 说明：本页用于统筹底座与业务改造的实际进度，按日期记录，按里程碑（M1–M6）分栏。与 `ai/planner.md` 的目标与验收标准对应，便于管理与追踪。
## 时间轴（Timeline）
| 日期 | 模块/范围 | 主要事项 | 关联里程碑 | 状态 |
|---|---|---|---|---|
| 2025-08-26 | Core 基座 | 统一异常响应、统一成功响应、配置校验方案落地（Joi） | M1 | 已完成 |
| 2025-08-26 | Database | 事务封装（TransactionManager）、BaseRepository 分页/过滤、Redis 分布式锁 | M2 | 已完成 |
| 2025-08-26 | Security | `SiteScopeGuard` 多租隔离、`IdempotencyService`、`RateLimitService`、`AuditService` | M3 | 已完成 |
| 2025-08-26 | Events/Queues | 事件契约（AJV）、发布助手、订阅装饰器、事件总线模式配置（Outbox/Kafka） | M4 | 已完成 |
| 2025-08-26 | Observability | 健康聚合器与指示器（DB/Redis/事件/队列/存储）、HTTP 指标、/health /metrics 控制器 | M5 | 已完成 |
| 2025-08-26 | Vendor/Storage | `StorageAdapter` 标准、Local 实现、`StorageRegistry`（siteId 解析：站点启用>平台默认>local）、`STORAGE_ADAPTER_FACTORY` Provider | M6 | 已完成 |
| 2025-08-26 | Upload | 服务重构完成，使用 `STORAGE_ADAPTER_FACTORY`，修复所有编译错误 | M6（落地示例） | 已完成 |
> 说明：状态枚举建议采用：已完成 / 进行中 / 待开始 / 阻塞。
## 里程碑视图（M1–M6）
### M1 基础通信与契约
- [x] 全局异常过滤：`core/http/filters/http-exception.filter.ts`
- [x] 统一成功响应拦截：`core/http/interceptors/response.interceptor.ts`
- [x] 配置校验（Joi）：`config/schema/validation.ts`
- [x] 应用装配：在 `app.module.ts` 全局注册 `APP_FILTER` 与 `APP_INTERCEPTOR`
### M2 事务与数据访问
- [x] 事务封装：`core/database/transaction.manager.ts`
- [x] BaseRepository：`core/database/base-repository.ts`（分页/排序/过滤白名单）
- [x] Redis 分布式锁：`core/database/redis-lock.service.ts`
### M3 安全与多租
- [x] 多租站点隔离：`core/security/site-scope.guard.ts`
- [x] 幂等：`core/security/idempotency.service.ts`
- [x] 限流：`core/security/rate-limit.service.ts`
- [x] 审计：`core/audit/audit.service.ts`
### M4 事件与队列
- [x] 事件契约与校验：`core/event-bus/contract.validator.ts`、`core/event-bus/contracts/*`
- [x] 发布助手：`core/event-bus/publish.helper.ts`
- [x] 订阅装饰器：`core/event-bus/subscribe.decorator.ts`
- [x] 事件总线配置：`config/eventbus.config.ts`
### M5 可观测与稳定性
- [x] 健康聚合器：`core/observability/health/health-aggregator.ts`
- [x] 健康指示器：DB/Redis/EventBus/Queue/Storage
- [x] 健康控制器：`core/observability/health/health.controller.ts`
- [x] HTTP 指标：`core/observability/metrics/http-metrics.service.ts`、`core/observability/metrics/metrics.controller.ts`
### M6 Vendor 外设标准（Storage）
- [x] 接口：`vendor/storage/interfaces/storage-adapter.ts`
- [x] 适配器：`vendor/storage/adapters/local.adapter.ts`
- [x] Token：`vendor/storage/tokens.ts`
- [x] 工厂/注册表：`vendor/storage/providers/registry.ts`、`vendor/storage/providers/storage.provider.ts`
- [x] 健康检查联动：`core/observability/health/indicators/storage.indicator.ts`
- [x] 示例接线（upload）：`common/upload/upload.service.ts`
## 下一步计划
- [x] 在 `app.module.ts` 中注册：
- [x] 全局异常过滤器（`APP_FILTER` -> `HttpExceptionFilter`）
- [x] 统一响应拦截器（`APP_INTERCEPTOR` -> `ResponseInterceptor`）
- [x] 确认 `/health` 与 `/metrics` 控制器装配
- [ ] `settings/storage` 平台端与站点端 API 最小可用实现与测试
- [ ] `upload` 成功入库 `sys_attachment`（实体+仓储+用例），并发布事件/入队任务（缩略图等）
## 附：参考
- 架构概览：`structure/overview.md`
- 规范/流程/对齐：`ai/index.md`、`ai/workflow.md`、`ai/checklists.md`、`ai/mapping.md`、`ai/integration.md`、`ai/planner.md`

73
admin/docs/src/wwjcloud/project/ai-prompts-and-constraints.md Normal file
View File

@@ -0,0 +1,73 @@
---
title: AI 提示词与执行约束（WWJCloud）
description: 统一的 AI 协作提示词、上下文提供清单与强制约束，确保回答可执行、改动可控、与架构规划一致。
---
# AI 提示词与执行约束（WWJCloud）
## 目标
- 回答必须“可执行、可核验、最小改动、可回滚”。
- 严格遵守本项目的领域边界、数据一致性与微服务演进路线。
## 提供上下文（调用 AI 前的必备信息）
- 任务目的与期望产出（代码/文档/脚本/命令）。
- 影响范围（目录/模块/表/接口）。
- 相关文件片段（尽量给出路径与行号）。
- 现状与约束（运行环境、端口、依赖版本、是否允许新依赖）。
- 回滚策略（如仅限编辑文档、不许改表结构、不改公开 API）。
## 强制约束（回答/改动必须遵守）
- 架构与边界
- 禁跨域直查数据库；跨域仅通过“域 SDK 接口/领域事件”。
- 保持统一 Swagger（/docs、/docs-json），文档站按前缀（/api、/adminapi）分组。
- 事件/任务：事件走 Kafka（或 Outbox→Kafka），任务走 Redis（或 Outbox→Worker），允许现阶段沿用 DB jobs 作为 Outbox。
- 数据与迁移
- 不重命名/拆分现有表；优先加索引与新增伴随表（如 Outbox）。
- 新增字段/索引需说明兼容性与回滚方式。
- 安全与网关
- 网关二选一（Traefik/Kong）作为北向入口；东西向留给服务网格（Envoy/Istio）。
- 默认开启 JWT 校验、限流、超时/重试、熔断（如可用）。
- 可观测
- 保留 traceId、site_id；核心链路加指标与追踪埋点。
- 代码与风格
- 避免破坏性重构；提交“最小可行改动”。
- 保留原缩进与格式；新增代码遵循项目风格与命名规范。
## 代码与文档编辑规范
- 代码
- 仅在必要文件做“最小范围编辑”；注释解释“为什么改”。
- 新接口/事件需提供类型、示例载荷与兼容策略。
- 新依赖需标注用途、体量与替代方案，默认不引入重量依赖。
- 文档
- 路径引用保持现有规则：`/wwjcloud/...`；侧边栏改动需同步 `zh.mts`。
- 新文档放置目录：`admin/docs/src/wwjcloud/project/`。
## 决策检查清单（回答前自检）
- 该改动是否违反“禁跨域直查库”？
- 是否影响公开 API/事件契约？若是，是否给出兼容与迁移指引？
- 是否可回滚（仅新增文件/配置、或可逆编辑）？
- 是否与 Roadmap/Plan 一致（M0–M3 阶段）？
- 是否提供了验证步骤（命令/接口/可观测指标）？
## 通用提示词模板
- 功能开发
- “请在不破坏现有 API 的前提下，为 {domain} 域新增 {feature}，产出：
1) 变更文件列表与最小改动；2) 新增接口/事件定义（含类型与示例）；
3) 单元/集成验证步骤；4) 回滚方法。上下文：{files...} 约束：禁跨域直查库、保留 /docs-json。”
- 事件接入
- “为 {domain} 接入事件 `{eventType}`：发布点、订阅方、载荷 schema（含 tenantId/idempotencyKey/traceId）、Outbox 入队、Kafka 主题、重试/幂等策略、验证步骤。”
- 性能优化
- “分析 {table/query} 的慢查询，提出仅加索引与读模型的优化方案；避免改表/改名；给出索引 DDL 与回滚方案，并提供前后对比验证步骤。”
- 网关与熔断
- “在 {Traefik|Kong} 中为 {route} 启用 JWT、限流、超时/重试、熔断；给出最小配置片段、灰度方案与回滚；不改变后端服务代码。”
- 文档生成
- “基于 `/docs-json` 拉取，更新 `openapi/api/{frontend|adminapi}`；仅路径与侧边栏更新，不改内容。”
## 示例回答应包含
- 变更点清单（文件/行号范围、改动理由）。
- 验证步骤（命令、接口调用、预期输出）。
- 回滚步骤（如何还原文件/配置、撤销索引/发布）。
- 影响评估（性能、安全、兼容性）。
---
以上规范用于约束 AI 在 WWJCloud 项目内的协作行为，确保结果“可用、可控、可演进”。

Some files were not shown because too many files have changed in this diff Show More