@jira-deploy/core 1.0.2 → 1.0.4

package/tools/grayrelease.js

@@ -1,6 +1,11 @@
 /**
  * Gray Release 相關 tools
  *   - create_grayrelease_ticket
+ *   - link_stg_grayrelease
+ *   - auto_grayrelease
+ *   - deploy_grayrelease
+ *   - get_grayrelease_status
+ *   - continue_grayrelease
  */
 import {
   SYSTEM_CODES,
@@ -16,8 +21,182 @@ import {
   SIGN_VALUES,
   NOTES_TEMPLATES,
   JIRA_DEFAULTS,
+  resolveAccountId,
 } from '../constants/index.js';
-import {error, ok, today, getServerList} from './helpers.js';
+import { error, ok, today, getServerList } from './helpers.js';
+import { Poller } from '../poller.js';
+import { handleGetReleaseManager, handleWaitForComment } from './release.js';
+import { handleSendJabberMessage } from './jabber.js';
+
+// ── Flow Definition ──────────────────────────────────────────────
+
+/**
+ * GrayRelease 狀態流程定義
+ * 每個狀態定義其可能的下一步 transitions
+ *
+ * 完整流程：
+ *   PLANNING → (Accept) → WAIT FOR BUILD → (GrayRelease Build)
+ *   → WAIT FOR BUILD → (Apply to approval) → WAIT APPROVAL
+ *   → (Approve，依環境處理簽核) → WAIT DEPLOY
+ *   → (Switch Execution Node，視上次 CD 部署環境群組 prd/nonPrd 決定是否需要)
+ *   → WAIT DEPLOY → (GrayRelease Deploy) → WAIT DEPLOY → (To Verify)
+ *   → VERIFY → (Verify Success) → MERGE CODE AND TAG → (To Done) → DONE
+ *
+ * 簽核規則：
+ *   - DEV：直接 Approve
+ *   - STG：指派給當日 Release Manager，等待簽核
+ *   - UAT：指派 James Yu 等待留言，再轉給 Solar Chen 等待簽核
+ *
+ * Rebuild 規則：
+ *   VERIFY 狀態只有在使用者明確要求 build/rebuild 時，才可透過 build_ticket({rebuild: true})
+ *   執行 Verify fail 回到 PLANNING 後重新 GrayRelease Build。
+ */
+const GRAYRELEASE_FLOW_MAP = {
+  'PLANNING': {
+    transitions: ['Accept'],
+    desc: '接受需求開始執行',
+    nextState: 'WAIT FOR BUILD',
+  },
+  'WAIT FOR BUILD': {
+    transitions: ['GrayRelease Build'],
+    desc: 'Build 程式',
+    nextState: 'WAIT FOR BUILD', // build 完會回到同狀態
+    afterBuild: 'Apply to approval', // build 完後要切到簽核
+  },
+  'WAIT APPROVAL': {
+    transitions: ['Approve'],
+    desc: '等待主管簽核',
+    nextState: 'WAIT DEPLOY',
+    requiresApproval: true,
+  },
+  'WAIT DEPLOY': {
+    transitions: ['Switch Execution Node', 'GrayRelease Deploy', 'To Verify'],
+    desc: '部署程式',
+    nextState: 'WAIT DEPLOY', // deploy 完會回到同狀態
+    afterDeploy: 'To Verify', // deploy 完後切到驗證
+  },
+  'VERIFY': {
+    transitions: ['Verify Success', 'Verify fail'],
+    desc: '驗證部署結果',
+    onSuccess: 'MERGE CODE AND TAG',
+    onFail: 'WAIT FOR BUILD', // 失敗重新 build
+  },
+  'MERGE CODE AND TAG': {
+    transitions: ['To Done'],
+    desc: '合併程式碼並打 tag',
+    nextState: 'DONE',
+  },
+  'DONE': {
+    completed: true,
+    desc: '流程完成',
+  },
+};
+
+function normalizeStatusName(statusName) {
+  return String(statusName ?? '')
+    .trim()
+    .replace(/\s+/g, ' ')
+    .toUpperCase();
+}
+
+function getPollIntervalMs() {
+  return parseInt(process.env.POLL_INTERVAL_MS ?? '30000');
+}
+
+function getPollTimeoutMs() {
+  return parseInt(process.env.POLL_TIMEOUT_MS ?? '3600000');
+}
+
+function progress(ctx, event) {
+  if (typeof ctx.progress === 'function') {
+    ctx.progress(event);
+  }
+}
+
+function isPassingResult(value) {
+  return ['pass', 'passed', 'success', 'succeeded', 'done'].includes(
+    String(value ?? '').trim().toLowerCase(),
+  );
+}
+
+function isFailingResult(value) {
+  return ['fail', 'failed', 'failure', 'error'].includes(
+    String(value ?? '').trim().toLowerCase(),
+  );
+}
+
+async function findTransitionByName(issueKey, transitionName, jira) {
+  const transitions = await jira.getTransitions(issueKey);
+  return transitions.find((transition) => (
+    transition.name.toLowerCase() === transitionName.toLowerCase()
+  ));
+}
+
+async function waitForGrayReleaseResult(issueKey, fieldId, label, jira, onProgress = () => {}) {
+  const intervalMs = getPollIntervalMs();
+  const timeoutMs = getPollTimeoutMs();
+  const startedAt = Date.now();
+  const deadline = Date.now() + timeoutMs;
+  let attempts = 0;
+  let lastValue;
+
+  while (true) {
+    attempts++;
+    const fields = await jira.getIssueFields(issueKey, [fieldId]);
+    const raw = fields[fieldId];
+    lastValue = raw?.value ?? raw; // Jira Select List 回傳物件 {value:'pass',...}，純字串也相容
+    onProgress({
+      phase: 'polling',
+      title: `等待 ${label} 結果`,
+      detail: `${fieldId}: ${lastValue ?? 'empty'}`,
+      issueKey,
+      attempts,
+      elapsedMs: Date.now() - startedAt,
+      timeoutMs,
+      nextPollMs: intervalMs,
+    });
+
+    if (isPassingResult(lastValue)) {
+      return { issueKey, fieldId, result: lastValue, attempts };
+    }
+
+    if (isFailingResult(lastValue)) {
+      throw new Error(`${label} 失敗，${fieldId}: ${lastValue}`);
+    }
+
+    if (Date.now() >= deadline) {
+      throw new Error(`${label} 等待逾時，${fieldId}: ${lastValue ?? 'empty'}`);
+    }
+
+    await sleep(intervalMs);
+  }
+}
+
+function parseToolResult(result) {
+  if (!result || result.isError) {
+    return null;
+  }
+
+  if (result.success || result.data) {
+    return result.data ?? result;
+  }
+
+  const text = result.content
+    ?.filter((item) => item.type === 'text')
+    .map((item) => item.text)
+    .join('\n')
+    .trim();
+
+  if (!text) {
+    return null;
+  }
+
+  try {
+    return JSON.parse(text);
+  } catch {
+    return null;
+  }
+}
 
 // ── Schema definitions ───────────────────────────────────────────
 export function getGrayReleaseToolDefinitions() {
@@ -75,12 +254,91 @@ export function getGrayReleaseToolDefinitions() {
           },
           stgKeys: {
             type: 'array',
-            items: {type: 'string'},
+            items: { type: 'string' },
             description: '要關聯的 STG 灰度單 key 陣列，例如 ["CID-1234", "CID-1235"]',
           },
         },
       },
     },
+    {
+      name: 'auto_grayrelease',
+      description:
+        '自動執行 GrayRelease 完整流程：PLANNING → Build → Approval → Deploy → Verify → Done。' +
+        '依環境自動處理簽核（DEV 跳過 / STG 組長簽核 / UAT 部長簽核）。支援 Build/Deploy 無限循環。',
+      inputSchema: {
+        type: 'object',
+        required: ['issueKey'],
+        properties: {
+          issueKey: {
+            type: 'string',
+            description: 'GrayRelease 單 issue key，例如 CID-822',
+          },
+          maxBuildRetries: {
+            type: 'number',
+            description: '(選填) Build 失敗最大重試次數，預設 3',
+          },
+          autoVerify: {
+            type: 'boolean',
+            description: '(選填) 是否自動執行 Verify Success（預設 false，需人工確認）',
+          },
+        },
+      },
+    },
+    {
+      name: 'deploy_grayrelease',
+      description:
+        '部署既有 GrayRelease 單，與 CD 部署完全分離。使用者說 GrayRelease deploy、部署灰度單時優先使用此 tool；' +
+        '若上下文 issue 是 GrayRelease 且使用者只說 deploy/部署，應先確認是否部署該 GrayRelease 單。' +
+        '此 tool 不會建立 CD 單、不接受 CI 單、不會重新 build；若目前在 Wait for Build 且可 Apply to approval，會往簽核/部署前進，最後停在 VERIFY 等人工驗證。',
+      inputSchema: {
+        type: 'object',
+        required: ['issueKey'],
+        properties: {
+          issueKey: {
+            type: 'string',
+            description: 'GrayRelease 單 issue key，例如 CID-822',
+          },
+        },
+      },
+    },
+    {
+      name: 'get_grayrelease_status',
+      description:
+        '查詢 GrayRelease 單當前狀態，並給出下一步建議。用於了解流程進度或中斷後查看位置。',
+      inputSchema: {
+        type: 'object',
+        required: ['issueKey'],
+        properties: {
+          issueKey: {
+            type: 'string',
+            description: 'GrayRelease 單 issue key，例如 CID-822',
+          },
+        },
+      },
+    },
+    {
+      name: 'continue_grayrelease',
+      description:
+        '從 GrayRelease 單當前狀態繼續執行流程。適用於流程中斷或需要從中間開始的場景。',
+      inputSchema: {
+        type: 'object',
+        required: ['issueKey'],
+        properties: {
+          issueKey: {
+            type: 'string',
+            description: 'GrayRelease 單 issue key，例如 CID-822',
+          },
+          maxBuildRetries: {
+            type: 'number',
+            description: '(選填) Build 失敗最大重試次數，預設 3',
+          },
+          autoVerify: {
+            type: 'boolean',
+            description: '(選填) 是否自動執行 Verify Success（預設 false，需人工確認）',
+          },
+        },
+      },
+    },
   ];
 }
 
@@ -121,13 +379,13 @@ async function findUnlinkedStgGrayReleases(gitBranch, moduleId, jira) {
         return linked?.fields?.issuetype?.id === GR_ISSUE_TYPE;
       });
     })
-    .map((issue) => ({key: issue.key, summary: issue.fields?.summary ?? ''}));
+    .map((issue) => ({ key: issue.key, summary: issue.fields?.summary ?? '' }));
 }
 
 /**
  * 建立 Gray Release 上版單
  */
-export async function handleCreateGrayReleaseTicket(args, {jira, notifier}) {
+export async function handleCreateGrayReleaseTicket(args, { jira, notifier }) {
   try {
     const normalizedArgs = {
       ...args,
@@ -168,14 +426,14 @@ export async function handleCreateGrayReleaseTicket(args, {jira, notifier}) {
     const serverList = getServerList(normalizedArgs.systemCode, envCode, false, normalizedArgs.module) || [];
 
     const fields = {
-      project: {key: JIRA_PROJECT_ID},
-      issuetype: {id: ISSUE_TYPE_IDS.GrayRelease},
+      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};
+    fields[GRAY_RELEASE_FIELD_IDS.systemCode] = { value: normalizedArgs.systemCode };
 
     // sign fields
     fields[GRAY_RELEASE_FIELD_IDS.deptManagerSign] = SIGN_VALUES.deptManagerSign;
@@ -184,17 +442,17 @@ export async function handleCreateGrayReleaseTicket(args, {jira, notifier}) {
 
     // env
     if (ENV_CODES[envCode]) {
-      fields[GRAY_RELEASE_FIELD_IDS.env] = {value: envCode};
+      fields[GRAY_RELEASE_FIELD_IDS.env] = { value: envCode };
     }
 
     // dept code
     if (deptStr && DEPT_CODES[deptStr]) {
-      fields[GRAY_RELEASE_FIELD_IDS.deptCode] = {value: deptStr};
+      fields[GRAY_RELEASE_FIELD_IDS.deptCode] = { value: deptStr };
     }
 
     // system module
     if (moduleId) {
-      fields[GRAY_RELEASE_FIELD_IDS.systemModule] = {id: moduleId};
+      fields[GRAY_RELEASE_FIELD_IDS.systemModule] = { id: moduleId };
     }
 
     // jenkins branch
@@ -208,7 +466,7 @@ export async function handleCreateGrayReleaseTicket(args, {jira, notifier}) {
     fields[GRAY_RELEASE_FIELD_IDS.grayReleaseVersion] = grayReleaseVersion;
 
     // cluster deploy (always true)
-    fields[GRAY_RELEASE_FIELD_IDS.clusterDeploy] = {id: FIELD_OPTIONS.clusterDeploy.true};
+    fields[GRAY_RELEASE_FIELD_IDS.clusterDeploy] = { id: FIELD_OPTIONS.clusterDeploy.true };
 
     // cluster list
     fields[GRAY_RELEASE_FIELD_IDS.clusterList] = serverList.join('\n');
@@ -217,7 +475,7 @@ export async function handleCreateGrayReleaseTicket(args, {jira, notifier}) {
     fields[GRAY_RELEASE_FIELD_IDS.grayReleaseNotes] = NOTES_TEMPLATES.grayRelease;
 
     if (normalizedArgs.dryRun) {
-      return ok({dryRun: true, summary: fields.summary, grayReleaseVersion, fields});
+      return ok({ dryRun: true, summary: fields.summary, grayReleaseVersion, fields });
     }
 
     const issue = await jira.createIssue(fields);
@@ -258,9 +516,9 @@ export async function handleCreateGrayReleaseTicket(args, {jira, notifier}) {
 /**
  * 將 STG 灰度單關聯（relates to）到 UAT 灰度單
  */
-export async function handleLinkStgGrayRelease(args, {jira, notifier}) {
+export async function handleLinkStgGrayRelease(args, { jira, notifier }) {
   try {
-    const {uatKey, stgKeys} = args;
+    const { uatKey, stgKeys } = args;
     if (!Array.isArray(stgKeys) || stgKeys.length === 0) {
       return error('stgKeys 不可為空');
     }
@@ -273,7 +531,7 @@ export async function handleLinkStgGrayRelease(args, {jira, notifier}) {
         await jira.linkIssue(stgKey, uatKey, 'Relates');
         linked.push(stgKey);
       } catch (e) {
-        failed.push({key: stgKey, reason: e.message});
+        failed.push({ key: stgKey, reason: e.message });
       }
     }
 
@@ -294,3 +552,776 @@ export async function handleLinkStgGrayRelease(args, {jira, notifier}) {
     return error(`無法建立關聯: ${err.message}`);
   }
 }
+
+// ── Handlers (NEW) ───────────────────────────────────────────────
+
+/**
+ * 自動執行 GrayRelease 完整流程
+ */
+export async function handleAutoGrayRelease(args, ctx) {
+  const { issueKey } = args;
+  const { jira, notifier } = ctx;
+
+  try {
+    progress(ctx, {
+      phase: 'action',
+      title: '開始 GrayRelease 自動流程',
+      issueKey,
+    });
+    await notifier.notify(issueKey, '開始自動執行 GrayRelease 流程');
+
+    const result = await executeGrayReleaseFlow(
+      issueKey,
+      {
+        maxBuildRetries: args.maxBuildRetries ?? 3,
+        autoVerify: args.autoVerify ?? false,
+      },
+      ctx,
+    );
+
+    return ok(result);
+  } catch (err) {
+    await notifier.notify(issueKey, `GrayRelease 流程執行失敗: ${err.message}`);
+    return error(`auto_grayrelease 失敗: ${err.message}`);
+  }
+}
+
+/**
+ * 查詢 GrayRelease 單當前狀態並給出建議
+ */
+export async function handleGetGrayReleaseStatus(args, { jira }) {
+  try {
+    const status = await getGrayReleaseStatus(args.issueKey, jira);
+    return ok(status);
+  } catch (err) {
+    return error(`get_grayrelease_status 失敗: ${err.message}`);
+  }
+}
+
+/**
+ * 執行 GrayRelease 部署流程，不觸發 rebuild。
+ */
+export async function handleDeployGrayRelease(args, ctx) {
+  const { issueKey } = args;
+  const { jira, notifier } = ctx;
+
+  try {
+    progress(ctx, {
+      phase: 'action',
+      title: '開始 GrayRelease deploy 流程',
+      issueKey,
+    });
+    const result = await executeGrayReleaseDeployFlow(issueKey, ctx);
+    await notifier.notify(issueKey, `GrayRelease deploy 流程結束，目前狀態：${result.finalStatus}`);
+    return ok(result);
+  } catch (err) {
+    await notifier.notify(issueKey, `GrayRelease deploy 失敗: ${err.message}`);
+    return error(`deploy_grayrelease 失敗: ${err.message}`);
+  }
+}
+
+/**
+ * 從當前狀態繼續執行 GrayRelease 流程
+ */
+export async function handleContinueGrayRelease(args, ctx) {
+  const { issueKey } = args;
+  const { jira, notifier } = ctx;
+
+  try {
+    const status = await getGrayReleaseStatus(issueKey, jira);
+
+    if (status.completed) {
+      progress(ctx, {
+        phase: 'done',
+        title: 'GrayRelease 已完成',
+        issueKey,
+        currentStatus: status.currentStatus,
+      });
+      return ok({
+        issueKey,
+        message: '此 GrayRelease 單已完成（狀態: DONE），無需繼續執行',
+        currentStatus: status.currentStatus,
+      });
+    }
+
+    await notifier.notify(
+      issueKey,
+      `從狀態 ${status.currentStatus} 繼續執行 GrayRelease 流程`,
+    );
+    progress(ctx, {
+      phase: 'action',
+      title: '繼續 GrayRelease 流程',
+      issueKey,
+      currentStatus: status.currentStatus,
+    });
+
+    const result = await executeGrayReleaseFlow(
+      issueKey,
+      {
+        maxBuildRetries: args.maxBuildRetries ?? 3,
+        autoVerify: args.autoVerify ?? false,
+      },
+      ctx,
+    );
+
+    return ok(result);
+  } catch (err) {
+    await notifier.notify(issueKey, `GrayRelease 流程執行失敗: ${err.message}`);
+    return error(`continue_grayrelease 失敗: ${err.message}`);
+  }
+}
+
+// ── Internal Helpers ─────────────────────────────────────────────
+
+/**
+ * 查詢 GrayRelease 單狀態並分析下一步
+ */
+async function getGrayReleaseStatus(issueKey, jira) {
+  const issue = await jira.getIssue(issueKey);
+  const currentStatus = issue.fields.status.name;
+  const normalizedStatus = normalizeStatusName(currentStatus);
+  const summary = issue.fields.summary;
+
+  // 查詢環境欄位
+  const fields = await jira.getIssueFields(issueKey, [
+    GRAY_RELEASE_FIELD_IDS.env,
+    GRAY_RELEASE_FIELD_IDS.systemCode,
+  ]);
+  const environment = fields[GRAY_RELEASE_FIELD_IDS.env]?.value ?? 'unknown';
+  const systemCode = fields[GRAY_RELEASE_FIELD_IDS.systemCode]?.value ?? 'unknown';
+
+  // 查詢可用 transitions
+  const transitions = await jira.getTransitions(issueKey);
+  const availableTransitions = transitions.map((t) => t.name);
+
+  // 根據當前狀態查找流程定義
+  const flowDef = GRAYRELEASE_FLOW_MAP[normalizedStatus];
+  const completed = flowDef?.completed === true;
+
+  let nextSteps = [];
+  let recommendation = '';
+
+  if (completed) {
+    recommendation = '✅ GrayRelease 流程已完成';
+  } else if (flowDef) {
+    nextSteps = flowDef.transitions ?? [];
+    recommendation = `${flowDef.desc}。可執行: ${nextSteps.join(' / ')}`;
+  } else {
+    recommendation = `⚠️ 未知狀態，請檢查 Jira 或手動處理。可用 transitions: ${availableTransitions.join(', ')}`;
+  }
+
+  return {
+    issueKey,
+    summary,
+    currentStatus,
+    normalizedStatus,
+    environment,
+    systemCode,
+    completed,
+    flowDefinition: flowDef,
+    nextSteps,
+    availableTransitions,
+    recommendation,
+  };
+}
+
+async function executeGrayReleaseDeployFlow(issueKey, ctx) {
+  const { jira, notifier } = ctx;
+  const log = [];
+  const fields = await jira.getIssueFields(issueKey, [
+    GRAY_RELEASE_FIELD_IDS.env,
+    GRAY_RELEASE_FIELD_IDS.systemCode,
+  ]);
+  const environment = fields[GRAY_RELEASE_FIELD_IDS.env]?.value;
+  const systemCode = fields[GRAY_RELEASE_FIELD_IDS.systemCode]?.value;
+
+  if (!environment) {
+    throw new Error('無法讀取 GrayRelease 環境欄位');
+  }
+
+  log.push(`🚀 開始執行 GrayRelease Deploy - 環境: ${environment.toUpperCase()}`);
+
+  while (true) {
+    const issue = await jira.getIssue(issueKey);
+    const currentStatus = issue.fields.status.name;
+    const normalizedStatus = normalizeStatusName(currentStatus);
+    const flowDef = GRAYRELEASE_FLOW_MAP[normalizedStatus];
+
+    log.push(`\n📍 當前狀態: ${currentStatus}`);
+    progress(ctx, {
+      phase: 'action',
+      title: '檢查 GrayRelease deploy 狀態',
+      issueKey,
+      currentStatus,
+    });
+
+    if (flowDef?.completed) {
+      log.push('✅ GrayRelease 流程已完成，無需 deploy');
+      break;
+    }
+
+    if (!flowDef) {
+      log.push(`⚠️ 未知狀態: ${currentStatus}，停止 deploy`);
+      break;
+    }
+
+    if (normalizedStatus === 'PLANNING') {
+      log.push('  執行: Accept');
+      await jira.transitionByName(issueKey, 'Accept');
+      await notifier.notify(issueKey, 'Accept 需求，準備進入部署流程');
+      continue;
+    }
+
+    if (normalizedStatus === 'WAIT FOR BUILD') {
+      const applyTransition = await findTransitionByName(issueKey, 'Apply to approval', jira);
+      if (!applyTransition) {
+        log.push('  ⏸️ 目前仍需 build，deploy_grayrelease 不會觸發 rebuild');
+        break;
+      }
+      log.push('  執行: Apply to approval');
+      await jira.transitionByName(issueKey, 'Apply to approval');
+      await notifier.notify(issueKey, '進入 GrayRelease 部署簽核流程');
+      continue;
+    }
+
+    if (normalizedStatus === 'WAIT APPROVAL') {
+      log.push(`  處理簽核流程 (環境: ${environment})`);
+      const approvalResult = await handleGrayReleaseApproval(issueKey, environment, systemCode, ctx);
+      if (approvalResult.skipped) {
+        log.push(`  ✅ ${approvalResult.reason}`);
+        await jira.transitionByName(issueKey, 'Approve');
+        await notifier.notify(issueKey, 'DEV 環境無需簽核，直接 Approve');
+      } else {
+        log.push(`  ✅ 簽核完成 by ${approvalResult.by}`);
+      }
+      continue;
+    }
+
+    if (normalizedStatus === 'WAIT DEPLOY') {
+      const deployCompleted = await runGrayReleaseDeployStep(issueKey, systemCode, ctx, log);
+      if (!deployCompleted) {
+        break;
+      }
+      continue;
+    }
+
+    if (normalizedStatus === 'VERIFY') {
+      log.push('  ⏸️ 已進入 VERIFY，請人工驗證；若需重 build 請明確執行 build/rebuild');
+      break;
+    }
+
+    if (normalizedStatus === 'MERGE CODE AND TAG') {
+      log.push('  ✅ 已完成部署與驗證，等待合併程式碼與打 tag');
+      break;
+    }
+
+    log.push(`⚠️ 狀態 ${currentStatus} 沒有 deploy 處理邏輯，停止執行`);
+    break;
+  }
+
+  const finalIssue = await jira.getIssue(issueKey);
+  return {
+    issueKey,
+    finalStatus: finalIssue.fields.status.name,
+    log,
+  };
+}
+
+/**
+ * 主執行流程：從當前狀態開始，自動執行到完成或需要人工介入
+ */
+async function executeGrayReleaseFlow(issueKey, options, ctx) {
+  const { jira, notifier } = ctx;
+  const log = [];
+  let buildAttempts = 0;
+
+  // 讀取環境和系統代碼
+  const fields = await jira.getIssueFields(issueKey, [
+    GRAY_RELEASE_FIELD_IDS.env,
+    GRAY_RELEASE_FIELD_IDS.systemCode,
+  ]);
+  const environment = fields[GRAY_RELEASE_FIELD_IDS.env]?.value;
+  const systemCode = fields[GRAY_RELEASE_FIELD_IDS.systemCode]?.value;
+
+  if (!environment) {
+    throw new Error('無法讀取 GrayRelease 環境欄位');
+  }
+
+  log.push(`🚀 開始執行 GrayRelease 流程 - 環境: ${environment.toUpperCase()}`);
+
+  while (true) {
+    const issue = await jira.getIssue(issueKey);
+    const currentStatus = issue.fields.status.name;
+    const normalizedStatus = normalizeStatusName(currentStatus);
+    const flowDef = GRAYRELEASE_FLOW_MAP[normalizedStatus];
+
+    log.push(`\n📍 當前狀態: ${currentStatus}`);
+    progress(ctx, {
+      phase: 'action',
+      title: '檢查 GrayRelease 狀態',
+      issueKey,
+      currentStatus,
+    });
+
+    // 已完成
+    if (flowDef?.completed) {
+      log.push('✅ GrayRelease 流程完成！');
+      break;
+    }
+
+    // 未知狀態
+    if (!flowDef) {
+      log.push(`⚠️ 未知狀態: ${currentStatus}，停止自動執行`);
+      break;
+    }
+
+    // ── PLANNING → Accept ────────────────────────────────────
+    if (normalizedStatus === 'PLANNING') {
+      log.push('  執行: Accept');
+      await jira.transitionByName(issueKey, 'Accept');
+      await notifier.notify(issueKey, 'Accept 需求，進入 WAIT FOR BUILD');
+      continue;
+    }
+
+    // ── WAIT FOR BUILD → GrayRelease Build ───────────────────
+    if (normalizedStatus === 'WAIT FOR BUILD') {
+      buildAttempts++;
+      if (buildAttempts > options.maxBuildRetries) {
+        log.push(`⚠️ Build 已達最大重試次數 (${options.maxBuildRetries})，停止執行`);
+        break;
+      }
+
+      log.push(`  執行: GrayRelease Build (第 ${buildAttempts} 次)`);
+      await jira.transitionByName(issueKey, 'GrayRelease Build');
+      await notifier.notify(issueKey, `觸發 GrayRelease Build (第 ${buildAttempts} 次)`);
+
+      // 等待 build 完成
+      log.push('  ⏳ 等待 Jenkins Build 完成...');
+      await waitForGrayReleaseResult(
+        issueKey,
+        GRAY_RELEASE_FIELD_IDS.buildResult,
+        'GrayRelease Build',
+        jira,
+        ctx.progress,
+      );
+
+      log.push('  ✅ Build 完成');
+
+      // Build 完成後切到 WAIT APPROVAL
+      log.push('  執行: Apply to approval');
+      await jira.transitionByName(issueKey, 'Apply to approval');
+      await notifier.notify(issueKey, 'Build 完成，申請簽核');
+      continue;
+    }
+
+    // ── WAIT APPROVAL → Approve ───────────────────────────────
+    if (normalizedStatus === 'WAIT APPROVAL') {
+      log.push(`  處理簽核流程 (環境: ${environment})`);
+
+      const approvalResult = await handleGrayReleaseApproval(
+        issueKey,
+        environment,
+        systemCode,
+        ctx,
+      );
+
+      if (approvalResult.skipped) {
+        log.push(`  ✅ ${approvalResult.reason}`);
+        // DEV 環境直接執行 Approve
+        await jira.transitionByName(issueKey, 'Approve');
+        await notifier.notify(issueKey, 'DEV 環境無需簽核，直接 Approve');
+      } else {
+        log.push(`  ✅ 簽核完成 by ${approvalResult.by}`);
+      }
+      continue;
+    }
+
+    // ── WAIT DEPLOY → Switch / Deploy ─────────────────────────
+    if (normalizedStatus === 'WAIT DEPLOY') {
+      const deployCompleted = await runGrayReleaseDeployStep(issueKey, systemCode, ctx, log);
+      if (!deployCompleted) {
+        break;
+      }
+      continue;
+    }
+
+    // ── VERIFY → 需要人工決定 ─────────────────────────────────
+    if (normalizedStatus === 'VERIFY') {
+      if (options.autoVerify) {
+        log.push('  ⚠️ autoVerify=true，自動執行 Verify Success');
+        await jira.transitionByName(issueKey, 'Verify Success');
+        await notifier.notify(issueKey, '自動驗證成功');
+        continue;
+      } else {
+        log.push('  ⏸️  需要人工驗證結果，停止自動執行');
+        log.push('     可執行: Verify Success（成功）/ Verify fail（失敗重新 build）');
+        break;
+      }
+    }
+
+    // ── MERGE CODE AND TAG → To Done ─────────────────────────
+    if (normalizedStatus === 'MERGE CODE AND TAG') {
+      log.push('  執行: To Done');
+      await jira.transitionByName(issueKey, 'To Done');
+      await notifier.notify(issueKey, 'GrayRelease 流程完成');
+      continue;
+    }
+
+    // 未處理的狀態
+    log.push(`⚠️ 狀態 ${currentStatus} 沒有自動處理邏輯，停止執行`);
+    break;
+  }
+
+  const finalIssue = await jira.getIssue(issueKey);
+  return {
+    issueKey,
+    finalStatus: finalIssue.fields.status.name,
+    buildAttempts,
+    log,
+  };
+}
+
+async function runGrayReleaseDeployStep(issueKey, systemCode, ctx, log) {
+  const { jira, notifier } = ctx;
+  const needSwitch = await needSwitchExecutionNode(issueKey, systemCode, jira);
+
+  if (needSwitch) {
+    log.push('  執行: Switch Execution Node');
+    progress(ctx, {
+      phase: 'action',
+      title: '切換 GrayRelease execution node',
+      issueKey,
+    });
+    await jira.transitionByName(issueKey, 'Switch Execution Node');
+    await notifier.notify(issueKey, '切換 Ansible instance');
+    await waitForSwitchExecutionNode(issueKey, systemCode, jira);
+  }
+
+  log.push('  執行: GrayRelease Deploy');
+  progress(ctx, {
+    phase: 'action',
+    title: '觸發 GrayRelease Deploy',
+    issueKey,
+  });
+  await jira.transitionByName(issueKey, 'GrayRelease Deploy');
+  await notifier.notify(issueKey, '觸發 GrayRelease Deploy');
+
+  // 等待部署完成：優先輪詢 deploy result、VERIFY 狀態，
+  // 或「To Verify」transition 是否出現。
+  // 最多等待 3 分鐘（避免 MCP client timeout），
+  // 若超時則回傳「部署中」訊息，請使用者稍後繼續。
+  const DEPLOY_WAIT_MS = Math.min(getPollTimeoutMs(), 3 * 60 * 1000);
+  const DEPLOY_POLL_MS = Math.min(getPollIntervalMs(), 10_000);
+  const deployDeadline = Date.now() + DEPLOY_WAIT_MS;
+  let deployCompleted = false;
+  let attempts = 0;
+
+  log.push('  ⏳ 等待部署完成（最多 3 分鐘）...');
+  while (Date.now() <= deployDeadline) {
+    attempts++;
+    const issue = await jira.getIssue(issueKey);
+    const statusNow = normalizeStatusName(issue.fields.status.name);
+    const fields = await jira.getIssueFields(issueKey, [GRAY_RELEASE_FIELD_IDS.deployResult]);
+    const rawDeployResult = fields[GRAY_RELEASE_FIELD_IDS.deployResult];
+    const deployResult = rawDeployResult?.value ?? rawDeployResult;
+    progress(ctx, {
+      phase: 'polling',
+      title: '等待 GrayRelease deploy 完成',
+      detail: `${GRAY_RELEASE_FIELD_IDS.deployResult}: ${deployResult ?? 'empty'}`,
+      issueKey,
+      currentStatus: issue.fields.status.name,
+      targetStatus: 'VERIFY',
+      attempts,
+      elapsedMs: DEPLOY_WAIT_MS - Math.max(0, deployDeadline - Date.now()),
+      timeoutMs: DEPLOY_WAIT_MS,
+      nextPollMs: DEPLOY_POLL_MS,
+    });
+
+    if (statusNow === 'VERIFY') {
+      // Jira automation 或 Jenkins 已自動切到 VERIFY
+      deployCompleted = true;
+      log.push('  ✅ 狀態已進入 VERIFY（自動切換），跳過手動 To Verify');
+      break;
+    }
+
+    if (isFailingResult(deployResult)) {
+      throw new Error(`GrayRelease Deploy 失敗，${GRAY_RELEASE_FIELD_IDS.deployResult}: ${deployResult}`);
+    }
+
+    const transitions = await jira.getTransitions?.(issueKey) ?? [];
+    const toVerifyTrans = transitions.find(
+      (t) => t.name.toLowerCase() === 'to verify',
+    );
+    if (isPassingResult(deployResult) || toVerifyTrans) {
+      log.push('  ✅ Deploy 完成，執行: To Verify');
+      if (toVerifyTrans?.id && jira.transitionById) {
+        await jira.transitionById(issueKey, toVerifyTrans.id);
+      } else {
+        await jira.transitionByName(issueKey, 'To Verify');
+      }
+      await notifier.notify(issueKey, 'Deploy 完成，進入驗證階段');
+      deployCompleted = true;
+      break;
+    }
+
+    if (Date.now() >= deployDeadline) {
+      break;
+    }
+
+    await sleep(DEPLOY_POLL_MS);
+  }
+
+  if (!deployCompleted) {
+    log.push('  ⚠️ 3 分鐘內未看到部署結果，部署可能仍在進行中');
+    log.push('  請稍後使用 get_grayrelease_status 或 deploy_grayrelease 繼續');
+    await notifier.notify(issueKey, '部署仍在進行中，請稍後查詢狀態');
+    return false;
+  }
+
+  await notifier.notify(issueKey, 'Deploy 完成，進入驗證階段');
+  return true;
+}
+
+/**
+ * 處理簽核流程（依環境別）
+ */
+async function handleGrayReleaseApproval(issueKey, environment, systemCode, ctx) {
+  const { jira, notifier } = ctx;
+  const env = environment.toLowerCase();
+
+  // DEV: 跳過簽核
+  if (env === 'dev') {
+    return { skipped: true, reason: 'DEV 環境無需簽核' };
+  }
+
+  // STG: 查 wiki 值班組長 → assign → 發 jabber → 等待 approve
+  if (env === 'stg') {
+    const managerResult = await handleGetReleaseManager({}, {});
+    const managerData = parseToolResult(managerResult);
+
+    if (!managerData?.found) {
+      throw new Error('無法查詢 STG 值班組長，請手動處理');
+    }
+
+    const managerName = managerData.name;
+    const accountId = resolveAccountId(managerName);
+
+    if (!accountId) {
+      throw new Error(`找不到 ${managerName} 的 accountId`);
+    }
+
+    // Assign 給組長
+    progress(ctx, {
+      phase: 'action',
+      title: '指派 GrayRelease 簽核人',
+      detail: `STG 值班組長 ${managerName}`,
+      issueKey,
+    });
+    await jira.updateAssignee(issueKey, accountId);
+    await notifier.notify(issueKey, `已指派給 STG 值班組長 ${managerName}`);
+
+    // 發送 jabber 通知
+    const jabberTo = `${accountId}@linebank.com.tw`;
+    progress(ctx, {
+      phase: 'waiting',
+      title: '發送 GrayRelease 簽核通知',
+      detail: `to ${managerName} (${jabberTo})`,
+      issueKey,
+    });
+    await handleSendJabberMessage(
+      {
+        to: jabberTo,
+        message: `[GrayRelease 簽核通知] ${issueKey} 需要您的簽核。環境: STG\n${process.env.JIRA_BASE_URL}/browse/${issueKey}`,
+      },
+      {},
+    );
+
+    // 輪詢等待 Approve（狀態變為 WAIT DEPLOY）
+    const poller = new Poller(jira);
+    await poller.waitForStatus(issueKey, 'WAIT DEPLOY', {
+      intervalMs: parseInt(process.env.POLL_INTERVAL_MS ?? '30000'),
+      timeoutMs: parseInt(process.env.POLL_TIMEOUT_MS ?? '3600000'),
+      onProgress: ctx.progress,
+    });
+
+    return { approved: true, by: managerName };
+  }
+
+  // UAT: assign James Yu → 等待留言 → 轉 Solar Chen → 等待 approve
+  if (env === 'uat') {
+    const jamesAccountId = resolveAccountId('James Yu');
+    if (!jamesAccountId) {
+      throw new Error('找不到 James Yu 的 accountId');
+    }
+
+    // Assign 給 James Yu
+    progress(ctx, {
+      phase: 'action',
+      title: '指派 GrayRelease 簽核人',
+      detail: '部長 James Yu',
+      issueKey,
+    });
+    await jira.updateAssignee(issueKey, jamesAccountId);
+    await notifier.notify(issueKey, '已指派給部長 James Yu，等待留言確認');
+
+    // 發送 jabber 通知給 James Yu
+    const jamesJabber = `${jamesAccountId}@linebank.com.tw`;
+    progress(ctx, {
+      phase: 'waiting',
+      title: '發送 GrayRelease 簽核通知',
+      detail: `to James Yu (${jamesJabber})`,
+      issueKey,
+    });
+    await handleSendJabberMessage(
+      {
+        to: jamesJabber,
+        message: `[GrayRelease 簽核通知] ${issueKey} 需要您的簽核並留言確認。環境: UAT\n${process.env.JIRA_BASE_URL}/browse/${issueKey}`,
+      },
+      {},
+    );
+
+    // 等待 James Yu 留言 "Approved"
+    const commentResult = await handleWaitForComment(
+      {
+        issueKey,
+        keyword: 'approved',
+        authorAccountId: jamesAccountId,
+        timeoutMs: parseInt(process.env.POLL_TIMEOUT_MS ?? '3600000'),
+        intervalMs: parseInt(process.env.POLL_INTERVAL_MS ?? '30000'),
+      },
+      { jira, progress: ctx.progress },
+    );
+    const commentData = parseToolResult(commentResult);
+
+    if (!commentData?.found) {
+      throw new Error('等待 James Yu 留言超時');
+    }
+
+    await notifier.notify(issueKey, `James Yu 已留言確認: ${commentData.comment}`);
+
+    // 轉給 Solar Chen
+    const solarAccountId = resolveAccountId('Solar Chen');
+    if (!solarAccountId) {
+      throw new Error('找不到 Solar Chen 的 accountId');
+    }
+
+    progress(ctx, {
+      phase: 'action',
+      title: '指派 GrayRelease 簽核人',
+      detail: 'Solar Chen',
+      issueKey,
+    });
+    await jira.updateAssignee(issueKey, solarAccountId);
+    await notifier.notify(issueKey, '已轉單給 Solar Chen，等待最終簽核');
+
+    // 發送 jabber 通知給 Solar Chen
+    const solarJabber = `${solarAccountId}@linebank.com.tw`;
+    progress(ctx, {
+      phase: 'waiting',
+      title: '發送 GrayRelease 簽核通知',
+      detail: `to Solar Chen (${solarJabber})`,
+      issueKey,
+    });
+    await handleSendJabberMessage(
+      {
+        to: solarJabber,
+        message: `[GrayRelease 簽核通知] ${issueKey} 已由 James Yu 確認，需要您的最終簽核。環境: UAT\n${process.env.JIRA_BASE_URL}/browse/${issueKey}`,
+      },
+      {},
+    );
+
+    // 輪詢等待 Solar Approve（狀態變為 WAIT DEPLOY）
+    const poller = new Poller(jira);
+    await poller.waitForStatus(issueKey, 'WAIT DEPLOY', {
+      intervalMs: parseInt(process.env.POLL_INTERVAL_MS ?? '30000'),
+      timeoutMs: parseInt(process.env.POLL_TIMEOUT_MS ?? '3600000'),
+      onProgress: ctx.progress,
+    });
+
+    return { approved: true, by: 'James Yu → Solar Chen' };
+  }
+
+  throw new Error(`不支援的環境: ${environment}`);
+}
+
+/**
+ * 判斷是否需要執行 Switch Execution Node
+ * 規則：查詢同系統上次 CD 部署的環境群組，若與本次不同則需切換
+ * 注意：不查詢 GrayRelease 歷史，因為 GrayRelease 永遠是 nonPrd
+ */
+async function needSwitchExecutionNode(issueKey, systemCode, jira) {
+  if (await hasRecentSwitchExecutionNodeComment(issueKey, systemCode, jira)) {
+    return false;
+  }
+
+  // GrayRelease 永遠是 nonPrd 群組
+  const thisGroup = 'nonPrd';
+
+  // 只查詢 CD 單的部署歷史（不包含 GrayRelease）
+  const isPrdEnv = (env) => ['prd', 'dr', 'prd/dr', 'prd&dr'].includes(env?.toLowerCase()?.trim());
+
+  const jql_cd = `project = CID AND issuetype = CD AND "System Code[Select List (single choice)]" = "${systemCode}" AND status = Done AND issueKey != "${issueKey}" ORDER BY updated DESC`;
+
+  try {
+    const cdResults = await jira.searchIssues(jql_cd, ['customfield_13436', 'updated'], 1);
+    const cdIssue = cdResults[0] ?? null;
+
+    // 查不到歷史 → 保守執行 Switch
+    if (!cdIssue) {
+      return true;
+    }
+
+    // CD：讀 customfield_13436.value 判斷群組
+    const envVal = cdIssue.fields?.customfield_13436?.value ?? '';
+    const lastGroup = isPrdEnv(envVal) ? 'prd' : 'nonPrd';
+
+    // 群組不同 → 需要 Switch
+    return lastGroup !== thisGroup;
+  } catch {
+    // 查詢失敗 → 保守執行 Switch
+    return true;
+  }
+}
+
+async function waitForSwitchExecutionNode(issueKey, systemCode, jira) {
+  const waitMs = parseInt(process.env.SWITCH_EXECUTION_NODE_WAIT_MS ?? '180000');
+  const intervalMs = getPollIntervalMs();
+  const deadline = Date.now() + waitMs;
+
+  while (true) {
+    if (await hasRecentSwitchExecutionNodeComment(issueKey, systemCode, jira)) {
+      return;
+    }
+
+    if (Date.now() >= deadline) {
+      return;
+    }
+
+    await sleep(intervalMs);
+  }
+}
+
+async function hasRecentSwitchExecutionNodeComment(issueKey, systemCode, jira) {
+  if (!jira.getComments) {
+    return false;
+  }
+
+  try {
+    const comments = await jira.getComments(issueKey);
+    const lowerSystemCode = String(systemCode ?? '').toLowerCase();
+    return comments.some((comment) => {
+      const body = String(comment.body ?? '').toLowerCase();
+      const author = String(comment.author?.displayName ?? comment.author?.name ?? '').toLowerCase();
+      return author === 'cid jira worker'
+        && body.includes('instance_group')
+        && body.includes('nonprd_executionnode')
+        && (!lowerSystemCode || body.includes(lowerSystemCode));
+    });
+  } catch {
+    return false;
+  }
+}
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}