// -------- tests/unit/_helpers/mockHttpBridge.ts  (公开 API 锁定) --------

/**
 * ProviderLike / EmitterLike 与 httpBridge 源码保持一致;
 * 直接从源码 import type,N4 测试可复用同一类型符号。
 */
export type ProviderLike<Data, Params = undefined> = {
  provider: (handler: (params: Params) => Promise<Data>) => void;
  invoke: Params extends undefined ? () => Promise<Data> : (params: Params) => Promise<Data>;
};

export type EmitterLike<Params = undefined> = {
  on: (callback: Params extends undefined ? () => void : (params: Params) => void) => () => void;
  emit: Params extends undefined ? () => void : (params: Params) => void;
};

/**
 * HTTP method literals accepted by route stubs.
 */
export type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';

/**
 * Handler registered for a single (method, pathPattern) pair.
 *
 * - `pathPattern` 可以是精确字符串(如 `/api/providers`)或以 `:name` 占位符
 *   定义的路径(如 `/api/providers/:id`)。占位符按段匹配,`params` 参数会
 *   携带已 decode 的段值。
 * - Query string 在匹配前会被剥离,并以对象形式塞进 `query`。
 * - `body` 对有 body 的 verb(POST/PUT/PATCH)是调用方传入的已序列化 JSON
 *   payload;对无 body 的 verb(GET/DELETE)是 `undefined`。
 * - handler 返回值就是被测代码看到的 "unwrapped" data(即相当于后端
 *   `{ success, data }` 中的 data);mock 不做 envelope 包裹。
 * - 抛错会被 invoke 直接透传为 rejection(用来模拟 BackendHttpError 等)。
 */
export type MockHttpHandler<TBody = unknown, TData = unknown> = (ctx: {
  method: HttpMethod;
  path: string;
  pathPattern: string;
  params: Record<string, string>;
  query: Record<string, string>;
  body: TBody | undefined;
}) => TData | Promise<TData>;

export type MockHttpBridgeOptions = {
  /**
   * 未匹配路由时的行为,默认 `'throw'`(抛 "unexpected call" Error)。
   * 设为 `'warn'`:console.warn 一次后返回 `undefined` — 仅用于调试,
   * 不得在常规测试里使用(UC-F-4 要求严格断言,未匹配路由一律视为 bug)。
   */
  unmatched?: 'throw' | 'warn';
};

export interface MockHttpBridge {
  // --- route registration (return `this` 以支持链式调用) ---
  onGet<TData = unknown>(pathPattern: string, handler: MockHttpHandler<undefined, TData>): this;
  onPost<TBody = unknown, TData = unknown>(pathPattern: string, handler: MockHttpHandler<TBody, TData>): this;
  onPut<TBody = unknown, TData = unknown>(pathPattern: string, handler: MockHttpHandler<TBody, TData>): this;
  onPatch<TBody = unknown, TData = unknown>(pathPattern: string, handler: MockHttpHandler<TBody, TData>): this;
  onDelete<TData = unknown>(pathPattern: string, handler: MockHttpHandler<undefined, TData>): this;

  // --- WS event emission ---
  /**
   * 向所有通过 `wsEmitter(eventName).on(cb)` 订阅的 cb 同步派发 payload。
   * 同步派发:call stack 解开时所有 listener 已收到事件,测试可立即断言
   * (与 `@vitest-environment node` + `setImmediate`/microtask 无关)。
   * 若 handler 抛错,mock 会 console.warn 但不会打断 emit。
   */
  emit(eventName: string, payload: unknown): void;

  // --- inspection helpers (测试断言用) ---
  /** 已记录的调用流水,按时间先后(不含重置前的历史)。 */
  calls: ReadonlyArray<{
    method: HttpMethod;
    path: string;
    pathPattern: string;
    params: Record<string, string>;
    query: Record<string, string>;
    body: unknown;
  }>;
  /** 已登记的 (method, pathPattern) 对数量,用于断言"setup 齐全"。 */
  readonly routeCount: number;
  /** 已登记的 WS listener 数量(所有 event 汇总)。 */
  readonly wsListenerCount: number;

  // --- lifecycle ---
  /**
   * 清空路由注册、WS listener、calls 历史。
   * `beforeEach` 里推荐调用;仅影响由本 helper 创建的实例,不触碰 vitest
   * 的 `vi.mock()` 注册。
   */
  reset(): void;

  /**
   * 返回一个可以直接 `vi.mock('@/common/adapter/httpBridge', () => ...)`
   * 使用的对象。键名与 httpBridge.ts 的**所有**具名导出一一对应,保证
   * `vi.mock` 工厂替换后的模块 shape 完全匹配(否则 TS 会报缺失导出)。
   */
  asModule(): {
    httpGet: typeof import('@/common/adapter/httpBridge').httpGet;
    httpPost: typeof import('@/common/adapter/httpBridge').httpPost;
    httpPut: typeof import('@/common/adapter/httpBridge').httpPut;
    httpPatch: typeof import('@/common/adapter/httpBridge').httpPatch;
    httpDelete: typeof import('@/common/adapter/httpBridge').httpDelete;
    stubProvider: typeof import('@/common/adapter/httpBridge').stubProvider;
    withResponseMap: typeof import('@/common/adapter/httpBridge').withResponseMap;
    wsEmitter: typeof import('@/common/adapter/httpBridge').wsEmitter;
    wsMappedEmitter: typeof import('@/common/adapter/httpBridge').wsMappedEmitter;
    stubEmitter: typeof import('@/common/adapter/httpBridge').stubEmitter;
    httpRequest: typeof import('@/common/adapter/httpBridge').httpRequest;
    getBaseUrl: typeof import('@/common/adapter/httpBridge').getBaseUrl;
    BackendHttpError: typeof import('@/common/adapter/httpBridge').BackendHttpError;
    isBackendHttpError: typeof import('@/common/adapter/httpBridge').isBackendHttpError;
  };
}

/**
 * 创建一个新的 mock 实例。
 * @param options.unmatched — 未匹配路由行为,默认 'throw'(见 MockHttpBridgeOptions)
 */
export function createMockHttpBridge(options?: MockHttpBridgeOptions): MockHttpBridge;

/**
 * 便捷函数:对传入的 `mock` 调用 `.reset()`。语义上等同;保留独立导出
 * 以便 N4 teammate 写 `beforeEach(() => resetMockHttpBridge(mock))`。
 */
export function resetMockHttpBridge(mock: MockHttpBridge): void;

# 执行目录
cd /Users/zhoukai/Documents/github/AionUi

# 工具可用性
node --version            # 预期: v22.x
bun --version             # 预期: 1.x
bunx vitest --version     # 预期: vitest/4.x darwin-arm64 node-v22.x
bunx tsc --version        # 预期: Version 5.x
which prek                # 预期: 非空路径
prek --version            # 预期: 可执行,版本号可读
which gh                  # 预期: 非空路径(handoff 备用,不主动触发 CI)
git --version             # 预期: 2.x

npm install -g @j178/prek
prek --version     # 复验

bun install
bunx vitest --version

cd /Users/zhoukai/Documents/github/AionUi

git status --porcelain
# 预期:无输出(空行)。非空 → STOP,escalate 给 team-lead。

git remote -v | head -4
# 预期:包含 origin  [email protected]:iOfficeAI/AionUi.git

git fetch origin
# 预期:无错误

mkdir -p /tmp/n3-baseline

# 上游 SHA(用于 handoff)
git rev-parse origin/feat/n2-legacy-test-cleanup > /tmp/n3-baseline/n2-sha.txt
cat /tmp/n3-baseline/n2-sha.txt
# 预期:ae1d150f3ae2d942bd3d9aeb2139932f8c33f19f

git rev-parse origin/feat/backend-migration > /tmp/n3-baseline/base-sha.txt
cat /tmp/n3-baseline/base-sha.txt
# 预期:e4cdff41fb7eb154a43dbe5568bfb2edc7fb7ea2

# 当前 tests/unit/ 文件数(基线 = 只有 12 个 .gitkeep + 空目录)
find tests/unit -type f | wc -l > /tmp/n3-baseline/test-file-count.txt
cat /tmp/n3-baseline/test-file-count.txt
# 预期:12(仅 .gitkeep)

# 当前 vitest 行为基线(空集合退出 1)
bunx vitest run --reporter=verbose 2>&1 | tee /tmp/n3-baseline/vitest.log | tail -5
echo "exit=$?" >> /tmp/n3-baseline/vitest.log
# 预期:"No test files found, exiting with code 1" — 已知 N2 偏离

cd /Users/zhoukai/Documents/github/AionUi

git checkout -b feat/n3-test-rewrite-adapter-common origin/feat/n2-legacy-test-cleanup
# 预期:Switched to a new branch 'feat/n3-test-rewrite-adapter-common'

git rev-parse --abbrev-ref HEAD
# 预期:feat/n3-test-rewrite-adapter-common

git merge-base --is-ancestor origin/feat/n2-legacy-test-cleanup HEAD && echo "base OK"
# 预期:base OK

git log --oneline -3
# 预期:ae1d150f3 docs(n2): add team-lead adjudication ... 之类

bun install
# 预期:无错误,lockfile 保持干净

git diff bun.lock
# 预期:无输出(bun install 未改 lockfile)。若改了 → STOP,escalate。

# 骨架目录验证(N2 已建)
for d in _helpers common-adapter common-config; do
  test -d "tests/unit/$d" || { echo "MISSING: tests/unit/$d"; exit 1; }
done
echo "N2 skeleton OK"
# 预期:N2 skeleton OK

ls tests/unit/_helpers/
# 预期:.gitkeep

git rm tests/unit/_helpers/.gitkeep
# 预期:rm 'tests/unit/_helpers/.gitkeep'

/**
 * @license
 * Copyright 2025 AionUi (aionui.com)
 * SPDX-License-Identifier: Apache-2.0
 *
 * AionUi N3 mock HTTP/WS bridge helper.
 *
 * Public API frozen in docs/backend-migration/plans/2026-05-08-n3-test-rewrite-adapter-common.md §2.1.
 * N4 teammates: do NOT change the exported signatures. If a new capability is
 * needed, escalate to the team-lead instead of patching this file.
 */

bunx tsc --noEmit 2>&1 | tail -20
# 预期:退出 0,无输出

bunx vitest run tests/unit/_helpers --reporter=verbose 2>&1 | tee /tmp/n3-phase2-vitest.log | tail -30
echo "exit=$?"
# 预期:退出 0;T6.1..T6.8 全部 ✓;passed >= 8

git add tests/unit/_helpers/
git status --short
# 预期:
#   A  tests/unit/_helpers/mockHttpBridge.test.ts
#   A  tests/unit/_helpers/mockHttpBridge.ts
#   D  tests/unit/_helpers/.gitkeep

git commit -m "test(n3): add mockHttpBridge helper with frozen public signatures

Helper backs T6 in the N3 test checklist and is the single entry point for
N4's 54-file domain tests. Public API (functions, types, MockHttpBridge
interface) is frozen per docs/backend-migration/plans/2026-05-08-n3-test-rewrite-adapter-common.md
§2.1 — N4 must not change these signatures."

git rm tests/unit/common-adapter/.gitkeep

bunx vitest run tests/unit/common-adapter/apiModelMapper.test.ts --reporter=verbose 2>&1 | tee /tmp/n3-phase3-vitest.log | tail -30
echo "exit=$?"
# 预期:退出 0;passed >= 8

git add tests/unit/common-adapter/
git commit -m "test(n3): add apiModelMapper unit tests (T1)

Cover toApiModel/toApiModelOptional roundtrip, fromApiConversation model
hydration + custom_workspace inference, and fromApiPaginatedConversations
item mapping. No mock needed — pure function suite."

bunx vitest run tests/unit/common-adapter/searchMapper.test.ts --reporter=verbose 2>&1 | tee /tmp/n3-phase4-vitest.log | tail -30
echo "exit=$?"
# 预期:退出 0;passed >= 5

git add tests/unit/common-adapter/searchMapper.test.ts
git commit -m "test(n3): add searchMapper unit tests (T2)

Cover fromApiSearchResult pagination pass-through and per-item field
mapping (conversation via fromApiConversation, message fields pass-through)."

bunx vitest run tests/unit/common-adapter/httpBridge.test.ts --reporter=verbose 2>&1 | tee /tmp/n3-phase5-vitest.log | tail -30
echo "exit=$?"
# 预期:退出 0;passed >= 12

git add tests/unit/common-adapter/httpBridge.test.ts
git commit -m "test(n3): add httpBridge unit tests (T3)

Cover getBaseUrl three-branch port resolution (window/globalThis/fallback),
httpGet/httpPost/httpPut/httpPatch/httpDelete factory shape and fetch
integration, BackendHttpError envelope parsing with code/status/
backendMessage, stubProvider default + warn, withResponseMap mapping, and
wsEmitter/wsMappedEmitter subscribe/dispatch via stubbed WebSocket."

git rm tests/unit/common-config/.gitkeep

import { vi } from 'vitest';

vi.mock('@/common/adapter/httpBridge', () => ({
  httpRequest: vi.fn(),
  // 其他导出不需要,不会被 configMigration 直接 import
}));

vi.mock('@/common', () => ({
  ipcBridge: {
    mode: {
      listProviders: { invoke: vi.fn(), provider: vi.fn() },
      createProvider: { invoke: vi.fn(), provider: vi.fn() },
    },
  },
}));

// 其后再 import 被测模块
import { migrateConfigStorage, migrateProviders } from '@/common/config/configMigration';
import { httpRequest } from '@/common/adapter/httpBridge';
import { ipcBridge } from '@/common';

bunx vitest run tests/unit/common-config/configMigration.test.ts --reporter=verbose 2>&1 | tee /tmp/n3-phase6-vitest.log | tail -30
echo "exit=$?"
# 预期:退出 0;passed >= 8

git add tests/unit/common-config/configMigration.test.ts
git commit -m "test(n3): add configMigration unit tests (T4)

Cover migrateConfigStorage empty/normal/null/error paths (httpRequest PUT
to /api/settings/client) and migrateProviders guard flag, backend-populated
skip, bulk import with per-item failure tolerance, and legacy camelCase →
snake_case field mapping (bedrock_config, model_health)."

import { vi } from 'vitest';

// In-memory stub for @office-ai/platform storage.
vi.mock('@office-ai/platform', () => {
  function buildStorage<T extends Record<string, unknown>>(namespace: string) {
    const store = new Map<keyof T, unknown>();
    return {
      namespace,
      get: vi.fn(async <K extends keyof T>(k: K): Promise<T[K] | undefined> => store.get(k) as T[K] | undefined),
      set: vi.fn(async <K extends keyof T>(k: K, v: T[K]): Promise<void> => {
        store.set(k, v);
      }),
      remove: vi.fn(async <K extends keyof T>(k: K): Promise<void> => {
        store.delete(k);
      }),
    };
  }
  return {
    storage: { buildStorage },
    // 其它 @office-ai/platform 导出不被 storage.ts 直接用,无需 stub
  };
});

import { ConfigStorage, EnvStorage, BUILTIN_IMAGE_GEN_ID } from '@/common/config/storage';

bunx vitest run tests/unit/common-config/storage.test.ts --reporter=verbose 2>&1 | tee /tmp/n3-phase7-vitest.log | tail -30
echo "exit=$?"
# 预期:退出 0;passed >= 5

git add tests/unit/common-config/storage.test.ts
git commit -m "test(n3): add storage runtime exports unit tests (T5)

Cover BUILTIN_IMAGE_GEN_ID constant, ConfigStorage/EnvStorage namespaces
and set/get roundtrip via in-memory @office-ai/platform mock."

cd /Users/zhoukai/Documents/github/AionUi

# 1. Lint
bun run lint 2>&1 | tee /tmp/n3-phase8-lint.log | tail -30
echo "exit=$?"
# 预期:退出 0(允许 warnings,不允许 errors)。输出末尾:"Found N warnings and 0 errors."

# 2. TSC
bunx tsc --noEmit 2>&1 | tee /tmp/n3-phase8-tsc.log | tail -30
echo "exit=$?"
# 预期:退出 0,无输出行 / "error TS..."

# 3. Vitest full
bunx vitest run --reporter=verbose 2>&1 | tee /tmp/n3-phase8-vitest.log | tail -40
echo "exit=$?"
# 预期:退出 0;测试数 >= 30(清单最低)。按 requirements 期望 30-50
#       范围。关键断言行:"Tests  N passed (N)" 且无 failed/skipped。

# 4. prek
prek run --from-ref origin/feat/backend-migration --to-ref HEAD 2>&1 | tee /tmp/n3-phase8-prek.log | tail -30
echo "exit=$?"
# 预期:退出 0;所有 hook Passed 或 Skipped(无 Failed)。
#       如果 oxfmt 自动修复后 Passed,也算 OK;若报 Failed 而未修复,
#       检查 /tmp/n3-phase8-prek.log 的输出,跑对应 auto-fix 命令后重跑。

bunx vitest run --coverage 2>&1 | tee /tmp/n3-phase8-coverage.log | grep -E "(apiModelMapper|searchMapper|httpBridge|configMigration|storage|File).*\|"
# 预期:输出 6 个文件的 % Stmts、% Branch、% Funcs、% Lines 列。handoff 里贴原表。
#       若 apiModelMapper / searchMapper 覆盖 < 70% → 检查是否漏了某个分支。
#       httpBridge 允许 < 80%(WS 重连的 scheduleWsReconnect 分支较难穷尽)。

grep -rnE "\.skip\(|\.todo\(|test\.skip|it\.skip|xtest\(|xit\(" tests/unit/ | tee /tmp/n3-phase8-skip.log
# 预期:无输出(空)。非空 → UC-F-4 违规,必须改成正常 test 或删除。

for f in \
  tests/unit/_helpers/mockHttpBridge.ts \
  tests/unit/_helpers/mockHttpBridge.test.ts \
  tests/unit/common-adapter/apiModelMapper.test.ts \
  tests/unit/common-adapter/searchMapper.test.ts \
  tests/unit/common-adapter/httpBridge.test.ts \
  tests/unit/common-config/configMigration.test.ts \
  tests/unit/common-config/storage.test.ts; do
  test -f "$f" || { echo "MISSING: $f"; exit 1; }
done
echo "N3 file checklist OK"
# 预期:N3 file checklist OK

grep -rn "mockHttpBridge" tests/unit/common-adapter tests/unit/common-config 2>&1 | tee /tmp/n3-phase8-helper-use.log
# 预期:**至少一行输出**,确认 helper 已被消费。
#       **注意**:requirements §验收标准第 2 条要求 helper 被至少 1 个 N3 测试 import,
#       T3-T7 里至少一个要用它。T1 / T2(纯函数)无需 mock,T3(直测 httpBridge)
#       不用 mock,T4(configMigration)在 Phase 6 中推荐复用 asModule() 的写法
#       替代手写 httpRequest mock,以满足此要求。
#
#       若 0 行输出 → executor 回到 Phase 6,把 configMigration.test.ts 的
#       httpRequest mock 改为 createMockHttpBridge().asModule(),或在 T4 之外
#       新增一个使用 helper 的小 demo 测试(不算入 T1-T6 计数)。

cd /Users/zhoukai/Documents/github/AionUi

git fetch origin feat/backend-migration
# 预期:无错误

git log --oneline HEAD..origin/feat/backend-migration | head -10
# 情况 A(推荐):无输出 → 基线没有新 commit,跳到步骤 9.3(complete 复跑)
# 情况 B:有输出 → 执行步骤 9.2

git rev-parse origin/feat/backend-migration > /tmp/n3-phase9-base-sha.txt
cat /tmp/n3-phase9-base-sha.txt
# 期望与 Phase 0 的 base-sha.txt 对比:是否变化

git merge origin/feat/backend-migration --no-ff -m "chore(n3): sync with feat/backend-migration"
# 预期无冲突 → "Merge made by the 'ort' strategy"

# 若冲突:
#   - 简单文件级冲突 + executor 有信心 → 手动 resolve → git add + git commit
#   - 复杂冲突(tests/unit/** 上游动了 / common/adapter/** 上游改了)→ STOP,escalate

# Step 4 标准顺序
bun run lint 2>&1 | tee /tmp/n3-phase9-lint.log | tail -10
echo "exit=$?"
# 预期:退出 0

bunx tsc --noEmit 2>&1 | tee /tmp/n3-phase9-tsc.log | tail -10
echo "exit=$?"
# 预期:退出 0

bunx vitest run --reporter=verbose 2>&1 | tee /tmp/n3-phase9-vitest.log | tail -10
echo "exit=$?"
# 预期:退出 0;passed 与 Phase 8 一致 / 可接受增加(上游加 test 的话)

prek run --from-ref origin/feat/backend-migration --to-ref HEAD 2>&1 | tee /tmp/n3-phase9-prek.log | tail -10
echo "exit=$?"
# 预期:退出 0

git push -u origin feat/n3-test-rewrite-adapter-common
# 预期:成功 + 打印 "Branch 'feat/n3-test-rewrite-adapter-common' set up to track..."

git rev-parse HEAD > /tmp/n3-phase9-final-sha.txt
cat /tmp/n3-phase9-final-sha.txt
# 预期:输出 N3 最终 SHA,写进 handoff

git add docs/backend-migration/handoffs/N3-outcome.md
git commit -m "docs(n3): add N3 handoff with UC-F evidence and locked mockHttpBridge signature

Records 7 deliverables (helper + 6 test files), quality gate outputs
(lint / tsc / vitest / prek), coverage snapshot for the 6 source files,
and the frozen mockHttpBridge public API that N4 must consume unchanged."

git push origin feat/n3-test-rewrite-adapter-common
# 预期:成功,带 handoff 的 N3 分支 ready

git rev-parse HEAD > /tmp/n3-phase10-final-sha.txt
# 最终 SHA,handoff 里可能已写,push 后用此 SHA 更新一次

SendMessage({
  to: "team-lead",
  message: "N3 完成。
  - 分支:feat/n3-test-rewrite-adapter-common
  - SHA:<从 /tmp/n3-phase10-final-sha.txt 读>
  - 基线同步:origin/feat/backend-migration @ <从 /tmp/n3-phase9-base-sha.txt 读> 已合入(或 Already up to date)
  - Handoff:docs/backend-migration/handoffs/N3-outcome.md
  - Test files delivered: 6(helper + 5 domain tests;helper 被 T4 消费)
  - Total tests passed: <N>(vitest full run)
  - UC-F 证据:命令输出 ✓ / helper-use ✓ / 无 skip ✓ / 基线后复跑 ✓ / Backend 改动 无
  - 签名锁定:见 handoff §锁定的 helper 签名
  - 偏离计划:<无 / 列出>
  请启动 N4 plan-writer。"
})

# 放弃所有未 push 的本地提交
git checkout feat/n2-legacy-test-cleanup      # 或 origin/feat/n2-legacy-test-cleanup
git branch -D feat/n3-test-rewrite-adapter-common
# 完全回到 N2 状态

# 删远程分支,本地重做
git push origin --delete feat/n3-test-rewrite-adapter-common
git checkout feat/n2-legacy-test-cleanup
git branch -D feat/n3-test-rewrite-adapter-common
# 重新 checkout 新分支开工(Phase 1 起)