# QQBot NapCat WebUI Gateway Implementation Plan

> **Execution note:** Execute this plan task-by-task with the KT-local workflow and use the checkboxes to track plan state.

**Goal:** Build an independent NapCat WebUI Gateway service and an Admin second-level route that opens the selected QQBot account's original NapCat WebUI with full operation capability and route-bound session cleanup.

**Architecture:** The API service remains the Admin-authenticated authority that resolves a QQBot account to its active NapCat container and requests a short-lived Gateway session. The new `kt-napcat-webui-gateway` process owns session storage, one-time bootstrap tickets, NapCat WebUI credential exchange, HTTP/static/API/WebSocket proxying, and audit events. Admin opens `/qqbot/account/:accountId/napcat-webui`, creates a route-bound session, heartbeats while mounted, and revokes on route leave.

**Tech Stack:** NestJS 11, Express adapter, TypeORM/MySQL, Redis through `@nestjs-modules/ioredis` + `ioredis`, `http-proxy-middleware` for Express/WebSocket proxying, Vue 3 TSX, VueUse `useIntervalFn`, Vben Admin, antdv-next, K8s, Jenkins, Caddy/Admin domain route.

---

## Source References

- Spec: `docs/specs/2026-06-24-qqbot-napcat-webui-gateway-design.md`
- Chinese spec: `docs/specs/2026-06-24-qqbot-napcat-webui-gateway-design.zh-CN.md`
- `http-proxy-middleware` supports Express proxy middleware and WebSocket upgrades through `ws: true` and upgrade handling: <https://github.com/chimurai/http-proxy-middleware>
- `http-proxy-middleware` WebSocket recipe documents `ws: true`, manual `server.on('upgrade', proxy.upgrade)`, multiple targets, and path rewriting: <https://github.com/chimurai/http-proxy-middleware/blob/master/recipes/websocket.md>
- `@nestjs-modules/ioredis` provides Nest `RedisModule.forRoot` and `@InjectRedis()` over `ioredis`: <https://github.com/nest-modules/ioredis>
- `connect-redis` is intentionally not used because it is an Express session store, while this Gateway needs API-created sessions, one-time tickets, target metadata, concurrent-session revocation, Credential cache, and audit events: <https://github.com/tj/connect-redis>
- VueUse `useIntervalFn` wraps `setInterval` with pause/resume controls and is already available in Admin: <https://vueuse.org/shared/useintervalfn/>

## Scope Check

This is one deployable workstream even though it spans API, Gateway, Admin, and deployment files. The pieces are not independently useful: Admin cannot load a WebUI route without API session creation, API session creation cannot pass online smoke without Gateway, and Gateway cannot be safely exposed without the route lifecycle and deploy route.

## File Structure

### API repository: `D:\MyFiles\KT\Node\kt-template-online-api`

- Modify `package.json` and `pnpm-lock.yaml`: add `@nestjs-modules/ioredis`, `ioredis`, and `http-proxy-middleware`, plus gateway start scripts.
- Create `src/apps/napcat-webui-gateway/main.ts`: standalone Nest bootstrap on port `48086`.
- Create `src/apps/napcat-webui-gateway/napcat-webui-gateway.module.ts`: Gateway module imports config, logger, TypeORM, `RedisModule`, and gateway providers/controllers.
- Create `src/apps/napcat-webui-gateway/config/napcat-webui-gateway-config.service.ts`: reads Gateway env with bounded defaults.
- Create `src/apps/napcat-webui-gateway/domain/napcat-webui-gateway.types.ts`: session, audit, target, and proxy types.
- Create `src/apps/napcat-webui-gateway/infrastructure/session/napcat-webui-gateway-redis.store.ts`: Redis-backed session and ticket store.
- Create `src/apps/napcat-webui-gateway/infrastructure/session/napcat-webui-gateway-ticket.service.ts`: one-time bootstrap ticket generation and redemption.
- Create `src/apps/napcat-webui-gateway/infrastructure/napcat-webui-credential.client.ts`: server-side WebUI token to Credential exchange.
- Create `src/apps/napcat-webui-gateway/infrastructure/proxy/napcat-webui-proxy.service.ts`: HTTP, header, redirect, cookie, and WebSocket proxy assembly.
- Create `src/apps/napcat-webui-gateway/application/napcat-webui-gateway-session.service.ts`: session create, active mark, heartbeat, revoke, expire, and concurrent-session policy.
- Create `src/apps/napcat-webui-gateway/presentation/internal-session.controller.ts`: internal service-to-service session API.
- Create `src/apps/napcat-webui-gateway/presentation/public-webui.controller.ts`: bootstrap and public iframe/proxy entry.
- Create `src/modules/qqbot/napcat/webui-gateway/contract/qqbot-napcat-webui-gateway.dto.ts`: Admin-facing DTOs.
- Create `src/modules/qqbot/napcat/webui-gateway/contract/qqbot-napcat-webui-gateway.controller.ts`: Admin endpoints under `/qqbot/napcat/webui`.
- Create `src/modules/qqbot/napcat/webui-gateway/application/qqbot-napcat-webui-gateway.service.ts`: account authorization, target resolution, and Gateway client orchestration.
- Create `src/modules/qqbot/napcat/webui-gateway/infrastructure/qqbot-napcat-webui-gateway.client.ts`: internal Gateway HTTP client.
- Create `src/modules/qqbot/napcat/webui-gateway/infrastructure/persistence/napcat-webui-gateway-audit.entity.ts`: MySQL audit entity.
- Modify `src/modules/qqbot/napcat/qqbot-napcat.module.ts`: register controller, service, client, and audit entity.
- Modify `sql/qqbot-init.sql` and `sql/refactor-v3/01-seed-core.sql`: add `QqBot:Account:WebUI` hidden route/menu and row-action permission.
- Modify `sql/refactor-v3/99-verify.sql`: assert the new permission and audit table exist.
- Create `dockerfile.gateway`: production image entry for `dist/apps/napcat-webui-gateway/main`.
- Modify `Jenkinsfile`: build, push, and deploy API image plus Gateway image.
- Modify `k8s/prod/api.yaml`: add Gateway Deployment/Service and API env for Gateway base URL/public base URL/internal secret.
- Modify `README.md` and `API.md`: document Gateway env, route, and validation commands.

### Admin repository: `D:\MyFiles\KT\Vue\kt-template-admin`

- Modify `apps/web-antdv-next/src/router/routes/modules/qqbot.ts`: add hidden second-level WebUI route.
- Modify `apps/web-antdv-next/src/api/qqbot/napcat.ts`: add WebUI session contracts and callers.
- Modify `apps/web-antdv-next/src/views/qqbot/account/list.tsx`: add WebUI row action.
- Create `apps/web-antdv-next/src/views/qqbot/account/napcat-webui/index.tsx`: remote console page.
- Create `apps/web-antdv-next/src/views/qqbot/account/napcat-webui/index.scss`: layout and theme-aware console styles.
- Create `apps/web-antdv-next/src/views/qqbot/account/napcat-webui/useNapcatWebuiGatewaySession.ts`: route-bound session lifecycle.
- Modify `apps/web-antdv-next/src/views/qqbot/account/napcat-boundary.spec.ts`: keep WebUI session code out of account list.
- Create `apps/web-antdv-next/src/views/qqbot/account/napcat-webui/napcat-webui.spec.tsx`: page lifecycle tests.
- Modify `apps/web-antdv-next/src/api/qqbot/napcat.spec.ts`: WebUI session caller tests.

---

### Task 1: Add Contracts, Permission Seeds, and Red Tests

**Files:**
- Create: `test/modules/qqbot/napcat-webui-gateway/webui-gateway-contract.spec.ts`
- Modify: `sql/qqbot-init.sql`
- Modify: `sql/refactor-v3/01-seed-core.sql`
- Modify: `sql/refactor-v3/99-verify.sql`

- [ ] **Step 1: Write the failing structural test**

Create `test/modules/qqbot/napcat-webui-gateway/webui-gateway-contract.spec.ts`:

```ts
import { readFileSync } from 'fs';
import { resolve } from 'path';

const repoRoot = resolve(__dirname, '../../../..');

const read = (path: string) => readFileSync(resolve(repoRoot, path), 'utf8');

describe('NapCat WebUI Gateway contract seeds', () => {
  it('registers a dedicated Admin permission for full NapCat WebUI access', () => {
    const coreSeed = read('sql/refactor-v3/01-seed-core.sql');
    const qqbotSeed = read('sql/qqbot-init.sql');

    expect(coreSeed).toContain('QqBot:Account:WebUI');
    expect(coreSeed).toContain('QqBotAccountNapcatWebui');
    expect(qqbotSeed).toContain('QqBot:Account:WebUI');
    expect(qqbotSeed).toContain('QqBotAccountNapcatWebui');
  });

  it('verifies the gateway audit table during full schema checks', () => {
    const verifySql = read('sql/refactor-v3/99-verify.sql');

    expect(verifySql).toContain('qqbot_napcat_webui_gateway_audit');
    expect(verifySql).toContain('QqBot:Account:WebUI');
  });
});
```

- [ ] **Step 2: Run the new test and verify RED**

Run:

```powershell
pnpm --dir D:\MyFiles\KT\Node\kt-template-online-api jest --runTestsByPath test/modules/qqbot/napcat-webui-gateway/webui-gateway-contract.spec.ts --runInBand
```

Expected: FAIL because `QqBot:Account:WebUI` and `qqbot_napcat_webui_gateway_audit` are not present.

- [ ] **Step 3: Add SQL seed rows**

Add these rows next to existing QQBot account rows in both `sql/qqbot-init.sql` and `sql/refactor-v3/01-seed-core.sql`:

```sql
(2041700000000100412, 2041700000000100400, 'QqBotAccountNapcatWebui', '/qqbot/account/:accountId/napcat-webui', '/qqbot/account/napcat-webui/index', NULL, 'QqBot:Account:WebUI', 'menu', '{"activePath":"/qqbot/account","hideInMenu":true,"title":"NapCat WebUI"}', 1, 0),
(2041700000000120407, 2041700000000100402, 'QqBotAccountWebUI', NULL, NULL, NULL, 'QqBot:Account:WebUI', 'button', '{"title":"NapCat WebUI"}', 1, 0),
```

Keep IDs unique and do not modify unrelated menu rows.

- [ ] **Step 4: Add schema verification SQL**

In `sql/refactor-v3/99-verify.sql`, add assertions using the existing verify style:

```sql
SELECT 'qqbot_napcat_webui_gateway_audit table exists' AS check_name,
       COUNT(*) AS matched
FROM information_schema.tables
WHERE table_schema = DATABASE()
  AND table_name = 'qqbot_napcat_webui_gateway_audit';

SELECT 'QqBot Account WebUI permission exists' AS check_name,
       COUNT(*) AS matched
FROM admin_menu
WHERE auth_code = 'QqBot:Account:WebUI';
```

The current menu table is `admin_menu`, and the permission column is `auth_code`; use those exact names in the verification SQL.

- [ ] **Step 5: Run the contract test and verify GREEN**

Run:

```powershell
pnpm --dir D:\MyFiles\KT\Node\kt-template-online-api jest --runTestsByPath test/modules/qqbot/napcat-webui-gateway/webui-gateway-contract.spec.ts --runInBand
```

Expected: PASS.

- [ ] **Step 6: Commit Task 1**

```powershell
git -C D:\MyFiles\KT\Node\kt-template-online-api add test/modules/qqbot/napcat-webui-gateway/webui-gateway-contract.spec.ts sql/qqbot-init.sql sql/refactor-v3/01-seed-core.sql sql/refactor-v3/99-verify.sql
git -C D:\MyFiles\KT\Node\kt-template-online-api commit -m "feat: 增加NapCat WebUI权限契约"
```

---

### Task 2: Build API Session Endpoints and Audit Entity

**Files:**
- Create: `test/modules/qqbot/napcat-webui-gateway/api-session.service.spec.ts`
- Create: `src/modules/qqbot/napcat/webui-gateway/contract/qqbot-napcat-webui-gateway.dto.ts`
- Create: `src/modules/qqbot/napcat/webui-gateway/contract/qqbot-napcat-webui-gateway.controller.ts`
- Create: `src/modules/qqbot/napcat/webui-gateway/application/qqbot-napcat-webui-gateway.service.ts`
- Create: `src/modules/qqbot/napcat/webui-gateway/infrastructure/qqbot-napcat-webui-gateway.client.ts`
- Create: `src/modules/qqbot/napcat/webui-gateway/infrastructure/persistence/napcat-webui-gateway-audit.entity.ts`
- Modify: `src/modules/qqbot/napcat/qqbot-napcat.module.ts`
- Modify: `src/modules/qqbot/napcat/infrastructure/persistence/index.ts`

- [ ] **Step 1: Write the failing API service test**

Create `test/modules/qqbot/napcat-webui-gateway/api-session.service.spec.ts`:

```ts
import { QqbotNapcatWebuiGatewayService } from '../../../../src/modules/qqbot/napcat/webui-gateway/application/qqbot-napcat-webui-gateway.service';

const account = {
  id: 'account-1',
  name: 'Mirror',
  selfId: '1914728559',
};

const redactedWebuiToken = ['redacted', 'webui', 'token'].join('-');

const container = {
  id: 'container-1',
  name: 'kt-qqbot-napcat-1',
  webuiPort: 6100,
  webuiStatus: 'online',
  webuiToken: redactedWebuiToken,
};

describe('QqbotNapcatWebuiGatewayService', () => {
  it('creates a safe Admin session response without leaking NapCat secrets', async () => {
    const service = new QqbotNapcatWebuiGatewayService(
      { findById: jest.fn().mockResolvedValue(account) } as any,
      { findPrimaryContainerByAccountId: jest.fn().mockResolvedValue(container) } as any,
      {
        createSession: jest.fn().mockResolvedValue({
          expiresAt: 1782268000000,
          iframeUrl: '/napcat-webui/session/session-1/bootstrap?ticket=ticket-1',
          sessionId: 'session-1',
        }),
        heartbeat: jest.fn(),
        revoke: jest.fn(),
      } as any,
      { record: jest.fn() } as any,
    );

    const result = await service.createSession({
      accountId: 'account-1',
      adminUserId: '2041700000000000002',
      clientIp: '127.0.0.1',
      userAgent: 'vitest',
    });

    expect(result).toMatchObject({
      account: { id: 'account-1', selfId: '1914728559' },
      container: {
        id: 'container-1',
        name: 'kt-qqbot-napcat-1',
        webuiStatus: 'online',
      },
      iframeUrl: '/napcat-webui/session/session-1/bootstrap?ticket=ticket-1',
      sessionId: 'session-1',
    });
    expect(JSON.stringify(result)).not.toContain('secret-token');
    expect(JSON.stringify(result)).not.toContain('6100');
  });

  it('rejects accounts without an online WebUI target before calling Gateway', async () => {
    const gatewayClient = { createSession: jest.fn() };
    const service = new QqbotNapcatWebuiGatewayService(
      { findById: jest.fn().mockResolvedValue(account) } as any,
      {
        findPrimaryContainerByAccountId: jest
          .fn()
          .mockResolvedValue({ ...container, webuiStatus: 'offline' }),
      } as any,
      gatewayClient as any,
      { record: jest.fn() } as any,
    );

    await expect(
      service.createSession({
        accountId: 'account-1',
        adminUserId: '2041700000000000002',
        clientIp: '127.0.0.1',
        userAgent: 'vitest',
      }),
    ).rejects.toThrow('NapCat WebUI 不在线');
    expect(gatewayClient.createSession).not.toHaveBeenCalled();
  });
});
```

- [ ] **Step 2: Run the service test and verify RED**

```powershell
pnpm --dir D:\MyFiles\KT\Node\kt-template-online-api jest --runTestsByPath test/modules/qqbot/napcat-webui-gateway/api-session.service.spec.ts --runInBand
```

Expected: FAIL because the service and DTOs do not exist.

- [ ] **Step 3: Create DTOs**

Create `src/modules/qqbot/napcat/webui-gateway/contract/qqbot-napcat-webui-gateway.dto.ts`:

```ts
import { ApiProperty } from '@nestjs/swagger';

export class QqbotNapcatWebuiSessionCreateDto {
  @ApiProperty({ description: 'QQBot account id selected from the account list' })
  accountId!: string;
}

export class QqbotNapcatWebuiSessionResponseDto {
  account!: {
    id: string;
    name?: string;
    selfId: string;
  };
  container!: {
    id: string;
    name: string;
    webuiStatus: string;
  };
  expiresAt!: number;
  iframeUrl!: string;
  sessionId!: string;
}
```

- [ ] **Step 4: Create the audit entity**

Create `src/modules/qqbot/napcat/webui-gateway/infrastructure/persistence/napcat-webui-gateway-audit.entity.ts`:

```ts
import { Column, Entity, PrimaryColumn } from 'typeorm';
import { KtCreateDateColumn, KtDateTime } from '@/common';

@Entity('qqbot_napcat_webui_gateway_audit')
export class NapcatWebuiGatewayAudit {
  @PrimaryColumn({ length: 32 })
  id!: string;

  @Column({ length: 64, name: 'session_id' })
  sessionId!: string;

  @Column({ length: 32, name: 'admin_user_id' })
  adminUserId!: string;

  @Column({ length: 32, name: 'account_id' })
  accountId!: string;

  @Column({ length: 32, name: 'self_id' })
  selfId!: string;

  @Column({ length: 32, name: 'container_id' })
  containerId!: string;

  @Column({ length: 64, name: 'event_type' })
  eventType!: string;

  @Column({ length: 128, name: 'client_ip', nullable: true })
  clientIp?: null | string;

  @Column({ length: 512, name: 'user_agent', nullable: true })
  userAgent?: null | string;

  @Column({ name: 'detail_json', nullable: true, type: 'json' })
  detailJson?: null | Record<string, unknown>;

  @KtCreateDateColumn()
  createTime!: KtDateTime;
}
```

Use the existing ID generation helper used by nearby services when recording rows.

- [ ] **Step 5: Create the Gateway internal client**

Create `src/modules/qqbot/napcat/webui-gateway/infrastructure/qqbot-napcat-webui-gateway.client.ts` with methods:

```ts
export interface CreateGatewaySessionInput {
  accountId: string;
  adminUserId: string;
  clientIp?: string;
  containerId: string;
  containerName: string;
  selfId: string;
  upstreamBaseUrl: string;
  userAgent?: string;
  webuiToken: string;
}

export interface CreateGatewaySessionResult {
  expiresAt: number;
  iframeUrl: string;
  sessionId: string;
}

export class QqbotNapcatWebuiGatewayClient {
  /**
   * Creates a Gateway session through the internal service endpoint.
   * @param input Account, container, and server-side WebUI credential material resolved by API.
   * @returns The browser-safe iframe URL and session lifetime returned by Gateway.
   */
  async createSession(
    input: CreateGatewaySessionInput,
  ): Promise<CreateGatewaySessionResult> {
    // Implement with axios or Node fetch using NAPCAT_WEBUI_GATEWAY_INTERNAL_BASE_URL
    // and NAPCAT_WEBUI_GATEWAY_INTERNAL_SECRET. Do not log webuiToken.
    throw new Error('NapCat WebUI Gateway client not implemented');
  }

  /**
   * Forwards a route-bound heartbeat to Gateway.
   * @param sessionId Gateway session id returned to Admin.
   * @returns Updated session lifetime.
   */
  async heartbeat(sessionId: string) {
    throw new Error('NapCat WebUI Gateway heartbeat not implemented');
  }

  /**
   * Revokes an active Gateway session.
   * @param sessionId Gateway session id returned to Admin.
   */
  async revoke(sessionId: string) {
    throw new Error('NapCat WebUI Gateway revoke not implemented');
  }
}
```

Replace the throwing bodies in the implementation step with bounded HTTP calls and sanitized errors.

- [ ] **Step 6: Create the API service**

Create `src/modules/qqbot/napcat/webui-gateway/application/qqbot-napcat-webui-gateway.service.ts` with these public methods:

```ts
export interface CreateAdminWebuiSessionInput {
  accountId: string;
  adminUserId: string;
  clientIp?: string;
  userAgent?: string;
}

export class QqbotNapcatWebuiGatewayService {
  /**
   * Creates a browser-safe NapCat WebUI Gateway session for one QQBot account.
   * @param input Admin user id, selected account id, and client evidence for audit.
   * @returns Safe session metadata for Admin route iframe loading.
   */
  async createSession(input: CreateAdminWebuiSessionInput) {
    const account = await this.accountService.findById(input.accountId);
    if (!account) throw new Error('QQBot 账号不存在');

    const container =
      await this.napcatRuntimeService.findPrimaryContainerByAccountId(
        input.accountId,
      );
    if (!container) throw new Error('账号未绑定 NapCat 容器');
    if (container.webuiStatus === 'offline') {
      throw new Error('NapCat WebUI 不在线');
    }
    if (!container.webuiToken || !container.webuiPort) {
      throw new Error('NapCat WebUI 配置不完整');
    }

    const gateway = await this.gatewayClient.createSession({
      accountId: account.id,
      adminUserId: input.adminUserId,
      clientIp: input.clientIp,
      containerId: container.id,
      containerName: container.name,
      selfId: account.selfId,
      upstreamBaseUrl: this.buildContainerWebuiUrl(container.webuiPort),
      userAgent: input.userAgent,
      webuiToken: container.webuiToken,
    });

    return {
      account: { id: account.id, name: account.name, selfId: account.selfId },
      container: {
        id: container.id,
        name: container.name,
        webuiStatus: container.webuiStatus || 'unknown',
      },
      ...gateway,
    };
  }
}
```

Add `findPrimaryContainerByAccountId(accountId: string)` to `QqbotNapcatContainerService` with JSDoc and a focused unit test, then use that method from `QqbotNapcatWebuiGatewayService`.

- [ ] **Step 7: Create the API controller**

Create `src/modules/qqbot/napcat/webui-gateway/contract/qqbot-napcat-webui-gateway.controller.ts`:

```ts
import { Body, Controller, HttpCode, HttpStatus, Param, Post, Req, UseGuards } from '@nestjs/common';
import { ApiOperation, ApiTags } from '@nestjs/swagger';
import { JwtAuthGuard } from '@/modules/admin/identity/auth/jwt-auth.guard';
import { vbenSuccess } from '@/common';
import { QqbotNapcatWebuiGatewayService } from '../application/qqbot-napcat-webui-gateway.service';
import { QqbotNapcatWebuiSessionCreateDto } from './qqbot-napcat-webui-gateway.dto';

@ApiTags('QQBot - NapCat WebUI Gateway')
@Controller('qqbot/napcat/webui')
@UseGuards(JwtAuthGuard)
export class QqbotNapcatWebuiGatewayController {
  /**
   * Initializes the Admin-facing NapCat WebUI Gateway controller.
   * @param service Gateway session application service.
   */
  constructor(private readonly service: QqbotNapcatWebuiGatewayService) {}

  /**
   * Creates one route-bound NapCat WebUI session.
   * @param body Selected QQBot account id from Admin.
   * @param req Authenticated request carrying Admin user and client evidence.
   */
  @Post('session')
  @HttpCode(HttpStatus.OK)
  @ApiOperation({ summary: '创建 NapCat WebUI Gateway 会话' })
  async createSession(@Body() body: QqbotNapcatWebuiSessionCreateDto, @Req() req: any) {
    return vbenSuccess(
      await this.service.createSession({
        accountId: body.accountId,
        adminUserId: `${req.user?.sub || req.user?.id || ''}`,
        clientIp: req.ip,
        userAgent: req.headers?.['user-agent'],
      }),
    );
  }

  @Post('session/:sessionId/heartbeat')
  @HttpCode(HttpStatus.OK)
  async heartbeat(@Param('sessionId') sessionId: string) {
    return vbenSuccess(await this.service.heartbeat(sessionId));
  }

  @Post('session/:sessionId/revoke')
  @HttpCode(HttpStatus.OK)
  async revoke(@Param('sessionId') sessionId: string) {
    return vbenSuccess(await this.service.revoke(sessionId));
  }
}
```

- [ ] **Step 8: Register providers and entities**

Modify `src/modules/qqbot/napcat/qqbot-napcat.module.ts` to include:

```ts
import { QqbotNapcatWebuiGatewayController } from './webui-gateway/contract/qqbot-napcat-webui-gateway.controller';
import { QqbotNapcatWebuiGatewayService } from './webui-gateway/application/qqbot-napcat-webui-gateway.service';
import { QqbotNapcatWebuiGatewayClient } from './webui-gateway/infrastructure/qqbot-napcat-webui-gateway.client';
```

Add the controller to `QQBOT_NAPCAT_CONTROLLERS` and the service/client to `QQBOT_NAPCAT_PROVIDERS`.

Modify `src/modules/qqbot/napcat/infrastructure/persistence/index.ts` to include `NapcatWebuiGatewayAudit` in `NAPCAT_RUNTIME_ENTITIES` and add `qqbot_napcat_webui_gateway_audit` to `NAPCAT_RUNTIME_DOMAIN_CONTRACT.tables`.

- [ ] **Step 9: Run API tests and typecheck**

```powershell
pnpm --dir D:\MyFiles\KT\Node\kt-template-online-api jest --runTestsByPath test/modules/qqbot/napcat-webui-gateway/api-session.service.spec.ts test/modules/qqbot/napcat-webui-gateway/webui-gateway-contract.spec.ts --runInBand
pnpm --dir D:\MyFiles\KT\Node\kt-template-online-api run typecheck
```

Expected: tests PASS and typecheck PASS.

- [ ] **Step 10: Commit Task 2**

```powershell
git -C D:\MyFiles\KT\Node\kt-template-online-api add src/modules/qqbot/napcat/webui-gateway src/modules/qqbot/napcat/qqbot-napcat.module.ts src/modules/qqbot/napcat/infrastructure/persistence/index.ts test/modules/qqbot/napcat-webui-gateway
git -C D:\MyFiles\KT\Node\kt-template-online-api commit -m "feat: 增加NapCat WebUI会话接口"
```

---

### Task 3: Build Gateway App, Session Store, and Bootstrap Tickets

**Files:**
- Modify: `package.json`
- Modify: `pnpm-lock.yaml`
- Create: `test/apps/napcat-webui-gateway/session-store.spec.ts`
- Create: `src/apps/napcat-webui-gateway/main.ts`
- Create: `src/apps/napcat-webui-gateway/napcat-webui-gateway.module.ts`
- Create: `src/apps/napcat-webui-gateway/config/napcat-webui-gateway-config.service.ts`
- Create: `src/apps/napcat-webui-gateway/domain/napcat-webui-gateway.types.ts`
- Create: `src/apps/napcat-webui-gateway/infrastructure/session/napcat-webui-gateway-redis.store.ts`
- Create: `src/apps/napcat-webui-gateway/infrastructure/session/napcat-webui-gateway-ticket.service.ts`
- Create: `src/apps/napcat-webui-gateway/application/napcat-webui-gateway-session.service.ts`
- Create: `src/apps/napcat-webui-gateway/presentation/internal-session.controller.ts`

- [ ] **Step 1: Add dependencies**

Run:

```powershell
pnpm --dir D:\MyFiles\KT\Node\kt-template-online-api add @nestjs-modules/ioredis ioredis http-proxy-middleware
```

Expected: `package.json` and `pnpm-lock.yaml` update. Keep `ws` unchanged because it already exists. Do not add `connect-redis` because Gateway sessions are domain sessions, not Express login sessions.

- [ ] **Step 2: Add package scripts**

Modify `package.json` scripts:

```json
{
  "start:gateway:prod": "cross-env NODE_ENV=production node dist/apps/napcat-webui-gateway/main",
  "start:gateway:dev": "ts-node -r tsconfig-paths/register src/apps/napcat-webui-gateway/main.ts"
}
```

The API repo already depends on `ts-node` and `tsconfig-paths`, so the dev script uses the direct TypeScript entrypoint and the production script keeps the compiled `dist/apps/napcat-webui-gateway/main` entrypoint.

- [ ] **Step 3: Write the failing session lifecycle test**

Create `test/apps/napcat-webui-gateway/session-store.spec.ts`:

```ts
import { NapcatWebuiGatewaySessionService } from '../../../src/apps/napcat-webui-gateway/application/napcat-webui-gateway-session.service';
import type { NapcatWebuiGatewaySessionStore } from '../../../src/apps/napcat-webui-gateway/domain/napcat-webui-gateway.types';

class MemoryStore implements NapcatWebuiGatewaySessionStore {
  readonly sessions = new Map<string, any>();

  async create(session: any) {
    this.sessions.set(session.sessionId, session);
    return session;
  }

  async find(sessionId: string) {
    return this.sessions.get(sessionId);
  }

  async findActiveByUserAndAccount(adminUserId: string, accountId: string) {
    return [...this.sessions.values()].find(
      (item) =>
        item.adminUserId === adminUserId &&
        item.accountId === accountId &&
        item.status !== 'revoked',
    );
  }

  async update(sessionId: string, patch: any) {
    const current = this.sessions.get(sessionId);
    const next = { ...current, ...patch };
    this.sessions.set(sessionId, next);
    return next;
  }
}

describe('NapcatWebuiGatewaySessionService', () => {
  it('revokes an older same-user same-account session when creating a new one', async () => {
    const store = new MemoryStore();
    const service = new NapcatWebuiGatewaySessionService(store as any, {
      now: () => 1000,
      ttlMs: () => 60000,
    } as any);

    const first = await service.create({
      accountId: 'account-1',
      adminUserId: 'admin-1',
      containerId: 'container-1',
      containerName: 'container',
      selfId: '1914728559',
      upstreamBaseUrl: 'http://127.0.0.1:6100',
      webuiToken: ['redacted', 'webui', 'token'].join('-'),
    });
    const second = await service.create({
      accountId: 'account-1',
      adminUserId: 'admin-1',
      containerId: 'container-1',
      containerName: 'container',
      selfId: '1914728559',
      upstreamBaseUrl: 'http://127.0.0.1:6100',
      webuiToken: ['redacted', 'webui', 'token'].join('-'),
    });

    expect(first.sessionId).not.toBe(second.sessionId);
    expect(await store.find(first.sessionId)).toMatchObject({
      status: 'revoked',
    });
    expect(await store.find(second.sessionId)).toMatchObject({
      status: 'created',
    });
  });

  it('extends active sessions on heartbeat and rejects revoked sessions', async () => {
    const store = new MemoryStore();
    let now = 1000;
    const service = new NapcatWebuiGatewaySessionService(store as any, {
      now: () => now,
      ttlMs: () => 60000,
    } as any);

    const session = await service.create({
      accountId: 'account-1',
      adminUserId: 'admin-1',
      containerId: 'container-1',
      containerName: 'container',
      selfId: '1914728559',
      upstreamBaseUrl: 'http://127.0.0.1:6100',
      webuiToken: ['redacted', 'webui', 'token'].join('-'),
    });

    now = 5000;
    await service.markActive(session.sessionId);
    const heartbeat = await service.heartbeat(session.sessionId);
    expect(heartbeat).toMatchObject({
      sessionId: session.sessionId,
      status: 'active',
    });
    expect(heartbeat.expiresAt).toBe(65000);

    await service.revoke(session.sessionId);
    await expect(service.heartbeat(session.sessionId)).rejects.toThrow(
      'Gateway session is not active',
    );
  });
});
```

- [ ] **Step 4: Run the test and verify RED**

```powershell
pnpm --dir D:\MyFiles\KT\Node\kt-template-online-api jest --runTestsByPath test/apps/napcat-webui-gateway/session-store.spec.ts --runInBand
```

Expected: FAIL because Gateway app types and service do not exist.

- [ ] **Step 5: Create Gateway domain types**

Create `src/apps/napcat-webui-gateway/domain/napcat-webui-gateway.types.ts`:

```ts
export type NapcatWebuiGatewaySessionStatus =
  | 'active'
  | 'created'
  | 'expired'
  | 'failed'
  | 'revoked';

export interface NapcatWebuiGatewaySession {
  accountId: string;
  activeAt?: number;
  adminUserId: string;
  clientIp?: string;
  containerId: string;
  containerName: string;
  createdAt: number;
  expiresAt: number;
  lastSeenAt?: number;
  revokedAt?: number;
  selfId: string;
  sessionId: string;
  status: NapcatWebuiGatewaySessionStatus;
  upstreamBaseUrl: string;
  userAgent?: string;
  webuiToken: string;
}

export interface NapcatWebuiGatewaySessionStore {
  create(session: NapcatWebuiGatewaySession): Promise<NapcatWebuiGatewaySession>;
  find(sessionId: string): Promise<NapcatWebuiGatewaySession | undefined>;
  findActiveByUserAndAccount(
    adminUserId: string,
    accountId: string,
  ): Promise<NapcatWebuiGatewaySession | undefined>;
  update(
    sessionId: string,
    patch: Partial<NapcatWebuiGatewaySession>,
  ): Promise<NapcatWebuiGatewaySession>;
}
```

- [ ] **Step 6: Implement session service**

Create `src/apps/napcat-webui-gateway/application/napcat-webui-gateway-session.service.ts` with `create`, `markActive`, `heartbeat`, `revoke`, `requireBootstrapSession`, and `requireProxySession`. Every method needs JSDoc. Use `crypto.randomUUID()` for `sessionId`.

The `create()` implementation must:

```ts
const older = await this.store.findActiveByUserAndAccount(
  input.adminUserId,
  input.accountId,
);
if (older) {
  await this.store.update(older.sessionId, {
    revokedAt: now,
    status: 'revoked',
  });
}
```

The `heartbeat()` implementation must extend active sessions only. It must reject `created`, `revoked`, `expired`, `failed`, missing sessions, and sessions whose user/account index no longer points at the requested `sessionId`. `requireBootstrapSession()` accepts only non-terminal, non-expired, currently indexed sessions for one-time ticket bootstrap. `markActive()` is the only method that may promote a `created` session to `active`. `requireProxySession()` accepts only `active`, non-expired, currently indexed sessions.

- [ ] **Step 7: Implement Redis store and ticket service**

Create `src/apps/napcat-webui-gateway/infrastructure/session/napcat-webui-gateway-redis.store.ts`. Inject Redis through `@nestjs-modules/ioredis`:

```ts
import { Injectable } from '@nestjs/common';
import { InjectRedis } from '@nestjs-modules/ioredis';
import type Redis from 'ioredis';

@Injectable()
export class NapcatWebuiGatewayRedisStore
  implements NapcatWebuiGatewaySessionStore
{
  /**
   * Initializes the Redis-backed Gateway session store.
   * @param redis Shared Gateway Redis client managed by Nest RedisModule.
   */
  constructor(@InjectRedis() private readonly redis: Redis) {}
}
```

Use Redis `set(key, value, 'PX', ttlMs)`, `get`, and a secondary index key:

```text
napcat:webui:session:{sessionId}
napcat:webui:user-account:{adminUserId}:{accountId}
```

Create `src/apps/napcat-webui-gateway/infrastructure/session/napcat-webui-gateway-ticket.service.ts`. Ticket keys:

```text
napcat:webui:ticket:{ticket}
```

Ticket TTL must be 60 seconds or less. Redemption deletes the ticket key before returning the session id.

- [ ] **Step 8: Add Gateway module and internal controller**

Create `src/apps/napcat-webui-gateway/napcat-webui-gateway.module.ts` and `presentation/internal-session.controller.ts`. The module must use the community Redis module rather than a custom Redis provider:

```ts
import { Module } from '@nestjs/common';
import { ConfigModule, ConfigService } from '@nestjs/config';
import { RedisModule } from '@nestjs-modules/ioredis';

@Module({
  imports: [
    ConfigModule.forRoot({ isGlobal: true }),
    RedisModule.forRootAsync({
      inject: [ConfigService],
      useFactory: (config: ConfigService) => ({
        type: 'single',
        url:
          config.get<string>('NAPCAT_WEBUI_GATEWAY_REDIS_URL') ||
          `redis://${config.get<string>('NAPCAT_WEBUI_GATEWAY_REDIS_HOST') || '127.0.0.1'}:${config.get<number>('NAPCAT_WEBUI_GATEWAY_REDIS_PORT') || 6379}`,
      }),
    }),
  ],
})
export class NapcatWebuiGatewayModule {}
```

Internal controller paths:

```text
POST /internal/sessions
POST /internal/sessions/:sessionId/heartbeat
POST /internal/sessions/:sessionId/revoke
GET /internal/health
```

Check the `x-kt-gateway-secret` header against `NAPCAT_WEBUI_GATEWAY_INTERNAL_SECRET` before accepting mutating internal calls.

- [ ] **Step 9: Add Gateway bootstrap**

Create `src/apps/napcat-webui-gateway/main.ts`:

```ts
import { NestFactory } from '@nestjs/core';
import { Logger } from 'nestjs-pino';
import { json, urlencoded } from 'express';
import { NapcatWebuiGatewayModule } from './napcat-webui-gateway.module';

/**
 * Starts the standalone NapCat WebUI Gateway process.
 */
async function bootstrap() {
  const app = await NestFactory.create(NapcatWebuiGatewayModule, {
    bufferLogs: true,
  });
  app.useLogger(app.get(Logger));
  app.use(json({ limit: '50mb' }));
  app.use(urlencoded({ extended: true, limit: '50mb' }));
  await app.listen(Number(process.env.NAPCAT_WEBUI_GATEWAY_PORT || 48086));
}

bootstrap();
```

- [ ] **Step 10: Run Gateway session tests and typecheck**

```powershell
pnpm --dir D:\MyFiles\KT\Node\kt-template-online-api jest --runTestsByPath test/apps/napcat-webui-gateway/session-store.spec.ts --runInBand
pnpm --dir D:\MyFiles\KT\Node\kt-template-online-api run typecheck
```

Expected: tests PASS and typecheck PASS.

- [ ] **Step 11: Commit Task 3**

```powershell
git -C D:\MyFiles\KT\Node\kt-template-online-api add package.json pnpm-lock.yaml src/apps/napcat-webui-gateway test/apps/napcat-webui-gateway
git -C D:\MyFiles\KT\Node\kt-template-online-api commit -m "feat: 增加NapCat WebUI Gateway会话服务"
```

---

### Task 4: Add Gateway Credential Exchange and Proxy

**Files:**
- Create: `test/apps/napcat-webui-gateway/proxy-rewrite.spec.ts`
- Create: `src/apps/napcat-webui-gateway/infrastructure/napcat-webui-credential.client.ts`
- Create: `src/apps/napcat-webui-gateway/infrastructure/proxy/napcat-webui-proxy.service.ts`
- Create: `src/apps/napcat-webui-gateway/presentation/public-webui.controller.ts`
- Modify: `src/apps/napcat-webui-gateway/main.ts`
- Modify: `src/apps/napcat-webui-gateway/napcat-webui-gateway.module.ts`

- [ ] **Step 1: Write proxy rewrite tests**

Create `test/apps/napcat-webui-gateway/proxy-rewrite.spec.ts`:

```ts
import {
  buildGatewayCookiePathRewrite,
  rewriteNapcatLocationHeader,
  sanitizeGatewayProxyPath,
} from '../../../src/apps/napcat-webui-gateway/infrastructure/proxy/napcat-webui-proxy.service';

describe('NapCat WebUI Gateway proxy rewriting', () => {
  it('rejects upstream URL injection and path traversal', () => {
    expect(() => sanitizeGatewayProxyPath('https://evil.test/api')).toThrow(
      'Invalid NapCat WebUI proxy path',
    );
    expect(() => sanitizeGatewayProxyPath('../api/auth/login')).toThrow(
      'Invalid NapCat WebUI proxy path',
    );
    expect(sanitizeGatewayProxyPath('api/QQLogin/CheckLoginStatus')).toBe(
      '/api/QQLogin/CheckLoginStatus',
    );
  });

  it('rewrites redirects under the session proxy prefix', () => {
    expect(
      rewriteNapcatLocationHeader('/webui/login', {
        sessionId: 'session-1',
      }),
    ).toBe('/napcat-webui/session/session-1/webui/webui/login');
  });

  it('delegates cookie path rewriting to http-proxy-middleware options', () => {
    expect(buildGatewayCookiePathRewrite({ sessionId: 'session-1' })).toEqual({
      '*': '/napcat-webui/session/session-1',
    });
  });
});
```

- [ ] **Step 2: Run proxy test and verify RED**

```powershell
pnpm --dir D:\MyFiles\KT\Node\kt-template-online-api jest --runTestsByPath test/apps/napcat-webui-gateway/proxy-rewrite.spec.ts --runInBand
```

Expected: FAIL because proxy helpers do not exist.

- [ ] **Step 3: Implement credential client**

Create `src/apps/napcat-webui-gateway/infrastructure/napcat-webui-credential.client.ts`. Use the same NapCat WebUI contract as `NapcatWebuiHttpClient`: hash `webuiToken + ".napcat"`, POST `/api/auth/login`, and cache Credential per session until session revoke/expire.

Do not log `webuiToken`, hash, or Credential.

- [ ] **Step 4: Implement proxy helpers**

Create pure helper exports in `src/apps/napcat-webui-gateway/infrastructure/proxy/napcat-webui-proxy.service.ts`. Keep cookie rewriting as a `http-proxy-middleware` option instead of rewriting `Set-Cookie` by hand:

```ts
export function sanitizeGatewayProxyPath(rawPath: string): string {
  const decoded = decodeURIComponent(rawPath || '');
  if (/^https?:\/\//i.test(decoded) || decoded.includes('..')) {
    throw new Error('Invalid NapCat WebUI proxy path');
  }
  return `/${decoded.replace(/^\/+/, '')}`;
}

export function rewriteNapcatLocationHeader(
  location: string,
  input: { sessionId: string },
) {
  if (/^https?:\/\//i.test(location)) return location;
  return `/napcat-webui/session/${input.sessionId}/webui/${location.replace(/^\/+/, '')}`;
}

export function buildGatewayCookiePathRewrite(input: { sessionId: string }) {
  return {
    '*': `/napcat-webui/session/${input.sessionId}`,
  };
}
```

- [ ] **Step 5: Implement proxy service**

Use `createProxyMiddleware` from `http-proxy-middleware` with:

```ts
{
  changeOrigin: true,
  cookiePathRewrite: buildGatewayCookiePathRewrite({ sessionId }),
  on: {
    proxyReq: handleProxyReq,
    proxyReqWs: handleProxyReqWs,
    proxyRes: handleProxyRes,
  },
  pathRewrite: (_path, req) => sanitizeGatewayProxyPath(req.params[0] || ''),
  secure: false,
  ws: true,
  selfHandleResponse: false,
}
```

Before proxying:

- resolve an active session by `sessionId` through `sessionService.requireProxySession(sessionId)`;
- reject non-active, stale, terminal, expired, or missing sessions with 410;
- redeem Credential through `NapcatWebuiCredentialClient`;
- add `Authorization: Bearer ${credential}` upstream;
- never forward API/Admin cookies upstream;
- never allow the browser to override `target`.

Do not mark sessions active from the proxy path; bootstrap activates the session before redirecting into the proxied WebUI.

For WebSocket upgrade, do not tunnel frames through MQTT and do not hand-roll a WebSocket bridge. Expose a method on `NapcatWebuiProxyService` and bind HPM's upgrade handler from `main.ts`:

```ts
/**
 * Binds NapCat WebUI WebSocket upgrades to the same proxy middleware.
 * @param server HTTP server created by Nest's Express adapter.
 */
bindWebSocketUpgrade(server: import('http').Server) {
  server.on('upgrade', (req, socket, head) => {
    if (!req.url?.startsWith('/napcat-webui/session/')) return;
    this.proxy.upgrade(req, socket, head);
  });
}
```

Modify `src/apps/napcat-webui-gateway/main.ts` after `app.listen()`:

```ts
  const server = app.getHttpServer();
  app.get(NapcatWebuiProxyService).bindWebSocketUpgrade(server);
```

- [ ] **Step 6: Implement public controller**

Create `src/apps/napcat-webui-gateway/presentation/public-webui.controller.ts`:

```text
GET /napcat-webui/session/:sessionId/bootstrap
ALL /napcat-webui/session/:sessionId/webui/*
```

Bootstrap must redeem `ticket`, validate the redeemed session through `sessionService.requireBootstrapSession(sessionId)`, call `sessionService.markActive(sessionId)`, set an HttpOnly gateway cookie scoped to `/napcat-webui/session/:sessionId`, and redirect to `/napcat-webui/session/:sessionId/webui/webui`.

Proxy route delegates to `NapcatWebuiProxyService`. The proxy service remains responsible for path sanitization, active-only session validation, Credential injection, HPM `cookiePathRewrite`, HPM HTTP proxying, and HPM WebSocket upgrade handling.

- [ ] **Step 7: Run tests and typecheck**

```powershell
pnpm --dir D:\MyFiles\KT\Node\kt-template-online-api jest --runTestsByPath test/apps/napcat-webui-gateway/session-store.spec.ts test/apps/napcat-webui-gateway/proxy-rewrite.spec.ts --runInBand
pnpm --dir D:\MyFiles\KT\Node\kt-template-online-api run typecheck
```

Expected: tests PASS and typecheck PASS.

- [ ] **Step 8: Commit Task 4**

```powershell
git -C D:\MyFiles\KT\Node\kt-template-online-api add src/apps/napcat-webui-gateway test/apps/napcat-webui-gateway
git -C D:\MyFiles\KT\Node\kt-template-online-api commit -m "feat: 代理NapCat WebUI流量"
```

---

### Task 5: Wire Build, Docker, K8s, and API Gateway Env

**Files:**
- Create: `test/modules/qqbot/napcat-webui-gateway/gateway-deployment.spec.ts`
- Create: `dockerfile.gateway`
- Modify: `Jenkinsfile`
- Modify: `k8s/prod/api.yaml`
- Modify: `README.md`
- Modify: `API.md`

- [ ] **Step 1: Write deployment structural tests**

Create `test/modules/qqbot/napcat-webui-gateway/gateway-deployment.spec.ts`:

```ts
import { readFileSync } from 'fs';
import { resolve } from 'path';

const root = resolve(__dirname, '../../../..');
const read = (path: string) => readFileSync(resolve(root, path), 'utf8');

describe('NapCat WebUI Gateway deployment wiring', () => {
  it('has a dedicated production dockerfile entry', () => {
    const dockerfile = read('dockerfile.gateway');

    expect(dockerfile).toContain('dist/apps/napcat-webui-gateway/main');
    expect(dockerfile).toContain('EXPOSE 48086');
  });

  it('deploys Gateway as a separate K8s Deployment and Service', () => {
    const manifest = read('k8s/prod/api.yaml');

    expect(manifest).toContain('name: kt-napcat-webui-gateway');
    expect(manifest).toContain('containerPort: 48086');
    expect(manifest).toContain('NAPCAT_WEBUI_GATEWAY_INTERNAL_SECRET');
    expect(manifest).toContain('NAPCAT_WEBUI_GATEWAY_REDIS_HOST');
  });

  it('builds and pushes a separate Gateway image in Jenkins', () => {
    const jenkinsfile = read('Jenkinsfile');

    expect(jenkinsfile).toContain('GATEWAY_IMAGE_NAME');
    expect(jenkinsfile).toContain('dockerfile.gateway');
    expect(jenkinsfile).toContain('kt-napcat-webui-gateway');
  });
});
```

- [ ] **Step 2: Run deployment test and verify RED**

```powershell
pnpm --dir D:\MyFiles\KT\Node\kt-template-online-api jest --runTestsByPath test/modules/qqbot/napcat-webui-gateway/gateway-deployment.spec.ts --runInBand
```

Expected: FAIL because deployment files are not wired yet.

- [ ] **Step 3: Add `dockerfile.gateway`**

Create `dockerfile.gateway` by mirroring `dockerfile`, changing:

```dockerfile
ENV APP_PORT=48086
ENV LOG_APP_NAME=kt-napcat-webui-gateway
EXPOSE 48086
CMD ["node", "dist/apps/napcat-webui-gateway/main"]
```

Keep font and production dependency installation consistent with the API image.

- [ ] **Step 4: Update Jenkins**

Add parameter:

```groovy
string(name: 'GATEWAY_IMAGE_NAME', defaultValue: 'kt-napcat-webui-gateway', description: 'NapCat WebUI Gateway 镜像名称')
```

In `Prepare`, compute:

```groovy
env.GATEWAY_DOCKER_IMAGE = registry ? "${registry}/${params.GATEWAY_IMAGE_NAME}:${env.IMAGE_TAG_FINAL}" : "${params.GATEWAY_IMAGE_NAME}:${env.IMAGE_TAG_FINAL}"
env.GATEWAY_DOCKER_IMAGE_LATEST = registry ? "${registry}/${params.GATEWAY_IMAGE_NAME}:latest" : "${params.GATEWAY_IMAGE_NAME}:latest"
```

In Docker Build, after API image build:

```groovy
docker build -f dockerfile.gateway -t ${env.GATEWAY_DOCKER_IMAGE} .
if [ '${env.GATEWAY_DOCKER_IMAGE}' != '${env.GATEWAY_DOCKER_IMAGE_LATEST}' ]; then
  docker tag ${env.GATEWAY_DOCKER_IMAGE} ${env.GATEWAY_DOCKER_IMAGE_LATEST}
fi
```

In Docker Push, push both Gateway tags. In K8s Deploy, set the Gateway deployment image:

```groovy
kubectl ${kubeConfigArg} ${namespaceArg} set image deployment/kt-napcat-webui-gateway gateway=${env.GATEWAY_DOCKER_IMAGE}
```

Check rollout for both API and Gateway deployments.

- [ ] **Step 5: Update K8s manifest**

Add Gateway Deployment and Service in `k8s/prod/api.yaml`:

```yaml
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: kt-napcat-webui-gateway
  namespace: kt-prod
  labels:
    app: kt-napcat-webui-gateway
spec:
  replicas: 1
  revisionHistoryLimit: 3
  selector:
    matchLabels:
      app: kt-napcat-webui-gateway
  template:
    metadata:
      labels:
        app: kt-napcat-webui-gateway
    spec:
      containers:
        - name: gateway
          image: k3d-kt-registry.localhost:5000/kt-napcat-webui-gateway:latest
          imagePullPolicy: IfNotPresent
          ports:
            - name: http
              containerPort: 48086
          env:
            - name: NODE_ENV
              value: production
            - name: TZ
              value: Asia/Shanghai
            - name: NAPCAT_WEBUI_GATEWAY_PORT
              value: "48086"
            - name: NAPCAT_WEBUI_GATEWAY_REDIS_HOST
              value: kt-qqbot-plugin-redis
            - name: NAPCAT_WEBUI_GATEWAY_REDIS_PORT
              value: "6379"
            - name: NAPCAT_WEBUI_GATEWAY_PUBLIC_BASE_URL
              value: /napcat-webui
          envFrom:
            - secretRef:
                name: kt-template-online-api-env
          readinessProbe:
            httpGet:
              path: /internal/health
              port: 48086
            initialDelaySeconds: 5
            periodSeconds: 10
            timeoutSeconds: 3
            failureThreshold: 6
---
apiVersion: v1
kind: Service
metadata:
  name: kt-napcat-webui-gateway
  namespace: kt-prod
  labels:
    app: kt-napcat-webui-gateway
spec:
  type: NodePort
  selector:
    app: kt-napcat-webui-gateway
  ports:
    - name: http
      port: 48086
      targetPort: 48086
      nodePort: 30086
```

Add API env:

```yaml
- name: NAPCAT_WEBUI_GATEWAY_INTERNAL_BASE_URL
  value: http://kt-napcat-webui-gateway:48086
- name: NAPCAT_WEBUI_GATEWAY_PUBLIC_BASE_URL
  value: /napcat-webui
```

Ensure `NAPCAT_WEBUI_GATEWAY_INTERNAL_SECRET` is read from the existing production env secret, not committed.

- [ ] **Step 6: Update docs**

Add to `README.md` and `API.md`:

```text
NapCat WebUI Gateway:
- API creates route-bound sessions through /qqbot/napcat/webui/session.
- Gateway listens on 48086 and proxies /napcat-webui/session/:sessionId/*.
- Required env: NAPCAT_WEBUI_GATEWAY_INTERNAL_BASE_URL, NAPCAT_WEBUI_GATEWAY_PUBLIC_BASE_URL, NAPCAT_WEBUI_GATEWAY_INTERNAL_SECRET, NAPCAT_WEBUI_GATEWAY_REDIS_HOST, NAPCAT_WEBUI_GATEWAY_REDIS_PORT.
- Browser responses must not contain webuiToken, Credential, Docker host ports, or NAS SSH paths.
```

- [ ] **Step 7: Run deployment tests and build checks**

```powershell
pnpm --dir D:\MyFiles\KT\Node\kt-template-online-api jest --runTestsByPath test/modules/qqbot/napcat-webui-gateway/gateway-deployment.spec.ts --runInBand
pnpm --dir D:\MyFiles\KT\Node\kt-template-online-api run typecheck
pnpm --dir D:\MyFiles\KT\Node\kt-template-online-api run build
```

Expected: tests PASS, typecheck PASS, build PASS, and `dist/apps/napcat-webui-gateway/main.js` exists.

- [ ] **Step 8: Commit Task 5**

```powershell
git -C D:\MyFiles\KT\Node\kt-template-online-api add dockerfile.gateway Jenkinsfile k8s/prod/api.yaml README.md API.md test/modules/qqbot/napcat-webui-gateway/gateway-deployment.spec.ts
git -C D:\MyFiles\KT\Node\kt-template-online-api commit -m "feat: 部署NapCat WebUI Gateway"
```

---

### Task 6: Add Admin API Client, Route, and Account Action

**Files:**
- Modify: `apps/web-antdv-next/src/api/qqbot/napcat.ts`
- Modify: `apps/web-antdv-next/src/api/qqbot/napcat.spec.ts`
- Modify: `apps/web-antdv-next/src/router/routes/modules/qqbot.ts`
- Modify: `apps/web-antdv-next/src/views/qqbot/account/list.tsx`
- Modify: `apps/web-antdv-next/src/views/qqbot/account/napcat-boundary.spec.ts`

- [ ] **Step 1: Add failing Admin API tests**

Extend `apps/web-antdv-next/src/api/qqbot/napcat.spec.ts` with:

```ts
it('calls NapCat WebUI Gateway session endpoints', async () => {
  await createQqbotNapcatWebuiSession('account-1');
  await heartbeatQqbotNapcatWebuiSession('session-1');
  await revokeQqbotNapcatWebuiSession('session-1');

  expect(postMock).toHaveBeenCalledWith('/qqbot/napcat/webui/session', {
    accountId: 'account-1',
  });
  expect(postMock).toHaveBeenCalledWith(
    '/qqbot/napcat/webui/session/session-1/heartbeat',
  );
  expect(postMock).toHaveBeenCalledWith(
    '/qqbot/napcat/webui/session/session-1/revoke',
  );
});
```

Import the new functions at the top of the spec.

- [ ] **Step 2: Add failing boundary test**

Extend `apps/web-antdv-next/src/views/qqbot/account/napcat-boundary.spec.ts`:

```ts
it('keeps WebUI route lifecycle outside the account list page', () => {
  const source = readAccountSource('list.tsx');

  expect(source).toContain('QqBotAccountNapcatWebui');
  expect(source).not.toContain('createQqbotNapcatWebuiSession');
  expect(source).not.toContain('heartbeatQqbotNapcatWebuiSession');
  expect(source).not.toContain('iframe');
});
```

- [ ] **Step 3: Run Admin tests and verify RED**

```powershell
pnpm --dir D:\MyFiles\KT\Vue\kt-template-admin --filter @vben/web-antdv-next vitest run apps/web-antdv-next/src/api/qqbot/napcat.spec.ts apps/web-antdv-next/src/views/qqbot/account/napcat-boundary.spec.ts
```

Expected: FAIL because functions and route action are missing.

- [ ] **Step 4: Add Admin API functions**

Modify `apps/web-antdv-next/src/api/qqbot/napcat.ts`:

```ts
export namespace QqbotNapcatApi {
  export interface WebuiGatewaySession {
    account: { id: string; name?: string; selfId: string };
    container: { id: string; name: string; webuiStatus: string };
    expiresAt: number;
    iframeUrl: string;
    sessionId: string;
  }
}

export function createQqbotNapcatWebuiSession(accountId: string) {
  return requestClient.post<QqbotNapcatApi.WebuiGatewaySession>(
    '/qqbot/napcat/webui/session',
    { accountId },
  );
}

export function heartbeatQqbotNapcatWebuiSession(sessionId: string) {
  return requestClient.post<Pick<QqbotNapcatApi.WebuiGatewaySession, 'expiresAt' | 'sessionId'> & { status: 'active' }>(
    `/qqbot/napcat/webui/session/${sessionId}/heartbeat`,
  );
}

export function revokeQqbotNapcatWebuiSession(sessionId: string) {
  return requestClient.post<boolean>(
    `/qqbot/napcat/webui/session/${sessionId}/revoke`,
  );
}
```

- [ ] **Step 5: Add hidden Admin route**

Modify `apps/web-antdv-next/src/router/routes/modules/qqbot.ts`:

```ts
{
  component: () => import('#/views/qqbot/account/napcat-webui'),
  meta: {
    activePath: '/qqbot/account',
    hideInMenu: true,
    title: 'NapCat WebUI',
  },
  name: 'QqBotAccountNapcatWebui',
  path: '/qqbot/account/:accountId/napcat-webui',
}
```

- [ ] **Step 6: Add account row action**

Modify `apps/web-antdv-next/src/views/qqbot/account/list.tsx`:

```ts
{
  disabled: (row) => !row.napcat?.containerName || getWebuiStatus(row) === 'offline',
  key: 'napcatWebui',
  label: 'WebUI',
  onClick: openNapcatWebui,
  permissionCodes: ['QqBot:Account:WebUI'],
}
```

Add:

```ts
function openNapcatWebui(row: QqbotApi.Account) {
  void router.push({
    name: 'QqBotAccountNapcatWebui',
    params: { accountId: row.id },
  });
}
```

- [ ] **Step 7: Run Admin API and boundary tests**

```powershell
pnpm --dir D:\MyFiles\KT\Vue\kt-template-admin --filter @vben/web-antdv-next vitest run apps/web-antdv-next/src/api/qqbot/napcat.spec.ts apps/web-antdv-next/src/views/qqbot/account/napcat-boundary.spec.ts
```

Expected: tests PASS.

- [ ] **Step 8: Commit Task 6**

```powershell
git -C D:\MyFiles\KT\Vue\kt-template-admin add apps/web-antdv-next/src/api/qqbot/napcat.ts apps/web-antdv-next/src/api/qqbot/napcat.spec.ts apps/web-antdv-next/src/router/routes/modules/qqbot.ts apps/web-antdv-next/src/views/qqbot/account/list.tsx apps/web-antdv-next/src/views/qqbot/account/napcat-boundary.spec.ts
git -C D:\MyFiles\KT\Vue\kt-template-admin commit -m "feat: 增加NapCat WebUI入口"
```

---

### Task 7: Build Admin Route Page and Lifecycle Composable

**Files:**
- Create: `apps/web-antdv-next/src/views/qqbot/account/napcat-webui/index.tsx`
- Create: `apps/web-antdv-next/src/views/qqbot/account/napcat-webui/index.scss`
- Create: `apps/web-antdv-next/src/views/qqbot/account/napcat-webui/useNapcatWebuiGatewaySession.ts`
- Create: `apps/web-antdv-next/src/views/qqbot/account/napcat-webui/napcat-webui.spec.tsx`

- [ ] **Step 1: Write route lifecycle tests**

Create `apps/web-antdv-next/src/views/qqbot/account/napcat-webui/napcat-webui.spec.tsx`:

```ts
import { flushPromises, mount } from '@vue/test-utils';
import { describe, expect, it, vi } from 'vitest';
import NapcatWebuiPage from './index';

const createSession = vi.fn();
const heartbeat = vi.fn();
const revoke = vi.fn();

vi.mock('#/api/qqbot/napcat', () => ({
  createQqbotNapcatWebuiSession: createSession,
  heartbeatQqbotNapcatWebuiSession: heartbeat,
  revokeQqbotNapcatWebuiSession: revoke,
}));

vi.mock('vue-router', () => ({
  useRoute: () => ({ params: { accountId: 'account-1' } }),
  useRouter: () => ({ push: vi.fn() }),
}));

describe('NapcatWebuiPage', () => {
  it('creates a Gateway session on mount and revokes on unmount', async () => {
    createSession.mockResolvedValue({
      account: { id: 'account-1', selfId: '1914728559' },
      container: {
        id: 'container-1',
        name: 'kt-qqbot-napcat-1',
        webuiStatus: 'online',
      },
      expiresAt: Date.now() + 60000,
      iframeUrl: '/napcat-webui/session/session-1/bootstrap?ticket=ticket-1',
      sessionId: 'session-1',
    });
    heartbeat.mockResolvedValue({
      expiresAt: Date.now() + 60000,
      sessionId: 'session-1',
      status: 'active',
    });

    const wrapper = mount(NapcatWebuiPage);
    await flushPromises();

    expect(createSession).toHaveBeenCalledWith('account-1');
    expect(wrapper.find('iframe').attributes('src')).toContain(
      '/napcat-webui/session/session-1/bootstrap',
    );

    wrapper.unmount();
    await flushPromises();

    expect(revoke).toHaveBeenCalledWith('session-1');
  });
});
```

- [ ] **Step 2: Run route page test and verify RED**

```powershell
pnpm --dir D:\MyFiles\KT\Vue\kt-template-admin --filter @vben/web-antdv-next vitest run apps/web-antdv-next/src/views/qqbot/account/napcat-webui/napcat-webui.spec.tsx
```

Expected: FAIL because the page does not exist.

- [ ] **Step 3: Implement lifecycle composable**

Create `useNapcatWebuiGatewaySession.ts` with:

```ts
import { useIntervalFn } from '@vueuse/core';
import { onBeforeUnmount, ref } from 'vue';
import {
  createQqbotNapcatWebuiSession,
  heartbeatQqbotNapcatWebuiSession,
  revokeQqbotNapcatWebuiSession,
  type QqbotNapcatApi,
} from '#/api/qqbot/napcat';

export type NapcatWebuiSessionState = 'error' | 'idle' | 'loading' | 'ready' | 'revoked';

/**
 * Owns one route-bound NapCat WebUI Gateway session.
 *
 * @param accountId QQBot account id from the current route.
 * @returns Reactive session state and lifecycle commands for the WebUI page.
 */
export function useNapcatWebuiGatewaySession(accountId: string) {
  const errorMessage = ref('');
  const session = ref<QqbotNapcatApi.WebuiGatewaySession>();
  const state = ref<NapcatWebuiSessionState>('idle');

  const { pause: pauseHeartbeat, resume: resumeHeartbeat } = useIntervalFn(
    () => {
      const sessionId = session.value?.sessionId;
      if (!sessionId) return;
      void heartbeatQqbotNapcatWebuiSession(sessionId).catch(() => {
        errorMessage.value = 'NapCat WebUI 会话心跳失败，请重新打开';
        state.value = 'error';
        pauseHeartbeat();
      });
    },
    20_000,
    { immediate: false },
  );

  /**
   * Creates a Gateway session and starts the route-bound heartbeat.
   */
  async function open() {
    state.value = 'loading';
    errorMessage.value = '';
    try {
      session.value = await createQqbotNapcatWebuiSession(accountId);
      state.value = 'ready';
      resumeHeartbeat();
    } catch (error: any) {
      errorMessage.value = error?.message || 'NapCat WebUI 会话创建失败';
      state.value = 'error';
      pauseHeartbeat();
    }
  }

  /**
   * Revokes the current Gateway session and stops heartbeat traffic.
   */
  async function revoke() {
    pauseHeartbeat();
    const sessionId = session.value?.sessionId;
    if (!sessionId) return;
    await revokeQqbotNapcatWebuiSession(sessionId).catch(() => undefined);
    state.value = 'revoked';
  }

  onBeforeUnmount(() => {
    void revoke();
  });

  return { errorMessage, open, revoke, session, state };
}
```

- [ ] **Step 4: Implement route page**

Create `index.tsx` using `Page`, `Button`, `Alert`, `Spin`, and `Typography` from existing UI libraries. The iframe must only render when `state === 'ready'` and `session.iframeUrl` exists.

Use one stable root element. Include top controls:

- back to account list;
- reopen session;
- close session;
- display selfId and container name.

- [ ] **Step 5: Add SCSS**

Create `index.scss`:

```scss
.qqbot-napcat-webui-page {
  display: flex;
  flex-direction: column;
  height: var(--vben-content-height);
  min-height: 0;
  overflow: hidden;

  &__bar {
    align-items: center;
    border-bottom: 1px solid hsl(var(--border));
    display: flex;
    flex: 0 0 auto;
    gap: 12px;
    justify-content: space-between;
    padding: 10px 12px;
  }

  &__frame-wrap {
    background: hsl(var(--background));
    flex: 1 1 auto;
    min-height: 0;
  }

  &__frame {
    border: 0;
    display: block;
    height: 100%;
    width: 100%;
  }
}
```

- [ ] **Step 6: Run Admin tests and typecheck**

```powershell
pnpm --dir D:\MyFiles\KT\Vue\kt-template-admin --filter @vben/web-antdv-next vitest run apps/web-antdv-next/src/views/qqbot/account/napcat-webui/napcat-webui.spec.tsx apps/web-antdv-next/src/api/qqbot/napcat.spec.ts apps/web-antdv-next/src/views/qqbot/account/napcat-boundary.spec.ts
pnpm --dir D:\MyFiles\KT\Vue\kt-template-admin --filter @vben/web-antdv-next run typecheck
```

Expected: tests PASS and typecheck PASS.

- [ ] **Step 7: Commit Task 7**

```powershell
git -C D:\MyFiles\KT\Vue\kt-template-admin add apps/web-antdv-next/src/views/qqbot/account/napcat-webui
git -C D:\MyFiles\KT\Vue\kt-template-admin commit -m "feat: 增加NapCat WebUI二级页面"
```

---

### Task 8: Local End-to-End Smoke

**Files:**
- No planned source changes. Validation fixes must be applied to the failing files from Tasks 1-7 and committed with the related repo.

- [ ] **Step 1: Confirm repo types and package managers**

```powershell
git -C D:\MyFiles\KT\Node\kt-template-online-api status --short --branch
Get-Content D:\MyFiles\KT\Node\kt-template-online-api\.node-version
Get-Content D:\MyFiles\KT\Node\kt-template-online-api\package.json | Select-String '"packageManager"'
git -C D:\MyFiles\KT\Vue\kt-template-admin status --short --branch
Get-Content D:\MyFiles\KT\Vue\kt-template-admin\.node-version
Get-Content D:\MyFiles\KT\Vue\kt-template-admin\package.json | Select-String '"packageManager"'
```

Expected: both repos are Git; API uses pnpm 9.15.9; Admin uses pnpm 10.28.2.

- [ ] **Step 2: Run focused API validation**

```powershell
pnpm --dir D:\MyFiles\KT\Node\kt-template-online-api jest --runTestsByPath test/modules/qqbot/napcat-webui-gateway/webui-gateway-contract.spec.ts test/modules/qqbot/napcat-webui-gateway/api-session.service.spec.ts test/apps/napcat-webui-gateway/session-store.spec.ts test/apps/napcat-webui-gateway/proxy-rewrite.spec.ts test/modules/qqbot/napcat-webui-gateway/gateway-deployment.spec.ts --runInBand
pnpm --dir D:\MyFiles\KT\Node\kt-template-online-api run typecheck
pnpm --dir D:\MyFiles\KT\Node\kt-template-online-api run build
```

Expected: focused tests PASS, typecheck PASS, build PASS.

- [ ] **Step 3: Run focused Admin validation**

```powershell
pnpm --dir D:\MyFiles\KT\Vue\kt-template-admin --filter @vben/web-antdv-next vitest run apps/web-antdv-next/src/api/qqbot/napcat.spec.ts apps/web-antdv-next/src/views/qqbot/account/napcat-boundary.spec.ts apps/web-antdv-next/src/views/qqbot/account/napcat-webui/napcat-webui.spec.tsx
pnpm --dir D:\MyFiles\KT\Vue\kt-template-admin --filter @vben/web-antdv-next run typecheck
```

Expected: focused tests PASS and typecheck PASS.

- [ ] **Step 4: Start local API and Gateway**

Use existing local env conventions. Start API and Gateway in bounded terminals:

```powershell
Start-Process powershell -WindowStyle Hidden -ArgumentList '-NoLogo','-Command','cd D:\MyFiles\KT\Node\kt-template-online-api; pnpm run start:dev *> .kt-workspace\logs\api-webui-gateway-api.log'
Start-Process powershell -WindowStyle Hidden -ArgumentList '-NoLogo','-Command','cd D:\MyFiles\KT\Node\kt-template-online-api; pnpm run start:gateway:dev *> .kt-workspace\logs\api-webui-gateway-service.log'
```

Expected: API listens on `48085`; Gateway listens on `48086`.

- [ ] **Step 5: Call the API session endpoint against local service**

Use an existing local Admin token. If a token is not available, log into the local Admin UI and copy the token from the tracked local workflow. Then call:

```powershell
curl.exe -sS -X POST "http://127.0.0.1:48085/qqbot/napcat/webui/session" -H "authorization: Bearer <local-admin-token>" -H "content-type: application/json" --data "{\"accountId\":\"<local-account-id>\"}"
```

Expected: JSON contains `sessionId`, `iframeUrl`, `account`, and `container`, and does not contain `webuiToken`, `Credential`, `6100`, or Docker/NAS host paths.

- [ ] **Step 6: Open the Admin route locally**

Start Admin for the route smoke:

```powershell
Start-Process powershell -WindowStyle Hidden -ArgumentList '-NoLogo','-Command','cd D:\MyFiles\KT\Vue\kt-template-admin; pnpm -F @vben/web-antdv-next run dev *> .kt-workspace\logs\admin-webui-gateway.log'
```

Open:

```text
http://127.0.0.1:5999/#/qqbot/account/<local-account-id>/napcat-webui
```

Expected: page renders the route console, creates a session, loads iframe shell, and revokes when navigating back to `/qqbot/account`.

- [ ] **Step 7: Clean local processes**

Stop Node processes started from these project paths:

```powershell
Get-CimInstance Win32_Process |
  Where-Object { $_.CommandLine -like '*kt-template-online-api*start:dev*' -or $_.CommandLine -like '*kt-template-online-api*start:gateway:dev*' -or $_.CommandLine -like '*kt-template-admin*web-antdv-next*dev*' } |
  ForEach-Object { Stop-Process -Id $_.ProcessId -Force }
```

- [ ] **Step 8: Commit local validation fixes**

If validation required fixes, commit the touched repo separately:

```powershell
git -C D:\MyFiles\KT\Node\kt-template-online-api status --short
git -C D:\MyFiles\KT\Vue\kt-template-admin status --short
```

Commit only files related to this feature.

---

### Task 9: Documentation, Review, Push, Deploy, and Online Closure

**Files:**
- Modify: `D:\MyFiles\KT\TASKS.md`

- [ ] **Step 1: Update `TASKS.md`**

Add a recent record with:

```text
范围：API Gateway service、Admin WebUI 二级页面、K8s/Jenkins Gateway 发布。
关键词：/qqbot/account/:accountId/napcat-webui、kt-napcat-webui-gateway、route-bound session、heartbeat/revoke、完整 WebUI 操作、token/Credential 不下发浏览器。
验证：列出 API focused tests、Admin focused tests、typecheck/build、本地 iframe smoke、线上 Gateway health 与账号 1914728559 iframe smoke。
```

- [ ] **Step 2: Run final local gates**

```powershell
git -C D:\MyFiles\KT\Node\kt-template-online-api diff --check
git -C D:\MyFiles\KT\Vue\kt-template-admin diff --check
pnpm --dir D:\MyFiles\KT\mcp\ktWorkflow run global-review -- --project api --changed-files <comma-separated-api-files>
pnpm --dir D:\MyFiles\KT\mcp\ktWorkflow run global-review -- --project admin --changed-files <comma-separated-admin-files>
pnpm --dir D:\MyFiles\KT\mcp\ktWorkflow run cleanup-history -- --dry-run
```

Expected: diff checks PASS, global-review findings=[], cleanup dry-run deleted=[].

- [ ] **Step 3: Commit remaining docs**

```powershell
git -C D:\MyFiles\KT add TASKS.md
git -C D:\MyFiles\KT commit -m "docs: 记录NapCat WebUI Gateway实施"
```

- [ ] **Step 4: Push when explicitly requested**

Push API and Admin only after user asks:

```powershell
git -C D:\MyFiles\KT\Node\kt-template-online-api push origin main
git -C D:\MyFiles\KT\Vue\kt-template-admin push origin main
```

- [ ] **Step 5: Observe Jenkins/K8s**

Use deploy observation for API:

```powershell
pnpm --dir D:\MyFiles\KT\mcp\ktWorkflow run deploy-observation -- --project api --job KT-Template/KT-Template-API/main --commit <api-commit> --execute
```

Manually verify Gateway because the current deploy-observation script targets API deployment by default:

```powershell
$script = @'
set -eu
KUBECONFIG_PATH='/vol1/docker/kt-k8s/kubeconfig/kt-nas.jenkins.yaml'
kubectl --kubeconfig "$KUBECONFIG_PATH" -n kt-prod get deployment kt-napcat-webui-gateway -o wide
kubectl --kubeconfig "$KUBECONFIG_PATH" -n kt-prod get pod -l app=kt-napcat-webui-gateway
kubectl --kubeconfig "$KUBECONFIG_PATH" -n kt-prod logs -l app=kt-napcat-webui-gateway --tail=80
'@
$script | ssh nas "tr -d '\015' | bash -s"
```

Expected: API and Gateway deployments Running/Ready, restartCount 0, Gateway image tag matches the Jenkins build.

- [ ] **Step 6: Configure Caddy/Admin route if not already routed**

On Tencent Cloud Caddy, follow the stabilized Caddy rule: backup `/opt/nas-gateway/caddy/Caddyfile`, add `/napcat-webui/*` reverse proxy to the Gateway NodePort or service route, run `caddy validate`, reload, then verify:

```powershell
curl.exe -I https://admin.kwitsukasa.top/napcat-webui/
```

Expected: public route reaches Gateway and does not expose upstream host details.

- [ ] **Step 7: Online functional smoke**

Open:

```text
https://admin.kwitsukasa.top/#/qqbot/account
```

For account `1914728559`:

1. Click `WebUI`.
2. Confirm route becomes `/#/qqbot/account/<account-id>/napcat-webui`.
3. Confirm iframe loads the original NapCat WebUI shell.
4. Open a safe WebUI page such as login status or settings.
5. Confirm browser URL does not contain `webuiToken`, `Credential`, `6100`, Docker container IP, NAS host path, or SSH route.
6. Navigate back to account list.
7. Verify Gateway logs or audit table contain revoke or heartbeat-timeout cleanup.

- [ ] **Step 8: Final report**

Report:

- API commit(s), Admin commit(s), root TASKS commit.
- Tests and typecheck/build evidence.
- Jenkins/K8s evidence.
- Online smoke evidence.
- Any remaining blocker with exact next command.

---

## Self-Review

- Spec coverage: covered Admin row action, second-level route, route-bound session lifecycle, independent Gateway process, full WebUI operation, no token/credential/browser leak, Redis session state, MySQL audit, K8s/Jenkins deployment, and online smoke.
- Placeholder scan: no forbidden placeholder words or cross-task shorthand remain in the plan body.
- Type consistency: all plan tasks use `QqBot:Account:WebUI`, `/qqbot/napcat/webui/session`, `/napcat-webui/session/:sessionId`, `kt-napcat-webui-gateway`, `48086`, and `QqbotNapcatWebuiGatewayService`.

## Execution Handoff

Plan complete and saved to `docs/plans/2026-06-24-qqbot-napcat-webui-gateway-implementation-plan.md`.

Two execution options:

1. **Subagent-Driven (recommended)** - Dispatch a fresh subagent per task, review between tasks, fast iteration.
2. **Inline Execution** - Execute tasks in this session using the KT-local execution loop, batch execution with checkpoints.

Which approach?