worsoft-daily-mcp 0.1.0

package/.env.example

@@ -0,0 +1,15 @@
+# Worsoft gateway base URL. Frontend dev proxy /api maps to this target.
+WORSOFT_BASE_URL=https://saas.link-work.com.cn/api
+
+# Login credentials. Prefer setting these in your MCP client config env.
+WORSOFT_USERNAME=
+WORSOFT_PASSWORD=
+
+# Frontend login uses Basic cGlnOnBpZw==, platform pc_saas, VERSION LT.
+WORSOFT_BASIC_AUTH=Basic cGlnOnBpZw==
+WORSOFT_PLATFORM=pc_saas
+WORSOFT_VERSION=LT
+
+# Optional defaults.
+WORSOFT_DEFAULT_PAGE_SIZE=100
+WORSOFT_TIMEOUT_MS=120000

package/README.md

@@ -0,0 +1,84 @@
+# Worsoft Daily MCP
+
+这个 MCP 用来让模型通过 Worsoft 后端接口读取日报、获取日报详情、收集月报总结素材，并提交日报或月报。
+
+## 已对齐的现有接口
+
+- 登录：`POST /auth/oauth/token`
+- 当前用户：`GET /admin/user/info`
+- 日报查询：`GET /hr/HrReportDaily/page`
+- 日报详情：`GET /hr/HrReportDaily/{id}`
+- 新增日报/月报：`POST /hr/HrReportDaily`
+- 修改日报/月报：`PUT /hr/HrReportDaily`
+- 当前时间段任务：`GET /hr/HrReportDaily/getTaskByExecuteUserId`
+
+前端开发代理里的 `/api` 已被折叠进 `WORSOFT_BASE_URL`，默认值是 `https://saas.link-work.com.cn/api`。
+
+## 配置
+
+推荐在 MCP 客户端配置环境变量，不要把账号密码写进仓库。
+
+```json
+{
+  "mcpServers": {
+    "worsoft-daily": {
+      "command": "node",
+      "args": ["E:\\project\\worsoft-daily-mcp\\src\\server.js"],
+      "env": {
+        "WORSOFT_BASE_URL": "https://saas.link-work.com.cn/api",
+        "WORSOFT_USERNAME": "你的用户名",
+        "WORSOFT_PASSWORD": "你的密码",
+        "WORSOFT_PLATFORM": "pc_saas",
+        "WORSOFT_VERSION": "LT",
+        "WORSOFT_BASIC_AUTH": "Basic cGlnOnBpZw=="
+      }
+    }
+  }
+}
+```
+
+也可以复制 `.env.example` 为 `.env` 后在本目录运行，但不要提交 `.env`。
+
+## 工具
+
+- `worsoft_login`：登录并缓存 token。
+- `worsoft_get_user_info`：获取当前登录用户。
+- `worsoft_query_reports`：按类型、时间和范围查询汇报。
+- `worsoft_get_report`：获取单条完整汇报详情。注意后端会把当前用户标记为已读。
+- `worsoft_get_report_tasks`：获取指定时间段内当前用户相关任务。
+- `worsoft_month_summary_source`：读取某个月的日报详情，供模型生成月报总结。
+- `worsoft_submit_report`：新增或修改日报、周报、月报。建议先传 `dryRun: true` 检查 payload。
+
+## 查询语义
+
+`scope` 会映射到后端的 `sign`：
+
+- `related` -> `0`，我提交或我收到
+- `submitted` -> `1`，我提交的
+- `received` -> `2`，我收到的
+
+`reportType` 会映射到后端的 `reportingType`：
+
+- `daily` -> `0`
+- `weekly` -> `1`
+- `monthly` -> `2`
+- `all` -> 不过滤类型
+
+日期过滤会按前端页面同款逻辑转换成：
+
+- `startTime >= startDate`
+- `endTime <= endDate`
+
+## 月报流程建议
+
+1. 调 `worsoft_month_summary_source`，例如 `{ "month": "2026-06", "scope": "submitted" }`。
+2. 模型根据返回的日报详情生成月报正文和下月计划。
+3. 调 `worsoft_submit_report`，`reportType` 传 `monthly`，`startDate` 传当月 1 日，`endDate` 传当月最后一天。
+4. 首次提交先用 `dryRun: true`，确认后再真实提交。
+
+## 本地检查
+
+```powershell
+cd E:\project\worsoft-daily-mcp
+npm run check
+```

package/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "worsoft-daily-mcp",
+  "version": "0.1.0",
+  "description": "MCP stdio server for Worsoft daily and monthly reports.",
+  "type": "module",
+  "bin": "./src/server.js",
+  "scripts": {
+    "start": "node ./src/server.js",
+    "check": "node --check ./src/server.js"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "UNLICENSED"
+}

package/src/server.js

@@ -0,0 +1,647 @@
+#!/usr/bin/env node
+
+import readline from "node:readline";
+import { readFileSync, existsSync } from "node:fs";
+import { resolve } from "node:path";
+
+const SERVER_NAME = "worsoft-daily-mcp";
+const SERVER_VERSION = "0.1.0";
+
+loadDotEnv();
+
+const config = {
+  baseUrl: trimTrailingSlash(env("WORSOFT_BASE_URL", "https://saas.link-work.com.cn/api")),
+  username: env("WORSOFT_USERNAME", ""),
+  password: env("WORSOFT_PASSWORD", ""),
+  basicAuth: env("WORSOFT_BASIC_AUTH", "Basic cGlnOnBpZw=="),
+  platform: env("WORSOFT_PLATFORM", "pc_saas"),
+  version: env("WORSOFT_VERSION", "LT"),
+  timeoutMs: Number(env("WORSOFT_TIMEOUT_MS", "120000")),
+  defaultPageSize: Number(env("WORSOFT_DEFAULT_PAGE_SIZE", "100"))
+};
+
+let tokenState = {
+  accessToken: "",
+  refreshToken: "",
+  expiresAt: 0
+};
+
+const tools = [
+  {
+    name: "worsoft_login",
+    description: "Login to Worsoft and cache the access token. Usually credentials should come from MCP environment variables.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        username: { type: "string", description: "Optional username override." },
+        password: { type: "string", description: "Optional password override." },
+        baseUrl: { type: "string", description: "Optional Worsoft gateway base URL, for example https://saas.link-work.com.cn/api." }
+      },
+      additionalProperties: false
+    }
+  },
+  {
+    name: "worsoft_get_user_info",
+    description: "Get the currently logged-in Worsoft user information from /admin/user/info.",
+    inputSchema: {
+      type: "object",
+      properties: {},
+      additionalProperties: false
+    }
+  },
+  {
+    name: "worsoft_query_reports",
+    description: "Query Worsoft report records with business-friendly filters. Supports daily, weekly, and monthly reports.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        reportType: {
+          type: "string",
+          enum: ["daily", "weekly", "monthly", "all"],
+          description: "Report type. daily=0, weekly=1, monthly=2."
+        },
+        scope: {
+          type: "string",
+          enum: ["related", "submitted", "received"],
+          description: "related queries reports submitted by or sent to current user. submitted queries only current user's reports. received queries reports sent to current user."
+        },
+        startDate: { type: "string", description: "Start date inclusive, yyyy-MM-dd." },
+        endDate: { type: "string", description: "End date inclusive, yyyy-MM-dd." },
+        current: { type: "integer", minimum: 1, description: "Page number." },
+        size: { type: "integer", minimum: 1, maximum: 500, description: "Page size." },
+        smartVal: { type: "string", description: "Optional keyword search." },
+        includeDetails: { type: "boolean", description: "Whether to fetch full detail for each returned record." }
+      },
+      additionalProperties: false
+    }
+  },
+  {
+    name: "worsoft_get_report",
+    description: "Get full detail for one Worsoft report by id. The backend marks the report as read for the current user.",
+    inputSchema: {
+      type: "object",
+      required: ["id"],
+      properties: {
+        id: { type: "string", description: "Report id." }
+      },
+      additionalProperties: false
+    }
+  },
+  {
+    name: "worsoft_get_report_tasks",
+    description: "Get current user's task records that overlap a date range, matching the frontend report form behavior.",
+    inputSchema: {
+      type: "object",
+      required: ["startDate", "endDate"],
+      properties: {
+        startDate: { type: "string", description: "Start date, yyyy-MM-dd." },
+        endDate: { type: "string", description: "End date, yyyy-MM-dd." }
+      },
+      additionalProperties: false
+    }
+  },
+  {
+    name: "worsoft_submit_report",
+    description: "Create or update a Worsoft report. Use dryRun first when a model has generated the content.",
+    inputSchema: {
+      type: "object",
+      required: ["reportType", "startDate", "endDate", "todayTaskConditionStatement"],
+      properties: {
+        id: { type: "string", description: "Existing report id. If set, the MCP updates that report; otherwise it creates one." },
+        reportType: {
+          type: "string",
+          enum: ["daily", "weekly", "monthly"],
+          description: "daily=0, weekly=1, monthly=2."
+        },
+        startDate: { type: "string", description: "Start date, yyyy-MM-dd." },
+        endDate: { type: "string", description: "End date, yyyy-MM-dd." },
+        todayTaskConditionStatement: { type: "string", description: "Current period completion summary. HTML is accepted because the backend form uses rich text." },
+        tomorrowTaskConditionStatement: { type: "string", description: "Next period plan. HTML is accepted." },
+        publicOrNot: { type: "string", enum: ["0", "1"], description: "Matches backend field publicOrNot. Defaults to the frontend form value 0." },
+        currentTaskId: { type: "string", description: "Comma-separated current task ids. If omitted and includeCurrentTasks=true, MCP fills it from getTaskByExecuteUserId." },
+        nextTimeTaskId: { type: "string", description: "Comma-separated next period task ids." },
+        recipientUsers: {
+          type: "array",
+          description: "Copied recipients.",
+          items: {
+            type: "object",
+            required: ["recipientUserId", "recipientUser"],
+            properties: {
+              recipientUserId: { type: ["string", "number"] },
+              recipientUser: { type: "string" },
+              signExamine: { type: "string", enum: ["0", "1"] },
+              recipientUserType: { type: "string", enum: ["0", "1"] }
+            },
+            additionalProperties: false
+          }
+        },
+        includeCurrentTasks: { type: "boolean", description: "When true, fills currentTaskId and reviewer details from overlapping tasks." },
+        bugIds: { type: "string", description: "Comma-separated related bug ids." },
+        dryRun: { type: "boolean", description: "When true, return the payload without submitting." }
+      },
+      additionalProperties: false
+    }
+  },
+  {
+    name: "worsoft_month_summary_source",
+    description: "Fetch detailed daily reports for a month so the calling model can summarize them into a monthly report.",
+    inputSchema: {
+      type: "object",
+      required: ["month"],
+      properties: {
+        month: { type: "string", description: "Month in yyyy-MM format." },
+        scope: {
+          type: "string",
+          enum: ["related", "submitted", "received"],
+          description: "Usually submitted for summarizing your own month."
+        },
+        includeWeeklyAndMonthly: { type: "boolean", description: "Include weekly/monthly reports too. Defaults to false, daily only." }
+      },
+      additionalProperties: false
+    }
+  }
+];
+
+const handlers = {
+  async worsoft_login(args) {
+    const loginResult = await login(args);
+    return {
+      ok: true,
+      baseUrl: config.baseUrl,
+      tokenType: loginResult.token_type,
+      expiresIn: loginResult.expires_in,
+      hasRefreshToken: Boolean(loginResult.refresh_token)
+    };
+  },
+
+  async worsoft_get_user_info() {
+    return unwrap(await apiRequest("GET", "/admin/user/info"));
+  },
+
+  async worsoft_query_reports(args) {
+    const response = unwrap(await apiRequest("GET", "/hr/HrReportDaily/page", {
+      query: buildReportQuery(args)
+    }));
+    if (!args?.includeDetails) {
+      return response;
+    }
+    const records = Array.isArray(response?.records) ? response.records : [];
+    const details = [];
+    for (const record of records) {
+      if (record?.id != null) {
+        details.push(unwrap(await apiRequest("GET", `/hr/HrReportDaily/${record.id}`)));
+      }
+    }
+    return { ...response, records: details };
+  },
+
+  async worsoft_get_report(args) {
+    assertRequired(args, ["id"]);
+    return unwrap(await apiRequest("GET", `/hr/HrReportDaily/${encodeURIComponent(String(args.id))}`));
+  },
+
+  async worsoft_get_report_tasks(args) {
+    assertRequired(args, ["startDate", "endDate"]);
+    assertDate(args.startDate, "startDate");
+    assertDate(args.endDate, "endDate");
+    return unwrap(await apiRequest("GET", "/hr/HrReportDaily/getTaskByExecuteUserId", {
+      query: { startTime: args.startDate, endTime: args.endDate }
+    }));
+  },
+
+  async worsoft_submit_report(args) {
+    const payload = await buildSubmitPayload(args);
+    if (args?.dryRun) {
+      return { dryRun: true, method: payload.id ? "PUT" : "POST", path: "/hr/HrReportDaily", payload };
+    }
+    const method = payload.id ? "PUT" : "POST";
+    return unwrap(await apiRequest(method, "/hr/HrReportDaily", { body: payload }));
+  },
+
+  async worsoft_month_summary_source(args) {
+    assertRequired(args, ["month"]);
+    if (!/^\d{4}-\d{2}$/.test(args.month)) {
+      throw new Error("month must be yyyy-MM.");
+    }
+    const startDate = `${args.month}-01`;
+    const endDate = lastDateOfMonth(args.month);
+    const response = unwrap(await apiRequest("GET", "/hr/HrReportDaily/page", {
+      query: buildReportQuery({
+        reportType: args.includeWeeklyAndMonthly ? "all" : "daily",
+        scope: args.scope || "submitted",
+        startDate,
+        endDate,
+        current: 1,
+        size: 100
+      })
+    }));
+    const records = Array.isArray(response?.records) ? response.records : [];
+    const details = [];
+    for (const record of records) {
+      if (record?.id != null) {
+        details.push(unwrap(await apiRequest("GET", `/hr/HrReportDaily/${record.id}`)));
+      }
+    }
+    return {
+      month: args.month,
+      startDate,
+      endDate,
+      total: response?.total ?? details.length,
+      records: details,
+      summaryHint: "Use these records to summarize completed work, risks/blockers, task progress, and next-month plan, then call worsoft_submit_report with reportType=monthly."
+    };
+  }
+};
+
+const rl = readline.createInterface({
+  input: process.stdin,
+  output: process.stdout,
+  terminal: false
+});
+
+rl.on("line", async (line) => {
+  if (!line.trim()) return;
+  let request;
+  try {
+    request = JSON.parse(line);
+  } catch (error) {
+    sendError(null, -32700, "Parse error", error.message);
+    return;
+  }
+
+  if (!request || request.jsonrpc !== "2.0" || typeof request.method !== "string") {
+    sendError(request?.id ?? null, -32600, "Invalid Request");
+    return;
+  }
+
+  try {
+    if (request.method === "initialize") {
+      sendResult(request.id, {
+        protocolVersion: request.params?.protocolVersion || "2024-11-05",
+        capabilities: { tools: {} },
+        serverInfo: { name: SERVER_NAME, version: SERVER_VERSION }
+      });
+      return;
+    }
+
+    if (request.method === "notifications/initialized") {
+      return;
+    }
+
+    if (request.method === "tools/list") {
+      sendResult(request.id, { tools });
+      return;
+    }
+
+    if (request.method === "tools/call") {
+      const name = request.params?.name;
+      const args = request.params?.arguments || {};
+      if (!handlers[name]) {
+        sendError(request.id, -32602, `Unknown tool: ${name}`);
+        return;
+      }
+      const result = await handlers[name](args);
+      sendResult(request.id, {
+        content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
+      });
+      return;
+    }
+
+    sendError(request.id, -32601, `Method not found: ${request.method}`);
+  } catch (error) {
+    sendResult(request.id, {
+      isError: true,
+      content: [{ type: "text", text: errorToText(error) }]
+    });
+  }
+});
+
+function loadDotEnv() {
+  const envPath = resolve(process.cwd(), ".env");
+  if (!existsSync(envPath)) return;
+  const content = readFileSync(envPath, "utf8");
+  for (const rawLine of content.split(/\r?\n/)) {
+    const line = rawLine.trim();
+    if (!line || line.startsWith("#")) continue;
+    const index = line.indexOf("=");
+    if (index <= 0) continue;
+    const key = line.slice(0, index).trim();
+    const value = line.slice(index + 1).trim().replace(/^['"]|['"]$/g, "");
+    if (!process.env[key]) {
+      process.env[key] = value;
+    }
+  }
+}
+
+function env(name, fallback) {
+  return process.env[name] == null || process.env[name] === "" ? fallback : process.env[name];
+}
+
+function trimTrailingSlash(value) {
+  return String(value || "").replace(/\/+$/, "");
+}
+
+function sendResult(id, result) {
+  process.stdout.write(`${JSON.stringify({ jsonrpc: "2.0", id, result })}\n`);
+}
+
+function sendError(id, code, message, data) {
+  process.stdout.write(`${JSON.stringify({ jsonrpc: "2.0", id, error: { code, message, data } })}\n`);
+}
+
+function errorToText(error) {
+  if (error?.responseBody) {
+    return `${error.message}\n${JSON.stringify(error.responseBody, null, 2)}`;
+  }
+  return error?.stack || error?.message || String(error);
+}
+
+async function login(args = {}) {
+  if (args.baseUrl) {
+    config.baseUrl = trimTrailingSlash(args.baseUrl);
+  }
+  const username = args.username || config.username;
+  const password = args.password || config.password;
+  if (!username || !password) {
+    throw new Error("Missing Worsoft credentials. Set WORSOFT_USERNAME and WORSOFT_PASSWORD or pass username/password to worsoft_login.");
+  }
+
+  const params = new URLSearchParams({ grant_type: "password" });
+  const body = new URLSearchParams({ username, password });
+  const response = await rawRequest("POST", `/auth/oauth/token?${params}`, {
+    headers: {
+      Authorization: config.basicAuth,
+      platform: config.platform,
+      "content-type": "application/x-www-form-urlencoded"
+    },
+    body: body.toString(),
+    skipAuth: true
+  });
+
+  const data = response.body;
+  const accessToken = data?.access_token || data?.data?.access_token;
+  if (!accessToken) {
+    const err = new Error("Login response did not contain access_token.");
+    err.responseBody = data;
+    throw err;
+  }
+
+  const expiresIn = Number(data.expires_in || data?.data?.expires_in || 3600);
+  tokenState = {
+    accessToken,
+    refreshToken: data.refresh_token || data?.data?.refresh_token || "",
+    expiresAt: Date.now() + Math.max(30, expiresIn - 60) * 1000
+  };
+  return data;
+}
+
+async function ensureLogin() {
+  if (tokenState.accessToken && Date.now() < tokenState.expiresAt) {
+    return;
+  }
+  await login();
+}
+
+async function apiRequest(method, path, options = {}) {
+  await ensureLogin();
+  return rawRequest(method, path, options);
+}
+
+async function rawRequest(method, path, options = {}) {
+  const url = new URL(config.baseUrl + path);
+  if (options.query) {
+    appendQuery(url.searchParams, options.query);
+  }
+
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), config.timeoutMs);
+  const headers = {
+    platform: config.platform,
+    VERSION: config.version,
+    ...(options.headers || {})
+  };
+  if (!options.skipAuth) {
+    headers.Authorization = `Bearer ${tokenState.accessToken}`;
+  }
+
+  let body = options.body;
+  if (body != null && typeof body !== "string") {
+    headers["content-type"] = headers["content-type"] || "application/json";
+    body = JSON.stringify(body);
+  }
+
+  try {
+    const response = await fetch(url, {
+      method,
+      headers,
+      body,
+      signal: controller.signal
+    });
+    const responseBody = await parseResponseBody(response);
+    if (!response.ok || responseBody?.code === 1) {
+      const error = new Error(`Worsoft API ${method} ${url.pathname} failed with HTTP ${response.status}.`);
+      error.responseBody = responseBody;
+      throw error;
+    }
+    return { status: response.status, body: responseBody };
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+
+async function parseResponseBody(response) {
+  const text = await response.text();
+  if (!text) return null;
+  try {
+    return JSON.parse(text);
+  } catch {
+    return text;
+  }
+}
+
+function unwrap(response) {
+  const body = response.body;
+  if (body && typeof body === "object" && Object.prototype.hasOwnProperty.call(body, "data")) {
+    return body.data;
+  }
+  return body;
+}
+
+function appendQuery(searchParams, query) {
+  for (const [key, value] of Object.entries(query)) {
+    if (value == null || value === "") continue;
+    if (Array.isArray(value)) {
+      for (const item of value) searchParams.append(key, String(item));
+    } else if (typeof value === "object") {
+      searchParams.append(key, JSON.stringify(value));
+    } else {
+      searchParams.append(key, String(value));
+    }
+  }
+}
+
+function buildReportQuery(args = {}) {
+  const current = args.current || 1;
+  const size = args.size || config.defaultPageSize;
+  const reportType = args.reportType || "daily";
+  const scope = args.scope || "submitted";
+  const query = {
+    current,
+    size,
+    orderBy: "endTime:desc",
+    sign: scopeToSign(scope)
+  };
+
+  const customFilters = [];
+  if (args.startDate) {
+    assertDate(args.startDate, "startDate");
+    customFilters.push({ name: "startTime", filterType: 13, filterValue: [args.startDate] });
+  }
+  if (args.endDate) {
+    assertDate(args.endDate, "endDate");
+    customFilters.push({ name: "endTime", filterType: 15, filterValue: [args.endDate] });
+  }
+  if (customFilters.length > 0) {
+    query.conditionFormat = customFilters.map(() => "1").join("a");
+    query.customFilters = JSON.stringify(customFilters);
+  }
+
+  if (reportType !== "all") {
+    query["entityExt[reportingType]"] = [reportTypeToCode(reportType)];
+    query.filterTypes = JSON.stringify({ reportingType: 30 });
+  }
+
+  if (args.smartVal) {
+    query.smartVal = args.smartVal;
+    query.smartNames = ["createUser", "todayTaskConditionStatement", "tomorrowTaskConditionStatement"];
+  }
+
+  return query;
+}
+
+async function buildSubmitPayload(args = {}) {
+  assertRequired(args, ["reportType", "startDate", "endDate", "todayTaskConditionStatement"]);
+  assertDate(args.startDate, "startDate");
+  assertDate(args.endDate, "endDate");
+
+  const payload = {
+    id: args.id,
+    reportingType: reportTypeToCode(args.reportType),
+    startTime: args.startDate,
+    endTime: args.endDate,
+    billDate: today(),
+    publicOrNot: args.publicOrNot || "0",
+    todayTaskConditionStatement: args.todayTaskConditionStatement,
+    tomorrowTaskConditionStatement: args.tomorrowTaskConditionStatement || "",
+    currentTaskId: args.currentTaskId || "",
+    nextTimeTaskId: args.nextTimeTaskId || "",
+    bugIds: args.bugIds || "",
+    hrReportDailyDetailList: normalizeRecipientUsers(args.recipientUsers || [])
+  };
+
+  if (args.id) {
+    const hasRecipientOverride = Array.isArray(args.recipientUsers);
+    const existing = unwrap(await apiRequest("GET", `/hr/HrReportDaily/${encodeURIComponent(String(args.id))}`));
+    Object.assign(payload, cleanUndefined({
+      createTime: existing?.createTime,
+      createUserId: existing?.createUserId,
+      createUser: existing?.createUser,
+      createDptId: existing?.createDptId,
+      createDpt: existing?.createDpt,
+      tenantId: existing?.tenantId
+    }));
+    if (!hasRecipientOverride) {
+      payload.hrReportDailyDetailList = normalizeRecipientUsers(existing?.hrReportDailyDetailList || existing?.HrReportDailyDetailList || []);
+    }
+    payload.evaluationContents = existing?.evaluationContents || [];
+  }
+
+  if (args.includeCurrentTasks) {
+    const tasks = unwrap(await apiRequest("GET", "/hr/HrReportDaily/getTaskByExecuteUserId", {
+      query: { startTime: args.startDate, endTime: args.endDate }
+    })) || [];
+    if (!payload.currentTaskId) {
+      payload.currentTaskId = tasks.map((task) => task.id).filter(Boolean).join(",");
+    }
+    const reviewerDetails = tasks
+      .filter((task) => task.submitUserId && task.submitUserName)
+      .map((task) => ({
+        recipientUserId: task.submitUserId,
+        recipientUser: task.submitUserName,
+        signExamine: "1",
+        recipientUserType: "1"
+      }));
+    payload.hrReportDailyDetailList = uniqueRecipients([
+      ...payload.hrReportDailyDetailList,
+      ...reviewerDetails
+    ]);
+  }
+
+  return payload;
+}
+
+function normalizeRecipientUsers(users) {
+  return uniqueRecipients(users.map((user) => ({
+    recipientUserId: user.recipientUserId,
+    recipientUser: user.recipientUser,
+    signExamine: user.signExamine || "1",
+    recipientUserType: user.recipientUserType || "0"
+  })).filter((user) => user.recipientUserId && user.recipientUser));
+}
+
+function uniqueRecipients(users) {
+  const seen = new Set();
+  const result = [];
+  for (const user of users) {
+    const key = `${user.recipientUserType || "0"}:${user.recipientUserId}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    result.push(user);
+  }
+  return result;
+}
+
+function reportTypeToCode(type) {
+  const map = { daily: "0", weekly: "1", monthly: "2" };
+  if (!map[type]) throw new Error("reportType must be daily, weekly, or monthly.");
+  return map[type];
+}
+
+function scopeToSign(scope) {
+  const map = { related: 0, submitted: 1, received: 2 };
+  if (!Object.prototype.hasOwnProperty.call(map, scope)) {
+    throw new Error("scope must be related, submitted, or received.");
+  }
+  return map[scope];
+}
+
+function assertRequired(args, names) {
+  for (const name of names) {
+    if (args?.[name] == null || args[name] === "") {
+      throw new Error(`Missing required argument: ${name}`);
+    }
+  }
+}
+
+function assertDate(value, name) {
+  if (!/^\d{4}-\d{2}-\d{2}$/.test(String(value))) {
+    throw new Error(`${name} must be yyyy-MM-dd.`);
+  }
+}
+
+function today() {
+  const date = new Date();
+  const year = date.getFullYear();
+  const month = String(date.getMonth() + 1).padStart(2, "0");
+  const day = String(date.getDate()).padStart(2, "0");
+  return `${year}-${month}-${day}`;
+}
+
+function lastDateOfMonth(month) {
+  const [year, monthNumber] = month.split("-").map(Number);
+  return new Date(Date.UTC(year, monthNumber, 0)).toISOString().slice(0, 10);
+}
+
+function cleanUndefined(object) {
+  return Object.fromEntries(Object.entries(object).filter(([, value]) => value !== undefined));
+}