中文译文
背景：
我是一名刚加入项目的开发者，正在使用你——一个 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. 其他相关观察（包括构建/部署）
- 是否有与构建或部署相关的文件？
Dockerfiledocker-compose.yml- 构建/部署脚本
- CI/CD 配置文件（例如
.github/workflows/、.gitlab-ci.yml）
- 这些文件说明了应用程序是如何构建和部署的？
- 是否还有其他对新开发者至关重要或特别有帮助的内容？
- 注释中提到的已知技术债务
- 不寻常的设计模式
- 重要的编码约定
- 性能说明
最终输出格式
- 将完整回复生成为一份格式良好的 Markdown（
.md）文档。 - 使用清晰直接的语言。
- 按照上述编号章节，用标题和副标题组织内容。
- 包含相关代码片段（简短且有代表性）。
- 每当提到具体代码元素时，包含指向文件、函数、类和定义的可点击链接。
- 使用上述编号章节来组织文档，以提高可读性。
尽可能做到：
- 包含指向文件、函数和类的可点击链接。
- 展示简短且有代表性的代码片段。
- 对列表使用项目符号或表格。
重要
分析必须考虑项目中的所有文件。 阅读并理解所有必要的文件，以完整执行此任务并实现对系统的完整理解。
操作
请分析我当前环境/工作区中可用的源代码，并按请求生成 Markdown 文档。
输出文件名必须遵循以下格式：
<yyyy-mm-dd-project-name-app-dev-discovery_cursor.md>
English original
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).
- Programming language(s), including versions when detectable (e.g., from
- 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?
Dockerfiledocker-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>