# requirements-pool

**Repository Path**: anghuiyan/requirements-pool

## Basic Information

- **Project Name**: requirements-pool
- **Description**: 一个智能的需求管理工具，帮助你管理需求缓冲池，分析需求对项目的影响和优先级，辅助成长为架构师。
- **Primary Language**: Unknown
- **License**: Zlib
- **Default Branch**: develop
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-12-21
- **Last Updated**: 2025-12-30

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 需求缓冲池管理系统

一个智能的需求管理工具，帮助你管理需求缓冲池，分析需求对项目的影响和优先级，辅助成长为架构师。

## 🛠️ 技术栈

本项目采用 **Node.js** 技术栈构建，具体技术选型如下：

### 后端技术栈
- **Node.js**: JavaScript 运行时环境，提供跨平台支持
- **CommonJS**: 模块系统，使用 `require/module.exports`
- **Express.js**: Web 框架（Web 版本）

### 前端技术栈
- **React 18**: 现代化 UI 框架
- **Vite**: 快速构建工具
- **Ant Design 5**: 企业级 UI 组件库
- **React Router**: 路由管理
- **Axios**: HTTP 客户端

### 主要依赖库
- **[inquirer](https://github.com/SBoudrias/Inquirer.js)** (^8.2.6): 交互式命令行界面库，提供丰富的终端交互体验
  - 支持列表选择、输入框、确认对话框、编辑器等多种交互方式
  - 让终端操作更加友好和直观
- **[chalk](https://github.com/chalk/chalk)** (^4.1.2): 终端字符串样式库，提供彩色输出
  - 用于美化终端输出，提升可读性
  - 支持不同颜色、粗体、下划线等样式
- **[dayjs](https://github.com/iamkun/dayjs)** (^1.11.10): 轻量级日期处理库
  - 用于处理需求创建时间、更新时间等日期操作
  - 相比 Moment.js 更轻量，API 简洁
- **[fs-extra](https://github.com/jprichardson/node-fs-extra)** (^11.2.0): 文件系统增强库
  - 扩展 Node.js 原生 `fs` 模块
  - 提供 JSON 读写、目录创建等便捷方法

### 数据存储
- **JSON 文件**: 使用 JSON 格式存储需求数据
  - 无需数据库，轻量级，易于备份和迁移
  - 数据存储在 `requirements/requirements.json`

### 为什么选择终端界面？

1. **快速启动**: 无需启动浏览器，打开终端即可使用
2. **轻量高效**: 不占用浏览器资源，运行速度快
3. **专注体验**: 终端界面简洁，减少干扰，专注于需求管理
4. **跨平台**: Node.js 支持 Windows、macOS、Linux，终端界面通用性好
5. **易于集成**: 可以轻松集成到脚本、自动化流程中
6. **低资源消耗**: 相比 Web 应用，资源占用更少

## ✨ 功能特性

- 📝 **需求管理**: 添加、查看、更新、删除需求
- 🔍 **智能分析**: 自动分析需求的技术影响、业务影响和风险
- ⭐ **优先级评估**: 基于多维度因素智能建议优先级
- 🔗 **依赖分析**: 自动识别需求之间的依赖关系
- 🏗️ **架构建议**: 提供架构设计相关的专业建议
- 💡 **成长辅助**: 通过分析报告学习架构思维

## 🚀 快速开始

### 方式一：终端 CLI 版本

#### 安装

```bash
npm install
```

#### 使用

启动交互式菜单：

```bash
npm start
```

或者直接使用命令：

```bash
# 添加新需求
npm run add

# 查看需求列表
npm run list

# 分析需求
npm run analyze [需求ID]
```

### 方式二：Web 前端版本（推荐）

#### 一键启动（推荐）

最简单的方式，一条命令同时启动前后端：

```bash
# 安装依赖（如果还没安装）
npm install
cd frontend && npm install && cd ..

# 一键启动前后端
npm run startAll
```

这将同时启动：
- 后端 API 服务器（http://localhost:3000）
- 前端开发服务器（http://localhost:5173）

两个服务会在同一个终端窗口中运行，使用不同颜色和前缀区分输出。按 `Ctrl+C` 可同时停止两个服务。

#### 分步启动

如果需要分别控制前后端服务，可以按以下步骤操作：

##### 1. 启动后端 API 服务器

```bash
# 安装后端依赖（如果还没安装）
npm install

# 安装 Web 服务器依赖
npm install express cors

# 启动后端 API 服务器
npm run server
```

后端 API 将在 `http://localhost:3000` 启动。

##### 2. 启动前端开发服务器

```bash
# 进入前端目录
cd frontend

# 安装前端依赖
npm install

# 启动前端开发服务器
npm run dev
```

前端将在 `http://localhost:5173` 启动，自动打开浏览器。

##### 3. 访问应用

打开浏览器访问 `http://localhost:5173`，即可使用现代化的 Web 界面管理需求。

#### 前端功能

- 🎨 **现代化 UI**: 基于 Ant Design 的美观界面
- 📊 **数据可视化**: 需求统计、分析报告可视化
- 🔍 **高级搜索**: 支持搜索、筛选、排序
- 📱 **响应式设计**: 支持桌面和移动设备
- ⚡ **快速操作**: 一键分析、批量操作

## 📖 使用指南

### 1. 添加新需求

运行 `npm start` 或 `npm run add`，系统会引导你输入：

- **需求标题**: 简洁明确的需求名称
- **需求描述**: 详细描述需求的内容、背景和目标
- **需求分类**: 功能、性能、安全、架构、优化、修复、其他
- **初始优先级**: 高、中、低
- **影响的项目**: 该需求会影响哪些项目
- **预估工作量**: 如 "2周"、"1个月"
- **标签**: 用于分类和关联相关需求
- **备注**: 其他需要记录的信息

添加完成后，系统会询问是否立即分析该需求。

### 2. 分析需求

系统会自动分析需求的以下方面：

#### 🔧 技术影响分析
- **影响级别**: 高/中/低
- **影响领域**: 架构设计、数据层、接口层、性能、安全性、前端、测试等
- **建议**: 针对不同技术领域提供专业建议

#### 💼 业务影响分析
- **影响级别**: 高/中/低
- **业务价值**: 用户体验提升、商业价值、效率提升、合规性等
- **影响用户**: 终端用户、内部用户等

#### ⚠️ 风险评估
- **风险级别**: 高/中/低
- **风险因素**: 系统变更风险、外部依赖风险、数据风险等
- **缓解措施**: 针对性的风险控制建议

#### 🔗 依赖关系
- **被阻塞**: 哪些需求被当前需求阻塞
- **阻塞当前需求**: 当前需求依赖哪些需求
- **相关需求**: 基于标签和分类的关联需求

#### ⭐ 优先级评估
基于技术影响、业务影响、风险和依赖关系，智能建议优先级调整。

#### 🏗️ 架构建议
针对高影响需求，提供架构设计、数据设计、风险管理、依赖管理等方面的专业建议。

### 3. 查看需求列表

运行 `npm run list` 查看所有需求，包括：
- 需求ID和标题
- 分类、优先级、状态
- 描述摘要
- 影响的项目
- 创建时间

### 4. 更新需求

可以更新需求的以下字段：
- 优先级
- 状态（待评估、已评估、规划中、开发中、测试中、已完成、已取消）
- 分类
- 标题
- 描述

### 5. 删除需求

谨慎删除需求，系统会要求确认。

## 📁 项目结构

```
requirements-pool/
├── backend/                    # 后端项目（独立）
│   ├── src/
│   │   ├── config.js          # 配置文件
│   │   ├── storage/           # 存储层抽象
│   │   ├── middleware/        # 中间件
│   │   ├── requirementsManager.js
│   │   ├── analyzer.js
│   │   ├── cli.js
│   │   ├── requirements/      # 数据目录
│   │   │   └── requirements.json
│   │   └── test/              # 测试脚本
│   ├── server.js              # Web API 服务器
│   ├── package.json
│   └── README.md
├── frontend/                   # 前端项目（独立）
│   ├── src/
│   │   ├── components/        # 公共组件
│   │   ├── pages/             # 页面组件
│   │   ├── services/          # API 服务
│   │   └── styles/            # 样式文件
│   ├── package.json
│   └── vite.config.js
├── test/                       # 前后端联动测试
│   └── test-integration.js
├── package.json                # 统一启动脚本
└── README.md
```

## 💾 数据存储

需求数据存储在 `backend/src/requirements/requirements.json` 文件中，采用JSON格式，包含：

- **requirements**: 需求列表
- **metadata**: 元数据（创建时间、更新时间、总数等）

每个需求包含以下字段：

```json
{
  "id": "0001",
  "title": "需求标题",
  "description": "需求描述",
  "category": "功能",
  "priority": "高",
  "status": "待评估",
  "impact": {},
  "affectedProjects": ["project1"],
  "estimatedEffort": "2周",
  "dependencies": [],
  "tags": ["标签1"],
  "createdAt": "2024-01-01 10:00:00",
  "updatedAt": "2024-01-01 10:00:00",
  "notes": "备注"
}
```

## 🎯 架构师成长路径

这个工具通过以下方式帮助你成长为架构师：

1. **系统性思维**: 通过多维度分析，培养全面思考问题的能力
2. **影响评估**: 学习如何评估需求对系统的技术影响和业务影响
3. **风险评估**: 识别和评估技术风险，制定缓解措施
4. **依赖管理**: 理解需求之间的依赖关系，合理安排实施顺序
5. **优先级判断**: 基于多因素综合判断优先级，培养决策能力
6. **架构设计**: 通过架构建议学习架构设计的最佳实践

## 🔍 分析关键词

系统会自动识别以下关键词进行分析：

### 技术关键词
- **架构相关**: 架构、架构设计、重构、微服务、分布式
- **数据相关**: 数据库、表结构、数据迁移、SQL
- **接口相关**: API、接口、服务、RPC
- **性能相关**: 性能、优化、缓存、并发
- **安全相关**: 安全、权限、认证、加密
- **前端相关**: 前端、UI、界面、组件
- **测试相关**: 测试、自动化、单元测试

### 业务关键词
- **用户相关**: 用户、客户、体验
- **商业相关**: 收入、付费、商业化、盈利
- **效率相关**: 效率、自动化、节省时间
- **合规相关**: 合规、法规、标准

### 风险关键词
- **变更风险**: 重构、迁移、替换
- **依赖风险**: 第三方、外部、依赖
- **数据风险**: 数据、迁移、备份

## 📝 使用示例

### 示例1: 添加并分析一个架构重构需求

```bash
npm start
# 选择 "添加新需求"
# 输入:
#   标题: 微服务架构重构
#   描述: 将单体应用拆分为微服务架构，提升系统可扩展性
#   分类: 架构
#   优先级: 高
#   影响项目: backend, frontend
#   预估工作量: 3个月
#   标签: 架构,重构,微服务
```

系统会自动识别这是一个高影响、高风险的架构需求，并提供详细的架构设计建议。

### 示例2: 分析需求依赖关系

当你添加多个相关需求后，运行分析命令，系统会自动识别：
- 哪些需求被当前需求阻塞
- 当前需求依赖哪些需求
- 相关的需求有哪些

这帮助你合理安排需求的实施顺序。

## 🤝 贡献

欢迎提出建议和改进！

## 🌐 Web 版本部署方案

虽然当前版本是终端 CLI 工具，但完全可以部署为 Web 应用。以下是几种实现方案：

### 方案一：基于 Express + React/Vue（推荐）

创建一个完整的 Web 应用，前后端分离：

**后端 (Express.js)**
- 使用现有的 `requirementsManager.js` 和 `analyzer.js` 作为业务逻辑层
- 创建 RESTful API 接口
- 提供需求 CRUD、分析等接口

**前端 (React/Vue)**
- 使用 React 或 Vue 构建现代化 UI
- 可视化展示需求列表、分析报告
- 支持图表展示依赖关系、优先级分布等

**优势**:
- 用户体验更好，支持图表可视化
- 多人协作，可以共享需求池
- 支持权限管理、评论等功能
- 可以部署到云服务器，通过域名访问

### 方案二：基于 Next.js（全栈框架）

使用 Next.js 构建全栈应用：
- 服务端渲染，性能更好
- API Routes 直接提供后端接口
- 前后端代码统一管理

### 方案三：基于 Electron（桌面应用）

将现有 CLI 工具包装为桌面应用：
- 保留现有代码逻辑
- 使用 Electron 创建桌面窗口
- 可以内嵌 Web 技术栈（HTML/CSS/JS）

### 快速 Web 版本实现示例

如果你想快速体验 Web 版本，可以：

1. **使用 Express 创建简单 API 服务器**:
```bash
npm install express cors
```

2. **创建 `server.js`**:
```javascript
const express = require('express');
const cors = require('cors');
const RequirementsManager = require('./src/requirementsManager');
const RequirementsAnalyzer = require('./src/analyzer');

const app = express();
app.use(cors());
app.use(express.json());

const manager = new RequirementsManager();
const analyzer = new RequirementsAnalyzer(manager);

// API 路由
app.get('/api/requirements', (req, res) => {
  res.json(manager.getAllRequirements());
});

app.post('/api/requirements', async (req, res) => {
  const requirement = await manager.addRequirement(req.body);
  res.json(requirement);
});

app.get('/api/requirements/:id/analyze', (req, res) => {
  const requirement = manager.getRequirementById(req.params.id);
  if (!requirement) {
    return res.status(404).json({ error: '需求不存在' });
  }
  const impact = analyzer.analyzeImpact(requirement);
  const priorityEval = analyzer.evaluatePriority(requirement);
  res.json({ impact, priorityEval });
});

app.listen(3000, () => {
  console.log('服务器运行在 http://localhost:3000');
});
```

3. **部署到云服务器**:
   - 使用 PM2 管理 Node.js 进程
   - 配置 Nginx 反向代理
   - 绑定域名和 SSL 证书

### 部署步骤（以 Express 为例）

1. **准备服务器**:
   - 购买云服务器（阿里云、腾讯云等）
   - 安装 Node.js 和 Nginx

2. **部署应用**:
```bash
# 上传代码到服务器
git clone your-repo
cd requirements-pool
npm install

# 使用 PM2 启动
npm install -g pm2
pm2 start server.js --name requirements-pool
```

3. **配置 Nginx**:
```nginx
server {
    listen 80;
    server_name your-domain.com;

    location / {
        proxy_pass http://localhost:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}
```

4. **配置域名和 SSL**:
   - 在域名解析中添加 A 记录指向服务器 IP
   - 使用 Let's Encrypt 免费 SSL 证书

### 未来规划

如果社区有需求，可以考虑：
- ✅ 开发 Web 版本（React/Vue + Express）
- ✅ 支持多用户和权限管理
- ✅ 需求评论和协作功能
- ✅ 数据可视化（图表、看板）
- ✅ 导出功能（PDF、Excel）
- ✅ 移动端适配

## 🔒 Git 版本控制说明

### .gitignore 配置

项目已配置 `.gitignore`，确保：

- ✅ **保留目录结构**：`screenshots/` 和 `reports/` 目录会被保留
- ❌ **忽略文件内容**：截图和日报文件不会被提交到 Git
- ✅ **保留源代码**：所有源代码文件正常跟踪

**配置详情**：

- 截图文件（`.png`, `.jpg`, `.jpeg` 等）会被忽略
- 日报文件（`.md`）会被忽略
- 目录结构通过 `.gitkeep` 文件保留

📖 **详细说明**：查看 [GITIGNORE_EXPLANATION.md](./GITIGNORE_EXPLANATION.md)

### 首次提交前

如果目录中已有文件，需要清理 Git 跟踪：

```bash
# 移除已跟踪的截图和日报文件（但保留本地文件）
git rm --cached screenshots/**/*.png screenshots/**/*.jpg
git rm --cached reports/**/*.md

# 提交 .gitignore 配置
git add .gitignore screenshots/.gitkeep reports/.gitkeep
git commit -m "配置 .gitignore，忽略截图和日报文件"
```

### Git 提交规范

Git 提交信息（Commit Message）的规范核心是**清晰、简洁、结构化**，目的是提升团队协作效率、便于追溯历史、自动化生成日志（如 CHANGELOG）。目前行业通用标准是 **[Conventional Commits](https://www.conventionalcommits.org/)**（约定式提交），以下是详细规范和实操指南：

#### **一、核心规范：结构化提交信息**

提交信息需包含 **「类型」「描述」**，可选 **「作用域」「正文」「脚注」**，格式如下：

```
<类型>[可选作用域]: <描述>

[可选正文]

[可选脚注]
```

#### **二、各部分详解**

1. **类型（Type）：必填，说明提交性质**

用**小写英文**，代表本次提交的核心变更类型，常用类型如下（按优先级排序）：

| 类型       | 含义                                                    | 示例场景                               |
| ---------- | ------------------------------------------------------- | -------------------------------------- |
| `feat`     | 新增功能（feature）                                     | 添加用户登录模块、新增API接口          |
| `fix`      | 修复 bug（bug fix）                                     | 修复订单支付超时问题、修正表单验证逻辑 |
| `docs`     | 文档更新（documentation）                               | 更新 README、补充 API 注释             |
| `style`    | 代码格式调整（不影响逻辑，如空格、缩进、分号）          | 统一代码缩进为 2 空格、移除多余空行    |
| `refactor` | 重构（既不新增功能也不修复 bug，如代码优化、结构调整）  | 拆分复杂函数、优化循环逻辑             |
| `test`     | 测试相关（添加/修改测试用例）                           | 新增单元测试、修复测试脚本             |
| `chore`    | 构建/工具链相关（不影响业务代码，如依赖更新、配置修改） | 升级 Webpack 版本、修改 ESLint 规则    |
| `perf`     | 性能优化（performance）                                 | 优化图片加载速度、减少数据库查询次数   |
| `ci`       | CI/CD 配置变更（如 GitHub Actions、Jenkins）            | 新增自动部署脚本、修改构建流程         |
| `build`    | 构建系统变更（如 Webpack、Rollup 配置）                 | 调整打包输出目录、新增代码压缩插件     |

2. **作用域（Scope）：可选，说明影响范围**

用**小写英文**，指定变更涉及的模块/组件/功能，增强可读性。例如：

- 前端项目：`auth`（认证模块）、`cart`（购物车）、`ui`（UI组件）
- 后端项目：`user`（用户服务）、`order`（订单服务）、`db`（数据库）

示例：`feat(auth): add social login`（新增社交登录功能，作用于 auth 模块）

3. **描述（Description）：必填，简洁说明变更**

- **用祈使句**（动词原形开头，如“add”“fix”“update”），首字母**小写**，结尾**不加句号**。
- 长度控制在 **50 字符以内**（便于快速浏览）。
- 避免模糊表述（如“update code”“fix bug”），需具体说明做了什么。

✅ 正确示例：`add user profile editing feature`

❌ 错误示例：`updated some code`（模糊）、`Fixed a problem`（不具体）

4. **正文（Body）：可选，详细说明变更**

- 解释**为什么改**（背景）、**改了什么**（细节）、**与之前的区别**（如有）。
- 用空行分隔，每行不超过 72 字符（避免换行混乱）。

示例：

```
feat(order): add order cancellation feature

- Allow users to cancel unpaid orders within 30 minutes
- Add cancellation reason dropdown (5 optional reasons)
- Send notification to admin when order is cancelled
```

5. **脚注（Footer）：可选，关联 Issue/破坏性变更**

- **关联 Issue**：用 `Fixes #123`（修复 Issue #123）、`Closes #456`（关闭 Issue #456）。
- **破坏性变更**：用 `BREAKING CHANGE:`开头，说明变更影响和迁移方案（需大写，后跟冒号）。

示例：

```
fix(api): correct timestamp format in response

BREAKING CHANGE: The `createdAt` field now returns ISO 8601 format (e.g., "2024-05-20T12:34:56Z") instead of Unix timestamp. Update client parsing logic accordingly.

Fixes #789
```

#### **三、完整示例**

1. 简单提交（仅类型和描述）

```
feat: add dark mode toggle
```

2. 带作用域的提交

```
fix(ui): resolve button click event conflict in modal
```

3. 完整提交（含正文和脚注）

```
refactor(user): split user service into auth and profile modules

The original monolithic user service caused tight coupling between authentication and profile management. This refactor separates concerns:
- `auth.service.js`: handles login, logout, token validation
- `profile.service.js`: handles profile CRUD, avatar upload

BREAKING CHANGE: Import paths changed from `import { userService } from '@/services'` to `import { authService, profileService } from '@/services/user'`.

Fixes #234, Closes #567
```

#### **四、避坑指南（常见错误）**

1. **避免模糊描述**：不用“update”“fix”“change”等单独动词，需具体（如“update user avatar upload limit”而非“update user”）。
2. **不用大写开头**：描述首字母小写（如“add”而非“Add”）。
3. **不用句号结尾**：描述结尾不加标点。
4. **不混合多类型**：一次提交只做一件事（如同时修复 bug 和新增功能，拆分为两个提交）。
5. **作用域不滥用**：非必要不使用作用域，避免过度细分（如小项目可省略作用域）。

#### **五、工具推荐（自动规范提交）**

1. **commitlint + husky**：提交前自动检查格式，不符合规范则阻止提交。 安装：`npm install @commitlint/cli @commitlint/config-conventional husky --save-dev` 配置：创建 `commitlint.config.js`继承 Conventional Commits 规范。
2. **Commitizen**：交互式生成提交信息，避免手动编写格式错误。 安装：`npm install commitizen cz-conventional-changelog --save-dev` 使用：运行 `npx git-cz`按提示填写信息。

#### **六、团队适配建议**

- 小型团队：直接使用 Conventional Commits 基础类型（feat/fix/docs/refactor/test/chore）。
- 大型项目：补充团队自定义类型（如 `i18n`国际化、`security`安全修复）。
- 文档同步：在 `CONTRIBUTING.md`中明确规范，新人入职时培训。

**总结**：规范的提交信息是“写给未来的自己和团队看的”，坚持用 **“类型(作用域): 描述”** 结构，配合工具约束，可大幅提升 Git 历史的可维护性。从现在开始，每次推送前花 30 秒规范提交信息，长期收益巨大！

## 📄 许可证

MIT