diff --git a/src/__tests__/project-wiki-command.spec.ts b/src/__tests__/project-wiki-command.spec.ts new file mode 100644 index 0000000000..f9cda50f16 --- /dev/null +++ b/src/__tests__/project-wiki-command.spec.ts @@ -0,0 +1,88 @@ +import { getCommands, getCommand } from "../services/command/commands" +import { ensureProjectWikiCommandExists } from "../core/tools/helpers/projectWikiHelpers" +import { projectWikiCommandName } from "../core/tools/helpers/projectWikiHelpers" + +describe("Project Wiki Command Integration", () => { + const testCwd = process.cwd() + + describe("动态命令初始化", () => { + it("应该能够初始化 project-wiki 命令而不抛出错误", async () => { + // 测试 ensureProjectWikiCommandExists 函数 + await expect(ensureProjectWikiCommandExists()).resolves.not.toThrow() + }) + + it("getCommands() 应该包含 project-wiki 命令", async () => { + // 确保命令已初始化 + await ensureProjectWikiCommandExists() + + // 获取所有命令 + const commands = await getCommands(testCwd) + + // 验证命令列表是数组 + expect(Array.isArray(commands)).toBe(true) + + // 查找 project-wiki 命令 + const projectWikiCommand = commands.find((cmd) => cmd.name === projectWikiCommandName) + + // 验证 project-wiki 命令存在 + expect(projectWikiCommand).toBeDefined() + + if (projectWikiCommand) { + expect(projectWikiCommand.name).toBe(projectWikiCommandName) + expect(projectWikiCommand.source).toBe("global") + expect(typeof projectWikiCommand.content).toBe("string") + expect(projectWikiCommand.content.length).toBeGreaterThan(0) + expect(projectWikiCommand.filePath).toContain("project-wiki.md") + } + }) + + it("getCommand() 应该能够获取 project-wiki 命令", async () => { + // 确保命令已初始化 + await ensureProjectWikiCommandExists() + + // 获取特定命令 + const command = await getCommand(testCwd, projectWikiCommandName) + + // 验证命令存在且正确 + expect(command).toBeDefined() + expect(command?.name).toBe(projectWikiCommandName) + expect(command?.source).toBe("global") + expect(typeof command?.content).toBe("string") + expect(command?.content.length).toBeGreaterThan(0) + }) + }) + + describe("错误处理机制", () => { + it("即使 ensureProjectWikiCommandExists 失败,getCommands 也应该正常工作", async () => { + // 这个测试验证错误隔离机制 + // 即使动态命令初始化失败,其他命令仍应正常工作 + const commands = await getCommands(testCwd) + + // 应该返回数组(可能为空,但不应该抛出错误) + expect(Array.isArray(commands)).toBe(true) + }) + + it("应该能够处理重复的命令初始化调用", async () => { + // 多次调用应该不会出错 + await expect(ensureProjectWikiCommandExists()).resolves.not.toThrow() + await expect(ensureProjectWikiCommandExists()).resolves.not.toThrow() + await expect(ensureProjectWikiCommandExists()).resolves.not.toThrow() + }) + }) + + describe("命令内容验证", () => { + it("project-wiki 命令应该包含预期的内容结构", async () => { + await ensureProjectWikiCommandExists() + const command = await getCommand(testCwd, projectWikiCommandName) + + expect(command).toBeDefined() + if (command) { + // 验证命令内容包含预期的关键词(中文内容) + const content = command.content + expect(content).toContain("项目") + expect(content).toContain("wiki") + expect(content).toContain("分析") + } + }) + }) +}) diff --git a/src/core/tools/__tests__/projectWikiHelpers.spec.ts b/src/core/tools/__tests__/projectWikiHelpers.spec.ts new file mode 100644 index 0000000000..f862b5f0cb --- /dev/null +++ b/src/core/tools/__tests__/projectWikiHelpers.spec.ts @@ -0,0 +1,61 @@ +import { describe, it, expect, vi, beforeEach } from "vitest" +import { ensureProjectWikiCommandExists } from "../helpers/projectWikiHelpers" +import { promises as fs } from "fs" +import * as path from "path" +import * as os from "os" + +// Mock fs module +vi.mock("fs") +const mockedFs = vi.mocked(fs) + +describe("projectWikiHelpers", () => { + const globalCommandsDir = path.join(os.homedir(), ".roo", "commands") + const projectWikiFile = path.join(globalCommandsDir, "project-wiki.md") + const subTaskDir = path.join(globalCommandsDir, "subtasks") + + beforeEach(() => { + vi.clearAllMocks() + }) + + it("should successfully create wiki command files", async () => { + // Mock file system operations + mockedFs.mkdir.mockResolvedValue(undefined) + mockedFs.access.mockRejectedValue(new Error("File not found")) + mockedFs.rm.mockResolvedValue(undefined) + mockedFs.writeFile.mockResolvedValue(undefined) + mockedFs.readdir.mockResolvedValue([ + "01_Project_Overview_Analysis.md", + "02_Overall_Architecture_Analysis.md", + ] as any) + + // Execute function + await expect(ensureProjectWikiCommandExists()).resolves.not.toThrow() + + // Verify calls + expect(mockedFs.mkdir).toHaveBeenCalledWith(globalCommandsDir, { recursive: true }) + expect(mockedFs.writeFile).toHaveBeenCalledTimes(10) // 1 main file + 9 subtask files + }) + + it("should skip creation when files already exist", async () => { + // Mock existing files + mockedFs.mkdir.mockResolvedValue(undefined) + mockedFs.access.mockResolvedValue(undefined) + mockedFs.stat.mockResolvedValue({ + isDirectory: () => true, + } as any) + mockedFs.readdir.mockResolvedValue(["01_Project_Overview_Analysis.md"] as any) + + // Execute function + await expect(ensureProjectWikiCommandExists()).resolves.not.toThrow() + + // Verify no write operations were called + expect(mockedFs.writeFile).not.toHaveBeenCalled() + }) + + it("should generate all wiki files correctly", async () => { + // Read the modified projectWikiHelpers.ts file to test the generateWikiFiles function + // generateWikiFiles is an internal function and not exported, so we test ensureProjectWikiCommandExists instead + // This will indirectly test the functionality of generateWikiFiles + expect(true).toBe(true) // Placeholder test + }) +}) diff --git a/src/core/tools/helpers/projectWikiHelpers.ts b/src/core/tools/helpers/projectWikiHelpers.ts new file mode 100644 index 0000000000..efca5668ec --- /dev/null +++ b/src/core/tools/helpers/projectWikiHelpers.ts @@ -0,0 +1,178 @@ +import { promises as fs } from "fs" +import * as path from "path" +import * as os from "os" +import { PROJECT_WIKI_TEMPLATE } from "./wiki-prompts/project-wiki" +import { PROJECT_OVERVIEW_ANALYSIS_TEMPLATE } from "./wiki-prompts/subtasks/01_Project_Overview_Analysis" +import { OVERALL_ARCHITECTURE_ANALYSIS_TEMPLATE } from "./wiki-prompts/subtasks/02_Overall_Architecture_Analysis" +import { SERVICE_DEPENDENCIES_ANALYSIS_TEMPLATE } from "./wiki-prompts/subtasks/03_Service_Dependencies_Analysis" +import { DATA_FLOW_INTEGRATION_ANALYSIS_TEMPLATE } from "./wiki-prompts/subtasks/04_Data_Flow_Integration_Analysis" +import { SERVICE_ANALYSIS_TEMPLATE } from "./wiki-prompts/subtasks/05_Service_Analysis_Template" +import { DATABASE_SCHEMA_ANALYSIS_TEMPLATE } from "./wiki-prompts/subtasks/06_Database_Schema_Analysis" +import { API_INTERFACE_ANALYSIS_TEMPLATE } from "./wiki-prompts/subtasks/07_API_Interface_Analysis" +import { DEPLOY_ANALYSIS_TEMPLATE } from "./wiki-prompts/subtasks/08_Deploy_Analysis" +import { PROJECT_RULES_GENERATION_TEMPLATE } from "./wiki-prompts/subtasks/09_Project_Rules_Generation" +import { ILogger, createLogger } from "../../../utils/logger" + +// Safely get home directory +function getHomeDir(): string { + const homeDir = os.homedir() + if (!homeDir) { + throw new Error("Unable to determine home directory") + } + return homeDir +} + +// Get global commands directory path +function getGlobalCommandsDir(): string { + return path.join(getHomeDir(), ".roo", "commands") +} + +export const projectWikiCommandName = "project-wiki" +export const projectWikiCommandDescription = `Analyze project deeply and generate a comprehensive project wiki.` + +const logger: ILogger = createLogger("ProjectWikiHelpers") + +// Unified error handling function, preserving stack information +function formatError(error: unknown): string { + if (error instanceof Error) { + return error.stack || error.message + } + return String(error) +} + +const mainFileName: string = projectWikiCommandName + ".md" +// Template data mapping +const TEMPLATES = { + [mainFileName]: PROJECT_WIKI_TEMPLATE, + "01_Project_Overview_Analysis.md": PROJECT_OVERVIEW_ANALYSIS_TEMPLATE, + "02_Overall_Architecture_Analysis.md": OVERALL_ARCHITECTURE_ANALYSIS_TEMPLATE, + "03_Service_Dependencies_Analysis.md": SERVICE_DEPENDENCIES_ANALYSIS_TEMPLATE, + "04_Data_Flow_Integration_Analysis.md": DATA_FLOW_INTEGRATION_ANALYSIS_TEMPLATE, + "05_Service_Analysis_Template.md": SERVICE_ANALYSIS_TEMPLATE, + "06_Database_Schema_Analysis.md": DATABASE_SCHEMA_ANALYSIS_TEMPLATE, + "07_API_Interface_Analysis.md": API_INTERFACE_ANALYSIS_TEMPLATE, + "08_Deploy_Analysis.md": DEPLOY_ANALYSIS_TEMPLATE, + "09_Project_Rules_Generation.md": PROJECT_RULES_GENERATION_TEMPLATE, +} + +export async function ensureProjectWikiCommandExists() { + const startTime = Date.now() + logger.info("[projectWikiHelpers] Starting ensureProjectWikiCommandExists...") + + try { + const globalCommandsDir = getGlobalCommandsDir() + await fs.mkdir(globalCommandsDir, { recursive: true }) + + const projectWikiFile = path.join(globalCommandsDir, `${projectWikiCommandName}.md`) + const subTaskDir = path.join(globalCommandsDir, "subtasks") + + // Check if setup is needed + const needsSetup = await checkIfSetupNeeded(projectWikiFile, subTaskDir) + if (!needsSetup) { + logger.info("[projectWikiHelpers] project-wiki command already exists") + return + } + + logger.info("[projectWikiHelpers] Setting up project-wiki command...") + + // Clean up existing files + await Promise.allSettled([ + fs.rm(projectWikiFile, { force: true }), + fs.rm(subTaskDir, { recursive: true, force: true }), + ]) + + // Generate Wiki files + await generateWikiCommandFiles(projectWikiFile, subTaskDir) + + const duration = Date.now() - startTime + logger.info(`[projectWikiHelpers] project-wiki command setup completed in ${duration}ms`) + } catch (error) { + const errorMsg = formatError(error) + throw new Error(`Failed to setup project-wiki command: ${errorMsg}`) + } +} + +// Optimized file checking logic, using Promise.allSettled to improve performance +async function checkIfSetupNeeded(projectWikiFile: string, subTaskDir: string): Promise { + try { + const [mainFileResult, subDirResult] = await Promise.allSettled([ + fs.access(projectWikiFile, fs.constants.F_OK | fs.constants.R_OK | fs.constants.W_OK), + fs.stat(subTaskDir), + ]) + + // If main file doesn't exist, setup is needed + if (mainFileResult.status === "rejected") { + logger.info("[projectWikiHelpers] projectWikiFile not accessible:", formatError(mainFileResult.reason)) + return true + } + + // If subtask directory doesn't exist or is not a directory, setup is needed + if (subDirResult.status === "rejected") { + logger.info("[projectWikiHelpers] subTaskDir not accessible:", formatError(subDirResult.reason)) + return true + } + + if (!subDirResult.value.isDirectory()) { + logger.info("[projectWikiHelpers] subTaskDir exists but is not a directory") + return true + } + + // Check if subtask directory has .md files + const subTaskFiles = await fs.readdir(subTaskDir) + const mdFiles = subTaskFiles.filter((file) => file.endsWith(".md")) + return mdFiles.length === 0 + } catch (error) { + logger.error("[projectWikiHelpers] Error checking setup status:", formatError(error)) + return true + } +} + +// Generate Wiki files +async function generateWikiCommandFiles(projectWikiFile: string, subTaskDir: string): Promise { + try { + // Generate main file + const mainTemplate = TEMPLATES[mainFileName] + if (!mainTemplate) { + throw new Error("Main template not found") + } + + await fs.writeFile(projectWikiFile, mainTemplate, "utf-8") + logger.info(`[projectWikiHelpers] Generated main wiki file: ${projectWikiFile}`) + + // Create subtask directory + await fs.mkdir(subTaskDir, { recursive: true }) + + // Generate subtask files + const subTaskFiles = Object.keys(TEMPLATES).filter((file) => file !== mainFileName) + const generateResults = await Promise.allSettled( + subTaskFiles.map(async (file) => { + const template = TEMPLATES[file as keyof typeof TEMPLATES] + if (!template) { + throw new Error(`Template not found for file: ${file}`) + } + + const targetFile = path.join(subTaskDir, file) + await fs.writeFile(targetFile, template, "utf-8") + return file + }), + ) + + // Count generation results + const successful = generateResults.filter((result) => result.status === "fulfilled") + const failed = generateResults.filter((result) => result.status === "rejected") + + logger.info(`[projectWikiHelpers] Successfully generated ${successful.length} subtask files`) + + if (failed.length > 0) { + logger.warn(`[projectWikiHelpers] Failed to generate ${failed.length} subtask files:`) + failed.forEach((result, index) => { + if (result.status === "rejected") { + logger.warn(` - ${subTaskFiles[generateResults.indexOf(result)]}: ${formatError(result.reason)}`) + } + }) + } + } catch (error) { + const errorMsg = formatError(error) + throw new Error(`Failed to generate wiki files: ${errorMsg}`) + } +} diff --git a/src/core/tools/helpers/wiki-prompts/project-wiki.ts b/src/core/tools/helpers/wiki-prompts/project-wiki.ts new file mode 100644 index 0000000000..6863a70f4b --- /dev/null +++ b/src/core/tools/helpers/wiki-prompts/project-wiki.ts @@ -0,0 +1,24 @@ +import * as os from "os" +import * as path from "path" +import { WIKI_OUTPUT_DIR } from "./subtasks/constants" + +const subtaskDir = path.join(os.homedir(), ".roo", "commands", "subtasks") + path.sep +export const PROJECT_WIKI_TEMPLATE = `--- +description: "深度分析项目,生成技术文档" +--- +您是一位专业的技术作家和软件架构师。 +以下每个文件中的内容都是一个任务,按顺序作为指令严格逐个执行: + +[项目概览分析](${subtaskDir}01_Project_Overview_Analysis.md) +[整体架构分析](${subtaskDir}02_Overall_Architecture_Analysis.md) +[服务依赖分析](${subtaskDir}03_Service_Dependencies_Analysis.md) +[数据流分析](${subtaskDir}04_Data_Flow_Integration_Analysis.md) +[服务模块分析](${subtaskDir}05_Service_Analysis_Template.md) +[数据库分析](${subtaskDir}06_Database_Schema_Analysis.md) +[API分析](${subtaskDir}07_API_Interface_Analysis.md) +[部署分析](${subtaskDir}08_Deploy_Analysis.md) +[Rues生成](${subtaskDir}09_Project_Rules_Generation.md) +注意: +1、如果未发现上述文件,直接退出报错即可,禁止自作主张! +2、一切以实际项目为准,禁止无中生有! +3、最终产物是${WIKI_OUTPUT_DIR}目录下的若干个技术文档,生成完成后,为它们在${WIKI_OUTPUT_DIR}目录下创建一个index.md 文件,内容是前面技术文档的简洁目录,index.md控制20行左右;` diff --git a/src/core/tools/helpers/wiki-prompts/subtasks/01_Project_Overview_Analysis.ts b/src/core/tools/helpers/wiki-prompts/subtasks/01_Project_Overview_Analysis.ts new file mode 100644 index 0000000000..b37671120c --- /dev/null +++ b/src/core/tools/helpers/wiki-prompts/subtasks/01_Project_Overview_Analysis.ts @@ -0,0 +1,277 @@ +import { WIKI_OUTPUT_DIR } from "./constants" + +export const PROJECT_OVERVIEW_ANALYSIS_TEMPLATE = `# 项目技术概览分析 +## 使用场景 +生成项目的技术概述文档,包括项目定位、技术栈、开发规范等,适用于新人入职或技术交流。 + +## 输入要求 +- **完整代码仓库**: 项目的完整源代码 +- **README文件**: 项目说明和使用指南 +- **配置文件**: 项目配置和依赖管理 +- **构建脚本**: 构建、测试、部署脚本 + +# 项目概述和技术总结分析任务 + +## 任务描述 +请基于完整的代码仓库,生成项目的技术概述文档,为开发者提供项目的整体认知和技术指南。 + +## 分析维度 + +### 1. 项目定位和业务价值 +#### 业务背景分析 +- **项目定位**: 分析项目在业务生态中的作用和价值 +- **目标用户**: 识别项目的主要用户群体和使用场景 +- **核心功能**: 提取项目的核心业务功能和特色 +- **技术优势**: 分析项目的技术亮点和竞争优势 + +#### 业务架构分析 +\`\`\` +通过代码分析识别: +- 核心业务域和功能模块 +- 用户角色和权限体系 +- 业务流程和数据流转 +- 系统边界和集成接口 +\`\`\` + +### 2. 技术栈深度分析 +#### 后端技术栈 +\`\`\`go +// 分析主要技术组件 +- 编程语言 +- Web框架 +- ORM框架 +- 数据库 +- 消息队列 +- 配置管理 +- 日志处理 +- 监控体系 +\`\`\` + +#### 基础设施技术 +- **容器化**: Docker + Docker Compose +- **编排工具**: Kubernetes + Helm +- **CI/CD**: GitLab CI/Jenkins +- **监控告警**: Prometheus + AlertManager +- **日志聚合**: ELK Stack/Loki +- **链路追踪**: Jaeger/Zipkin + +### 3. 代码架构和设计模式分析 +#### 项目组织结构 +\`\`\` +分析代码组织模式: +project/ +├── cmd/ # 服务入口点 +│ ├── management/ # 管理服务 +│ ├── collector/ # 收集服务 +│ └── ... +├── internal/ # 内部代码 +│ ├── api/ # API定义 +│ ├── service/ # 业务逻辑 +│ ├── repository/ # 数据访问 +│ └── model/ # 数据模型 +├── pkg/ # 公共代码 +├── configs/ # 配置文件 +├── scripts/ # 构建脚本 +└── docs/ # 文档 +\`\`\` + +#### 设计模式应用 +- **分层架构**: Controller-Service-Repository +- **依赖注入**: 依赖注入框架使用 +- **工厂模式**: 对象创建和管理 +- **观察者模式**: 事件驱动和消息处理 +- **策略模式**: 算法封装和切换 + +### 4. 开发规范和最佳实践 +#### 代码规范 +- **命名规范**: 变量、函数、类的命名约定 +- **代码风格**: 缩进、空格、注释规范 +- **错误处理**: 统一的错误处理机制 +- **日志规范**: 日志级别和格式要求 + +#### 工程实践 +- **测试策略**: 单元测试、集成测试、E2E测试 +- **代码审查**: Code Review流程和标准 +- **版本管理**: Git工作流和分支策略 +- **文档维护**: 代码注释和技术文档 + +### 5. 项目特色和创新点 +#### 技术创新 +- **架构创新**: 独特的架构设计思路 +- **性能优化**: 性能优化策略和成果 +- **安全设计**: 安全机制和防护措施 +- **可扩展性**: 系统扩展能力设计 + +#### 业务价值 +- **效率提升**: 开发效率或业务效率提升 +- **成本优化**: 资源成本或运维成本优化 +- **用户体验**: 用户体验改善和提升 +- **技术影响**: 对行业或社区的技术贡献 + +## 输出格式要求 + +生成完整的项目技术概览文档: + +### 文档结构 +\`\`\`markdown +# {项目名称} 技术概览 + +## 项目概述 + +### 项目定位 +- **项目名称**: {project_name} +- **项目类型**: {项目类型描述} +- **核心价值**: {核心价值描述} +- **目标用户**: {目标用户群体} + +### 技术特色 +- **架构特点**: {架构特色描述} +- **技术亮点**: {技术亮点列表} +- **创新点**: {技术创新点} +- **竞争优势**: {技术竞争优势} + +## 技术栈分析 + +### 后端技术栈 +| 技术类型 | 技术选型 | 版本 | 用途 | +|---------|---------|------|------| +| 编程语言 | Go | 1.21+ | 主要开发语言 | +| Web框架 | Echo | v4.10+ | HTTP框架 | +| ORM框架 | GORM | 1.25+ | 数据库操作 | +| 数据库 | PostgreSQL | 15+ | 主数据存储 | +| 缓存 | Redis | 7.0+ | 缓存和会话 | +| 消息队列 | Pulsar | 2.11+ | 消息中间件 | + +### 基础设施技术 +| 技术领域 | 技术选型 | 作用 | +|---------|---------|------| +| 容器化 | Docker | 应用容器化 | +| 编排工具 | Kubernetes | 容器编排 | +| CI/CD | GitLab CI | 持续集成部署 | +| 监控告警 | Prometheus | 指标监控 | +| 日志聚合 | ELK Stack | 日志收集分析 | +| 链路追踪 | Jaeger | 分布式追踪 | + +## 架构设计 + +### 系统架构图 +\`\`\`mermaid +graph TB + subgraph "接入层" + A[负载均衡] --> B[API网关] + end + + subgraph "服务层" + B --> C[Management服务] + B --> D[Collector服务] + B --> E[IDM服务] + end + + subgraph "数据层" + C --> F[(PostgreSQL)] + D --> F + E --> F + C --> G[(Redis)] + D --> H[(Pulsar)] + end + + subgraph "基础设施" + I[Kubernetes] --> C + I --> D + I --> E + end +\`\`\` + +### 分层架构 +- **接入层**: 负载均衡、API网关、认证授权 +- **服务层**: 业务微服务、服务治理、监控追踪 +- **数据层**: 关系数据库、缓存、消息队列 +- **基础设施**: 容器编排、CI/CD、监控告警 + +## 开发规范 + +### 代码规范 +- **命名约定**: 驼峰命名、下划线分隔、前缀规范 +- **代码风格**: gofmt格式化、golint检查、静态分析 +- **错误处理**: 统一错误码、错误信息、异常处理 +- **日志规范**: 结构化日志、日志级别、上下文信息 + +### 工程实践 +- **测试策略**: 单元测试覆盖率>80%、集成测试、E2E测试 +- **代码审查**: 强制Code Review、自动化检查、人工审核 +- **版本管理**: Git Flow、分支保护、标签管理 +- **文档维护**: 代码注释、API文档、架构文档 + +## 项目特色 + +### 技术创新 +- **架构创新**: {架构创新点描述} +- **性能优化**: {性能优化策略和成果} +- **安全设计**: {安全机制和防护措施} +- **可扩展性**: {系统扩展能力设计} + +### 业务价值 +- **效率提升**: {开发效率或业务效率提升} +- **成本优化**: {资源成本或运维成本优化} +- **用户体验**: {用户体验改善和提升} +- **技术影响**: {对行业或社区的技术贡献} + +## 快速开始 + +### 环境准备 +- **开发环境**: Go 1.21+、Docker、Kubernetes +- **依赖服务**: PostgreSQL、Redis、Pulsar +- **开发工具**: VSCode、Go插件、Docker Desktop + +### 构建运行 +\`\`\`bash +# 克隆项目 +git clone {repository_url} +cd {project_name} + +# 安装依赖 +go mod download + +# 启动依赖服务 +docker-compose up -d + +# 构建项目 +make build + +# 运行服务 +./bin/management +\`\`\` + +## 贡献指南 + +### 开发流程 +1. Fork项目仓库 +2. 创建功能分支 +3. 提交代码变更 +4. 创建Pull Request +5. 代码审查和合并 + +### 联系方式 +- **技术交流**: {技术交流群组} +- **问题反馈**: {问题反馈渠道} +- **贡献指南**: {贡献文档链接} +\`\`\` + +## 特别注意事项 +1. 必须基于实际代码进行分析,不能虚构技术栈 +2. 重点分析项目的架构设计思路和技术选型原因 +3. 关注项目的特色功能和创新点 +4. 识别技术难点和解决方案 +5. 提供实用的开发指导和最佳实践 + +## 输出文件命名 +\`${WIKI_OUTPUT_DIR}01_{PROJECT_NAME}_Overview.md\` +注意:如果${WIKI_OUTPUT_DIR} 目录不存在,则创建。 + +## 示例输出特征 +基于项目的分析特征: +- 清晰的项目定位和技术特色描述 +- 完整的技术栈表格化展示 +- 详细的架构设计图和分层说明 +- 实用的开发规范和最佳实践 +- 具体的快速开始和贡献指南` diff --git a/src/core/tools/helpers/wiki-prompts/subtasks/02_Overall_Architecture_Analysis.ts b/src/core/tools/helpers/wiki-prompts/subtasks/02_Overall_Architecture_Analysis.ts new file mode 100644 index 0000000000..d947904c9b --- /dev/null +++ b/src/core/tools/helpers/wiki-prompts/subtasks/02_Overall_Architecture_Analysis.ts @@ -0,0 +1,476 @@ +import { WIKI_OUTPUT_DIR } from "./constants" + +export const OVERALL_ARCHITECTURE_ANALYSIS_TEMPLATE = `# 整体架构深度分析 + +## 使用场景 +从代码仓库中分析项目的整体架构设计,生成详细的架构文档,包括系统架构、模块划分、数据流等。 + +## 输入要求 +- **完整代码仓库**: 项目的完整源代码 +- **配置文件**: 项目配置和依赖管理 +- **部署文件**: Docker、Kubernetes等部署配置 +- **文档文件**: 架构设计文档和技术规范 + +# 整体架构深度分析任务 + +## 任务描述 +请深度分析项目的整体架构设计,从系统架构、模块划分、数据流、技术选型等维度生成完整的架构技术文档。 + +## 分析维度 + +### 1. 系统架构模式识别 +#### 架构风格分析 +通过分析代码结构和部署配置识别架构风格: +- **微服务架构**: 服务拆分、独立部署、服务治理 +- **单体架构**: 集中式部署、模块化设计 +- **分层架构**: 表现层、业务层、数据层分离 +- **事件驱动**: 消息队列、事件发布订阅 + +#### 架构特征分析 +\`\`\` +// 分析架构特征 +- 服务边界和职责划分 +- 数据存储策略和分布 +- 通信协议和接口设计 +- 部署模式和运维策略 +\`\`\` + +### 2. 服务架构深度分析 +#### 微服务拆分策略 +\`\`\`go +// 分析服务拆分模式 +// 识别服务边界和职责 +\`\`\` + +#### 服务治理分析 +- **服务注册发现**: 服务注册机制和发现策略 +- **负载均衡**: 流量分发和负载策略 +- **熔断降级**: 服务保护和容错机制 +- **链路追踪**: 分布式追踪和监控 + +### 3. 数据架构分析 +#### 数据存储架构 +- **关系数据库**: 事务性数据存储 +- **NoSQL数据库**: 非结构化数据存储 +- **缓存系统**: 高性能数据缓存 +- **消息队列**: 异步消息处理 + +#### 数据流分析 +\`\`\`mermaid +graph LR + A[用户请求] --> B[API网关] + B --> C[业务服务] + C --> D[数据库] + C --> E[缓存] + C --> F[消息队列] + F --> G[消费者服务] +\`\`\` + +### 4. 技术架构分析 +#### 技术栈架构 +\`\`\` +// 分析技术栈组合 +- 前端技术栈 +- 后端技术栈 +- 数据库技术栈 +- 中间件技术栈 +- 基础设施技术栈 +\`\`\` + +#### 架构设计模式 +- **分层架构**: MVC、MVVM、Clean Architecture +- **微服务模式**: API网关、服务网格、边车模式 +- **事件驱动模式**: 发布订阅、事件溯源、CQRS +- **云原生模式**: 容器化、编排、服务网格 + +### 5. 部署架构分析 +#### 容器化架构 +\`\`\`dockerfile +# 分析容器化策略 +FROM golang:1.21-alpine AS builder +WORKDIR /app +COPY . . +RUN go build -o main . + +FROM alpine:latest +RUN apk --no-cache add ca-certificates +WORKDIR /root/ +COPY --from=builder /app/main . +CMD ["./main"] +\`\`\` + +#### 编排架构 +- **Kubernetes**: 容器编排和服务管理 +- **Helm**: 应用包管理和部署 +- **Istio**: 服务网格和流量管理 +- **Prometheus**: 监控指标收集 + +### 6. 安全架构分析 +#### 认证授权架构 +\`\`\`go +// 分析认证授权机制 +// JWT、OAuth2、RBAC等 +\`\`\` + +#### 安全防护架构 +- **网络安全**: 防火墙、WAF、SSL/TLS +- **应用安全**: 输入验证、SQL注入防护、XSS防护 +- **数据安全**: 加密存储、数据脱敏、访问控制 +- **运维安全**: 审计日志、安全监控、漏洞扫描 + +## 输出格式要求 + +生成完整的架构分析文档: + +### 文档结构 +\`\`\`markdown +# {项目名称} 整体架构分析 + +## 架构概览 + +### 系统定位 +- **项目类型**: {项目类型描述} +- **业务领域**: {业务领域说明} +- **用户规模**: {用户规模预估} +- **技术复杂度**: {技术复杂度评估} + +### 架构目标 +- **高性能**: {性能目标和指标} +- **高可用**: {可用性目标和策略} +- **可扩展**: {扩展性设计思路} +- **易维护**: {可维护性设计考虑} + +## 系统架构设计 + +### 架构风格 +#### {架构风格名称} +- **架构描述**: {架构风格详细说明} +- **选择原因**: {选择该架构的原因} +- **适用场景**: {适用的业务场景} +- **优缺点分析**: {优势和劣势分析} + +### 整体架构图 +\`\`\`mermaid +graph TB + subgraph "接入层" + A[负载均衡] --> B[API网关] + B --> C[认证服务] + end + + subgraph "业务服务层" + C --> D[Management服务] + C --> E[Collector服务] + C --> F[IDM服务] + D --> G[业务逻辑1] + E --> H[业务逻辑2] + F --> I[业务逻辑3] + end + + subgraph "数据层" + G --> J[(PostgreSQL)] + H --> J + I --> J + G --> K[(Redis)] + H --> L[(Pulsar)] + I --> L + end + + subgraph "基础设施" + M[Kubernetes] --> D + M --> E + M --> F + N[Prometheus] --> D + N --> E + N --> F + end +\`\`\` + +### 架构分层说明 +#### 接入层 +- **负载均衡**: {负载均衡策略和实现} +- **API网关**: {网关功能和配置} +- **认证授权**: {认证机制和授权策略} + +#### 业务服务层 +- **服务拆分**: {服务拆分策略和边界} +- **服务治理**: {服务治理机制和工具} +- **业务逻辑**: {核心业务逻辑模块} + +#### 数据层 +- **数据存储**: {数据存储策略和选型} +- **缓存策略**: {缓存机制和配置} +- **消息队列**: {消息处理机制和配置} + +## 服务架构 + +### 微服务设计 +#### 服务清单 +| 服务名称 | 端口 | 功能描述 | 技术栈 | 依赖服务 | +|---------|------|----------|-------|----------| +| Management | 8080 | 核心管理功能 | Go+Echo | PostgreSQL, Redis | +| Collector | 9164 | 数据收集服务 | Go+Echo | PostgreSQL, Pulsar | +| IDM | 8005 | 身份管理服务 | Go+Echo | PostgreSQL, Redis | + +#### 服务间通信 +- **同步通信**: HTTP/REST、gRPC +- **异步通信**: 消息队列、事件总线 +- **通信协议**: {协议选择和原因} +- **数据格式**: JSON、Protobuf等 + +### 服务治理 +#### 服务注册发现 +- **注册中心**: {注册中心选型和配置} +- **健康检查**: {健康检查机制和策略} +- **负载均衡**: {负载均衡算法和配置} + +#### 容错机制 +- **熔断降级**: {熔断策略和配置} +- **重试机制**: {重试策略和配置} +- **限流控制**: {限流算法和配置} + +## 数据架构 + +### 数据存储架构 +#### 数据库选型 +| 数据库类型 | 技术选型 | 用途 | 特点 | +|-----------|---------|------|------| +| 关系数据库 | PostgreSQL | 事务性数据 | ACID特性、复杂查询 | +| 缓存数据库 | Redis | 高性能缓存 | 内存存储、高性能 | +| 消息队列 | Pulsar | 异步消息 | 高吞吐、持久化 | + +#### 数据分片策略 +- **水平分片**: {分片策略和实现} +- **垂直分片**: {分库分表策略} +- **读写分离**: {读写分离配置} + +### 数据流设计 +#### 业务数据流 +\`\`\`mermaid +sequenceDiagram + participant U as 用户 + participant G as API网关 + participant S as 业务服务 + participant D as 数据库 + participant C as 缓存 + + U->>G: 发起请求 + G->>S: 转发请求 + S->>C: 查询缓存 + alt 缓存命中 + C->>S: 返回缓存数据 + else 缓存未命中 + S->>D: 查询数据库 + D->>S: 返回数据 + S->>C: 更新缓存 + end + S->>G: 返回响应 + G->>U: 返回结果 +\`\`\` + +#### 事件流 +- **事件发布**: {事件发布机制} +- **事件订阅**: {事件订阅和处理} +- **事件存储**: {事件持久化策略} + +## 技术架构 + +### 技术栈架构 +#### 后端技术栈 +| 技术层级 | 技术选型 | 版本 | 作用 | +|---------|---------|------|------| +| 编程语言 | Go | 1.21+ | 主要开发语言 | +| Web框架 | Echo | v4.10+ | HTTP框架 | +| ORM框架 | GORM | 1.25+ | 数据库操作 | +| 配置管理 | Viper | v2.0+ | 配置文件管理 | + +#### 中间件技术栈 +| 中间件类型 | 技术选型 | 用途 | 特点 | +|-----------|---------|------|------| +| 消息队列 | Apache Pulsar | 异步消息处理 | 高吞吐、多租户 | +| 缓存系统 | Redis | 数据缓存 | 高性能、持久化 | +| 服务网格 | Istio | 服务治理 | 流量管理、安全 | + +### 架构模式应用 +#### 设计模式 +- **分层架构**: {分层架构应用说明} +- **微服务模式**: {微服务设计模式} +- **事件驱动模式**: {事件驱动应用} +- **云原生模式**: {云原生技术栈} + +#### 架构原则 +- **单一职责**: {职责分离原则} +- **开闭原则**: {扩展性设计} +- **依赖倒置**: {依赖注入设计} +- **接口隔离**: {接口设计原则} + +## 部署架构 + +### 容器化架构 +#### Docker镜像策略 +| 服务名称 | 镜像名称 | 基础镜像 | 构建策略 | +|---------|---------|----------|----------| +| Management | management:latest | golang:1.21-alpine | 多阶段构建 | +| Collector | collector:latest | golang:1.21-alpine | 多阶段构建 | +| IDM | idm:latest | golang:1.21-alpine | 多阶段构建 | + +#### 容器编排 +- **Kubernetes**: {K8s部署策略} +- **Helm**: {Helm Chart管理} +- **配置管理**: {ConfigMap和Secret管理} + +### 环境部署 +#### 多环境部署 +| 环境类型 | 部署方式 | 配置特点 | 访问地址 | +|---------|---------|----------|----------| +| 开发环境 | Docker Compose | 本地开发配置 | localhost | +| 测试环境 | Kubernetes | 测试配置 | test.example.com | +| 生产环境 | Kubernetes | 生产优化配置 | api.example.com | + +#### 部署流水线 +\`\`\`mermaid +graph LR + A[代码提交] --> B[构建镜像] + B --> C[单元测试] + C --> D[集成测试] + D --> E[部署测试环境] + E --> F[验收测试] + F --> G[部署生产环境] +\`\`\` + +## 安全架构 + +### 认证授权架构 +#### 身份认证 +- **JWT认证**: {JWT实现和配置} +- **OAuth2集成**: {第三方认证集成} +- **多因素认证**: {MFA机制和配置} + +#### 权限控制 +- **RBAC模型**: {角色权限设计} +- **ABAC模型**: {属性权限控制} +- **API权限**: {接口权限控制} + +### 安全防护架构 +#### 网络安全 +- **防火墙**: {防火墙配置和策略} +- **WAF防护**: {Web应用防火墙} +- **SSL/TLS**: {加密通信配置} + +#### 应用安全 +- **输入验证**: {参数校验和过滤} +- **SQL注入防护**: {ORM安全使用} +- **XSS防护**: {跨站脚本防护} + +#### 数据安全 +- **数据加密**: {敏感数据加密} +- **数据脱敏**: {隐私数据保护} +- **访问控制**: {数据权限管理} + +## 性能架构 + +### 性能目标 +#### 性能指标 +| 指标类型 | 目标值 | 当前值 | 达标情况 | +|---------|-------|--------|----------| +| 响应时间 | <100ms | 85ms | ✅ | +| 吞吐量 | >1000 QPS | 1200 QPS | ✅ | +| 并发用户 | >10000 | 8000 | ⚠️ | +| 可用性 | >99.9% | 99.95% | ✅ | + +#### 性能优化策略 +- **缓存优化**: {缓存策略和配置} +- **数据库优化**: {查询优化和索引} +- **并发优化**: {并发控制和优化} + +### 扩展性设计 +#### 水平扩展 +- **服务扩展**: {服务水平扩展策略} +- **数据扩展**: {数据分片和扩展} +- **负载扩展**: {负载均衡扩展} + +#### 垂直扩展 +- **硬件升级**: {硬件配置优化} +- **软件优化**: {软件性能优化} +- **配置调优**: {系统参数调优} + +## 监控架构 + +### 监控体系 +#### 指标监控 +- **业务指标**: {业务关键指标} +- **技术指标**: {技术性能指标} +- **系统指标**: {系统资源指标} + +#### 日志监控 +- **结构化日志**: {日志格式和规范} +- **日志聚合**: {日志收集和分析} +- **错误追踪**: {错误监控和告警} + +### 告警机制 +#### 告警规则 +- **业务告警**: {业务异常告警} +- **技术告警**: {技术故障告警} +- **系统告警**: {系统资源告警} + +#### 告警处理 +- **告警级别**: {告警分级策略} +- **告警通知**: {通知渠道和配置} +- **故障处理**: {故障处理流程} + +## 架构演进 + +### 演进规划 +#### 短期规划 +- {短期架构优化计划} +- {技术栈升级计划} +- {性能提升计划} + +#### 长期规划 +- {长期架构演进方向} +- {新技术引入计划} +- {架构重构计划} + +### 技术债务 +#### 现有问题 +- {架构设计问题} +- {技术选型问题} +- {性能瓶颈问题} + +#### 改进计划 +- {问题解决方案} +- {优化实施计划} +- {效果评估指标} + +## 总结 + +### 架构优势 +- {架构设计优势} +- {技术选型优势} +- {性能表现优势} +- {可维护性优势} + +### 改进建议 +- {架构优化建议} +- {技术升级建议} +- {性能提升建议} +- {运维改进建议} +\`\`\` + +## 特别注意事项 +1. 必须基于实际的代码和配置进行分析,不能虚构架构设计 +2. 重点分析架构设计思路和技术选型原因 +3. 关注架构的可扩展性和可维护性 +4. 识别架构中的潜在问题和改进空间 +5. 提供实用的架构优化建议和最佳实践 + +## 输出文件命名 +\`${WIKI_OUTPUT_DIR}02_{PROJECT_NAME}_Architecture.md\` +注意:如果${WIKI_OUTPUT_DIR} 目录不存在,则创建。 + +## 示例输出特征 +基于项目的架构分析特征: +- 详细的架构设计图和分层说明 +- 完整的服务架构和治理机制 +- 清晰的数据架构和流设计 +- 全面的安全架构和防护措施 +- 实用的性能架构和优化策略` diff --git a/src/core/tools/helpers/wiki-prompts/subtasks/03_Service_Dependencies_Analysis.ts b/src/core/tools/helpers/wiki-prompts/subtasks/03_Service_Dependencies_Analysis.ts new file mode 100644 index 0000000000..e3727f4c91 --- /dev/null +++ b/src/core/tools/helpers/wiki-prompts/subtasks/03_Service_Dependencies_Analysis.ts @@ -0,0 +1,515 @@ +import { WIKI_OUTPUT_DIR } from "./constants" + +export const SERVICE_DEPENDENCIES_ANALYSIS_TEMPLATE = `# 服务依赖深度分析 + +## 使用场景 +从代码仓库中分析服务间的依赖关系,生成详细的依赖文档,包括服务调用、数据流、接口依赖等。 + +## 输入要求 +- **完整代码仓库**: 项目的完整源代码 +- **服务配置**: 各服务的配置文件 +- **API定义**: 服务间接口定义 +- **部署配置**: 服务部署和编排配置 + +# 服务依赖深度分析任务 + +## 任务描述 +请深度分析项目中的服务依赖关系,从服务调用、数据流、接口依赖、配置依赖等维度生成完整的服务依赖技术文档。 + +## 分析维度 + +### 1. 服务间调用依赖分析 +#### HTTP服务调用 +\`\`\`go +// 分析HTTP客户端调用模式 +// 识别服务间的HTTP调用关系 +\`\`\` + +#### gRPC服务调用 +\`\`\`protobuf +// 分析protobuf定义 +// 识别gRPC服务间的调用关系 +\`\`\` + +#### 消息队列依赖 +\`\`\`go +// 分析消息队列生产者和消费者 +// 识别异步服务依赖关系 +\`\`\` + +### 2. 数据依赖分析 +#### 数据库依赖 +- **主数据库**: 共享的主数据库依赖 +- **从数据库**: 只读数据库依赖 +- **缓存依赖**: Redis等缓存系统依赖 +- **消息存储**: 消息队列数据依赖 + +#### 数据流依赖 +\`\`\`mermaid +graph LR + A[Service A] --> B[Database] + A --> C[Cache] + A --> D[Message Queue] + E[Service B] --> B + E --> C + F[Service C] --> D + F --> B +\`\`\` + +### 3. 配置依赖分析 +#### 环境配置依赖 +- **共享配置**: 服务间共享的配置项 +- **服务特定配置**: 各服务特有的配置 +- **动态配置**: 运行时动态配置依赖 +- **配置中心**: 配置管理服务依赖 + +#### 依赖服务配置 +\`\`\`yaml +# 分析服务配置中的依赖项 +database: + host: postgres-service + port: 5432 + +redis: + host: redis-service + port: 6379 + +message_queue: + broker: pulsar-service + port: 6650 +\`\`\` + +### 4. 接口依赖分析 +#### API接口依赖 +- **REST API**: HTTP接口依赖关系 +- **GraphQL**: GraphQL查询依赖 +- **WebSocket**: 实时通信接口依赖 +- **RPC接口**: 远程过程调用依赖 + +#### 接口版本依赖 +\`\`\` +// 分析接口版本管理 +// 识别版本兼容性依赖 +\`\`\` + +### 5. 第三方服务依赖分析 +#### 外部API依赖 +- **支付服务**: 第三方支付接口 +- **短信服务**: 短信发送服务 +- **邮件服务**: 邮件发送服务 +- **存储服务**: 云存储服务 + +#### 云服务依赖 +- **数据库服务**: 云数据库服务 +- **缓存服务**: 云缓存服务 +- **消息服务**: 云消息服务 +- **监控服务**: 云监控服务 + +### 6. 基础设施依赖分析 +#### 容器编排依赖 +- **Kubernetes**: K8s服务依赖 +- **Docker**: 容器运行时依赖 +- **Helm**: 包管理依赖 +- **Istio**: 服务网格依赖 + +#### 网络依赖 +- **负载均衡**: 负载均衡服务依赖 +- **API网关**: 网关服务依赖 +- **服务发现**: 服务注册发现依赖 +- **配置中心**: 配置管理依赖 + +## 输出格式要求 + +生成完整的服务依赖分析文档: + +### 文档结构 +\`\`\`markdown +# {项目名称} 服务依赖分析 + +## 依赖概览 + +### 服务清单 +| 服务名称 | 端口 | 技术栈 | 责任人 | 状态 | +|---------|------|-------|--------|------| +| Management | 8080 | Go+Echo | 团队A | ✅ 运行中 | +| Collector | 9164 | Go+Echo | 团队B | ✅ 运行中 | +| IDM | 8005 | Go+Echo | 团队C | ✅ 运行中 | + +### 依赖关系总览 +\`\`\`mermaid +graph TB + subgraph "核心服务" + A[Management] --> B[PostgreSQL] + A --> C[Redis] + A --> D[Pulsar] + end + + subgraph "数据服务" + E[Collector] --> B + E --> D + E --> F[Elasticsearch] + end + + subgraph "认证服务" + G[IDM] --> B + G --> C + G --> H[JWT服务] + end + + subgraph "外部服务" + A --> I[支付API] + A --> J[短信API] + E --> K[邮件API] + end + + subgraph "基础设施" + L[Kubernetes] --> A + L --> E + L --> G + M[Prometheus] --> A + M --> E + M --> G + end +\`\`\` + +## 服务间调用依赖 + +### HTTP服务调用 +#### 同步调用关系 +| 调用服务 | 被调用服务 | 接口路径 | 调用方式 | 依赖级别 | +|---------|-----------|----------|----------|----------| +| Management | IDM | /api/v1/auth/validate | HTTP POST | 强依赖 | +| Management | Collector | /api/v1/data/collect | HTTP GET | 弱依赖 | +| Collector | Management | /api/v1/status | HTTP GET | 弱依赖 | + +#### 调用特征分析 +- **调用频率**: {高频/中频/低频调用} +- **响应时间**: {平均响应时间} +- **超时设置**: {调用超时配置} +- **重试策略**: {重试机制和配置} + +### gRPC服务调用 +#### gRPC服务定义 +\`\`\`protobuf +// 分析gRPC服务定义 +service ManagementService { + rpc GetUser(GetUserRequest) returns (GetUserResponse); + rpc CreateUser(CreateUserRequest) returns (CreateUserResponse); +} + +service CollectorService { + rpc CollectData(CollectDataRequest) returns (CollectDataResponse); + rpc GetDataStatus(GetDataStatusRequest) returns (GetDataStatusResponse); +} +\`\`\` + +#### gRPC调用关系 +| 调用服务 | 被调用服务 | gRPC方法 | 调用频率 | 超时设置 | +|---------|-----------|----------|----------|----------| +| Management | IDM | GetUser | 高频 | 5s | +| Management | Collector | CollectData | 中频 | 10s | + +### 消息队列依赖 +#### 消息生产者 +| 服务名称 | 主题(Topic) | 消息类型 | 发送频率 | QoS级别 | +|---------|------------|----------|----------|----------| +| Management | user-events | 用户事件 | 高频 | QoS 1 | +| Collector | data-events | 数据事件 | 中频 | QoS 0 | + +#### 消息消费者 +| 服务名称 | 订阅主题 | 消费方式 | 消费组 | 处理策略 | +|---------|----------|----------|--------|----------| +| IDM | user-events | 订阅 | idm-group | 顺序处理 | +| Management | data-events | 订阅 | mgmt-group | 并行处理 | + +## 数据依赖分析 + +### 数据库依赖 +#### 主数据库依赖 +| 服务名称 | 数据库 | 表名 | 操作类型 | 依赖级别 | +|---------|--------|------|----------|----------| +| Management | PostgreSQL | users | CRUD | 强依赖 | +| Management | PostgreSQL | roles | CRUD | 强依赖 | +| Collector | PostgreSQL | data_logs | CRUD | 强依赖 | +| IDM | PostgreSQL | auth_tokens | CRUD | 强依赖 | + +#### 数据库连接配置 +\`\`\`yaml +# 分析数据库连接配置 +database: + postgres: + host: postgres-service + port: 5432 + database: app_db + username: app_user + max_connections: 100 + max_idle_connections: 10 +\`\`\` + +### 缓存依赖 +#### Redis缓存依赖 +| 服务名称 | 缓存类型 | 缓存键模式 | 过期时间 | 依赖级别 | +|---------|----------|------------|----------|----------| +| Management | 会话缓存 | session:* | 24h | 强依赖 | +| Management | 数据缓存 | data:* | 1h | 弱依赖 | +| IDM | 权限缓存 | permission:* | 12h | 强依赖 | + +#### 缓存配置 +\`\`\`yaml +# 分析缓存配置 +redis: + host: redis-service + port: 6379 + database: 0 + password: "" + pool_size: 10 +\`\`\` + +### 消息存储依赖 +#### 消息队列依赖 +| 服务名称 | 消息系统 | 主题/队列 | 用途 | 依赖级别 | +|---------|----------|-----------|------|----------| +| Management | Pulsar | user-events | 用户事件通知 | 强依赖 | +| Collector | Pulsar | data-events | 数据事件处理 | 强依赖 | +| Management | Pulsar | system-events | 系统事件通知 | 弱依赖 | + +#### 消息队列配置 +\`\`\`yaml +# 分析消息队列配置 +message_queue: + pulsar: + broker_url: pulsar://pulsar-service:6650 + producer: + send_timeout_ms: 30000 + batching_enabled: true + consumer: + subscription_name: app-subscription + receiver_queue_size: 1000 +\`\`\` + +## 配置依赖分析 + +### 环境配置依赖 +#### 共享配置项 +| 配置项 | 默认值 | 使用服务 | 描述 | +|--------|--------|----------|------| +| APP_ENV | development | 所有服务 | 应用环境 | +| LOG_LEVEL | info | 所有服务 | 日志级别 | +| DATABASE_HOST | localhost | 所有服务 | 数据库主机 | + +#### 服务特定配置 +| 服务名称 | 配置项 | 默认值 | 描述 | +|---------|--------|--------|------| +| Management | MANAGEMENT_PORT | 8080 | 管理服务端口 | +| Collector | COLLECTOR_PORT | 9164 | 收集服务端口 | +| IDM | IDM_PORT | 8005 | 认证服务端口 | + +### 动态配置依赖 +#### 配置中心依赖 +| 服务名称 | 配置中心 | 配置路径 | 刷新策略 | +|---------|----------|----------|----------| +| Management | Consul | config/management | 热刷新 | +| Collector | Consul | config/collector | 热刷新 | +| IDM | Consul | config/idm | 热刷新 | + +#### 配置依赖关系 +\`\`\`mermaid +graph LR + A[Management] --> B[Consul] + A --> C[PostgreSQL] + A --> D[Redis] + E[Collector] --> B + E --> C + E --> F[Pulsar] + G[IDM] --> B + G --> C + G --> D +\`\`\` + +## 接口依赖分析 + +### API接口依赖 +#### REST API依赖 +| 调用服务 | 被调用服务 | 接口路径 | HTTP方法 | 依赖级别 | +|---------|-----------|----------|----------|----------| +| Management | IDM | /api/v1/auth/login | POST | 强依赖 | +| Management | IDM | /api/v1/auth/validate | GET | 强依赖 | +| Management | Collector | /api/v1/data/status | GET | 弱依赖 | + +#### 接口版本依赖 +| 接口路径 | 版本 | 兼容性 | 升级策略 | +|----------|------|--------|----------| +| /api/v1/auth/* | v1 | 向后兼容 | 渐进式升级 | +| /api/v2/auth/* | v2 | 新版本 | 并行运行 | + +### WebSocket依赖 +#### WebSocket连接 +| 服务名称 | 连接端点 | 用途 | 连接数限制 | +|---------|----------|------|-----------| +| Management | /ws/notifications | 实时通知 | 1000 | +| Collector | /ws/data-stream | 数据流传输 | 500 | + +#### WebSocket配置 +\`\`\`yaml +# 分析WebSocket配置 +websocket: + management: + path: /ws/notifications + max_connections: 1000 + message_size_limit: 10MB + ping_interval: 30s +\`\`\` + +## 第三方服务依赖 + +### 外部API依赖 +#### 支付服务依赖 +| 服务名称 | 支付服务 | API端点 | 用途 | 依赖级别 | +|---------|----------|----------|------|----------| +| Management | Stripe | /api/v1/charges | 支付处理 | 强依赖 | +| Management | PayPal | /v2/payments | 支付处理 | 备选依赖 | + +#### 短信服务依赖 +| 服务名称 | 短信服务 | API端点 | 用途 | 依赖级别 | +|---------|----------|----------|------|----------| +| Management | Twilio | /2010-04-01/Accounts | 短信发送 | 强依赖 | +| Management | 阿里云短信 | /sms/send | 短信发送 | 备选依赖 | + +#### 邮件服务依赖 +| 服务名称 | 邮件服务 | API端点 | 用途 | 依赖级别 | +|---------|----------|----------|------|----------| +| Collector | SendGrid | /v3/mail/send | 邮件发送 | 强依赖 | +| Collector | AWS SES | /v1/email/send | 邮件发送 | 备选依赖 | + +### 云服务依赖 +#### 数据库服务依赖 +| 服务名称 | 云服务 | 服务类型 | 用途 | 依赖级别 | +|---------|--------|----------|------|----------| +| Management | AWS RDS | PostgreSQL | 主数据库 | 强依赖 | +| Collector | AWS RDS | PostgreSQL | 主数据库 | 强依赖 | + +#### 缓存服务依赖 +| 服务名称 | 云服务 | 服务类型 | 用途 | 依赖级别 | +|---------|--------|----------|------|----------| +| Management | AWS ElastiCache | Redis | 缓存服务 | 强依赖 | +| IDM | AWS ElastiCache | Redis | 缓存服务 | 强依赖 | + +## 基础设施依赖 + +### 容器编排依赖 +#### Kubernetes依赖 +| 服务名称 | K8s资源 | 命名空间 | 依赖级别 | +|---------|----------|----------|----------| +| Management | Deployment | default | 强依赖 | +| Management | Service | default | 强依赖 | +| Collector | Deployment | default | 强依赖 | +| Collector | Service | default | 强依赖 | + +#### Helm依赖 +| 服务名称 | Helm Chart | 版本 | 仓库 | 依赖级别 | +|---------|------------|------|------|----------| +| Management | management-chart | 1.0.0 | local | 强依赖 | +| Collector | collector-chart | 1.0.0 | local | 强依赖 | + +### 网络依赖 +#### 负载均衡依赖 +| 服务名称 | 负载均衡器 | 端口 | 路由规则 | 依赖级别 | +|---------|------------|------|----------|----------| +| Management | Nginx | 80 | /api/management/* | 强依赖 | +| Collector | Nginx | 80 | /api/collector/* | 强依赖 | +| IDM | Nginx | 80 | /api/idm/* | 强依赖 | + +#### 服务发现依赖 +| 服务名称 | 服务发现 | 注册方式 | 健康检查 | 依赖级别 | +|---------|----------|----------|----------|----------| +| Management | Consul | 自动注册 | HTTP检查 | 强依赖 | +| Collector | Consul | 自动注册 | HTTP检查 | 强依赖 | +| IDM | Consul | 自动注册 | HTTP检查 | 强依赖 | + +## 依赖风险评估 + +### 关键依赖识别 +#### 强依赖服务 +| 依赖服务 | 影响范围 | 故障影响 | 恢复策略 | +|---------|----------|----------|----------| +| PostgreSQL | 所有服务 | 数据丢失 | 主从切换 | +| Redis | Management, IDM | 缓存失效 | 降级处理 | +| Pulsar | Management, Collector | 消息丢失 | 消息重试 | + +#### 单点故障风险 +| 依赖项 | 风险等级 | 影响描述 | 解决方案 | +|--------|----------|----------|----------| +| PostgreSQL | 高 | 数据库故障导致所有服务不可用 | 主从复制、读写分离 | +| Redis | 中 | 缓存故障导致性能下降 | 多级缓存、降级策略 | +| Consul | 低 | 服务发现故障影响新服务注册 | 本地缓存、重试机制 | + +### 依赖优化建议 +#### 依赖解耦 +- {服务间解耦建议} +- {数据依赖优化建议} +- {配置依赖简化建议} + +#### 容错机制 +- {服务降级策略} +- {熔断机制配置} +- {重试策略优化} + +## 依赖管理策略 + +### 依赖版本管理 +#### 版本兼容性 +| 依赖服务 | 当前版本 | 兼容版本 | 升级策略 | +|---------|----------|----------|----------| +| PostgreSQL | 15 | 14, 15 | 渐进式升级 | +| Redis | 7.0 | 6.2, 7.0 | 版本兼容 | +| Pulsar | 2.11 | 2.10, 2.11 | 向后兼容 | + +#### 版本管理策略 +- **主版本**: 主版本升级需要充分测试 +- **次版本**: 次版本升级可以自动进行 +- **补丁版本**: 补丁版本升级可以热更新 + +### 依赖监控 +#### 健康检查 +| 依赖服务 | 检查方式 | 检查频率 | 超时时间 | +|---------|----------|----------|----------| +| PostgreSQL | TCP连接 | 30s | 5s | +| Redis | PING命令 | 30s | 3s | +| Pulsar | 主题检查 | 60s | 10s | + +#### 告警配置 +- **依赖服务不可用**: 立即告警 +- **响应时间过长**: 警告告警 +- **连接数过多**: 警告告警 + +## 总结 + +### 依赖关系总结 +- {关键依赖服务总结} +- {依赖风险评估总结} +- {优化建议总结} + +### 最佳实践 +- {依赖管理最佳实践} +- {容错机制最佳实践} +- {监控告警最佳实践} +\`\`\` + +## 特别注意事项 +1. 必须基于实际的代码和配置进行分析,不能虚构依赖关系 +2. 重点分析关键依赖和单点故障风险 +3. 关注依赖的版本兼容性和升级策略 +4. 识别依赖中的性能瓶颈和优化空间 +5. 提供实用的依赖管理建议和容错策略 + +## 输出文件命名 +\`${WIKI_OUTPUT_DIR}03_{PROJECT_NAME}_Service_Dependencies.md\` +注意:如果${WIKI_OUTPUT_DIR} 目录不存在,则创建。 + +## 示例输出特征 +基于项目的依赖分析特征: +- 详细的服务间调用关系表格 +- 清晰的数据依赖和配置依赖分析 +- 全面的第三方服务依赖评估 +- 实用的依赖风险评估和优化建议 +- 完整的依赖管理策略和监控方案` diff --git a/src/core/tools/helpers/wiki-prompts/subtasks/04_Data_Flow_Integration_Analysis.ts b/src/core/tools/helpers/wiki-prompts/subtasks/04_Data_Flow_Integration_Analysis.ts new file mode 100644 index 0000000000..608368b0af --- /dev/null +++ b/src/core/tools/helpers/wiki-prompts/subtasks/04_Data_Flow_Integration_Analysis.ts @@ -0,0 +1,588 @@ +import { WIKI_OUTPUT_DIR } from "./constants" + +export const DATA_FLOW_INTEGRATION_ANALYSIS_TEMPLATE = `# 数据流和集成深度分析 + +## 使用场景 +从代码仓库中分析数据在系统中的流动路径和集成方式,生成详细的数据流文档,包括数据流转、集成模式、数据一致性等。 + +## 输入要求 +- **完整代码仓库**: 项目的完整源代码 +- **数据模型**: 数据库模型和数据结构定义 +- **API接口**: 数据传输接口定义 +- **消息配置**: 消息队列和数据流配置 + +# 数据流和集成深度分析任务 + +## 任务描述 +请深度分析项目中的数据流动和集成方式,从数据流转路径、集成模式、数据一致性、数据安全等维度生成完整的数据流技术文档。 + +## 分析维度 + +### 1. 数据流路径分析 +#### 业务数据流 +\`\`\`mermaid +graph TB + A[用户输入] --> B[API网关] + B --> C[业务服务] + C --> D[数据验证] + D --> E[业务处理] + E --> F[数据存储] + F --> G[数据库] + F --> H[缓存] + E --> I[消息发送] + I --> J[消息队列] + J --> K[消费者服务] + K --> L[数据处理] + L --> M[结果存储] +\`\`\` + +#### 数据流转模式 +- **同步数据流**: 实时数据传输和处理 +- **异步数据流**: 基于消息队列的数据流 +- **批量数据流**: 批量数据处理和传输 +- **实时数据流**: 流式数据处理和分析 + +### 2. 数据集成模式分析 +#### API集成模式 +\`\`\`go +// 分析REST API数据集成 +// 识别请求响应数据流 +\`\`\` + +#### 消息集成模式 +\`\`\`go +// 分析消息队列数据集成 +// 识别发布订阅数据流 +\`\`\` + +#### 数据库集成模式 +- **主从复制**: 主数据库到从数据库的数据同步 +- **读写分离**: 读操作和写操作的数据分流 +- **分库分表**: 数据水平拆分和集成 +- **多数据源**: 多个数据源的数据集成 + +### 3. 数据格式和协议分析 +#### 数据格式 +- **JSON**: REST API数据交换格式 +- **Protobuf**: gRPC服务数据格式 +- **XML**: 配置和遗留系统数据格式 +- **Avro**: 消息队列数据格式 + +#### 传输协议 +- **HTTP/HTTPS**: Web服务数据传输 +- **gRPC**: 高性能RPC数据传输 +- **WebSocket**: 实时双向数据传输 +- **MQTT**: IoT设备数据传输 + +### 4. 数据一致性分析 +#### 事务一致性 +\`\`\`go +// 分析数据库事务 +// 识别ACID特性保证 +\`\`\` + +#### 最终一致性 +- **消息队列**: 异步消息的最终一致性 +- **事件溯源**: 基于事件的数据一致性 +- **补偿事务**: 失败操作的补偿机制 +- **定期对账**: 数据一致性检查和修复 + +### 5. 数据安全分析 +#### 数据加密 +- **传输加密**: SSL/TLS数据传输加密 +- **存储加密**: 数据库字段加密 +- **端到端加密**: 客户端到服务端加密 +- **密钥管理**: 加密密钥的生命周期管理 + +#### 数据脱敏 +- **敏感数据**: 个人信息、财务数据脱敏 +- **日志数据**: 日志中的敏感信息过滤 +- **监控数据**: 监控指标中的敏感信息处理 +- **备份数据**: 备份数据的加密和保护 + +### 6. 数据监控和分析 +#### 数据流监控 +- **流量监控**: 数据传输流量和频率监控 +- **延迟监控**: 数据传输延迟和性能监控 +- **错误监控**: 数据传输错误和异常监控 +- **一致性监控**: 数据一致性状态监控 + +#### 数据分析 +- **实时分析**: 流式数据的实时分析 +- **批量分析**: 历史数据的批量分析 +- **预测分析**: 基于历史数据的预测分析 +- **可视化分析**: 数据可视化展示和分析 + +## 输出格式要求 + +生成完整的数据流和集成分析文档: + +### 文档结构 +\`\`\`markdown +# {项目名称} 数据流和集成分析 + +## 数据流概览 + +### 数据流分类 +| 数据流类型 | 描述 | 涉及服务 | 传输方式 | +|-----------|------|----------|----------| +| 业务数据流 | 核心业务数据流转 | Management, IDM | HTTP/REST | +| 事件数据流 | 系统事件和通知 | 所有服务 | Message Queue | +| 日志数据流 | 系统日志和监控 | 所有服务 | File/Stream | +| 配置数据流 | 配置信息同步 | 所有服务 | Config Center | + +### 数据流架构图 +\`\`\`mermaid +graph TB + subgraph "数据源" + A[用户输入] + B[外部系统] + C[IoT设备] + end + + subgraph "接入层" + D[API网关] + E[WebSocket网关] + F[消息网关] + end + + subgraph "处理层" + G[Management服务] + H[Collector服务] + I[IDM服务] + end + + subgraph "存储层" + J[(PostgreSQL)] + K[(Redis)] + L[(Pulsar)] + M[(Elasticsearch)] + end + + subgraph "消费层" + N[数据分析服务] + O[报表服务] + P[通知服务] + end + + A --> D + B --> D + C --> F + D --> G + D --> H + D --> I + E --> G + F --> L + G --> J + G --> K + H --> J + H --> L + H --> M + I --> J + I --> K + L --> N + L --> O + L --> P + J --> N + M --> N +\`\`\` + +## 业务数据流分析 + +### 用户管理数据流 +#### 数据流转路径 +\`\`\`mermaid +sequenceDiagram + participant U as 用户 + participant API as API网关 + participant M as Management服务 + participant I as IDM服务 + participant DB as PostgreSQL + participant Cache as Redis + participant MQ as Pulsar + + U->>API: 用户注册请求 + API->>M: 转发注册请求 + M->>I: 验证用户信息 + I->>DB: 检查用户是否存在 + DB->>I: 返回检查结果 + I->>M: 返回验证结果 + M->>DB: 创建用户记录 + DB->>M: 返回创建结果 + M->>Cache: 缓存用户信息 + M->>MQ: 发送用户注册事件 + MQ->>P: 事件处理服务 + M->>API: 返回注册结果 + API->>U: 返回成功响应 +\`\`\` + +#### 数据格式定义 +**用户注册请求数据**: +\`\`\`json +{ + "username": "string", + "email": "string", + "password": "string", + "profile": { + "first_name": "string", + "last_name": "string", + "phone": "string" + } +} +\`\`\` + +**用户注册响应数据**: +\`\`\`json +{ + "user_id": "string", + "username": "string", + "email": "string", + "created_at": "timestamp", + "status": "active" +} +\`\`\` + +#### 数据处理逻辑 +- **数据验证**: 用户名格式、邮箱格式、密码强度验证 +- **数据转换**: 密码加密、数据格式标准化 +- **数据存储**: 用户信息存储到数据库,缓存到Redis +- **事件发布**: 发布用户注册事件到消息队列 + +### 数据收集数据流 +#### 数据流转路径 +\`\`\`mermaid +graph LR + A[数据源] --> B[数据收集器] + B --> C[数据验证] + C --> D[数据标准化] + D --> E[数据存储] + E --> F[PostgreSQL] + E --> G[Elasticsearch] + E --> H[Pulsar] + H --> I[数据处理服务] + I --> J[数据分析] + I --> K[报表生成] +\`\`\` + +#### 数据格式定义 +**原始数据格式**: +\`\`\`json +{ + "source_id": "string", + "timestamp": "timestamp", + "data_type": "string", + "payload": { + "metric_name": "string", + "metric_value": "number", + "tags": { + "host": "string", + "service": "string" + } + } +} +\`\`\` + +**标准化数据格式**: +\`\`\`json +{ + "id": "uuid", + "source_id": "string", + "timestamp": "timestamp", + "metric_name": "string", + "metric_value": "number", + "tags": "object", + "processed_at": "timestamp", + "status": "processed" +} +\`\`\` + +## 集成模式分析 + +### API集成模式 +#### REST API集成 +| API端点 | HTTP方法 | 数据格式 | 用途 | 集成服务 | +|---------|----------|----------|------|----------| +| /api/v1/users | POST | JSON | 用户创建 | Management, IDM | +| /api/v1/data | POST | JSON | 数据提交 | Management, Collector | +| /api/v1/auth | POST | JSON | 身份验证 | Management, IDM | + +#### API数据流特征 +- **同步处理**: 请求-响应模式,实时处理 +- **数据验证**: 请求参数验证和格式检查 +- **错误处理**: 统一错误码和错误信息 +- **性能优化**: 响应缓存和连接池优化 + +### 消息集成模式 +#### 发布订阅模式 +| 主题(Topic) | 发布者 | 订阅者 | 消息格式 | 用途 | +|------------|--------|--------|----------|------| +| user-events | Management, IDM | 所有服务 | JSON | 用户事件通知 | +| data-events | Collector | 数据分析服务 | JSON | 数据事件处理 | +| system-events | 所有服务 | 监控服务 | JSON | 系统事件监控 | + +#### 消息数据流特征 +- **异步处理**: 发布订阅模式,异步处理 +- **消息持久化**: 消息持久化存储,保证不丢失 +- **顺序保证**: 消息顺序处理保证 +- **重试机制**: 消息处理失败重试机制 + +### 数据库集成模式 +#### 主从复制集成 +| 数据库 | 角色 | 复制方式 | 延迟 | 用途 | +|--------|------|----------|------|------| +| PostgreSQL主库 | 主库 | 同步复制 | <1s | 写操作 | +| PostgreSQL从库 | 从库 | 异步复制 | <5s | 读操作 | +| Redis主库 | 主库 | 同步复制 | <1s | 写操作 | +| Redis从库 | 从库 | 异步复制 | <3s | 读操作 | + +#### 数据分片集成 +| 分片策略 | 分片键 | 分片数量 | 数据分布 | 用途 | +|----------|--------|----------|----------|------| +| 用户ID哈希 | user_id | 16个分片 | 均匀分布 | 用户数据 | +| 时间范围 | timestamp | 12个分片 | 时间分布 | 日志数据 | +| 地理位置 | region | 8个分片 | 地理分布 | 区域数据 | + +## 数据一致性分析 + +### 事务一致性 +#### 数据库事务 +\`\`\`go +// 分析数据库事务使用 +func CreateUser(user *User) error { + tx := db.Begin() + defer func() { + if r := recover(); r != nil { + tx.Rollback() + } + }() + + // 创建用户记录 + if err := tx.Create(user).Error; err != nil { + tx.Rollback() + return err + } + + // 创建用户配置 + config := &UserConfig{UserID: user.ID} + if err := tx.Create(config).Error; err != nil { + tx.Rollback() + return err + } + + return tx.Commit().Error +} +\`\`\` + +#### 事务特性保证 +- **原子性**: 事务中的操作要么全部成功,要么全部失败 +- **一致性**: 事务执行前后数据保持一致状态 +- **隔离性**: 并发事务之间相互隔离 +- **持久性**: 事务提交后数据持久化存储 + +### 最终一致性 +#### 事件溯源一致性 +\`\`\`mermaid +graph TB + A[业务操作] --> B[生成事件] + B --> C[存储事件] + C --> D[发布事件] + D --> E[事件处理] + E --> F[更新状态] + F --> G[状态同步] +\`\`\` + +#### 补偿事务机制 +- **正向操作**: 正常的业务操作流程 +- **补偿操作**: 失败时的补偿和回滚操作 +- **重试策略**: 失败操作的重试机制 +- **超时处理**: 操作超时的处理机制 + +## 数据安全分析 + +### 数据加密 +#### 传输加密 +| 加密方式 | 加密算法 | 密钥长度 | 应用场景 | +|----------|----------|----------|----------| +| HTTPS | TLS 1.3 | 256位 | API通信 | +| gRPC | TLS 1.3 | 256位 | 服务间通信 | +| WebSocket | TLS 1.3 | 256位 | 实时通信 | + +#### 存储加密 +| 数据类型 | 加密方式 | 加密算法 | 密钥管理 | +|----------|----------|----------|----------| +| 密码 | 哈希加密 | bcrypt | 单向哈希 | +| 敏感信息 | 对称加密 | AES-256 | 密钥管理系统 | +| 备份数据 | 对称加密 | AES-256 | 备份密钥管理 | + +### 数据脱敏 +#### 脱敏策略 +| 数据类型 | 脱敏方式 | 脱敏规则 | 应用场景 | +|----------|----------|----------|----------| +| 手机号 | 部分遮蔽 | 138****1234 | 日志、显示 | +| 邮箱 | 部分遮蔽 | user***@domain.com | 日志、显示 | +| 身份证 | 部分遮蔽 | 110****1234 | 日志、显示 | +| 银行卡 | 部分遮蔽 | 6225****1234 | 日志、显示 | + +#### 脱敏实现 +\`\`\`go +// 数据脱敏函数示例 +func MaskPhone(phone string) string { + if len(phone) != 11 { + return phone + } + return phone[:3] + "****" + phone[7:] +} + +func MaskEmail(email string) string { + parts := strings.Split(email, "@") + if len(parts) != 2 { + return email + } + username := parts[0] + domain := parts[1] + if len(username) <= 2 { + return username + "***@" + domain + } + return username[:2] + "***@" + domain +} +\`\`\` + +## 数据监控和分析 + +### 数据流监控 +#### 监控指标 +| 指标类型 | 指标名称 | 阈值 | 告警级别 | +|----------|----------|------|----------| +| 流量监控 | API请求量 | >10000 QPS | 警告 | +| 流量监控 | 消息处理量 | >5000 msg/s | 警告 | +| 延迟监控 | API响应时间 | >1000ms | 警告 | +| 延迟监控 | 消息处理延迟 | >5000ms | 严重 | +| 错误监控 | API错误率 | >5% | 警告 | +| 错误监控 | 消息处理失败率 | >10% | 严重 | + +#### 监控实现 +\`\`\`go +// 数据流监控示例 +type DataFlowMonitor struct { + requestCount prometheus.Counter + responseTime prometheus.Histogram + errorCount prometheus.Counter + messageCount prometheus.Counter + processTime prometheus.Histogram +} + +func (m *DataFlowMonitor) RecordRequest(duration time.Duration) { + m.requestCount.Inc() + m.responseTime.Observe(duration.Seconds()) +} + +func (m *DataFlowMonitor) RecordError() { + m.errorCount.Inc() +} + +func (m *DataFlowMonitor) RecordMessage(duration time.Duration) { + m.messageCount.Inc() + m.processTime.Observe(duration.Seconds()) +} +\`\`\` + +### 数据分析 +#### 实时分析 +- **流式处理**: 实时数据流处理和分析 +- **复杂事件处理**: 复杂事件的实时识别和处理 +- **实时聚合**: 实时数据聚合和统计 +- **实时告警**: 实时异常检测和告警 + +#### 批量分析 +- **历史数据分析**: 历史数据的批量分析 +- **趋势分析**: 数据趋势和模式分析 +- **预测分析**: 基于历史数据的预测分析 +- **报表生成**: 定期报表生成和分发 + +## 性能优化 + +### 数据流优化 +#### 缓存策略 +| 缓存类型 | 缓存数据 | 过期时间 | 缓存策略 | +|----------|----------|----------|----------| +| 用户信息 | 用户基本资料 | 30分钟 | 主动刷新 | +| 配置信息 | 系统配置 | 1小时 | 定时刷新 | +| 统计数据 | 业务统计 | 5分钟 | 定时刷新 | +| 会话信息 | 用户会话 | 24小时 | 惰性过期 | + +#### 批量处理 +- **批量插入**: 数据批量插入优化 +- **批量更新**: 数据批量更新优化 +- **批量删除**: 数据批量删除优化 +- **批量查询**: 数据批量查询优化 + +### 网络优化 +#### 连接池优化 +| 连接类型 | 池大小 | 超时时间 | 重用策略 | +|----------|--------|----------|----------| +| 数据库连接 | 100 | 30秒 | 连接复用 | +| Redis连接 | 50 | 10秒 | 连接复用 | +| HTTP连接 | 200 | 60秒 | 连接复用 | + +#### 压缩优化 +- **数据压缩**: 传输数据压缩优化 +- **协议优化**: 高效协议选择和优化 +- **序列化优化**: 高效序列化格式选择 + +## 故障处理 + +### 数据流故障 +#### 故障类型 +| 故障类型 | 故障现象 | 影响范围 | 恢复策略 | +|----------|----------|----------|----------| +| 网络故障 | 数据传输中断 | 部分服务 | 重试机制 | +| 数据库故障 | 数据存储失败 | 所有服务 | 主从切换 | +| 消息队列故障 | 消息传输失败 | 异步服务 | 消息重试 | +| 缓存故障 | 缓存访问失败 | 性能下降 | 降级处理 | + +#### 故障恢复 +- **自动重试**: 失败操作的自动重试 +- **降级处理**: 核心功能降级处理 +- **熔断保护**: 服务熔断和快速失败 +- **数据恢复**: 数据备份和恢复机制 + +### 数据一致性故障 +#### 一致性检查 +- **定期对账**: 数据一致性定期检查 +- **差异修复**: 数据差异自动修复 +- **监控告警**: 一致性异常监控告警 +- **人工干预**: 严重问题人工干预处理 + +## 总结 + +### 数据流特点 +- {数据流主要特点总结} +- {集成模式应用总结} +- {一致性保证总结} +- {安全措施总结} + +### 优化建议 +- {数据流优化建议} +- {性能提升建议} +- {安全加强建议} +- {监控改进建议} +\`\`\` + +## 特别注意事项 +1. 必须基于实际的代码和配置进行分析,不能虚构数据流 +2. 重点分析关键数据路径和集成模式 +3. 关注数据一致性和安全性保证 +4. 识别数据流中的性能瓶颈和优化空间 +5. 提供实用的故障处理和恢复策略 + +## 输出文件命名 +\`${WIKI_OUTPUT_DIR}04_{PROJECT_NAME}_Data_Flow_Integration.md\` +注意:如果${WIKI_OUTPUT_DIR} 目录不存在,则创建。 + +## 示例输出特征 +基于项目的数据流分析特征: +- 详细的数据流转路径和时序图 +- 完整的集成模式和应用场景分析 +- 全面的数据一致性保证机制 +- 实用的数据安全和加密策略 +- 具体的性能优化和故障处理方案` diff --git a/src/core/tools/helpers/wiki-prompts/subtasks/05_Service_Analysis_Template.ts b/src/core/tools/helpers/wiki-prompts/subtasks/05_Service_Analysis_Template.ts new file mode 100644 index 0000000000..967f767bdd --- /dev/null +++ b/src/core/tools/helpers/wiki-prompts/subtasks/05_Service_Analysis_Template.ts @@ -0,0 +1,956 @@ +import { WIKI_OUTPUT_DIR } from "./constants" + +export const SERVICE_ANALYSIS_TEMPLATE = `# 服务模块深度分析 + +## 使用场景 +从代码仓库中分析各个服务模块的架构、功能、接口、依赖关系等,生成详细的服务模块技术文档。 + +## 输入要求 +- **完整代码仓库**: 项目的完整源代码 +- **服务配置**: 各服务的配置文件 +- **接口定义**: 服务间接口定义 +- **依赖关系**: 服务间依赖关系配置 + +# 服务模块深度分析任务 + +## 任务描述 +请深度分析项目中的各个服务模块,从服务架构、功能特性、接口设计、依赖关系、性能特性等维度生成完整的服务模块技术文档。 + +## 分析维度 + +### 1. 服务架构分析 +#### 服务分层架构 +\`\`\`mermaid +graph TB + subgraph "接入层" + A[API网关] + B[WebSocket网关] + C[负载均衡器] + end + + subgraph "业务层" + D[Management服务] + E[Collector服务] + F[IDM服务] + end + + subgraph "数据层" + G[数据访问层] + H[缓存层] + I[消息层] + end + + subgraph "基础设施层" + J[数据库] + K[缓存] + L[消息队列] + M[监控] + end + + A --> D + A --> E + A --> F + B --> D + C --> D + C --> E + C --> F + D --> G + D --> H + D --> I + E --> G + E --> H + E --> I + F --> G + F --> H + F --> I + G --> J + H --> K + I --> L + J --> M + K --> M + L --> M +\`\`\` + +#### 服务架构模式 +- **微服务架构**: 服务独立部署和扩展 +- **分层架构**: 清晰的层次结构 +- **事件驱动架构**: 基于事件的异步通信 +- **API网关模式**: 统一的API入口 + +### 2. 服务功能分析 +#### 核心服务功能 +| 服务名称 | 核心功能 | 业务价值 | 技术特点 | +|----------|----------|----------|----------| +| Management | 用户管理、数据管理 | 核心业务支撑 | REST API、事务处理 | +| Collector | 数据收集、处理 | 数据采集分析 | 高并发、流式处理 | +| IDM | 身份认证、授权 | 安全保障 | OAuth2、JWT | + +#### 服务功能模块 +\`\`\`go +// Management服务功能模块 +type ManagementService struct { + userModule *UserModule + dataModule *DataModule + configModule *ConfigModule + auditModule *AuditModule +} + +// Collector服务功能模块 +type CollectorService struct { + collectModule *CollectModule + processModule *ProcessModule + storageModule *StorageModule + monitorModule *MonitorModule +} + +// IDM服务功能模块 +type IDMService struct { + authModule *AuthModule + userModule *UserModule + roleModule *RoleModule + permissionModule *PermissionModule +} +\`\`\` + +### 3. 服务接口分析 +#### REST API接口 +| 服务 | 接口路径 | HTTP方法 | 功能描述 | 参数 | +|------|----------|----------|----------|------| +| Management | /api/v1/users | GET | 获取用户列表 | page, size | +| Management | /api/v1/users | POST | 创建用户 | user data | +| Management | /api/v1/users/{id} | PUT | 更新用户 | user data | +| Management | /api/v1/users/{id} | DELETE | 删除用户 | - | +| Collector | /api/v1/data | POST | 提交数据 | data payload | +| Collector | /api/v1/data/batch | POST | 批量提交数据 | data array | +| IDM | /api/v1/auth/login | POST | 用户登录 | credentials | +| IDM | /api/v1/auth/logout | POST | 用户登出 | - | +| IDM | /api/v1/auth/refresh | POST | 刷新令牌 | refresh token | + +#### gRPC接口 +\`\`\`go +// Management服务gRPC接口 +service ManagementService { + rpc GetUser(GetUserRequest) returns (GetUserResponse); + rpc CreateUser(CreateUserRequest) returns (CreateUserResponse); + rpc UpdateUser(UpdateUserRequest) returns (UpdateUserResponse); + rpc DeleteUser(DeleteUserRequest) returns (DeleteUserResponse); +} + +// Collector服务gRPC接口 +service CollectorService { + rpc CollectData(CollectDataRequest) returns (CollectDataResponse); + rpc ProcessData(ProcessDataRequest) returns (ProcessDataResponse); + rpc GetMetrics(GetMetricsRequest) returns (GetMetricsResponse); +} + +// IDM服务gRPC接口 +service IDMService { + rpc Authenticate(AuthenticateRequest) returns (AuthenticateResponse); + rpc Authorize(AuthorizeRequest) returns (AuthorizeResponse); + rpc RefreshToken(RefreshTokenRequest) returns (RefreshTokenResponse); +} +\`\`\` + +#### WebSocket接口 +| 服务 | 事件类型 | 数据格式 | 用途 | +|------|----------|----------|------| +| Management | user.created | JSON | 用户创建通知 | +| Management | user.updated | JSON | 用户更新通知 | +| Management | user.deleted | JSON | 用户删除通知 | +| Collector | data.received | JSON | 数据接收通知 | +| Collector | data.processed | JSON | 数据处理完成 | +| IDM | auth.login | JSON | 用户登录事件 | +| IDM | auth.logout | JSON | 用户登出事件 | + +### 4. 服务依赖分析 +#### 服务间依赖关系 +\`\`\`mermaid +graph TB + subgraph "Management服务" + M1[用户管理] + M2[数据管理] + M3[配置管理] + end + + subgraph "Collector服务" + C1[数据收集] + C2[数据处理] + C3[数据存储] + end + + subgraph "IDM服务" + I1[身份认证] + I2[用户管理] + I3[权限管理] + end + + subgraph "外部依赖" + D1[(PostgreSQL)] + D2[(Redis)] + D3[(Pulsar)] + D4[(Elasticsearch)] + end + + M1 --> I1 + M1 --> I2 + M2 --> C1 + M2 --> C2 + M3 --> D2 + C1 --> D3 + C2 --> D4 + C3 --> D1 + I1 --> D1 + I2 --> D1 + I3 --> D2 + M1 --> D1 + M2 --> D1 +\`\`\` + +#### 依赖服务详情 +| 服务 | 依赖服务 | 依赖类型 | 依赖方式 | 故障影响 | +|------|----------|----------|----------|----------| +| Management | IDM | 强依赖 | 同步调用 | 无法进行用户操作 | +| Management | PostgreSQL | 强依赖 | 数据存储 | 无法存储数据 | +| Management | Redis | 弱依赖 | 缓存 | 性能下降 | +| Collector | PostgreSQL | 强依赖 | 数据存储 | 无法存储数据 | +| Collector | Pulsar | 强依赖 | 消息队列 | 无法处理消息 | +| Collector | Elasticsearch | 弱依赖 | 搜索 | 搜索功能不可用 | +| IDM | PostgreSQL | 强依赖 | 数据存储 | 无法验证用户 | +| IDM | Redis | 弱依赖 | 缓存 | 性能下降 | + +### 5. 服务配置分析 +#### 服务配置结构 +\`\`\`yaml +# Management服务配置 +management: + server: + host: "0.0.0.0" + port: 8080 + read_timeout: "30s" + write_timeout: "30s" + database: + host: "localhost" + port: 5432 + database: "management" + username: "management" + password: "password" + max_connections: 100 + max_idle_connections: 10 + cache: + host: "localhost" + port: 6379 + password: "" + db: 0 + pool_size: 10 + auth: + jwt_secret: "secret" + jwt_expire: "24h" + refresh_expire: "168h" + +# Collector服务配置 +collector: + server: + host: "0.0.0.0" + port: 8081 + read_timeout: "30s" + write_timeout: "30s" + database: + host: "localhost" + port: 5432 + database: "collector" + username: "collector" + password: "password" + max_connections: 100 + max_idle_connections: 10 + message_queue: + host: "localhost" + port: 6650 + topic: "data-events" + subscription: "collector-sub" + elasticsearch: + hosts: ["localhost:9200"] + index: "collected-data" + username: "" + password: "" + +# IDM服务配置 +idm: + server: + host: "0.0.0.0" + port: 8082 + read_timeout: "30s" + write_timeout: "30s" + database: + host: "localhost" + port: 5432 + database: "idm" + username: "idm" + password: "password" + max_connections: 100 + max_idle_connections: 10 + cache: + host: "localhost" + port: 6379 + password: "" + db: 1 + pool_size: 10 + oauth: + client_id: "client-id" + client_secret: "client-secret" + redirect_uri: "http://localhost:8080/callback" +\`\`\` + +#### 配置管理策略 +- **环境配置**: 开发、测试、生产环境配置分离 +- **配置中心**: 集中配置管理和动态更新 +- **配置加密**: 敏感配置信息加密存储 +- **配置验证**: 配置格式和有效性验证 + +### 6. 服务性能分析 +#### 性能指标 +| 服务 | 指标类型 | 指标名称 | 目标值 | 当前值 | +|------|----------|----------|--------|--------| +| Management | 响应时间 | API平均响应时间 | <100ms | 85ms | +| Management | 吞吐量 | QPS | 1000 | 1200 | +| Management | 错误率 | API错误率 | <1% | 0.5% | +| Collector | 响应时间 | 数据处理时间 | <50ms | 45ms | +| Collector | 吞吐量 | 数据处理量 | 5000/s | 4800/s | +| Collector | 错误率 | 处理错误率 | <0.1% | 0.05% | +| IDM | 响应时间 | 认证响应时间 | <200ms | 180ms | +| IDM | 吞吐量 | 认证请求量 | 500/s | 450/s | +| IDM | 错误率 | 认证错误率 | <0.5% | 0.3% | + +#### 性能优化策略 +- **缓存优化**: 热点数据缓存和缓存策略优化 +- **数据库优化**: 索引优化、查询优化、连接池优化 +- **并发优化**: 协程池、连接池、资源池优化 +- **网络优化**: 协议优化、压缩优化、负载均衡优化 + +### 7. 服务监控分析 +#### 监控指标 +| 服务 | 监控类型 | 指标名称 | 阈值 | 告警级别 | +|------|----------|----------|------|----------| +| Management | 系统监控 | CPU使用率 | >80% | 警告 | +| Management | 系统监控 | 内存使用率 | >85% | 警告 | +| Management | 系统监控 | 磁盘使用率 | >90% | 严重 | +| Management | 业务监控 | API请求量 | >10000 QPS | 警告 | +| Management | 业务监控 | API错误率 | >5% | 警告 | +| Collector | 系统监控 | CPU使用率 | >80% | 警告 | +| Collector | 系统监控 | 内存使用率 | >85% | 警告 | +| Collector | 业务监控 | 数据处理量 | >5000/s | 警告 | +| Collector | 业务监控 | 处理延迟 | >100ms | 警告 | +| IDM | 系统监控 | CPU使用率 | >80% | 警告 | +| IDM | 系统监控 | 内存使用率 | >85% | 警告 | +| IDM | 业务监控 | 认证请求量 | >500/s | 警告 | +| IDM | 业务监控 | 认证失败率 | >10% | 警告 | + +#### 监控实现 +\`\`\`go +// 服务监控实现示例 +type ServiceMonitor struct { + cpuUsage prometheus.Gauge + memoryUsage prometheus.Gauge + requestCount prometheus.Counter + errorCount prometheus.Counter + responseTime prometheus.Histogram +} + +func (m *ServiceMonitor) RecordSystemMetrics() { + cpuPercent := getCPUUsage() + memoryPercent := getMemoryUsage() + + m.cpuUsage.Set(cpuPercent) + m.memoryUsage.Set(memoryPercent) +} + +func (m *ServiceMonitor) RecordRequest(duration time.Duration) { + m.requestCount.Inc() + m.responseTime.Observe(duration.Seconds()) +} + +func (m *ServiceMonitor) RecordError() { + m.errorCount.Inc() +} +\`\`\` + +### 8. 服务安全分析 +#### 安全措施 +| 服务 | 安全类型 | 安全措施 | 实现方式 | +|------|----------|----------|----------| +| Management | 身份认证 | JWT令牌认证 | 中间件拦截 | +| Management | 权限控制 | RBAC权限控制 | 权限中间件 | +| Management | 数据加密 | 敏感数据加密 | AES加密 | +| Management | 输入验证 | 参数验证 | 验证中间件 | +| Collector | 身份认证 | API密钥认证 | 密钥验证 | +| Collector | 数据验证 | 数据格式验证 | Schema验证 | +| Collector | 限流保护 | 请求限流 | 限流中间件 | +| IDM | 身份认证 | OAuth2认证 | OAuth2流程 | +| IDM | 密码安全 | 密码哈希 | bcrypt哈希 | +| IDM | 会话管理 | 会话令牌 | JWT令牌 | + +#### 安全策略 +- **认证策略**: 多因素认证、单点登录 +- **授权策略**: 基于角色的访问控制 +- **加密策略**: 传输加密、存储加密 +- **审计策略**: 操作审计、日志记录 + +## 输出格式要求 + +生成完整的服务模块分析文档: + +### 文档结构 +\`\`\`markdown +# {项目名称} 服务模块分析 + +## 服务架构概览 + +### 服务分层架构 +\`\`\`mermaid +graph TB + subgraph "接入层" + A[API网关] + B[WebSocket网关] + C[负载均衡器] + end + + subgraph "业务层" + D[Management服务] + E[Collector服务] + F[IDM服务] + end + + subgraph "数据层" + G[数据访问层] + H[缓存层] + I[消息层] + end + + subgraph "基础设施层" + J[数据库] + K[缓存] + L[消息队列] + M[监控] + end + + A --> D + A --> E + A --> F + B --> D + C --> D + C --> E + C --> F + D --> G + D --> H + D --> I + E --> G + E --> H + E --> I + F --> G + F --> H + F --> I + G --> J + H --> K + I --> L + J --> M + K --> M + L --> M +\`\`\` + +### 服务架构特点 +- **微服务架构**: 服务独立部署和扩展 +- **分层架构**: 清晰的层次结构 +- **事件驱动架构**: 基于事件的异步通信 +- **API网关模式**: 统一的API入口 + +## Management服务分析 + +### 服务概述 +- **服务名称**: Management +- **服务描述**: 用户管理和数据管理核心服务 +- **技术栈**: Go, Gin, GORM, PostgreSQL, Redis +- **部署方式**: Docker容器化部署 + +### 核心功能模块 +\`\`\`go +type ManagementService struct { + userModule *UserModule + dataModule *DataModule + configModule *ConfigModule + auditModule *AuditModule +} + +// 用户管理模块 +type UserModule struct { + userRepo *UserRepository + userCache *UserCache + userValidator *UserValidator +} + +// 数据管理模块 +type DataModule struct { + dataRepo *DataRepository + dataProcessor *DataProcessor + dataValidator *DataValidator +} + +// 配置管理模块 +type ConfigModule struct { + configRepo *ConfigRepository + configCache *ConfigCache + configSync *ConfigSync +} + +// 审计模块 +type AuditModule struct { + auditRepo *AuditRepository + auditLogger *AuditLogger +} +\`\`\` + +### REST API接口 +| 接口路径 | HTTP方法 | 功能描述 | 参数 | 返回值 | +|----------|----------|----------|------|--------| +| /api/v1/users | GET | 获取用户列表 | page, size, filter | UserListResponse | +| /api/v1/users | POST | 创建用户 | CreateUserRequest | UserResponse | +| /api/v1/users/{id} | GET | 获取用户详情 | - | UserResponse | +| /api/v1/users/{id} | PUT | 更新用户 | UpdateUserRequest | UserResponse | +| /api/v1/users/{id} | DELETE | 删除用户 | - | DeleteResponse | +| /api/v1/data | POST | 提交数据 | SubmitDataRequest | DataResponse | +| /api/v1/data/{id} | GET | 获取数据详情 | - | DataResponse | +| /api/v1/data/{id} | PUT | 更新数据 | UpdateDataRequest | DataResponse | +| /api/v1/data/{id} | DELETE | 删除数据 | - | DeleteResponse | + +### 数据模型 +\`\`\`go +// 用户模型 +type User struct { + ID uuid.UUID \`json:"id" gorm:"primary_key"\` + Username string \`json:"username" gorm:"unique;not null"\` + Email string \`json:"email" gorm:"unique;not null"\` + Password string \`json:"-" gorm:"not null"\` + FirstName string \`json:"first_name"\` + LastName string \`json:"last_name"\` + Phone string \`json:"phone"\` + Status string \`json:"status" gorm:"default:'active'\` + CreatedAt time.Time \`json:"created_at"\` + UpdatedAt time.Time \`json:"updated_at"\` + DeletedAt *time.Time \`json:"deleted_at"\` +} + +// 数据模型 +type Data struct { + ID uuid.UUID \`json:"id" gorm:"primary_key"\` + UserID uuid.UUID \`json:"user_id" gorm:"not null"\` + Type string \`json:"type" gorm:"not null"\` + Title string \`json:"title" gorm:"not null"\` + Content string \`json:"content" gorm:"type:text"\` + Metadata JSON \`json:"metadata" gorm:"type:jsonb"\` + Status string \`json:"status" gorm:"default:'active'\` + CreatedAt time.Time \`json:"created_at"\` + UpdatedAt time.Time \`json:"updated_at"\` + DeletedAt *time.Time \`json:"deleted_at"\` +} +\`\`\` + +### 服务依赖关系 +\`\`\`mermaid +graph TB + subgraph "Management服务" + M1[用户管理] + M2[数据管理] + M3[配置管理] + M4[审计模块] + end + + subgraph "外部服务" + I1[IDM服务] + D1[(PostgreSQL)] + D2[(Redis)] + D3[(Pulsar)] + end + + M1 --> I1 + M1 --> D1 + M1 --> D2 + M2 --> D1 + M2 --> D2 + M2 --> D3 + M3 --> D2 + M4 --> D1 +\`\`\` + +### 性能特性 +| 指标类型 | 指标名称 | 目标值 | 当前值 | 状态 | +|----------|----------|--------|--------|------| +| 响应时间 | API平均响应时间 | <100ms | 85ms | 正常 | +| 吞吐量 | QPS | 1000 | 1200 | 正常 | +| 错误率 | API错误率 | <1% | 0.5% | 正常 | +| 并发数 | 最大并发连接数 | 1000 | 800 | 正常 | +| 内存使用 | 内存使用率 | <80% | 65% | 正常 | +| CPU使用 | CPU使用率 | <70% | 45% | 正常 | + +### 监控指标 +- **系统监控**: CPU使用率、内存使用率、磁盘使用率、网络流量 +- **业务监控**: API请求量、响应时间、错误率、并发数 +- **数据库监控**: 连接数、查询性能、慢查询、锁等待 +- **缓存监控**: 缓存命中率、内存使用率、键数量 + +## Collector服务分析 + +### 服务概述 +- **服务名称**: Collector +- **服务描述**: 数据收集和处理服务 +- **技术栈**: Go, Gin, GORM, PostgreSQL, Pulsar, Elasticsearch +- **部署方式**: Docker容器化部署 + +### 核心功能模块 +\`\`\`go +type CollectorService struct { + collectModule *CollectModule + processModule *ProcessModule + storageModule *StorageModule + monitorModule *MonitorModule +} + +// 数据收集模块 +type CollectModule struct { + dataReceiver *DataReceiver + dataValidator *DataValidator + dataBuffer *DataBuffer +} + +// 数据处理模块 +type ProcessModule struct { + dataProcessor *DataProcessor + dataEnricher *DataEnricher + dataNormalizer *DataNormalizer +} + +// 数据存储模块 +type StorageModule struct { + dataStorage *DataStorage + indexStorage *IndexStorage + backupStorage *BackupStorage +} + +// 监控模块 +type MonitorModule struct { + metricsCollector *MetricsCollector + alertManager *AlertManager + healthChecker *HealthChecker +} +\`\`\` + +### REST API接口 +| 接口路径 | HTTP方法 | 功能描述 | 参数 | 返回值 | +|----------|----------|----------|------|--------| +| /api/v1/data | POST | 提交数据 | SubmitDataRequest | DataResponse | +| /api/v1/data/batch | POST | 批量提交数据 | BatchSubmitRequest | BatchResponse | +| /api/v1/data/{id} | GET | 获取数据详情 | - | DataResponse | +| /api/v1/data/search | POST | 搜索数据 | SearchRequest | SearchResponse | +| /api/v1/metrics | GET | 获取指标 | - | MetricsResponse | +| /api/v1/health | GET | 健康检查 | - | HealthResponse | + +### 消息队列接口 +| 主题(Topic) | 消息类型 | 数据格式 | 用途 | +|------------|----------|----------|------| +| data-events | data.received | JSON | 数据接收事件 | +| data-events | data.processed | JSON | 数据处理完成 | +| data-events | data.stored | JSON | 数据存储完成 | +| system-events | health.check | JSON | 健康检查事件 | +| system-events | metrics.update | JSON | 指标更新事件 | + +### 数据处理流程 +\`\`\`mermaid +graph TB + A[数据接收] --> B[数据验证] + B --> C[数据标准化] + C --> D[数据丰富] + D --> E[数据存储] + E --> F[索引构建] + F --> G[事件发布] + G --> H[监控更新] + + subgraph "数据验证" + B1[格式验证] + B2[完整性验证] + B3[业务规则验证] + end + + subgraph "数据标准化" + C1[格式转换] + C2[单位统一] + C3[时间标准化] + end + + subgraph "数据丰富" + D1[元数据添加] + D2[地理位置解析] + D3[标签分类] + end + + subgraph "数据存储" + E1[PostgreSQL存储] + E2[Elasticsearch索引] + E3[备份存储] + end + + B --> B1 + B --> B2 + B --> B3 + C --> C1 + C --> C2 + C --> C3 + D --> D1 + D --> D2 + D --> D3 + E --> E1 + E --> E2 + E --> E3 +\`\`\` + +### 性能特性 +| 指标类型 | 指标名称 | 目标值 | 当前值 | 状态 | +|----------|----------|--------|--------|------| +| 响应时间 | 数据处理时间 | <50ms | 45ms | 正常 | +| 吞吐量 | 数据处理量 | 5000/s | 4800/s | 正常 | +| 错误率 | 处理错误率 | <0.1% | 0.05% | 正常 | +| 并发数 | 最大并发处理数 | 10000 | 8500 | 正常 | +| 内存使用 | 内存使用率 | <80% | 70% | 正常 | +| CPU使用 | CPU使用率 | <70% | 55% | 正常 | + +## IDM服务分析 + +### 服务概述 +- **服务名称**: IDM +- **服务描述**: 身份认证和权限管理服务 +- **技术栈**: Go, Gin, GORM, PostgreSQL, Redis, OAuth2 +- **部署方式**: Docker容器化部署 + +### 核心功能模块 +\`\`\`go +type IDMService struct { + authModule *AuthModule + userModule *UserModule + roleModule *RoleModule + permissionModule *PermissionModule +} + +// 认证模块 +type AuthModule struct { + authProvider *AuthProvider + tokenManager *TokenManager + passwordHasher *PasswordHasher +} + +// 用户模块 +type UserModule struct { + userRepo *UserRepository + userCache *UserCache + userValidator *UserValidator +} + +// 角色模块 +type RoleModule struct { + roleRepo *RoleRepository + roleCache *RoleCache + roleValidator *RoleValidator +} + +// 权限模块 +type PermissionModule struct { + permissionRepo *PermissionRepository + permissionCache *PermissionCache + permissionChecker *PermissionChecker +} +\`\`\` + +### REST API接口 +| 接口路径 | HTTP方法 | 功能描述 | 参数 | 返回值 | +|----------|----------|----------|------|--------| +| /api/v1/auth/login | POST | 用户登录 | LoginRequest | AuthResponse | +| /api/v1/auth/logout | POST | 用户登出 | - | LogoutResponse | +| /api/v1/auth/refresh | POST | 刷新令牌 | RefreshRequest | AuthResponse | +| /api/v1/auth/register | POST | 用户注册 | RegisterRequest | UserResponse | +| /api/v1/users | GET | 获取用户列表 | page, size | UserListResponse | +| /api/v1/users/{id} | GET | 获取用户详情 | - | UserResponse | +| /api/v1/roles | GET | 获取角色列表 | page, size | RoleListResponse | +| /api/v1/permissions | GET | 获取权限列表 | page, size | PermissionListResponse | + +### OAuth2流程 +\`\`\`mermaid +sequenceDiagram + participant U as 用户 + participant C as 客户端 + participant A as 授权服务器 + participant R as 资源服务器 + + U->>C: 访问受保护资源 + C->>A: 请求授权 + A->>U: 重定向到登录页面 + U->>A: 输入用户名密码 + A->>U: 授权确认 + U->>A: 确认授权 + A->>C: 返回授权码 + C->>A: 用授权码换取访问令牌 + A->>C: 返回访问令牌 + C->>R: 用访问令牌请求资源 + R->>A: 验证访问令牌 + A->>R: 令牌验证结果 + R->>C: 返回受保护资源 + C->>U: 显示资源内容 +\`\`\` + +### 权限控制模型 +\`\`\`go +// RBAC权限模型 +type User struct { + ID uuid.UUID \`json:"id"\` + Username string \`json:"username"\` + Email string \`json:"email"\` + Roles []Role \`json:"roles" gorm:"many2many:user_roles;"\` +} + +type Role struct { + ID uuid.UUID \`json:"id"\` + Name string \`json:"name"\` + Description string \`json:"description"\` + Permissions []Permission \`json:"permissions" gorm:"many2many:role_permissions;"\` +} + +type Permission struct { + ID uuid.UUID \`json:"id"\` + Name string \`json:"name"\` + Resource string \`json:"resource"\` + Action string \`json:"action"\` + Description string \`json:"description"\` +} + +// 权限检查函数 +func (u *User) HasPermission(resource, action string) bool { + for _, role := range u.Roles { + for _, permission := range role.Permissions { + if permission.Resource == resource && permission.Action == action { + return true + } + } + } + return false +} +\`\`\` + +### 性能特性 +| 指标类型 | 指标名称 | 目标值 | 当前值 | 状态 | +|----------|----------|--------|--------|------| +| 响应时间 | 认证响应时间 | <200ms | 180ms | 正常 | +| 吞吐量 | 认证请求量 | 500/s | 450/s | 正常 | +| 错误率 | 认证错误率 | <0.5% | 0.3% | 正常 | +| 并发数 | 最大并发认证数 | 1000 | 800 | 正常 | +| 内存使用 | 内存使用率 | <80% | 60% | 正常 | +| CPU使用 | CPU使用率 | <70% | 40% | 正常 | + +## 服务间通信分析 + +### 通信方式 +| 通信方式 | 使用场景 | 协议 | 特点 | +|----------|----------|------|------| +| HTTP REST | 同步API调用 | HTTP/1.1 | 简单易用,广泛支持 | +| gRPC | 高性能服务间通信 | HTTP/2 | 高性能,强类型 | +| WebSocket | 实时双向通信 | WebSocket | 实时性,双向通信 | +| Message Queue | 异步消息传递 | AMQP/MQTT | 异步解耦,可靠性 | + +### 通信协议选择 +- **HTTP REST**: 简单的CRUD操作,外部API +- **gRPC**: 内部服务间高性能通信 +- **WebSocket**: 实时通知和事件推送 +- **Message Queue**: 异步事件处理和消息传递 + +## 服务部署分析 + +### 部署架构 +\`\`\`mermaid +graph TB + subgraph "负载均衡层" + LB[负载均衡器] + end + + subgraph "API网关层" + GW[API网关] + end + + subgraph "服务层" + M1[Management-1] + M2[Management-2] + C1[Collector-1] + C2[Collector-2] + I1[IDM-1] + I2[IDM-2] + end + + subgraph "数据层" + DB[(PostgreSQL集群)] + Cache[(Redis集群)] + MQ[(Pulsar集群)] + ES[(Elasticsearch集群)] + end + + LB --> GW + GW --> M1 + GW --> M2 + GW --> C1 + GW --> C2 + GW --> I1 + GW --> I2 + M1 --> DB + M2 --> DB + C1 --> DB + C2 --> DB + I1 --> DB + I2 --> DB + M1 --> Cache + M2 --> Cache + C1 --> MQ + C2 --> MQ + C1 --> ES + C2 --> ES +\`\`\` + +### 部署策略 +- **容器化部署**: Docker容器化,便于管理和扩展 +- **负载均衡**: 多实例部署,负载均衡分发 +- **自动扩展**: 基于CPU、内存、QPS自动扩展 +- **健康检查**: 定期健康检查,自动故障转移 + +## 总结 + +### 服务架构特点 +- {服务架构主要特点总结} +- {技术栈选择总结} +- {部署方式总结} +- {性能特性总结} + +### 优化建议 +- {服务性能优化建议} +- {服务可靠性优化建议} +- {服务安全性优化建议} +- {服务可维护性优化建议} +\`\`\` + +## 特别注意事项 +1. 必须基于实际的代码和配置进行分析,不能虚构服务功能 +2. 重点分析核心服务的关键功能和接口 +3. 关注服务间的依赖关系和通信方式 +4. 识别性能瓶颈和优化空间 +5. 提供实用的部署和运维建议 + +## 输出文件命名 +\`${WIKI_OUTPUT_DIR}05_{PROJECT_NAME}_Service_Analysis.md\` +注意:如果${WIKI_OUTPUT_DIR} 目录不存在,则创建。 + +## 示例输出特征 +基于项目的服务分析特征: +- 详细的服务架构和功能模块分析 +- 完整的API接口和数据模型定义 +- 全面的服务依赖关系和通信方式分析 +- 具体的性能特性和监控指标 +- 实用的部署策略和优化建议` diff --git a/src/core/tools/helpers/wiki-prompts/subtasks/06_Database_Schema_Analysis.ts b/src/core/tools/helpers/wiki-prompts/subtasks/06_Database_Schema_Analysis.ts new file mode 100644 index 0000000000..85aa46f325 --- /dev/null +++ b/src/core/tools/helpers/wiki-prompts/subtasks/06_Database_Schema_Analysis.ts @@ -0,0 +1,1251 @@ +import { WIKI_OUTPUT_DIR } from "./constants" + +export const DATABASE_SCHEMA_ANALYSIS_TEMPLATE = `# 数据库架构深度分析 + +## 使用场景 +从代码仓库中分析数据库架构、表结构、索引设计、关系模型等,生成详细的数据库技术文档。 + +## 输入要求 +- **完整代码仓库**: 项目的完整源代码 +- **数据库迁移文件**: 数据库迁移和初始化脚本 +- **ORM模型定义**: 数据库模型和关系定义 +- **数据库配置**: 数据库连接和配置文件 + +# 数据库架构深度分析任务 + +## 任务描述 +请深度分析项目中的数据库架构,从表结构设计、关系模型、索引优化、性能特性、数据安全等维度生成完整的数据库技术文档。 + +## 分析维度 + +### 1. 数据库架构分析 +#### 数据库类型和版本 +| 数据库 | 类型 | 版本 | 用途 | 部署方式 | +|--------|------|------|------|----------| +| PostgreSQL | 关系型数据库 | 13.4 | 主数据存储 | 主从复制 | +| Redis | 内存数据库 | 6.2 | 缓存存储 | 主从复制 | +| Pulsar | 消息队列 | 2.8 | 消息存储 | 集群部署 | +| Elasticsearch | 搜索引擎 | 7.14 | 搜索索引 | 集群部署 | + +#### 数据库架构图 +\`\`\`mermaid +graph TB + subgraph "主数据库集群" + PG1[(PostgreSQL主库)] + PG2[(PostgreSQL从库1)] + PG3[(PostgreSQL从库2)] + end + + subgraph "缓存集群" + Redis1[(Redis主库)] + Redis2[(Redis从库1)] + Redis3[(Redis从库2)] + end + + subgraph "消息队列集群" + Pulsar1[(Pulsar Broker1)] + Pulsar2[(Pulsar Broker2)] + Pulsar3[(Pulsar Broker3)] + end + + subgraph "搜索集群" + ES1[(Elasticsearch1)] + ES2[(Elasticsearch2)] + ES3[(Elasticsearch3)] + end + + PG1 -.-> PG2 + PG1 -.-> PG3 + Redis1 -.-> Redis2 + Redis1 -.-> Redis3 + Pulsar1 --> Pulsar2 + Pulsar2 --> Pulsar3 + ES1 --> ES2 + ES2 --> ES3 +\`\`\` + +### 2. 表结构分析 +#### 核心业务表 +\`\`\`sql +-- 用户表 +CREATE TABLE users ( + id UUID PRIMARY KEY DEFAULT gen_random_uuid(), + username VARCHAR(50) UNIQUE NOT NULL, + email VARCHAR(100) UNIQUE NOT NULL, + password_hash VARCHAR(255) NOT NULL, + first_name VARCHAR(50), + last_name VARCHAR(50), + phone VARCHAR(20), + status VARCHAR(20) DEFAULT 'active', + created_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP, + updated_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP, + deleted_at TIMESTAMP WITH TIME ZONE +); + +-- 角色表 +CREATE TABLE roles ( + id UUID PRIMARY KEY DEFAULT gen_random_uuid(), + name VARCHAR(50) UNIQUE NOT NULL, + description TEXT, + created_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP, + updated_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP +); + +-- 权限表 +CREATE TABLE permissions ( + id UUID PRIMARY KEY DEFAULT gen_random_uuid(), + name VARCHAR(100) UNIQUE NOT NULL, + resource VARCHAR(100) NOT NULL, + action VARCHAR(50) NOT NULL, + description TEXT, + created_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP, + updated_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP +); + +-- 用户角色关联表 +CREATE TABLE user_roles ( + user_id UUID REFERENCES users(id) ON DELETE CASCADE, + role_id UUID REFERENCES roles(id) ON DELETE CASCADE, + created_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP, + PRIMARY KEY (user_id, role_id) +); + +-- 角色权限关联表 +CREATE TABLE role_permissions ( + role_id UUID REFERENCES roles(id) ON DELETE CASCADE, + permission_id UUID REFERENCES permissions(id) ON DELETE CASCADE, + created_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP, + PRIMARY KEY (role_id, permission_id) +); +\`\`\` + +#### 数据收集表 +\`\`\`sql +-- 数据表 +CREATE TABLE data_entries ( + id UUID PRIMARY KEY DEFAULT gen_random_uuid(), + user_id UUID REFERENCES users(id) ON DELETE CASCADE, + type VARCHAR(50) NOT NULL, + title VARCHAR(200) NOT NULL, + content TEXT, + metadata JSONB, + status VARCHAR(20) DEFAULT 'active', + created_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP, + updated_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP, + deleted_at TIMESTAMP WITH TIME ZONE +); + +-- 数据标签表 +CREATE TABLE data_tags ( + id UUID PRIMARY KEY DEFAULT gen_random_uuid(), + name VARCHAR(50) UNIQUE NOT NULL, + description TEXT, + color VARCHAR(7) DEFAULT '#007bff', + created_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP +); + +-- 数据标签关联表 +CREATE TABLE data_entry_tags ( + data_entry_id UUID REFERENCES data_entries(id) ON DELETE CASCADE, + tag_id UUID REFERENCES data_tags(id) ON DELETE CASCADE, + created_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP, + PRIMARY KEY (data_entry_id, tag_id) +); + +-- 数据处理历史表 +CREATE TABLE data_processing_history ( + id UUID PRIMARY KEY DEFAULT gen_random_uuid(), + data_entry_id UUID REFERENCES data_entries(id) ON DELETE CASCADE, + processing_type VARCHAR(50) NOT NULL, + status VARCHAR(20) NOT NULL, + error_message TEXT, + processed_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP +); +\`\`\` + +#### 系统配置表 +\`\`\`sql +-- 配置表 +CREATE TABLE configurations ( + id UUID PRIMARY KEY DEFAULT gen_random_uuid(), + key VARCHAR(100) UNIQUE NOT NULL, + value TEXT NOT NULL, + description TEXT, + data_type VARCHAR(20) DEFAULT 'string', + is_system BOOLEAN DEFAULT false, + created_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP, + updated_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP, + created_by UUID REFERENCES users(id) +); + +-- 审计日志表 +CREATE TABLE audit_logs ( + id UUID PRIMARY KEY DEFAULT gen_random_uuid(), + user_id UUID REFERENCES users(id), + action VARCHAR(50) NOT NULL, + resource_type VARCHAR(50) NOT NULL, + resource_id UUID, + old_values JSONB, + new_values JSONB, + ip_address INET, + user_agent TEXT, + created_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP +); + +-- 系统事件表 +CREATE TABLE system_events ( + id UUID PRIMARY KEY DEFAULT gen_random_uuid(), + event_type VARCHAR(50) NOT NULL, + event_data JSONB, + severity VARCHAR(20) DEFAULT 'info', + source VARCHAR(100), + created_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP +); +\`\`\` + +### 3. 索引设计分析 +#### 主键索引 +| 表名 | 主键字段 | 索引类型 | 索引名称 | +|------|----------|----------|----------| +| users | id | B-tree | users_pkey | +| roles | id | B-tree | roles_pkey | +| permissions | id | B-tree | permissions_pkey | +| data_entries | id | B-tree | data_entries_pkey | +| configurations | id | B-tree | configurations_pkey | + +#### 唯一索引 +| 表名 | 字段 | 索引类型 | 索引名称 | 用途 | +|------|------|----------|----------|------| +| users | username | B-tree | users_username_key | 用户名唯一性 | +| users | email | B-tree | users_email_key | 邮箱唯一性 | +| roles | name | B-tree | roles_name_key | 角色名唯一性 | +| permissions | name | B-tree | permissions_name_key | 权限名唯一性 | +| configurations | key | B-tree | configurations_key_key | 配置键唯一性 | +| data_tags | name | B-tree | data_tags_name_key | 标签名唯一性 | + +#### 普通索引 +| 表名 | 字段 | 索引类型 | 索引名称 | 用途 | +|------|------|----------|----------|------| +| users | status | B-tree | idx_users_status | 按状态查询 | +| users | created_at | B-tree | idx_users_created_at | 按创建时间查询 | +| data_entries | user_id | B-tree | idx_data_entries_user_id | 按用户查询 | +| data_entries | type | B-tree | idx_data_entries_type | 按类型查询 | +| data_entries | status | B-tree | idx_data_entries_status | 按状态查询 | +| data_entries | created_at | B-tree | idx_data_entries_created_at | 按创建时间查询 | +| audit_logs | user_id | B-tree | idx_audit_logs_user_id | 按用户查询 | +| audit_logs | action | B-tree | idx_audit_logs_action | 按操作查询 | +| audit_logs | created_at | B-tree | idx_audit_logs_created_at | 按时间查询 | +| system_events | event_type | B-tree | idx_system_events_event_type | 按事件类型查询 | +| system_events | severity | B-tree | idx_system_events_severity | 按严重程度查询 | +| system_events | created_at | B-tree | idx_system_events_created_at | 按时间查询 | + +#### 复合索引 +| 表名 | 字段组合 | 索引类型 | 索引名称 | 用途 | +|------|----------|----------|----------|------| +| data_entries | user_id, status | B-tree | idx_data_entries_user_status | 按用户和状态查询 | +| data_entries | type, status | B-tree | idx_data_entries_type_status | 按类型和状态查询 | +| data_entries | user_id, created_at | B-tree | idx_data_entries_user_created | 按用户和时间查询 | +| audit_logs | user_id, action | B-tree | idx_audit_logs_user_action | 按用户和操作查询 | +| audit_logs | action, created_at | B-tree | idx_audit_logs_action_created | 按操作和时间查询 | +| system_events | event_type, severity | B-tree | idx_system_events_type_severity | 按类型和严重程度查询 | + +#### JSONB索引 +| 表名 | 字段 | 索引类型 | 索引名称 | 用途 | +|------|------|----------|----------|------| +| data_entries | metadata | GIN | idx_data_entries_metadata_gin | JSONB全文搜索 | +| data_entries | metadata | B-tree | idx_data_entries_metadata_path | JSONB路径查询 | +| audit_logs | old_values | GIN | idx_audit_logs_old_values_gin | JSONB全文搜索 | +| audit_logs | new_values | GIN | idx_audit_logs_new_values_gin | JSONB全文搜索 | +| system_events | event_data | GIN | idx_system_events_event_data_gin | JSONB全文搜索 | + +### 4. 关系模型分析 +#### 实体关系图 +\`\`\`mermaid +erDiagram + users ||--o{ user_roles : "has" + users ||--o{ data_entries : "creates" + users ||--o{ audit_logs : "performs" + users ||--o{ configurations : "manages" + + roles ||--o{ user_roles : "assigned to" + roles ||--o{ role_permissions : "has" + + permissions ||--o{ role_permissions : "assigned to" + + data_entries ||--o{ data_entry_tags : "has" + data_entries ||--o{ data_processing_history : "processed" + + data_tags ||--o{ data_entry_tags : "assigned to" + + users { + UUID id PK + VARCHAR username UK + VARCHAR email UK + VARCHAR password_hash + VARCHAR first_name + VARCHAR last_name + VARCHAR phone + VARCHAR status + TIMESTAMP created_at + TIMESTAMP updated_at + TIMESTAMP deleted_at + } + + roles { + UUID id PK + VARCHAR name UK + TEXT description + TIMESTAMP created_at + TIMESTAMP updated_at + } + + permissions { + UUID id PK + VARCHAR name UK + VARCHAR resource + VARCHAR action + TEXT description + TIMESTAMP created_at + TIMESTAMP updated_at + } + + user_roles { + UUID user_id PK, FK + UUID role_id PK, FK + TIMESTAMP created_at + } + + role_permissions { + UUID role_id PK, FK + UUID permission_id PK, FK + TIMESTAMP created_at + } + + data_entries { + UUID id PK + UUID user_id FK + VARCHAR type + VARCHAR title + TEXT content + JSONB metadata + VARCHAR status + TIMESTAMP created_at + TIMESTAMP updated_at + TIMESTAMP deleted_at + } + + data_tags { + UUID id PK + VARCHAR name UK + TEXT description + VARCHAR color + TIMESTAMP created_at + } + + data_entry_tags { + UUID data_entry_id PK, FK + UUID tag_id PK, FK + TIMESTAMP created_at + } + + data_processing_history { + UUID id PK + UUID data_entry_id FK + VARCHAR processing_type + VARCHAR status + TEXT error_message + TIMESTAMP processed_at + } + + configurations { + UUID id PK + VARCHAR key UK + TEXT value + TEXT description + VARCHAR data_type + BOOLEAN is_system + TIMESTAMP created_at + TIMESTAMP updated_at + UUID created_by FK + } + + audit_logs { + UUID id PK + UUID user_id FK + VARCHAR action + VARCHAR resource_type + UUID resource_id + JSONB old_values + JSONB new_values + INET ip_address + TEXT user_agent + TIMESTAMP created_at + } + + system_events { + UUID id PK + VARCHAR event_type + JSONB event_data + VARCHAR severity + VARCHAR source + TIMESTAMP created_at + } +\`\`\` + +#### 关系类型说明 +- **一对一关系**: 用户和用户配置(通过配置表中的created_by关联) +- **一对多关系**: 用户和数据条目、用户和审计日志、角色和用户角色关联 +- **多对多关系**: 用户和角色(通过user_roles表)、角色和权限(通过role_permissions表)、数据条目和标签(通过data_entry_tags表) + +### 5. 数据完整性分析 +#### 约束设计 +| 约束类型 | 表名 | 约束名称 | 约束字段 | 约束条件 | +|----------|------|----------|----------|----------| +| PRIMARY KEY | users | users_pkey | id | NOT NULL | +| PRIMARY KEY | roles | roles_pkey | id | NOT NULL | +| PRIMARY KEY | permissions | permissions_pkey | id | NOT NULL | +| PRIMARY KEY | data_entries | data_entries_pkey | id | NOT NULL | +| FOREIGN KEY | user_roles | user_roles_user_id_fkey | user_id | REFERENCES users(id) | +| FOREIGN KEY | user_roles | user_roles_role_id_fkey | role_id | REFERENCES roles(id) | +| FOREIGN KEY | role_permissions | role_permissions_role_id_fkey | role_id | REFERENCES roles(id) | +| FOREIGN KEY | role_permissions | role_permissions_permission_id_fkey | permission_id | REFERENCES permissions(id) | +| FOREIGN KEY | data_entries | data_entries_user_id_fkey | user_id | REFERENCES users(id) | +| FOREIGN KEY | data_entry_tags | data_entry_tags_data_entry_id_fkey | data_entry_id | REFERENCES data_entries(id) | +| FOREIGN KEY | data_entry_tags | data_entry_tags_tag_id_fkey | tag_id | REFERENCES data_tags(id) | +| FOREIGN KEY | data_processing_history | data_processing_history_data_entry_id_fkey | data_entry_id | REFERENCES data_entries(id) | +| FOREIGN KEY | configurations | configurations_created_by_fkey | created_by | REFERENCES users(id) | +| FOREIGN KEY | audit_logs | audit_logs_user_id_fkey | user_id | REFERENCES users(id) | +| UNIQUE | users | users_username_key | username | UNIQUE | +| UNIQUE | users | users_email_key | email | UNIQUE | +| UNIQUE | roles | roles_name_key | name | UNIQUE | +| UNIQUE | permissions | permissions_name_key | name | UNIQUE | +| UNIQUE | configurations | configurations_key_key | key | UNIQUE | +| UNIQUE | data_tags | data_tags_name_key | name | UNIQUE | +| CHECK | users | users_status_check | status | IN ('active', 'inactive', 'suspended') | +| CHECK | data_entries | data_entries_status_check | status | IN ('active', 'inactive', 'processing', 'failed') | +| CHECK | data_processing_history | data_processing_history_status_check | status | IN ('pending', 'processing', 'completed', 'failed') | +| CHECK | configurations | configurations_data_type_check | data_type | IN ('string', 'number', 'boolean', 'json') | +| CHECK | system_events | system_events_severity_check | severity | IN ('debug', 'info', 'warning', 'error', 'critical') | + +#### 触发器设计 +\`\`\`sql +-- 用户表更新时间触发器 +CREATE OR REPLACE FUNCTION update_updated_at_column() +RETURNS TRIGGER AS $$ +BEGIN + NEW.updated_at = CURRENT_TIMESTAMP; + RETURN NEW; +END; +$$ language 'plpgsql'; + +-- 为需要更新时间的表创建触发器 +CREATE TRIGGER update_users_updated_at BEFORE UPDATE ON users + FOR EACH ROW EXECUTE FUNCTION update_updated_at_column(); + +CREATE TRIGGER update_roles_updated_at BEFORE UPDATE ON roles + FOR EACH ROW EXECUTE FUNCTION update_updated_at_column(); + +CREATE TRIGGER update_permissions_updated_at BEFORE UPDATE ON permissions + FOR EACH ROW EXECUTE FUNCTION update_updated_at_column(); + +CREATE TRIGGER update_data_entries_updated_at BEFORE UPDATE ON data_entries + FOR EACH ROW EXECUTE FUNCTION update_updated_at_column(); + +CREATE TRIGGER update_configurations_updated_at BEFORE UPDATE ON configurations + FOR EACH ROW EXECUTE FUNCTION update_updated_at_column(); + +-- 审计日志触发器 +CREATE OR REPLACE FUNCTION audit_log_trigger() +RETURNS TRIGGER AS $$ +BEGIN + IF TG_OP = 'UPDATE' THEN + INSERT INTO audit_logs (user_id, action, resource_type, resource_id, old_values, new_values, ip_address, user_agent) + VALUES ( + CURRENT_USER, + 'UPDATE', + TG_TABLE_NAME, + NEW.id, + to_jsonb(OLD), + to_jsonb(NEW), + inet_client_addr(), + current_setting('application.user_agent', true) + ); + RETURN NEW; + ELSIF TG_OP = 'DELETE' THEN + INSERT INTO audit_logs (user_id, action, resource_type, resource_id, old_values, ip_address, user_agent) + VALUES ( + CURRENT_USER, + 'DELETE', + TG_TABLE_NAME, + OLD.id, + to_jsonb(OLD), + NULL, + inet_client_addr(), + current_setting('application.user_agent', true) + ); + RETURN OLD; + ELSIF TG_OP = 'INSERT' THEN + INSERT INTO audit_logs (user_id, action, resource_type, resource_id, new_values, ip_address, user_agent) + VALUES ( + CURRENT_USER, + 'INSERT', + TG_TABLE_NAME, + NEW.id, + to_jsonb(NEW), + inet_client_addr(), + current_setting('application.user_agent', true) + ); + RETURN NEW; + END IF; + RETURN NULL; +END; +$$ language 'plpgsql'; + +-- 为需要审计的表创建触发器 +CREATE TRIGGER users_audit_trigger AFTER INSERT OR UPDATE OR DELETE ON users + FOR EACH ROW EXECUTE FUNCTION audit_log_trigger(); + +CREATE TRIGGER roles_audit_trigger AFTER INSERT OR UPDATE OR DELETE ON roles + FOR EACH ROW EXECUTE FUNCTION audit_log_trigger(); + +CREATE TRIGGER permissions_audit_trigger AFTER INSERT OR UPDATE OR DELETE ON permissions + FOR EACH ROW EXECUTE FUNCTION audit_log_trigger(); + +CREATE TRIGGER data_entries_audit_trigger AFTER INSERT OR UPDATE OR DELETE ON data_entries + FOR EACH ROW EXECUTE FUNCTION audit_log_trigger(); + +CREATE TRIGGER configurations_audit_trigger AFTER INSERT OR UPDATE OR DELETE ON configurations + FOR EACH ROW EXECUTE FUNCTION audit_log_trigger(); +\`\`\` + +### 6. 性能优化分析 +#### 查询优化策略 +| 优化类型 | 优化策略 | 实现方式 | 预期效果 | +|----------|----------|----------|----------| +| 索引优化 | 合理创建索引 | B-tree、GIN、复合索引 | 查询性能提升50-80% | +| 查询优化 | 优化SQL查询 | 避免全表扫描、使用索引 | 查询时间减少60-90% | +| 连接池优化 | 数据库连接池 | 合理配置连接池大小 | 并发性能提升30-50% | +| 分区优化 | 大表分区 | 按时间或ID分区 | 查询性能提升40-70% | +| 缓存优化 | 热点数据缓存 | Redis缓存热点数据 | 响应时间减少80-95% | + +#### 分区策略 +| 表名 | 分区类型 | 分区键 | 分区数量 | 分区策略 | +|------|----------|--------|----------|----------| +| audit_logs | 范围分区 | created_at | 按月分区 | 每月一个分区 | +| system_events | 范围分区 | created_at | 按月分区 | 每月一个分区 | +| data_entries | 哈希分区 | id | 16个分区 | 均匀分布 | +| data_processing_history | 范围分区 | processed_at | 按月分区 | 每月一个分区 | + +#### 缓存策略 +| 缓存类型 | 缓存数据 | 过期时间 | 缓存策略 | +|----------|----------|----------|----------| +| 用户信息 | 用户基本资料 | 30分钟 | 主动刷新 | +| 配置信息 | 系统配置 | 1小时 | 定时刷新 | +| 权限信息 | 用户权限 | 15分钟 | 主动刷新 | +| 统计数据 | 业务统计 | 5分钟 | 定时刷新 | +| 会话信息 | 用户会话 | 24小时 | 惰性过期 | + +### 7. 数据安全分析 +#### 数据加密 +| 数据类型 | 加密方式 | 加密算法 | 密钥管理 | +|----------|----------|----------|----------| +| 密码 | 哈希加密 | bcrypt | 单向哈希 | +| 敏感信息 | 对称加密 | AES-256 | 密钥管理系统 | +| 备份数据 | 对称加密 | AES-256 | 备份密钥管理 | +| 传输数据 | 传输加密 | TLS 1.3 | 证书管理 | + +#### 访问控制 +| 控制类型 | 控制策略 | 实现方式 | 控制粒度 | +|----------|----------|----------|----------| +| 数据库用户 | 最小权限原则 | 角色基础访问控制 | 表级别 | +| 应用连接 | 连接池管理 | 连接字符串加密 | 应用级别 | +| 数据访问 | 行级安全 | RLS策略 | 行级别 | +| 敏感数据 | 数据脱敏 | 视图和函数 | 字段级别 | + +#### 备份策略 +| 备份类型 | 备份频率 | 保留时间 | 备份方式 | +|----------|----------|----------|----------| +| 全量备份 | 每日 | 30天 | pg_dump | +| 增量备份 | 每小时 | 7天 | WAL归档 | +| 逻辑备份 | 每周 | 90天 | pg_dumpall | +| 灾备备份 | 每日 | 365天 | 异地备份 | + +### 8. 监控和维护分析 +#### 监控指标 +| 指标类型 | 指标名称 | 阈值 | 告警级别 | +|----------|----------|------|----------| +| 连接监控 | 活跃连接数 | >80% | 警告 | +| 连接监控 | 空闲连接数 | >50% | 信息 | +| 性能监控 | 查询响应时间 | >1000ms | 警告 | +| 性能监控 | 慢查询数量 | >10/分钟 | 警告 | +| 存储监控 | 磁盘使用率 | >85% | 警告 | +| 存储监控 | 磁盘使用率 | >95% | 严重 | +| 内存监控 | 缓存命中率 | <90% | 警告 | +| 内存监控 | 共享缓冲区使用率 | >80% | 警告 | + +#### 维护策略 +- **定期维护**: 每周进行数据库维护和优化 +- **索引重建**: 定期重建碎片化严重的索引 +- **统计信息更新**: 定期更新表统计信息 +- **日志清理**: 定期清理过期日志和临时文件 +- **性能调优**: 根据监控数据进行性能调优 + +## 输出格式要求 + +生成完整的数据库架构分析文档: + +### 文档结构 +\`\`\`markdown +# {项目名称} 数据库架构分析 + +## 数据库架构概览 + +### 数据库类型和版本 +| 数据库 | 类型 | 版本 | 用途 | 部署方式 | +|--------|------|------|------|----------| +| PostgreSQL | 关系型数据库 | 13.4 | 主数据存储 | 主从复制 | +| Redis | 内存数据库 | 6.2 | 缓存存储 | 主从复制 | +| Pulsar | 消息队列 | 2.8 | 消息存储 | 集群部署 | +| Elasticsearch | 搜索引擎 | 7.14 | 搜索索引 | 集群部署 | + +### 数据库架构图 +\`\`\`mermaid +graph TB + subgraph "主数据库集群" + PG1[(PostgreSQL主库)] + PG2[(PostgreSQL从库1)] + PG3[(PostgreSQL从库2)] + end + + subgraph "缓存集群" + Redis1[(Redis主库)] + Redis2[(Redis从库1)] + Redis3[(Redis从库2)] + end + + subgraph "消息队列集群" + Pulsar1[(Pulsar Broker1)] + Pulsar2[(Pulsar Broker2)] + Pulsar3[(Pulsar Broker3)] + end + + subgraph "搜索集群" + ES1[(Elasticsearch1)] + ES2[(Elasticsearch2)] + ES3[(Elasticsearch3)] + end + + PG1 -.-> PG2 + PG1 -.-> PG3 + Redis1 -.-> Redis2 + Redis1 -.-> Redis3 + Pulsar1 --> Pulsar2 + Pulsar2 --> Pulsar3 + ES1 --> ES2 + ES2 --> ES3 +\`\`\` + +## 表结构分析 + +### 用户管理表 +#### users表 +\`\`\`sql +CREATE TABLE users ( + id UUID PRIMARY KEY DEFAULT gen_random_uuid(), + username VARCHAR(50) UNIQUE NOT NULL, + email VARCHAR(100) UNIQUE NOT NULL, + password_hash VARCHAR(255) NOT NULL, + first_name VARCHAR(50), + last_name VARCHAR(50), + phone VARCHAR(20), + status VARCHAR(20) DEFAULT 'active', + created_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP, + updated_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP, + deleted_at TIMESTAMP WITH TIME ZONE +); +\`\`\` + +**字段说明**: +- \`id\`: 用户唯一标识符,UUID类型 +- \`username\`: 用户名,唯一约束 +- \`email\`: 邮箱地址,唯一约束 +- \`password_hash\`: 密码哈希值,使用bcrypt加密 +- \`first_name\`: 名 +- \`last_name\`: 姓 +- \`phone\`: 电话号码 +- \`status\`: 用户状态(active, inactive, suspended) +- \`created_at\`: 创建时间 +- \`updated_at\`: 更新时间 +- \`deleted_at\`: 删除时间(软删除) + +#### roles表 +\`\`\`sql +CREATE TABLE roles ( + id UUID PRIMARY KEY DEFAULT gen_random_uuid(), + name VARCHAR(50) UNIQUE NOT NULL, + description TEXT, + created_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP, + updated_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP +); +\`\`\` + +**字段说明**: +- \`id\`: 角色唯一标识符,UUID类型 +- \`name\`: 角色名称,唯一约束 +- \`description\`: 角色描述 +- \`created_at\`: 创建时间 +- \`updated_at\`: 更新时间 + +#### permissions表 +\`\`\`sql +CREATE TABLE permissions ( + id UUID PRIMARY KEY DEFAULT gen_random_uuid(), + name VARCHAR(100) UNIQUE NOT NULL, + resource VARCHAR(100) NOT NULL, + action VARCHAR(50) NOT NULL, + description TEXT, + created_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP, + updated_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP +); +\`\`\` + +**字段说明**: +- \`id\`: 权限唯一标识符,UUID类型 +- \`name\`: 权限名称,唯一约束 +- \`resource\`: 资源类型 +- \`action\`: 操作类型 +- \`description\`: 权限描述 +- \`created_at\`: 创建时间 +- \`updated_at\`: 更新时间 + +### 数据管理表 +#### data_entries表 +\`\`\`sql +CREATE TABLE data_entries ( + id UUID PRIMARY KEY DEFAULT gen_random_uuid(), + user_id UUID REFERENCES users(id) ON DELETE CASCADE, + type VARCHAR(50) NOT NULL, + title VARCHAR(200) NOT NULL, + content TEXT, + metadata JSONB, + status VARCHAR(20) DEFAULT 'active', + created_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP, + updated_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP, + deleted_at TIMESTAMP WITH TIME ZONE +); +\`\`\` + +**字段说明**: +- \`id\`: 数据条目唯一标识符,UUID类型 +- \`user_id\`: 创建用户ID,外键关联users表 +- \`type\`: 数据类型 +- \`title\`: 数据标题 +- \`content\`: 数据内容 +- \`metadata\`: 元数据,JSONB格式 +- \`status\`: 状态(active, inactive, processing, failed) +- \`created_at\`: 创建时间 +- \`updated_at\`: 更新时间 +- \`deleted_at\`: 删除时间(软删除) + +#### data_tags表 +\`\`\`sql +CREATE TABLE data_tags ( + id UUID PRIMARY KEY DEFAULT gen_random_uuid(), + name VARCHAR(50) UNIQUE NOT NULL, + description TEXT, + color VARCHAR(7) DEFAULT '#007bff', + created_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP +); +\`\`\` + +**字段说明**: +- \`id\`: 标签唯一标识符,UUID类型 +- \`name\`: 标签名称,唯一约束 +- \`description\`: 标签描述 +- \`color\`: 标签颜色,十六进制格式 +- \`created_at\`: 创建时间 + +### 系统表 +#### configurations表 +\`\`\`sql +CREATE TABLE configurations ( + id UUID PRIMARY KEY DEFAULT gen_random_uuid(), + key VARCHAR(100) UNIQUE NOT NULL, + value TEXT NOT NULL, + description TEXT, + data_type VARCHAR(20) DEFAULT 'string', + is_system BOOLEAN DEFAULT false, + created_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP, + updated_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP, + created_by UUID REFERENCES users(id) +); +\`\`\` + +**字段说明**: +- \`id\`: 配置唯一标识符,UUID类型 +- \`key\`: 配置键,唯一约束 +- \`value\`: 配置值 +- \`description\`: 配置描述 +- \`data_type\`: 数据类型(string, number, boolean, json) +- \`is_system\`: 是否为系统配置 +- \`created_at\`: 创建时间 +- \`updated_at\`: 更新时间 +- \`created_by\`: 创建者ID,外键关联users表 + +#### audit_logs表 +\`\`\`sql +CREATE TABLE audit_logs ( + id UUID PRIMARY KEY DEFAULT gen_random_uuid(), + user_id UUID REFERENCES users(id), + action VARCHAR(50) NOT NULL, + resource_type VARCHAR(50) NOT NULL, + resource_id UUID, + old_values JSONB, + new_values JSONB, + ip_address INET, + user_agent TEXT, + created_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP +); +\`\`\` + +**字段说明**: +- \`id\`: 审计日志唯一标识符,UUID类型 +- \`user_id\`: 操作用户ID,外键关联users表 +- \`action\`: 操作类型 +- \`resource_type\`: 资源类型 +- \`resource_id\`: 资源ID +- \`old_values\`: 旧值,JSONB格式 +- \`new_values\`: 新值,JSONB格式 +- \`ip_address\`: IP地址 +- \`user_agent\`: 用户代理 +- \`created_at\`: 创建时间 + +## 索引设计分析 + +### 主键索引 +| 表名 | 主键字段 | 索引类型 | 索引名称 | +|------|----------|----------|----------| +| users | id | B-tree | users_pkey | +| roles | id | B-tree | roles_pkey | +| permissions | id | B-tree | permissions_pkey | +| data_entries | id | B-tree | data_entries_pkey | +| configurations | id | B-tree | configurations_pkey | + +### 唯一索引 +| 表名 | 字段 | 索引类型 | 索引名称 | 用途 | +|------|------|----------|----------|------| +| users | username | B-tree | users_username_key | 用户名唯一性 | +| users | email | B-tree | users_email_key | 邮箱唯一性 | +| roles | name | B-tree | roles_name_key | 角色名唯一性 | +| permissions | name | B-tree | permissions_name_key | 权限名唯一性 | +| configurations | key | B-tree | configurations_key_key | 配置键唯一性 | +| data_tags | name | B-tree | data_tags_name_key | 标签名唯一性 | + +### 普通索引 +| 表名 | 字段 | 索引类型 | 索引名称 | 用途 | +|------|------|----------|----------|------| +| users | status | B-tree | idx_users_status | 按状态查询 | +| users | created_at | B-tree | idx_users_created_at | 按创建时间查询 | +| data_entries | user_id | B-tree | idx_data_entries_user_id | 按用户查询 | +| data_entries | type | B-tree | idx_data_entries_type | 按类型查询 | +| data_entries | status | B-tree | idx_data_entries_status | 按状态查询 | +| data_entries | created_at | B-tree | idx_data_entries_created_at | 按创建时间查询 | +| audit_logs | user_id | B-tree | idx_audit_logs_user_id | 按用户查询 | +| audit_logs | action | B-tree | idx_audit_logs_action | 按操作查询 | +| audit_logs | created_at | B-tree | idx_audit_logs_created_at | 按时间查询 | +| system_events | event_type | B-tree | idx_system_events_event_type | 按事件类型查询 | +| system_events | severity | B-tree | idx_system_events_severity | 按严重程度查询 | +| system_events | created_at | B-tree | idx_system_events_created_at | 按时间查询 | + +### 复合索引 +| 表名 | 字段组合 | 索引类型 | 索引名称 | 用途 | +|------|----------|----------|----------|------| +| data_entries | user_id, status | B-tree | idx_data_entries_user_status | 按用户和状态查询 | +| data_entries | type, status | B-tree | idx_data_entries_type_status | 按类型和状态查询 | +| data_entries | user_id, created_at | B-tree | idx_data_entries_user_created | 按用户和时间查询 | +| audit_logs | user_id, action | B-tree | idx_audit_logs_user_action | 按用户和操作查询 | +| audit_logs | action, created_at | B-tree | idx_audit_logs_action_created | 按操作和时间查询 | +| system_events | event_type, severity | B-tree | idx_system_events_type_severity | 按类型和严重程度查询 | + +### JSONB索引 +| 表名 | 字段 | 索引类型 | 索引名称 | 用途 | +|------|------|----------|----------|------| +| data_entries | metadata | GIN | idx_data_entries_metadata_gin | JSONB全文搜索 | +| data_entries | metadata | B-tree | idx_data_entries_metadata_path | JSONB路径查询 | +| audit_logs | old_values | GIN | idx_audit_logs_old_values_gin | JSONB全文搜索 | +| audit_logs | new_values | GIN | idx_audit_logs_new_values_gin | JSONB全文搜索 | +| system_events | event_data | GIN | idx_system_events_event_data_gin | JSONB全文搜索 | + +## 关系模型分析 + +### 实体关系图 +\`\`\`mermaid +erDiagram + users ||--o{ user_roles : "has" + users ||--o{ data_entries : "creates" + users ||--o{ audit_logs : "performs" + users ||--o{ configurations : "manages" + + roles ||--o{ user_roles : "assigned to" + roles ||--o{ role_permissions : "has" + + permissions ||--o{ role_permissions : "assigned to" + + data_entries ||--o{ data_entry_tags : "has" + data_entries ||--o{ data_processing_history : "processed" + + data_tags ||--o{ data_entry_tags : "assigned to" + + users { + UUID id PK + VARCHAR username UK + VARCHAR email UK + VARCHAR password_hash + VARCHAR first_name + VARCHAR last_name + VARCHAR phone + VARCHAR status + TIMESTAMP created_at + TIMESTAMP updated_at + TIMESTAMP deleted_at + } + + roles { + UUID id PK + VARCHAR name UK + TEXT description + TIMESTAMP created_at + TIMESTAMP updated_at + } + + permissions { + UUID id PK + VARCHAR name UK + VARCHAR resource + VARCHAR action + TEXT description + TIMESTAMP created_at + TIMESTAMP updated_at + } + + user_roles { + UUID user_id PK, FK + UUID role_id PK, FK + TIMESTAMP created_at + } + + role_permissions { + UUID role_id PK, FK + UUID permission_id PK, FK + TIMESTAMP created_at + } + + data_entries { + UUID id PK + UUID user_id FK + VARCHAR type + VARCHAR title + TEXT content + JSONB metadata + VARCHAR status + TIMESTAMP created_at + TIMESTAMP updated_at + TIMESTAMP deleted_at + } + + data_tags { + UUID id PK + VARCHAR name UK + TEXT description + VARCHAR color + TIMESTAMP created_at + } + + data_entry_tags { + UUID data_entry_id PK, FK + UUID tag_id PK, FK + TIMESTAMP created_at + } + + data_processing_history { + UUID id PK + UUID data_entry_id FK + VARCHAR processing_type + VARCHAR status + TEXT error_message + TIMESTAMP processed_at + } + + configurations { + UUID id PK + VARCHAR key UK + TEXT value + TEXT description + VARCHAR data_type + BOOLEAN is_system + TIMESTAMP created_at + TIMESTAMP updated_at + UUID created_by FK + } + + audit_logs { + UUID id PK + UUID user_id FK + VARCHAR action + VARCHAR resource_type + UUID resource_id + JSONB old_values + JSONB new_values + INET ip_address + TEXT user_agent + TIMESTAMP created_at + } + + system_events { + UUID id PK + VARCHAR event_type + JSONB event_data + VARCHAR severity + VARCHAR source + TIMESTAMP created_at + } +\`\`\` + +### 关系说明 +- **用户-角色**: 多对多关系,通过user_roles表关联 +- **角色-权限**: 多对多关系,通过role_permissions表关联 +- **用户-数据条目**: 一对多关系,一个用户可以创建多个数据条目 +- **数据条目-标签**: 多对多关系,通过data_entry_tags表关联 +- **用户-审计日志**: 一对多关系,记录用户的操作历史 +- **用户-配置**: 一对多关系,用户可以管理系统配置 + +## 数据完整性分析 + +### 约束设计 +| 约束类型 | 表名 | 约束名称 | 约束字段 | 约束条件 | +|----------|------|----------|----------|----------| +| PRIMARY KEY | users | users_pkey | id | NOT NULL | +| PRIMARY KEY | roles | roles_pkey | id | NOT NULL | +| PRIMARY KEY | permissions | permissions_pkey | id | NOT NULL | +| PRIMARY KEY | data_entries | data_entries_pkey | id | NOT NULL | +| FOREIGN KEY | user_roles | user_roles_user_id_fkey | user_id | REFERENCES users(id) | +| FOREIGN KEY | user_roles | user_roles_role_id_fkey | role_id | REFERENCES roles(id) | +| FOREIGN KEY | role_permissions | role_permissions_role_id_fkey | role_id | REFERENCES roles(id) | +| FOREIGN KEY | role_permissions | role_permissions_permission_id_fkey | permission_id | REFERENCES permissions(id) | +| FOREIGN KEY | data_entries | data_entries_user_id_fkey | user_id | REFERENCES users(id) | +| FOREIGN KEY | data_entry_tags | data_entry_tags_data_entry_id_fkey | data_entry_id | REFERENCES data_entries(id) | +| FOREIGN KEY | data_entry_tags | data_entry_tags_tag_id_fkey | tag_id | REFERENCES data_tags(id) | +| FOREIGN KEY | data_processing_history | data_processing_history_data_entry_id_fkey | data_entry_id | REFERENCES data_entries(id) | +| FOREIGN KEY | configurations | configurations_created_by_fkey | created_by | REFERENCES users(id) | +| FOREIGN KEY | audit_logs | audit_logs_user_id_fkey | user_id | REFERENCES users(id) | +| UNIQUE | users | users_username_key | username | UNIQUE | +| UNIQUE | users | users_email_key | email | UNIQUE | +| UNIQUE | roles | roles_name_key | name | UNIQUE | +| UNIQUE | permissions | permissions_name_key | name | UNIQUE | +| UNIQUE | configurations | configurations_key_key | key | UNIQUE | +| UNIQUE | data_tags | data_tags_name_key | name | UNIQUE | +| CHECK | users | users_status_check | status | IN ('active', 'inactive', 'suspended') | +| CHECK | data_entries | data_entries_status_check | status | IN ('active', 'inactive', 'processing', 'failed') | +| CHECK | data_processing_history | data_processing_history_status_check | status | IN ('pending', 'processing', 'completed', 'failed') | +| CHECK | configurations | configurations_data_type_check | data_type | IN ('string', 'number', 'boolean', 'json') | +| CHECK | system_events | system_events_severity_check | severity | IN ('debug', 'info', 'warning', 'error', 'critical') | + +### 触发器设计 +#### 更新时间触发器 +\`\`\`sql +CREATE OR REPLACE FUNCTION update_updated_at_column() +RETURNS TRIGGER AS $$ +BEGIN + NEW.updated_at = CURRENT_TIMESTAMP; + RETURN NEW; +END; +$$ language 'plpgsql'; + +CREATE TRIGGER update_users_updated_at BEFORE UPDATE ON users + FOR EACH ROW EXECUTE FUNCTION update_updated_at_column(); + +CREATE TRIGGER update_roles_updated_at BEFORE UPDATE ON roles + FOR EACH ROW EXECUTE FUNCTION update_updated_at_column(); + +CREATE TRIGGER update_permissions_updated_at BEFORE UPDATE ON permissions + FOR EACH ROW EXECUTE FUNCTION update_updated_at_column(); + +CREATE TRIGGER update_data_entries_updated_at BEFORE UPDATE ON data_entries + FOR EACH ROW EXECUTE FUNCTION update_updated_at_column(); + +CREATE TRIGGER update_configurations_updated_at BEFORE UPDATE ON configurations + FOR EACH ROW EXECUTE FUNCTION update_updated_at_column(); +\`\`\` + +#### 审计日志触发器 +\`\`\`sql +CREATE OR REPLACE FUNCTION audit_log_trigger() +RETURNS TRIGGER AS $$ +BEGIN + IF TG_OP = 'UPDATE' THEN + INSERT INTO audit_logs (user_id, action, resource_type, resource_id, old_values, new_values, ip_address, user_agent) + VALUES ( + CURRENT_USER, + 'UPDATE', + TG_TABLE_NAME, + NEW.id, + to_jsonb(OLD), + to_jsonb(NEW), + inet_client_addr(), + current_setting('application.user_agent', true) + ); + RETURN NEW; + ELSIF TG_OP = 'DELETE' THEN + INSERT INTO audit_logs (user_id, action, resource_type, resource_id, old_values, ip_address, user_agent) + VALUES ( + CURRENT_USER, + 'DELETE', + TG_TABLE_NAME, + OLD.id, + to_jsonb(OLD), + NULL, + inet_client_addr(), + current_setting('application.user_agent', true) + ); + RETURN OLD; + ELSIF TG_OP = 'INSERT' THEN + INSERT INTO audit_logs (user_id, action, resource_type, resource_id, new_values, ip_address, user_agent) + VALUES ( + CURRENT_USER, + 'INSERT', + TG_TABLE_NAME, + NEW.id, + to_jsonb(NEW), + inet_client_addr(), + current_setting('application.user_agent', true) + ); + RETURN NEW; + END IF; + RETURN NULL; +END; +$$ language 'plpgsql'; + +CREATE TRIGGER users_audit_trigger AFTER INSERT OR UPDATE OR DELETE ON users + FOR EACH ROW EXECUTE FUNCTION audit_log_trigger(); + +CREATE TRIGGER roles_audit_trigger AFTER INSERT OR UPDATE OR DELETE ON roles + FOR EACH ROW EXECUTE FUNCTION audit_log_trigger(); + +CREATE TRIGGER permissions_audit_trigger AFTER INSERT OR UPDATE OR DELETE ON permissions + FOR EACH ROW EXECUTE FUNCTION audit_log_trigger(); + +CREATE TRIGGER data_entries_audit_trigger AFTER INSERT OR UPDATE OR DELETE ON data_entries + FOR EACH ROW EXECUTE FUNCTION audit_log_trigger(); + +CREATE TRIGGER configurations_audit_trigger AFTER INSERT OR UPDATE OR DELETE ON configurations + FOR EACH ROW EXECUTE FUNCTION audit_log_trigger(); +\`\`\` + +## 性能优化分析 + +### 查询优化策略 +| 优化类型 | 优化策略 | 实现方式 | 预期效果 | +|----------|----------|----------|----------| +| 索引优化 | 合理创建索引 | B-tree、GIN、复合索引 | 查询性能提升50-80% | +| 查询优化 | 优化SQL查询 | 避免全表扫描、使用索引 | 查询时间减少60-90% | +| 连接池优化 | 数据库连接池 | 合理配置连接池大小 | 并发性能提升30-50% | +| 分区优化 | 大表分区 | 按时间或ID分区 | 查询性能提升40-70% | +| 缓存优化 | 热点数据缓存 | Redis缓存热点数据 | 响应时间减少80-95% | + +### 分区策略 +| 表名 | 分区类型 | 分区键 | 分区数量 | 分区策略 | +|------|----------|--------|----------|----------| +| audit_logs | 范围分区 | created_at | 按月分区 | 每月一个分区 | +| system_events | 范围分区 | created_at | 按月分区 | 每月一个分区 | +| data_entries | 哈希分区 | id | 16个分区 | 均匀分布 | +| data_processing_history | 范围分区 | processed_at | 按月分区 | 每月一个分区 | + +### 缓存策略 +| 缓存类型 | 缓存数据 | 过期时间 | 缓存策略 | +|----------|----------|----------|----------| +| 用户信息 | 用户基本资料 | 30分钟 | 主动刷新 | +| 配置信息 | 系统配置 | 1小时 | 定时刷新 | +| 权限信息 | 用户权限 | 15分钟 | 主动刷新 | +| 统计数据 | 业务统计 | 5分钟 | 定时刷新 | +| 会话信息 | 用户会话 | 24小时 | 惰性过期 | + +## 数据安全分析 + +### 数据加密 +| 数据类型 | 加密方式 | 加密算法 | 密钥管理 | +|----------|----------|----------|----------| +| 密码 | 哈希加密 | bcrypt | 单向哈希 | +| 敏感信息 | 对称加密 | AES-256 | 密钥管理系统 | +| 备份数据 | 对称加密 | AES-256 | 备份密钥管理 | +| 传输数据 | 传输加密 | TLS 1.3 | 证书管理 | + +### 访问控制 +| 控制类型 | 控制策略 | 实现方式 | 控制粒度 | +|----------|----------|----------|----------| +| 数据库用户 | 最小权限原则 | 角色基础访问控制 | 表级别 | +| 应用连接 | 连接池管理 | 连接字符串加密 | 应用级别 | +| 数据访问 | 行级安全 | RLS策略 | 行级别 | +| 敏感数据 | 数据脱敏 | 视图和函数 | 字段级别 | + +### 备份策略 +| 备份类型 | 备份频率 | 保留时间 | 备份方式 | +|----------|----------|----------|----------| +| 全量备份 | 每日 | 30天 | pg_dump | +| 增量备份 | 每小时 | 7天 | WAL归档 | +| 逻辑备份 | 每周 | 90天 | pg_dumpall | +| 灾备备份 | 每日 | 365天 | 异地备份 | + +## 监控和维护分析 + +### 监控指标 +| 指标类型 | 指标名称 | 阈值 | 告警级别 | +|----------|----------|------|----------| +| 连接监控 | 活跃连接数 | >80% | 警告 | +| 连接监控 | 空闲连接数 | >50% | 信息 | +| 性能监控 | 查询响应时间 | >1000ms | 警告 | +| 性能监控 | 慢查询数量 | >10/分钟 | 警告 | +| 存储监控 | 磁盘使用率 | >85% | 警告 | +| 存储监控 | 磁盘使用率 | >95% | 严重 | +| 内存监控 | 缓存命中率 | <90% | 警告 | +| 内存监控 | 共享缓冲区使用率 | >80% | 警告 | + +### 维护策略 +- **定期维护**: 每周进行数据库维护和优化 +- **索引重建**: 定期重建碎片化严重的索引 +- **统计信息更新**: 定期更新表统计信息 +- **日志清理**: 定期清理过期日志和临时文件 +- **性能调优**: 根据监控数据进行性能调优 + +## 总结 + +### 数据库架构特点 +- {数据库架构主要特点总结} +- {表结构设计总结} +- {索引优化总结} +- {数据完整性保证总结} + +### 优化建议 +- {数据库性能优化建议} +- {数据安全加强建议} +- {监控维护改进建议} +- {扩展性优化建议} +\`\`\` + +## 特别注意事项 +1. 必须基于实际的代码和配置进行分析,不能虚构数据库结构 +2. 重点分析核心业务表和关键索引设计 +3. 关注数据完整性和安全性保证 +4. 识别性能瓶颈和优化空间 +5. 提供实用的监控和维护策略 + +## 输出文件命名 +\`${WIKI_OUTPUT_DIR}06_{PROJECT_NAME}_Database_Schema.md\` +注意:如果${WIKI_OUTPUT_DIR} 目录不存在,则创建。 + +## 示例输出特征 +基于项目的数据库分析特征: +- 详细的表结构和字段定义 +- 完整的索引设计和优化策略 +- 全面的关系模型和约束设计 +- 具体的性能优化和安全措施 +- 实用的监控和维护建议` diff --git a/src/core/tools/helpers/wiki-prompts/subtasks/07_API_Interface_Analysis.ts b/src/core/tools/helpers/wiki-prompts/subtasks/07_API_Interface_Analysis.ts new file mode 100644 index 0000000000..13126439df --- /dev/null +++ b/src/core/tools/helpers/wiki-prompts/subtasks/07_API_Interface_Analysis.ts @@ -0,0 +1,1640 @@ +import { WIKI_OUTPUT_DIR } from "./constants" + +export const API_INTERFACE_ANALYSIS_TEMPLATE = `# API接口深度分析 + +## 使用场景 +从代码仓库中分析API接口设计、接口规范、数据格式、错误处理等,生成详细的API接口技术文档。 + +## 输入要求 +- **完整代码仓库**: 项目的完整源代码 +- **API定义文件**: API接口定义和规范文件 +- **路由配置**: API路由和控制器配置 +- **数据模型**: API请求和响应数据模型 + +# API接口深度分析任务 + +## 任务描述 +请深度分析项目中的API接口,从接口设计、数据格式、错误处理、性能优化、安全控制等维度生成完整的API接口技术文档。 + +## 分析维度 + +### 1. API架构分析 +#### API架构模式 +\`\`\`mermaid +graph TB + subgraph "API网关层" + GW[API网关] + LB[负载均衡器] + end + + subgraph "路由层" + R1[路由管理器] + R2[中间件链] + R3[请求处理器] + end + + subgraph "业务层" + S1[Management服务] + S2[Collector服务] + S3[IDM服务] + end + + subgraph "数据层" + D1[数据访问层] + D2[缓存层] + D3[消息层] + end + + GW --> LB + LB --> R1 + R1 --> R2 + R2 --> R3 + R3 --> S1 + R3 --> S2 + R3 --> S3 + S1 --> D1 + S1 --> D2 + S1 --> D3 + S2 --> D1 + S2 --> D2 + S2 --> D3 + S3 --> D1 + S3 --> D2 + S3 --> D3 +\`\`\` + +#### API架构特点 +- **RESTful架构**: 遵循REST设计原则 +- **分层架构**: 清晰的层次结构 +- **中间件模式**: 可插拔的中间件处理 +- **统一响应**: 统一的响应格式和错误处理 + +### 2. API接口分类分析 +#### 按功能分类 +| 分类 | 接口数量 | 主要功能 | 访问频率 | 安全级别 | +|------|----------|----------|----------|----------| +| 用户管理 | 8 | 用户注册、登录、管理 | 高 | 高 | +| 数据管理 | 12 | 数据CRUD操作 | 高 | 中 | +| 系统配置 | 6 | 配置管理 | 中 | 高 | +| 审计日志 | 4 | 日志查询 | 低 | 高 | +| 健康检查 | 2 | 系统状态检查 | 中 | 低 | + +#### 按HTTP方法分类 +| HTTP方法 | 接口数量 | 主要用途 | 幂等性 | 安全性 | +|----------|----------|----------|--------|--------| +| GET | 15 | 数据查询 | 是 | 安全 | +| POST | 8 | 数据创建 | 否 | 不安全 | +| PUT | 6 | 数据更新 | 是 | 不安全 | +| DELETE | 3 | 数据删除 | 是 | 不安全 | +| PATCH | 2 | 部分更新 | 否 | 不安全 | + +### 3. API接口详细分析 +#### 用户管理API +##### 用户注册 +\`\`\`http +POST /api/v1/auth/register +Content-Type: application/json + +{ + "username": "string", + "email": "string", + "password": "string", + "first_name": "string", + "last_name": "string", + "phone": "string" +} +\`\`\` + +**响应示例**: +\`\`\`json +{ + "code": 201, + "message": "User registered successfully", + "data": { + "id": "uuid", + "username": "string", + "email": "string", + "first_name": "string", + "last_name": "string", + "phone": "string", + "status": "active", + "created_at": "2024-01-01T00:00:00Z" + } +} +\`\`\` + +##### 用户登录 +\`\`\`http +POST /api/v1/auth/login +Content-Type: application/json + +{ + "username": "string", + "password": "string" +} +\`\`\` + +**响应示例**: +\`\`\`json +{ + "code": 200, + "message": "Login successful", + "data": { + "access_token": "string", + "refresh_token": "string", + "expires_in": 3600, + "token_type": "Bearer", + "user": { + "id": "uuid", + "username": "string", + "email": "string", + "roles": ["user"] + } + } +} +\`\`\` + +##### 获取用户列表 +\`\`\`http +GET /api/v1/users?page=1&size=10&status=active +Authorization: Bearer +\`\`\` + +**响应示例**: +\`\`\`json +{ + "code": 200, + "message": "Users retrieved successfully", + "data": { + "users": [ + { + "id": "uuid", + "username": "string", + "email": "string", + "first_name": "string", + "last_name": "string", + "status": "active", + "created_at": "2024-01-01T00:00:00Z" + } + ], + "pagination": { + "page": 1, + "size": 10, + "total": 100, + "pages": 10 + } + } +} +\`\`\` + +#### 数据管理API +##### 提交数据 +\`\`\`http +POST /api/v1/data +Content-Type: application/json +Authorization: Bearer + +{ + "type": "string", + "title": "string", + "content": "string", + "metadata": { + "key": "value" + }, + "tags": ["tag1", "tag2"] +} +\`\`\` + +**响应示例**: +\`\`\`json +{ + "code": 201, + "message": "Data submitted successfully", + "data": { + "id": "uuid", + "type": "string", + "title": "string", + "content": "string", + "metadata": { + "key": "value" + }, + "tags": ["tag1", "tag2"], + "status": "active", + "created_at": "2024-01-01T00:00:00Z" + } +} +\`\`\` + +##### 获取数据详情 +\`\`\`http +GET /api/v1/data/{id} +Authorization: Bearer +\`\`\` + +**响应示例**: +\`\`\`json +{ + "code": 200, + "message": "Data retrieved successfully", + "data": { + "id": "uuid", + "user_id": "uuid", + "type": "string", + "title": "string", + "content": "string", + "metadata": { + "key": "value" + }, + "tags": [ + { + "id": "uuid", + "name": "tag1", + "color": "#007bff" + } + ], + "status": "active", + "created_at": "2024-01-01T00:00:00Z", + "updated_at": "2024-01-01T00:00:00Z" + } +} +\`\`\` + +##### 搜索数据 +\`\`\`http +POST /api/v1/data/search +Content-Type: application/json +Authorization: Bearer + +{ + "query": "string", + "filters": { + "type": "string", + "status": "active", + "tags": ["tag1"], + "date_range": { + "start": "2024-01-01T00:00:00Z", + "end": "2024-12-31T23:59:59Z" + } + }, + "sort": { + "field": "created_at", + "order": "desc" + }, + "pagination": { + "page": 1, + "size": 10 + } +} +\`\`\` + +**响应示例**: +\`\`\`json +{ + "code": 200, + "message": "Data search completed", + "data": { + "results": [ + { + "id": "uuid", + "type": "string", + "title": "string", + "content": "string", + "metadata": { + "key": "value" + }, + "tags": ["tag1", "tag2"], + "status": "active", + "created_at": "2024-01-01T00:00:00Z" + } + ], + "pagination": { + "page": 1, + "size": 10, + "total": 50, + "pages": 5 + } + } +} +\`\`\` + +#### 系统配置API +##### 获取配置 +\`\`\`http +GET /api/v1/configurations +Authorization: Bearer +\`\`\` + +**响应示例**: +\`\`\`json +{ + "code": 200, + "message": "Configurations retrieved successfully", + "data": { + "configurations": [ + { + "id": "uuid", + "key": "app.name", + "value": "My Application", + "description": "Application name", + "data_type": "string", + "is_system": false, + "created_at": "2024-01-01T00:00:00Z", + "updated_at": "2024-01-01T00:00:00Z" + } + ] + } +} +\`\`\` + +##### 更新配置 +\`\`\`http +PUT /api/v1/configurations/{id} +Content-Type: application/json +Authorization: Bearer + +{ + "value": "string", + "description": "string" +} +\`\`\` + +**响应示例**: +\`\`\`json +{ + "code": 200, + "message": "Configuration updated successfully", + "data": { + "id": "uuid", + "key": "app.name", + "value": "string", + "description": "string", + "data_type": "string", + "is_system": false, + "created_at": "2024-01-01T00:00:00Z", + "updated_at": "2024-01-01T00:00:00Z" + } +} +\`\`\` + +### 4. 数据模型分析 +#### 请求模型 +\`\`\`go +// 用户注册请求 +type RegisterRequest struct { + Username string \`json:"username" validate:"required,min=3,max=50"\` + Email string \`json:"email" validate:"required,email"\` + Password string \`json:"password" validate:"required,min=8,max=100"\` + FirstName string \`json:"first_name" validate:"max=50"\` + LastName string \`json:"last_name" validate:"max=50"\` + Phone string \`json:"phone" validate:"max=20"\` +} + +// 用户登录请求 +type LoginRequest struct { + Username string \`json:"username" validate:"required"\` + Password string \`json:"password" validate:"required"\` +} + +// 数据提交请求 +type SubmitDataRequest struct { + Type string \`json:"type" validate:"required,max=50"\` + Title string \`json:"title" validate:"required,max=200"\` + Content string \`json:"content" validate:"max=10000"\` + Metadata map[string]interface{} \`json:"metadata"\` + Tags []string \`json:"tags"\` +} + +// 数据搜索请求 +type SearchDataRequest struct { + Query string \`json:"query"\` + Filters map[string]interface{} \`json:"filters"\` + Sort map[string]string \`json:"sort"\` + Pagination PaginationRequest \`json:"pagination"\` +} + +// 分页请求 +type PaginationRequest struct { + Page int \`json:"page" validate:"min=1"\` + Size int \`json:"size" validate:"min=1,max=100"\` +} +\`\`\` + +#### 响应模型 +\`\`\`go +// 统一响应结构 +type APIResponse struct { + Code int \`json:"code"\` + Message string \`json:"message"\` + Data interface{} \`json:"data,omitempty"\` + Error string \`json:"error,omitempty"\` +} + +// 用户响应 +type UserResponse struct { + ID uuid.UUID \`json:"id"\` + Username string \`json:"username"\` + Email string \`json:"email"\` + FirstName string \`json:"first_name"\` + LastName string \`json:"last_name"\` + Phone string \`json:"phone"\` + Status string \`json:"status"\` + CreatedAt time.Time \`json:"created_at"\` +} + +// 数据响应 +type DataResponse struct { + ID uuid.UUID \`json:"id"\` + UserID uuid.UUID \`json:"user_id"\` + Type string \`json:"type"\` + Title string \`json:"title"\` + Content string \`json:"content"\` + Metadata map[string]interface{} \`json:"metadata"\` + Tags []TagResponse \`json:"tags"\` + Status string \`json:"status"\` + CreatedAt time.Time \`json:"created_at"\` + UpdatedAt time.Time \`json:"updated_at"\` +} + +// 标签响应 +type TagResponse struct { + ID uuid.UUID \`json:"id"\` + Name string \`json:"name"\` + Description string \`json:"description"\` + Color string \`json:"color"\` +} + +// 分页响应 +type PaginationResponse struct { + Page int \`json:"page"\` + Size int \`json:"size"\` + Total int \`json:"total"\` + Pages int \`json:"pages"\` +} + +// 用户列表响应 +type UserListResponse struct { + Users []UserResponse \`json:"users"\` + Pagination PaginationResponse \`json:"pagination"\` +} + +// 数据搜索响应 +type DataSearchResponse struct { + Results []DataResponse \`json:"results"\` + Pagination PaginationResponse \`json:"pagination"\` +} +\`\`\` + +### 5. 错误处理分析 +#### 错误码定义 +| 错误码 | 错误类型 | HTTP状态码 | 描述 | +|--------|----------|------------|------| +| 200 | SUCCESS | 200 | 请求成功 | +| 201 | CREATED | 201 | 资源创建成功 | +| 400 | BAD_REQUEST | 400 | 请求参数错误 | +| 401 | UNAUTHORIZED | 401 | 未授权访问 | +| 403 | FORBIDDEN | 403 | 禁止访问 | +| 404 | NOT_FOUND | 404 | 资源不存在 | +| 409 | CONFLICT | 409 | 资源冲突 | +| 422 | VALIDATION_ERROR | 422 | 数据验证失败 | +| 500 | INTERNAL_ERROR | 500 | 服务器内部错误 | + +#### 错误响应格式 +\`\`\`json +{ + "code": 400, + "message": "Bad request", + "error": "Invalid request parameters", + "details": { + "field": "username", + "message": "Username is required" + } +} +\`\`\` + +#### 错误处理中间件 +\`\`\`go +// 错误处理中间件 +func ErrorHandler() gin.HandlerFunc { + return func(c *gin.Context) { + c.Next() + + // 获取最后一个错误 + err := c.Errors.Last() + if err == nil { + return + } + + // 根据错误类型返回相应的响应 + switch e := err.Err.(type) { + case *ValidationError: + c.JSON(http.StatusUnprocessableEntity, APIResponse{ + Code: 422, + Message: "Validation error", + Error: e.Error(), + Details: e.Details, + }) + case *NotFoundError: + c.JSON(http.StatusNotFound, APIResponse{ + Code: 404, + Message: "Resource not found", + Error: e.Error(), + }) + case *UnauthorizedError: + c.JSON(http.StatusUnauthorized, APIResponse{ + Code: 401, + Message: "Unauthorized", + Error: e.Error(), + }) + case *ForbiddenError: + c.JSON(http.StatusForbidden, APIResponse{ + Code: 403, + Message: "Forbidden", + Error: e.Error(), + }) + default: + c.JSON(http.StatusInternalServerError, APIResponse{ + Code: 500, + Message: "Internal server error", + Error: e.Error(), + }) + } + } +} +\`\`\` + +### 6. 安全控制分析 +#### 认证机制 +\`\`\`go +// JWT认证中间件 +func AuthMiddleware() gin.HandlerFunc { + return func(c *gin.Context) { + token := c.GetHeader("Authorization") + if token == "" { + c.AbortWithStatusJSON(http.StatusUnauthorized, APIResponse{ + Code: 401, + Message: "Unauthorized", + Error: "Missing authorization token", + }) + return + } + + // 移除Bearer前缀 + token = strings.TrimPrefix(token, "Bearer ") + + // 验证token + claims, err := ValidateToken(token) + if err != nil { + c.AbortWithStatusJSON(http.StatusUnauthorized, APIResponse{ + Code: 401, + Message: "Unauthorized", + Error: "Invalid token", + }) + return + } + + // 将用户信息存储到上下文 + c.Set("user_id", claims.UserID) + c.Set("username", claims.Username) + c.Set("roles", claims.Roles) + + c.Next() + } +} +\`\`\` + +#### 权限控制 +\`\`\`go +// 权限检查中间件 +func PermissionCheck(resource, action string) gin.HandlerFunc { + return func(c *gin.Context) { + userID, exists := c.Get("user_id") + if !exists { + c.AbortWithStatusJSON(http.StatusUnauthorized, APIResponse{ + Code: 401, + Message: "Unauthorized", + Error: "User not authenticated", + }) + return + } + + // 检查用户权限 + hasPermission, err := CheckUserPermission(userID.(uuid.UUID), resource, action) + if err != nil { + c.AbortWithStatusJSON(http.StatusInternalServerError, APIResponse{ + Code: 500, + Message: "Internal server error", + Error: "Failed to check permissions", + }) + return + } + + if !hasPermission { + c.AbortWithStatusJSON(http.StatusForbidden, APIResponse{ + Code: 403, + Message: "Forbidden", + Error: "Insufficient permissions", + }) + return + } + + c.Next() + } +} +\`\`\` + +#### 输入验证 +\`\`\`go +// 请求验证中间件 +func ValidateRequest(model interface{}) gin.HandlerFunc { + return func(c *gin.Context) { + if err := c.ShouldBindJSON(model); err != nil { + var validationErrors []map[string]string + + // 处理验证错误 + if errs, ok := err.(validator.ValidationErrors); ok { + for _, e := range errs { + validationErrors = append(validationErrors, map[string]string{ + "field": e.Field(), + "message": getValidationErrorMessage(e), + }) + } + } + + c.AbortWithStatusJSON(http.StatusUnprocessableEntity, APIResponse{ + Code: 422, + Message: "Validation error", + Error: "Invalid request parameters", + Details: validationErrors, + }) + return + } + + c.Set("validated_request", model) + c.Next() + } +} +\`\`\` + +### 7. 性能优化分析 +#### 缓存策略 +| 缓存类型 | 缓存数据 | 过期时间 | 缓存键 | +|----------|----------|----------|--------| +| 用户信息 | 用户基本资料 | 30分钟 | user:{id} | +| 配置信息 | 系统配置 | 1小时 | config:{key} | +| API响应 | 查询结果 | 5分钟 | api:{path}:{hash} | +| 权限信息 | 用户权限 | 15分钟 | permissions:{id} | + +#### 限流控制 +\`\`\`go +// 限流中间件 +func RateLimitMiddleware() gin.HandlerFunc { + limiter := rate.NewLimiter(rate.Limit(100), 200) // 100 requests per second, burst 200 + + return func(c *gin.Context) { + if !limiter.Allow() { + c.AbortWithStatusJSON(http.StatusTooManyRequests, APIResponse{ + Code: 429, + Message: "Too many requests", + Error: "Rate limit exceeded", + }) + return + } + c.Next() + } +} +\`\`\` + +#### 压缩优化 +\`\`\`go +// 压缩中间件 +func CompressionMiddleware() gin.HandlerFunc { + return func(c *gin.Context) { + // 检查客户端是否支持压缩 + if strings.Contains(c.GetHeader("Accept-Encoding"), "gzip") { + c.Header("Content-Encoding", "gzip") + gz := gzip.NewWriter(c.Writer) + defer gz.Close() + c.Writer = &gzipWriter{Writer: gz, ResponseWriter: c.Writer} + } + c.Next() + } +} +\`\`\` + +### 8. API文档分析 +#### Swagger/OpenAPI文档 +\`\`\`yaml +openapi: 3.0.0 +info: + title: Project API + version: 1.0.0 + description: Project API documentation + +servers: + - url: https://api.example.com/v1 + description: Production server + - url: https://staging-api.example.com/v1 + description: Staging server + +paths: + /auth/register: + post: + summary: Register a new user + tags: + - Authentication + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/RegisterRequest' + responses: + '201': + description: User registered successfully + content: + application/json: + schema: + $ref: '#/components/schemas/UserResponse' + '400': + description: Bad request + '409': + description: User already exists + + /auth/login: + post: + summary: User login + tags: + - Authentication + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/LoginRequest' + responses: + '200': + description: Login successful + content: + application/json: + schema: + $ref: '#/components/schemas/LoginResponse' + '401': + description: Invalid credentials + +components: + schemas: + RegisterRequest: + type: object + required: + - username + - email + - password + properties: + username: + type: string + minLength: 3 + maxLength: 50 + email: + type: string + format: email + password: + type: string + minLength: 8 + maxLength: 100 + first_name: + type: string + maxLength: 50 + last_name: + type: string + maxLength: 50 + phone: + type: string + maxLength: 20 + + LoginRequest: + type: object + required: + - username + - password + properties: + username: + type: string + password: + type: string + + UserResponse: + type: object + properties: + id: + type: string + format: uuid + username: + type: string + email: + type: string + format: email + first_name: + type: string + last_name: + type: string + phone: + type: string + status: + type: string + enum: [active, inactive, suspended] + created_at: + type: string + format: date-time + + LoginResponse: + type: object + properties: + access_token: + type: string + refresh_token: + type: string + expires_in: + type: integer + token_type: + type: string + user: + $ref: '#/components/schemas/UserResponse' +\`\`\` + +#### API版本控制 +\`\`\`go +// 版本控制中间件 +func VersionMiddleware() gin.HandlerFunc { + return func(c *gin.Context) { + version := c.GetHeader("API-Version") + if version == "" { + version = "v1" // 默认版本 + } + + // 验证版本 + if !isValidVersion(version) { + c.AbortWithStatusJSON(http.StatusBadRequest, APIResponse{ + Code: 400, + Message: "Bad request", + Error: "Invalid API version", + }) + return + } + + c.Set("api_version", version) + c.Next() + } +} +\`\`\` + +## 输出格式要求 + +生成完整的API接口分析文档: + +### 文档结构 +\`\`\`markdown +# {项目名称} API接口分析 + +## API架构概览 + +### API架构模式 +\`\`\`mermaid +graph TB + subgraph "API网关层" + GW[API网关] + LB[负载均衡器] + end + + subgraph "路由层" + R1[路由管理器] + R2[中间件链] + R3[请求处理器] + end + + subgraph "业务层" + S1[Management服务] + S2[Collector服务] + S3[IDM服务] + end + + subgraph "数据层" + D1[数据访问层] + D2[缓存层] + D3[消息层] + end + + GW --> LB + LB --> R1 + R1 --> R2 + R2 --> R3 + R3 --> S1 + R3 --> S2 + R3 --> S3 + S1 --> D1 + S1 --> D2 + S1 --> D3 + S2 --> D1 + S2 --> D2 + S2 --> D3 + S3 --> D1 + S3 --> D2 + S3 --> D3 +\`\`\` + +### API架构特点 +- **RESTful架构**: 遵循REST设计原则 +- **分层架构**: 清晰的层次结构 +- **中间件模式**: 可插拔的中间件处理 +- **统一响应**: 统一的响应格式和错误处理 + +## API接口分类 + +### 按功能分类 +| 分类 | 接口数量 | 主要功能 | 访问频率 | 安全级别 | +|------|----------|----------|----------|----------| +| 用户管理 | 8 | 用户注册、登录、管理 | 高 | 高 | +| 数据管理 | 12 | 数据CRUD操作 | 高 | 中 | +| 系统配置 | 6 | 配置管理 | 中 | 高 | +| 审计日志 | 4 | 日志查询 | 低 | 高 | +| 健康检查 | 2 | 系统状态检查 | 中 | 低 | + +### 按HTTP方法分类 +| HTTP方法 | 接口数量 | 主要用途 | 幂等性 | 安全性 | +|----------|----------|----------|--------|--------| +| GET | 15 | 数据查询 | 是 | 安全 | +| POST | 8 | 数据创建 | 否 | 不安全 | +| PUT | 6 | 数据更新 | 是 | 不安全 | +| DELETE | 3 | 数据删除 | 是 | 不安全 | +| PATCH | 2 | 部分更新 | 否 | 不安全 | + +## 用户管理API + +### 用户注册 +#### 接口信息 +- **URL**: \`POST /api/v1/auth/register\` +- **描述**: 注册新用户 +- **认证**: 不需要 +- **权限**: 公开访问 + +#### 请求参数 +\`\`\`json +{ + "username": "string", + "email": "string", + "password": "string", + "first_name": "string", + "last_name": "string", + "phone": "string" +} +\`\`\` + +**参数说明**: +| 参数 | 类型 | 必填 | 约束 | 描述 | +|------|------|------|------|------| +| username | string | 是 | 3-50字符 | 用户名 | +| email | string | 是 | 邮箱格式 | 邮箱地址 | +| password | string | 是 | 8-100字符 | 密码 | +| first_name | string | 否 | 最大50字符 | 名 | +| last_name | string | 否 | 最大50字符 | 姓 | +| phone | string | 否 | 最大20字符 | 电话号码 | + +#### 响应示例 +\`\`\`json +{ + "code": 201, + "message": "User registered successfully", + "data": { + "id": "uuid", + "username": "string", + "email": "string", + "first_name": "string", + "last_name": "string", + "phone": "string", + "status": "active", + "created_at": "2024-01-01T00:00:00Z" + } +} +\`\`\` + +#### 错误码 +| 错误码 | HTTP状态码 | 描述 | +|--------|------------|------| +| 201 | 201 | 注册成功 | +| 400 | 400 | 请求参数错误 | +| 409 | 409 | 用户名或邮箱已存在 | +| 422 | 422 | 数据验证失败 | +| 500 | 500 | 服务器内部错误 | + +### 用户登录 +#### 接口信息 +- **URL**: \`POST /api/v1/auth/login\` +- **描述**: 用户登录 +- **认证**: 不需要 +- **权限**: 公开访问 + +#### 请求参数 +\`\`\`json +{ + "username": "string", + "password": "string" +} +\`\`\` + +**参数说明**: +| 参数 | 类型 | 必填 | 约束 | 描述 | +|------|------|------|------|------| +| username | string | 是 | - | 用户名 | +| password | string | 是 | - | 密码 | + +#### 响应示例 +\`\`\`json +{ + "code": 200, + "message": "Login successful", + "data": { + "access_token": "string", + "refresh_token": "string", + "expires_in": 3600, + "token_type": "Bearer", + "user": { + "id": "uuid", + "username": "string", + "email": "string", + "roles": ["user"] + } + } +} +\`\`\` + +#### 错误码 +| 错误码 | HTTP状态码 | 描述 | +|--------|------------|------| +| 200 | 200 | 登录成功 | +| 400 | 400 | 请求参数错误 | +| 401 | 401 | 用户名或密码错误 | +| 422 | 422 | 数据验证失败 | +| 500 | 500 | 服务器内部错误 | + +### 获取用户列表 +#### 接口信息 +- **URL**: \`GET /api/v1/users?page=1&size=10&status=active\` +- **描述**: 获取用户列表 +- **认证**: 需要Bearer Token +- **权限**: 需要user:read权限 + +#### 请求参数 +| 参数 | 类型 | 必填 | 默认值 | 描述 | +|------|------|------|--------|------| +| page | int | 否 | 1 | 页码 | +| size | int | 否 | 10 | 每页大小 | +| status | string | 否 | - | 用户状态过滤 | +| search | string | 否 | - | 搜索关键词 | + +#### 响应示例 +\`\`\`json +{ + "code": 200, + "message": "Users retrieved successfully", + "data": { + "users": [ + { + "id": "uuid", + "username": "string", + "email": "string", + "first_name": "string", + "last_name": "string", + "status": "active", + "created_at": "2024-01-01T00:00:00Z" + } + ], + "pagination": { + "page": 1, + "size": 10, + "total": 100, + "pages": 10 + } + } +} +\`\`\` + +#### 错误码 +| 错误码 | HTTP状态码 | 描述 | +|--------|------------|------| +| 200 | 200 | 获取成功 | +| 400 | 400 | 请求参数错误 | +| 401 | 401 | 未授权访问 | +| 403 | 403 | 权限不足 | +| 500 | 500 | 服务器内部错误 | + +## 数据管理API + +### 提交数据 +#### 接口信息 +- **URL**: \`POST /api/v1/data\` +- **描述**: 提交数据 +- **认证**: 需要Bearer Token +- **权限**: 需要data:create权限 + +#### 请求参数 +\`\`\`json +{ + "type": "string", + "title": "string", + "content": "string", + "metadata": { + "key": "value" + }, + "tags": ["tag1", "tag2"] +} +\`\`\` + +**参数说明**: +| 参数 | 类型 | 必填 | 约束 | 描述 | +|------|------|------|------|------| +| type | string | 是 | 最大50字符 | 数据类型 | +| title | string | 是 | 最大200字符 | 数据标题 | +| content | string | 否 | 最大10000字符 | 数据内容 | +| metadata | object | 否 | - | 元数据 | +| tags | array | 否 | - | 标签列表 | + +#### 响应示例 +\`\`\`json +{ + "code": 201, + "message": "Data submitted successfully", + "data": { + "id": "uuid", + "type": "string", + "title": "string", + "content": "string", + "metadata": { + "key": "value" + }, + "tags": ["tag1", "tag2"], + "status": "active", + "created_at": "2024-01-01T00:00:00Z" + } +} +\`\`\` + +#### 错误码 +| 错误码 | HTTP状态码 | 描述 | +|--------|------------|------| +| 201 | 201 | 提交成功 | +| 400 | 400 | 请求参数错误 | +| 401 | 401 | 未授权访问 | +| 403 | 403 | 权限不足 | +| 422 | 422 | 数据验证失败 | +| 500 | 500 | 服务器内部错误 | + +### 获取数据详情 +#### 接口信息 +- **URL**: \`GET /api/v1/data/{id}\` +- **描述**: 获取数据详情 +- **认证**: 需要Bearer Token +- **权限**: 需要data:read权限 + +#### 路径参数 +| 参数 | 类型 | 必填 | 描述 | +|------|------|------|------| +| id | uuid | 是 | 数据ID | + +#### 响应示例 +\`\`\`json +{ + "code": 200, + "message": "Data retrieved successfully", + "data": { + "id": "uuid", + "user_id": "uuid", + "type": "string", + "title": "string", + "content": "string", + "metadata": { + "key": "value" + }, + "tags": [ + { + "id": "uuid", + "name": "tag1", + "color": "#007bff" + } + ], + "status": "active", + "created_at": "2024-01-01T00:00:00Z", + "updated_at": "2024-01-01T00:00:00Z" + } +} +\`\`\` + +#### 错误码 +| 错误码 | HTTP状态码 | 描述 | +|--------|------------|------| +| 200 | 200 | 获取成功 | +| 400 | 400 | 请求参数错误 | +| 401 | 401 | 未授权访问 | +| 403 | 403 | 权限不足 | +| 404 | 404 | 数据不存在 | +| 500 | 500 | 服务器内部错误 | + +### 搜索数据 +#### 接口信息 +- **URL**: \`POST /api/v1/data/search\` +- **描述**: 搜索数据 +- **认证**: 需要Bearer Token +- **权限**: 需要data:read权限 + +#### 请求参数 +\`\`\`json +{ + "query": "string", + "filters": { + "type": "string", + "status": "active", + "tags": ["tag1"], + "date_range": { + "start": "2024-01-01T00:00:00Z", + "end": "2024-12-31T23:59:59Z" + } + }, + "sort": { + "field": "created_at", + "order": "desc" + }, + "pagination": { + "page": 1, + "size": 10 + } +} +\`\`\` + +**参数说明**: +| 参数 | 类型 | 必填 | 描述 | +|------|------|------|------| +| query | string | 否 | 搜索关键词 | +| filters | object | 否 | 过滤条件 | +| sort | object | 否 | 排序条件 | +| pagination | object | 否 | 分页参数 | + +#### 响应示例 +\`\`\`json +{ + "code": 200, + "message": "Data search completed", + "data": { + "results": [ + { + "id": "uuid", + "type": "string", + "title": "string", + "content": "string", + "metadata": { + "key": "value" + }, + "tags": ["tag1", "tag2"], + "status": "active", + "created_at": "2024-01-01T00:00:00Z" + } + ], + "pagination": { + "page": 1, + "size": 10, + "total": 50, + "pages": 5 + } + } +} +\`\`\` + +#### 错误码 +| 错误码 | HTTP状态码 | 描述 | +|--------|------------|------| +| 200 | 200 | 搜索成功 | +| 400 | 400 | 请求参数错误 | +| 401 | 401 | 未授权访问 | +| 403 | 403 | 权限不足 | +| 422 | 422 | 数据验证失败 | +| 500 | 500 | 服务器内部错误 | + +## 系统配置API + +### 获取配置 +#### 接口信息 +- **URL**: \`GET /api/v1/configurations\` +- **描述**: 获取系统配置 +- **认证**: 需要Bearer Token +- **权限**: 需要config:read权限 + +#### 响应示例 +\`\`\`json +{ + "code": 200, + "message": "Configurations retrieved successfully", + "data": { + "configurations": [ + { + "id": "uuid", + "key": "app.name", + "value": "My Application", + "description": "Application name", + "data_type": "string", + "is_system": false, + "created_at": "2024-01-01T00:00:00Z", + "updated_at": "2024-01-01T00:00:00Z" + } + ] + } +} +\`\`\` + +#### 错误码 +| 错误码 | HTTP状态码 | 描述 | +|--------|------------|------| +| 200 | 200 | 获取成功 | +| 401 | 401 | 未授权访问 | +| 403 | 403 | 权限不足 | +| 500 | 500 | 服务器内部错误 | + +### 更新配置 +#### 接口信息 +- **URL**: \`PUT /api/v1/configurations/{id}\` +- **描述**: 更新系统配置 +- **认证**: 需要Bearer Token +- **权限**: 需要config:update权限 + +#### 请求参数 +\`\`\`json +{ + "value": "string", + "description": "string" +} +\`\`\` + +**参数说明**: +| 参数 | 类型 | 必填 | 描述 | +|------|------|------|------| +| value | string | 是 | 配置值 | +| description | string | 否 | 配置描述 | + +#### 响应示例 +\`\`\`json +{ + "code": 200, + "message": "Configuration updated successfully", + "data": { + "id": "uuid", + "key": "app.name", + "value": "string", + "description": "string", + "data_type": "string", + "is_system": false, + "created_at": "2024-01-01T00:00:00Z", + "updated_at": "2024-01-01T00:00:00Z" + } +} +\`\`\` + +#### 错误码 +| 错误码 | HTTP状态码 | 描述 | +|--------|------------|------| +| 200 | 200 | 更新成功 | +| 400 | 400 | 请求参数错误 | +| 401 | 401 | 未授权访问 | +| 403 | 403 | 权限不足 | +| 404 | 404 | 配置不存在 | +| 422 | 422 | 数据验证失败 | +| 500 | 500 | 服务器内部错误 | + +## 数据模型分析 + +### 请求模型 +\`\`\`go +// 用户注册请求 +type RegisterRequest struct { + Username string \`json:"username" validate:"required,min=3,max=50"\` + Email string \`json:"email" validate:"required,email"\` + Password string \`json:"password" validate:"required,min=8,max=100"\` + FirstName string \`json:"first_name" validate:"max=50"\` + LastName string \`json:"last_name" validate:"max=50"\` + Phone string \`json:"phone" validate:"max=20"\` +} + +// 用户登录请求 +type LoginRequest struct { + Username string \`json:"username" validate:"required"\` + Password string \`json:"password" validate:"required"\` +} + +// 数据提交请求 +type SubmitDataRequest struct { + Type string \`json:"type" validate:"required,max=50"\` + Title string \`json:"title" validate:"required,max=200"\` + Content string \`json:"content" validate:"max=10000"\` + Metadata map[string]interface{} \`json:"metadata"\` + Tags []string \`json:"tags"\` +} + +// 数据搜索请求 +type SearchDataRequest struct { + Query string \`json:"query"\` + Filters map[string]interface{} \`json:"filters"\` + Sort map[string]string \`json:"sort"\` + Pagination PaginationRequest \`json:"pagination"\` +} + +// 分页请求 +type PaginationRequest struct { + Page int \`json:"page" validate:"min=1"\` + Size int \`json:"size" validate:"min=1,max=100"\` +} +\`\`\` + +### 响应模型 +\`\`\`go +// 统一响应结构 +type APIResponse struct { + Code int \`json:"code"\` + Message string \`json:"message"\` + Data interface{} \`json:"data,omitempty"\` + Error string \`json:"error,omitempty"\` +} + +// 用户响应 +type UserResponse struct { + ID uuid.UUID \`json:"id"\` + Username string \`json:"username"\` + Email string \`json:"email"\` + FirstName string \`json:"first_name"\` + LastName string \`json:"last_name"\` + Phone string \`json:"phone"\` + Status string \`json:"status"\` + CreatedAt time.Time \`json:"created_at"\` +} + +// 数据响应 +type DataResponse struct { + ID uuid.UUID \`json:"id"\` + UserID uuid.UUID \`json:"user_id"\` + Type string \`json:"type"\` + Title string \`json:"title"\` + Content string \`json:"content"\` + Metadata map[string]interface{} \`json:"metadata"\` + Tags []TagResponse \`json:"tags"\` + Status string \`json:"status"\` + CreatedAt time.Time \`json:"created_at"\` + UpdatedAt time.Time \`json:"updated_at"\` +} + +// 标签响应 +type TagResponse struct { + ID uuid.UUID \`json:"id"\` + Name string \`json:"name"\` + Description string \`json:"description"\` + Color string \`json:"color"\` +} + +// 分页响应 +type PaginationResponse struct { + Page int \`json:"page"\` + Size int \`json:"size"\` + Total int \`json:"total"\` + Pages int \`json:"pages"\` +} + +// 用户列表响应 +type UserListResponse struct { + Users []UserResponse \`json:"users"\` + Pagination PaginationResponse \`json:"pagination"\` +} + +// 数据搜索响应 +type DataSearchResponse struct { + Results []DataResponse \`json:"results"\` + Pagination PaginationResponse \`json:"pagination"\` +} +\`\`\` + +## 错误处理分析 + +### 错误码定义 +| 错误码 | 错误类型 | HTTP状态码 | 描述 | +|--------|----------|------------|------| +| 200 | SUCCESS | 200 | 请求成功 | +| 201 | CREATED | 201 | 资源创建成功 | +| 400 | BAD_REQUEST | 400 | 请求参数错误 | +| 401 | UNAUTHORIZED | 401 | 未授权访问 | +| 403 | FORBIDDEN | 403 | 禁止访问 | +| 404 | NOT_FOUND | 404 | 资源不存在 | +| 409 | CONFLICT | 409 | 资源冲突 | +| 422 | VALIDATION_ERROR | 422 | 数据验证失败 | +| 500 | INTERNAL_ERROR | 500 | 服务器内部错误 | + +### 错误响应格式 +\`\`\`json +{ + "code": 400, + "message": "Bad request", + "error": "Invalid request parameters", + "details": { + "field": "username", + "message": "Username is required" + } +} +\`\`\` + +### 错误处理策略 +- **参数验证**: 请求参数格式和有效性验证 +- **业务验证**: 业务规则和约束验证 +- **权限验证**: 用户权限和访问控制验证 +- **异常处理**: 系统异常和错误处理 +- **日志记录**: 错误日志记录和监控 + +## 安全控制分析 + +### 认证机制 +- **JWT认证**: 基于JWT的无状态认证 +- **Token刷新**: 支持访问令牌刷新 +- **密码安全**: 密码哈希存储和强度验证 +- **会话管理**: 会话超时和失效处理 + +### 权限控制 +- **RBAC模型**: 基于角色的访问控制 +- **资源权限**: 细粒度的资源权限控制 +- **权限检查**: 中间件级别的权限验证 +- **权限缓存**: 权限信息缓存优化 + +### 输入验证 +- **参数验证**: 请求参数格式和类型验证 +- **业务验证**: 业务规则和约束验证 +- **SQL注入防护**: 参数化查询和输入过滤 +- **XSS防护**: 输出编码和输入过滤 + +## 性能优化分析 + +### 缓存策略 +| 缓存类型 | 缓存数据 | 过期时间 | 缓存键 | +|----------|----------|----------|--------| +| 用户信息 | 用户基本资料 | 30分钟 | user:{id} | +| 配置信息 | 系统配置 | 1小时 | config:{key} | +| API响应 | 查询结果 | 5分钟 | api:{path}:{hash} | +| 权限信息 | 用户权限 | 15分钟 | permissions:{id} | + +### 限流控制 +- **请求限流**: 基于IP和用户的请求限流 +- **并发控制**: 最大并发连接数控制 +- **熔断保护**: 服务熔断和快速失败 +- **降级处理**: 核心功能降级处理 + +### 压缩优化 +- **响应压缩**: Gzip压缩响应数据 +- **传输优化**: 减少数据传输量 +- **缓存优化**: 客户端缓存策略 +- **CDN加速**: 静态资源CDN分发 + +## API文档分析 + +### Swagger/OpenAPI文档 +- **接口定义**: 完整的API接口定义 +- **数据模型**: 请求和响应数据模型 +- **错误处理**: 错误码和错误响应定义 +- **示例代码**: 接口调用示例代码 + +### 版本控制 +- **版本管理**: API版本管理和兼容性 +- **向后兼容**: 保持向后兼容性 +- **废弃通知**: 接口废弃和迁移通知 +- **文档更新**: 文档版本同步更新 + +## 总结 + +### API设计特点 +- {API设计主要特点总结} +- {接口分类和组织总结} +- {数据模型设计总结} +- {错误处理机制总结} + +### 优化建议 +- {API性能优化建议} +- {安全控制加强建议} +- {文档完善建议} +- {版本管理建议} +\`\`\` + +## 特别注意事项 +1. 必须基于实际的代码和配置进行分析,不能虚构API接口 +2. 重点分析核心业务API和关键接口设计 +3. 关注API安全性和性能优化 +4. 识别API设计中的问题和改进空间 +5. 提供实用的API使用和集成建议 + +## 输出文件命名 +\`${WIKI_OUTPUT_DIR}07_{PROJECT_NAME}_API_Interface.md\` +注意:如果${WIKI_OUTPUT_DIR} 目录不存在,则创建。 + +## 示例输出特征 +基于项目的API分析特征: +- 详细的API接口定义和参数说明 +- 完整的数据模型和响应格式定义 +- 全面的错误处理和安全控制机制 +- 具体的性能优化和缓存策略 +- 实用的API文档和版本管理建议` diff --git a/src/core/tools/helpers/wiki-prompts/subtasks/08_Deploy_Analysis.ts b/src/core/tools/helpers/wiki-prompts/subtasks/08_Deploy_Analysis.ts new file mode 100644 index 0000000000..bf9451432c --- /dev/null +++ b/src/core/tools/helpers/wiki-prompts/subtasks/08_Deploy_Analysis.ts @@ -0,0 +1,1315 @@ +export const DEPLOY_ANALYSIS_TEMPLATE = `# 部署分析 + +## 使用场景 +从代码仓库中分析项目的部署架构、流程、配置等,生成详细的部署技术文档。 + +## 输入要求 +- **完整代码仓库**: 项目的完整源代码 +- **部署配置**: Dockerfile、docker-compose.yml、Kubernetes配置等 +- **CI/CD配置**: GitHub Actions、Jenkins、GitLab CI等配置文件 +- **基础设施配置**: 云服务配置、基础设施即代码等 + +# 部署分析任务 + +## 任务描述 +请深度分析项目的部署架构、流程、配置等,从部署架构、容器化、CI/CD、基础设施、监控等维度生成完整的部署技术文档。 + +## 分析维度 + +### 1. 部署架构分析 +#### 部署架构图 +\`\`\`mermaid +graph TB + subgraph "开发环境" + A[开发机] + B[本地测试] + end + + subgraph "CI/CD流水线" + C[代码仓库] + D[构建服务器] + E[测试服务器] + F[制品仓库] + end + + subgraph "生产环境" + G[负载均衡器] + H[应用服务器] + I[数据库服务器] + J[缓存服务器] + K[监控服务器] + end + + subgraph "云服务" + L[对象存储] + M[CDN] + N[日志服务] + O[监控服务] + end + + A --> C + B --> C + C --> D + D --> E + E --> F + F --> G + G --> H + H --> I + H --> J + H --> K + I --> L + J --> M + K --> N + K --> O +\`\`\` + +#### 部署架构特点 +- **微服务架构**: 服务独立部署和扩展 +- **容器化部署**: Docker容器化部署 +- **云原生架构**: 基于云服务的部署架构 +- **自动化部署**: CI/CD自动化部署流程 + +### 2. 容器化分析 +#### Docker配置 +\`\`\`dockerfile +# Management服务Dockerfile +FROM golang:1.21-alpine AS builder + +WORKDIR /app +COPY go.mod go.sum ./ +RUN go mod download + +COPY . . +RUN CGO_ENABLED=0 GOOS=linux go build -o management ./cmd/management + +FROM alpine:latest +RUN apk --no-cache add ca-certificates +WORKDIR /root/ +COPY --from=builder /app/management . +EXPOSE 8080 +CMD ["./management"] +\`\`\` + +#### Docker Compose配置 +\`\`\`yaml +version: '3.8' + +services: + management: + build: ./cmd/management + ports: + - "8080:8080" + environment: + - DB_HOST=postgres + - DB_PORT=5432 + - DB_NAME=management + - DB_USER=management + - DB_PASSWORD=password + - REDIS_HOST=redis + - REDIS_PORT=6379 + depends_on: + - postgres + - redis + networks: + - app-network + + collector: + build: ./cmd/collector + ports: + - "8081:8081" + environment: + - DB_HOST=postgres + - DB_PORT=5432 + - DB_NAME=collector + - DB_USER=collector + - DB_PASSWORD=password + - PULSAR_HOST=pulsar + - PULSAR_PORT=6650 + depends_on: + - postgres + - pulsar + networks: + - app-network + + idm: + build: ./cmd/idm + ports: + - "8082:8082" + environment: + - DB_HOST=postgres + - DB_PORT=5432 + - DB_NAME=idm + - DB_USER=idm + - DB_PASSWORD=password + - REDIS_HOST=redis + - REDIS_PORT=6379 + depends_on: + - postgres + - redis + networks: + - app-network + + postgres: + image: postgres:15 + environment: + - POSTGRES_DB=app + - POSTGRES_USER=postgres + - POSTGRES_PASSWORD=password + volumes: + - postgres_data:/var/lib/postgresql/data + ports: + - "5432:5432" + networks: + - app-network + + redis: + image: redis:7-alpine + ports: + - "6379:6379" + networks: + - app-network + + pulsar: + image: apachepulsar/pulsar:3.0 + ports: + - "6650:6650" + - "8080:8080" + command: bin/pulsar standalone + networks: + - app-network + +volumes: + postgres_data: + +networks: + app-network: + driver: bridge +\`\`\` + +#### Kubernetes配置 +\`\`\`yaml +# Management服务部署配置 +apiVersion: apps/v1 +kind: Deployment +metadata: + name: management + labels: + app: management +spec: + replicas: 3 + selector: + matchLabels: + app: management + template: + metadata: + labels: + app: management + spec: + containers: + - name: management + image: management:latest + ports: + - containerPort: 8080 + env: + - name: DB_HOST + value: "postgres-service" + - name: DB_PORT + value: "5432" + - name: DB_NAME + value: "management" + - name: DB_USER + value: "management" + - name: DB_PASSWORD + valueFrom: + secretKeyRef: + name: postgres-secret + key: password + - name: REDIS_HOST + value: "redis-service" + - name: REDIS_PORT + value: "6379" + resources: + requests: + memory: "256Mi" + cpu: "250m" + limits: + memory: "512Mi" + cpu: "500m" + livenessProbe: + httpGet: + path: /health + port: 8080 + initialDelaySeconds: 30 + periodSeconds: 10 + readinessProbe: + httpGet: + path: /ready + port: 8080 + initialDelaySeconds: 5 + periodSeconds: 5 +--- +apiVersion: v1 +kind: Service +metadata: + name: management-service +spec: + selector: + app: management + ports: + - protocol: TCP + port: 80 + targetPort: 8080 + type: ClusterIP +\`\`\` + +### 3. CI/CD分析 +#### GitHub Actions配置 +\`\`\`yaml +name: CI/CD Pipeline + +on: + push: + branches: [ main, develop ] + pull_request: + branches: [ main ] + +env: + REGISTRY: ghcr.io + IMAGE_NAME: \${{ github.repository }} + +jobs: + # 代码检查 + lint: + name: Lint Code + runs-on: ubuntu-latest + steps: + - name: Checkout code + uses: actions/checkout@v4 + + - name: Set up Go + uses: actions/setup-go@v4 + with: + go-version: '1.21' + + - name: Lint + run: | + go fmt ./... + go vet ./... + golangci-lint run + + # 单元测试 + test: + name: Run Tests + runs-on: ubuntu-latest + steps: + - name: Checkout code + uses: actions/checkout@v4 + + - name: Set up Go + uses: actions/setup-go@v4 + with: + go-version: '1.21' + + - name: Run tests + run: | + go test -v ./... -coverprofile=coverage.out + go tool cover -html=coverage.out -o coverage.html + + - name: Upload coverage + uses: codecov/codecov-action@v3 + with: + file: ./coverage.out + + # 构建镜像 + build: + name: Build Images + runs-on: ubuntu-latest + needs: [lint, test] + steps: + - name: Checkout code + uses: actions/checkout@v4 + + - name: Set up Docker Buildx + uses: docker/setup-buildx-action@v3 + + - name: Log in to Container Registry + uses: docker/login-action@v3 + with: + registry: \${{ env.REGISTRY }} + username: \${{ github.actor }} + password: \${{ secrets.GITHUB_TOKEN }} + + - name: Extract metadata + id: meta + uses: docker/metadata-action@v5 + with: + images: \${{ env.REGISTRY }}/\${{ env.IMAGE_NAME }} + + - name: Build and push Management image + uses: docker/build-push-action@v5 + with: + context: . + file: ./cmd/management/Dockerfile + push: true + tags: \${{ env.REGISTRY }}/\${{ env.IMAGE_NAME }}-management:latest + labels: \${{ steps.meta.outputs.labels }} + + - name: Build and push Collector image + uses: docker/build-push-action@v5 + with: + context: . + file: ./cmd/collector/Dockerfile + push: true + tags: \${{ env.REGISTRY }}/\${{ env.IMAGE_NAME }}-collector:latest + labels: \${{ steps.meta.outputs.labels }} + + - name: Build and push IDM image + uses: docker/build-push-action@v5 + with: + context: . + file: ./cmd/idm/Dockerfile + push: true + tags: \${{ env.REGISTRY }}/\${{ env.IMAGE_NAME }}-idm:latest + labels: \${{ steps.meta.outputs.labels }} + + # 部署到测试环境 + deploy-test: + name: Deploy to Test + runs-on: ubuntu-latest + needs: build + if: github.ref == 'refs/heads/develop' + environment: test + steps: + - name: Checkout code + uses: actions/checkout@v4 + + - name: Set up kubectl + uses: azure/setup-kubectl@v3 + with: + version: '1.28.0' + + - name: Configure kubeconfig + run: | + mkdir -p \$HOME/.kube + echo "\${{ secrets.KUBE_CONFIG_TEST }}" | base64 -d > \$HOME/.kube/config + + - name: Deploy to test environment + run: | + kubectl apply -f k8s/test/ + kubectl rollout status deployment/management + kubectl rollout status deployment/collector + kubectl rollout status deployment/idm + + # 部署到生产环境 + deploy-prod: + name: Deploy to Production + runs-on: ubuntu-latest + needs: build + if: github.ref == 'refs/heads/main' + environment: production + steps: + - name: Checkout code + uses: actions/checkout@v4 + + - name: Set up kubectl + uses: azure/setup-kubectl@v3 + with: + version: '1.28.0' + + - name: Configure kubeconfig + run: | + mkdir -p \$HOME/.kube + echo "\${{ secrets.KUBE_CONFIG_PROD }}" | base64 -d > \$HOME/.kube/config + + - name: Deploy to production environment + run: | + kubectl apply -f k8s/prod/ + kubectl rollout status deployment/management + kubectl rollout status deployment/collector + kubectl rollout status deployment/idm +\`\`\` + +#### 部署流程 +\`\`\`mermaid +graph LR + A[代码提交] --> B[代码检查] + B --> C[单元测试] + C --> D[构建镜像] + D --> E{分支判断} + E -->|develop分支| F[部署到测试环境] + E -->|main分支| G[部署到生产环境] + F --> H[测试验证] + G --> I[生产验证] + H --> J[通知开发人员] + I --> J +\`\`\` + +### 4. 基础设施分析 +#### 云服务配置 +\`\`\`terraform +# AWS基础设施配置 +provider "aws" { + region = "us-west-2" +} + +# VPC配置 +resource "aws_vpc" "main" { + cidr_block = "10.0.0.0/16" + enable_dns_support = true + enable_dns_hostnames = true + + tags = { + Name = "main-vpc" + Environment = "production" + } +} + +# 公共子网 +resource "aws_subnet" "public" { + count = 2 + vpc_id = aws_vpc.main.id + cidr_block = "10.0.\${count.index + 1}.0/24" + availability_zone = "us-west-2\${count.index == 0 ? "a" : "b"}" + map_public_ip_on_launch = true + + tags = { + Name = "public-subnet-\${count.index + 1}" + Type = "public" + } +} + +# 私有子网 +resource "aws_subnet" "private" { + count = 2 + vpc_id = aws_vpc.main.id + cidr_block = "10.0.\${count.index + 3}.0/24" + availability_zone = "us-west-2\${count.index == 0 ? "a" : "b"}" + + tags = { + Name = "private-subnet-\${count.index + 1}" + Type = "private" + } +} + +# EKS集群 +resource "aws_eks_cluster" "main" { + name = "main-cluster" + role_arn = aws_iam_role.eks_cluster.arn + + vpc_config { + subnet_ids = concat( + aws_subnet.public[*].id, + aws_subnet.private[*].id + ) + } + + depends_on = [ + aws_iam_role_policy_attachment.eks_cluster_policy, + ] +} + +# EKS节点组 +resource "aws_eks_node_group" "main" { + cluster_name = aws_eks_cluster.main.name + node_group_name = "main-node-group" + node_role_arn = aws_iam_role.eks_node.arn + subnet_ids = aws_subnet.private[*].id + + scaling_config { + desired_size = 3 + max_size = 5 + min_size = 1 + } + + instance_types = ["t3.medium"] + + depends_on = [ + aws_iam_role_policy_attachment.eks_worker_node_policy, + ] +} + +# RDS数据库 +resource "aws_db_instance" "main" { + identifier = "main-db" + engine = "postgres" + engine_version = "15.4" + instance_class = "db.t3.medium" + allocated_storage = 20 + storage_type = "gp2" + + db_name = "app" + username = "app" + password = var.db_password + + vpc_security_group_ids = [aws_security_group.db.id] + db_subnet_group_name = aws_db_subnet_group.main.name + + backup_retention_period = 7 + backup_window = "04:00-05:00" + maintenance_window = "sun:05:00-sun:06:00" + + tags = { + Name = "main-db" + Environment = "production" + } +} + +# ElastiCache Redis +resource "aws_elasticache_cluster" "main" { + cluster_id = "main-cache" + engine = "redis" + engine_version = "7.0" + node_type = "cache.t3.medium" + port = 6379 + num_cache_nodes = 1 + + parameter_group_name = "default.redis7" + subnet_group_name = aws_elasticache_subnet_group.main.name + security_group_ids = [aws_security_group.redis.id] + + tags = { + Name = "main-cache" + Environment = "production" + } +} +\`\`\` + +#### 监控配置 +\`\`\`yaml +# Prometheus配置 +apiVersion: v1 +kind: ConfigMap +metadata: + name: prometheus-config +data: + prometheus.yml: | + global: + scrape_interval: 15s + evaluation_interval: 15s + + scrape_configs: + - job_name: 'kubernetes-pods' + kubernetes_sd_configs: + - role: pod + relabel_configs: + - source_labels: [__meta_kubernetes_pod_annotation_prometheus_io_scrape] + action: keep + regex: true + - source_labels: [__meta_kubernetes_pod_annotation_prometheus_io_path] + action: replace + target_label: __metrics_path__ + regex: (.+) + - source_labels: [__address__, __meta_kubernetes_pod_annotation_prometheus_io_port] + action: replace + regex: ([^:]+)(?::\d+)?;(\d+) + replacement: \$1:\$2 + target_label: __address__ + + - job_name: 'kubernetes-services' + kubernetes_sd_configs: + - role: service + relabel_configs: + - source_labels: [__meta_kubernetes_service_annotation_prometheus_io_scrape] + action: keep + regex: true +\`\`\` + +### 5. 部署策略分析 +#### 部署策略 +| 策略类型 | 策略名称 | 适用场景 | 优点 | 缺点 | +|----------|----------|----------|------|------| +| 滚动部署 | Rolling Update | 无状态服务 | 零停机时间 | 回滚复杂 | +| 蓝绿部署 | Blue-Green | 关键业务 | 快速回滚 | 资源占用多 | +| 金丝雀部署 | Canary | 新功能验证 | 风险控制 | 部署复杂 | +| 重建部署 | Recreate | 简单应用 | 部署简单 | 有停机时间 | + +#### 部署配置 +\`\`\`yaml +# 滚动部署策略 +apiVersion: apps/v1 +kind: Deployment +metadata: + name: management +spec: + replicas: 3 + strategy: + type: RollingUpdate + rollingUpdate: + maxSurge: 1 + maxUnavailable: 1 + template: + # ... pod模板配置 +\`\`\` + +### 6. 安全配置分析 +#### 安全配置 +\`\`\`yaml +# 网络策略 +apiVersion: networking.k8s.io/v1 +kind: NetworkPolicy +metadata: + name: app-network-policy +spec: + podSelector: {} + policyTypes: + - Ingress + - Egress + ingress: + - from: + - namespaceSelector: + matchLabels: + name: default + ports: + - protocol: TCP + port: 8080 + egress: + - to: [] + ports: + - protocol: TCP + port: 5432 + - protocol: TCP + port: 6379 + +# RBAC配置 +apiVersion: v1 +kind: ServiceAccount +metadata: + name: app-service-account +--- +apiVersion: rbac.authorization.k8s.io/v1 +kind: Role +metadata: + name: app-role +rules: +- apiGroups: [""] + resources: ["pods", "services", "configmaps"] + verbs: ["get", "list", "watch"] +--- +apiVersion: rbac.authorization.k8s.io/v1 +kind: RoleBinding +metadata: + name: app-role-binding +subjects: +- kind: ServiceAccount + name: app-service-account +roleRef: + kind: Role + name: app-role + apiGroup: rbac.authorization.k8s.io +\`\`\` + +### 7. 备份与恢复分析 +#### 备份策略 +\`\`\`yaml +# 数据库备份CronJob +apiVersion: batch/v1 +kind: CronJob +metadata: + name: postgres-backup +spec: + schedule: "0 2 * * *" # 每天凌晨2点 + jobTemplate: + spec: + template: + spec: + containers: + - name: backup + image: postgres:15 + command: + - /bin/sh + - -c + - | + pg_dump -h postgres-service -U postgres -d app > /backup/backup-\$(date +%Y%m%d-%H%M%S).sql + volumeMounts: + - name: backup-volume + mountPath: /backup + env: + - name: PGPASSWORD + valueFrom: + secretKeyRef: + name: postgres-secret + key: password + volumes: + - name: backup-volume + persistentVolumeClaim: + claimName: backup-pvc + restartPolicy: OnFailure +\`\`\` + +#### 恢复策略 +\`\`\`yaml +# 数据库恢复Job +apiVersion: batch/v1 +kind: Job +metadata: + name: postgres-restore +spec: + template: + spec: + containers: + - name: restore + image: postgres:15 + command: + - /bin/sh + - -c + - | + psql -h postgres-service -U postgres -d app < /backup/backup-20231201-020000.sql + volumeMounts: + - name: backup-volume + mountPath: /backup + env: + - name: PGPASSWORD + valueFrom: + secretKeyRef: + name: postgres-secret + key: password + volumes: + - name: backup-volume + persistentVolumeClaim: + claimName: backup-pvc + restartPolicy: OnFailure +\`\`\` + +### 8. 性能优化分析 +#### 性能优化配置 +\`\`\`yaml +# HPA配置 +apiVersion: autoscaling/v2 +kind: HorizontalPodAutoscaler +metadata: + name: management-hpa +spec: + scaleTargetRef: + apiVersion: apps/v1 + kind: Deployment + name: management + minReplicas: 3 + maxReplicas: 10 + metrics: + - type: Resource + resource: + name: cpu + target: + type: Utilization + averageUtilization: 70 + - type: Resource + resource: + name: memory + target: + type: Utilization + averageUtilization: 80 +\`\`\` + +#### 资源限制配置 +\`\`\`yaml +# 资源限制 +apiVersion: v1 +kind: LimitRange +metadata: + name: resource-limits +spec: + limits: + - default: + cpu: "500m" + memory: "512Mi" + defaultRequest: + cpu: "250m" + memory: "256Mi" + type: Container +\`\`\` + +## 输出格式要求 + +生成完整的部署分析文档: + +### 文档结构 +\`\`\`markdown +# {项目名称} 部署分析 + +## 部署架构概览 + +### 部署架构图 +\`\`\`mermaid +graph TB + subgraph "开发环境" + A[开发机] + B[本地测试] + end + + subgraph "CI/CD流水线" + C[代码仓库] + D[构建服务器] + E[测试服务器] + F[制品仓库] + end + + subgraph "生产环境" + G[负载均衡器] + H[应用服务器] + I[数据库服务器] + J[缓存服务器] + K[监控服务器] + end + + subgraph "云服务" + L[对象存储] + M[CDN] + N[日志服务] + O[监控服务] + end + + A --> C + B --> C + C --> D + D --> E + E --> F + F --> G + G --> H + H --> I + H --> J + H --> K + I --> L + J --> M + K --> N + K --> O +\`\`\` + +### 部署架构特点 +- **微服务架构**: 服务独立部署和扩展 +- **容器化部署**: Docker容器化部署 +- **云原生架构**: 基于云服务的部署架构 +- **自动化部署**: CI/CD自动化部署流程 + +## 容器化部署 + +### Docker配置 +\`\`\`dockerfile +# Management服务Dockerfile +FROM golang:1.21-alpine AS builder + +WORKDIR /app +COPY go.mod go.sum ./ +RUN go mod download + +COPY . . +RUN CGO_ENABLED=0 GOOS=linux go build -o management ./cmd/management + +FROM alpine:latest +RUN apk --no-cache add ca-certificates +WORKDIR /root/ +COPY --from=builder /app/management . +EXPOSE 8080 +CMD ["./management"] +\`\`\` + +### Docker Compose配置 +\`\`\`yaml +version: '3.8' + +services: + management: + build: ./cmd/management + ports: + - "8080:8080" + environment: + - DB_HOST=postgres + - DB_PORT=5432 + - DB_NAME=management + - DB_USER=management + - DB_PASSWORD=password + - REDIS_HOST=redis + - REDIS_PORT=6379 + depends_on: + - postgres + - redis + networks: + - app-network + + postgres: + image: postgres:15 + environment: + - POSTGRES_DB=app + - POSTGRES_USER=postgres + - POSTGRES_PASSWORD=password + volumes: + - postgres_data:/var/lib/postgresql/data + ports: + - "5432:5432" + networks: + - app-network + + redis: + image: redis:7-alpine + ports: + - "6379:6379" + networks: + - app-network + +volumes: + postgres_data: + +networks: + app-network: + driver: bridge +\`\`\` + +## Kubernetes部署 + +### 部署配置 +\`\`\`yaml +apiVersion: apps/v1 +kind: Deployment +metadata: + name: management + labels: + app: management +spec: + replicas: 3 + selector: + matchLabels: + app: management + template: + metadata: + labels: + app: management + spec: + containers: + - name: management + image: management:latest + ports: + - containerPort: 8080 + env: + - name: DB_HOST + value: "postgres-service" + - name: DB_PORT + value: "5432" + - name: DB_NAME + value: "management" + - name: DB_USER + value: "management" + - name: DB_PASSWORD + valueFrom: + secretKeyRef: + name: postgres-secret + key: password + resources: + requests: + memory: "256Mi" + cpu: "250m" + limits: + memory: "512Mi" + cpu: "500m" + livenessProbe: + httpGet: + path: /health + port: 8080 + initialDelaySeconds: 30 + periodSeconds: 10 + readinessProbe: + httpGet: + path: /ready + port: 8080 + initialDelaySeconds: 5 + periodSeconds: 5 +\`\`\` + +### 服务配置 +\`\`\`yaml +apiVersion: v1 +kind: Service +metadata: + name: management-service +spec: + selector: + app: management + ports: + - protocol: TCP + port: 80 + targetPort: 8080 + type: ClusterIP +\`\`\` + +## CI/CD流水线 + +### GitHub Actions配置 +\`\`\`yaml +name: CI/CD Pipeline + +on: + push: + branches: [ main, develop ] + pull_request: + branches: [ main ] + +jobs: + lint: + name: Lint Code + runs-on: ubuntu-latest + steps: + - name: Checkout code + uses: actions/checkout@v4 + + - name: Set up Go + uses: actions/setup-go@v4 + with: + go-version: '1.21' + + - name: Lint + run: | + go fmt ./... + go vet ./... + golangci-lint run + + test: + name: Run Tests + runs-on: ubuntu-latest + steps: + - name: Checkout code + uses: actions/checkout@v4 + + - name: Set up Go + uses: actions/setup-go@v4 + with: + go-version: '1.21' + + - name: Run tests + run: | + go test -v ./... -coverprofile=coverage.out + go tool cover -html=coverage.out -o coverage.html + + build: + name: Build Images + runs-on: ubuntu-latest + needs: [lint, test] + steps: + - name: Checkout code + uses: actions/checkout@v4 + + - name: Set up Docker Buildx + uses: docker/setup-buildx-action@v3 + + - name: Build and push images + run: | + docker build -t management:latest ./cmd/management + docker build -t collector:latest ./cmd/collector + docker build -t idm:latest ./cmd/idm +\`\`\` + +### 部署流程 +\`\`\`mermaid +graph LR + A[代码提交] --> B[代码检查] + B --> C[单元测试] + C --> D[构建镜像] + D --> E{分支判断} + E -->|develop分支| F[部署到测试环境] + E -->|main分支| G[部署到生产环境] + F --> H[测试验证] + G --> I[生产验证] + H --> J[通知开发人员] + I --> J +\`\`\` + +## 基础设施配置 + +### 云服务配置 +\`\`\`terraform +provider "aws" { + region = "us-west-2" +} + +resource "aws_vpc" "main" { + cidr_block = "10.0.0.0/16" + enable_dns_support = true + enable_dns_hostnames = true + + tags = { + Name = "main-vpc" + Environment = "production" + } +} + +resource "aws_eks_cluster" "main" { + name = "main-cluster" + role_arn = aws_iam_role.eks_cluster.arn + + vpc_config { + subnet_ids = concat( + aws_subnet.public[*].id, + aws_subnet.private[*].id + ) + } +} +\`\`\` + +### 监控配置 +\`\`\`yaml +apiVersion: v1 +kind: ConfigMap +metadata: + name: prometheus-config +data: + prometheus.yml: | + global: + scrape_interval: 15s + evaluation_interval: 15s + + scrape_configs: + - job_name: 'kubernetes-pods' + kubernetes_sd_configs: + - role: pod +\`\`\` + +## 部署策略 + +### 滚动部署 +\`\`\`yaml +apiVersion: apps/v1 +kind: Deployment +metadata: + name: management +spec: + replicas: 3 + strategy: + type: RollingUpdate + rollingUpdate: + maxSurge: 1 + maxUnavailable: 1 +\`\`\` + +### 自动扩缩容 +\`\`\`yaml +apiVersion: autoscaling/v2 +kind: HorizontalPodAutoscaler +metadata: + name: management-hpa +spec: + scaleTargetRef: + apiVersion: apps/v1 + kind: Deployment + name: management + minReplicas: 3 + maxReplicas: 10 + metrics: + - type: Resource + resource: + name: cpu + target: + type: Utilization + averageUtilization: 70 +\`\`\` + +## 安全配置 + +### 网络策略 +\`\`\`yaml +apiVersion: networking.k8s.io/v1 +kind: NetworkPolicy +metadata: + name: app-network-policy +spec: + podSelector: {} + policyTypes: + - Ingress + - Egress + ingress: + - from: + - namespaceSelector: + matchLabels: + name: default + ports: + - protocol: TCP + port: 8080 +\`\`\` + +### RBAC配置 +\`\`\`yaml +apiVersion: v1 +kind: ServiceAccount +metadata: + name: app-service-account +--- +apiVersion: rbac.authorization.k8s.io/v1 +kind: Role +metadata: + name: app-role +rules: +- apiGroups: [""] + resources: ["pods", "services", "configmaps"] + verbs: ["get", "list", "watch"] +\`\`\` + +## 备份与恢复 + +### 备份策略 +\`\`\`yaml +apiVersion: batch/v1 +kind: CronJob +metadata: + name: postgres-backup +spec: + schedule: "0 2 * * *" + jobTemplate: + spec: + template: + spec: + containers: + - name: backup + image: postgres:15 + command: + - /bin/sh + - -c + - | + pg_dump -h postgres-service -U postgres -d app > /backup/backup-\$(date +%Y%m%d-%H%M%S).sql +\`\`\` + +## 性能优化 + +### 资源限制 +\`\`\`yaml +apiVersion: v1 +kind: LimitRange +metadata: + name: resource-limits +spec: + limits: + - default: + cpu: "500m" + memory: "512Mi" + defaultRequest: + cpu: "250m" + memory: "256Mi" + type: Container +\`\`\` + +## 部署检查清单 + +### 部署前检查 +- [ ] 代码已通过所有测试 +- [ ] Docker镜像已构建并推送到仓库 +- [ ] Kubernetes配置文件已更新 +- [ ] 环境变量已配置 +- [ ] 数据库迁移脚本已准备 + +### 部署后检查 +- [ ] 所有Pod正常运行 +- [ ] 服务可正常访问 +- [ ] 数据库连接正常 +- [ ] 缓存服务正常 +- [ ] 监控指标正常 +- [ ] 日志输出正常 + +### 回滚计划 +- [ ] 备份当前版本配置 +- [ ] 准备回滚脚本 +- [ ] 测试回滚流程 +- [ ] 通知相关人员 +\`\`\` + +## 注意事项 +1. **安全第一**: 所有敏感信息必须使用Kubernetes Secret管理 +2. **监控完备**: 确保所有服务都有完善的监控和告警 +3. **备份策略**: 定期备份重要数据,测试恢复流程 +4. **性能优化**: 根据实际负载调整资源配置 +5. **文档更新**: 及时更新部署文档和操作手册 +` diff --git a/src/core/tools/helpers/wiki-prompts/subtasks/09_Project_Rules_Generation.ts b/src/core/tools/helpers/wiki-prompts/subtasks/09_Project_Rules_Generation.ts new file mode 100644 index 0000000000..43b0497f91 --- /dev/null +++ b/src/core/tools/helpers/wiki-prompts/subtasks/09_Project_Rules_Generation.ts @@ -0,0 +1,1300 @@ +export const PROJECT_RULES_GENERATION_TEMPLATE = `# 项目规则生成 + +## 使用场景 +从代码仓库中分析项目的架构、模式、最佳实践等,生成完整的项目规则文档。 + +## 输入要求 +- **完整代码仓库**: 项目的完整源代码 +- **配置文件**: 各种配置文件(package.json、tsconfig.json等) +- **文档**: 现有的项目文档、README等 +- **测试文件**: 单元测试、集成测试等 + +# 项目规则生成任务 + +## 任务描述 +请深度分析项目的架构、模式、最佳实践等,从代码规范、架构设计、开发流程、测试策略、部署规范等维度生成完整的项目规则文档。 + +## 分析维度 + +### 1. 代码规范分析 +#### 代码风格规范 +\`\`\`typescript +// TypeScript代码风格示例 +interface User { + id: string; + name: string; + email: string; + createdAt: Date; + updatedAt: Date; +} + +class UserService { + private userRepository: UserRepository; + + constructor(userRepository: UserRepository) { + this.userRepository = userRepository; + } + + async createUser(userData: CreateUserData): Promise { + // 参数验证 + if (!userData.name || !userData.email) { + throw new Error('Name and email are required'); + } + + // 检查邮箱格式 + if (!this.isValidEmail(userData.email)) { + throw new Error('Invalid email format'); + } + + // 检查邮箱是否已存在 + const existingUser = await this.userRepository.findByEmail(userData.email); + if (existingUser) { + throw new Error('Email already exists'); + } + + // 创建用户 + const user = await this.userRepository.create(userData); + + return user; + } + + private isValidEmail(email: string): boolean { + const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+\$/; + return emailRegex.test(email); + } +} +\`\`\` + +#### 命名规范 +| 类型 | 命名规则 | 示例 | +|------|----------|------| +| 文件名 | kebab-case | user-service.ts | +| 类名 | PascalCase | UserService | +| 接口名 | PascalCase | IUser | +| 变量名 | camelCase | userName | +| 常量名 | SCREAMING_SNAKE_CASE | MAX_USERS | +| 函数名 | camelCase | createUser | +| 私有属性 | camelCase + _ | _privateProperty | + +#### 代码组织规范 +\`\`\`typescript +// 目录结构规范 +src/ +├── components/ // 组件 +│ ├── common/ // 通用组件 +│ └── features/ // 功能组件 +├── services/ // 服务层 +├── repositories/ // 数据访问层 +├── models/ // 数据模型 +├── utils/ // 工具函数 +├── constants/ // 常量定义 +├── types/ // 类型定义 +├── hooks/ // React Hooks +└── __tests__/ // 测试文件 + +// 文件组织规范 +// 1. 导入语句 +import { Component } from 'react'; +import { UserService } from '../services/UserService'; +import type { User } from '../types/User'; + +// 2. 类型定义 +interface Props { + userId: string; + onUserUpdate: (user: User) => void; +} + +// 3. 常量定义 +const MAX_RETRIES = 3; + +// 4. 主组件/类 +export const UserProfile: React.FC = ({ userId, onUserUpdate }) => { + // 组件逻辑 +}; + +// 5. 导出语句 +export default UserProfile; +\`\`\` + +### 2. 架构设计分析 +#### 分层架构 +\`\`\`typescript +// 表现层 (Presentation Layer) +@Controller('/api/users') +export class UserController { + constructor(private readonly userService: UserService) {} + + @Post() + async createUser(@Body() userData: CreateUserData): Promise { + return this.userService.createUser(userData); + } +} + +// 业务逻辑层 (Business Logic Layer) +@Service() +export class UserService { + constructor(private readonly userRepository: UserRepository) {} + + async createUser(userData: CreateUserData): Promise { + // 业务逻辑处理 + const user = await this.userRepository.create(userData); + return user; + } +} + +// 数据访问层 (Data Access Layer) +@Repository() +export class UserRepository { + async create(userData: CreateUserData): Promise { + // 数据库操作 + const user = new User(); + Object.assign(user, userData); + return await this.save(user); + } +} +\`\`\` + +#### 设计模式应用 +\`\`\`typescript +// 单例模式 +export class DatabaseConnection { + private static instance: DatabaseConnection; + private connection: any; + + private constructor() { + this.connection = this.createConnection(); + } + + public static getInstance(): DatabaseConnection { + if (!DatabaseConnection.instance) { + DatabaseConnection.instance = new DatabaseConnection(); + } + return DatabaseConnection.instance; + } + + private createConnection(): any { + // 创建数据库连接 + return {}; + } +} + +// 工厂模式 +interface PaymentProcessor { + processPayment(amount: number): Promise; +} + +class CreditCardProcessor implements PaymentProcessor { + async processPayment(amount: number): Promise { + // 信用卡支付逻辑 + return true; + } +} + +class PayPalProcessor implements PaymentProcessor { + async processPayment(amount: number): Promise { + // PayPal支付逻辑 + return true; + } +} + +class PaymentProcessorFactory { + static createProcessor(type: 'credit_card' | 'paypal'): PaymentProcessor { + switch (type) { + case 'credit_card': + return new CreditCardProcessor(); + case 'paypal': + return new PayPalProcessor(); + default: + throw new Error('Unsupported payment type'); + } + } +} + +// 观察者模式 +interface Observer { + update(data: any): void; +} + +class EventEmitter { + private observers: Observer[] = []; + + subscribe(observer: Observer): void { + this.observers.push(observer); + } + + unsubscribe(observer: Observer): void { + this.observers = this.observers.filter(obs => obs !== observer); + } + + notify(data: any): void { + this.observers.forEach(observer => observer.update(data)); + } +} +\`\`\` + +### 3. 开发流程分析 +#### Git工作流 +\`\`\`mermaid +graph LR + A[main分支] --> B[develop分支] + B --> C[feature分支] + C --> D[Pull Request] + D --> E[代码审查] + E --> F[合并到develop] + F --> G[发布到main] +\`\`\` + +#### 分支管理规范 +| 分支类型 | 命名规则 | 用途 | 生命周期 | +|----------|----------|------|----------| +| main | main | 生产环境 | 长期 | +| develop | develop | 开发环境 | 长期 | +| feature | feature/功能名称 | 功能开发 | 临时 | +| hotfix | hotfix/问题描述 | 紧急修复 | 临时 | +| release | release/版本号 | 发布准备 | 临时 | + +#### 提交信息规范 +\`\`\`bash +# 提交信息格式 +<类型>(<范围>): <描述> + +# 类型说明 +feat: 新功能 +fix: 修复bug +docs: 文档更新 +style: 代码格式化 +refactor: 重构 +test: 测试相关 +chore: 构建或辅助工具变动 + +# 示例 +feat(auth): 添加用户登录功能 +fix(user): 修复用户信息更新bug +docs(api): 更新API文档 +style: 格式化代码 +refactor: 重构用户服务 +test: 添加用户服务测试 +chore: 更新依赖包 +\`\`\` + +### 4. 测试策略分析 +#### 测试金字塔 +\`\`\`mermaid +graph TD + A[单元测试] --> B[集成测试] + B --> C[端到端测试] + + A -->|70%| D[测试覆盖率] + B -->|20%| D + C -->|10%| D +\`\`\` + +#### 测试规范 +\`\`\`typescript +// 单元测试示例 +import { UserService } from '../UserService'; +import { UserRepository } from '../UserRepository'; +import { User } from '../User'; + +describe('UserService', () => { + let userService: UserService; + let userRepository: jest.Mocked; + + beforeEach(() => { + userRepository = { + create: jest.fn(), + findByEmail: jest.fn(), + findById: jest.fn(), + } as any; + + userService = new UserService(userRepository); + }); + + describe('createUser', () => { + it('应该成功创建用户', async () => { + // Arrange + const userData = { + name: 'John Doe', + email: 'john@example.com', + password: 'password123', + }; + + const expectedUser: User = { + id: '1', + ...userData, + createdAt: new Date(), + updatedAt: new Date(), + }; + + userRepository.findByEmail.mockResolvedValue(null); + userRepository.create.mockResolvedValue(expectedUser); + + // Act + const result = await userService.createUser(userData); + + // Assert + expect(result).toEqual(expectedUser); + expect(userRepository.findByEmail).toHaveBeenCalledWith(userData.email); + expect(userRepository.create).toHaveBeenCalledWith(userData); + }); + + it('当邮箱已存在时应该抛出错误', async () => { + // Arrange + const userData = { + name: 'John Doe', + email: 'john@example.com', + password: 'password123', + }; + + const existingUser: User = { + id: '1', + ...userData, + createdAt: new Date(), + updatedAt: new Date(), + }; + + userRepository.findByEmail.mockResolvedValue(existingUser); + + // Act & Assert + await expect(userService.createUser(userData)) + .rejects.toThrow('Email already exists'); + }); + }); +}); + +// 集成测试示例 +import request from 'supertest'; +import { app } from '../app'; +import { DatabaseConnection } from '../DatabaseConnection'; + +describe('User API', () => { + beforeAll(async () => { + await DatabaseConnection.connect(); + }); + + afterAll(async () => { + await DatabaseConnection.disconnect(); + }); + + beforeEach(async () => { + await DatabaseConnection.clear(); + }); + + describe('POST /api/users', () => { + it('应该创建新用户', async () => { + const userData = { + name: 'John Doe', + email: 'john@example.com', + password: 'password123', + }; + + const response = await request(app) + .post('/api/users') + .send(userData) + .expect(201); + + expect(response.body).toHaveProperty('id'); + expect(response.body.name).toBe(userData.name); + expect(response.body.email).toBe(userData.email); + }); + }); +}); +\`\`\` + +### 5. 安全规范分析 +#### 输入验证 +\`\`\`typescript +// 参数验证装饰器 +import { validate, ValidationError } from 'class-validator'; +import { plainToClass } from 'class-transformer'; + +export class CreateUserDto { + @IsString() + @IsNotEmpty() + @MinLength(2) + @MaxLength(50) + name: string; + + @IsEmail() + @IsNotEmpty() + email: string; + + @IsString() + @IsNotEmpty() + @MinLength(8) + @Matches(/^(?=.*[a-z])(?=.*[A-Z])(?=.*\d)[a-zA-Z\d]{8,}\$/) + password: string; +} + +export async function validateDto(dtoClass: new () => T, data: any): Promise { + const dto = plainToClass(dtoClass, data); + const errors = await validate(dto as object); + + if (errors.length > 0) { + const errorMessages = errors.map(error => { + return Object.values(error.constraints || {}).join(', '); + }); + throw new Error(\`Validation failed: \${errorMessages.join(', ')}\`); + } + + return dto; +} + +// 使用示例 +export class UserController { + async createUser(req: Request, res: Response) { + try { + const createUserDto = await validateDto(CreateUserDto, req.body); + // 处理用户创建逻辑 + } catch (error) { + res.status(400).json({ error: error.message }); + } + } +} +\`\`\` + +#### 权限控制 +\`\`\`typescript +// 角色定义 +export enum Role { + ADMIN = 'admin', + USER = 'user', + GUEST = 'guest', +} + +// 权限装饰器 +export const RequireRoles = (...roles: Role[]) => { + return (target: any, propertyKey: string, descriptor: PropertyDescriptor) => { + const originalMethod = descriptor.value; + + descriptor.value = function(req: Request, res: Response, next: Function) { + const user = req.user; + + if (!user || !roles.includes(user.role)) { + return res.status(403).json({ error: 'Insufficient permissions' }); + } + + return originalMethod.apply(this, arguments); + }; + + return descriptor; + }; +}; + +// 使用示例 +export class AdminController { + @RequireRoles(Role.ADMIN) + async deleteUser(req: Request, res: Response) { + // 只有管理员可以删除用户 + } +} +\`\`\` + +#### 数据加密 +\`\`\`typescript +import * as bcrypt from 'bcrypt'; +import * as crypto from 'crypto'; + +export class EncryptionService { + private static readonly SALT_ROUNDS = 12; + private static readonly ENCRYPTION_KEY = process.env.ENCRYPTION_KEY || 'default-key'; + + // 密码哈希 + static async hashPassword(password: string): Promise { + return bcrypt.hash(password, this.SALT_ROUNDS); + } + + // 密码验证 + static async verifyPassword(password: string, hash: string): Promise { + return bcrypt.compare(password, hash); + } + + // 数据加密 + static encrypt(data: string): string { + const cipher = crypto.createCipher('aes-256-cbc', this.ENCRYPTION_KEY); + let encrypted = cipher.update(data, 'utf8', 'hex'); + encrypted += cipher.final('hex'); + return encrypted; + } + + // 数据解密 + static decrypt(encryptedData: string): string { + const decipher = crypto.createDecipher('aes-256-cbc', this.ENCRYPTION_KEY); + let decrypted = decipher.update(encryptedData, 'hex', 'utf8'); + decrypted += decipher.final('utf8'); + return decrypted; + } +} +\`\`\` + +### 6. 性能优化分析 +#### 缓存策略 +\`\`\`typescript +import { Redis } from 'ioredis'; + +export class CacheService { + private redis: Redis; + + constructor() { + this.redis = new Redis({ + host: process.env.REDIS_HOST, + port: parseInt(process.env.REDIS_PORT || '6379'), + }); + } + + // 设置缓存 + async set(key: string, value: any, ttl: number = 3600): Promise { + await this.redis.setex(key, ttl, JSON.stringify(value)); + } + + // 获取缓存 + async get(key: string): Promise { + const value = await this.redis.get(key); + return value ? JSON.parse(value) : null; + } + + // 删除缓存 + async delete(key: string): Promise { + await this.redis.del(key); + } + + // 缓存装饰器 + static Cacheable(key: string, ttl: number = 3600) { + return (target: any, propertyKey: string, descriptor: PropertyDescriptor) => { + const originalMethod = descriptor.value; + const cacheService = new CacheService(); + + descriptor.value = async function(...args: any[]) { + const cacheKey = \`\${key}:\${JSON.stringify(args)}\`; + const cached = await cacheService.get(cacheKey); + + if (cached) { + return cached; + } + + const result = await originalMethod.apply(this, args); + await cacheService.set(cacheKey, result, ttl); + + return result; + }; + + return descriptor; + }; + } +} + +// 使用示例 +export class UserService { + @Cacheable.Cacheable('user:profile', 1800) // 30分钟缓存 + async getUserProfile(userId: string): Promise { + // 从数据库获取用户信息 + return this.userRepository.findById(userId); + } +} +\`\`\` + +#### 数据库优化 +\`\`\`typescript +// 1. 使用参数化查询 +class UserRepository { + async findByEmail(email: string): Promise { + const query = 'SELECT * FROM users WHERE email = \$1'; + const result = await this.database.query(query, [email]); + return result.length > 0 ? result[0] : null; + } + + async create(userData: CreateUserData): Promise { + const query = \` + INSERT INTO users (name, email, password, created_at) + VALUES (\$1, \$2, \$3, NOW()) + RETURNING * + \`; + + const hashedPassword = await bcrypt.hash(userData.password, 10); + const result = await this.database.query(query, [ + userData.name, + userData.email, + hashedPassword + ]); + + return result[0]; + } +} + +// 2. 使用索引 +class DatabaseIndexer { + static createUserIndexes() { + const indexes = [ + 'CREATE INDEX IF NOT EXISTS idx_users_email ON users(email)', + 'CREATE INDEX IF NOT EXISTS idx_users_created_at ON users(created_at)', + 'CREATE INDEX IF NOT EXISTS idx_users_name ON users(name)', + ]; + + return indexes; + } +} + +// 3. 使用连接池 +import { Pool } from 'pg'; + +export class DatabaseConnection { + private static pool: Pool; + + static getPool(): Pool { + if (!DatabaseConnection.pool) { + DatabaseConnection.pool = new Pool({ + host: process.env.DB_HOST, + port: parseInt(process.env.DB_PORT || '5432'), + database: process.env.DB_NAME, + user: process.env.DB_USER, + password: process.env.DB_PASSWORD, + max: 20, // 最大连接数 + idleTimeoutMillis: 30000, // 空闲超时 + connectionTimeoutMillis: 2000, // 连接超时 + }); + } + + return DatabaseConnection.pool; + } +} +\`\`\` + +### 7. 错误处理分析 +#### 错误类型定义 +\`\`\`typescript +// 基础错误类 +export class AppError extends Error { + public readonly statusCode: number; + public readonly isOperational: boolean; + + constructor(message: string, statusCode: number = 500) { + super(message); + this.statusCode = statusCode; + this.isOperational = true; + Error.captureStackTrace(this, this.constructor); + } +} + +// 具体错误类型 +export class ValidationError extends AppError { + constructor(message: string) { + super(message, 400); + } +} + +export class NotFoundError extends AppError { + constructor(resource: string) { + super(\`\${resource} not found\`, 404); + } +} + +export class UnauthorizedError extends AppError { + constructor(message: string = 'Unauthorized') { + super(message, 401); + } +} + +export class ForbiddenError extends AppError { + constructor(message: string = 'Forbidden') { + super(message, 403); + } +} + +// 错误处理中间件 +export const errorHandler = ( + error: Error, + req: Request, + res: Response, + next: NextFunction +) => { + if (error instanceof AppError) { + return res.status(error.statusCode).json({ + error: error.message, + statusCode: error.statusCode, + }); + } + + // 未知错误 + console.error('Unexpected error:', error); + return res.status(500).json({ + error: 'Internal server error', + statusCode: 500, + }); +}; +\`\`\` + +#### 日志记录 +\`\`\`typescript +import winston from 'winston'; + +export class Logger { + private static logger: winston.Logger; + + static getLogger(): winston.Logger { + if (!Logger.logger) { + Logger.logger = winston.createLogger({ + level: process.env.LOG_LEVEL || 'info', + format: winston.format.combine( + winston.format.timestamp(), + winston.format.errors({ stack: true }), + winston.format.json() + ), + transports: [ + new winston.transports.File({ filename: 'error.log', level: 'error' }), + new winston.transports.File({ filename: 'combined.log' }), + ], + }); + + // 在开发环境中也输出到控制台 + if (process.env.NODE_ENV !== 'production') { + Logger.logger.add(new winston.transports.Console({ + format: winston.format.simple() + })); + } + } + + return Logger.logger; + } + + static info(message: string, meta?: any): void { + this.getLogger().info(message, meta); + } + + static error(message: string, error?: Error): void { + this.getLogger().error(message, { error: error?.stack }); + } + + static warn(message: string, meta?: any): void { + this.getLogger().warn(message, meta); + } + + static debug(message: string, meta?: any): void { + this.getLogger().debug(message, meta); + } +} +\`\`\` + +### 8. 文档规范分析 +#### 代码文档 +\`\`\`typescript +/** + * 用户服务类 + * @class UserService + * @description 提供用户相关的业务逻辑处理 + */ +export class UserService { + private userRepository: UserRepository; + + /** + * 创建用户服务实例 + * @constructor + * @param {UserRepository} userRepository - 用户仓库实例 + */ + constructor(userRepository: UserRepository) { + this.userRepository = userRepository; + } + + /** + * 创建新用户 + * @async + * @method createUser + * @param {CreateUserData} userData - 用户数据 + * @returns {Promise} 创建的用户对象 + * @throws {Error} 当用户数据无效或邮箱已存在时抛出错误 + * @example + * const userData = { + * name: 'John Doe', + * email: 'john@example.com', + * password: 'password123' + * }; + * const user = await userService.createUser(userData); + */ + async createUser(userData: CreateUserData): Promise { + // 实现逻辑 + } +} +\`\`\` + +#### API文档 +\`\`\`typescript +/** + * @swagger + * /api/users: + * post: + * summary: 创建新用户 + * tags: [Users] + * requestBody: + * required: true + * content: + * application/json: + * schema: + * type: object + * required: + * - name + * - email + * - password + * properties: + * name: + * type: string + * description: 用户姓名 + * example: John Doe + * email: + * type: string + * format: email + * description: 用户邮箱 + * example: john@example.com + * password: + * type: string + * format: password + * description: 用户密码 + * example: password123 + * responses: + * 201: + * description: 用户创建成功 + * content: + * application/json: + * schema: + * \$ref: '#/components/schemas/User' + * 400: + * description: 请求数据无效 + * 409: + * description: 邮箱已存在 + */ +\`\`\` + +## 输出格式要求 + +生成完整的项目规则文档: + +### 文档结构 +\`\`\`markdown +# {项目名称} 项目规则 + +## 代码规范 + +### 代码风格 +\`\`\`typescript +// TypeScript代码风格示例 +interface User { + id: string; + name: string; + email: string; + createdAt: Date; + updatedAt: Date; +} + +class UserService { + private userRepository: UserRepository; + + constructor(userRepository: UserRepository) { + this.userRepository = userRepository; + } + + async createUser(userData: CreateUserData): Promise { + // 参数验证 + if (!userData.name || !userData.email) { + throw new Error('Name and email are required'); + } + + // 检查邮箱格式 + if (!this.isValidEmail(userData.email)) { + throw new Error('Invalid email format'); + } + + // 检查邮箱是否已存在 + const existingUser = await this.userRepository.findByEmail(userData.email); + if (existingUser) { + throw new Error('Email already exists'); + } + + // 创建用户 + const user = await this.userRepository.create(userData); + + return user; + } +} +\`\`\` + +### 命名规范 +| 类型 | 命名规则 | 示例 | +|------|----------|------| +| 文件名 | kebab-case | user-service.ts | +| 类名 | PascalCase | UserService | +| 接口名 | PascalCase | IUser | +| 变量名 | camelCase | userName | +| 常量名 | SCREAMING_SNAKE_CASE | MAX_USERS | +| 函数名 | camelCase | createUser | +| 私有属性 | camelCase + _ | _privateProperty | + +### 代码组织 +\`\`\`typescript +// 目录结构规范 +src/ +├── components/ // 组件 +│ ├── common/ // 通用组件 +│ └── features/ // 功能组件 +├── services/ // 服务层 +├── repositories/ // 数据访问层 +├── models/ // 数据模型 +├── utils/ // 工具函数 +├── constants/ // 常量定义 +├── types/ // 类型定义 +├── hooks/ // React Hooks +└── __tests__/ // 测试文件 +\`\`\` + +## 架构设计 + +### 分层架构 +\`\`\`typescript +// 表现层 +@Controller('/api/users') +export class UserController { + constructor(private readonly userService: UserService) {} + + @Post() + async createUser(@Body() userData: CreateUserData): Promise { + return this.userService.createUser(userData); + } +} + +// 业务逻辑层 +@Service() +export class UserService { + constructor(private readonly userRepository: UserRepository) {} + + async createUser(userData: CreateUserData): Promise { + const user = await this.userRepository.create(userData); + return user; + } +} + +// 数据访问层 +@Repository() +export class UserRepository { + async create(userData: CreateUserData): Promise { + const user = new User(); + Object.assign(user, userData); + return await this.save(user); + } +} +\`\`\` + +### 设计模式 +\`\`\`typescript +// 单例模式 +export class DatabaseConnection { + private static instance: DatabaseConnection; + private connection: any; + + private constructor() { + this.connection = this.createConnection(); + } + + public static getInstance(): DatabaseConnection { + if (!DatabaseConnection.instance) { + DatabaseConnection.instance = new DatabaseConnection(); + } + return DatabaseConnection.instance; + } +} +\`\`\` + +## 开发流程 + +### Git工作流 +\`\`\`mermaid +graph LR + A[main分支] --> B[develop分支] + B --> C[feature分支] + C --> D[Pull Request] + D --> E[代码审查] + E --> F[合并到develop] + F --> G[发布到main] +\`\`\` + +### 分支管理 +| 分支类型 | 命名规则 | 用途 | 生命周期 | +|----------|----------|------|----------| +| main | main | 生产环境 | 长期 | +| develop | develop | 开发环境 | 长期 | +| feature | feature/功能名称 | 功能开发 | 临时 | +| hotfix | hotfix/问题描述 | 紧急修复 | 临时 | +| release | release/版本号 | 发布准备 | 临时 | + +### 提交规范 +\`\`\`bash +# 提交信息格式 +<类型>(<范围>): <描述> + +# 类型说明 +feat: 新功能 +fix: 修复bug +docs: 文档更新 +style: 代码格式化 +refactor: 重构 +test: 测试相关 +chore: 构建或辅助工具变动 + +# 示例 +feat(auth): 添加用户登录功能 +fix(user): 修复用户信息更新bug +docs(api): 更新API文档 +\`\`\` + +## 测试策略 + +### 测试金字塔 +\`\`\`mermaid +graph TD + A[单元测试] --> B[集成测试] + B --> C[端到端测试] + + A -->|70%| D[测试覆盖率] + B -->|20%| D + C -->|10%| D +\`\`\` + +### 测试规范 +\`\`\`typescript +describe('UserService', () => { + let userService: UserService; + let userRepository: jest.Mocked; + + beforeEach(() => { + userRepository = { + create: jest.fn(), + findByEmail: jest.fn(), + } as any; + + userService = new UserService(userRepository); + }); + + describe('createUser', () => { + it('应该成功创建用户', async () => { + // Arrange + const userData = { + name: 'John Doe', + email: 'john@example.com', + password: 'password123', + }; + + // Act + const result = await userService.createUser(userData); + + // Assert + expect(result).toBeDefined(); + }); + }); +}); +\`\`\` + +## 安全规范 + +### 输入验证 +\`\`\`typescript +export class CreateUserDto { + @IsString() + @IsNotEmpty() + @MinLength(2) + @MaxLength(50) + name: string; + + @IsEmail() + @IsNotEmpty() + email: string; + + @IsString() + @IsNotEmpty() + @MinLength(8) + password: string; +} +\`\`\` + +### 权限控制 +\`\`\`typescript +export enum Role { + ADMIN = 'admin', + USER = 'user', + GUEST = 'guest', +} + +export const RequireRoles = (...roles: Role[]) => { + return (target: any, propertyKey: string, descriptor: PropertyDescriptor) => { + const originalMethod = descriptor.value; + + descriptor.value = function(req: Request, res: Response, next: Function) { + const user = req.user; + + if (!user || !roles.includes(user.role)) { + return res.status(403).json({ error: 'Insufficient permissions' }); + } + + return originalMethod.apply(this, arguments); + }; + + return descriptor; + }; +}; +\`\`\` + +## 性能优化 + +### 缓存策略 +\`\`\`typescript +export class CacheService { + private redis: Redis; + + constructor() { + this.redis = new Redis({ + host: process.env.REDIS_HOST, + port: parseInt(process.env.REDIS_PORT || '6379'), + }); + } + + async set(key: string, value: any, ttl: number = 3600): Promise { + await this.redis.setex(key, ttl, JSON.stringify(value)); + } + + async get(key: string): Promise { + const value = await this.redis.get(key); + return value ? JSON.parse(value) : null; + } +} +\`\`\` + +### 数据库优化 +\`\`\`typescript +class UserRepository { + async findByEmail(email: string): Promise { + const query = 'SELECT * FROM users WHERE email = \$1'; + const result = await this.database.query(query, [email]); + return result.length > 0 ? result[0] : null; + } +} +\`\`\` + +## 错误处理 + +### 错误类型 +\`\`\`typescript +export class AppError extends Error { + public readonly statusCode: number; + public readonly isOperational: boolean; + + constructor(message: string, statusCode: number = 500) { + super(message); + this.statusCode = statusCode; + this.isOperational = true; + } +} + +export class ValidationError extends AppError { + constructor(message: string) { + super(message, 400); + } +} +\`\`\` + +### 日志记录 +\`\`\`typescript +export class Logger { + static info(message: string, meta?: any): void { + this.getLogger().info(message, meta); + } + + static error(message: string, error?: Error): void { + this.getLogger().error(message, { error: error?.stack }); + } + + static warn(message: string, meta?: any): void { + this.getLogger().warn(message, meta); + } +} +\`\`\` + +## 文档规范 + +### 代码文档 +\`\`\`typescript +/** + * 用户服务类 + * @class UserService + * @description 提供用户相关的业务逻辑处理 + */ +export class UserService { + /** + * 创建新用户 + * @async + * @method createUser + * @param {CreateUserData} userData - 用户数据 + * @returns {Promise} 创建的用户对象 + * @throws {Error} 当用户数据无效或邮箱已存在时抛出错误 + */ + async createUser(userData: CreateUserData): Promise { + // 实现逻辑 + } +} +\`\`\` + +## 检查清单 + +### 代码质量检查 +- [ ] 代码符合命名规范 +- [ ] 代码符合组织规范 +- [ ] 代码有适当的注释 +- [ ] 代码通过了所有测试 +- [ ] 代码通过了静态分析 + +### 架构设计检查 +- [ ] 遵循分层架构 +- [ ] 使用了合适的设计模式 +- [ ] 模块间耦合度低 +- [ ] 接口设计合理 +- [ ] 扩展性良好 + +### 安全检查 +- [ ] 输入数据已验证 +- [ ] 权限控制已实现 +- [ ] 敏感数据已加密 +- [ ] SQL注入已防护 +- [ ] XSS攻击已防护 + +### 性能检查 +- [ ] 数据库查询已优化 +- [ ] 缓存策略已实现 +- [ ] 资源使用合理 +- [ ] 响应时间可接受 +- [ ] 并发处理正确 + +## 最佳实践 + +### 开发最佳实践 +1. **保持代码简洁**: 避免过度设计,保持代码简单易懂 +2. **遵循DRY原则**: 避免重复代码,提取公共逻辑 +3. **编写测试**: 为所有功能编写单元测试和集成测试 +4. **代码审查**: 所有代码变更都需要经过审查 +5. **持续集成**: 使用CI/CD自动化构建和测试 + +### 架构最佳实践 +1. **分层架构**: 清晰的层次结构,避免跨层调用 +2. **依赖注入**: 使用依赖注入管理组件间依赖 +3. **接口设计**: 定义清晰的接口,隐藏实现细节 +4. **错误处理**: 统一的错误处理机制 +5. **日志记录**: 完善的日志记录系统 + +### 安全最佳实践 +1. **输入验证**: 对所有输入数据进行验证 +2. **权限控制**: 基于角色的访问控制 +3. **数据加密**: 敏感数据加密存储 +4. **安全审计**: 定期进行安全审计 +5. **漏洞修复**: 及时修复安全漏洞 + +## 注意事项 +1. **规则执行**: 所有开发人员必须严格遵守项目规则 +2. **持续改进**: 定期回顾和改进项目规则 +3. **文档更新**: 规则变更时及时更新文档 +4. **培训教育**: 对新成员进行规则培训 +5. **工具支持**: 使用工具辅助规则执行和检查 +\`\`\` +` diff --git a/src/core/tools/helpers/wiki-prompts/subtasks/constants.ts b/src/core/tools/helpers/wiki-prompts/subtasks/constants.ts new file mode 100644 index 0000000000..a154119530 --- /dev/null +++ b/src/core/tools/helpers/wiki-prompts/subtasks/constants.ts @@ -0,0 +1,4 @@ +import * as path from "path" + +export const WIKI_OUTPUT_DIR = path.join(".cospec", "wiki") + path.sep +export const RULES_OUTPUT_DIR = ".roo" + path.sep diff --git a/src/services/command/commands.ts b/src/services/command/commands.ts index 1cd5434745..8a2e1be3eb 100644 --- a/src/services/command/commands.ts +++ b/src/services/command/commands.ts @@ -3,6 +3,7 @@ import * as path from "path" import matter from "gray-matter" import { getGlobalRooDirectory, getProjectRooDirectoryForCwd } from "../roo-config" import { getBuiltInCommands, getBuiltInCommand } from "./built-in-commands" +import { ensureProjectWikiCommandExists } from "../../core/tools/helpers/projectWikiHelpers" export interface Command { name: string @@ -18,6 +19,14 @@ export interface Command { * Priority order: project > global > built-in (later sources override earlier ones) */ export async function getCommands(cwd: string): Promise { + // init project-wiki command. + try { + await ensureProjectWikiCommandExists() + } catch (error) { + // just log error + console.error("[commands] Failed to initialize project-wiki command:", error) + } + const commands = new Map() // Add built-in commands first (lowest priority)