@jira-deploy/core 1.0.0

package/tools/ci.js

@@ -0,0 +1,204 @@
+/**
+ * CI Golden Image 相關 tools
+ *   - create_ci_ticket
+ */
+import {error, ok, today} from './helpers.js';
+import {
+  CI_FIELD_IDS,
+  DEPT_CODES,
+  ENV_CODES,
+  FIELD_OPTIONS,
+  ISSUE_TYPE_IDS,
+  JIRA_PROJECT_ID,
+  REPO_MAPS,
+  SYSTEM_CODES,
+  SYSTEM_MODULES,
+  SYSTEM_TO_CI_REPO_MAP,
+  SYSTEM_TO_DEPT_MAP,
+} from '../constants/index.js';
+
+// ── Schema definitions ───────────────────────────────────────────
+export function getCIToolDefinitions() {
+  return [
+    {
+      name: 'create_ci_ticket',
+      description: '建立 CI Release 上版單。專用工具，提前驗證必填欄位。',
+      inputSchema: {
+        type: 'object',
+        required: ['systemCode'],
+        properties: {
+          systemCode: {
+            type: 'string',
+            enum: Object.values(SYSTEM_CODES),
+            description: '系統代碼',
+          },
+          branch: {
+            type: 'string',
+            description: '(選填) Git 分支名稱，預設 master',
+          },
+          modules: {
+            type: 'string',
+            description:
+              '(選填) 模組名稱，例如 ibk、cwa、ssr（對應 SYSTEM_MODULES[systemCode])，可能同時多個模組，預設為 SYSTEM_MODULES[systemCode] 的全部模組',
+          },
+          environment: {
+            type: 'string',
+            enum: Object.keys(ENV_CODES),
+            description: '(選填) 部署環境，預設 stg',
+          },
+          summary: {
+            type: 'string',
+            description:
+              '（選填）自訂 Ticket 標題，不填則自動生成，格式：[IBK][CI] IBK & WEALTH & SSR & A11Y for 0.0.1',
+          },
+          goldenImageVersion: {
+            type: 'string',
+            description:
+              'Golden Image 版本號，例如 0.0.1（用於 summary：[IBK][CI] IBK & WEALTH for 0.0.1）',
+          },
+          antiScanRequired: {
+            type: 'boolean',
+            description: '是否需要反掃描檢測（選填，預設 true）',
+          },
+          relatesTo: {
+            type: 'array',
+            items: {type: 'string'},
+            description:
+              '關聯的 Library 單 issue key，有可能多個，例如 CID-1178 CID-1182（建立後自動加上 relates to link）',
+          },
+          dryRun: {
+            type: 'boolean',
+            description: '(選填) 預覽模式，不實際建立 Jira 單，回傳會送出的 payload',
+          },
+        },
+      },
+    },
+  ];
+}
+
+/**
+ * 建立 CI Golden Image 上版單
+ */
+export async function handleCreateCITicket(args, {jira, notifier}) {
+  try {
+    const branch = args.branch || 'master';
+    const envCode = (args.environment ?? 'stg').toLowerCase();
+    // Summary 格式對齊 Confluence：[IBK][CI] Wealth & SSR & IBK & A11y for 0.0.1
+    const modules = Array.isArray(args.modules)
+      ? args.modules
+      : typeof args.modules === 'string'
+        ? args.modules.split(',').map((module) => module.trim()).filter(Boolean)
+        : SYSTEM_MODULES[args.systemCode];
+    const modulesStr = modules.map((m) => m.toUpperCase()).join(' & ');
+
+    const versionSuffix = args.goldenImageVersion ? ` for ${args.goldenImageVersion}` : '';
+    const autoSummary = args.summary ?? `[${args.systemCode}][CI] ${modulesStr}${versionSuffix}`;
+
+    const fields = {
+      project: {key: JIRA_PROJECT_ID},
+      issuetype: {id: ISSUE_TYPE_IDS.CI},
+      summary: autoSummary,
+      duedate: today(),
+    };
+
+    // systemCode
+    if (CI_FIELD_IDS.systemCode) {
+      fields[CI_FIELD_IDS.systemCode] = {value: args.systemCode};
+    }
+    // env (必填)
+    if (CI_FIELD_IDS.env && ENV_CODES[envCode]) {
+      fields[CI_FIELD_IDS.env] = {id: ENV_CODES[envCode]};
+    }
+    // dept_code (必填，由 systemCode 推導)
+    const deptStr = SYSTEM_TO_DEPT_MAP[args.systemCode];
+    if (CI_FIELD_IDS.deptCode && deptStr && DEPT_CODES[deptStr]) {
+      fields[CI_FIELD_IDS.deptCode] = {id: DEPT_CODES[deptStr]};
+    }
+    // system_module (必填，預設 assembly)
+    if (CI_FIELD_IDS.systemModule) {
+      fields[CI_FIELD_IDS.systemModule] = {id: FIELD_OPTIONS.systemModule.assembly};
+    }
+    // git branch → customfield_13431 (14702 不在 CI screen)
+    if (CI_FIELD_IDS.gitBranch && branch) {
+      fields[CI_FIELD_IDS.gitBranch] = branch;
+    }
+
+    // antiScan
+    fields[CI_FIELD_IDS.antiScanRequired] = {
+      id: args.antiScanRequired === false
+        ? FIELD_OPTIONS.antiScan.false
+        : FIELD_OPTIONS.antiScan.true,
+    };
+
+    if (args.dryRun)
+      return ok({dryRun: true, summary: autoSummary, fields, relatesTo: args.relatesTo ?? []});
+
+    const issue = await jira.createIssue(fields);
+
+    // 自動 link 到 Library 單
+    const relatesTo = Array.isArray(args.relatesTo) ? args.relatesTo : args.relatesTo ? [args.relatesTo] : [];
+    if (relatesTo.length > 0) {
+      for (const key of relatesTo) {
+        await jira.linkIssue(issue.key, key, 'Relates');
+        await notifier.notify(issue.key, `已關聯 Library 單 ${key}`);
+      }
+    }
+
+    await notifier.notify(
+      issue.key,
+      `CI Release 單已建立。系統: ${args.systemCode}, 分支: ${branch}, 環境: ${envCode}`,
+    );
+    return ok({
+      issueKey: issue.key,
+      issueId: issue.id,
+      url: `${process.env.JIRA_BASE_URL}/browse/${issue.key}`,
+      type: 'CI Release',
+      system: args.systemCode,
+      ...(relatesTo.length > 0 && {relatesTo}),
+    });
+  } catch (err) {
+    return error(`無法建立 CI 單: ${err.message}`);
+  }
+}
+
+/**
+ * 計算下一個 Golden Image Release 版號
+ */
+export async function handleGetNextCIVersion(args, {jira}) {
+  const {systemCode, branch} = args;
+
+  const repoName = SYSTEM_TO_CI_REPO_MAP[systemCode];
+  if (!repoName) {
+    return error(`找不到系統 "${systemCode}" 的 Golden Image repo，請確認 SYSTEM_TO_CI_REPO_MAP`);
+  }
+  const repoMeta = REPO_MAPS[repoName];
+  if (!repoMeta) {
+    return error(`找不到 repo "${repoName}" 的 Bitbucket 設定`);
+  }
+
+  let xmlVersion = null;
+  try {
+    const xmlContent = await jira.getBitbucketFileContent(
+      repoMeta.project,
+      repoName,
+      'pom.xml',
+      branch,
+    );
+    // 移除 <parent> 區塊，避免誤抓 parent 版號
+    const contentWithoutParent = xmlContent.replace(/<parent>[\s\S]*?<\/parent>/m, '');
+    const match = contentWithoutParent.match(/<version>(\d+\.\d+\.\d+)(?:-[^<]+)?<\/version>/);
+    if (!match) {
+      return error(`專案 (${repoName})，pom.xml 中找不到 <version> 標籤（branch: ${branch}）`);
+    }
+    xmlVersion = match[1].trim();
+  } catch (err) {
+    return error(`無法取得 pom.xml：${err.message}`);
+  }
+
+  return ok({
+    systemCode,
+    branch,
+    summaryVersion: xmlVersion,
+    message: `✅ 下一個版本：${xmlVersion}（XML 現版：${xmlVersion}）`,
+  });
+}

package/tools/ci.test.js

@@ -0,0 +1,154 @@
+/**
+ * handleGetNextCIVersion 單元測試
+ * 執行：node --test src/tools/ci.test.js
+ */
+import {test, mock} from 'node:test';
+import assert from 'node:assert/strict';
+
+// helpers.js 內部 import '../constants'（directory import）在 ESM 直接執行時不支援，
+// 用 mock.module 提前替換，避免 ERR_UNSUPPORTED_DIR_IMPORT。
+await mock.module('./helpers.js', {
+  namedExports: {
+    ok: (data) => ({content: [{type: 'text', text: JSON.stringify(data, null, 2)}]}),
+    error: (msg) => ({content: [{type: 'text', text: `❌ 錯誤: ${msg}`}]}),
+    today: () => new Date().toISOString().slice(0, 10),
+  },
+});
+
+const {handleGetNextCIVersion, handleCreateCITicket} = await import('./ci.js');
+
+// ── Mock helpers ─────────────────────────────────────────────────
+
+function makePom(version) {
+  return `<project>
+    <parent><groupId>com.example</groupId><artifactId>parent</artifactId><version>0.0.1</version></parent>
+    <artifactId>assembly</artifactId>
+    <version>${version}-SNAPSHOT</version>
+  </project>`;
+}
+
+function makeJira(pomContent) {
+  return {getBitbucketFileContent: async () => pomContent};
+}
+
+function makeJiraThrows(msg) {
+  return {
+    getBitbucketFileContent: async () => {
+      throw new Error(msg);
+    },
+  };
+}
+
+function parseOk(result) {
+  return JSON.parse(result.content[0].text);
+}
+
+// ── Tests ────────────────────────────────────────────────────────
+
+test('IBK - 正常解析 pom.xml 版本號', async () => {
+  const result = await handleGetNextCIVersion(
+    {systemCode: 'IBK', branch: 'master'},
+    {jira: makeJira(makePom('0.0.12'))},
+  );
+  const data = parseOk(result);
+  assert.equal(data.systemCode, 'IBK');
+  assert.equal(data.summaryVersion, '0.0.12');
+  assert.equal(data.branch, 'master');
+});
+
+test('CWA - 正常解析 pom.xml 版本號', async () => {
+  const result = await handleGetNextCIVersion(
+    {systemCode: 'CWA', branch: 'master'},
+    {jira: makeJira(makePom('1.2.3'))},
+  );
+  assert.equal(parseOk(result).summaryVersion, '1.2.3');
+});
+
+test('systemCode 不存在 SYSTEM_TO_CI_REPO_MAP → 回傳 error', async () => {
+  const result = await handleGetNextCIVersion(
+    {systemCode: 'NPM', branch: 'master'},
+    {jira: makeJira('')},
+  );
+  const text = result.content[0].text;
+  assert.match(text, /❌/);
+  assert.match(text, /SYSTEM_TO_CI_REPO_MAP/);
+});
+
+test('pom.xml 沒有 <version> 標籤 → 回傳 error', async () => {
+  const result = await handleGetNextCIVersion(
+    {systemCode: 'IBK', branch: 'master'},
+    {jira: makeJira('<project><name>no-version</name></project>')},
+  );
+  const text = result.content[0].text;
+  assert.match(text, /❌/);
+  assert.match(text, /pom\.xml/);
+});
+
+test('Bitbucket 拋例外 → 回傳 error', async () => {
+  const result = await handleGetNextCIVersion(
+    {systemCode: 'IBK', branch: 'master'},
+    {jira: makeJiraThrows('network timeout')},
+  );
+  const text = result.content[0].text;
+  assert.match(text, /❌/);
+  assert.match(text, /network timeout/);
+});
+
+// ── handleCreateCITicket tests ────────────────────────────────────
+
+function makeFullJira(pomVersion = '0.0.12') {
+  const linked = [];
+  return {
+    getBitbucketFileContent: async () => `<project>
+      <parent><version>0.0.1</version></parent>
+      <version>${pomVersion}-SNAPSHOT</version>
+    </project>`,
+    createIssue: async () => ({id: 'TEST-ID', key: 'CID-TEST'}),
+    linkIssue: async (from, to, type) => {
+      linked.push({from, to, type});
+    },
+    _linked: linked,
+  };
+}
+
+function makeNotifier() {
+  const logs = [];
+  return {
+    notify: async (key, msg) => {
+      logs.push(msg);
+    },
+    _logs: logs,
+  };
+}
+
+test('create_ci_ticket - relatesTo 單一 key 呼叫一次 linkIssue', async () => {
+  const jira = makeFullJira();
+  const notifier = makeNotifier();
+  const result = await handleCreateCITicket(
+    {systemCode: 'IBK', relatesTo: ['CID-1708']},
+    {jira, notifier},
+  );
+  const data = parseOk(result);
+  assert.equal(data.issueKey, 'CID-TEST');
+  assert.equal(jira._linked.length, 1);
+  assert.equal(jira._linked[0].to, 'CID-1708');
+});
+
+test('create_ci_ticket - relatesTo 多個 key 各呼叫一次 linkIssue', async () => {
+  const jira = makeFullJira();
+  const notifier = makeNotifier();
+  await handleCreateCITicket(
+    {systemCode: 'IBK', relatesTo: ['CID-1178', 'CID-1182']},
+    {jira, notifier},
+  );
+  assert.equal(jira._linked.length, 2);
+  assert.equal(jira._linked[0].to, 'CID-1178');
+  assert.equal(jira._linked[1].to, 'CID-1182');
+});
+
+test('create_ci_ticket - 無 relatesTo 不呼叫 linkIssue', async () => {
+  const jira = makeFullJira();
+  const notifier = makeNotifier();
+  await handleCreateCITicket({systemCode: 'IBK'}, {jira, notifier});
+  assert.equal(jira._linked.length, 0);
+});

package/tools/grayrelease.js

@@ -0,0 +1,296 @@
+/**
+ * Gray Release 相關 tools
+ *   - create_grayrelease_ticket
+ */
+import {
+  SYSTEM_CODES,
+  ENV_CODES,
+  SUPPORTED_ENVS,
+  DEPT_CODES,
+  GRAY_RELEASE_MODULE_IDS,
+  ISSUE_TYPE_IDS,
+  JIRA_PROJECT_ID,
+  GRAY_RELEASE_FIELD_IDS,
+  SYSTEM_TO_DEPT_MAP,
+  FIELD_OPTIONS,
+  SIGN_VALUES,
+  NOTES_TEMPLATES,
+  JIRA_DEFAULTS,
+} from '../constants/index.js';
+import {error, ok, today, getServerList} from './helpers.js';
+
+// ── Schema definitions ───────────────────────────────────────────
+export function getGrayReleaseToolDefinitions() {
+  return [
+    {
+      name: 'create_grayrelease_ticket',
+      description:
+        '建立 GrayRelease 灰度上版單。適用於單一 module 開發與測試佈署，不支援 prd/dr 環境。',
+      inputSchema: {
+        type: 'object',
+        required: ['systemCode', 'module', 'gitBranch'],
+        properties: {
+          systemCode: {
+            type: 'string',
+            enum: Object.values(SYSTEM_CODES),
+            description: '系統代碼',
+          },
+          module: {
+            type: 'string',
+            description: '模組名稱，例如 ibk、ssr、wealth、a11y、cwa、web、web_cust、web_agnt',
+          },
+          gitBranch: {
+            type: 'string',
+            description:
+              'Git branch 名稱，例如 feature/my-feature。/ 會自動替換為 - 作為 grayReleaseVersion',
+          },
+          environment: {
+            type: 'string',
+            enum: SUPPORTED_ENVS.grayRelease,
+            description: '部署環境（只允許 dev / stg / uat，不支援 prd/dr）',
+          },
+          jenkinsBranch: {
+            type: 'string',
+            description: 'Jenkins branch（選填，預設 master）',
+          },
+          dryRun: {
+            type: 'boolean',
+            description: '(選填) 預覽模式，不實際建立 Jira 單，回傳會送出的 payload',
+          },
+        },
+      },
+    },
+    {
+      name: 'link_stg_grayrelease',
+      description:
+        '將 STG 灰度單關聯（relates to）到已建立的 UAT 灰度單。' +
+        '通常在 create_grayrelease_ticket 建立 UAT 單後，由使用者確認 suggest_link 的建議時呼叫。',
+      inputSchema: {
+        type: 'object',
+        required: ['uatKey', 'stgKeys'],
+        properties: {
+          uatKey: {
+            type: 'string',
+            description: 'UAT 灰度單的 issue key，例如 CID-9999',
+          },
+          stgKeys: {
+            type: 'array',
+            items: {type: 'string'},
+            description: '要關聯的 STG 灰度單 key 陣列，例如 ["CID-1234", "CID-1235"]',
+          },
+        },
+      },
+    },
+  ];
+}
+
+// ── Handler ──────────────────────────────────────────────────────
+
+/**
+ * 搜尋相同 module/gitBranch 的 STG 灰度單，並排除已被任何 UAT 灰度單 relates 的。
+ * @param {string} gitBranch
+ * @param {string} moduleId  - GRAY_RELEASE_MODULE_IDS 的值（Jira field option id）
+ * @param {object} jira
+ * @returns {Promise<{key:string, summary:string}[]>}
+ */
+async function findUnlinkedStgGrayReleases(gitBranch, moduleId, jira) {
+  const STG_ENV_ID = '14356';
+  const GR_ISSUE_TYPE = '12601';
+  const jql = [
+    'project = CID',
+    `issuetype = ${GR_ISSUE_TYPE}`,
+    `cf[13436] = ${STG_ENV_ID}`,
+    `cf[13431] = "${gitBranch.replace(/"/g, '\\"')}"`,
+    `cf[13444] = ${moduleId}`,
+    'ORDER BY created DESC',
+  ].join(' AND ');
+
+  let candidates;
+  try {
+    candidates = await jira.searchIssues(jql, ['summary', 'issuelinks'], 20);
+  } catch {
+    return []; // 搜尋失敗時靜默，不影響主流程
+  }
+
+  return candidates
+    .filter((issue) => {
+      const links = issue.fields?.issuelinks ?? [];
+      // 排除已有任何 GrayRelease UAT 關聯的票
+      return !links.some((link) => {
+        const linked = link.inwardIssue ?? link.outwardIssue;
+        return linked?.fields?.issuetype?.id === GR_ISSUE_TYPE;
+      });
+    })
+    .map((issue) => ({key: issue.key, summary: issue.fields?.summary ?? ''}));
+}
+
+/**
+ * 建立 Gray Release 上版單
+ */
+export async function handleCreateGrayReleaseTicket(args, {jira, notifier}) {
+  try {
+    const normalizedArgs = {
+      ...args,
+      module: args.module ?? args.systemCode?.toLowerCase(),
+      gitBranch: args.gitBranch ?? args.grayVersion,
+      environment: args.environment?.toLowerCase(),
+    };
+
+    // 未指定環境時，詢問使用者是否使用 STG
+    if (!normalizedArgs.environment) {
+      return ok({
+        confirm_environment: true,
+        message: '請問要部署到 STG 環境嗎？（STG / UAT / DEV）',
+        hint: '若要使用 STG，請回覆「是」或直接告訴我環境名稱',
+      });
+    }
+
+    const moduleId = GRAY_RELEASE_MODULE_IDS[normalizedArgs.module];
+    if (!moduleId) {
+      if (args.module || args.gitBranch) {
+        return error(
+          `找不到模組 "${normalizedArgs.module}" 的 GrayRelease ID，請確認模組名稱（支援: ${Object.keys(GRAY_RELEASE_MODULE_IDS).join(', ')}）`,
+        );
+      }
+    }
+
+    const envCode = normalizedArgs.environment;
+    if (!SUPPORTED_ENVS.grayRelease.includes(envCode)) {
+      return error(
+        `GrayRelease 不支援環境 "${envCode}"，僅支援: ${SUPPORTED_ENVS.grayRelease.join(', ')}`,
+      );
+    }
+
+    const deptStr = SYSTEM_TO_DEPT_MAP[normalizedArgs.systemCode];
+    const dateStr = today().replace(/-/g, '');
+    const autoSummary = `[${envCode.toUpperCase()}][GrayRelease] ${normalizedArgs.systemCode}_${normalizedArgs.module.toUpperCase()}_${dateStr} 程式上版作業申請單`;
+    const grayReleaseVersion = normalizedArgs.gitBranch.replace(/\//g, '-');
+    const serverList = getServerList(normalizedArgs.systemCode, envCode, false, normalizedArgs.module) || [];
+
+    const fields = {
+      project: {key: JIRA_PROJECT_ID},
+      issuetype: {id: ISSUE_TYPE_IDS.GrayRelease},
+      summary: normalizedArgs.summary ?? autoSummary,
+      duedate: today(),
+    };
+
+    // systemCode
+    fields[GRAY_RELEASE_FIELD_IDS.systemCode] = {value: normalizedArgs.systemCode};
+
+    // sign fields
+    fields[GRAY_RELEASE_FIELD_IDS.deptManagerSign] = SIGN_VALUES.deptManagerSign;
+    fields[GRAY_RELEASE_FIELD_IDS.authManagerSign] = SIGN_VALUES.authManagerSign;
+    fields[GRAY_RELEASE_FIELD_IDS.releaseInfo] = SIGN_VALUES.releaseInfo;
+
+    // env
+    if (ENV_CODES[envCode]) {
+      fields[GRAY_RELEASE_FIELD_IDS.env] = {value: envCode};
+    }
+
+    // dept code
+    if (deptStr && DEPT_CODES[deptStr]) {
+      fields[GRAY_RELEASE_FIELD_IDS.deptCode] = {value: deptStr};
+    }
+
+    // system module
+    if (moduleId) {
+      fields[GRAY_RELEASE_FIELD_IDS.systemModule] = {id: moduleId};
+    }
+
+    // jenkins branch
+    fields[GRAY_RELEASE_FIELD_IDS.jenkinsBranch] =
+      normalizedArgs.jenkinsBranch || JIRA_DEFAULTS.jenkinsBranch;
+
+    // git branch
+    fields[GRAY_RELEASE_FIELD_IDS.gitBranch] = normalizedArgs.gitBranch;
+
+    // grayReleaseVersion (/ → -)
+    fields[GRAY_RELEASE_FIELD_IDS.grayReleaseVersion] = grayReleaseVersion;
+
+    // cluster deploy (always true)
+    fields[GRAY_RELEASE_FIELD_IDS.clusterDeploy] = {id: FIELD_OPTIONS.clusterDeploy.true};
+
+    // cluster list
+    fields[GRAY_RELEASE_FIELD_IDS.clusterList] = serverList.join('\n');
+
+    // gray release notes
+    fields[GRAY_RELEASE_FIELD_IDS.grayReleaseNotes] = NOTES_TEMPLATES.grayRelease;
+
+    if (normalizedArgs.dryRun) {
+      return ok({dryRun: true, summary: fields.summary, grayReleaseVersion, fields});
+    }
+
+    const issue = await jira.createIssue(fields);
+    await notifier.notify(
+      issue.key,
+      `Gray Release 單已建立。系統: ${normalizedArgs.systemCode}, 模組: ${normalizedArgs.module}, 環境: ${envCode}, 分支: ${normalizedArgs.gitBranch}`,
+    );
+
+    const result = {
+      issueKey: issue.key,
+      issueId: issue.id,
+      url: `${process.env.JIRA_BASE_URL}/browse/${issue.key}`,
+      type: 'GrayRelease',
+      system: normalizedArgs.systemCode,
+      module: normalizedArgs.module,
+      environment: envCode,
+      grayReleaseVersion,
+    };
+
+    // 開 UAT 單後，主動搜尋尚未關聯的同 branch STG 灰度單
+    if (envCode === 'uat') {
+      const stgTickets = await findUnlinkedStgGrayReleases(normalizedArgs.gitBranch, moduleId, jira);
+      if (stgTickets.length > 0) {
+        result.suggest_link = {
+          message: `找到以下 STG 灰度單（branch: ${args.gitBranch}）尚未關聯到任何 UAT 灰度單，是否要建立 relates to 關聯到 ${issue.key}？`,
+          stgTickets,
+          hint: '回覆「是」或 yes 即可自動關聯，或直接呼叫 link_stg_grayrelease',
+        };
+      }
+    }
+
+    return ok(result);
+  } catch (err) {
+    return error(`無法建立 GrayRelease 單: ${err.message}`);
+  }
+}
+
+/**
+ * 將 STG 灰度單關聯（relates to）到 UAT 灰度單
+ */
+export async function handleLinkStgGrayRelease(args, {jira, notifier}) {
+  try {
+    const {uatKey, stgKeys} = args;
+    if (!Array.isArray(stgKeys) || stgKeys.length === 0) {
+      return error('stgKeys 不可為空');
+    }
+
+    const linked = [];
+    const failed = [];
+
+    for (const stgKey of stgKeys) {
+      try {
+        await jira.linkIssue(stgKey, uatKey, 'Relates');
+        linked.push(stgKey);
+      } catch (e) {
+        failed.push({key: stgKey, reason: e.message});
+      }
+    }
+
+    if (linked.length > 0) {
+      await notifier.notify(uatKey, `已將 STG 灰度單 ${linked.join(', ')} relates to ${uatKey}`);
+    }
+
+    return ok({
+      uatKey,
+      linked,
+      failed,
+      message:
+        linked.length > 0
+          ? `✅ 已關聯 ${linked.join(', ')} → ${uatKey}`
+          : '⚠️ 沒有成功關聯任何 STG 灰度單',
+    });
+  } catch (err) {
+    return error(`無法建立關聯: ${err.message}`);
+  }
+}