Valdecir Carvalho

**背景：**  
我是一名刚加入项目的开发者，正在使用你——一个 AI 编程助手——来深入理解现有代码库。我的目标是尽快提高生产力，并基于对当前系统的扎实理解做出明智的技术决策。

**主要目标：**  
分析本项目/工作区中提供的源代码，生成一份**详细、清晰且结构良好的 Markdown 文档**，解释系统的架构、功能、主要流程、关键组件和技术栈。  
本文档应作为一份**技术入门指南**。  
在可能的情况下，通过提供**指向相关文件、类和函数的直接链接**，以及有助于阐明概念的代码示例，来提升可导航性。

---

## **详细说明——请涵盖以下要点：**

### 1. **README / 说明文件摘要**
- 查找诸如 `README.md`、`LEIAME.md`、`CONTRIBUTING.md` 或类似文档的文件。
- 对新开发者最相关的部分提供客观而详细的摘要，包括：
  - 项目概述
  - 如何在本地搭建并运行系统
  - 采用的标准和约定
  - 贡献指南（如有）

---

### 2. **详细技术栈**
- 识别并列出项目中使用的完整技术栈：
  - 编程语言，在可检测时包括版本（例如，来自 `package.json`、`pom.xml`、`.tool-versions`、`requirements.txt`、`build.gradle` 等）。
  - 主要框架（后端、前端等——例如 Spring Boot、.NET、React、Angular、Vue、Django、Rails）。
  - 数据库：
    - 类型（SQL / NoSQL）
    - 名称（PostgreSQL、MongoDB 等）
  - 核心架构风格（例如，单体、微服务、无服务器、MVC、MVVM、整洁架构）。
  - 云平台（如可通过 SDK 或配置识别——AWS、Azure、GCP）。
  - 构建工具和包管理器（Maven、Gradle、npm、yarn、pip）。
  - 任何其他相关技术（缓存、消息代理、容器化——Docker、Kubernetes）。
- **引用并链接展示每一项的配置文件。**

---

### 3. **系统概述与用途**
- 清晰描述系统做什么以及面向谁。
- 它解决什么问题？
- 列出核心功能。
- 如有可能，将系统与所涉及的业务领域关联起来。
- 对主要功能进行高层描述。

---

### 4. **项目结构与阅读建议**
- **入口点：**  
  我应该从哪里开始探索代码？识别主要入口点（例如 `main.go`、`index.js`、`Program.cs`、`app.py`、`Application.java`）。  
  **提供指向这些文件的直接链接。**
- **总体组织：**  
  解释整体文件夹和文件结构。突出重要约定。  
  **使用真实的文件夹和文件名示例。**
- **配置：**  
  是否有主要配置文件？（例如 `config.yaml`、`.env`、`appsettings.json`）  
  哪些配置至关重要？  
  **提供链接。**
- **阅读建议：**  
  建议一个顺序或一组应优先阅读的关键文件/模块，以便快速掌握项目核心概念。

---

### 5. **关键组件**
- 识别并描述最重要或最核心的模块、类、函数或服务。
- 解释每个组件的职责。
- 描述它们的职责和相互依赖关系。
- 对于每个组件：
  - 包含一段有代表性的代码片段
  - 提供指向其实现位置的链接
- **尽可能提供直接链接和代码示例。**

---

### 6. **执行与数据流**
- 描述最常见或最关键的工作流或业务流程（例如，订单处理、用户认证）。
- 解释数据如何在系统中流动：
  - 数据在哪里持久化
  - 如何读取、修改和传播
- **尽可能用示例说明并链接到相关函数或类。**

#### 6.1 **数据库模式概述（如适用）**
- 对于数据密集型应用：
  - 识别主要实体/表/集合
  - 描述它们的主要关系
  - 如可用，基于 ORM 模型、迁移或模式文件进行说明

---

### 7. **依赖与集成**
- **依赖：**  
  列出主要的外部库、框架和 SDK。  
  简要说明每一项的作用。  
  **提供指向其配置位置或最常用位置的链接。**
- **集成：**  
  识别并解释与外部服务、附加数据库、第三方 API、消息代理等的集成。  
  通信如何发生？  
  **指向负责的模块/类并包含链接。**

#### 7.1 **API 文档（如适用）**
- 如果项目对外暴露 API：
  - 是否有 API 文档工具或标准的迹象（例如 Swagger/OpenAPI、Javadoc、特定端点的 docstring）？
  - 在哪里可以找到这些文档，或如何生成？

---

### 8. **图表**
- 生成高层图表以可视化系统架构和行为：
  - 组件图（突出主要模块及其交互）
  - 数据流图（展示信息如何在系统中移动）
  - 类图（如适用，展示关键类及其关系）
  - 简化部署图（组件运行的位置，如可检测）
  - 简化基础设施/部署图（如基础设施细节明显）
- **在 Markdown 文件中使用 Mermaid 语法创建这些图表。**
- 图表应为**高层**；不需要大量细节。

---

### 9. **测试**
- 是否有自动化测试？
  - 单元测试
  - 集成测试
  - 端到端（E2E）测试
- 它们在项目中的位置？
- 使用哪些测试框架？
- 测试通常如何执行？
- 如何在本地运行测试？
- 是否有涉及测试的 CI/CD 策略？

---

### 10. **错误处理与日志记录**
- 应用程序通常如何处理错误？
  - 是否有标准模式（例如，全局中间件、自定义异常）？
- 使用哪个日志库？
- 是否有标准日志格式？
- 是否有与监控工具（例如 Datadog、Sentry）的可见集成？

---

### 11. **安全考量**
- 代码中是否有明显的安全机制？
  - 认证
  - 授权（中间件/过滤器）
  - 输入验证
- 是否显著使用了特定的安全库（例如 Spring Security、Passport.js、JWT 库）？
- 是否有值得注意的安全实践？
  - 密钥管理
  - 对常见攻击的防护

---

### 12. **其他相关观察（包括构建/部署）**
- 是否有与**构建或部署**相关的文件？
  - `Dockerfile`
  - `docker-compose.yml`
  - 构建/部署脚本
  - CI/CD 配置文件（例如 `.github/workflows/`、`.gitlab-ci.yml`）
- 这些文件说明了什么 应用程序是如何构建和部署的？
- 还有没有其他对新开发者至关重要或特别有帮助的内容？
  - 注释中提到的已知技术债务
  - 不寻常的设计模式
  - 重要的编码约定
  - 性能注意事项

---

## **最终输出格式**
- 将完整回复生成为**格式良好的 Markdown（`.md`）文档**。
- 使用**清晰直接的语言**。
- 按照上述编号章节，用**标题和副标题**组织内容。
- **包含相关代码片段**（简短且有代表性）。
- 每当提及具体代码元素时，**包含可点击链接**，指向文件、函数、类和定义。
- 使用上述编号章节组织结构，以提高可读性。

**尽可能做到：**
- 包含指向文件、函数和类的**可点击链接**。
- 展示**简短且有代表性的代码片段**。
- 对列表使用**项目符号或表格**。

---

### **重要**
分析必须考虑**项目中的所有文件**。  
阅读并理解完整执行此任务并全面理解系统所需的**所有必要文件**。

---

### **操作**
请分析我当前环境/工作区中可用的源代码，并按请求生成 Markdown 文档。

输出文件名必须遵循以下格式：  
`<yyyy-mm-dd-project-name-app-dev-discovery_cursor.md>`

# **代码分析与系统文档生成提示词**

你是代码分析和系统文档方面的专家。你的任务是分析本项目/工作区中提供的源代码，并生成一份全面的 Markdown 文档，作为面向多个受众（高管、技术、业务和产品）的入门指南。

## **说明**

分析提供的源代码并提取以下信息，将其组织成结构良好的 Markdown 文档：

---

## **1. 高管层视角：执行摘要**

### **应用目的**
- 该系统的主要目标是什么？
- 它在高层面上旨在解决什么问题？

### **工作原理（高层概述）**
- 以简洁易懂的方式为非技术受众描述整体系统流程。
- 系统执行的主要步骤或流程是什么？

### **高层业务规则**
- 识别并描述代码中实现的主要业务规则。
- 系统遵循的基本业务策略、约束或逻辑是什么？

### **关键收益**
- 该系统为组织或其用户带来的主要收益是什么？

---

## **2. 技术层视角：技术概览**

### **系统架构**
- 基于代码分析描述整体系统架构。
- 它是否遵循特定模式（例如单体、微服务等）？
- 识别出的主要组件或模块有哪些？

### **使用的技术（技术栈）**
- 列出项目中使用的所有编程语言、框架、库、数据库和其他技术。

### **主要技术流程**
- 详细说明系统内的主要数据和执行流程。
- 不同组件之间如何交互？

### **关键组件**
- 识别并描述最重要的系统组件，解释它们在架构中的角色和职责。

### **代码复杂度（观察）**
- 基于你的分析，提供关于代码复杂度的一般性观察（例如结构良好、模块化、明显复杂度较高的区域）。

### **图表**
- 生成高层图表以可视化系统架构和行为：
  - 组件图（聚焦主要模块及其交互）
  - 数据流图（展示信息如何在系统中流动）
  - 类图（呈现关键类及其关系，如适用）
  - 简化部署图（展示组件运行位置，如可检测）
  - 简化基础设施/部署图（如基础设施细节明显）
- **在 Markdown 文件中使用 Mermaid 语法创建上述图表。图表应保持高层，不要过于详细。**

---

## **3. 产品视角：产品摘要**

### **系统功能（详细）**
- 详细描述系统的主要功能。
- 用户可以执行哪些任务或操作？

### **系统面向对象（用户/客户）**
- 识别系统的主要目标受众。
- 谁是最终用户或从中受益的客户？

### **解决的问题（满足的需求）**
- 系统帮助用户或组织解决哪些具体问题？
- 它满足了哪些需求？

### **用例/用户旅程（高层）**
- 系统的主要用例是什么？
- 用户如何与系统交互以实现其目标？

### **核心功能**
- 清晰简洁地列出最重要的系统功能。

### **业务领域**
- 识别系统覆盖的主要业务领域（例如销售、库存、财务）。

---

## **分析局限性**

- 代码分析过程中遇到的主要局限性是什么？
- 简要描述是什么限制了你对代码的理解。
- 提供减少或消除这些局限性的建议。

---

## **文档指南**

### **文档格式**
- 文档必须使用 Markdown 格式，每个部分都有清晰的标题和副标题。
- 使用列表、表格和其他 Markdown 元素以提高可读性和理解度。

### **附加说明**
- 专注于提供相关的高层信息，避免过多的实现细节，除非对理解至关重要。
- 使用清晰、简洁且适合多个受众的易懂语言。
- 基于代码分析尽可能具体。
- 将完整回复生成为**格式良好的 Markdown（`.md`）文档**。
- 使用**清晰直接的语言**。
- 根据上述部分使用**标题和副标题**。

### **文档标题**
**应用的高管与业务分析 – "<application-name>"**

### **文档摘要**
本文档是对 <system-name> 系统源代码分析的结果，涵盖以下领域：

- **高管层视角：** 应用目的、高层运作、主要业务规则和关键收益的摘要。
- **技术层视角：** 关于系统架构、使用的技术、主要流程、关键组件和图表（组件、数据流、类和部署）的详细信息。
- **产品视角：** 系统功能、目标用户、解决的问题、主要用例、功能和业务领域的详细描述。
- **分析局限性：** 识别关键分析约束以及克服这些约束的建议。

分析基于可用的源代码文件。

---

## **重要**
分析必须考虑**所有项目文件**。  
阅读并理解执行任务和实现对系统完整理解所需的**所有必要文件**。

---

## **操作**
请分析我当前环境/工作区中可用的源代码，并生成所请求的 Markdown 文档。

输出文件名必须遵循以下格式：  
`<yyyy-mm-dd-project-name-app-discovery_cursor.md>`