@jira-deploy/core 1.0.0

package/tools/cd.js

@@ -0,0 +1,666 @@
+/**
+ * CI Golden Image 相關 tools
+ *   - create_cd_ticket
+ */
+import {error, getModuleName, getServerList, ok, today} from './helpers.js';
+import {
+  CD_FIELD_IDS,
+  CI_FIELD_IDS,
+  SERVERS,
+  DEPT_CODES,
+  ENV_CODES,
+  FIELD_OPTIONS,
+  ISSUE_TYPE_IDS,
+  JIRA_PROJECT_ID,
+  LIBRARY_MODULE_IDS,
+  SYSTEM_CODES,
+  SYSTEM_MODULES,
+  SYSTEM_TO_DEPT_MAP,
+  MODULE_MAP,
+  REPO_MAPS,
+  REPO_LABEL_MAP,
+} from '../constants/index.js';
+import {SERVER_MODULE_MAP} from '../constants/server.js';
+
+// ── Schema definitions ───────────────────────────────────────────
+export function getCDToolDefinitions() {
+  return [
+    {
+      name: 'create_cd_ticket',
+      description: '建立 CD Deploy 上版單。專用工具，提前驗證必填欄位和叢集配置',
+      inputSchema: {
+        type: 'object',
+        required: ['systemCode', 'ciTicket'],
+        properties: {
+          systemCode: {
+            type: 'string',
+            enum: Object.values(SYSTEM_CODES),
+            description: '系統代碼',
+          },
+          environment: {
+            type: 'string',
+            enum: Object.keys(ENV_CODES),
+            description: '部署環境，必填，預設為 stg',
+          },
+          isClusterDeploy: {
+            type: 'boolean',
+            description: '(選填) 是否要集群部署，預設為 true',
+          },
+          summary: {
+            type: 'string',
+            description:
+              '（選填）自訂標題，不填則自動生成：[IBK][STG] 程式上版作業申請單_YYYYMMDD (CD deployment with {release_version})',
+          },
+          ciTicket: {
+            type: 'string',
+            description:
+              '關聯的 CI 單 issue key，例如 CID-1677。自動：① 取 release_version 填入 summary/CID_deploy_version ② 查 CI 所有 relates Library 單，各自取 CID_branch 找 LBPRJ 版本頁 → 加 Web Link',
+          },
+          metaTest: {
+            type: 'boolean',
+            description:
+              '(選填) 是否為封測用，true 代表是封測用單，只有 cwa or ibk 有 prd 封測機 web05，extra_cluster_deploy 只有有 tvprd-{ibk/cwa}-web05，預設為 false',
+          },
+          dryRun: {
+            type: 'boolean',
+            description:
+              '(選填) 預覽模式，不實際建立 Jira 單，回傳會送出的 payload（reads 操作如取 CI 版本仍會執行）',
+          },
+        },
+      },
+    },
+  ];
+}
+
+/**
+ * 建立 CD 上版單
+ */
+export async function handleCreateCDTicket(args, {jira, notifier}) {
+  try {
+    const envCode = (args.environment ?? '').toLowerCase();
+    const ciTicket = args.ciTicket ?? args.linkedCiKey;
+    const clusterDeploy = typeof args.clusterDeploy === 'string'
+      ? args.clusterDeploy.split(',').map((cluster) => cluster.trim()).filter(Boolean)
+      : null;
+    const isClusterDeploy = args.isClusterDeploy ?? (envCode !== 'dev');
+    const normalizedArgs = {
+      ...args,
+      ciTicket,
+      isClusterDeploy,
+      environment: envCode,
+    };
+
+    // 未指定環境時，詢問使用者是否使用 STG
+    if (!normalizedArgs.environment) {
+      return ok({
+        confirm_environment: true,
+        message: '請問要部署到 STG 環境嗎？（STG / UAT / PRD）',
+        hint: '若要使用 STG，請回覆「是」或直接告訴我環境名稱',
+      });
+    }
+
+    // extra_vars 參數邏輯：只對 ibk/cwa 的 prd 環境生效
+    const serverList = clusterDeploy ?? getServerList(
+      normalizedArgs.systemCode,
+      normalizedArgs.environment,
+      normalizedArgs.metaTest,
+    );
+
+    let goldenImageVersion = '';
+
+    // 先取 CI 單的 deploy_version JSON（customfield_13438，如 {"cwa_ap_version":"0.0.12"}）
+    let ciReleaseVersion = '';
+    if (normalizedArgs.ciTicket) {
+      try {
+        const ciFields = await jira.getIssueFields(normalizedArgs.ciTicket, [CI_FIELD_IDS.releaseVersion]);
+        ciReleaseVersion = ciFields?.[CI_FIELD_IDS.releaseVersion] ?? '';
+        if (!ciReleaseVersion) {
+          const legacyFields = await jira.getIssueFields(normalizedArgs.ciTicket, ['customfield_14705']);
+          ciReleaseVersion = legacyFields?.customfield_14705 ?? '';
+        }
+        if (!ciReleaseVersion) {
+          const summaryFields = await jira.getIssueFields(normalizedArgs.ciTicket, ['summary']);
+          const summaryMatch = summaryFields?.summary?.match(/\bfor\s+([0-9]+(?:\.[0-9]+){2,})\b/i);
+          ciReleaseVersion = summaryMatch?.[1] ?? '';
+        }
+        if (ciReleaseVersion) {
+          try {
+            const parsed = JSON.parse(ciReleaseVersion);
+            goldenImageVersion = Object.values(parsed)[0] ?? '';
+          } catch {
+            goldenImageVersion = ciReleaseVersion;
+          }
+        }
+      } catch (e) {
+        console.error(
+          `[create_cd_ticket] 無法讀取 ${normalizedArgs.ciTicket} 的 CID_release_version: ${e.message}`,
+        );
+      }
+    }
+
+    const dateStr = today().replace(/-/g, '');
+    const displayEnv =
+      normalizedArgs.metaTest ? 'prd' : (envCode === 'prd' || envCode === 'prd/dr') ? 'prd/dr' : envCode;
+    const summaryVersion = goldenImageVersion || normalizedArgs.ciTicket || '';
+    const autoSummary = `[${normalizedArgs.systemCode}][${displayEnv.toUpperCase()}] 程式上版作業申請單_${dateStr} (CD deployment with ${summaryVersion})`;
+
+    const fields = {
+      project: {key: JIRA_PROJECT_ID},
+      issuetype: {id: ISSUE_TYPE_IDS.CD},
+      duedate: today(),
+      summary: normalizedArgs.summary ?? autoSummary,
+    };
+
+    // CID_deploy_version：deploy JSON 優先，否則 release_version
+    if (normalizedArgs.ciTicket && ciReleaseVersion) {
+      fields[CD_FIELD_IDS.deployVersion] = ciReleaseVersion;
+    }
+
+    // CID_env（必填，用 id 格式）
+    if (ENV_CODES[envCode]) {
+      fields[CD_FIELD_IDS.env] = {id: ENV_CODES[envCode]};
+    }
+
+    // dept_code（由 systemCode 推導）
+    const deptStr = SYSTEM_TO_DEPT_MAP[normalizedArgs.systemCode];
+    if (deptStr && DEPT_CODES[deptStr]) {
+      fields[CD_FIELD_IDS.deptCode] = {id: DEPT_CODES[deptStr]};
+    }
+
+    fields[CD_FIELD_IDS.systemCode] = {value: normalizedArgs.systemCode};
+
+    // CID_cluster_deploy：DEV → false，STG/UAT/PRD/DR → true（Confluence Step 1）
+    fields[CD_FIELD_IDS.clusterDeploy] = {
+      id: normalizedArgs.isClusterDeploy
+        ? FIELD_OPTIONS.clusterDeploy.true
+        : FIELD_OPTIONS.clusterDeploy.false,
+    };
+
+    // CID_server_list（換行分隔）
+    fields[CD_FIELD_IDS.serverList] = serverList.map((c) => c.trim()).join('\n');
+
+    // CID_restart_only（option id 格式）
+    if (normalizedArgs.restartOnly !== undefined) {
+      fields[CD_FIELD_IDS.restartOnly] = {
+        id: normalizedArgs.restartOnly
+          ? FIELD_OPTIONS.restartOnly.true
+          : FIELD_OPTIONS.restartOnly.false,
+      };
+    }
+
+    fields[CD_FIELD_IDS.extraVars] = normalizedArgs.extraVars
+      ?? await getExtraVarsJson({serverList, ...normalizedArgs}, {jira});
+
+    // 預先生成 description（dryRun 預覽用，正式開單後也會再呼叫 updateIssue 寫入）
+    let previewDescription = generateCDDescription(ciReleaseVersion || '');
+    if (normalizedArgs.ciTicket) {
+      const releaseNotesStr = await generateReleaseNotes(
+        jira,
+        normalizedArgs.ciTicket,
+        envCode,
+        normalizedArgs.systemCode,
+      );
+      if (releaseNotesStr) previewDescription += `\n\n${releaseNotesStr}`;
+    }
+
+    if (args.dryRun)
+      return ok({
+        dryRun: true,
+        summary: fields.summary,
+        fields,
+        description: previewDescription,
+        ciTicket: normalizedArgs.ciTicket,
+      });
+
+    const issue = await jira.createIssue(fields);
+
+    // CI contains CD 關聯（Hierarchy link (WBSGantt)：outward=contains / inward=is contained in）
+    if (normalizedArgs.ciTicket) {
+      await jira.linkIssue(normalizedArgs.ciTicket, issue.key, 'Hierarchy link (WBSGantt)');
+      await notifier.notify(
+        issue.key,
+        `已建立 contains 關聯：${normalizedArgs.ciTicket} contains ${issue.key}`,
+      );
+    }
+
+    // Confluence Step 3：Web Link（對應 LBPRJ 版本頁）
+    await handleWeblink(jira, issue, notifier, normalizedArgs);
+
+    // 更新 description 表格，因為 cid jira worker 會將 init 的表格回朔
+    if (issue.key) {
+      // version = ciReleaseVersion（CI golden image version，例如 0.0.11）
+      let cdDescription = generateCDDescription(ciReleaseVersion || '');
+
+      // 生成 release notes Bitbucket compare URL
+      if (normalizedArgs.ciTicket) {
+        const releaseNotesStr = await generateReleaseNotes(
+          jira,
+          normalizedArgs.ciTicket,
+          envCode,
+          normalizedArgs.systemCode,
+        );
+        if (releaseNotesStr) {
+          cdDescription += `\n\n${releaseNotesStr}`;
+        }
+      }
+      if (normalizedArgs.description) {
+        cdDescription += `\n\n${normalizedArgs.description}`;
+      }
+
+      await jira.updateIssue(issue.key, {
+        [CD_FIELD_IDS.description]: cdDescription,
+      });
+    }
+
+    await notifier.notify(
+      issue.key,
+      `CD Deploy 單已建立。系統: ${args.systemCode}, 環境: ${args.environment}, Cluster: ${args.clusterDeploy}`,
+    );
+    return ok({
+      issueKey: issue.key,
+      issueId: issue.id,
+      url: `${process.env.JIRA_BASE_URL}/browse/${issue.key}`,
+      type: 'CD Deploy',
+      system: normalizedArgs.systemCode,
+      environment: normalizedArgs.environment,
+    });
+  } catch (err) {
+    return error(`無法建立 CD 單: ${err.message}`);
+  }
+}
+
+/**
+ * 計算下一個 Golden Image Release 版號
+ */
+export async function getExtraVarsJson(args, {jira}) {
+  try {
+    const {serverList, module} = args;
+
+    let extraVarsJson = null;
+    // ① 從 CI 關聯的 Library 票推導模組（只含本次實際部署的模組）
+    let modules = null;
+
+    if (args.ciTicket) {
+      try {
+        const ciFields = await jira.getIssueFields(args.ciTicket, ['issuelinks']);
+        const issueLinks = ciFields?.issuelinks ?? [];
+        // 建立反查表：child module ID → module name（僅限本系統）
+        const childIdToName = Object.fromEntries(
+          Object.entries(LIBRARY_MODULE_IDS[args.systemCode] ?? {}).map(([name, id]) => [id, name]),
+        );
+
+        const detectedModules = [];
+        for (const link of issueLinks) {
+          const linked = link.inwardIssue ?? link.outwardIssue;
+          if (linked?.fields?.issuetype?.name !== 'Library') continue;
+          try {
+            const libFields = await jira.getIssueFields(linked.key, ['customfield_13702']);
+            const childId = libFields?.['customfield_13702']?.child?.id;
+            if (childId && childIdToName[childId]) {
+              detectedModules.push(childIdToName[childId]);
+            }
+          } catch (_) {
+            /* skip this library */
+          }
+        }
+        if (detectedModules.length > 0) modules = [...new Set(detectedModules)];
+      } catch (_) {
+        /* fall through */
+      }
+    }
+
+    // ② fallback：CI 無關聯 Library 時使用全系統模組
+    if (!modules) modules = SYSTEM_MODULES[args.systemCode] ?? [];
+
+    const sysLower = args.systemCode.toLowerCase();
+
+    const envServerList = SERVERS[args.systemCode]?.[args.environment];
+
+    // 只對 cluster 是 flat array 的系統自動生成（EIB/EVT 結構較複雜，另外處理）
+    const flatClusters = Array.isArray(envServerList) ? serverList : null;
+
+    if (flatClusters) {
+      const serverMap = Object.fromEntries(flatClusters.map((s) => [s, true]));
+      const vars = Object.fromEntries(
+        modules.map((mod) => [`${sysLower}_${mod}_installation`, serverMap]),
+      );
+      extraVarsJson = JSON.stringify(vars);
+    } else {
+      // EVT & EIB 有分 web was 機器
+      const serverType = modules.map((module) => SERVER_MODULE_MAP[module]);
+      const vars = Object.fromEntries(
+        modules.map((mod, i) => {
+          const servers = envServerList[serverType[i]] ?? [];
+          return [
+            `${sysLower}_${mod}_installation`,
+            Object.fromEntries(servers.map((s) => [s, true])),
+          ];
+        }),
+      );
+      extraVarsJson = JSON.stringify(vars);
+    }
+    return extraVarsJson;
+  } catch (e) {
+  }
+} // end getExtraVarsJson
+
+// ── Private helpers ───────────────────────────────────────────────
+
+function generateCDDescription(version) {
+  return `||一般資訊作業申請單||參考符號 ◼️◻️||
+|*上版版本號*|${version}|
+|*相關電子單號*|參照連結|
+|*Purpose*|參照連結|
+|*防毒掃描 (需檢附 CI 單連結)*|不適用|
+|*測試報告 (檢附前一環境 CD 單驗證結果並附上連結)*|參照連結|
+|*SIT 測試涵蓋檢核表 (UAT 申請時需確認)*|參照連結|
+|*UAT 黑箱掃描報告 (PRD 申請時需檢附，需白箱則請附上報告連結)*|不適用|
+|*操作步驟說明*|Ansible 程式上版。|
+|*簽核流程*|STG : 單位 Reviewer\\\\UAT : 單位部長 > INFRA_資管部長\\\\PRD/DR : 單位部長 > 單位處長 > INFRA_資管部長|`;
+}
+
+/**
+ * 從 Library Jenkins build comment 提取 CID_version 與 moduleKey
+ * comment format: "Release version [ch014.ibk.ibk-release-v1.5.2.0-0.0.1|url] pass in ..."
+ * @returns {{ CID_version: string|null, moduleKey: string|null }}
+ */
+function parseLibraryInfo(comments = []) {
+  for (const comment of comments) {
+    const body = comment.body ?? String(comment);
+    const bracketMatch = body.match(/Release version \[([^\]]+)/);
+    if (!bracketMatch) continue;
+    const text = bracketMatch[1].split('|')[0];
+    const releaseIdx = text.indexOf('-release-');
+    if (releaseIdx === -1) continue;
+    const prefix = text.slice(0, releaseIdx);
+    const suffix = text.slice(releaseIdx + '-release-'.length);
+    const moduleKey = prefix.split('.').pop();
+    const versionMatch = suffix.match(/.*-(\d+\.\d+\.\d+)$/);
+    const CID_version = versionMatch ? versionMatch[1] : null;
+    if (!moduleKey || !CID_version) continue;
+    return {CID_version, moduleKey};
+  }
+  return {CID_version: null, moduleKey: null};
+}
+
+function normalizeLibraryCidVersion(branch, parsedComment) {
+  if (!branch || !parsedComment.CID_version) return '';
+  const normalizedBranch = branch.replace(/\//g, '-');
+  return normalizedBranch.endsWith(`-${parsedComment.CID_version}`)
+    ? normalizedBranch
+    : `${normalizedBranch}-${parsedComment.CID_version}`;
+}
+
+function inferModuleFromBranch(branch, systemCode) {
+  const normalized = branch.replace(/^release[\/\-]/, '');
+  const prefix = `${systemCode}_`;
+  if (!normalized.startsWith(prefix)) return '';
+  const rest = normalized.slice(prefix.length);
+  return rest.split('_')[0] ?? '';
+}
+
+function getLibraryVersionName(branch, systemCode, module) {
+  const normalized = branch.startsWith('release-')
+    ? branch.replace(/^release-/, '').replace(/-\d+\.\d+\.\d+$/, '')
+    : branch.replace(/^release\//, '');
+  const prefix = `${systemCode}_`;
+  if (systemCode === SYSTEM_CODES.CWA && branch.startsWith('release-')) return normalized;
+  if (!normalized.startsWith(prefix)) return normalized.replace(/^v/, '');
+
+  const rest = normalized.slice(prefix.length);
+  const modulePrefix = `${module}_`;
+  if (!rest.startsWith(modulePrefix)) return rest;
+  const version = rest.slice(modulePrefix.length);
+  return module === systemCode.toLowerCase() ? rest : version;
+}
+
+async function findPrevLibraryDeployedToEnv(jira, branchBase, cidVersion, env, systemCode) {
+  try {
+    // ex: cwa CID-1714 library release-v1.5.2.0-0.0.3
+    // STG: sourceBranch=release-v1.5.2.0-0.0.3, targetBranch=release-v1.5.2.0-0.0.2
+    // UAT: sourceBranch=release-v1.5.2.0-0.0.3, targetBranch=release-v1.5.1.1
+
+    const envLower = env.toLowerCase();
+    const parts = cidVersion.split('.').map(Number);
+    if (parts.length < 3) return null;
+
+    // PRD 永遠找最後一個 release/ 分支 → 回傳 null，由上層 fallback 到 getBitbucketTags
+    if (envLower === 'prd' || envLower === 'dr' || envLower === 'prd/dr') {
+      return null;
+    }
+
+    // STG: 只有第一次（serial = 0.0.1）才找前一個 release/；其他找上一個 Library CID_version
+    if (envLower === 'stg' || envLower === 'dev') {
+      if (parts[2] <= 1) return null; // 第一次 → fallback to release/ tag
+      const prevSerial = `${parts[0]}.${parts[1]}.${parts[2] - 1}`;
+      // 驗證上一個 serial 的 Library 是否已經有同環境 CD 完成。
+      const searchResults = await jira.searchIssues(
+        `project = CID AND issuetype = Library AND "CID_branch" ~ "${branchBase}" ORDER BY created DESC`,
+        ['comment', 'issuelinks'],
+      );
+      for (const lib of searchResults) {
+        const {CID_version: libVersion} = parseLibraryInfo(lib.fields?.comment?.comments ?? []);
+        if (libVersion !== prevSerial) continue;
+        for (const link of lib.fields?.issuelinks ?? []) {
+          const ci = link.inwardIssue ?? link.outwardIssue;
+          if (ci?.fields?.issuetype?.name !== 'CI') continue;
+          try {
+            const ciFields = await jira.getIssueFields(ci.key, ['issuelinks']);
+            for (const cdLink of ciFields?.issuelinks ?? []) {
+              const cd = cdLink.inwardIssue ?? cdLink.outwardIssue;
+              if (
+                cd?.fields?.issuetype?.name === 'CD' &&
+                (cd.fields?.summary ?? '').includes(`[${systemCode}][${envLower.toUpperCase()}]`) &&
+                cd.fields?.status?.name?.toLowerCase() === 'done'
+              ) {
+                return prevSerial;
+              }
+            }
+          } catch (_) {
+            /* skip */
+          }
+        }
+      }
+      return null;
+    }
+
+    // UAT: 往前找，直到找到有 UAT CD status=Done 的版本
+    if (envLower === 'uat') {
+      if (parts[2] <= 1) return null; // 第一版 → fallback to release/ tag
+      // 一次撈同 branchBase 下的所有 Library
+      const searchResults = await jira.searchIssues(
+        `project = CID AND issuetype = Library AND "CID_branch" ~ "${branchBase}" ORDER BY created DESC`,
+        ['comment', 'issuelinks'],
+      );
+      // 從 cidVersion - 1 逐步往前找
+      for (let i = parts[2] - 1; i >= 1; i--) {
+        const prevSerial = `${parts[0]}.${parts[1]}.${i}`;
+        for (const lib of searchResults) {
+          const {CID_version: libVersion} = parseLibraryInfo(lib.fields?.comment?.comments ?? []);
+          if (libVersion !== prevSerial) continue;
+          // 找 Library → CI → CD（UAT, status = Done）
+          for (const link of lib.fields?.issuelinks ?? []) {
+            const ci = link.inwardIssue ?? link.outwardIssue;
+            if (ci?.fields?.issuetype?.name !== 'CI') continue;
+            try {
+              const ciFields = await jira.getIssueFields(ci.key, ['issuelinks']);
+              for (const cdLink of ciFields?.issuelinks ?? []) {
+                const cd = cdLink.inwardIssue ?? cdLink.outwardIssue;
+                if (
+                  cd?.fields?.issuetype?.name === 'CD' &&
+                  (cd.fields?.summary ?? '').includes(`[${systemCode}][UAT]`) &&
+                  cd.fields?.status?.name?.toLowerCase() === 'done'
+                ) {
+                  return prevSerial;
+                }
+              }
+            } catch (_) {
+              /* skip */
+            }
+          }
+        }
+      }
+      return null; // 都找不到 → fallback to release/ tag
+    }
+
+    return null;
+  } catch (_) {
+    return null;
+  }
+}
+
+/**
+ * 根據 CI 關聯的 Library 單生成 release notes，格式為 "模組: Bitbucket compare URL"
+ * @param jira
+ * @param ciKey
+ * @param env
+ * @param systemCode
+ * @returns {Promise<string|string>}
+ */
+async function generateReleaseNotes(jira, ciKey, env, systemCode) {
+  try {
+    const ciFields = await jira.getIssueFields(ciKey, ['issuelinks']);
+    const notes = [];
+
+    for (const link of ciFields?.issuelinks ?? []) {
+      const linked = link.inwardIssue ?? link.outwardIssue;
+      if (linked?.fields?.issuetype?.name !== 'Library') continue;
+      try {
+        const libFields = await jira.getIssueFields(linked.key, [
+          'customfield_13431',
+          'customfield_13702',
+          'customfield_14705',
+          'comment',
+        ]);
+        const branch = libFields?.['customfield_13431'] ?? '';
+        const child = libFields?.['customfield_13702']?.child;
+        const childIdToName = Object.fromEntries(
+          Object.entries(LIBRARY_MODULE_IDS[systemCode] ?? {}).map(([name, id]) => [id, name]),
+        );
+        const parsedComment = parseLibraryInfo(libFields?.comment?.comments ?? []);
+        const module =
+          child?.value ??
+          childIdToName[child?.id] ??
+          parsedComment.moduleKey ??
+          inferModuleFromBranch(branch, systemCode);
+        const cidVersion = libFields?.['customfield_14705'] ?? normalizeLibraryCidVersion(
+          branch,
+          parsedComment,
+        );
+
+        // library build 流水號 0.0.1
+        const cidVersionSerialNum = cidVersion.split('-').pop();
+
+        if (!cidVersionSerialNum || !module) continue;
+        const repoName = MODULE_MAP[module];
+        if (!repoName) continue;
+        const repoMeta = REPO_MAPS[repoName];
+        if (!repoMeta) continue;
+        const label = REPO_LABEL_MAP[repoName];
+        const branchWithDashes = branch.replace(/\//g, '-');
+
+        // source branch 直接抓 lib CID_version customfield_14705
+        const sourceBranch = `ci/${cidVersion}`;
+
+        const prevVersion = await findPrevLibraryDeployedToEnv(
+          jira,
+          branch,
+          cidVersionSerialNum,
+          env,
+          systemCode,
+        );
+
+        // let targetBranch = await findPrevLibraryDeployedToEnv(jira, branch, cidVersionSerialNum, env, systemCode)
+        let targetBranch;
+
+        if (prevVersion) {
+          targetBranch = `ci/${branchWithDashes}-${prevVersion}`;
+        } else {
+          // 找最新的 release/ 開頭 branch（非 tag）
+          const branches = await jira.getBitbucketBranches(repoMeta.project, repoName, {
+            filterValue: 'release/',
+          });
+          if (!branches?.length) continue;
+          targetBranch = branches[0].displayId;
+        }
+        const baseUrl = process.env.BITBUCKET_URL || 'https://bitbucket.example.com';
+        const compareUrl = `${baseUrl}/projects/${repoMeta.project}/repos/${repoName}/compare/diff?sourceBranch=${sourceBranch.replace(/\//g, '%2F')}&targetBranch=${targetBranch.replace(/\//g, '%2F')}&targetRepoId=${repoMeta.repoId}`;
+        notes.push(`${label}: ${compareUrl}`);
+      } catch (_) {
+        /* skip */
+      }
+    }
+    return notes.length ? `release notes:\n${notes.join('\n')}` : '';
+  } catch (_) {
+    return '';
+  }
+}
+
+/**
+ * 自動從 CI 單的 relates Library 單取 CID_branch，比對 LBPRJ 版本頁，每個 Library 單加一筆 Web Link
+ */
+async function handleWeblink(jira, issue, notifier, args) {
+  if (args.ciTicket) {
+    try {
+      const ciFields = await jira.getIssueFields(args.ciTicket, ['issuelinks']);
+      const issueLinks = ciFields?.issuelinks ?? [];
+      // 找出所有 Library 類型的關聯單（inward 或 outward 都算）
+      const libraryKeys = [];
+      for (const link of issueLinks) {
+        const linked = link.outwardIssue ?? link.inwardIssue;
+        if (linked?.fields?.issuetype?.name === 'Library') {
+          libraryKeys.push(linked.key);
+        }
+      }
+
+      // CI 單有找到 library relates
+      if (libraryKeys.length > 0) {
+        for (const libKey of libraryKeys) {
+          try {
+            // 同時取 branch 與 comment（comment 用於解析 CID_version 去除後綴）
+            const libFields = await jira.getIssueFields(libKey, [
+              'customfield_13431',
+              'customfield_13702',
+              'comment',
+            ]);
+            const branch = libFields?.['customfield_13431'] ?? '';
+            const child = libFields?.['customfield_13702']?.child;
+            const childIdToName = Object.fromEntries(
+              Object.entries(LIBRARY_MODULE_IDS[args.systemCode] ?? {}).map(([name, id]) => [id, name]),
+            );
+            const parsedComment = parseLibraryInfo(libFields?.comment?.comments ?? []);
+            const module =
+              child?.value ??
+              childIdToName[child?.id] ??
+              parsedComment.moduleKey ??
+              inferModuleFromBranch(branch, args.systemCode);
+
+            // 去掉 'release/' 或 'release-' 前綴取得版本名稱
+            const versionName = getLibraryVersionName(branch, args.systemCode, module);
+            const moduleName = args.systemCode === SYSTEM_CODES.CWA
+              ? versionName
+              : getModuleName(args.systemCode, module, versionName);
+            // 只取 unreleased、名稱含 systemCode 的版本（對應 UI: status=unreleased&contains=systemCode）
+            const versionId = await jira.getProjectVersions('LBPRJ', {
+              name: moduleName,
+            });
+
+            if (versionId) {
+              const versionUrl = `${process.env.JIRA_BASE_URL}/projects/LBPRJ/versions/${versionId}`;
+              await jira.addRemoteLink(issue.key, versionUrl, moduleName);
+              await notifier.notify(issue.key, `已附上版本 Web Link：${moduleName}（${libKey}）`);
+            } else {
+              console.error(
+                `[create_cd_ticket] 找不到 Release Version unreleased 的版本 "${moduleName}"（來自 ${libKey}"，有可能已經 release 了）`,
+              );
+            }
+          } catch (e) {
+            console.error(`[create_cd_ticket] 處理 ${libKey} remote link 失敗: ${e.message}`);
+          }
+        }
+      }
+    } catch (e) {
+      console.error(`[create_cd_ticket] 取得 CI 關聯 Library 單失敗: ${e.message}`);
+    }
+  }
+}