@hecom/codearts 0.1.0

package/.env.example

@@ -0,0 +1,20 @@
+# 华为云CodeArts API 环境变量配置
+# 复制此文件为 .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 API基础URL（可选，默认根据区域自动生成）
+CODEARTS_BASE_URL=https://projectman-ext.cn-north-4.myhuaweicloud.cn
+
+PROJECT_ID=your-project-id
+
+# 角色ID（支持多个，逗号分隔）
+ROLE_ID=your-role-id
+# 示例：ROLE_ID=1,2,3

package/README.md

@@ -0,0 +1,228 @@
+# @hecom/codearts
+
+基于华为云 CodeArts API 的工时统计分析工具。
+
+## 快速开始
+
+### 1. 初始化
+
+```bash
+npx @hecom/codearts
+```
+
+自动运行交互式配置向导，根据提示输入必要的配置项。配置文件将保存在 `~/.hecom-codearts/config.env`，配置一次后全局可用。
+
+### 2. 使用
+
+```bash
+# 查看帮助
+npx @hecom/codearts --help
+
+# 生成今日工时日报
+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 daily 2026-01-15 --project-id abc123 --role-id 1,2
+npx @hecom/codearts work-hour 2025 --role-id 1,2,3
+
+# 更新配置
+npx @hecom/codearts config
+```
+
+---
+
+## 本地开发与调试
+
+### 环境要求
+
+- Node.js >= 16.0.0
+- npm >= 7.0.0
+
+### 安装依赖
+
+```bash
+npm install
+```
+
+### 本地链接 CLI 工具
+
+```bash
+npm run build
+npm link
+codearts --help
+```
+
+### 开发调试
+
+```bash
+# 编译 TypeScript
+npm run build
+
+# 运行测试
+npm test
+```
+
+### 高级配置
+
+**配置优先级**：命令行参数 > 当前目录 .env > 全局配置 > 默认值
+
+#### 项目级配置
+
+在项目目录创建 `.env` 文件（优先级高于全局配置）：
+
+```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                # 项目配置
+```
+
+### 核心功能
+
+#### 日报统计 (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)
+
+- 支持中国法定节假日配置
+- 支持调休工作日配置
+- 支持大小周制度
+- 自动计算年度应计工作日
+- 判断指定日期是否为工作日
+
+---
+
+## License
+
+MIT

package/bin/codearts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+require('../dist/bin/cli.js');

package/dist/bin/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/bin/cli.js

@@ -0,0 +1,137 @@
+#!/usr/bin/env node
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        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 config_command_1 = require("../commands/config.command");
+const work_hour_command_1 = require("../commands/work-hour.command");
+const global_config_1 = require("../utils/global-config");
+// 读取 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 program = new commander_1.Command();
+program.name('codearts').description('华为云 CodeArts API 工时统计分析工具').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 地址');
+// config 命令 - 交互式配置向导
+program
+    .command('config')
+    .description('交互式配置向导\n\n引导用户创建或更新全局配置文件')
+    .action(async () => {
+    await (0, config_command_1.configCommand)();
+});
+// 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')
+    .action(async (date) => {
+    const opts = program.opts();
+    await (0, daily_command_1.dailyCommand)(date, opts);
+});
+// 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')
+    .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
+`);
+// 检查配置并自动执行 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) {
+            // 没有配置，自动执行 config 命令
+            console.log('未检测到配置文件，启动配置向导...\n');
+            await (0, config_command_1.configCommand)();
+            return;
+        }
+        // 有配置，显示帮助信息
+        program.help();
+    }
+    // 有参数，正常解析命令
+    program.parse();
+}
+checkConfigAndRun().catch((error) => {
+    console.error('执行失败:', error);
+    process.exit(1);
+});

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

@@ -0,0 +1,5 @@
+/**
+ * 交互式配置向导命令
+ * 引导用户创建或更新全局配置文件
+ */
+export declare function configCommand(): Promise<void>;

package/dist/commands/config.command.js

@@ -0,0 +1,109 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.configCommand = configCommand;
+const inquirer_1 = __importDefault(require("inquirer"));
+const global_config_1 = require("../utils/global-config");
+/**
+ * 交互式配置向导命令
+ * 引导用户创建或更新全局配置文件
+ */
+async function configCommand() {
+    console.log('\n欢迎使用 Hecom CodeArts 配置向导');
+    console.log('='.repeat(60));
+    console.log('此向导将帮助您配置华为云 CodeArts API 访问凭证。');
+    console.log(`配置将保存到: ${(0, global_config_1.getGlobalConfigPath)()}\n`);
+    const existingConfig = (0, global_config_1.globalConfigExists)() ? (0, global_config_1.readGlobalConfig)() : {};
+    if ((0, global_config_1.globalConfigExists)()) {
+        const { overwrite } = await inquirer_1.default.prompt([
+            {
+                type: 'confirm',
+                name: 'overwrite',
+                message: '检测到已存在全局配置，是否覆盖？',
+                default: false,
+            },
+        ]);
+        if (!overwrite) {
+            console.log('\n已取消配置。');
+            return;
+        }
+    }
+    const answers = await inquirer_1.default.prompt([
+        {
+            type: 'input',
+            name: 'iamEndpoint',
+            message: 'IAM 认证端点:',
+            default: existingConfig.HUAWEI_CLOUD_IAM_ENDPOINT || 'https://iam.cn-north-4.myhuaweicloud.com',
+        },
+        {
+            type: 'input',
+            name: 'region',
+            message: '华为云区域:',
+            default: existingConfig.HUAWEI_CLOUD_REGION || 'cn-north-4',
+        },
+        {
+            type: 'input',
+            name: 'username',
+            message: 'IAM 用户名:',
+            default: existingConfig.HUAWEI_CLOUD_USERNAME || '',
+            validate: (input) => (input.trim() ? true : 'IAM 用户名不能为空'),
+        },
+        {
+            type: 'password',
+            name: 'password',
+            message: 'IAM 密码:',
+            mask: '*',
+            default: existingConfig.HUAWEI_CLOUD_PASSWORD || '',
+            validate: (input) => (input.trim() ? true : 'IAM 密码不能为空'),
+        },
+        {
+            type: 'input',
+            name: 'domain',
+            message: '华为云账号名:',
+            default: existingConfig.HUAWEI_CLOUD_DOMAIN || '',
+            validate: (input) => (input.trim() ? true : '华为云账号名不能为空'),
+        },
+        {
+            type: 'input',
+            name: 'codeartsUrl',
+            message: 'CodeArts API 地址:',
+            default: existingConfig.CODEARTS_BASE_URL || 'https://projectman-ext.cn-north-4.myhuaweicloud.cn',
+        },
+        {
+            type: 'input',
+            name: 'projectId',
+            message: '项目 ID:',
+            default: existingConfig.PROJECT_ID || '',
+            validate: (input) => (input.trim() ? true : '项目 ID 不能为空'),
+        },
+        {
+            type: 'input',
+            name: 'roleId',
+            message: '角色 ID（支持逗号分隔，如: 1,2,3）:',
+            default: existingConfig.ROLE_ID || '',
+            validate: (input) => {
+                if (!input.trim()) {
+                    return '角色 ID 不能为空';
+                }
+                const ids = input.split(',').map((id) => id.trim());
+                const allValid = ids.every((id) => /^\d+$/.test(id));
+                return allValid ? true : '角色 ID 必须是数字或逗号分隔的数字列表';
+            },
+        },
+    ]);
+    try {
+        (0, global_config_1.writeGlobalConfig)(answers);
+        console.log('\n✅ 全局配置已成功保存');
+        console.log(`配置文件位置: ${(0, global_config_1.getGlobalConfigPath)()}`);
+        console.log('\n您现在可以在任何目录使用以下命令：');
+        console.log('  codearts daily              # 生成日报');
+        console.log('  codearts work-hour          # 生成年度工时统计');
+        console.log('\n提示：配置文件包含敏感信息，请妥善保管。');
+    }
+    catch (error) {
+        console.error('\n❌ 保存配置文件失败:', error);
+        process.exit(1);
+    }
+}

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

@@ -0,0 +1,10 @@
+import { BusinessService } from '../services/business.service';
+import { CliOptions } from '../utils/config-loader';
+/**
+ * 生成单个角色的日报
+ */
+export declare function generateDailyReport(businessService: BusinessService, projectId: string, roleId: number, targetDate: string): Promise<void>;
+/**
+ * daily 命令入口
+ */
+export declare function dailyCommand(date?: string, cliOptions?: CliOptions): Promise<void>;