onesystems/leantime-timesheets

Leantime工时表导出与邮件发送工具

通过JSON-RPC API（使用API密钥）从Leantime系统拉取工时数据，将时间戳从UTC转换为本地日历日期，生成CSV文件，并向每个用户发送汇总邮件。可单次运行或通过Cron定时任务执行，基于轻量Alpine容器构建。

核心特点

• 🕒 准确的UTC→本地时间转换（如Europe/Zurich），支持可靠的日期解析
• 📅 周期预设：last_day（昨日）、last_week（上周）、last_month（上月）（适用于定时自动化）
• 📤 CSV输出 + HTML邮件汇总（可选附件）
• 👤 严格的按用户过滤（无跨用户数据行）
• 🧠 项目缓存与智能客户端//项目检测，自动填充CSV的Client列
• 📧 若用户在周期内无工时，则跳过邮件发送
• 🔐 通过API密钥（x-api-key）认证访问Leantime JSON-RPC接口

CSV格式

表头（分号分隔）：

date;hours;client;projectId;projectName;ticketId;ticketTitle;type;description

日期格式由CSV_DATE_STRFTIME控制（默认"%d.%m.%Y"，例如22.09.2025）。

快速开始

Docker Run

bash
docker run --rm \
  -e LEANTIME_API_URL="https://planner.example.com/api/jsonrpc" \
  -e LEANTIME_API_KEY="你的API密钥" \
  -e LEANTIME_USERS="alice@example.com,bob@example.com" \
  -e LEANTIME_PERIOD="last_week" \
  -e LOCAL_TZ="Asia/Shanghai" \
  -e SMTP_HOST="smtp.office365.com" \
  -e SMTP_PORT=587 \
  -e SMTP_STARTTLS=true \
  -e SMTP_USERNAME="support@example.com" \
  -e SMTP_PASSWORD="****" \
  -e SMTP_FROM="工时表机器人 <support@example.com>" \
  -v $(pwd)/out:/app/out \
  docker.xuanyuan.run/onesystems/leantime-timesheets:latest

Docker Compose

yaml
services:
  leantime-timesheets:
    image: docker.xuanyuan.run/onesystems/leantime-timesheets:latest
    restart: unless-stopped
    env_file: .env          # 可选，或使用下方的environment配置
    environment:
      LEANTIME_API_URL: https://planner.example.com/api/jsonrpc
      LEANTIME_API_KEY: ${LEANTIME_API_KEY}
      LEANTIME_USERS: alice@example.com, bob@example.com
      LEANTIME_PERIOD: last_week          # last_day | last_week | last_month
      LOCAL_TZ: Asia/Shanghai
      CSV_DATE_STRFTIME: "%d.%m.%Y"
      SMTP_HOST: smtp.office365.com
      SMTP_PORT: 587
      SMTP_STARTTLS: "true"
      SMTP_SSL: "false"
      SMTP_USERNAME: support@example.com
      SMTP_PASSWORD: ${SMTP_PASSWORD}
      SMTP_FROM: "工时表机器人 <support@example.com>"
      # 可选配置：
      # SMTP_EXTRA_TO: manager@example.com
      # ADMIN_CC:
      # TIMESHEETS_BCC_ALL:
      # STRICT_USER_FILTER: "true"
      # RESOLVE_TICKET_TITLES: "false"
      # DEBUG: "false"
      # CRON_SCHEDULE: "0 7 * * 1"  # 每周一07:00运行
    volumes:
      - ./out:/app/out

若未设置CRON_SCHEDULE，容器会执行一次任务后退出；若设置（如"0 7 * * 1"），则容器保持运行并定期执行任务。

环境变量配置

Leantime API（必填）

• LEANTIME_API_URL – 示例：https://planner.example.com/api/jsonrpc
• LEANTIME_API_KEY – 用于x-api-key请求头的API密钥

时间范围与用户

• LEANTIME_PERIOD – 可选值：last_day | last_week | last_month
• LEANTIME_USERS – 逗号/分号分隔的用户***列表
• LEANTIME_START、LEANTIME_END – 格式YYYY-MM-DD（若同时设置则覆盖LEANTIME_PERIOD）

时区与格式

• LOCAL_TZ – 本地时区（默认Europe/Zurich，建议改为Asia/Shanghai）
• SERVER_TZ – 兼容保留项（默认UTC，不影响时间转换）
• CSV_DATE_STRFTIME – 日期格式（默认"%d.%m.%Y"）

邮件配置（可选但推荐）

• SMTP_HOST、SMTP_PORT – SMTP服务器地址与端口
• SMTP_STARTTLS（true/false）、SMTP_SSL（false/true）– 加密方式
• SMTP_USERNAME、SMTP_PASSWORD – SMTP认证凭据
• SMTP_FROM – 发件人信息，示例：工时表机器人 <support@example.com>
• SMTP_EXTRA_TO – 额外收件人列表（逗号/分号分隔）
• ADMIN_CC、TIMESHEETS_BCC_ALL – 可选抄送/密送列表

行为开关

• STRICT_USER_FILTER – 默认true（仅保留目标用户的工时数据）
• RESOLVE_TICKET_TITLES – 默认false（未来功能预留）
• DEBUG – 默认false（打印RPC调用与缓存信息）

定时任务

• CRON_SCHEDULE – 空值则单次运行；否则为标准Crontab表达式（如0 7 * * 1）
• 容器时区由TZ变量控制（镜像默认Europe/Zurich）

工作原理

1. 根据本地时间确定周期（last_day/last_week/last_month）
2. 使用API密钥通过JSON-RPC查询Leantime数据
3. 将时间戳（ epoch/ISO格式）标准化为UTC，再转换为LOCAL_TZ的日历日期
4. 构建Client列值：
   • 从项目标题Client // Project拆分（优先）
   • 从项目元数据（clientName/company等）获取
   • 从缓存的项目映射中读取
5. 将结果写入/app/out目录下的CSV文件
6. 向每个用户发送邮件（若总工时<=0则跳过）

Cron定时示例

• 每周一07:00（导出上周数据）：

  CRON_SCHEDULE=0 7 * * 1
  LEANTIME_PERIOD=last_week
  

• 每月1日08:30（导出上月数据）：

  CRON_SCHEDULE=30 8 1 * *
  LEANTIME_PERIOD=last_month
  

退出行为

• 无CRON_SCHEDULE：执行一次任务后退出（适用于临时/CI场景）
• 有CRON_SCHEDULE：容器保持运行，Cron触发任务并输出日志到stdout（容器内路径/var/log/cron.log）

故障排除

• 401 Unauthorized：检查LEANTIME_API_URL（需包含https://…/api/jsonrpc）和LEANTIME_API_KEY是否正确
• Client列为空：确保Leantime项目名称遵循Client // Project格式，或项目元数据包含客户端/公司字段；工具会缓存这些信息
• 日期错误：验证LOCAL_TZ、主机时区挂载及CSV_DATE_STRFTIME格式
• 无邮件发送：SMTP配置需正确；若用户无工时则跳过邮件

安全注意事项

• 优先通过env_file或Docker Secrets传递敏感信息
• 限制API密钥权限并定期轮换
• 尽可能以最小权限运行容器

作者

• Michael Kleger
  OneSystems GmbH

  ---

许可证

MIT许可证 – 允许商业和个人免费使用。