供刚加入项目的开发者使用，让 AI 编程助手分析代码库，输出说明架构、流程和技术栈的 Markdown 文档。
**上下文：** 我是一名刚刚加入项目的开发人员，正在使用你——一个 AI 编码助手——来深入理解现有的代码库。我的目标是尽快变得高效，并基于对当前系统的扎实理解做出明智的技术决策。 **主要目标：** 分析在此项目/工作区中提供的源代码，并生成一份**详细、清晰且结构良好的 Markdown 文档**，解释系统的架构、功能、主要流程、关键组件和技术栈。 该文档应作为一份**技术入职指南**。 在可能的情况下，通过提供指向相关文件、类和函数的**直接链接**，以及有助于阐明概念的代码示例，来提升可导航性。 --- ## **详细说明——请逐一回答以下问题：** ### 1. **README / 指令文件摘要** - 查找如 `README.md`、`LEIAME.md`、`CONTRIBUTING.md` 或类似的文档文件。 - 对新开发者最相关的部分提供客观但详细的摘要，包括： - 项目概述 - 如何在本地设置并运行系统 - 采用的标准与规范 - 贡献指南（如果存在） - 这些文档可以在哪里找到，或者如何生成？ --- ### 8. **图表** - 生成高层级图表以可视化系统架构和行为： - 组件图（突出主要模块及其交互） - 数据流图（展示信息在系统中的流动方式） - 类图（展示关键类及其关系，如适用） - 简化部署图（组件运行的位置，如可检测到） - 简化基础设施/部署图（如可明显看出基础设施细节） - **使用 Mermaid 语法在 Markdown 文件中创建这些图表。** - 图表应为**高层级**；无需详尽细节。 --- ### 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>`
**Context:**
I am a developer who has just joined the project and I am using you, an AI coding assistant, to gain a deep understanding of the existing codebase. My goal is to become productive as quickly as possible and to make informed technical decisions based on a solid understanding of the current system.
**Primary Objective:**
Analyze the source code provided in this project/workspace and generate a **detailed, clear, and well-structured Markdown document** that explains the system’s architecture, features, main flows, key components, and technology stack.
This document should serve as a **technical onboarding guide**.
Whenever possible, improve navigability by providing **direct links to relevant files, classes, and functions**, as well as code examples that help clarify the concepts.
---
## **Detailed Instructions — Please address the following points:**
### 1. **README / Instruction Files Summary**
- Look for files such as `README.md`, `LEIAME.md`, `CONTRIBUTING.md`, or similar documentation.
- Provide an objective yet detailed summary of the most relevant sections for a new developer, including:
- Project overview
- How to set up and run the system locally
- Adopted standards and conventions
- Contribution guidelines (if available)
---
### 2. **Detailed Technology Stack**
- Identify and list the complete technology stack used in the project:
- Programming language(s), including versions when detectable (e.g., from `package.json`, `pom.xml`, `.tool-versions`, `requirements.txt`, `build.gradle`, etc.).
- Main frameworks (backend, frontend, etc. — e.g., Spring Boot, .NET, React, Angular, Vue, Django, Rails).
- Database(s):
- Type (SQL / NoSQL)
- Name (PostgreSQL, MongoDB, etc.)
- Core architecture style (e.g., Monolith, Microservices, Serverless, MVC, MVVM, Clean Architecture).
- Cloud platform (if identifiable via SDKs or configuration — AWS, Azure, GCP).
- Build tools and package managers (Maven, Gradle, npm, yarn, pip).
- Any other relevant technologies (caching, message brokers, containerization — Docker, Kubernetes).
- **Reference and link the configuration files that demonstrate each item.**
---
### 3. **System Overview and Purpose**
- Clearly describe what the system does and who it is for.
- What problems does it solve?
- List the core functionalities.
- If possible, relate the system to the business domains involved.
- Provide a high-level description of the main features.
---
### 4. **Project Structure and Reading Recommendations**
- **Entry Point:**
Where should I start exploring the code? Identify the main entry points (e.g., `main.go`, `index.js`, `Program.cs`, `app.py`, `Application.java`).
**Provide direct links to these files.**
- **General Organization:**
Explain the overall folder and file structure. Highlight important conventions.
**Use real folder and file name examples.**
- **Configuration:**
Are there main configuration files? (e.g., `config.yaml`, `.env`, `appsettings.json`)
Which configurations are critical?
**Provide links.**
- **Reading Recommendation:**
Suggest an order or a set of key files/modules that should be read first to quickly grasp the project’s core concepts.
---
### 5. **Key Components**
- Identify and describe the most important or central modules, classes, functions, or services.
- Explain the responsibilities of each component.
- Describe their responsibilities and interdependencies.
- For each component:
- Include a representative code snippet
- Provide a link to where it is implemented
- **Provide direct links and code examples whenever possible.**
---
### 6. **Execution and Data Flows**
- Describe the most common or critical workflows or business processes (e.g., order processing, user authentication).
- Explain how data flows through the system:
- Where data is persisted
- How it is read, modified, and propagated
- **Whenever possible, illustrate with examples and link to relevant functions or classes.**
#### 6.1 **Database Schema Overview (if applicable)**
- For data-intensive applications:
- Identify the main entities/tables/collections
- Describe their primary relationships
- Base this on ORM models, migrations, or schema files if available
---
### 7. **Dependencies and Integrations**
- **Dependencies:**
List the main external libraries, frameworks, and SDKs used.
Briefly explain the role of each one.
**Provide links to where they are configured or most commonly used.**
- **Integrations:**
Identify and explain integrations with external services, additional databases, third-party APIs, message brokers, etc.
How does communication occur?
**Point to the modules/classes responsible and include links.**
#### 7.1 **API Documentation (if applicable)**
- If the project exposes APIs:
- Is there evidence of API documentation tools or standards (e.g., Swagger/OpenAPI, Javadoc, endpoint-specific docstrings)?
- Where can this documentation be found or how can it be generated?
---
### 8. **Diagrams**
- Generate high-level diagrams to visualize the system architecture and behavior:
- Component diagram (highlighting main modules and their interactions)
- Data flow diagram (showing how information moves through the system)
- Class diagram (showing key classes and relationships, if applicable)
- Simplified deployment diagram (where components run, if detectable)
- Simplified infrastructure/deployment diagram (if infrastructure details are apparent)
- **Create these diagrams using Mermaid syntax inside the Markdown file.**
- Diagrams should be **high-level**; extensive detailing is not required.
---
### 9. **Testing**
- Are there automated tests?
- Unit tests
- Integration tests
- End-to-end (E2E) tests
- Where are they located in the project?
- Which testing framework(s) are used?
- How are tests typically executed?
- How can tests be run locally?
- Is there any CI/CD strategy involving tests?
---
### 10. **Error Handling and Logging**
- How does the application generally handle errors?
- Is there a standard pattern (e.g., global middleware, custom exceptions)?
- Which logging library is used?
- Is there a standard logging format?
- Is there visible integration with monitoring tools (e.g., Datadog, Sentry)?
---
### 11. **Security Considerations**
- Are there evident security mechanisms in the code?
- Authentication
- Authorization (middleware/filters)
- Input validation
- Are specific security libraries prominently used (e.g., Spring Security, Passport.js, JWT libraries)?
- Are there notable security practices?
- Secrets management
- Protection against common attacks
---
### 12. **Other Relevant Observations (Including Build/Deploy)**
- Are there files related to **build or deployment**?
- `Dockerfile`
- `docker-compose.yml`
- Build/deploy scripts
- CI/CD configuration files (e.g., `.github/workflows/`, `.gitlab-ci.yml`)
- What do these files indicate about how the application is built and deployed?
- Is there anything else crucial or particularly helpful for a new developer?
- Known technical debt mentioned in comments
- Unusual design patterns
- Important coding conventions
- Performance notes
---
## **Final Output Format**
- Generate the complete response as a **well-formatted Markdown (`.md`) document**.
- Use **clear and direct language**.
- Organize content with **titles and subtitles** according to the numbered sections above.
- **Include relevant code snippets** (short and representative).
- **Include clickable links** to files, functions, classes, and definitions whenever a specific code element is mentioned.
- Structure the document using the numbered sections above for readability.
**Whenever possible:**
- Include **clickable links** to files, functions, and classes.
- Show **short, representative code snippets**.
- Use **bullet points or tables** for lists.
---
### **IMPORTANT**
The analysis must consider **ALL files in the project**.
Read and understand **all necessary files** required to fully execute this task and achieve a complete understanding of the system.
---
### **Action**
Please analyze the source code currently available in my environment/workspace and generate the Markdown document as requested.
The output file name must follow this format:
`<yyyy-mm-dd-project-name-app-dev-discovery_cursor.md>`