# visionA Cloud 整合 — converter scheduler 交接檔 v2

> **時間**：2026-05-16
> **背景**：visionA Cloud Phase 0.8b — 從 OAuth client_credentials 改 API key + 重設計 download 路徑
> **替代**：本檔取代 `docs/TODO-visionA-integration.md`（5/2 寫的、ADR-014 設計 — 已過時）
> **對應**：visionA repo 的 `docs/autoflow/04-architecture/adr/adr-015-server-to-server-api-key.md` v2.1 + `adr-016-download-via-converter.md` v1.0

---

## 1. 為什麼會有這份交接檔

### 5/2 原本的設計（ADR-014、現已 supersede）

visionA → converter / FAA 走 **OAuth `client_credentials`** + MC（Member Center）service token + scope (`converter:job.read/write` / `files:download.delegate`)。

### 5/9 stage e2e 撞 4 個 blocker → ADR-015 改 API key

| # | Blocker |
|---|---------|
| 1 | MC stage 沒註冊 `converter:job.read/write` 兩個 scope |
| 2 | converter image 5 週前舊版、沒 OAuth middleware、沒 `/api/v1/jobs` endpoint |
| 3 | converter 缺 `MEMBER_CENTER_*` env |
| 4 | FAA 端 OAuth 整合狀態不確定（warrenchen 維護） |

**使用者拍板**：1:1 internal trust（visionA ↔ converter 是 1 對 1）用 OAuth 過度設計、改 pre-shared API key。

### 5/16 grep MC + FAA source 發現 ADR-014 §2 設計缺口 → ADR-016 改 download 路徑

```bash
grep -rn "delegated\|DownloadToken" member_center/src --include="*.cs"
# 0 命中 — MC source 沒有 issue / validate delegated download token endpoint
```

MC 端**從來就沒有實作** ADR-014 §2 假設的「issue delegated download token」+「validate delegated download token」兩個 endpoint。FAA 的 `MemberCenterDelegatedDownloadTokenValidator.cs` 假設 MC 有 `_options.DownloadTokenValidationPath` introspection endpoint，**也假設錯了**。

→ **delegated token 鏈從 5/2 寫完到現在一直是斷的**，只是因為從未實際 e2e 跑通過所以沒人發現。

**使用者拍板**：不動 MC、不動 FAA。改設計成 visionA → converter `GET /api/v1/jobs/{id}/result` 中轉（ADR-016）。

---

## 2. converter scheduler 需要做的 2 件事

| # | 範圍 | 動 code 多少 | 風險 |
|---|------|-------------|------|
| **任務 A** | 加 API key middleware（取代 OAuth JWT 驗證、或並存）| ~50-100 行 | 低（現有 `requireAuth` pattern 可借鑑）|
| **任務 B** | 加 `GET /api/v1/jobs/:id/result` endpoint | ~80 行 + test | 低（`getObjectStream` 已存在、Phase 2 預留位已有 routing 慣例）|

兩個都在 `apps/task-scheduler/src/` 內、單一 repo。

---

## 3. 任務 A — API key middleware

### 3.1 設計取捨：API key only vs API key + OAuth 並存

**推薦：並存模式**（最少 breaking change）

| 設計 | 動 code | 影響 | 推薦? |
|------|---------|------|-------|
| **A. 純 API key**（砍 OAuth）| 砍 `src/auth/middleware.js` + `src/auth/jwks.js` + `src/auth/oauthClient.js` | 既有 OAuth caller 全部要 migrate（如有）| ❌ 風險高 |
| **B. 並存**（OAuth + API key 二選一）| 新增 `src/auth/apiKeyMiddleware.js` + 改 `routes/v1/index.js` wire | 既有 OAuth 路徑完全不動、API key 是額外 path | ✅ **推薦** |
| **C. 純 API key + 保留 OAuth helper code**（不 wire）| 既有 `auth/` 留著但不啟用 | 模糊、未來容易誤啟用 | ⚠️ 不推薦 |

採 **B 並存**，理由：
1. visionA 是 1 個 caller、走 API key
2. 其他既有 caller（如 jimchen 手動測試、CI、未來其他產品線）仍可用 OAuth
3. converter 不需要強迫所有 caller 一次 migrate
4. 如果未來 100% caller 都用 API key、再砍 OAuth path

### 3.2 實作（新增 `src/auth/apiKeyMiddleware.js`）

對齊既有 `requireAuth(scope)` API surface，讓 routes/v1/jobs.js 可以無痛換掛。

```javascript
// src/auth/apiKeyMiddleware.js
//
// API key middleware — Phase 0.8b 為 visionA 整合新增。
//
// 設計：
//   - 接受 Authorization: Bearer <pre-shared-API-key>
//   - 用 crypto.timingSafeEqual constant-time compare（避免 timing attack）
//   - 不驗 scope / tenant — 1:1 internal trust，API key 就是「caller 是 visionA」的完整證明
//   - 對齊既有 sendAuthError 模式（含 destroy socket M2 行為）
//
// 對應 visionA repo 的：
//   - ADR-015 v2.1 §1 visionA → converter
//   - ADR-015 v2.1 §3.5.1 reference middleware implementation (Go)
//   - 本檔是 Node.js port
//
// 如何接：
//   const { requireAuth } = require('./middleware');           // 既有 OAuth
//   const { requireApiKey } = require('./apiKeyMiddleware');   // 新 API key
//   const auth = requireApiKey() || requireAuth('converter:job.write');  // 不能直接這樣寫，看 §3.3
//
// 看 §3.3「並存策略」實際 wire 方式。

'use strict';

const crypto = require('crypto');

/**
 * 解析 Bearer header（複用 ./middleware.js 內部 helper 邏輯）。
 */
function extractBearerToken(headerValue) {
  if (typeof headerValue !== 'string' || headerValue.length === 0) return null;
  const match = headerValue.match(/^Bearer\s+(.+)$/i);
  if (!match) return null;
  const token = match[1].trim();
  return token === '' ? null : token;
}

/**
 * sendApiKeyError — 對齊既有 ./middleware.js sendAuthError 的 destroy socket M2 行為。
 *
 * 不直接 require ./middleware._internals.sendAuthError 是因為它含 request_id 邏輯、
 * 跟 API key 不同 context；inline 一個簡化版避免循環依賴。
 */
function sendApiKeyError(req, res, status, code, message) {
  if (res.headersSent) {
    try { if (req.socket && !req.socket.destroyed) req.socket.destroy(); } catch (_) {}
    return;
  }
  res.setHeader('Connection', 'close');
  res.status(status).json({
    error: {
      code,
      message,
      request_id: req.requestId || null,
    },
  });
  res.once('finish', () => {
    try { if (req.socket && !req.socket.destroyed) req.socket.destroy(); } catch (_) {}
  });
}

/**
 * Constant-time string compare。
 *
 * 重要：
 *   - 必須長度先比（避免 timingSafeEqual 在長度不同時 throw）
 *   - 長度不算 secret（公開資訊）
 */
function constantTimeEquals(a, b) {
  if (typeof a !== 'string' || typeof b !== 'string') return false;
  const bufA = Buffer.from(a, 'utf8');
  const bufB = Buffer.from(b, 'utf8');
  if (bufA.length !== bufB.length) return false;
  return crypto.timingSafeEqual(bufA, bufB);
}

/**
 * 建立一個 requireApiKey middleware。
 *
 * @param {object} [deps] — 測試注入
 * @param {string} [deps.expectedApiKey] — 明文 API key；不傳則 lazy load from config
 * @returns {import('express').RequestHandler}
 */
function requireApiKey(deps = {}) {
  let expected = deps.expectedApiKey;

  return function apiKeyMiddleware(req, res, next) {
    try {
      if (!expected) {
        // Lazy-load config（對齊 ./middleware.js pattern）
        const config = require('../config').loadConfig();
        expected = config.converter.apiKey;  // §3.4 加入 config 後可讀
      }

      // Fail-fast: API key 未設定就拒絕所有 request（不要 silently allow）
      if (!expected || expected === '') {
        // eslint-disable-next-line no-console
        console.error(JSON.stringify({
          level: 'ERROR',
          action: 'auth.api_key.not_configured',
          message: 'CONVERTER_API_KEY env not set; rejecting all requests',
          timestamp: new Date().toISOString(),
        }));
        return sendApiKeyError(req, res, 503, 'service_unavailable', 'API key not configured');
      }

      const token = extractBearerToken(req.headers && req.headers.authorization);
      if (!token) {
        return sendApiKeyError(req, res, 401, 'invalid_token',
          '缺少或格式錯誤的 Authorization header（需為 Bearer <token>）');
      }

      if (!constantTimeEquals(token, expected)) {
        return sendApiKeyError(req, res, 401, 'invalid_token', 'API key 驗證失敗');
      }

      // 驗證成功 — 設 req.auth 給下游使用（對齊 OAuth middleware 的 req.auth shape）
      req.auth = {
        sub: 'visionA-service',          // 固定值（API key 沒 sub）
        clientId: 'visionA-service',
        tenantId: null,                  // API key 不帶 tenant
        scopes: ['converter:job.write', 'converter:job.read'],  // implicit full access
        raw: { authType: 'api_key' },
      };

      return next();
    } catch (err) {
      // eslint-disable-next-line no-console
      console.error(JSON.stringify({
        level: 'ERROR',
        action: 'auth.api_key.unexpected_error',
        message: err && err.message ? err.message : 'unknown',
        timestamp: new Date().toISOString(),
      }));
      return sendApiKeyError(req, res, 401, 'invalid_token', 'API key 驗證失敗');
    }
  };
}

module.exports = {
  requireApiKey,
  _internals: { extractBearerToken, constantTimeEquals, sendApiKeyError },
};
```

### 3.3 並存策略 — 二選一 middleware

最簡單做法：寫一個 `requireApiKeyOrOAuth(oauthScope)` wrapper。

```javascript
// src/auth/middleware.js 末尾加：

const { requireApiKey } = require('./apiKeyMiddleware');

/**
 * 並存 middleware — 先試 API key、不行 fallback OAuth。
 *
 * 用法（取代既有 routes/v1/jobs.js + promote.js 的 requireAuth(scope) 呼叫）：
 *   const auth = require('./middleware');
 *   router.post('/jobs', auth.requireApiKeyOrOAuth('converter:job.write'), handler);
 *
 * 行為：
 *   1. 沒帶 Authorization header → 401（API key middleware 處理）
 *   2. 帶的 token 是 visionA 的 API key（constant-time match）→ API key path 過、req.auth 設好、next()
 *   3. 帶的 token 不 match API key → 走 OAuth JWT 驗證（既有 requireAuth）
 *      - 過 → next()
 *      - 不過 → 401（OAuth middleware 處理）
 *
 * 為什麼 API key 優先：API key compare 快（constant-time string compare），JWT 驗證慢（JWKS fetch + verify）。
 */
function requireApiKeyOrOAuth(oauthScope) {
  const apiKey = requireApiKey();
  const oauth = requireAuth(oauthScope);

  return function combinedAuth(req, res, next) {
    // 先攔截 response — 如果 API key 過了 next()，就完成；如果 API key 寫了 401，我們 swap 成試 OAuth
    const originalSetHeader = res.setHeader.bind(res);
    const originalStatus = res.status.bind(res);
    const originalJson = res.json.bind(res);

    let apiKeyRejected = false;
    let pendingResponse = null;

    // 暫時 mock res 來看 API key middleware 的決定
    const mockRes = {
      setHeader: (...args) => { /* swallow */ },
      status: (code) => ({ json: (body) => { apiKeyRejected = true; pendingResponse = { code, body }; return mockRes; } }),
      headersSent: false,
      once: () => {},
    };

    apiKey(req, mockRes, (err) => {
      if (err) return next(err);
      if (apiKeyRejected) {
        // API key 失敗 → 試 OAuth（真的 res 給 OAuth 用）
        return oauth(req, res, next);
      }
      // API key 過 → next() 已被 apiKey middleware 呼叫
      return next();
    });
  };
}
```

**注意**：上面 `requireApiKeyOrOAuth` 用 mock res 攔截 API key 的 401 response、實作有點 hacky。**比較乾淨的做法**是兩個 middleware 都不直接 send response、而是 `next(err)` 給統一 error handler。但這需要改 `sendAuthError` 行為、變動範圍大。

**建議**：先用上面 hacky 版本 ship、後續 refactor 改成 `next(err)` 模式。

**或者**：更簡單——**直接砍 OAuth、只用 API key**（如果你確定沒其他 caller）。看下面 §3.5 決策樹。

### 3.4 Config 加 API key

```javascript
// src/config.js — 在 converter 段落內加：

// 在 schema / loadConfig 內：
const config = {
  // ... 既有欄位
  converter: {
    // ... 既有 audience / scopeWrite / scopeRead / tenantId
    apiKey: process.env.CONVERTER_API_KEY || '',  // Phase 0.8b 新增
  },
};

// 啟動時驗證（fail-fast）：
function validateConfig(config) {
  // 既有驗證...
  // 不強制 apiKey 必填（保留 OAuth-only 部署）— 但 startup log 印明確訊息
  if (!config.converter.apiKey) {
    // eslint-disable-next-line no-console
    console.warn(JSON.stringify({
      level: 'WARN',
      action: 'config.api_key_not_set',
      message: 'CONVERTER_API_KEY env not set; API key middleware will reject all requests',
      timestamp: new Date().toISOString(),
    }));
  } else {
    console.log(JSON.stringify({
      level: 'INFO',
      action: 'config.api_key_enabled',
      message: 'API key middleware enabled',
      // 不印 key 本身（對齊 visionA 的 api_key_set boolean pattern）
      api_key_length: config.converter.apiKey.length,
      timestamp: new Date().toISOString(),
    }));
  }
}
```

### 3.5 決策樹：純 API key vs 並存

**先回答**：除了 visionA 之外，**現在 / 短期內**還有別的 caller 會打 converter `/api/v1/*` 嗎？

| 答案 | 推薦 |
|------|------|
| 沒有 / 不確定 | **純 API key**（砍 OAuth）— 簡單、code 少、不用維護兩條 path |
| 有 / 短期會有 | **並存** — 用 §3.3 的 `requireApiKeyOrOAuth` |
| 只有 jimchen 手動測試會用 | **純 API key** + 提供 API key 給自己用即可 |

**我（jimchen）建議**：**純 API key**。理由：
- visionA 是唯一真實 caller
- 自己手動測試用同一把 API key 就好
- 並存增加 code 複雜度（`requireApiKeyOrOAuth` hacky）+ 維護成本
- 未來真有第二個 caller 再加 OAuth 回來不遲

→ **如果你選純 API key**：把 `requireAuth(scope)` 全部改成 `requireApiKey()`（4 個 endpoint）、砍掉 `auth/middleware.js` + `auth/jwks.js` + `auth/oauthClient.js`、`config.js` 移除 OAuth 相關欄位。

---

## 4. 任務 B — 新增 `GET /api/v1/jobs/:id/result` endpoint

對齊 visionA repo 的 **ADR-016 §1** spec。

### 4.1 API spec（**這是 visionA 端會打的契約、不可變動**）

| 欄位 | 值 |
|------|---|
| **Method + Path** | `GET /api/v1/jobs/:id/result` |
| **Auth** | `Authorization: Bearer <CONVERTER_API_KEY>` |
| **Query** | 無 |
| **Body** | 無 |

#### Response 200（成功）

```http
HTTP/1.1 200 OK
Content-Type: application/octet-stream
Content-Length: <NEF binary 大小>
Content-Disposition: attachment; filename="<source_filename_stem>_<chip>.nef"

<NEF binary stream>
```

**重要**：
- 走 **streaming**、不要先 buffer 整個檔（NEF 可能幾百 MB）
- `Content-Length` 必須帶（visionA 端會用來決定是否 timeout）
- `Content-Disposition` filename 由 converter 端構造（visionA 端會用 `defaultDownloadFilename` 覆寫、但 converter 也要給）

#### Response 4xx/5xx（錯誤）

| HTTP | error.code | 情境 |
|------|-----------|------|
| 401 | `invalid_token` | API key 不對 / missing |
| 404 | `job_not_found` | jobID 不存在 |
| 409 | `job_not_completed` | job 還沒 completed（still running / failed） |
| **410** | `result_expired` | **converter MinIO 已過期清除（7 天 expires_at 後）** |
| 502 | `storage_unavailable` | MinIO 連不上 |
| 503 | `service_unavailable` | 其他暫時性錯誤 |

Body 格式：
```json
{
  "error": {
    "code": "job_not_found",
    "message": "Job not found",
    "request_id": "<uuid>"
  }
}
```

### 4.2 實作（新增 `src/routes/v1/result.js`）

```javascript
// src/routes/v1/result.js
//
// GET /api/v1/jobs/:id/result — Phase 0.8b 為 visionA download 路徑新增。
//
// 對應 visionA repo 的：
//   - ADR-016 §1 API spec
//   - conversion.md v0.6 §2.3 ConverterClient.GetResult method
//
// 設計：
//   - Stream NEF binary 從 MinIO 回 caller（不 buffer）
//   - 4 種失敗情境對應 4xx：401 (auth) / 404 (job 不存在) / 409 (還沒完成) / 410 (過期清除)
//   - Phase 2 預留的 download-tokens endpoint (回 501) 仍保留、不撤銷

'use strict';

const express = require('express');
const { ApiError } = require('../../middleware/errorHandler');

/**
 * @param {object} deps
 * @param {object} deps.jobService - existing job service（getJob method）
 * @param {object} deps.minioStorage - storage facade（getObjectStream method）
 * @returns {express.Router}
 */
function createResultRouter(deps = {}) {
  const { jobService, minioStorage } = deps;
  if (!jobService) throw new Error('[createResultRouter] jobService is required');
  if (!minioStorage) throw new Error('[createResultRouter] minioStorage is required');

  const router = express.Router({ mergeParams: true });  // mergeParams 取 :id

  router.get('/', async (req, res, next) => {
    try {
      const jobId = req.params.id;
      if (!jobId) {
        return next(new ApiError(400, 'invalid_request', 'job id is required'));
      }

      // 1. 拿 job record
      const job = await jobService.getJob(jobId);
      if (!job) {
        return next(new ApiError(404, 'job_not_found', `Job ${jobId} not found`));
      }

      // 2. 檢查 status — 必須 completed 才能拿 result
      if (job.status !== 'completed') {
        return next(new ApiError(409, 'job_not_completed',
          `Job ${jobId} is ${job.status}; result only available after completion`));
      }

      // 3. 檢查 expires_at — 過期 NEF 已從 MinIO 清掉
      if (job.expires_at && new Date(job.expires_at) < new Date()) {
        return next(new ApiError(410, 'result_expired',
          `Job ${jobId} result expired at ${job.expires_at}; re-convert to get a fresh result`));
      }

      // 4. 解析 result NEF object key
      //    對齊 promote.js §extractSourceObjectKey 的雙路徑邏輯（新格式 result_object_keys / 舊格式 output）
      const nefKey = extractNefObjectKey(job);
      if (!nefKey) {
        return next(new ApiError(404, 'result_not_found',
          `Job ${jobId} completed but no NEF result available`));
      }

      // 5. 從 MinIO 拿 stream + metadata
      const result = await minioStorage.getObjectStream(nefKey);
      if (!result) {
        // MinIO 說沒這個 object（與 job record 不一致 — 通常是過期清除但 record 沒同步更新）
        return next(new ApiError(410, 'result_expired',
          `Job ${jobId} NEF object not found in storage (likely expired)`));
      }

      // 6. 寫 response headers
      res.setHeader('Content-Type', result.contentType || 'application/octet-stream');
      if (result.contentLength) {
        res.setHeader('Content-Length', String(result.contentLength));
      }
      const filename = buildFilename(job);
      res.setHeader('Content-Disposition',
        `attachment; filename="${filename}"`);

      // 7. Pipe stream 回 client
      result.stream.on('error', (streamErr) => {
        // 注意：此時 headers 可能已 sent、不能改 status code
        // 只能 destroy connection、讓 client 看到 ECONNRESET
        // eslint-disable-next-line no-console
        console.error(JSON.stringify({
          level: 'ERROR',
          action: 'result.stream_error',
          job_id: jobId,
          error: streamErr.message,
          timestamp: new Date().toISOString(),
        }));
        if (!res.destroyed) res.destroy(streamErr);
      });

      req.on('close', () => {
        // Client 中斷下載 — 主動關 stream 釋放 MinIO connection
        if (result.stream && typeof result.stream.destroy === 'function') {
          result.stream.destroy();
        }
      });

      result.stream.pipe(res);
    } catch (err) {
      return next(err);
    }
  });

  return router;
}

/**
 * 從 job record 拿 NEF object key（雙路徑：新格式 + 舊格式）。
 * 對齊 promote.js extractSourceObjectKey logic。
 */
function extractNefObjectKey(job) {
  // 新格式
  if (job.result_object_keys && typeof job.result_object_keys === 'object'
      && typeof job.result_object_keys.nef === 'string'
      && job.result_object_keys.nef.length > 0) {
    return job.result_object_keys.nef;
  }
  // 舊格式（向後相容）
  if (job.output && typeof job.output === 'object'
      && typeof job.output.nef_path === 'string'
      && job.output.nef_path.length > 0) {
    return job.output.nef_path;
  }
  return null;
}

/**
 * 構造 download filename。
 *
 * 規則：<source_filename_stem>_<chip>.nef
 * 例：yolov5s.onnx + KL720 → yolov5s_kl720.nef
 *
 * Fallback：job_<jobID>.nef（極端情況、source_filename 缺失）
 */
function buildFilename(job) {
  const sourceFilename = job.source_filename || '';
  const platform = (job.platform || '').toLowerCase();

  // 去副檔名
  const stem = sourceFilename.replace(/\.(onnx|tflite|pb|h5)$/i, '');

  if (stem && platform) {
    return `${stem}_${platform}.nef`;
  }
  return `job_${job.job_id || 'unknown'}.nef`;
}

module.exports = { createResultRouter, _internals: { extractNefObjectKey, buildFilename } };
```

### 4.3 Wire 進 v1 router

```javascript
// src/routes/v1/index.js — 加 result router：

const { createResultRouter } = require('./result');
const { requireApiKey } = require('../../auth/apiKeyMiddleware');  // 或 requireApiKeyOrOAuth

function createV1Router(deps) {
  const router = express.Router();

  // ... 既有 jobs / promote

  // 新：result endpoint（GET /api/v1/jobs/:id/result）
  // 注意：mount 在 /jobs/:id/result 上、mergeParams 取 :id
  router.use('/jobs/:id/result',
    requireApiKey(),  // 或 requireApiKeyOrOAuth('converter:job.read')
    createResultRouter({
      jobService: deps.jobService,
      minioStorage: deps.minioStorage,
    }));

  // errorHandler 仍掛最末
  router.use(errorHandler);
  return router;
}
```

### 4.4 Test（新增 `src/routes/v1/__tests__/result.integration.test.js`）

最少 cover 4 個情境：
- ✅ 200 happy path — completed job + 有 NEF + 不過期 → stream 整段、Content-Type / Content-Length / Content-Disposition 正確
- ❌ 404 job 不存在
- ❌ 409 job 還在 running
- ❌ 410 job 已過期（測 expires_at 在過去）
- ❌ 401 missing API key / wrong API key（如果用 requireApiKey）

對齊既有 `__tests__/getJobs.integration.test.js` 的 fixture / mock pattern。

---

## 5. 部署順序（重要 — visionA / converter 雙端對齊）

**錯誤的順序會讓 stage 整段 down**。正確順序：

```
Step 1: converter 端先實作完 + deploy（含 API key 驗證 + result endpoint）
  → 但 CONVERTER_API_KEY env 設成跟 visionA 一樣的值
  → 此時 converter 同時接 OAuth（既有）+ API key（新）
  → 既有 caller 不受影響

Step 2: 驗證 converter 新 endpoint 可用
  → 用 curl 打 GET /api/v1/jobs/<某個 completed job>/result 帶 Bearer <CONVERTER_API_KEY>
  → 確認回 200 + NEF binary stream

Step 3: visionA backend deploy（已 ready、commit 9e29ebf）
  → VISIONA_CONVERTER_API_KEY env 跟 CONVERTER_API_KEY 對齊
  → 此時 visionA 用 API key 打 converter、走新的 GetResult endpoint

Step 4: e2e 驗證
  → User upload → init → poll → promote → download
  → 全綠 = 完成

Step 5（選配）: 砍 converter OAuth path
  → 確認沒其他 caller 後、砍 OAuth middleware + jwks + oauthClient
  → 砍 MEMBER_CENTER_* env
```

---

## 6. CONVERTER_API_KEY 怎麼產

```bash
openssl rand -hex 32
# 輸出：64 個 hex 字元、例如：a3f9b2c1d8e7f6a5b4c3d2e1f0987654321fedcba9876543210abcdef1234567
```

**部署**：
- converter stage：放 `kneron_model_converter/apps/task-scheduler/.env` 或對應的 docker-compose env
- visionA stage：放 `~/visionA/.env.stage` 的 `VISIONA_CONVERTER_API_KEY=...`
- **兩端必須完全相同字串**

**安全**：
- ⚠️ **絕不進 git**（`.gitignore` 已 exclude `.env`、verify 一次）
- ⚠️ **絕不寫進 Slack / email / 對話**
- ⚠️ **絕不印 log**（middleware 內 log 用 `api_key_length` 或 `api_key_set: true` boolean、不印 key 本身）
- 每環境獨立 key（dev / stage / prod 各自 `openssl rand -hex 32`）

---

## 7. 既有 promote 流程不變

**重要**：converter promote 流程（`POST /api/v1/jobs/:id/promote` → converter 自己 PUT FAA）**完全不動**。

- visionA → converter promote 仍會打、但 visionA 拿到 promote response 後**不再從 FAA pull NEF**（v0.6 設計改成從 converter GetResult pull）
- converter promote response 仍含 `target_object_key`（在 FAA 上）— visionA 不再用、但 converter promote logic 保留
- converter → FAA 的 OAuth client_credentials 鏈條保留（這條不在本次 scope）

→ 換句話說，visionA 既走 `/promote`（promote 還在 FAA）+ 也走 `/result`（拿 NEF 給 user download），**兩個 endpoint 都會被 visionA 打**。

---

## 8. Phase 2 預留的 `/download-tokens` endpoint

`apps/task-scheduler/README.md` 寫的 Phase 2 預留：

```
POST /api/v1/jobs/:id/download-tokens   converter:job.read   Phase 2 預留，回 501
```

**這個跟 ADR-016 沒衝突、保留**。`/download-tokens` 是給未來 browser 直連 converter download 用的 short-TTL token；本次 `/result` 是給 visionA backend 用的 stream proxy 入口。兩個 endpoint 用途不同。

---

## 9. 簡化版 checklist

如果你想跳過上面細節、只要可執行 checklist：

### Phase A — API key middleware
- [ ] 新建 `src/auth/apiKeyMiddleware.js`（複製 §3.2 code）
- [ ] 修 `src/config.js` 加 `converter.apiKey` 欄位、讀 `CONVERTER_API_KEY` env
- [ ] 修 `src/routes/v1/index.js` 把 `requireAuth(scope)` 全改 `requireApiKey()`（如果走純 API key）
- [ ] 加 unit test 對 `apiKeyMiddleware`（happy / missing / wrong key / constant-time 行為）
- [ ] 修 `.env.example` 加 `CONVERTER_API_KEY=` placeholder
- [ ] 修 README.md 認證段落（OAuth → API key）

### Phase B — `/result` endpoint
- [ ] 新建 `src/routes/v1/result.js`（複製 §4.2 code）
- [ ] 修 `src/routes/v1/index.js` 加 result router wire
- [ ] 加 integration test cover 4 情境（200 / 404 / 409 / 410）
- [ ] 修 `apps/task-scheduler/README.md` 加 `/result` endpoint 描述

### Phase C — 部署
- [ ] `openssl rand -hex 32` 產 stage `CONVERTER_API_KEY`
- [ ] 設到 converter stage `.env` / docker-compose env
- [ ] 設到 visionA stage `.env.stage` `VISIONA_CONVERTER_API_KEY=<same>`
- [ ] redeploy converter
- [ ] curl verify `/result` endpoint 用 API key 可拿
- [ ] redeploy visionA
- [ ] e2e 跑完整 upload → poll → promote → download

---

## 10. 參考文件（visionA repo）

| 文件 | 用途 |
|------|------|
| `docs/autoflow/04-architecture/adr/adr-015-server-to-server-api-key.md` v2.1 | 為什麼用 API key、§3.5.1 Go reference middleware（要 port 成 Node） |
| `docs/autoflow/04-architecture/adr/adr-016-download-via-converter.md` v1.0 | 為什麼加 `/result` endpoint、完整 6 個替代方案分析 |
| `docs/autoflow/04-architecture/conversion.md` v0.6.1 §2.3 | ConverterClient.GetResult method spec（visionA 端） |
| `docs/autoflow/04-architecture/api/api-conversion.md` v0.6 §4 | download endpoint 對外契約（visionA backend → browser） |

---

## 11. 給未來自己（jimchen）的提醒

1. **不要 assume MC team 會配合**：5/2 寫 ADR-014 時 assume MC 有 delegated token endpoint、結果根本沒有。**動 MC 之前先 grep MC source**。
2. **converter / FAA / MC 三方都 grep 一次**：以後做任何跨 repo integration design，**寫 ADR 前先 grep 每一方的 source code 確認 endpoint 真的存在**。
3. **e2e 要早跑**：Phase 0.8 設計到 5/4 完工、5/9 才實機跑 e2e 撞牆。**整合 design 完成、code 還沒寫前、先用 curl 跑一遍真實 e2e**（可以一些 endpoint mock、但起碼確認 auth / token / scope 鏈通）。