@hecom/codearts 0.1.0 → 0.2.1

package/README.md

@@ -1,6 +1,6 @@
 # @hecom/codearts
 
-基于华为云 CodeArts API 的工时统计分析工具。
+基于华为云 CodeArts API 的统计分析工具。
 
 ## 快速开始
 
@@ -24,16 +24,19 @@ npx @hecom/codearts daily
 # 生成当年工时统计
 npx @hecom/codearts work-hour
 
-# 生成指定日期/年份的统计
-npx @hecom/codearts daily 2026-01-15
-npx @hecom/codearts work-hour 2025
+# 更新全局配置
+npx @hecom/codearts config
+
+# 单独更新角色配置
+npx @hecom/codearts config role-id
+```
 
-# 使用命令行参数覆盖配置
-npx @hecom/codearts daily 2026-01-15 --project-id abc123 --role-id 1,2
-npx @hecom/codearts work-hour 2025 --role-id 1,2,3
+### 3. 升级
+
+```bash
+# 更新最新版本
+npx @hecom/codearts@latest
 
-# 更新配置
-npx @hecom/codearts config
 ```
 
 ---
@@ -42,7 +45,7 @@ npx @hecom/codearts config
 
 ### 环境要求
 
-- Node.js >= 16.0.0
+- Node.js >= 23.0.0
 - npm >= 7.0.0
 
 ### 安装依赖
@@ -51,175 +54,37 @@ npx @hecom/codearts config
 npm install
 ```
 
-### 本地链接 CLI 工具
+### 本地运行
 
 ```bash
-npm run build
-npm link
-codearts --help
-```
+# 运行命令
+npm run dev
 
-### 开发调试
-
-```bash
-# 编译 TypeScript
-npm run build
+npm run dev daily
 
-# 运行测试
-npm test
+npm run dev work-hour
 ```
 
-### 高级配置
-
-**配置优先级**：命令行参数 > 当前目录 .env > 全局配置 > 默认值
-
-#### 项目级配置
-
-在项目目录创建 `.env` 文件（优先级高于全局配置）：
+### 本地链接 CLI 工具
 
 ```bash
-cp .env.example .env
-```
-
-修改 `.env` 文件中的配置：
-
-```env
-# 华为云IAM认证端点（根据区域调整）
-HUAWEI_CLOUD_IAM_ENDPOINT=https://iam.cn-north-4.myhuaweicloud.com
-HUAWEI_CLOUD_REGION=cn-north-4
-
-# IAM用户凭证
-HUAWEI_CLOUD_USERNAME=your-iam-username
-HUAWEI_CLOUD_PASSWORD=your-iam-password
-HUAWEI_CLOUD_DOMAIN=your-domain-name
-
-# 项目配置
-CODEARTS_BASE_URL=https://projectman-ext.cn-north-4.myhuaweicloud.cn
-PROJECT_ID=your-project-id
-ROLE_ID=1,2,3  # 支持逗号分隔的多个角色ID
-```
-
-**适用场景**: 团队协作，不同项目使用不同配置
-
-#### 环境变量说明
-
-| 变量名                      | 说明                               | 必填 | 默认值                                               |
-| --------------------------- | ---------------------------------- | ---- | ---------------------------------------------------- |
-| `HUAWEI_CLOUD_IAM_ENDPOINT` | IAM 认证端点                       | 否   | `https://iam.cn-north-4.myhuaweicloud.com`           |
-| `HUAWEI_CLOUD_REGION`       | 华为云区域                         | 否   | `cn-north-4`                                         |
-| `HUAWEI_CLOUD_USERNAME`     | IAM 用户名                         | 是   | -                                                    |
-| `HUAWEI_CLOUD_PASSWORD`     | IAM 密码                           | 是   | -                                                    |
-| `HUAWEI_CLOUD_DOMAIN`       | 华为云账号名                       | 是   | -                                                    |
-| `CODEARTS_BASE_URL`         | CodeArts API 地址                  | 否   | `https://projectman-ext.cn-north-4.myhuaweicloud.cn` |
-| `PROJECT_ID`                | 项目 ID                            | 是   | -                                                    |
-| `ROLE_ID`                   | 角色 ID（支持逗号分隔，如: 1,2,3） | 是   | -                                                    |
-| `TARGET_DATE`               | 目标日期（YYYY-MM-DD）             | 否   | 当天日期                                             |
-
----
-
-## 项目信息
-
-### 项目描述
-
-这是一个使用 TypeScript/Node.js 构建的工时统计分析项目，通过华为云 CodeArts API 获取 issue、人员、工时等数据，并生成日报和年度工时统计报表。
-
-### 技术栈
-
-- **语言**: TypeScript
-- **运行环境**: Node.js
-- **HTTP客户端**: Axios
-- **测试框架**: Jest
-
-### 项目结构
-
-```
-@hecom/codearts/
-├── src/
-│   ├── bin/                    # CLI 入口
-│   │   └── cli.ts              # Commander.js CLI 定义
-│   ├── commands/               # 命令实现
-│   │   ├── config.command.ts   # 配置命令逻辑
-│   │   ├── daily.command.ts    # 日报命令逻辑
-│   │   ├── work-hour.command.ts# 工时统计命令逻辑
-│   │   └── index.ts            # 命令导出
-│   ├── services/               # API服务类
-│   │   ├── api.service.ts      # 华为云基础 API 封装
-│   │   └── business.service.ts # 业务场景 API 封装
-│   ├── utils/                  # 工具函数
-│   │   ├── global-config.ts    # 全局配置查找
-│   │   └── config-loader.ts    # 配置加载器（CLI参数 > 环境变量）
-│   ├── config/                 # 配置文件
-│   │   └── holidays.ts         # 节假日配置与工作日计算
-│   ├── types/                  # TypeScript 类型定义
-│   │   └── index.ts            # API 契约与数据结构定义
-│   └── index.ts                # 模块导出
-├── bin/
-│   └── codearts                # CLI 可执行文件
-├── __tests__/                  # 测试文件
-├── dist/                       # 编译输出目录
-├── .env                        # 环境变量配置
-├── .env.example                # 环境变量配置模板
-├── tsconfig.json               # TypeScript配置
-├── jest.config.js              # Jest测试配置
-└── package.json                # 项目配置
+npm run build
+npm link
+codearts --help
 ```
 
-### 核心功能
-
-#### 日报统计 (daily)
-
-生成指定日期的工时日报，包括：
-
-- 按人员统计当日工时
-- 统计 Bug 修复工时（自动合并同一 Bug 的多人工时）
-- 统计活跃的工作项数量
-- 计算工时完成率（基于角色成员数）
-- 生成可读的日报格式输出
-
-#### 年度工时统计 (work-hour)
-
-生成指定年份的工时统计报表，包括：
-
-- 计算年度应计工作日（自动排除法定节假日和周末）
-- 统计实际工时与应计工时的完成率
-- 按人员生成工时明细表
-- 按领域类型（需求、缺陷、任务等）统计工时分布
-- 支持多角色统计（按角色分组，显示小计和总计）
-- 生成 Markdown 格式的统计表格
-
-### API服务层
-
-#### ApiService (api.service.ts)
-
-华为云 CodeArts 基础 API 封装：
-
-- IAM Token 认证管理（自动获取和缓存）
-- 项目管理 API（项目列表、成员查询）
-- 迭代管理 API（迭代列表、迭代详情）
-- 工作项 API（Issue 列表、详情、创建、更新）
-- 工时管理 API（工时查询、提交）
-- 请求日志（可选的 curl 风格日志输出）
-- 完善的错误处理
-
-#### BusinessService (business.service.ts)
-
-面向业务场景的高级 API 封装：
-
-- `getMembersByRoleId()`: 通过角色获取人员列表
-- `getActiveIterationsOnDate()`: 查询指定日期的活跃迭代
-- `getWorkloadByIterationsAndUsers()`: 批量查询工作量
-- `getAllIssuesByIteration()`: 查询迭代内所有 Issue（自动分页）
-- `getDailyWorkHourStats()`: 获取日报工时统计
-- `getAllWorkHourStats()`: 获取年度工时统计
-- `addIssueNote()`: 添加工作项备注
-
-### 节假日配置 (config/holidays.ts)
-
-- 支持中国法定节假日配置
-- 支持调休工作日配置
-- 支持大小周制度
-- 自动计算年度应计工作日
-- 判断指定日期是否为工作日
+### 配置项
+
+| 配置项                      | 说明                               | 必填 |
+| --------------------------- | ---------------------------------- | ---- |
+| `HUAWEI_CLOUD_IAM_ENDPOINT` | IAM 认证端点                       | 是   |
+| `HUAWEI_CLOUD_REGION`       | 华为云区域                         | 是   |
+| `HUAWEI_CLOUD_USERNAME`     | IAM 用户名                         | 是   |
+| `HUAWEI_CLOUD_PASSWORD`     | IAM 密码                           | 是   |
+| `HUAWEI_CLOUD_DOMAIN`       | 华为云账号名                       | 是   |
+| `CODEARTS_BASE_URL`         | CodeArts API 地址                  | 是   |
+| `PROJECT_ID`                | 项目 ID                            | 是   |
+| `ROLE_ID`                   | 角色 ID（支持逗号分隔，如: 1,2,3） | 是   |
 
 ---
 

package/dist/bin/cli.js

@@ -33,45 +33,52 @@ var __importStar = (this && this.__importStar) || (function () {
         return result;
     };
 })();
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
 Object.defineProperty(exports, "__esModule", { value: true });
 const commander_1 = require("commander");
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
-const dotenv_1 = __importDefault(require("dotenv"));
-const daily_command_1 = require("../commands/daily.command");
+const bug_command_1 = require("../commands/bug.command");
 const config_command_1 = require("../commands/config.command");
+const daily_command_1 = require("../commands/daily.command");
 const work_hour_command_1 = require("../commands/work-hour.command");
-const global_config_1 = require("../utils/global-config");
+const config_loader_1 = require("../utils/config-loader");
 // 读取 package.json 中的版本号
 const packageJsonPath = path.join(__dirname, '../../package.json');
 const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf-8'));
-const version = packageJson.version || '0.0.1';
+const version = packageJson.version;
 const program = new commander_1.Command();
-program.name('codearts').description('华为云 CodeArts API 工时统计分析工具').version(version);
+program.name('codearts').description('华为云 CodeArts 统计分析工具').version(version);
 // 全局选项（环境变量覆盖）
-program
-    .option('--project-id <id>', '项目 ID')
-    .option('--role-id <ids>', '角色 ID（支持逗号分隔，如: 1,2,3）')
-    .option('--username <username>', 'IAM 用户名')
-    .option('--password <password>', 'IAM 密码（建议使用 .env 文件）')
-    .option('--domain <domain>', '华为云账号名')
-    .option('--region <region>', '华为云区域')
-    .option('--iam-endpoint <url>', 'IAM 认证端点')
-    .option('--codearts-url <url>', 'CodeArts API 地址');
+program.option('--role-id <ids>', '角色 ID（支持逗号分隔，如: 1,2,3），优先级高于环境变量 ROLE_ID');
 // config 命令 - 交互式配置向导
-program
+const configCmd = program
     .command('config')
-    .description('交互式配置向导\n\n引导用户创建或更新全局配置文件')
+    .description('交互式配置向导，引导用户创建或更新全局配置文件\n\n')
     .action(async () => {
     await (0, config_command_1.configCommand)();
 });
+// config show 子命令 - 显示当前配置
+configCmd
+    .command('show')
+    .description('显示当前配置信息')
+    .action(async () => {
+    await (0, config_command_1.showConfigCommand)();
+});
+// 为每个项目配置项添加子命令
+const availableConfigs = (0, config_command_1.getAvailableProjectConfigs)();
+availableConfigs.forEach((configItem) => {
+    const subCommandName = configItem.key.toLowerCase().replace(/_/g, '-');
+    configCmd
+        .command(subCommandName)
+        .description(`更新${configItem.label}`)
+        .action(async () => {
+        await (0, config_command_1.updateProjectConfigCommand)(configItem.key);
+    });
+});
 // daily 命令
 program
     .command('daily [date]')
-    .description('生成日报统计\n\n示例:\n  $ codearts daily\n  $ codearts daily 2026-01-15\n  $ codearts daily --project-id abc123 --role-id 1,2')
+    .description('生成日报统计')
     .action(async (date) => {
     const opts = program.opts();
     await (0, daily_command_1.dailyCommand)(date, opts);
@@ -79,47 +86,27 @@ program
 // work-hour 命令
 program
     .command('work-hour [year]')
-    .description('生成年度工时统计\n\n示例:\n  $ codearts work-hour\n  $ codearts work-hour 2025\n  $ codearts work-hour 2025 --role-id 1,2,3')
+    .description('生成年度工时统计')
     .action(async (year) => {
     const opts = program.opts();
     await (0, work_hour_command_1.workHourCommand)(year, opts);
 });
-// 添加帮助信息
-program.addHelpText('after', `
-环境变量:
-  命令行参数优先于环境变量。可通过 .env 文件配置以下变量:
-
-  HUAWEI_CLOUD_IAM_ENDPOINT   IAM 认证端点
-  HUAWEI_CLOUD_REGION         华为云区域
-  HUAWEI_CLOUD_USERNAME       IAM 用户名
-  HUAWEI_CLOUD_PASSWORD       IAM 密码
-  HUAWEI_CLOUD_DOMAIN         华为云账号名
-  CODEARTS_BASE_URL           CodeArts API 地址
-  PROJECT_ID                  项目 ID
-  ROLE_ID                     角色 ID（支持逗号分隔）
-
-配置优先级:
-  命令行参数 > 环境变量 > 默认值
-
-快速开始:
-  1. 运行配置向导: codearts config
-  2. 生成日报: codearts daily
-  3. 生成年度工时统计: codearts work-hour
-
-更多信息:
-  https://github.com/hecom-rn/hecom-codearts
-`);
+// bug-rate 命令
+program
+    .command('bug-rate <iterations>')
+    .description('按迭代统计产品缺陷率，支持多个迭代（逗号分隔）')
+    .action(async (iterations) => {
+    const opts = program.opts();
+    await (0, bug_command_1.bugCommand)(iterations, opts);
+});
 // 检查配置并自动执行 config 命令
 async function checkConfigAndRun() {
     const args = process.argv.slice(2);
     // 如果没有参数（直接执行 codearts），检测配置
     if (args.length === 0) {
-        // 加载当前目录 .env 文件
-        dotenv_1.default.config();
-        // 检查是否有配置（全局配置或环境变量）
-        const hasGlobalConfig = (0, global_config_1.globalConfigExists)();
-        const hasEnvConfig = process.env.PROJECT_ID && process.env.ROLE_ID;
-        if (!hasGlobalConfig && !hasEnvConfig) {
+        // 检查是否有全局配置
+        const hasGlobalConfig = (0, config_loader_1.globalConfigExists)();
+        if (!hasGlobalConfig) {
             // 没有配置，自动执行 config 命令
             console.log('未检测到配置文件，启动配置向导...\n');
             await (0, config_command_1.configCommand)();

package/dist/commands/bug.command.d.ts

@@ -0,0 +1,7 @@
+import { CliOptions } from '../utils/config-loader';
+/**
+ * bug 命令入口
+ * @param iterationTitlesStr 迭代标题（支持逗号、分号、空格、竖线、顿号等分隔符）
+ * @param cliOptions CLI 选项
+ */
+export declare function bugCommand(iterationTitlesStr: string, cliOptions?: CliOptions): Promise<void>;

package/dist/commands/bug.command.js

@@ -0,0 +1,158 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.bugCommand = bugCommand;
+const business_service_1 = require("../services/business.service");
+const types_1 = require("../types");
+const config_loader_1 = require("../utils/config-loader");
+/**
+ * 判断 Bug 是否属于需求变更或产品设计问题
+ * @param bug Bug 工作项
+ * @returns 是否属于需求变更或产品设计问题
+ */
+function isRequirementOrDesignBug(bug) {
+    // 检查 customValueNew（v2 版本的自定义字段，是对象格式）
+    const defectAnalysisValue = bug.customValueNew?.custom_field32;
+    if (defectAnalysisValue) {
+        return (defectAnalysisValue === types_1.DefectAnalysisType.REQUIREMENT_CHANGE ||
+            defectAnalysisValue === types_1.DefectAnalysisType.PRODUCT_DESIGN);
+    }
+    return false;
+}
+/**
+ * 生成 Bug 统计报告
+ */
+async function generateBugReport(businessService, projectId, roleIds, iterationTitles) {
+    console.log(`\n正在统计迭代中的 Bug 数据...`);
+    console.log(`目标迭代: ${iterationTitles.join(', ')}`);
+    console.log(`角色过滤: ${roleIds.length > 0 ? roleIds.join(', ') : '无（保留所有人）'}`);
+    console.log(`统计规则: 统计所有 Bug，同时标记"需求变更问题"和"产品设计问题"`);
+    // Step 1: 获取指定角色的成员列表（如果启用了角色过滤）
+    const targetMemberIds = new Set();
+    if (roleIds.length > 0) {
+        for (const roleId of roleIds) {
+            const members = await businessService.getMembersByRoleId(projectId, roleId);
+            members.forEach((member) => targetMemberIds.add(member.user_num_id));
+        }
+        console.log(`\n目标角色成员数: ${targetMemberIds.size} 人`);
+    }
+    else {
+        console.log(`\n角色过滤: 已禁用，将统计所有人`);
+    }
+    // Step 2: 获取所有 Story
+    const stories = await businessService.getStoriesByIterationTitles(projectId, iterationTitles);
+    if (stories.length === 0) {
+        console.log('未找到任何 Story');
+        return;
+    }
+    // Step 3: 过滤出目标角色成员处理的 Story（如果启用了角色过滤）
+    const filteredStories = roleIds.length > 0
+        ? stories.filter((story) => {
+            const assignedUserId = story.assigned_user?.id;
+            return assignedUserId && targetMemberIds.has(assignedUserId);
+        })
+        : stories;
+    if (filteredStories.length === 0) {
+        console.log(roleIds.length > 0 ? '未找到目标角色成员处理的 Story' : '未找到任何 Story');
+        return;
+    }
+    if (roleIds.length > 0) {
+        console.log(`\n找到 ${stories.length} 个 Story，其中 ${filteredStories.length} 个由目标角色成员处理，正在统计 Bug...`);
+    }
+    else {
+        console.log(`\n找到 ${filteredStories.length} 个 Story，正在统计 Bug...`);
+    }
+    // Step 4: 获取每个 Story 的子工作项（Bug）
+    const bugStatsMap = new Map();
+    for (const story of filteredStories) {
+        const childIssues = await businessService.getChildIssues(projectId, String(story.id));
+        // 过滤出所有 Bug 类型的子工作项（tracker_id = 3）
+        const allBugs = childIssues.filter((issue) => issue.tracker.id === 3);
+        if (allBugs.length === 0) {
+            continue;
+        }
+        // 统计产品问题 Bug（需求变更 + 产品设计）
+        const productBugs = allBugs.filter((bug) => isRequirementOrDesignBug(bug));
+        // Step 3: 按 Story 的处理人统计 Bug
+        const assignedUserId = story.assigned_user?.id;
+        const assignedUserName = story.assigned_user?.nick_name;
+        if (!assignedUserId) {
+            continue;
+        }
+        if (!bugStatsMap.has(assignedUserId)) {
+            bugStatsMap.set(assignedUserId, {
+                assignedUser: assignedUserName,
+                userId: assignedUserId,
+                totalBugCount: 0,
+                productBugCount: 0,
+                productDefectRate: 0,
+                stories: [],
+            });
+        }
+        const userStats = bugStatsMap.get(assignedUserId);
+        userStats.totalBugCount += allBugs.length;
+        userStats.productBugCount += productBugs.length;
+        userStats.stories.push({
+            storyName: story.name,
+            storyId: story.id,
+            totalBugCount: allBugs.length,
+            productBugCount: productBugs.length,
+        });
+    }
+    // 计算每个人的产品缺陷率
+    bugStatsMap.forEach((stats) => {
+        stats.productDefectRate =
+            stats.totalBugCount > 0 ? (stats.productBugCount / stats.totalBugCount) * 100 : 0;
+    });
+    // Step 4: 输出统计结果
+    console.log('\n');
+    console.log('='.repeat(80));
+    console.log(`Bug 统计报告 [${iterationTitles.join(', ')}]`);
+    console.log('='.repeat(80));
+    console.log('');
+    if (bugStatsMap.size === 0) {
+        console.log('未找到任何 Bug');
+        return;
+    }
+    // 按总 Bug 数量降序排列
+    const sortedStats = Array.from(bugStatsMap.values()).sort((a, b) => b.totalBugCount - a.totalBugCount);
+    let totalBugs = 0;
+    let totalProductBugs = 0;
+    sortedStats.forEach((stats) => {
+        console.log(`\x1b[31m${stats.assignedUser}: 总 Bug ${stats.totalBugCount} 个 | 产品问题 ${stats.productBugCount} 个 | 产品缺陷率 ${stats.productDefectRate.toFixed(1)}%\x1b[0m`);
+        // 输出该用户的 Story 及其 Bug 数量
+        stats.stories.forEach((story) => {
+            console.log(`  - ${story.storyName} (总 ${story.totalBugCount} 个 Bug，其中产品问题 ${story.productBugCount} 个)`);
+        });
+        totalBugs += stats.totalBugCount;
+        totalProductBugs += stats.productBugCount;
+        console.log('');
+    });
+    const overallProductDefectRate = totalBugs > 0 ? (totalProductBugs / totalBugs) * 100 : 0;
+    console.log('='.repeat(80));
+    console.log(`总计: ${totalBugs} 个 Bug（产品问题 ${totalProductBugs} 个，产品缺陷率 ${overallProductDefectRate.toFixed(1)}%），涉及 ${sortedStats.length} 位处理人`);
+    console.log('='.repeat(80));
+}
+/**
+ * bug 命令入口
+ * @param iterationTitlesStr 迭代标题（支持逗号、分号、空格、竖线、顿号等分隔符）
+ * @param cliOptions CLI 选项
+ */
+async function bugCommand(iterationTitlesStr, cliOptions = {}) {
+    try {
+        if (!iterationTitlesStr || iterationTitlesStr.trim() === '') {
+            throw new Error('请指定至少一个迭代标题');
+        }
+        // 解析迭代标题（支持多种分隔符：逗号、分号、空格、竖线、顿号等）
+        const iterationTitles = iterationTitlesStr
+            .split(/[,，;；|\s、]+/)
+            .map((title) => title.trim())
+            .filter((title) => title.length > 0);
+        const { projectId, roleIds, config } = (0, config_loader_1.loadConfig)(cliOptions);
+        const businessService = new business_service_1.BusinessService(config);
+        await generateBugReport(businessService, projectId, roleIds, iterationTitles);
+    }
+    catch (error) {
+        console.error('执行过程中发生错误:', error);
+        process.exit(1);
+    }
+}

package/dist/commands/config.command.d.ts

@@ -1,5 +1,30 @@
+import { BusinessService } from '../services/business.service';
+import { ConfigKey } from '../types';
+/**
+ * 第三阶段项目配置的配置项定义
+ */
+interface ProjectConfigItem {
+    key: ConfigKey;
+    label: string;
+    configure: (businessService: BusinessService, projectId: string, existingValue?: string) => Promise<string>;
+}
 /**
  * 交互式配置向导命令
  * 引导用户创建或更新全局配置文件
  */
 export declare function configCommand(): Promise<void>;
+/**
+ * 单独更新某个项目配置项
+ * @param configKey 配置项的键名（例如 ConfigKey.ROLE_ID）
+ */
+export declare function updateProjectConfigCommand(configKey: ConfigKey): Promise<void>;
+/**
+ * 获取所有可用的项目配置项
+ */
+export declare function getAvailableProjectConfigs(): ProjectConfigItem[];
+/**
+ * 显示当前配置
+ *
+ */
+export declare function showConfigCommand(): Promise<void>;
+export {};