<!-- 由 BMAD™ Core 驱动 -->

# 记录现有项目

## 目的

为现有项目生成为AI开发代理优化的综合文档。此任务创建结构化的参考资料，使AI代理能够理解项目背景、惯例和模式，从而有效地为任何代码库做出贡献。

## 任务说明

### 1. 初步项目分析

**关键：** 首先，检查上下文中是否存在PRD或需求文档。如果存在，则用它来将您的文档工作重点放在相关领域。

**如果存在PRD：**

-   审查PRD以了解计划中的增强/功能
-   确定将受影响的模块、服务或区域
-   仅将文档重点放在这些相关区域
-   跳过代码库中不相关的部分，以保持文档精简

**如果不存在PRD：**
询问用户：

“我注意到您没有提供PRD或需求文档。为了创建更专注、更有用的文档，我推荐以下选项之一：

1.  **首先创建PRD** - 您希望我在记录之前帮助创建棕地PRD吗？这有助于将文档重点放在相关领域。

2.  **提供现有需求** - 您是否有可以共享的需求文档、史诗或功能描述？

3.  **描述重点** - 您能简要描述您计划的增强或功能吗？例如：
    -   ‘向用户服务添加支付处理’
    -   ‘重构身份验证模块’
    -   ‘与新的第三方API集成’

4.  **记录所有内容** - 或者我应该继续对整个代码库进行综合文档记录？（注意：对于大型项目，这可能会产生过多的文档）

请告诉我您的偏好，或者如果您愿意，我可以继续进行完整的文档记录。”

根据他们的回应：

-   如果他们选择选项1-3：使用该背景来专注文档记录
-   如果他们选择选项4或拒绝：继续下面的综合分析

首先对现有项目进行分析。使用可用工具：

1.  **项目结构发现**：检查根目录结构，识别主文件夹，并了解整体组织
2.  **技术栈识别**：查找package.json、requirements.txt、Cargo.toml、pom.xml等，以识别语言、框架和依赖项
3.  **构建系统分析**：查找构建脚本、CI/CD配置和开发命令
4.  **现有文档审查**：检查README文件、docs文件夹和任何现有文档
5.  **代码模式分析**：抽样关键文件以了解编码模式、命名约定和架构方法

向用户提出这些启发性问题，以更好地了解他们的需求：

-   该项目的主要目的是什么？
-   代码库中是否有任何特定领域对于代理理解特别复杂或重要？
-   您希望AI代理在该项目上执行哪些类型的任务？（例如，错误修复、功能添加、重构、测试）
-   您是否有任何偏好的现有文档标准或格式？
-   文档应针对哪个技术细节级别？（初级开发人员、高级开发人员、混合团队）
-   您是否正在计划特定的功能或增强？（这有助于专注文档记录）

### 2. 深入代码库分析

关键：在生成文档之前，对现有代码库进行广泛分析：

1.  **探索关键领域**：
    -   入口点（主文件、索引文件、应用程序初始化程序）
    -   配置文件和环境设置
    -   包依赖项和版本
    -   构建和部署配置
    -   测试套件和覆盖率

2.  **提出澄清问题**：
    -   “我看到您正在使用[技术X]。我应该记录任何自定义模式或惯例吗？”
    -   “开发人员在此系统中最关键/复杂的部分是什么？”
    -   “我应该捕获任何未记录的‘部落知识’领域吗？”
    -   “我应该记录哪些技术债务或已知问题？”
    -   “代码库的哪些部分更改最频繁？”

3.  **映射现实**：
    -   识别实际使用的模式（而不是理论上的最佳实践）
    -   找到关键业务逻辑的位置
    -   定位集成点和外部依赖项
    -   记录变通方法和技术债务
    -   注意与标准模式不同的区域

**如果提供了PRD**：还要分析增强功能需要更改什么

### 3. 核心文档生成

[[LLM: 生成一份反映代码库实际状态的综合性棕地架构文档。

**关键**：这不是一份理想化的架构文档。记录存在的内容，包括：

-   技术债务和变通方法
-   不同部分之间不一致的模式
-   无法更改的旧代码
-   集成约束
-   性能瓶颈

**文档结构**：

# [项目名称] 棕地架构文档

## 引言

本文档记录了[项目名称]代码库的当前状态，包括技术债务、变通方法和实际模式。它作为AI代理进行增强工作的参考。

### 文档范围

[如果提供了PRD：“专注于与以下内容相关的领域：{增强描述}”]
[如果没有PRD：“整个系统的综合文档”]

### 变更日志

| 日期 | 版本 | 描述 | 作者 |
| --- | --- | --- | --- |
| [日期] | 1.0 | 初始棕地分析 | [分析师] |

## 快速参考 - 关键文件和入口点

### 理解系统的关键文件

-   **主入口**：`src/index.js`（或实际入口点）
-   **配置**：`config/app.config.js`、`.env.example`
-   **核心业务逻辑**：`src/services/`、`src/domain/`
-   **API定义**：`src/routes/`或指向OpenAPI规范的链接
-   **数据库模型**：`src/models/`或指向模式文件的链接
-   **关键算法**：[列出具有复杂逻辑的特定文件]

### 如果提供了PRD - 增强影响区域

[突出显示计划的增强将影响哪些文件/模块]

## 高层架构

### 技术摘要

### 实际技术栈（来自package.json/requirements.txt）

| 类别 | 技术 | 版本 | 说明 |
| --- | --- | --- | --- |
| 运行时 | Node.js | 16.x | [任何约束] |
| 框架 | Express | 4.18.2 | [自定义中间件？] |
| 数据库 | PostgreSQL | 13 | [连接池设置] |

等等...

### 存储库结构现实检查

-   类型：[单体仓库/多仓库/混合]
-   包管理器：[npm/yarn/pnpm]
-   值得注意的：[任何不寻常的结构决策]

## 源代码树和模块组织

### 项目结构（实际）

```text
project-root/
├── src/
│   ├── controllers/     # HTTP请求处理程序
│   ├── services/        # 业务逻辑（注意：用户和支付服务之间的模式不一致）
│   ├── models/          # 数据库模型（Sequelize）
│   ├── utils/           # 混合包 - 需要重构
│   └── legacy/          # 请勿修改 - 仍在使用的旧支付系统
├── tests/               # Jest测试（覆盖率60%）
├── scripts/             # 构建和部署脚本
└── config/              # 环境配置
```

### 关键模块及其用途

-   **用户管理**：`src/services/userService.js` - 处理所有用户操作
-   **身份验证**：`src/middleware/auth.js` - 基于JWT的自定义实现
-   **支付处理**：`src/legacy/payment.js` - 关键：不要重构，紧密耦合
-   **[列出其他关键模块及其各自的文件]**

## 数据模型和API

### 数据模型

不要重复，而是引用实际的模型文件：

-   **用户模型**：参见 `src/models/User.js`
-   **订单模型**：参见 `src/models/Order.js`
-   **相关类型**：`src/types/` 中的TypeScript定义

### API规范

-   **OpenAPI规范**：`docs/api/openapi.yaml`（如果存在）
-   **Postman集合**：`docs/api/postman-collection.json`
-   **手动端点**：[列出发现的任何未记录的端点]

## 技术债务和已知问题

### 关键技术债务

1.  **支付服务**：`src/legacy/payment.js` 中的旧代码 - 紧密耦合，没有测试
2.  **用户服务**：与其他服务模式不同，使用回调而不是Promise
3.  **数据库迁移**：手动跟踪，没有合适的迁移工具
4.  **[其他重大债务]**

### 变通方法和陷阱

-   **环境变量**：即使对于预发环境，也必须设置 `NODE_ENV=production`（历史原因）
-   **数据库连接**：连接池硬编码为10，更改会破坏支付服务
-   **[开发人员需要知道的其他变通方法]**

## 集成点和外部依赖

### 外部服务

| 服务 | 目的 | 集成类型 | 关键文件 |
| --- | --- | --- | --- |
| Stripe | 支付 | REST API | `src/integrations/stripe/` |
| SendGrid | 电子邮件 | SDK | `src/services/emailService.js` |

等等...

### 内部集成点

-   **前端通信**：端口3000上的REST API，需要特定的头信息
-   **后台作业**：Redis队列，参见 `src/workers/`
-   **[其他集成]**

## 开发和部署

### 本地开发设置

1.  实际可行的步骤（不是理想步骤）
2.  设置的已知问题
3.  所需的环境变量（参见 `.env.example`）

### 构建和部署过程

-   **构建命令**：`npm run build`（webpack配置在 `webpack.config.js` 中）
-   **部署**：通过 `scripts/deploy.sh` 手动部署
-   **环境**：开发、预发、生产（参见 `config/environments/`）

## 测试现状

### 当前测试覆盖率

-   单元测试：60%覆盖率（Jest）
-   集成测试：最少，在 `tests/integration/` 中
-   端到端测试：无
-   手动测试：主要的QA方法

### 运行测试

```bash
npm test           # 运行单元测试
npm run test:integration  # 运行集成测试（需要本地数据库）
```

## 如果提供了增强PRD - 影响分析

### 需要修改的文件

根据增强需求，这些文件将受到影响：

-   `src/services/userService.js` - 添加新的用户字段
-   `src/models/User.js` - 更新模式
-   `src/routes/userRoutes.js` - 新的端点
-   [等等...]

### 需要的新文件/模块

-   `src/services/newFeatureService.js` - 新的业务逻辑
-   `src/models/NewFeature.js` - 新的数据模型
-   [等等...]

### 集成注意事项

-   需要与现有的身份验证中间件集成
-   必须遵循 `src/utils/responseFormatter.js` 中的现有响应格式
-   [其他集成点]

## 附录 - 有用的命令和脚本

### 常用命令

```bash
npm run dev         # 启动开发服务器
npm run build       # 生产构建
npm run migrate     # 运行数据库迁移
npm run seed        # 填充测试数据
```

### 调试和故障排除

-   **日志**：检查 `logs/app.log` 以获取应用程序日志
-   **调试模式**：设置 `DEBUG=app:*` 以获取详细日志
-   **常见问题**：参见 `docs/troubleshooting.md`]]

### 4. 文档交付

1.  **在Web UI中（Gemini, ChatGPT, Claude）**：
    -   在一个响应中呈现整个文档（如果太长则分多个）
    -   告诉用户复制并另存为 `docs/brownfield-architecture.md` 或 `docs/project-architecture.md`
    -   如果需要，提及以后可以在IDE中分片

2.  **在IDE环境中**：
    -   将文档创建为 `docs/brownfield-architecture.md`
    -   告知用户此单个文档包含所有架构信息
    -   如果需要，以后可以使用PO代理分片

文档应足够全面，以便将来的代理能够理解：

-   系统的实际状态（非理想化）
-   在哪里找到关键文件和逻辑
-   存在哪些技术债务
-   必须遵守哪些约束
-   如果提供了PRD：增强功能需要更改什么]]

### 5. 质量保证

关键：在最终确定文档之前：

1.  **准确性检查**：验证所有技术细节与实际代码库匹配
2.  **完整性审查**：确保所有主要系统组件都已记录
3.  **重点验证**：如果用户提供了范围，验证相关领域是否被强调
4.  **清晰度评估**：检查解释对AI代理是否清晰
5.  **导航**：确保文档具有清晰的章节结构，便于参考

在主要章节后应用高级启发任务，以根据用户反馈进行完善。

## 成功标准

-   创建了单一的综合性棕地架构文档
-   文档反映了现实，包括技术债务和变通方法
-   关键文件和模块用实际路径引用
-   模型/API引用源文件而不是重复内容
-   如果提供了PRD：清晰的影响分析，显示需要更改的内容
-   文档使AI代理能够导航和理解实际代码库
-   清楚地记录了技术约束和“陷阱”

## 说明

-   此任务创建一个捕获系统真实状态的单一文档
-   尽可能引用实际文件而不是重复内容
-   诚实地记录技术债务、变通方法和约束
-   对于有PRD的棕地项目：提供清晰的增强影响分析
-   目标是为从事实际工作的AI代理提供实用的文档