npm package: @liuyiqqmail/yx-tools
Description: 云效（Alibaba Cloud DevOps）信息获取 CLI 工具，交互式生成迭代/需求/缺陷 Excel 报告
Latest version: 1.2.1

# yx-tools

云效（Alibaba Cloud DevOps）信息获取工具 — Node.js CLI 重实现。

交互式命令行工具，从云效平台拉取迭代、需求、缺陷等数据，一键生成 Excel 报告。

## 功能


| 报告类型         | 输出文件名               | 说明                    |
| ------------ | ------------------- | --------------------- |
| Sprint 开发报告  | `{迭代名}_d.xlsx`      | 按开发人员汇总工时与工作量         |
| Sprint 需求报告  | `{迭代名}_r.xlsx`      | 按需求列出预估/实际工时及偏差公式     |
| 需求池状态报告      | `需求情况表_{日期}.xlsx`   | 统计澄清/设计需求池变化量         |
| BUG 清单报告     | `{迭代名}_bug.xlsx`    | 缺陷开启次数、发布/完成时间等       |
| 需求跟踪报告       | `{迭代名}_sys.xlsx`    | 带标签需求的全生命周期跟踪         |
| Sprint 工作项报告 | `{迭代名}_Sprint.xlsx` | 迭代内所有 Bug/Task/Req 汇总 |


## 环境要求

- Node.js >= 20
- 阿里云 AccessKey（需有云效 DevOps 只读权限）

## 安装

```bash
npm install -g @liuyiqqmail/yx-tools
```

## 首次使用

直接运行，工具会自动引导配置（**只需设置一次**）：

```bash
yx-tools
```

```
首次使用，请配置阿里云 AccessKey（仅需设置一次，保存在本机 ~/.yx-tools/config.json）

获取 AccessKey：https://ram.console.aliyun.com/manage/ak

? AccessKey ID：  LTAI5t...
? AccessKey Secret：  ********
? 组织 ID（直接回车使用默认值）：  ↵

配置已保存至 C:\Users\xxx\.yx-tools\config.json

云效信息获取 — Node.js CLI

? 选择项目：  ›  新一代MBM平台
...
```

配置信息保存在本机 `~/.yx-tools/config.json`，后续运行直接进入主流程，无需重复填写。

## 使用

```bash
yx-tools
```

启动后按提示交互操作：

```
云效信息获取 — Node.js CLI

? 选择项目：  ›  新一代MBM平台
? 选择迭代：  ›  26-4SP1-一组
? 选择报告类型：  ›  Sprint 需求报告 (_r)

⏳ 正在获取数据，请稍候...

✅ 报告已生成：output\26-4SP1-一组_r.xlsx
```

生成的 Excel 文件保存在当前目录的 `output/` 文件夹，并自动用系统默认程序打开。

## Web 模式

除 Excel 输出外，还可以启动 Web 服务器，在浏览器中查看交互式报告。

```bash
yx-tools --web              # 默认 3000 端口
yx-tools --web --port=8080  # 自定义端口
```

启动后浏览器访问 `http://localhost:3000`，即可查看全部 6 种报告。

**功能特性：**

- 交互式表格展示（AG Grid），支持排序、筛选、搜索、分页
- 浏览器内一键导出 Excel
- 多报告类型切换（Sprint 开发报告、需求报告、BUG 清单、需求跟踪、工作项报告、需求池状态报告）
- 可选 Basic Auth 认证

**环境变量（可选）：**

| 变量 | 说明 |
|------|------|
| `WEB_USER` | Basic Auth 用户名 |
| `WEB_PASS` | Basic Auth 密码 |

两个变量同时设置时启用认证。

## 重置配置

如需更换 AccessKey，运行：

```bash
yx-tools --reset-config
```

## 目录结构

```
yx-tools/
├── src/
│   ├── index.js          # CLI 入口
│   ├── api/
│   │   └── yunxiaoAPI.js # 云效 SDK 封装（含分页、缓存）
│   ├── models/
│   │   ├── TeamInfo.js   # 团队成员管理
│   │   ├── ReqInfo.js    # 需求数据模型
│   │   └── BugInfo.js    # 缺陷数据模型
│   ├── reports/
│   │   ├── exportExecute.js  # Sprint 开发报告
│   │   ├── getSprintReg.js   # Sprint 需求报告
│   │   ├── getRegInfo.js     # 需求池状态报告
│   │   ├── bugSys.js         # BUG 清单报告
│   │   ├── reqSys.js         # 需求跟踪报告
│   │   └── mbmBugSys.js      # Sprint 工作项报告
│   ├── web/
│   │   ├── server.js         # Express Web 服务器
│   │   ├── reportRegistry.js # 报告元数据注册表
│   │   ├── routes/
│   │   │   └── api.js        # API 路由
│   │   └── public/
│   │       ├── index.html    # 前端页面
│   │       ├── app.js        # 前端逻辑
│   │       └── style.css     # 样式
│   └── utils/
│       ├── config.js         # 用户配置管理（首次引导 + 持久化）
│       ├── excelHelper.js    # Excel 导出工具
│       └── dateUtils.js      # 日期格式化工具
├── output/               # 生成的 Excel 文件（gitignored）
├── .env.example          # 环境变量参考（源码运行时使用）
└── start.cmd             # Windows 一键启动
```

## 依赖


| 包                          | 用途            |
| -------------------------- | ------------- |
| `@alicloud/devops20210625` | 云效 DevOps SDK |
| `exceljs`                  | Excel 文件生成    |
| `@inquirer/prompts`        | 交互式 CLI 菜单    |
| `express`                  | Web 服务器（--web 模式） |
| `dotenv`                   | 环境变量加载（源码模式）  |