GPU_GUARD_MONOREPO/docs/superpowers/plans/2026-05-03-geo-s1-infrastructure-plan.md

# Geo S1 基础设施层 实施计划

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
>
> **上位文档**：[`../specs/2026-05-03-geo-master-roadmap.md`](../specs/2026-05-03-geo-master-roadmap.md) · [`../specs/2026-05-03-geo-s1-infrastructure-design.md`](../specs/2026-05-03-geo-s1-infrastructure-design.md)

**Goal:** 在 Neta 中新建 `geo` 模块，提供账号矩阵 / IP 池 / 指纹浏览器三位一体基础设施，支持账号-IP-Profile 严格 1:1:1 强绑定，启动 Chromium 让用户登录后自动抱回 cookie。

**Architecture:** 后端 Midway.js + Cool Admin 自动 CRUD；浏览器层"两层正交"——`IBrowserProvider` 仅管进程生命周期（S1 主实现 `PlainChromiumProvider` 用 playwright-cli + Chromium，BitBrowser/AntBrowser/AdsPower 全 stub），`BrowserAutomationService` 统一用 `playwright-cli -s={session}` 做自动化（cookie/state），与底层浏览器解耦；TypeORM `synchronize:true` 自动建表；菜单走 `base_sys_menu` 表；定时任务通过 `task_info` 表注册。

**Tech Stack:** Midway.js 3.20 / TypeScript 5.9 / TypeORM / MySQL 8 / Cool Admin 8 / Vue 3.5 / Element Plus 2.9 / playwright-cli（Neta 已有 skill，全局 CLI）/ jest。

---

## 文件结构

### 后端文件（新建 17 个）

| 路径 | 职责 |
|---|---|
| `packages/backend/src/modules/geo/config.ts` | 模块配置 |
| `packages/backend/src/modules/geo/entity/account.ts` | `geo_account` Entity |
| `packages/backend/src/modules/geo/entity/proxy_ip.ts` | `geo_proxy_ip` Entity |
| `packages/backend/src/modules/geo/entity/browser_profile.ts` | `geo_browser_profile` Entity |
| `packages/backend/src/modules/geo/service/encrypt.ts` | GeoEncryptService AES-256-GCM |
| `packages/backend/src/modules/geo/service/browser_automation.ts` | **统一自动化层**（playwright-cli 包装） |
| `packages/backend/src/modules/geo/service/proxy_ip.ts` | GeoProxyIpService |
| `packages/backend/src/modules/geo/service/browser_profile.ts` | GeoBrowserProfileService |
| `packages/backend/src/modules/geo/service/account.ts` | GeoAccountService 编排核心 |
| `packages/backend/src/modules/geo/controller/admin/proxy_ip.ts` | IP 池 Controller |
| `packages/backend/src/modules/geo/controller/admin/browser_profile.ts` | 指纹浏览器 Controller |
| `packages/backend/src/modules/geo/controller/admin/account.ts` | 账号 Controller |
| `packages/backend/src/modules/geo/provider/proxy/interface.ts` | IProxyProvider |
| `packages/backend/src/modules/geo/provider/proxy/local.ts` | LocalProxyProvider |
| `packages/backend/src/modules/geo/provider/proxy/tianqi.ts` | 天启占位 |
| `packages/backend/src/modules/geo/provider/browser/interface.ts` | IBrowserProvider |
| `packages/backend/src/modules/geo/provider/browser/plain_chromium.ts` | **★ S1 主实现**：playwright-cli + Chromium |
| `packages/backend/src/modules/geo/provider/browser/bitbrowser.stub.ts` | BitBrowser 占位 |
| `packages/backend/src/modules/geo/provider/browser/ant_browser.stub.ts` | ant-browser 占位 |
| `packages/backend/src/modules/geo/provider/browser/adspower.stub.ts` | AdsPower 占位 |

### 测试文件（新建 8 个）

| 路径 | 测试对象 |
|---|---|
| `packages/backend/test/modules/geo/encrypt.test.ts` | GeoEncryptService |
| `packages/backend/test/modules/geo/browser_automation.test.ts` | BrowserAutomationService（mock execSync） |
| `packages/backend/test/modules/geo/proxy_provider_local.test.ts` | LocalProxyProvider |
| `packages/backend/test/modules/geo/proxy_provider_tianqi.test.ts` | TianqiProxyProvider 占位 |
| `packages/backend/test/modules/geo/browser_provider_plain_chromium.test.ts` | PlainChromiumProvider（mock execSync） |
| `packages/backend/test/modules/geo/browser_provider_stub.test.ts` | BitBrowser/AntBrowser/AdsPower 占位 |
| `packages/backend/test/modules/geo/service_proxy_ip.test.ts` | GeoProxyIpService |
| `packages/backend/test/modules/geo/service_browser_profile.test.ts` | GeoBrowserProfileService |
| `packages/backend/test/modules/geo/service_account.test.ts` | GeoAccountService |

### 前端文件（新建 5 个）

| 路径 | 职责 |
|---|---|
| `packages/frontend/src/modules/geo/config.ts` | 前端模块配置 |
| `packages/frontend/src/modules/geo/views/dashboard.vue` | 占位 |
| `packages/frontend/src/modules/geo/views/proxies.vue` | IP 池 |
| `packages/frontend/src/modules/geo/views/browser-profiles.vue` | 指纹浏览器 |
| `packages/frontend/src/modules/geo/views/accounts.vue` | 账号矩阵 |

### 数据库种子（通过 MCP mysql 工具执行 INSERT）

- `base_sys_menu`：1 条目录 + 3 条菜单页面 + 14 条按钮权限
- `task_info`：1 条 cron 记录（`geo.proxy_ip.healthCheckAll` 每 6 小时）

---

## 依赖检查

实施前确认：
- `pnpm` 已安装
- 数据库 `neta_test` 可连通（`packages/backend/src/config/config.local.ts`）
- `playwright-cli` 全局可用（`npx --no-install playwright-cli --version` 或 `npm i -g @playwright/cli@latest`）
- Neta 已有 `packages/backend/skills/playwright-cli/SKILL.md`

---

## Task 0：geo 模块脚手架

**Files:**
- Create: `packages/backend/src/modules/geo/config.ts`

- [ ] **Step 1：创建目录骨架**

```bash
mkdir -p packages/backend/src/modules/geo/{entity,service,controller/admin,provider/proxy,provider/browser}
mkdir -p packages/backend/test/modules/geo
```

- [ ] **Step 2：创建模块 config.ts**

```typescript
// packages/backend/src/modules/geo/config.ts
import { ModuleConfig } from '@cool-midway/core';

export default () => {
  return {
    name: 'GEO 生成式引擎优化',
    description: 'GEO 内容矩阵执行平台：账号矩阵 / IP 池 / 指纹浏览器 / 内容生产 / AI 引用监测',
    order: 60,
  } as ModuleConfig;
};
```

- [ ] **Step 3：启动后端验证模块加载**

```bash
cd packages/backend && pnpm dev
```
预期：日志中 `GEO 生成式引擎优化` 模块被加载，无报错。Ctrl+C 停止。

- [ ] **Step 4：commit**

```bash
git add packages/backend/src/modules/geo/config.ts
git commit -m "feat(geo): 新建 geo 模块脚手架（S1）"
```

---

## Task 1：GeoEncryptService

**Files:**
- Create: `packages/backend/src/modules/geo/service/encrypt.ts`
- Test: `packages/backend/test/modules/geo/encrypt.test.ts`

- [ ] **Step 1：写测试**

```typescript
// packages/backend/test/modules/geo/encrypt.test.ts
import { GeoEncryptService } from '../../../src/modules/geo/service/encrypt';

describe('GeoEncryptService', () => {
  const svc = new GeoEncryptService();

  beforeAll(() => {
    process.env.SKILL_SECRET_KEY = 'test-key-for-jest-only-do-not-use-in-prod';
  });

  it('加密后能解密回原文', () => {
    const plain = 'hello world 你好';
    const cipher = svc.encrypt(plain);
    expect(cipher).not.toBe(plain);
    expect(svc.decrypt(cipher)).toBe(plain);
  });

  it('每次加密同一字符串密文不同（IV 随机）', () => {
    const plain = 'same input';
    const c1 = svc.encrypt(plain);
    const c2 = svc.encrypt(plain);
    expect(c1).not.toBe(c2);
  });

  it('密文被篡改时解密抛错', () => {
    const cipher = svc.encrypt('test');
    expect(() => svc.decrypt(cipher.slice(0, -4) + 'XXXX')).toThrow();
  });

  it('支持长 JSON 字符串（cookies 场景）', () => {
    const cookies = JSON.stringify(Array(50).fill({ name: 'sess', value: 'abc'.repeat(20), domain: '.xiaohongshu.com' }));
    expect(svc.decrypt(svc.encrypt(cookies))).toBe(cookies);
  });
});
```

- [ ] **Step 2：跑测试看失败**

```bash
cd packages/backend && pnpm jest test/modules/geo/encrypt.test.ts
```
预期：FAIL

- [ ] **Step 3：实现**

```typescript
// packages/backend/src/modules/geo/service/encrypt.ts
import { Provide, Scope, ScopeEnum } from '@midwayjs/core';
import * as crypto from 'crypto';

@Provide()
@Scope(ScopeEnum.Singleton)
export class GeoEncryptService {
  private readonly algorithm = 'aes-256-gcm';

  private deriveKey(): Buffer {
    const raw = process.env.SKILL_SECRET_KEY || process.env.APP_SECRET;
    if (!raw) throw new Error('EncryptionKeyMissing: 必须配置 SKILL_SECRET_KEY 或 APP_SECRET');
    return crypto.createHash('sha256').update(raw).digest();
  }

  encrypt(plain: string): string {
    const key = this.deriveKey();
    const iv = crypto.randomBytes(12);
    const cipher = crypto.createCipheriv(this.algorithm, key, iv);
    const ct = Buffer.concat([cipher.update(plain, 'utf8'), cipher.final()]);
    const tag = cipher.getAuthTag();
    return Buffer.concat([iv, tag, ct]).toString('base64');
  }

  decrypt(cipherText: string): string {
    const key = this.deriveKey();
    const buf = Buffer.from(cipherText, 'base64');
    if (buf.length < 28) throw new Error('Invalid ciphertext: too short');
    const iv = buf.subarray(0, 12);
    const tag = buf.subarray(12, 28);
    const ct = buf.subarray(28);
    const decipher = crypto.createDecipheriv(this.algorithm, key, iv);
    decipher.setAuthTag(tag);
    return Buffer.concat([decipher.update(ct), decipher.final()]).toString('utf8');
  }
}
```

- [ ] **Step 4：跑测试看通过**

```bash
cd packages/backend && pnpm jest test/modules/geo/encrypt.test.ts
```
预期：PASS（4 tests）

- [ ] **Step 5：commit**

```bash
git add packages/backend/src/modules/geo/service/encrypt.ts packages/backend/test/modules/geo/encrypt.test.ts
git commit -m "feat(geo): 加密服务 GeoEncryptService（AES-256-GCM）"
```

---

## Task 2：BrowserAutomationService（统一自动化层）

> **关键设计**：这是 S1 与未来 S3 共用的自动化基础。所有 cookie 抓取、状态保存都通过它，不再分散到各 Provider 里。

**Files:**
- Create: `packages/backend/src/modules/geo/service/browser_automation.ts`
- Test: `packages/backend/test/modules/geo/browser_automation.test.ts`

- [ ] **Step 1：写测试**

```typescript
// packages/backend/test/modules/geo/browser_automation.test.ts
import { BrowserAutomationService } from '../../../src/modules/geo/service/browser_automation';

describe('BrowserAutomationService', () => {
  let svc: BrowserAutomationService;
  let execMock: jest.Mock;

  beforeEach(() => {
    execMock = jest.fn();
    svc = new BrowserAutomationService();
    (svc as any).exec = execMock;
  });

  it('getCookies 调 cookie-list --raw 并解析 JSON', async () => {
    execMock.mockReturnValue(JSON.stringify([{ name: 'sid', value: 'abc', domain: '.xhs.com' }]));
    const cookies = await svc.getCookies('geo-1', 'xhs.com');
    expect(execMock).toHaveBeenCalledWith(
      expect.stringContaining('playwright-cli -s=geo-1 --raw cookie-list --domain=xhs.com')
    );
    expect(cookies).toHaveLength(1);
    expect(cookies[0].name).toBe('sid');
  });

  it('getCookies 没传 domain 时不加 --domain', async () => {
    execMock.mockReturnValue('[]');
    await svc.getCookies('geo-1');
    expect(execMock).toHaveBeenCalledWith(expect.stringMatching(/cookie-list(?! --domain)/));
  });

  it('getCookies 输出非 JSON 时返回空数组', async () => {
    execMock.mockReturnValue('not-a-json');
    const cookies = await svc.getCookies('geo-1');
    expect(cookies).toEqual([]);
  });

  it('saveState 调 state-save', async () => {
    execMock.mockReturnValue('');
    await svc.saveState('geo-1', '/tmp/state.json');
    expect(execMock).toHaveBeenCalledWith(
      expect.stringContaining('playwright-cli -s=geo-1 state-save /tmp/state.json')
    );
  });

  it('loadState 调 state-load', async () => {
    execMock.mockReturnValue('');
    await svc.loadState('geo-1', '/tmp/state.json');
    expect(execMock).toHaveBeenCalledWith(
      expect.stringContaining('playwright-cli -s=geo-1 state-load /tmp/state.json')
    );
  });

  it('exec 失败时抛 BrowserAutomationFailed', async () => {
    execMock.mockImplementation(() => { throw new Error('cli not found'); });
    await expect(svc.getCookies('geo-1')).rejects.toThrow(/BrowserAutomationFailed/);
  });
});
```

- [ ] **Step 2：跑测试看失败**

```bash
cd packages/backend && pnpm jest test/modules/geo/browser_automation.test.ts
```
预期：FAIL

- [ ] **Step 3：实现**

```typescript
// packages/backend/src/modules/geo/service/browser_automation.ts
import { Provide, Scope, ScopeEnum, Logger, ILogger } from '@midwayjs/core';
import { execSync } from 'child_process';

export interface CookieItem {
  name: string;
  value: string;
  domain: string;
  path?: string;
  expires?: number;
  httpOnly?: boolean;
  secure?: boolean;
  sameSite?: string;
}

@Provide()
@Scope(ScopeEnum.Singleton)
export class BrowserAutomationService {
  @Logger()
  logger: ILogger;

  /** 单点 exec，便于测试时 mock。子类/测试可重写。 */
  protected exec(cmd: string): string {
    return execSync(cmd, { encoding: 'utf8', maxBuffer: 16 * 1024 * 1024 });
  }

  /** 列出 cookie；domain 可选 */
  async getCookies(sessionName: string, domain?: string): Promise<CookieItem[]> {
    const domainArg = domain ? ` --domain=${domain}` : '';
    const cmd = `playwright-cli -s=${sessionName} --raw cookie-list${domainArg}`;
    let out: string;
    try {
      out = this.exec(cmd);
    } catch (e: any) {
      throw new Error(`BrowserAutomationFailed: ${cmd} → ${e.message}`);
    }
    try {
      return JSON.parse(out.trim());
    } catch {
      this.logger.warn(`getCookies output not JSON: ${out.slice(0, 200)}`);
      return [];
    }
  }

  /** 保存完整登录态（cookie + localStorage）到文件 */
  async saveState(sessionName: string, filePath: string): Promise<void> {
    const cmd = `playwright-cli -s=${sessionName} state-save ${filePath}`;
    try {
      this.exec(cmd);
    } catch (e: any) {
      throw new Error(`BrowserAutomationFailed: ${cmd} → ${e.message}`);
    }
  }

  /** 从文件恢复登录态 */
  async loadState(sessionName: string, filePath: string): Promise<void> {
    const cmd = `playwright-cli -s=${sessionName} state-load ${filePath}`;
    try {
      this.exec(cmd);
    } catch (e: any) {
      throw new Error(`BrowserAutomationFailed: ${cmd} → ${e.message}`);
    }
  }

  /** S3 后续会增加 click / type / snapshot 等方法 */
}
```

- [ ] **Step 4：跑测试看通过**

```bash
cd packages/backend && pnpm jest test/modules/geo/browser_automation.test.ts
```
预期：PASS（6 tests）

- [ ] **Step 5：commit**

```bash
git add packages/backend/src/modules/geo/service/browser_automation.ts packages/backend/test/modules/geo/browser_automation.test.ts
git commit -m "feat(geo): BrowserAutomationService 统一自动化层（playwright-cli 包装）"
```

---

## Task 3：Provider 接口定义

**Files:**
- Create: `packages/backend/src/modules/geo/provider/proxy/interface.ts`
- Create: `packages/backend/src/modules/geo/provider/browser/interface.ts`

- [ ] **Step 1：IProxyProvider**

```typescript
// packages/backend/src/modules/geo/provider/proxy/interface.ts
export interface AcquireOpts {
  region?: string;
  isp?: string;
  duration?: 'fixed' | 'rotating';
  extra?: Record<string, any>;
}

export interface ProxyInfo {
  externalId: string;
  mode: 'local' | 'third_party';
  protocol: 'http' | 'socks5';
  host?: string;
  port?: number;
  username?: string;
  password?: string;
  region?: string;
  isp?: string;
  expiresAt?: Date;
}

export interface HealthCheckResult {
  ok: boolean;
  latencyMs: number;
}

export interface IProxyProvider {
  readonly name: string;
  acquire(opts: AcquireOpts): Promise<ProxyInfo>;
  release(externalId: string): Promise<void>;
  healthCheck(p: ProxyInfo): Promise<HealthCheckResult>;
  list?(): Promise<ProxyInfo[]>;
}
```

- [ ] **Step 2：IBrowserProvider（仅进程生命周期，不含自动化）**

```typescript
// packages/backend/src/modules/geo/provider/browser/interface.ts
import type { ProxyInfo } from '../proxy/interface';

export interface CreateOpts {
  name: string;
  sessionName: string;
  userAgent?: string;
  osPlatform?: 'windows' | 'mac' | 'linux';
  timezone?: string;
  language?: string;
  screenW?: number;
  screenH?: number;
  fingerprint?: Record<string, any>;
}

export interface ProfileInfo {
  sessionName: string;
  profileDir?: string;
  configPath?: string;
  userAgent: string;
  osPlatform: string;
  timezone: string;
  language: string;
  screenW: number;
  screenH: number;
}

export interface IBrowserProvider {
  readonly name: string;
  /** 创建 profile 配置（不启动进程） */
  create(opts: CreateOpts): Promise<ProfileInfo>;
  /** 删除 profile 配置 */
  delete(profile: ProfileInfo): Promise<void>;
  /** 把代理写入 profile 配置 */
  attachProxy(profile: ProfileInfo, proxy: ProxyInfo): Promise<void>;
  /** 启动浏览器进程并打开 URL */
  open(profile: ProfileInfo, url?: string): Promise<void>;
  /** 关闭浏览器进程 */
  close(profile: ProfileInfo): Promise<void>;
}
```

- [ ] **Step 3：tsc 类型检查**

```bash
cd packages/backend && npx tsc --noEmit
```
预期：通过

- [ ] **Step 4：commit**

```bash
git add packages/backend/src/modules/geo/provider/
git commit -m "feat(geo): IProxyProvider 与 IBrowserProvider 接口（自动化已剥离到 BrowserAutomationService）"
```

---

## Task 4：LocalProxyProvider

**Files:**
- Create: `packages/backend/src/modules/geo/provider/proxy/local.ts`
- Test: `packages/backend/test/modules/geo/proxy_provider_local.test.ts`

- [ ] **Step 1：写测试**

```typescript
// packages/backend/test/modules/geo/proxy_provider_local.test.ts
import { LocalProxyProvider } from '../../../src/modules/geo/provider/proxy/local';

describe('LocalProxyProvider', () => {
  const p = new LocalProxyProvider();

  it('name 为 local', () => {
    expect(p.name).toBe('local');
  });

  it('acquire 返回 mode=local', async () => {
    const info = await p.acquire({ region: 'shanghai' });
    expect(info.mode).toBe('local');
    expect(info.externalId).toMatch(/^local-/);
    expect(info.host).toBeUndefined();
  });

  it('release 不抛错', async () => {
    await expect(p.release('local-xxx')).resolves.toBeUndefined();
  });

  it('healthCheck 返回 ok 与延迟', async () => {
    (global as any).fetch = jest.fn().mockResolvedValue({ ok: true });
    const info = await p.acquire({});
    const result = await p.healthCheck(info);
    expect(result.ok).toBe(true);
    expect(result.latencyMs).toBeGreaterThanOrEqual(0);
  });
});
```

- [ ] **Step 2：跑测试看失败**

```bash
cd packages/backend && pnpm jest test/modules/geo/proxy_provider_local.test.ts
```
预期：FAIL

- [ ] **Step 3：实现**

```typescript
// packages/backend/src/modules/geo/provider/proxy/local.ts
import { IProxyProvider, AcquireOpts, ProxyInfo, HealthCheckResult } from './interface';

const HEALTH_URL = 'https://www.baidu.com';
const HEALTH_TIMEOUT = 5000;

export class LocalProxyProvider implements IProxyProvider {
  readonly name = 'local';

  async acquire(opts: AcquireOpts): Promise<ProxyInfo> {
    return {
      externalId: `local-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
      mode: 'local',
      protocol: 'http',
      region: opts.region,
      isp: opts.isp,
    };
  }

  async release(_externalId: string): Promise<void> {}

  async healthCheck(_p: ProxyInfo): Promise<HealthCheckResult> {
    const ctrl = new AbortController();
    const timer = setTimeout(() => ctrl.abort(), HEALTH_TIMEOUT);
    const start = Date.now();
    try {
      const res = await fetch(HEALTH_URL, { signal: ctrl.signal, method: 'HEAD' });
      return { ok: res.ok, latencyMs: Date.now() - start };
    } catch {
      return { ok: false, latencyMs: Date.now() - start };
    } finally {
      clearTimeout(timer);
    }
  }
}
```

- [ ] **Step 4：跑测试看通过**

```bash
cd packages/backend && pnpm jest test/modules/geo/proxy_provider_local.test.ts
```
预期：PASS（4 tests）

- [ ] **Step 5：commit**

```bash
git add packages/backend/src/modules/geo/provider/proxy/local.ts packages/backend/test/modules/geo/proxy_provider_local.test.ts
git commit -m "feat(geo): LocalProxyProvider"
```

---

## Task 5：占位 Provider（Tianqi + 浏览器三个 stub）

**Files:**
- Create: `packages/backend/src/modules/geo/provider/proxy/tianqi.ts`
- Create: `packages/backend/src/modules/geo/provider/browser/bitbrowser.stub.ts`
- Create: `packages/backend/src/modules/geo/provider/browser/ant_browser.stub.ts`
- Create: `packages/backend/src/modules/geo/provider/browser/adspower.stub.ts`
- Test: `packages/backend/test/modules/geo/proxy_provider_tianqi.test.ts`
- Test: `packages/backend/test/modules/geo/browser_provider_stub.test.ts`

- [ ] **Step 1：写测试**

```typescript
// packages/backend/test/modules/geo/proxy_provider_tianqi.test.ts
import { TianqiProxyProvider } from '../../../src/modules/geo/provider/proxy/tianqi';

describe('TianqiProxyProvider（占位）', () => {
  const p = new TianqiProxyProvider();

  it('name 为 tianqi', () => {
    expect(p.name).toBe('tianqi');
  });

  it('acquire 抛 NotImplemented', async () => {
    await expect(p.acquire({})).rejects.toThrow(/NotImplemented/);
  });

  it('healthCheck 抛 NotImplemented', async () => {
    await expect(p.healthCheck({} as any)).rejects.toThrow(/NotImplemented/);
  });
});
```

```typescript
// packages/backend/test/modules/geo/browser_provider_stub.test.ts
import { BitBrowserStubProvider } from '../../../src/modules/geo/provider/browser/bitbrowser.stub';
import { AntBrowserStubProvider } from '../../../src/modules/geo/provider/browser/ant_browser.stub';
import { AdsPowerStubProvider } from '../../../src/modules/geo/provider/browser/adspower.stub';

describe('Browser 占位 Provider', () => {
  it('BitBrowser stub 抛 NotImplemented', async () => {
    const p = new BitBrowserStubProvider();
    expect(p.name).toBe('bitbrowser');
    await expect(p.create({ name: 't', sessionName: 's' })).rejects.toThrow(/NotImplemented/);
  });

  it('AntBrowser stub 抛 NotImplemented', async () => {
    const p = new AntBrowserStubProvider();
    expect(p.name).toBe('ant_browser');
    await expect(p.create({ name: 't', sessionName: 's' })).rejects.toThrow(/NotImplemented/);
  });

  it('AdsPower stub 抛 NotImplemented', async () => {
    const p = new AdsPowerStubProvider();
    expect(p.name).toBe('adspower');
    await expect(p.create({ name: 't', sessionName: 's' })).rejects.toThrow(/NotImplemented/);
  });
});
```

- [ ] **Step 2：跑测试看失败**

```bash
cd packages/backend && pnpm jest test/modules/geo/proxy_provider_tianqi.test.ts test/modules/geo/browser_provider_stub.test.ts
```
预期：FAIL

- [ ] **Step 3：实现 4 个占位**

```typescript
// packages/backend/src/modules/geo/provider/proxy/tianqi.ts
// 天启 HTTP 代理 Provider（占位）
// TODO: 等用户提供天启 HTTP 接入文档后实现
import { IProxyProvider, AcquireOpts, ProxyInfo, HealthCheckResult } from './interface';

export class TianqiProxyProvider implements IProxyProvider {
  readonly name = 'tianqi';
  async acquire(_opts: AcquireOpts): Promise<ProxyInfo> {
    throw new Error('NotImplemented: TianqiProxyProvider 等待对接文档');
  }
  async release(_externalId: string): Promise<void> {
    throw new Error('NotImplemented: TianqiProxyProvider 等待对接文档');
  }
  async healthCheck(_p: ProxyInfo): Promise<HealthCheckResult> {
    throw new Error('NotImplemented: TianqiProxyProvider 等待对接文档');
  }
}
```

```typescript
// packages/backend/src/modules/geo/provider/browser/bitbrowser.stub.ts
// BitBrowser 占位。未来实现：调 BitBrowser Local API 启动 profile，playwright-cli attach 进去
import { IBrowserProvider, CreateOpts, ProfileInfo } from './interface';
import type { ProxyInfo } from '../proxy/interface';

export class BitBrowserStubProvider implements IBrowserProvider {
  readonly name = 'bitbrowser';
  async create(_o: CreateOpts): Promise<ProfileInfo> { throw new Error('NotImplemented: BitBrowser 占位'); }
  async delete(_p: ProfileInfo): Promise<void> { throw new Error('NotImplemented: BitBrowser 占位'); }
  async attachProxy(_p: ProfileInfo, _x: ProxyInfo): Promise<void> { throw new Error('NotImplemented: BitBrowser 占位'); }
  async open(_p: ProfileInfo, _url?: string): Promise<void> { throw new Error('NotImplemented: BitBrowser 占位'); }
  async close(_p: ProfileInfo): Promise<void> { throw new Error('NotImplemented: BitBrowser 占位'); }
}
```

```typescript
// packages/backend/src/modules/geo/provider/browser/ant_browser.stub.ts
// ant-browser 占位。等用户提供源码后实现
import { IBrowserProvider, CreateOpts, ProfileInfo } from './interface';
import type { ProxyInfo } from '../proxy/interface';

export class AntBrowserStubProvider implements IBrowserProvider {
  readonly name = 'ant_browser';
  async create(_o: CreateOpts): Promise<ProfileInfo> { throw new Error('NotImplemented: ant-browser 占位'); }
  async delete(_p: ProfileInfo): Promise<void> { throw new Error('NotImplemented: ant-browser 占位'); }
  async attachProxy(_p: ProfileInfo, _x: ProxyInfo): Promise<void> { throw new Error('NotImplemented: ant-browser 占位'); }
  async open(_p: ProfileInfo, _url?: string): Promise<void> { throw new Error('NotImplemented: ant-browser 占位'); }
  async close(_p: ProfileInfo): Promise<void> { throw new Error('NotImplemented: ant-browser 占位'); }
}
```

```typescript
// packages/backend/src/modules/geo/provider/browser/adspower.stub.ts
import { IBrowserProvider, CreateOpts, ProfileInfo } from './interface';
import type { ProxyInfo } from '../proxy/interface';

export class AdsPowerStubProvider implements IBrowserProvider {
  readonly name = 'adspower';
  async create(_o: CreateOpts): Promise<ProfileInfo> { throw new Error('NotImplemented: AdsPower 占位'); }
  async delete(_p: ProfileInfo): Promise<void> { throw new Error('NotImplemented: AdsPower 占位'); }
  async attachProxy(_p: ProfileInfo, _x: ProxyInfo): Promise<void> { throw new Error('NotImplemented: AdsPower 占位'); }
  async open(_p: ProfileInfo, _url?: string): Promise<void> { throw new Error('NotImplemented: AdsPower 占位'); }
  async close(_p: ProfileInfo): Promise<void> { throw new Error('NotImplemented: AdsPower 占位'); }
}
```

- [ ] **Step 4：跑测试看通过**

```bash
cd packages/backend && pnpm jest test/modules/geo/proxy_provider_tianqi.test.ts test/modules/geo/browser_provider_stub.test.ts
```
预期：PASS（6 tests）

- [ ] **Step 5：commit**

```bash
git add packages/backend/src/modules/geo/provider/proxy/tianqi.ts packages/backend/src/modules/geo/provider/browser/*.stub.ts packages/backend/test/modules/geo/proxy_provider_tianqi.test.ts packages/backend/test/modules/geo/browser_provider_stub.test.ts
git commit -m "feat(geo): Tianqi + 三个浏览器 Provider 占位实现"
```

---

## Task 6：PlainChromiumProvider（S1 主实现）

**Files:**
- Create: `packages/backend/src/modules/geo/provider/browser/plain_chromium.ts`
- Test: `packages/backend/test/modules/geo/browser_provider_plain_chromium.test.ts`

- [ ] **Step 1：写测试（mock execSync + fs）**

```typescript
// packages/backend/test/modules/geo/browser_provider_plain_chromium.test.ts
import { PlainChromiumProvider } from '../../../src/modules/geo/provider/browser/plain_chromium';

describe('PlainChromiumProvider', () => {
  let p: PlainChromiumProvider;
  let execMock: jest.Mock;
  let writeMock: jest.Mock;
  let unlinkMock: jest.Mock;

  beforeEach(() => {
    execMock = jest.fn();
    writeMock = jest.fn();
    unlinkMock = jest.fn();
    p = new PlainChromiumProvider({ baseDir: '/tmp/geo-test' });
    (p as any).exec = execMock;
    (p as any).writeFile = writeMock;
    (p as any).rm = unlinkMock;
  });

  it('name 为 plain_chromium', () => {
    expect(p.name).toBe('plain_chromium');
  });

  it('create 写 profile 目录与代理 config，返回 ProfileInfo', async () => {
    const info = await p.create({
      name: 'acc1', sessionName: 'geo-1',
      userAgent: 'Mozilla/5.0', osPlatform: 'windows',
      timezone: 'Asia/Shanghai', language: 'zh-CN', screenW: 1920, screenH: 1080,
    });
    expect(info.sessionName).toBe('geo-1');
    expect(info.profileDir).toMatch(/geo-1/);
    expect(info.configPath).toMatch(/geo-1.*\.json$/);
  });

  it('attachProxy 把代理配置写入 config 文件', async () => {
    const profile = { sessionName: 'geo-1', configPath: '/tmp/geo-test/configs/geo-1.json' } as any;
    await p.attachProxy(profile, {
      externalId: 'p', mode: 'third_party', protocol: 'http',
      host: '1.2.3.4', port: 8080, username: 'u', password: 'pp',
    });
    expect(writeMock).toHaveBeenCalled();
    const written = writeMock.mock.calls[0][1];
    expect(written).toContain('"server": "http://1.2.3.4:8080"');
    expect(written).toContain('"username": "u"');
  });

  it('open 调 playwright-cli open --persistent --headed', async () => {
    await p.open(
      { sessionName: 'geo-1', profileDir: '/tmp/p', configPath: '/tmp/c.json' } as any,
      'https://example.com'
    );
    expect(execMock).toHaveBeenCalledWith(
      expect.stringContaining('playwright-cli -s=geo-1 open https://example.com --persistent --profile=/tmp/p --headed --config=/tmp/c.json')
    );
  });

  it('close 调 playwright-cli close', async () => {
    await p.close({ sessionName: 'geo-1' } as any);
    expect(execMock).toHaveBeenCalledWith(expect.stringContaining('playwright-cli -s=geo-1 close'));
  });

  it('delete 调 delete-data 并清理 config', async () => {
    await p.delete({ sessionName: 'geo-1', configPath: '/tmp/c.json', profileDir: '/tmp/p' } as any);
    expect(execMock).toHaveBeenCalledWith(expect.stringContaining('playwright-cli -s=geo-1 delete-data'));
    expect(unlinkMock).toHaveBeenCalled();
  });

  it('exec 失败抛 BrowserProviderUnavailable', async () => {
    execMock.mockImplementation(() => { throw new Error('cli not found'); });
    await expect(
      p.open({ sessionName: 'geo-1', profileDir: '/tmp/p', configPath: '/tmp/c.json' } as any)
    ).rejects.toThrow(/BrowserProviderUnavailable/);
  });
});
```

- [ ] **Step 2：跑测试看失败**

```bash
cd packages/backend && pnpm jest test/modules/geo/browser_provider_plain_chromium.test.ts
```
预期：FAIL

- [ ] **Step 3：实现**

```typescript
// packages/backend/src/modules/geo/provider/browser/plain_chromium.ts
// S1 主实现：通过 playwright-cli 启动 Chromium，每个账号一个命名 session + 持久化 profile + 代理 config
import { execSync } from 'child_process';
import { writeFileSync, mkdirSync, rmSync, existsSync } from 'fs';
import * as path from 'path';
import { IBrowserProvider, CreateOpts, ProfileInfo } from './interface';
import type { ProxyInfo } from '../proxy/interface';

export interface PlainChromiumOptions {
  baseDir?: string;
}

export class PlainChromiumProvider implements IBrowserProvider {
  readonly name = 'plain_chromium';
  private readonly baseDir: string;

  constructor(opts: PlainChromiumOptions = {}) {
    this.baseDir = opts.baseDir
      || process.env.GEO_BROWSER_DATA_DIR
      || path.join(process.cwd(), '.geo-browser');
  }

  // 单点封装，便于测试 mock
  protected exec(cmd: string): string {
    return execSync(cmd, { encoding: 'utf8' });
  }
  protected writeFile(p: string, content: string): void {
    mkdirSync(path.dirname(p), { recursive: true });
    writeFileSync(p, content, 'utf8');
  }
  protected rm(p: string): void {
    if (existsSync(p)) rmSync(p, { recursive: true, force: true });
  }

  async create(opts: CreateOpts): Promise<ProfileInfo> {
    const profileDir = path.join(this.baseDir, 'profiles', opts.sessionName);
    const configPath = path.join(this.baseDir, 'configs', `${opts.sessionName}.json`);
    mkdirSync(profileDir, { recursive: true });
    // 初始 config（无代理）
    this.writeFile(configPath, JSON.stringify({ launchOptions: {} }, null, 2));
    return {
      sessionName: opts.sessionName,
      profileDir,
      configPath,
      userAgent: opts.userAgent || '',
      osPlatform: opts.osPlatform || 'windows',
      timezone: opts.timezone || 'Asia/Shanghai',
      language: opts.language || 'zh-CN',
      screenW: opts.screenW || 1920,
      screenH: opts.screenH || 1080,
    };
  }

  async delete(profile: ProfileInfo): Promise<void> {
    try {
      this.exec(`playwright-cli -s=${profile.sessionName} delete-data`);
    } catch {/* 忽略：可能未启动 */}
    if (profile.configPath) this.rm(profile.configPath);
    if (profile.profileDir) this.rm(profile.profileDir);
  }

  async attachProxy(profile: ProfileInfo, proxy: ProxyInfo): Promise<void> {
    if (!profile.configPath) throw new Error('attachProxy: profile.configPath 缺失');
    const config: any = { launchOptions: {} };
    if (proxy.mode === 'third_party' && proxy.host && proxy.port) {
      config.launchOptions.proxy = {
        server: `${proxy.protocol}://${proxy.host}:${proxy.port}`,
      };
      if (proxy.username) config.launchOptions.proxy.username = proxy.username;
      if (proxy.password) config.launchOptions.proxy.password = proxy.password;
    }
    this.writeFile(profile.configPath, JSON.stringify(config, null, 2));
  }

  async open(profile: ProfileInfo, url?: string): Promise<void> {
    const parts = [`playwright-cli -s=${profile.sessionName} open`];
    if (url) parts.push(url);
    parts.push('--persistent');
    if (profile.profileDir) parts.push(`--profile=${profile.profileDir}`);
    parts.push('--headed');
    if (profile.configPath) parts.push(`--config=${profile.configPath}`);
    const cmd = parts.join(' ');
    try {
      this.exec(cmd);
    } catch (e: any) {
      throw new Error(`BrowserProviderUnavailable: ${cmd} → ${e.message}`);
    }
  }

  async close(profile: ProfileInfo): Promise<void> {
    try {
      this.exec(`playwright-cli -s=${profile.sessionName} close`);
    } catch {/* 容忍 */}
  }
}
```

- [ ] **Step 4：跑测试看通过**

```bash
cd packages/backend && pnpm jest test/modules/geo/browser_provider_plain_chromium.test.ts
```
预期：PASS（7 tests）

- [ ] **Step 5：commit**

```bash
git add packages/backend/src/modules/geo/provider/browser/plain_chromium.ts packages/backend/test/modules/geo/browser_provider_plain_chromium.test.ts
git commit -m "feat(geo): PlainChromiumProvider（S1 主实现，playwright-cli + Chromium）"
```

---

## Task 7：GeoProxyIp Entity

**Files:**
- Create: `packages/backend/src/modules/geo/entity/proxy_ip.ts`

- [ ] **Step 1：实现**

```typescript
// packages/backend/src/modules/geo/entity/proxy_ip.ts
import { BaseEntity } from '../../base/entity/base';
import { Column, Entity, Index } from 'typeorm';

@Entity('geo_proxy_ip')
export class GeoProxyIpEntity extends BaseEntity {
  @Column({ comment: '名称' })
  name: string;

  @Column({ comment: '所属 Provider：local / tianqi', length: 32 })
  provider: string;

  @Column({ comment: '模式：local / third_party', length: 16 })
  mode: string;

  @Column({ comment: '代理主机', nullable: true, length: 128 })
  host: string;

  @Column({ comment: '代理端口', nullable: true })
  port: number;

  @Column({ comment: '协议 http/socks5', length: 8, default: 'http' })
  protocol: string;

  @Column({ comment: '用户名（加密）', nullable: true, length: 256 })
  username: string;

  @Column({ comment: '密码（加密）', nullable: true, length: 512 })
  password: string;

  @Column({ comment: '区域', nullable: true, length: 64 })
  region: string;

  @Column({ comment: 'ISP', nullable: true, length: 32 })
  isp: string;

  @Column({ comment: 'Provider 侧外部 ID', nullable: true, length: 128 })
  externalId: string;

  @Index({ unique: true, where: 'bind_account_id IS NOT NULL' })
  @Column({ comment: '绑定账号 ID（强 1:1）', nullable: true })
  bindAccountId: number;

  @Column({ comment: '状态 active/expired/error/unbound', length: 16, default: 'unbound' })
  status: string;

  @Column({ comment: '健康检查延迟 ms', nullable: true })
  latencyMs: number;

  @Column({ comment: '上次检查时间', type: 'datetime', nullable: true })
  lastCheckAt: Date;

  @Column({ comment: '过期时间', type: 'datetime', nullable: true })
  expiresAt: Date;

  @Column({ comment: '扩展字段', type: 'json', nullable: true })
  extra: any;
}
```

- [ ] **Step 2：启动后端验证表自动创建**

```bash
cd packages/backend && pnpm dev
```
用 MCP 验证：`mcp__mysql__list_tables` 应包含 `geo_proxy_ip`。Ctrl+C 停止。

- [ ] **Step 3：commit**

```bash
git add packages/backend/src/modules/geo/entity/proxy_ip.ts
git commit -m "feat(geo): GeoProxyIp Entity"
```

---

## Task 8：GeoBrowserProfile Entity

**Files:**
- Create: `packages/backend/src/modules/geo/entity/browser_profile.ts`

- [ ] **Step 1：实现**

```typescript
// packages/backend/src/modules/geo/entity/browser_profile.ts
import { BaseEntity } from '../../base/entity/base';
import { Column, Entity, Index } from 'typeorm';

@Entity('geo_browser_profile')
export class GeoBrowserProfileEntity extends BaseEntity {
  @Column({ comment: '名称' })
  name: string;

  @Column({ comment: 'Provider：plain_chromium / bitbrowser / ant_browser / adspower', length: 32 })
  provider: string;

  @Index()
  @Column({ comment: 'playwright-cli 命名 session（唯一标识）', length: 128 })
  sessionName: string;

  @Index({ unique: true, where: 'account_id IS NOT NULL' })
  @Column({ comment: '绑定账号 ID（强 1:1）', nullable: true })
  accountId: number;

  @Column({ comment: 'profile 持久化目录', nullable: true, length: 512 })
  profileDir: string;

  @Column({ comment: '代理配置文件路径', nullable: true, length: 512 })
  configPath: string;

  @Column({ comment: 'UserAgent', nullable: true, length: 512 })
  userAgent: string;

  @Column({ comment: 'OS 平台', nullable: true, length: 32 })
  osPlatform: string;

  @Column({ comment: '时区', nullable: true, length: 32 })
  timezone: string;

  @Column({ comment: '语言', nullable: true, length: 16 })
  language: string;

  @Column({ comment: '屏幕宽', nullable: true })
  screenW: number;

  @Column({ comment: '屏幕高', nullable: true })
  screenH: number;

  @Column({ comment: '深度指纹（S1 不填，等 ant-browser）', type: 'json', nullable: true })
  fingerprint: any;

  @Column({ comment: '上次打开时间', type: 'datetime', nullable: true })
  lastOpenAt: Date;

  @Column({ comment: '状态 created/running/closed/error/deleted', length: 16, default: 'created' })
  status: string;

  @Column({ comment: '扩展字段', type: 'json', nullable: true })
  extra: any;
}
```

- [ ] **Step 2：启动后端验证**

```bash
cd packages/backend && pnpm dev
```
MCP `list_tables` 验证 `geo_browser_profile`。Ctrl+C。

- [ ] **Step 3：commit**

```bash
git add packages/backend/src/modules/geo/entity/browser_profile.ts
git commit -m "feat(geo): GeoBrowserProfile Entity（sessionName/profileDir/configPath）"
```

---

## Task 9：GeoAccount Entity

**Files:**
- Create: `packages/backend/src/modules/geo/entity/account.ts`

- [ ] **Step 1：实现**

```typescript
// packages/backend/src/modules/geo/entity/account.ts
import { BaseEntity } from '../../base/entity/base';
import { Column, Entity, Index, Unique } from 'typeorm';

@Entity('geo_account')
@Unique('uk_geo_account_platform_login', ['platform', 'loginAccount'])
export class GeoAccountEntity extends BaseEntity {
  @Column({ comment: '账号备注名/昵称' })
  name: string;

  @Index()
  @Column({ comment: '平台 xiaohongshu/douyin/weibo/zhihu/wechat', length: 32 })
  platform: string;

  @Column({ comment: '登录账号/手机号', length: 128 })
  loginAccount: string;

  @Column({ comment: 'cookies（加密 JSON）', type: 'text', nullable: true })
  cookies: string;

  @Column({ comment: 'Cookie 抓取时间', type: 'datetime', nullable: true })
  cookieCapturedAt: Date;

  @Column({ comment: '登录状态 never/logged_in/expired', length: 16, default: 'never' })
  loginStatus: string;

  @Column({ comment: '账号状态 draft/active/risky/banned/deleted', length: 16, default: 'draft' })
  status: string;

  @Index({ unique: true, where: 'proxy_id IS NOT NULL' })
  @Column({ comment: '绑定 IP', nullable: true })
  proxyId: number;

  @Index({ unique: true, where: 'browser_profile_id IS NOT NULL' })
  @Column({ comment: '绑定指纹浏览器 profile', nullable: true })
  browserProfileId: number;

  @Column({ comment: '人设 ID（S2 用）', nullable: true })
  personaId: number;

  @Column({ comment: 'Agent 配置 ID（S3 用）', nullable: true })
  agentConfigId: number;

  @Column({ comment: '上次活跃时间', type: 'datetime', nullable: true })
  lastActiveAt: Date;

  @Column({ comment: '平台特定字段', type: 'json', nullable: true })
  extra: any;
}
```

- [ ] **Step 2：启动验证三张表全部就位**

`mcp__mysql__list_tables` → geo_account / geo_proxy_ip / geo_browser_profile 都在。

- [ ] **Step 3：commit**

```bash
git add packages/backend/src/modules/geo/entity/account.ts
git commit -m "feat(geo): GeoAccount Entity"
```

---

## Task 10：GeoProxyIpService

**Files:**
- Create: `packages/backend/src/modules/geo/service/proxy_ip.ts`
- Test: `packages/backend/test/modules/geo/service_proxy_ip.test.ts`

- [ ] **Step 1：写测试**

```typescript
// packages/backend/test/modules/geo/service_proxy_ip.test.ts
import { GeoProxyIpService } from '../../../src/modules/geo/service/proxy_ip';
import { LocalProxyProvider } from '../../../src/modules/geo/provider/proxy/local';

describe('GeoProxyIpService', () => {
  let svc: GeoProxyIpService;
  let repo: any;

  beforeEach(() => {
    process.env.SKILL_SECRET_KEY = 'test-key';
    repo = {
      save: jest.fn(async (e) => ({ id: 1, ...e })),
      findOneBy: jest.fn(),
      find: jest.fn().mockResolvedValue([]),
      update: jest.fn(),
      create: (e: any) => e,
    };
    svc = new GeoProxyIpService();
    (svc as any).proxyIpEntity = repo;
    (svc as any).encryptService = {
      encrypt: (s: string) => `enc:${s}`,
      decrypt: (s: string) => s.replace(/^enc:/, ''),
    };
  });

  it('getProvider("local") 返回 LocalProxyProvider', () => {
    expect(svc.getProvider('local')).toBeInstanceOf(LocalProxyProvider);
  });

  it('getProvider 未知名称抛错', () => {
    expect(() => svc.getProvider('unknown')).toThrow();
  });

  it('healthCheckAll 遍历 active IP 并更新状态', async () => {
    repo.find.mockResolvedValue([
      { id: 1, provider: 'local', mode: 'local', protocol: 'http', status: 'active' },
    ]);
    (global as any).fetch = jest.fn().mockResolvedValue({ ok: true });
    await svc.healthCheckAll();
    expect(repo.update).toHaveBeenCalledWith(1, expect.objectContaining({ status: 'active' }));
  });

  it('toProxyInfo 解密 username/password', () => {
    const info = svc.toProxyInfo({ id: 1, externalId: 'p', mode: 'third_party', protocol: 'http', host: 'h', port: 8080, username: 'enc:user', password: 'enc:pass' } as any);
    expect(info.username).toBe('user');
    expect(info.password).toBe('pass');
  });
});
```

- [ ] **Step 2：跑测试看失败**

```bash
cd packages/backend && pnpm jest test/modules/geo/service_proxy_ip.test.ts
```

- [ ] **Step 3：实现**

```typescript
// packages/backend/src/modules/geo/service/proxy_ip.ts
import { Provide, Inject, ILogger, Logger } from '@midwayjs/core';
import { BaseService } from '@cool-midway/core';
import { InjectEntityModel } from '@midwayjs/typeorm';
import { Repository } from 'typeorm';
import { GeoProxyIpEntity } from '../entity/proxy_ip';
import { GeoEncryptService } from './encrypt';
import { IProxyProvider, AcquireOpts, ProxyInfo } from '../provider/proxy/interface';
import { LocalProxyProvider } from '../provider/proxy/local';
import { TianqiProxyProvider } from '../provider/proxy/tianqi';

@Provide()
export class GeoProxyIpService extends BaseService {
  @InjectEntityModel(GeoProxyIpEntity)
  proxyIpEntity: Repository<GeoProxyIpEntity>;

  @Inject()
  encryptService: GeoEncryptService;

  @Logger()
  logger: ILogger;

  private readonly providers = new Map<string, IProxyProvider>([
    ['local', new LocalProxyProvider()],
    ['tianqi', new TianqiProxyProvider()],
  ]);

  getProvider(name: string): IProxyProvider {
    const p = this.providers.get(name);
    if (!p) throw new Error(`Unknown proxy provider: ${name}`);
    return p;
  }

  async acquire(dto: { provider: string } & AcquireOpts): Promise<ProxyInfo> {
    return this.getProvider(dto.provider).acquire(dto);
  }

  async persist(info: ProxyInfo & { name?: string; provider?: string }, manager?: any): Promise<GeoProxyIpEntity> {
    const repo = manager ? manager.getRepository(GeoProxyIpEntity) : this.proxyIpEntity;
    const entity = repo.create({
      name: info.name || `${info.mode}-${info.region || 'unknown'}`,
      provider: info.provider || (info.mode === 'local' ? 'local' : 'tianqi'),
      mode: info.mode,
      host: info.host,
      port: info.port,
      protocol: info.protocol,
      username: info.username ? this.encryptService.encrypt(info.username) : null,
      password: info.password ? this.encryptService.encrypt(info.password) : null,
      region: info.region,
      isp: info.isp,
      externalId: info.externalId,
      status: 'active',
      expiresAt: info.expiresAt,
    });
    return repo.save(entity);
  }

  toProxyInfo(e: GeoProxyIpEntity): ProxyInfo {
    return {
      externalId: e.externalId,
      mode: e.mode as any,
      protocol: e.protocol as any,
      host: e.host,
      port: e.port,
      username: e.username ? this.encryptService.decrypt(e.username) : undefined,
      password: e.password ? this.encryptService.decrypt(e.password) : undefined,
      region: e.region,
      isp: e.isp,
      expiresAt: e.expiresAt,
    };
  }

  async healthCheckAll(): Promise<void> {
    const ips = await this.proxyIpEntity.find({ where: { status: 'active' } });
    for (const ip of ips) {
      try {
        const result = await this.getProvider(ip.provider).healthCheck(this.toProxyInfo(ip));
        await this.proxyIpEntity.update(ip.id, {
          latencyMs: result.latencyMs,
          lastCheckAt: new Date(),
          status: result.ok ? 'active' : 'error',
        });
        if (!result.ok) this.logger.warn(`[GEO] IP ${ip.id} health check failed`);
      } catch (e: any) {
        this.logger.error(`[GEO] IP ${ip.id} health check error: ${e.message}`);
      }
    }
  }
}
```

- [ ] **Step 4：跑测试看通过**

```bash
cd packages/backend && pnpm jest test/modules/geo/service_proxy_ip.test.ts
```

- [ ] **Step 5：commit**

```bash
git add packages/backend/src/modules/geo/service/proxy_ip.ts packages/backend/test/modules/geo/service_proxy_ip.test.ts
git commit -m "feat(geo): GeoProxyIpService"
```

---

## Task 11：GeoBrowserProfileService

**Files:**
- Create: `packages/backend/src/modules/geo/service/browser_profile.ts`
- Test: `packages/backend/test/modules/geo/service_browser_profile.test.ts`

- [ ] **Step 1：写测试**

```typescript
// packages/backend/test/modules/geo/service_browser_profile.test.ts
import { GeoBrowserProfileService } from '../../../src/modules/geo/service/browser_profile';

describe('GeoBrowserProfileService', () => {
  let svc: GeoBrowserProfileService;
  let repo: any;
  let mockProvider: any;

  beforeEach(() => {
    repo = {
      save: jest.fn(async (e) => ({ id: 1, ...e })),
      findOneBy: jest.fn(),
      update: jest.fn(),
      create: (e: any) => e,
    };
    mockProvider = {
      name: 'plain_chromium',
      create: jest.fn().mockResolvedValue({
        sessionName: 'geo-1', profileDir: '/p', configPath: '/c.json',
        userAgent: 'UA', osPlatform: 'windows', timezone: 'Asia/Shanghai',
        language: 'zh-CN', screenW: 1920, screenH: 1080,
      }),
      delete: jest.fn(),
      attachProxy: jest.fn(),
      open: jest.fn(),
      close: jest.fn(),
    };
    svc = new GeoBrowserProfileService();
    (svc as any).profileEntity = repo;
    (svc as any).providers = new Map([['plain_chromium', mockProvider]]);
  });

  it('createAndPersist 调 provider.create 并写库', async () => {
    const e = await svc.createAndPersist('plain_chromium', { name: 't', sessionName: 'geo-1' });
    expect(mockProvider.create).toHaveBeenCalled();
    expect(repo.save).toHaveBeenCalled();
    expect(e.sessionName).toBe('geo-1');
  });

  it('open 调 provider.open 并更新 status', async () => {
    repo.findOneBy.mockResolvedValue({ id: 1, provider: 'plain_chromium', sessionName: 'geo-1', profileDir: '/p', configPath: '/c.json' });
    await svc.open(1, 'https://example.com');
    expect(mockProvider.open).toHaveBeenCalled();
    expect(repo.update).toHaveBeenCalledWith(1, expect.objectContaining({ status: 'running' }));
  });

  it('attachProxy 调 provider.attachProxy', async () => {
    repo.findOneBy.mockResolvedValue({ id: 1, provider: 'plain_chromium', sessionName: 'geo-1', configPath: '/c.json' });
    await svc.attachProxy(1, { externalId: 'p', mode: 'local', protocol: 'http' });
    expect(mockProvider.attachProxy).toHaveBeenCalled();
  });

  it('deleteAt 调 provider.delete + status=deleted', async () => {
    repo.findOneBy.mockResolvedValue({ id: 1, provider: 'plain_chromium', sessionName: 'geo-1' });
    await svc.deleteAt(1);
    expect(mockProvider.delete).toHaveBeenCalled();
    expect(repo.update).toHaveBeenCalledWith(1, expect.objectContaining({ status: 'deleted' }));
  });
});
```

- [ ] **Step 2：跑测试看失败**

```bash
cd packages/backend && pnpm jest test/modules/geo/service_browser_profile.test.ts
```

- [ ] **Step 3：实现**

```typescript
// packages/backend/src/modules/geo/service/browser_profile.ts
import { Provide, Logger, ILogger } from '@midwayjs/core';
import { BaseService } from '@cool-midway/core';
import { InjectEntityModel } from '@midwayjs/typeorm';
import { Repository } from 'typeorm';
import { GeoBrowserProfileEntity } from '../entity/browser_profile';
import { IBrowserProvider, CreateOpts, ProfileInfo } from '../provider/browser/interface';
import { PlainChromiumProvider } from '../provider/browser/plain_chromium';
import { BitBrowserStubProvider } from '../provider/browser/bitbrowser.stub';
import { AntBrowserStubProvider } from '../provider/browser/ant_browser.stub';
import { AdsPowerStubProvider } from '../provider/browser/adspower.stub';
import { ProxyInfo } from '../provider/proxy/interface';

@Provide()
export class GeoBrowserProfileService extends BaseService {
  @InjectEntityModel(GeoBrowserProfileEntity)
  profileEntity: Repository<GeoBrowserProfileEntity>;

  @Logger()
  logger: ILogger;

  private providers: Map<string, IBrowserProvider> = new Map([
    ['plain_chromium', new PlainChromiumProvider()],
    ['bitbrowser', new BitBrowserStubProvider()],
    ['ant_browser', new AntBrowserStubProvider()],
    ['adspower', new AdsPowerStubProvider()],
  ]);

  getProvider(name: string): IBrowserProvider {
    const p = this.providers.get(name);
    if (!p) throw new Error(`Unknown browser provider: ${name}`);
    return p;
  }

  toProfileInfo(e: GeoBrowserProfileEntity): ProfileInfo {
    return {
      sessionName: e.sessionName,
      profileDir: e.profileDir,
      configPath: e.configPath,
      userAgent: e.userAgent,
      osPlatform: e.osPlatform,
      timezone: e.timezone,
      language: e.language,
      screenW: e.screenW,
      screenH: e.screenH,
    };
  }

  async createAndPersist(provider: string, opts: CreateOpts, manager?: any): Promise<GeoBrowserProfileEntity> {
    const repo = manager ? manager.getRepository(GeoBrowserProfileEntity) : this.profileEntity;
    const info = await this.getProvider(provider).create(opts);
    const entity = repo.create({
      name: opts.name,
      provider,
      sessionName: info.sessionName,
      profileDir: info.profileDir,
      configPath: info.configPath,
      userAgent: info.userAgent,
      osPlatform: info.osPlatform,
      timezone: info.timezone,
      language: info.language,
      screenW: info.screenW,
      screenH: info.screenH,
      fingerprint: opts.fingerprint || null,
      status: 'created',
    });
    return repo.save(entity);
  }

  async open(id: number, url?: string): Promise<void> {
    const e = await this.profileEntity.findOneBy({ id });
    if (!e) throw new Error(`profile ${id} not found`);
    await this.getProvider(e.provider).open(this.toProfileInfo(e), url);
    await this.profileEntity.update(id, { status: 'running', lastOpenAt: new Date() });
  }

  async close(id: number): Promise<void> {
    const e = await this.profileEntity.findOneBy({ id });
    if (!e) return;
    await this.getProvider(e.provider).close(this.toProfileInfo(e)).catch(err =>
      this.logger.warn(`close profile ${id} failed: ${err.message}`)
    );
    await this.profileEntity.update(id, { status: 'closed' });
  }

  async attachProxy(profileId: number, proxy: ProxyInfo): Promise<void> {
    const e = await this.profileEntity.findOneBy({ id: profileId });
    if (!e) throw new Error(`profile ${profileId} not found`);
    await this.getProvider(e.provider).attachProxy(this.toProfileInfo(e), proxy);
  }

  async deleteAt(id: number, manager?: any): Promise<void> {
    const repo = manager ? manager.getRepository(GeoBrowserProfileEntity) : this.profileEntity;
    const e = await repo.findOneBy({ id });
    if (!e) return;
    await this.getProvider(e.provider).delete(this.toProfileInfo(e)).catch(err =>
      this.logger.warn(`delete profile ${id} external failed: ${err.message}`)
    );
    await repo.update(id, { status: 'deleted', accountId: null });
  }
}
```

- [ ] **Step 4：跑测试看通过**

- [ ] **Step 5：commit**

```bash
git add packages/backend/src/modules/geo/service/browser_profile.ts packages/backend/test/modules/geo/service_browser_profile.test.ts
git commit -m "feat(geo): GeoBrowserProfileService"
```

---

## Task 12：GeoAccountService 编排核心

**Files:**
- Create: `packages/backend/src/modules/geo/service/account.ts`
- Test: `packages/backend/test/modules/geo/service_account.test.ts`

- [ ] **Step 1：写测试（覆盖：add 编排、补偿、launch、captureCookies、rebindIp）**

```typescript
// packages/backend/test/modules/geo/service_account.test.ts
import { GeoAccountService } from '../../../src/modules/geo/service/account';

describe('GeoAccountService', () => {
  let svc: GeoAccountService;
  let proxySvc: any;
  let profileSvc: any;
  let automationSvc: any;
  let accountRepo: any;
  let dataSource: any;

  beforeEach(() => {
    proxySvc = {
      acquire: jest.fn().mockResolvedValue({ externalId: 'p1', mode: 'local', protocol: 'http' }),
      persist: jest.fn().mockResolvedValue({ id: 11, status: 'active', externalId: 'p1', mode: 'local', protocol: 'http' }),
      getProvider: jest.fn(() => ({ release: jest.fn() })),
      toProxyInfo: jest.fn().mockReturnValue({ externalId: 'p1', mode: 'local', protocol: 'http' }),
    };
    profileSvc = {
      createAndPersist: jest.fn().mockResolvedValue({ id: 22, sessionName: 'geo-22', profileDir: '/p', configPath: '/c.json' }),
      attachProxy: jest.fn(),
      deleteAt: jest.fn(),
      open: jest.fn(),
      toProfileInfo: jest.fn(o => ({ sessionName: o.sessionName })),
      getProvider: jest.fn(() => ({ delete: jest.fn() })),
    };
    automationSvc = {
      getCookies: jest.fn(),
      saveState: jest.fn(),
    };
    accountRepo = {
      create: (e: any) => e,
      save: jest.fn(async (e) => ({ id: 1, ...e })),
      findOneBy: jest.fn(),
      update: jest.fn(),
    };
    const profileRepo = { findOneBy: jest.fn() };
    dataSource = {
      transaction: jest.fn(async (cb: any) => cb({
        getRepository: () => accountRepo,
        update: accountRepo.update,
        findOne: accountRepo.findOneBy,
        findOneOrFail: accountRepo.findOneBy,
      })),
    };
    svc = new GeoAccountService();
    (svc as any).proxyService = proxySvc;
    (svc as any).profileService = profileSvc;
    (svc as any).browserAutomation = automationSvc;
    (svc as any).accountEntity = accountRepo;
    (svc as any).profileEntity = profileRepo;
    (svc as any).dataSource = dataSource;
    (svc as any).encryptService = {
      encrypt: (s: string) => `enc:${s}`,
      decrypt: (s: string) => s.replace(/^enc:/, ''),
    };
  });

  it('add：申请 IP+Profile→挂代理→写 account', async () => {
    const acc = await svc.add({
      name: 'a1', platform: 'xiaohongshu', loginAccount: '13800000000', ipMode: 'local',
    } as any);
    expect(proxySvc.acquire).toHaveBeenCalled();
    expect(profileSvc.createAndPersist).toHaveBeenCalled();
    expect(profileSvc.attachProxy).toHaveBeenCalled();
    expect(accountRepo.save).toHaveBeenCalled();
  });

  it('add：profile 创建失败 → 触发 IP 补偿', async () => {
    profileSvc.createAndPersist.mockRejectedValueOnce(new Error('boom'));
    await expect(svc.add({ name: 'a', platform: 'x', loginAccount: '1', ipMode: 'local' } as any)).rejects.toThrow('boom');
    expect(proxySvc.getProvider).toHaveBeenCalledWith('local');
  });

  it('captureCookies：cookies 为空时不写库', async () => {
    accountRepo.findOneBy.mockResolvedValue({ id: 1, browserProfileId: 22 });
    (svc as any).profileEntity.findOneBy.mockResolvedValue({ id: 22, sessionName: 'geo-22', status: 'running' });
    automationSvc.getCookies.mockResolvedValue([]);
    const r = await svc.captureCookies(1);
    expect(r.captured).toBe(0);
    expect(accountRepo.update).not.toHaveBeenCalled();
  });

  it('captureCookies：抓到 cookie 后加密存储 + saveState', async () => {
    accountRepo.findOneBy.mockResolvedValue({ id: 1, browserProfileId: 22 });
    (svc as any).profileEntity.findOneBy.mockResolvedValue({ id: 22, sessionName: 'geo-22', status: 'running' });
    automationSvc.getCookies.mockResolvedValue([{ name: 'sid', value: 'abc', domain: '.xhs.com' }]);
    await svc.captureCookies(1, ['xhs.com']);
    expect(automationSvc.getCookies).toHaveBeenCalledWith('geo-22', 'xhs.com');
    expect(accountRepo.update).toHaveBeenCalledWith(1, expect.objectContaining({
      loginStatus: 'logged_in',
      cookies: expect.stringMatching(/^enc:/),
    }));
    expect(automationSvc.saveState).toHaveBeenCalled();
  });

  it('launch：profile.status 设 running', async () => {
    accountRepo.findOneBy.mockResolvedValue({ id: 1, browserProfileId: 22 });
    await svc.launch(1, 'https://example.com');
    expect(profileSvc.open).toHaveBeenCalledWith(22, 'https://example.com');
  });
});
```

- [ ] **Step 2：跑测试看失败**

```bash
cd packages/backend && pnpm jest test/modules/geo/service_account.test.ts
```

- [ ] **Step 3：实现**

```typescript
// packages/backend/src/modules/geo/service/account.ts
import { Provide, Inject, Logger, ILogger } from '@midwayjs/core';
import { BaseService } from '@cool-midway/core';
import { InjectEntityModel, InjectDataSource } from '@midwayjs/typeorm';
import { Repository, DataSource } from 'typeorm';
import * as path from 'path';
import { GeoAccountEntity } from '../entity/account';
import { GeoBrowserProfileEntity } from '../entity/browser_profile';
import { GeoProxyIpEntity } from '../entity/proxy_ip';
import { GeoProxyIpService } from './proxy_ip';
import { GeoBrowserProfileService } from './browser_profile';
import { GeoEncryptService } from './encrypt';
import { BrowserAutomationService } from './browser_automation';

export interface AddAccountDto {
  name: string;
  platform: string;
  loginAccount: string;
  ipMode: 'local' | 'third_party';
  region?: string;
  isp?: string;
  fingerprint?: Record<string, any>;
  browserProvider?: string;
  userAgent?: string;
  timezone?: string;
  language?: string;
  screenW?: number;
  screenH?: number;
}

const STATE_DIR = process.env.GEO_STATE_DIR || path.join(process.cwd(), '.geo-browser', 'states');

@Provide()
export class GeoAccountService extends BaseService {
  @InjectEntityModel(GeoAccountEntity)
  accountEntity: Repository<GeoAccountEntity>;

  @InjectEntityModel(GeoBrowserProfileEntity)
  profileEntity: Repository<GeoBrowserProfileEntity>;

  @InjectDataSource()
  dataSource: DataSource;

  @Inject() proxyService: GeoProxyIpService;
  @Inject() profileService: GeoBrowserProfileService;
  @Inject() encryptService: GeoEncryptService;
  @Inject() browserAutomation: BrowserAutomationService;

  @Logger() logger: ILogger;

  /** 创建账号：原子分配 IP + Profile，强 1:1:1 */
  async add(dto: AddAccountDto): Promise<GeoAccountEntity> {
    let acquiredIp: any = null;
    let createdProfile: any = null;
    try {
      return await this.dataSource.transaction(async manager => {
        const ipInfo = await this.proxyService.acquire({
          provider: dto.ipMode === 'local' ? 'local' : 'tianqi',
          region: dto.region, isp: dto.isp,
        });
        acquiredIp = ipInfo;
        const ipEntity = await this.proxyService.persist({ ...ipInfo, name: dto.name + '-ip' }, manager);

        // sessionName 必须唯一；此时还没有 account.id，先用临时 nanoid，写完 account 后再修正
        const tmpSession = `geo-tmp-${Date.now()}-${Math.random().toString(36).slice(2, 6)}`;
        const profileEntity = await this.profileService.createAndPersist(
          dto.browserProvider || 'plain_chromium',
          {
            name: dto.name + '-profile',
            sessionName: tmpSession,
            userAgent: dto.userAgent,
            osPlatform: 'windows',
            timezone: dto.timezone,
            language: dto.language,
            screenW: dto.screenW, screenH: dto.screenH,
            fingerprint: dto.fingerprint,
          },
          manager,
        );
        createdProfile = profileEntity;

        await this.profileService.attachProxy(profileEntity.id, this.proxyService.toProxyInfo(ipEntity));

        const repo = manager.getRepository(GeoAccountEntity);
        const saved = await repo.save(repo.create({
          name: dto.name,
          platform: dto.platform,
          loginAccount: dto.loginAccount,
          loginStatus: 'never',
          status: 'draft',
          proxyId: ipEntity.id,
          browserProfileId: profileEntity.id,
        }));
        await manager.update(GeoProxyIpEntity, ipEntity.id, { bindAccountId: saved.id });
        await manager.update(GeoBrowserProfileEntity, profileEntity.id, {
          accountId: saved.id,
          sessionName: `geo-${saved.id}`, // 改回稳定 sessionName
        });
        return saved;
      });
    } catch (e: any) {
      if (createdProfile?.sessionName) {
        await this.profileService.getProvider(createdProfile.provider || 'plain_chromium')
          .delete(this.profileService.toProfileInfo(createdProfile))
          .catch(err => this.logger.warn(`补偿删 profile 失败: ${err.message}`));
      }
      if (acquiredIp?.externalId) {
        await this.proxyService.getProvider(acquiredIp.provider || 'local')
          .release(acquiredIp.externalId)
          .catch(err => this.logger.warn(`补偿 release IP 失败: ${err.message}`));
      }
      throw e;
    }
  }

  async launch(id: number, url?: string): Promise<{ sessionName: string }> {
    const acc = await this.accountEntity.findOneBy({ id });
    if (!acc) throw new Error(`account ${id} not found`);
    await this.profileService.open(acc.browserProfileId, url);
    const profile = await this.profileEntity.findOneBy({ id: acc.browserProfileId });
    return { sessionName: profile.sessionName };
  }

  async captureCookies(id: number, domains?: string[]): Promise<{ captured: number }> {
    const acc = await this.accountEntity.findOneBy({ id });
    if (!acc) throw new Error(`account ${id} not found`);
    const profile = await this.profileEntity.findOneBy({ id: acc.browserProfileId });
    if (!profile) throw new Error(`profile ${acc.browserProfileId} not found`);
    if (profile.status !== 'running') throw new Error('Browser not running, call launch first');

    const domain = domains?.[0];
    const cookies = await this.browserAutomation.getCookies(profile.sessionName, domain);
    if (cookies.length === 0) return { captured: 0 };

    const encrypted = this.encryptService.encrypt(JSON.stringify(cookies));
    await this.accountEntity.update(id, {
      cookies: encrypted,
      cookieCapturedAt: new Date(),
      loginStatus: 'logged_in',
    });

    const statePath = path.join(STATE_DIR, `geo-state-${id}.json`);
    await this.browserAutomation.saveState(profile.sessionName, statePath).catch(e =>
      this.logger.warn(`saveState failed for ${id}: ${e.message}`)
    );
    return { captured: cookies.length };
  }

  async rebindIp(accountId: number, newIpId: number): Promise<void> {
    await this.dataSource.transaction(async manager => {
      const acc = await manager.findOneOrFail(GeoAccountEntity, { where: { id: accountId } });
      const newIp = await manager.findOne(GeoProxyIpEntity, { where: { id: newIpId } });
      if (!newIp) throw new Error(`IP ${newIpId} not found`);
      if (newIp.bindAccountId && newIp.bindAccountId !== accountId) {
        throw new Error(`IP ${newIpId} 已绑定其他账号`);
      }
      if (acc.proxyId) {
        await manager.update(GeoProxyIpEntity, acc.proxyId, { bindAccountId: null, status: 'unbound' });
      }
      await manager.update(GeoProxyIpEntity, newIpId, { bindAccountId: accountId, status: 'active' });
      await manager.update(GeoAccountEntity, accountId, { proxyId: newIpId });

      const profile = await manager.findOne(GeoBrowserProfileEntity, { where: { id: acc.browserProfileId } });
      if (profile) {
        await this.profileService.attachProxy(profile.id, this.proxyService.toProxyInfo(newIp));
      }
    });
  }

  async deleteAccount(id: number): Promise<void> {
    await this.dataSource.transaction(async manager => {
      const acc = await manager.findOneOrFail(GeoAccountEntity, { where: { id } });
      if (acc.browserProfileId) {
        await this.profileService.deleteAt(acc.browserProfileId, manager);
      }
      if (acc.proxyId) {
        await manager.update(GeoProxyIpEntity, acc.proxyId, { bindAccountId: null, status: 'unbound' });
      }
      await manager.update(GeoAccountEntity, id, { status: 'deleted', proxyId: null, browserProfileId: null });
    });
  }
}
```

- [ ] **Step 4：跑测试看通过**

```bash
cd packages/backend && pnpm jest test/modules/geo/service_account.test.ts
```

- [ ] **Step 5：commit**

```bash
git add packages/backend/src/modules/geo/service/account.ts packages/backend/test/modules/geo/service_account.test.ts
git commit -m "feat(geo): GeoAccountService 编排（依赖 BrowserAutomationService）"
```

---

## Task 13：ProxyIp Controller

**Files:**
- Create: `packages/backend/src/modules/geo/controller/admin/proxy_ip.ts`

- [ ] **Step 1：实现**

```typescript
// packages/backend/src/modules/geo/controller/admin/proxy_ip.ts
import { Provide, Inject, Post, Body } from '@midwayjs/core';
import { CoolController, BaseController } from '@cool-midway/core';
import { GeoProxyIpEntity } from '../../entity/proxy_ip';
import { GeoProxyIpService } from '../../service/proxy_ip';

@Provide()
@CoolController({
  api: ['add', 'delete', 'update', 'info', 'list', 'page'],
  entity: GeoProxyIpEntity,
  service: GeoProxyIpService,
  pageQueryOp: {
    keyWordLikeFields: ['name', 'host', 'region'],
    fieldEq: ['provider', 'mode', 'status'],
    addOrderBy: { createTime: 'DESC' },
  },
})
export class AdminGeoProxyIpController extends BaseController {
  @Inject() proxyIpService: GeoProxyIpService;

  @Post('/healthCheck', { summary: '触发单条 IP 健康检查' })
  async healthCheck(@Body('id') id: number) {
    const ip = await this.proxyIpService.proxyIpEntity.findOneBy({ id });
    if (!ip) return this.fail('IP 不存在');
    const result = await this.proxyIpService.getProvider(ip.provider).healthCheck(this.proxyIpService.toProxyInfo(ip));
    await this.proxyIpService.proxyIpEntity.update(id, {
      latencyMs: result.latencyMs, lastCheckAt: new Date(),
      status: result.ok ? 'active' : 'error',
    });
    return this.ok(result);
  }

  @Post('/healthCheckAll', { summary: '批量健康检查' })
  async healthCheckAll() {
    await this.proxyIpService.healthCheckAll();
    return this.ok();
  }
}
```

- [ ] **Step 2：启动后端验证 CRUD 路由**

```bash
cd packages/backend && pnpm dev
curl -X POST http://localhost:8003/admin/geo/proxy_ip/page -H 'Content-Type: application/json' -d '{"page":1,"size":10}'
```
预期：200。

- [ ] **Step 3：commit**

```bash
git add packages/backend/src/modules/geo/controller/admin/proxy_ip.ts
git commit -m "feat(geo): IP 池 Controller"
```

---

## Task 14：BrowserProfile Controller

**Files:**
- Create: `packages/backend/src/modules/geo/controller/admin/browser_profile.ts`

- [ ] **Step 1：实现**

```typescript
// packages/backend/src/modules/geo/controller/admin/browser_profile.ts
import { Provide, Inject, Post, Body } from '@midwayjs/core';
import { CoolController, BaseController } from '@cool-midway/core';
import { GeoBrowserProfileEntity } from '../../entity/browser_profile';
import { GeoBrowserProfileService } from '../../service/browser_profile';

@Provide()
@CoolController({
  api: ['add', 'delete', 'update', 'info', 'list', 'page'],
  entity: GeoBrowserProfileEntity,
  service: GeoBrowserProfileService,
  pageQueryOp: {
    keyWordLikeFields: ['name', 'sessionName'],
    fieldEq: ['provider', 'status'],
    addOrderBy: { createTime: 'DESC' },
  },
})
export class AdminGeoBrowserProfileController extends BaseController {
  @Inject() profileService: GeoBrowserProfileService;

  @Post('/open', { summary: '启动浏览器' })
  async open(@Body('id') id: number, @Body('url') url?: string) {
    await this.profileService.open(id, url);
    return this.ok();
  }

  @Post('/close', { summary: '关闭浏览器' })
  async close(@Body('id') id: number) {
    await this.profileService.close(id);
    return this.ok();
  }
}
```

- [ ] **Step 2：启动验证**

- [ ] **Step 3：commit**

```bash
git add packages/backend/src/modules/geo/controller/admin/browser_profile.ts
git commit -m "feat(geo): 指纹浏览器 Controller"
```

---

## Task 15：Account Controller

**Files:**
- Create: `packages/backend/src/modules/geo/controller/admin/account.ts`

- [ ] **Step 1：实现**

```typescript
// packages/backend/src/modules/geo/controller/admin/account.ts
import { Provide, Inject, Post, Body } from '@midwayjs/core';
import { CoolController, BaseController } from '@cool-midway/core';
import { GeoAccountEntity } from '../../entity/account';
import { GeoAccountService } from '../../service/account';

@Provide()
@CoolController({
  api: ['delete', 'update', 'info', 'list', 'page'],
  entity: GeoAccountEntity,
  service: GeoAccountService,
  pageQueryOp: {
    keyWordLikeFields: ['name', 'loginAccount'],
    fieldEq: ['platform', 'status', 'loginStatus'],
    addOrderBy: { createTime: 'DESC' },
  },
})
export class AdminGeoAccountController extends BaseController {
  @Inject() accountService: GeoAccountService;

  @Post('/add', { summary: '创建账号（同时分配 IP+Profile）' })
  async addAccount(@Body() dto: any) {
    return this.ok(await this.accountService.add(dto));
  }

  @Post('/launch', { summary: '启动浏览器登录' })
  async launch(@Body('id') id: number, @Body('url') url?: string) {
    return this.ok(await this.accountService.launch(id, url));
  }

  @Post('/captureCookies', { summary: '抓 cookie' })
  async captureCookies(@Body('id') id: number, @Body('domains') domains?: string[]) {
    return this.ok(await this.accountService.captureCookies(id, domains));
  }

  @Post('/rebindIp', { summary: '重新绑定 IP' })
  async rebindIp(@Body('id') id: number, @Body('newIpId') newIpId: number) {
    await this.accountService.rebindIp(id, newIpId);
    return this.ok();
  }

  @Post('/deleteAccount', { summary: '逻辑删除账号' })
  async deleteAccount(@Body('id') id: number) {
    await this.accountService.deleteAccount(id);
    return this.ok();
  }
}
```

- [ ] **Step 2：启动验证**

- [ ] **Step 3：commit**

```bash
git add packages/backend/src/modules/geo/controller/admin/account.ts
git commit -m "feat(geo): 账号 Controller"
```

---

## Task 16：注入 base_sys_menu 菜单

通过 MCP `mcp__mysql__execute` 直接 INSERT。

- [ ] **Step 1：连接数据库**（如未连接）

- [ ] **Step 2：插入 GEO 一级目录**

```sql
INSERT INTO base_sys_menu (parentId, name, icon, orderNum, type, isShow, createTime, updateTime)
VALUES (NULL, '🌍 GEO', 'icon-trend', 50, 0, 1, NOW(), NOW());
```
查 id：
```sql
SELECT id FROM base_sys_menu WHERE name = '🌍 GEO' ORDER BY id DESC LIMIT 1;
```
记为 `<GEO_ROOT_ID>`。

- [ ] **Step 3：3 个二级菜单**

```sql
INSERT INTO base_sys_menu (parentId, name, router, viewPath, orderNum, type, isShow, createTime, updateTime) VALUES
 (<GEO_ROOT_ID>, '账号矩阵', '/geo/accounts', 'modules/geo/views/accounts.vue', 1, 1, 1, NOW(), NOW()),
 (<GEO_ROOT_ID>, 'IP 池', '/geo/proxies', 'modules/geo/views/proxies.vue', 2, 1, 1, NOW(), NOW()),
 (<GEO_ROOT_ID>, '指纹浏览器', '/geo/browser-profiles', 'modules/geo/views/browser-profiles.vue', 3, 1, 1, NOW(), NOW());
```
记下 3 个 id 为 `<ACCOUNTS_ID>` `<PROXIES_ID>` `<PROFILES_ID>`。

- [ ] **Step 4：14 条按钮权限**

```sql
INSERT INTO base_sys_menu (parentId, type, perms, createTime, updateTime) VALUES
 (<ACCOUNTS_ID>, 2, 'geo:account:add', NOW(), NOW()),
 (<ACCOUNTS_ID>, 2, 'geo:account:update', NOW(), NOW()),
 (<ACCOUNTS_ID>, 2, 'geo:account:delete', NOW(), NOW()),
 (<ACCOUNTS_ID>, 2, 'geo:account:launch', NOW(), NOW()),
 (<ACCOUNTS_ID>, 2, 'geo:account:captureCookies', NOW(), NOW()),
 (<ACCOUNTS_ID>, 2, 'geo:account:rebindIp', NOW(), NOW()),
 (<PROXIES_ID>, 2, 'geo:proxy:add', NOW(), NOW()),
 (<PROXIES_ID>, 2, 'geo:proxy:update', NOW(), NOW()),
 (<PROXIES_ID>, 2, 'geo:proxy:delete', NOW(), NOW()),
 (<PROXIES_ID>, 2, 'geo:proxy:healthCheck', NOW(), NOW()),
 (<PROFILES_ID>, 2, 'geo:profile:add', NOW(), NOW()),
 (<PROFILES_ID>, 2, 'geo:profile:update', NOW(), NOW()),
 (<PROFILES_ID>, 2, 'geo:profile:delete', NOW(), NOW()),
 (<PROFILES_ID>, 2, 'geo:profile:open', NOW(), NOW());
```

- [ ] **Step 5：验证**

```sql
SELECT id, parentId, name, type, perms FROM base_sys_menu WHERE name LIKE '%GEO%' OR perms LIKE 'geo:%' ORDER BY id;
```
预期：1 + 3 + 14。

---

## Task 17：注册定时任务

通过 MCP `mcp__mysql__execute`。

- [ ] **Step 1：插入 cron 任务**

```sql
INSERT INTO task_info (name, type, cron, service, status, taskType, createTime, updateTime)
VALUES (
  'GEO IP 健康检查',
  0,
  '0 0 */6 * * *',
  'geoProxyIpService.healthCheckAll',
  1,
  'local',
  NOW(), NOW()
);
```

> 如 service 字段格式与 task_info 现有约定不符，参考：`SELECT name, service FROM task_info WHERE status = 1 LIMIT 5;` 调整。

- [ ] **Step 2：启动后端检查日志**

```bash
cd packages/backend && pnpm dev
```
预期：task 模块加载这条 cron。Ctrl+C 停止。

---

## Task 18：前端 config + dashboard

**Files:**
- Create: `packages/frontend/src/modules/geo/config.ts`
- Create: `packages/frontend/src/modules/geo/views/dashboard.vue`

- [ ] **Step 1：config.ts**

```typescript
import { ModuleConfig } from '/$/cool';

export default (): ModuleConfig => ({
  name: 'geo',
  label: 'GEO 生成式引擎优化',
  order: 60,
  views: [
    { path: '/geo/dashboard', meta: { label: 'GEO 总览' }, component: () => import('./views/dashboard.vue') },
    { path: '/geo/accounts', meta: { label: '账号矩阵' }, component: () => import('./views/accounts.vue') },
    { path: '/geo/proxies', meta: { label: 'IP 池' }, component: () => import('./views/proxies.vue') },
    { path: '/geo/browser-profiles', meta: { label: '指纹浏览器' }, component: () => import('./views/browser-profiles.vue') },
  ],
});
```

- [ ] **Step 2：dashboard.vue 占位**

```vue
<template>
  <div class="geo-dashboard">
    <el-card>
      <el-empty description="GEO 总览（S4 阶段补充：覆盖率/引用率/趋势）" />
    </el-card>
  </div>
</template>
<script lang="ts" setup></script>
<style lang="scss" scoped>.geo-dashboard { padding: 16px; }</style>
```

- [ ] **Step 3：commit**

```bash
git add packages/frontend/src/modules/geo/config.ts packages/frontend/src/modules/geo/views/dashboard.vue
git commit -m "feat(geo)[fe]: 前端模块 config + dashboard 占位"
```

---

## Task 19：前端 IP 池页面

**Files:**
- Create: `packages/frontend/src/modules/geo/views/proxies.vue`

- [ ] **Step 1：实现**（与原 plan 一致，无浏览器层耦合）

```vue
<template>
  <cl-crud ref="Crud">
    <cl-row><cl-refresh-btn /><cl-add-btn /><cl-multi-delete-btn /><cl-flex1 /><cl-search-key /></cl-row>
    <cl-row><cl-table v-bind="table" /></cl-row>
    <cl-row><cl-flex1 /><cl-pagination /></cl-row>
    <cl-upsert ref="Upsert" v-bind="upsert" />
  </cl-crud>
</template>
<script lang="ts" setup>
import { useCool, useCrud, useTable, useUpsert } from '/$/cool';
import { ElMessage } from 'element-plus';
const { service } = useCool();
const Upsert = useUpsert({
  items: [
    { prop: 'name', label: '名称', component: { name: 'el-input' }, rules: { required: true } },
    { prop: 'provider', label: 'Provider', component: { name: 'el-select', options: [{ label: 'local 本地', value: 'local' }, { label: 'tianqi 天启', value: 'tianqi' }] }, rules: { required: true } },
    { prop: 'mode', label: '模式', component: { name: 'el-select', options: [{ label: '本地', value: 'local' }, { label: '第三方', value: 'third_party' }] }, rules: { required: true } },
    { prop: 'host', label: '主机' },
    { prop: 'port', label: '端口', component: { name: 'el-input-number' } },
    { prop: 'protocol', label: '协议', component: { name: 'el-select', options: [{ label: 'http', value: 'http' }, { label: 'socks5', value: 'socks5' }] }, value: 'http' },
    { prop: 'region', label: '区域' },
    { prop: 'isp', label: 'ISP' },
  ],
});
const Crud = useCrud({ service: service.geo.proxy_ip }, (app) => app.refresh());
const Table = useTable({
  columns: [
    { type: 'selection' },
    { prop: 'id', label: 'ID', width: 80 },
    { prop: 'name', label: '名称' },
    { prop: 'provider', label: 'Provider', width: 100 },
    { prop: 'mode', label: '模式', width: 100 },
    { prop: 'host', label: '主机' },
    { prop: 'port', label: '端口', width: 80 },
    { prop: 'region', label: '区域', width: 100 },
    { prop: 'status', label: '状态', width: 100 },
    { prop: 'latencyMs', label: '延迟(ms)', width: 100 },
    { prop: 'lastCheckAt', label: '上次检查', width: 160 },
    { label: '操作', type: 'op', buttons: [
      { label: '健康检查', type: 'primary', onClick({ scope }) { healthCheck(scope.row.id); } },
      'edit', 'delete',
    ]},
  ],
});
async function healthCheck(id: number) {
  const r: any = await service.request({ url: '/admin/geo/proxy_ip/healthCheck', method: 'POST', data: { id } });
  ElMessage.success(`延迟 ${r.latencyMs}ms / ${r.ok ? 'OK' : 'FAIL'}`);
  (Crud.value as any).refresh();
}
</script>
```

- [ ] **Step 2：启动前端验证**

打开 http://localhost:9001/geo/proxies。

- [ ] **Step 3：commit**

```bash
git add packages/frontend/src/modules/geo/views/proxies.vue
git commit -m "feat(geo)[fe]: IP 池管理页"
```

---

## Task 20：前端指纹浏览器页面

**Files:**
- Create: `packages/frontend/src/modules/geo/views/browser-profiles.vue`

- [ ] **Step 1：实现**

```vue
<template>
  <cl-crud ref="Crud">
    <cl-row><cl-refresh-btn /><cl-add-btn /><cl-multi-delete-btn /><cl-flex1 /><cl-search-key /></cl-row>
    <cl-row><cl-table v-bind="table" /></cl-row>
    <cl-row><cl-flex1 /><cl-pagination /></cl-row>
    <cl-upsert ref="Upsert" v-bind="upsert" />
  </cl-crud>
</template>
<script lang="ts" setup>
import { useCool, useCrud, useTable, useUpsert } from '/$/cool';
import { ElMessage, ElMessageBox } from 'element-plus';
const { service } = useCool();
const Upsert = useUpsert({
  items: [
    { prop: 'name', label: '名称', component: { name: 'el-input' }, rules: { required: true } },
    { prop: 'provider', label: 'Provider', component: { name: 'el-select', options: [
      { label: 'Plain Chromium（默认）', value: 'plain_chromium' },
      { label: 'BitBrowser (占位)', value: 'bitbrowser' },
      { label: 'ant-browser (占位)', value: 'ant_browser' },
      { label: 'AdsPower (占位)', value: 'adspower' },
    ] }, value: 'plain_chromium', rules: { required: true } },
    { prop: 'sessionName', label: 'Session Name', component: { name: 'el-input' }, rules: { required: true } },
    { prop: 'userAgent', label: 'User Agent' },
    { prop: 'osPlatform', label: 'OS', component: { name: 'el-select', options: [{ label: 'windows', value: 'windows' }, { label: 'mac', value: 'mac' }, { label: 'linux', value: 'linux' }] }, value: 'windows' },
    { prop: 'timezone', label: '时区', value: 'Asia/Shanghai' },
    { prop: 'language', label: '语言', value: 'zh-CN' },
    { prop: 'screenW', label: '屏宽', component: { name: 'el-input-number' }, value: 1920 },
    { prop: 'screenH', label: '屏高', component: { name: 'el-input-number' }, value: 1080 },
  ],
});
const Crud = useCrud({ service: service.geo.browser_profile }, (app) => app.refresh());
const Table = useTable({
  columns: [
    { type: 'selection' },
    { prop: 'id', label: 'ID', width: 80 },
    { prop: 'name', label: '名称' },
    { prop: 'provider', label: 'Provider', width: 130 },
    { prop: 'sessionName', label: 'Session' },
    { prop: 'osPlatform', label: 'OS', width: 80 },
    { prop: 'status', label: '状态', width: 100 },
    { prop: 'lastOpenAt', label: '上次打开', width: 160 },
    { label: '操作', type: 'op', buttons: [
      { label: '打开', type: 'primary', onClick({ scope }) { openProfile(scope.row.id); } },
      { label: '关闭', onClick({ scope }) { closeProfile(scope.row.id); } },
      'edit', 'delete',
    ]},
  ],
});
async function openProfile(id: number) {
  try {
    await service.request({ url: '/admin/geo/browser_profile/open', method: 'POST', data: { id } });
    ElMessage.success('已启动 Chromium 窗口');
    (Crud.value as any).refresh();
  } catch (e: any) {
    if (String(e.message || '').includes('BrowserProviderUnavailable')) {
      ElMessageBox.alert('playwright-cli 未安装或不可用，请先安装：npm i -g @playwright/cli@latest', '提示');
    } else {
      ElMessage.error(e.message);
    }
  }
}
async function closeProfile(id: number) {
  await service.request({ url: '/admin/geo/browser_profile/close', method: 'POST', data: { id } });
  ElMessage.success('已关闭');
  (Crud.value as any).refresh();
}
</script>
```

- [ ] **Step 2：启动前端验证**

- [ ] **Step 3：commit**

```bash
git add packages/frontend/src/modules/geo/views/browser-profiles.vue
git commit -m "feat(geo)[fe]: 指纹浏览器管理页"
```

---

## Task 21：前端账号矩阵页面

**Files:**
- Create: `packages/frontend/src/modules/geo/views/accounts.vue`

- [ ] **Step 1：实现**

```vue
<template>
  <cl-crud ref="Crud">
    <cl-row>
      <cl-refresh-btn />
      <el-button type="primary" @click="openAdd">新增账号</el-button>
      <cl-flex1 />
      <cl-search-key />
    </cl-row>
    <cl-row><cl-table v-bind="table" /></cl-row>
    <cl-row><cl-flex1 /><cl-pagination /></cl-row>

    <el-dialog v-model="addDlg" title="新增账号（自动分配 IP + 浏览器 Profile）" width="640">
      <el-form :model="form" label-width="120px">
        <el-form-item label="账号名称"><el-input v-model="form.name" /></el-form-item>
        <el-form-item label="平台">
          <el-select v-model="form.platform">
            <el-option label="小红书" value="xiaohongshu" />
            <el-option label="抖音" value="douyin" />
            <el-option label="微博" value="weibo" />
            <el-option label="知乎" value="zhihu" />
            <el-option label="微信" value="wechat" />
          </el-select>
        </el-form-item>
        <el-form-item label="登录账号"><el-input v-model="form.loginAccount" placeholder="手机号或账号" /></el-form-item>
        <el-form-item label="IP 模式">
          <el-radio-group v-model="form.ipMode">
            <el-radio value="local">本地 IP</el-radio>
            <el-radio value="third_party">第三方（天启）</el-radio>
          </el-radio-group>
        </el-form-item>
        <el-form-item label="区域" v-if="form.ipMode === 'third_party'"><el-input v-model="form.region" /></el-form-item>
        <el-form-item label="浏览器 Provider">
          <el-select v-model="form.browserProvider">
            <el-option label="Plain Chromium（推荐）" value="plain_chromium" />
            <el-option label="BitBrowser (占位)" value="bitbrowser" />
            <el-option label="ant-browser (占位)" value="ant_browser" />
          </el-select>
        </el-form-item>
      </el-form>
      <template #footer>
        <el-button @click="addDlg = false">取消</el-button>
        <el-button type="primary" :loading="adding" @click="submitAdd">创建</el-button>
      </template>
    </el-dialog>
  </cl-crud>
</template>

<script lang="ts" setup>
import { ref, reactive } from 'vue';
import { useCool, useCrud, useTable } from '/$/cool';
import { ElMessage, ElMessageBox } from 'element-plus';
const { service } = useCool();
const Crud = useCrud({ service: service.geo.account }, (app) => app.refresh());
const Table = useTable({
  columns: [
    { prop: 'id', label: 'ID', width: 80 },
    { prop: 'name', label: '名称' },
    { prop: 'platform', label: '平台', width: 110 },
    { prop: 'loginAccount', label: '登录账号' },
    { prop: 'loginStatus', label: '登录状态', width: 110, dict: [
      { label: '未登录', value: 'never', color: 'info' },
      { label: '已登录', value: 'logged_in', color: 'success' },
      { label: '已过期', value: 'expired', color: 'warning' },
    ]},
    { prop: 'status', label: '状态', width: 100 },
    { prop: 'proxyId', label: 'IP', width: 80 },
    { prop: 'browserProfileId', label: 'Profile', width: 80 },
    { prop: 'cookieCapturedAt', label: '抓 Cookie 时间', width: 160 },
    { label: '操作', type: 'op', width: 320, buttons: [
      { label: '启动登录', type: 'primary', onClick({ scope }) { launch(scope.row.id, scope.row.platform); } },
      { label: '抓 Cookie', onClick({ scope }) { captureCookies(scope.row.id, scope.row.platform); } },
      { label: '删除', type: 'danger', onClick({ scope }) { remove(scope.row.id); } },
    ]},
  ],
});

const PLATFORM_URLS: Record<string, string> = {
  xiaohongshu: 'https://www.xiaohongshu.com',
  douyin: 'https://www.douyin.com',
  weibo: 'https://weibo.com',
  zhihu: 'https://www.zhihu.com',
  wechat: 'https://mp.weixin.qq.com',
};
const PLATFORM_DOMAINS: Record<string, string[]> = {
  xiaohongshu: ['xiaohongshu.com'],
  douyin: ['douyin.com'],
  weibo: ['weibo.com'],
  zhihu: ['zhihu.com'],
  wechat: ['weixin.qq.com'],
};

const addDlg = ref(false);
const adding = ref(false);
const form = reactive({
  name: '', platform: 'xiaohongshu', loginAccount: '',
  ipMode: 'local' as 'local' | 'third_party',
  region: '', browserProvider: 'plain_chromium',
});
function openAdd() {
  Object.assign(form, { name: '', platform: 'xiaohongshu', loginAccount: '', ipMode: 'local', region: '', browserProvider: 'plain_chromium' });
  addDlg.value = true;
}
async function submitAdd() {
  if (!form.name || !form.loginAccount) {
    ElMessage.warning('账号名称、登录账号必填');
    return;
  }
  adding.value = true;
  try {
    await service.request({ url: '/admin/geo/account/add', method: 'POST', data: form });
    addDlg.value = false;
    ElMessage.success('已创建');
    (Crud.value as any).refresh();
  } catch (e: any) {
    if (String(e.message || '').includes('BrowserProviderUnavailable')) {
      ElMessageBox.alert('playwright-cli 未安装。请先安装：npm i -g @playwright/cli@latest', '提示');
    } else {
      ElMessage.error(e.message);
    }
  } finally {
    adding.value = false;
  }
}
async function launch(id: number, platform: string) {
  try {
    const url = PLATFORM_URLS[platform];
    const r: any = await service.request({ url: '/admin/geo/account/launch', method: 'POST', data: { id, url } });
    ElMessageBox.alert(`Chromium 已启动并打开 ${platform} 主页。请在窗口里登录，然后回来点"抓 Cookie"。\n\nSession: ${r.sessionName}`, '提示');
  } catch (e: any) {
    ElMessage.error(e.message);
  }
}
async function captureCookies(id: number, platform: string) {
  const domains = PLATFORM_DOMAINS[platform];
  const r: any = await service.request({ url: '/admin/geo/account/captureCookies', method: 'POST', data: { id, domains } });
  if (r.captured === 0) {
    ElMessageBox.alert('未抓到目标域 cookie，请确认已在浏览器里完成登录。', '提示');
  } else {
    ElMessage.success(`已抓到 ${r.captured} 条 cookie`);
    (Crud.value as any).refresh();
  }
}
async function remove(id: number) {
  await ElMessageBox.confirm('确认删除该账号？将释放 IP 并删除浏览器 Profile。', '提示', { type: 'warning' });
  await service.request({ url: '/admin/geo/account/deleteAccount', method: 'POST', data: { id } });
  ElMessage.success('已删除');
  (Crud.value as any).refresh();
}
</script>
```

- [ ] **Step 2：启动前端验证**

- [ ] **Step 3：commit**

```bash
git add packages/frontend/src/modules/geo/views/accounts.vue
git commit -m "feat(geo)[fe]: 账号矩阵管理页"
```

---

## Task 22：联调与冒烟（手工验证）

- [ ] **Step 1：playwright-cli 自检**

```bash
playwright-cli --version
```
失败 → `npm i -g @playwright/cli@latest`

- [ ] **Step 2：双端启动**

```bash
cd packages/backend && pnpm dev   # 终端 1
cd packages/frontend && pnpm dev  # 终端 2
```

- [ ] **Step 3：MCP mysql 验证三张表**

```
mcp__mysql__list_tables → 应包含 geo_account / geo_proxy_ip / geo_browser_profile
```

- [ ] **Step 4：MCP mysql 验证菜单**

```sql
SELECT id, parentId, name, type, perms FROM base_sys_menu WHERE name LIKE '%GEO%' OR perms LIKE 'geo:%';
```
预期：1 + 3 + 14。

- [ ] **Step 5：浏览器登录 admin 验证菜单**

打开 http://localhost:9001，admin 登录。左侧应出现 `🌍 GEO`。

- [ ] **Step 6：本地 IP 流程**

进入 IP 池 → 新增 → name=test-local / provider=local / mode=local → 创建 → 健康检查 → 应返回延迟。

- [ ] **Step 7：账号完整闭环（关键）**

进入 账号矩阵 → 新增账号 → name=xhs-test / 平台=xiaohongshu / loginAccount=13800001234 / IP 模式=local / 浏览器 Provider=plain_chromium → 创建。

预期：
- 列表新行 proxyId / browserProfileId 都有值
- 数据库 geo_proxy_ip 对应记录 bindAccountId 写了
- geo_browser_profile 对应记录 accountId 写了，sessionName=`geo-{id}`

点击「启动登录」→ Chromium 弹真实窗口（已打开小红书首页）→ 在窗口里扫码登录。

回控制台点击「抓 Cookie」→ 提示"已抓到 N 条 cookie" → 列表刷新，loginStatus 变 logged_in。

数据库验证：
```sql
SELECT id, login_status, LENGTH(cookies) AS cookie_len, cookie_captured_at
FROM geo_account WHERE platform='xiaohongshu' ORDER BY id DESC LIMIT 1;
```
预期：cookie_len > 100，login_status='logged_in'。

- [ ] **Step 8：删除清理**

点击「删除」→ 确认。
```sql
SELECT id, status FROM geo_account WHERE id = <ID>;
SELECT id, status FROM geo_proxy_ip WHERE id = <PROXY_ID>;
SELECT id, status FROM geo_browser_profile WHERE id = <PROFILE_ID>;
```
预期：account=deleted、proxy=unbound、profile=deleted。

- [ ] **Step 9：强绑定约束**

```sql
UPDATE geo_proxy_ip SET bind_account_id = 9999 WHERE id = <已绑 IP id>;
```
预期：唯一索引报错。

- [ ] **Step 10：playwright-cli 不可用降级**

临时改环境变量 `PATH` 让 playwright-cli 失踪 → 前端再点「打开」profile。
预期：弹窗"playwright-cli 未安装"。

- [ ] **Step 11：所有 geo 测试**

```bash
cd packages/backend && pnpm jest test/modules/geo/
```
预期：全部 PASS。

- [ ] **Step 12：tsc 类型检查**

```bash
cd packages/backend && npx tsc --noEmit
cd packages/frontend && pnpm type-check
```

- [ ] **Step 13：更新路线图 + commit**

把 `docs/superpowers/specs/2026-05-03-geo-master-roadmap.md` §11 的 S1 状态改为 ✅ 已完成。

```bash
git add docs/superpowers/specs/2026-05-03-geo-master-roadmap.md
git commit -m "docs(geo): 更新路线图 S1 状态为已完成"
```

---

## 验收清单（与 spec §10 对齐）

- [ ] 后端启动表自动创建（Step 3）
- [ ] Cool Admin 自动 CRUD 全部可用（Task 13-15 各自验证）
- [ ] 自定义接口可用：launch / captureCookies / rebindIp / healthCheck / open / close（Step 7）
- [ ] base_sys_menu 已注入（Step 4）
- [ ] 前端菜单可见（Step 5）
- [ ] 完整闭环跑通（Step 6-7）
- [ ] 删除安全释放（Step 8）
- [ ] 强绑定约束生效（Step 9）
- [ ] playwright-cli 不可用友好降级（Step 10）

---

## 实施期间约束

- ❌ 不写 SQL 文件（用 MCP mysql 直接 INSERT）
- ❌ 不手动改 `entities.ts`（dev 模式通配符扫描，prod build 由 `cool entity` 生成）
- ❌ 不引入 gateway/skill/runtime（S3 之后再考虑）
- ❌ 不实现平台特定登录流程（QR/账密/短信全部 S3）
- ❌ 不在 controller 写业务逻辑
- ❌ 不绕过 Cool Admin 自动 CRUD 写手工 axios
- ❌ 不在 BrowserProvider 里做 cookie/state 操作（那是 BrowserAutomationService 的职责）

---

## 实施完成后

- 调用 `superpowers:verification-before-completion` 逐条核对验收清单
- 调用 `superpowers:requesting-code-review` 触发代码审查
- 调用 `superpowers:finishing-a-development-branch` 决策合并方式
- 更新 [`../specs/2026-05-03-geo-master-roadmap.md`](../specs/2026-05-03-geo-master-roadmap.md) §11
- 进入 S2（关键词与知识图谱）的 brainstorming 流程