OA工时填报Skill,打通gitlab与禅道，实现每日工时自动提交

OA工时填报Skill,打通gitlab与禅道，实现每日工时自动提交

概述

本文档介绍如何使用 oa-timesheet 技能自动填报OA工时，支持从 GitLab代码提交 和 禅道工作记录 自动生成工作描述。

---

一、填报流程概览

flowchart LR A[开始] --> B{选择数据来源} B -->|GitLab提交| C[自动获取代码提交记录] B -->|禅道记录| D[QoderWork浏览器连接器
自动获取Bug/需求/任务] C --> E[自动生成工作描述] D --> E E --> F[预览填报信息] F --> G{用户确认} G -->|确认| H[自动填报OA] G -->|修改| I[调整内容] I --> F H --> J[完成]

---

二、数据来源说明

2.1 方式一：GitLab代码提交（推荐）

系统自动从GitLab获取当天的代码提交记录，智能生成工作描述。

适用场景：

• 当天有代码提交
• 希望自动生成工作描述

生成的描述示例：

代码审查3次，解决抵押变更调档选择580个单位报错问题，完成合同信息栏优化

自动识别的提交类型：

提交前缀	识别为	示例
fix: / bug	问题修复	fix: 解决调档报错
feat: / feature	新功能	feat: 添加一键登簿
Merge branch	代码审查	Merge branch 'feature/xxx'
docs:	文档更新	docs: 更新API文档

2.2 方式二：禅道工作记录（QoderWork浏览器连接器）

通过 QoderWork浏览器连接器 自动访问禅道系统，获取指派给你的Bug、需求、任务记录，自动生成工作描述。

工作原理：

1. QoderWork自动打开浏览器，访问禅道 http://sc.supermap.com:9909
2. 登录并进入「我的动态」页面
3. 筛选今日动态，获取解决的Bug、关闭的任务、关联的需求
4. 自动整理生成工作描述

适用场景：

• 当天无代码提交（如开会、测试、文档工作）
• 需要补充GitLab未覆盖的工作内容
• 希望自动获取禅道工作记录

自动获取的内容：

动态类型	获取内容	示例
解决Bug	Bug ID + 标题	Bug#44576 抵押变更调档报错
关闭任务	任务ID + 标题	任务#148169 抵押注销问题修复
关联需求	需求ID + 标题	Story#91973 合同信息栏优化
创建任务	任务ID + 标题	任务#149585 合同信息栏开发

生成的描述示例：

Bug修复：解决抵押变更调档选择580个单位报错问题（Bug#44576）；
解决一并办理权利信息保存不上问题（Bug#44515）。
任务处理：关闭相关开发任务3个。
需求开发：关联并处理合同信息栏优化需求（Story#91973）。

2.3 方式三：历史记录继承

系统自动继承前一天的填报配置（项目、工时类型、子类等），只需修改工作描述。

适用场景：

• 连续在同一项目工作
• 快速填报，减少重复选择

---

三、使用步骤

步骤1：准备工作

确保 oa-timesheet 技能已配置：

// config.js 配置示例
module.exports = {
  oa: {
    username: 'your_username',    // OA账号
    password: 'your_password',    // OA密码
    staffCode: 'your_staffcode'   // 工号
  },
  gitlab: {
    baseUrl: 'http://sc.supermap.com',
    privateToken: 'your_gitlab_token'  // GitLab访问令牌
  },
  defaults: {
    hourType: '1',               // 应用项目类工时
    projectId: 'RJ-H-2024-2312', // 默认项目
    hourChildType: '19791',      // 编码与测试
    workSheet: '8'               // 8小时
  }
};

步骤2：调用技能

方式A：GitLab自动获取（推荐）

const { getPreview, submit } = require('oa-timesheet');

// 自动从GitLab获取提交记录
const preview = await getPreview('2026-03-17', '8');

console.log(preview.display.workDescription);
// 输出: "代码审查3次，解决抵押变更调档问题，完成合同信息栏优化"

// 确认后提交
const result = await submit(preview.formData);

方式B：禅道记录（QoderWork浏览器连接器）

// 使用QoderWork浏览器连接器自动获取禅道记录
// 1. QoderWork自动访问禅道 http://sc.supermap.com:9909/my-dynamic.html
// 2. 获取今日动态：解决的Bug、关闭的任务、关联的需求
// 3. 自动生成工作描述

const workDescription = await getZentaoWorkDescription('2026-03-17');
// 输出: "Bug修复：解决抵押变更调档选择580个单位报错问题（Bug#44576）；
//        解决一并办理房屋变更+抵押变更权利信息保存不上问题（Bug#44515）。
//        任务处理：关闭相关开发任务3个。"

const preview = await getPreview('2026-03-17', '8', workDescription);
const result = await submit(preview.formData);

方式C：混合模式（GitLab + 禅道）

// 先获取GitLab提交
const preview = await getPreview('2026-03-17', '8');

// 使用QoderWork浏览器连接器获取禅道记录并追加
const zentaoDescription = await getZentaoWorkDescription('2026-03-17');
preview.formData.workDescription += '；' + zentaoDescription;

const result = await submit(preview.formData);

步骤3：预览确认

系统会展示填报预览：

╔════════════════════════════════════════════════════════════════╗
║                    OA工时填报预览                               ║
╠════════════════════════════════════════════════════════════════╣
║                                                                ║
║  📅 日期：2026-03-17                                           ║
║  📋 工时类型：应用项目类工时                                     ║
║  📁 关联项目：RJ-H-2024-2312                                    ║
║  🔧 工时子类：编码与测试                                        ║
║  ⏱️  实际工时：8小时                                           ║
║                                                                ║
║  📝 工作描述：                                                  ║
║  代码审查3次，解决抵押变更调档选择580个单位报错问题，           ║
║  完成合同信息栏优化                                             ║
║                                                                ║
╠════════════════════════════════════════════════════════════════╣
║     [✅ 确认提交]    [✏️  修改]    [❌ 取消]                   ║
╚════════════════════════════════════════════════════════════════╝

步骤4：自动填报

确认后，系统自动完成：

1. 启动浏览器
2. 登录OA系统
3. 打开工时填报页面
4. 填充表单数据
5. 提交工时
6. 保存历史记录

---

四、配置选项

4.1 工时类型

值	类型	说明
1	应用项目类工时	客户项目实施
2	产品研发类项目工时	产品研发
3	营销类项目工时	市场活动
4	基建类项目工时	基础设施建设
5	管理类项目工时	管理工作
6	公共类工时	公共事务

4.2 工时子类（常用）

值	子类
19787	需求调研
19788	系统设计
19789	UI设计
19791	编码与测试
19792	质量检查
19795	集成部署
19798	技术支持

4.3 实际工时

范围：0.5 ~ 24 小时，步进 0.5 小时

---

五、完整示例

示例1：纯GitLab模式

const { getPreview, submit } = require('oa-timesheet');

async function fillTimesheet() {
  // 获取今日预览（自动从GitLab获取提交）
  const preview = await getPreview();
  
  console.log('=== 工时填报预览 ===');
  console.log('日期:', preview.display.date);
  console.log('工时:', preview.display.workSheet);
  console.log('项目:', preview.display.projectId);
  console.log('描述:', preview.display.workDescription);
  console.log('描述来源:', preview.display.descriptionSource);
  
  // 用户确认后提交
  const result = await submit(preview.formData);
  console.log('填报结果:', result.message);
}

fillTimesheet();

示例2：禅道Bug修复日（QoderWork浏览器连接器）

const { getPreview, submit } = require('oa-timesheet');

async function fillTimesheet() {
  // 使用QoderWork浏览器连接器自动获取禅道今日工作
  // QoderWork会自动：
  // 1. 打开浏览器访问禅道 http://sc.supermap.com:9909
  // 2. 进入「我的动态」页面，筛选今日记录
  // 3. 获取解决的Bug、关闭的任务、关联的需求
  
  const workDescription = await getZentaoWorkDescription('2026-03-17');
  // 输出: "Bug修复：解决抵押变更调档选择580个单位报错问题（Bug#44576）；
  //        解决一并办理权利信息保存不上问题（Bug#44515）。
  //        任务处理：关闭相关开发任务3个。"
  
  const preview = await getPreview('2026-03-17', '8', workDescription);
  
  console.log('=== 工时填报预览 ===');
  console.log('日期:', preview.display.date);
  console.log('描述:', preview.display.workDescription);
  
  const result = await submit(preview.formData);
  console.log('填报成功:', result.message);
}

fillTimesheet();

示例3：混合工作日（GitLab + 禅道）

const { getPreview, submit } = require('oa-timesheet');

async function fillTimesheet() {
  // 先获取GitLab提交记录
  const preview = await getPreview();
  
  let description = preview.display.workDescription;
  console.log('GitLab描述:', description);
  
  // 使用QoderWork浏览器连接器获取禅道记录并补充
  const zentaoDescription = await getZentaoWorkDescription('2026-03-17');
  console.log('禅道描述:', zentaoDescription);
  
  // 合并描述
  if (zentaoDescription) {
    description += '；' + zentaoDescription;
  }
  
  preview.formData.workDescription = description;
  
  console.log('合并后描述:', description);
  
  const result = await submit(preview.formData);
  console.log('填报成功:', result.message);
}

fillTimesheet();

---

六、常见问题

Q1: GitLab token如何获取？

1. 登录GitLab → 用户设置 → 访问令牌
2. 创建新令牌，勾选 read_api 权限
3. 复制token到 config.js

Q2: 为什么GitLab没有获取到提交？

• 检查token是否有效
• 确认当天是否有push记录
• 检查用户名是否匹配

Q3: 如何禁用GitLab自动获取？

// 传入自定义描述，跳过GitLab
const preview = await getPreview('2026-03-17', '8', '自定义工作描述');

Q4: 如何查看描述来源？

const preview = await getPreview();
console.log(preview.display.descriptionSource);
// 输出: "GitLab提交" / "用户指定" / "历史记录" / "无"

Q5: 如何修改默认项目？

编辑 config.js：

defaults: {
  projectId: '你的项目编号',
}

---

七、最佳实践

每日工作流程

下班前 10 分钟:
  ├── 查看禅道今日动态
  ├── 整理今日完成的工作
  ├── 调用 oa-timesheet 技能
  │     ├── 优先使用 GitLab 自动获取
  │     ├── 补充禅道 Bug/需求记录
  │     └── 确认并提交
  └── 检查填报结果

工作描述建议

GitLab自动生成：

• 保持提交信息规范（fix: / feat: 前缀）
• Merge提交自动识别为"代码审查"

禅道自动获取（QoderWork）：

• QoderWork自动访问禅道，获取今日动态
• 自动分类：Bug修复、需求开发、任务处理
• 自动提取关键ID：Bug#44576、Story#91973
• 无需手动整理，自动生成描述

---

八、总结

oa-timesheet 技能提供两种数据获取方式：

方式	优点	适用场景
GitLab自动	无需手动整理、自动生成描述	有代码提交的开发日
禅道自动	QoderWork自动获取、覆盖全面	无代码提交、混合工作
历史继承	快速填报、减少选择	连续同一项目工作

推荐使用流程：

1. 优先使用 GitLab 自动获取
2. 检查生成的描述是否完整
3. 如有遗漏，追加禅道记录
4. 确认提交

使用本技能，工时填报从15分钟缩短到1-2分钟！

---

文档版本：v1.0
更新日期：2026-03-17
技能：oa-timesheet