refactor: 重整运行时与通用基础层

docs/superpowers/plans/2026-06-15-api-admin-full-refactor-v3.md

@@ -653,7 +653,7 @@ git -C D:\MyFiles\KT commit -m "docs: 记录第三期迁移准备"
 - Create: `D:\MyFiles\KT\Node\kt-template-online-api\src\runtime\client\runtime-docker-client.types.ts`
 - Create: `D:\MyFiles\KT\Node\kt-template-online-api\test\runtime\runtime-client-contract.spec.ts`
 
-- [ ] **Step 1: Write RED contract test**
+- [x] **Step 1: Write RED contract test**
 
 Test expectations:
 
@@ -673,15 +673,15 @@ describe('runtime client contracts', () => {
 });
 ```
 
-- [ ] **Step 2: Create type files**
+- [x] **Step 2: Create type files**
 
 Define request/response types for HTTP, process, and Docker calls. Each request type includes `timeoutMs`, `correlationId`, and `safeSummary`.
 
-- [ ] **Step 3: Export contracts**
+- [x] **Step 3: Export contracts**
 
 Modify `src/runtime/index.ts` to export the new client contract types.
 
-- [ ] **Step 4: Verify**
+- [x] **Step 4: Verify**
 
 Run:
 
@@ -699,7 +699,7 @@ Expected: PASS.
 - Modify: `D:\MyFiles\KT\Node\kt-template-online-api\src\common\common.module.ts`
 - Test: existing `test/common/*.spec.ts`
 
-- [ ] **Step 1: List exported common symbols**
+- [x] **Step 1: List exported common symbols**
 
 Run:
 
@@ -707,11 +707,13 @@ Run:
 Get-Content D:\MyFiles\KT\Node\kt-template-online-api\src\common\index.ts
 ```
 
-- [ ] **Step 2: Remove only exports made obsolete by new runtime contracts**
+- [x] **Step 2: Remove only exports made obsolete by new runtime contracts**
 
 Keep response wrappers, filters, interceptors, time decorators, Snowflake, logger config, and generic tools.
 
-- [ ] **Step 3: Verify common tests**
+Actual note: no runtime client or now-obsolete export was present in `src/common/index.ts` or `src/common/common.module.ts`, so Common stayed unchanged to avoid artificial churn.
+
+- [x] **Step 3: Verify common tests**
 
 Run:
 
@@ -728,7 +730,7 @@ Expected: PASS.
 - Modify: `D:\MyFiles\KT\TASKS.md`
 - API and root commits.
 
-- [ ] **Step 1: Run Batch 1 review gates**
+- [x] **Step 1: Run Batch 1 review gates**
 
 Run MCP tools:
 
@@ -739,7 +741,7 @@ kt_global_code_review(projects=["api","root"], contentScanMode="changed", includ
 
 Expected: required docs resolved and `findings=[]`.
 
-- [ ] **Step 2: Commit**
+- [x] **Step 2: Commit**
 
 Run:
 

src/runtime/client/runtime-docker-client.types.ts

@@ -0,0 +1,26 @@
+export type RuntimeDockerClientAction =
+  | 'exec'
+  | 'run'
+  | 'start'
+  | 'stop'
+  | 'restart'
+  | 'logs'
+  | 'inspect';
+
+export interface RuntimeDockerClientRequest {
+  action: RuntimeDockerClientAction;
+  containerName?: string;
+  image?: string;
+  command?: string[];
+  timeoutMs: number;
+  correlationId: string;
+  safeSummary: string;
+}
+
+export interface RuntimeDockerClientResponse {
+  exitCode: number | null;
+  output: string;
+  timeoutMs: number;
+  correlationId: string;
+  safeSummary: string;
+}

src/runtime/client/runtime-http-client.types.ts

@@ -0,0 +1,19 @@
+export interface RuntimeHttpClientRequest {
+  url: string;
+  method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD' | 'OPTIONS';
+  headers?: Record<string, string>;
+  body?: string | Record<string, unknown> | ArrayBuffer | null;
+  timeoutMs: number;
+  correlationId: string;
+  safeSummary: string;
+  redactHeaders?: string[];
+}
+
+export interface RuntimeHttpClientResponse {
+  statusCode: number;
+  headers: Record<string, string>;
+  body: string;
+  timeoutMs: number;
+  correlationId: string;
+  safeSummary: string;
+}

src/runtime/client/runtime-process-client.types.ts

@@ -0,0 +1,18 @@
+export interface RuntimeProcessClientRequest {
+  command: string;
+  args: string[];
+  cwd?: string;
+  timeoutMs: number;
+  correlationId: string;
+  safeSummary: string;
+}
+
+export interface RuntimeProcessClientResponse {
+  exitCode: number | null;
+  signal?: NodeJS.Signals | null;
+  stdout: string;
+  stderr: string;
+  timeoutMs: number;
+  correlationId: string;
+  safeSummary: string;
+}

src/runtime/index.ts

@@ -1,5 +1,8 @@
 export * from './config/runtime-config.service';
 export * from './config/runtime-config.types';
+export * from './client/runtime-docker-client.types';
+export * from './client/runtime-http-client.types';
+export * from './client/runtime-process-client.types';
 export * from './errors/runtime-error.types';
 export * from './evidence/runtime-evidence.service';
 export * from './evidence/runtime-evidence.types';

test/runtime/runtime-client-contract.spec.ts

@@ -0,0 +1,47 @@
+import type {
+  RuntimeDockerClientRequest,
+  RuntimeHttpClientRequest,
+  RuntimeProcessClientRequest,
+} from '../../src/runtime';
+
+describe('runtime client contracts', () => {
+  it('uses explicit timeout and redaction fields for external calls', () => {
+    const request: RuntimeHttpClientRequest = {
+      url: 'https://example.invalid',
+      method: 'GET',
+      timeoutMs: 1000,
+      correlationId: 'runtime-contract-test',
+      safeSummary: 'fetch runtime contract fixture',
+      redactHeaders: ['authorization'],
+    };
+
+    expect(request.timeoutMs).toBeGreaterThan(0);
+    expect(request.redactHeaders).toContain('authorization');
+    expect(request.safeSummary).toContain('runtime contract');
+  });
+
+  it('keeps process and docker requests explicit without secret-bearing fields', () => {
+    const processRequest: RuntimeProcessClientRequest = {
+      command: 'pnpm',
+      args: ['run', 'typecheck'],
+      cwd: 'D:\\MyFiles\\KT\\Node\\kt-template-online-api',
+      timeoutMs: 1000,
+      correlationId: 'runtime-contract-test',
+      safeSummary: 'run api typecheck',
+    };
+
+    const dockerRequest: RuntimeDockerClientRequest = {
+      action: 'exec',
+      containerName: 'kt-template-online-api',
+      command: ['pnpm', 'run', 'typecheck'],
+      timeoutMs: 1000,
+      correlationId: 'runtime-contract-test',
+      safeSummary: 'exec api typecheck in container',
+    };
+
+    expect(processRequest.command).toBe('pnpm');
+    expect(processRequest.args).toContain('typecheck');
+    expect(dockerRequest.action).toBe('exec');
+    expect(dockerRequest.command).toContain('typecheck');
+  });
+});