GPU_GUARD_MONOREPO/docs/superpowers/specs/2026-05-03-geo-s1-infrastructure-design.md

# S1 基础设施层 设计文档

> Geo 模块第一个子项目：账号矩阵 / IP 池 / 指纹浏览器 / 菜单。
> 上位文档：[`2026-05-03-geo-master-roadmap.md`](./2026-05-03-geo-master-roadmap.md)

| 元数据 | 值 |
|---|---|
| 子项目 | S1 基础设施层 |
| 创建日期 | 2026-05-03 |
| 估期 | ~9 天 |
| 状态 | 设计完成，待 user 复核 → writing-plans |

---

## 1. 目标

为 Geo 模块后续所有子项目（S2/S3/S4）提供**账号—IP—指纹浏览器**三位一体的基础设施。S1 完成后，用户能在 Neta 控制台：

1. 在 GEO 一级菜单下看到三个子页面
2. 创建一个 IP（本地或第三方）
3. 创建一个指纹浏览器 profile
4. 创建一个社媒账号，自动绑定 IP + Profile（强 1:1:1）
5. 点击「启动登录」打开真实浏览器，扫码/输账密/输短信完成登录
6. Cookie 自动抱回并加密存储
7. 删除账号时安全释放 IP 和 Profile

S1 **不涉及**任何平台特定行为（发布、评论、监测）。

---

## 2. 关键决策（brainstorming 阶段已确认）

| 决策点 | 决策 |
|---|---|
| 子项目拆分 | 4 个子项目（S1/S2/S3/S4），先做 S1 |
| IP 池 | 抽象 `IProxyProvider` + 内置 `LocalProvider` + 占位 `TianqiProvider` |
| 浏览器（两层正交） | ① 浏览器进程层 `IBrowserProvider`：S1 主实现 `PlainChromiumProvider`（playwright-cli 直接启 Chromium）+ 占位 `BitBrowser` `AntBrowser` `AdsPower`。② 自动化层 `BrowserAutomationService`：统一用 `playwright-cli -s={session}` 做 cookie/state/click/type，不关心底层是哪种浏览器 |
| 绑定关系 | account ↔ proxy_ip ↔ browser_profile **严格 1:1:1**，IP/Profile 上 `bindAccountId` 唯一索引 |
| 登录方式 | `playwright-cli -s={session} open {url} --persistent --headed` 启动有头浏览器 + 用户自己登录 + `BrowserAutomationService.getCookies()` 自动抱回 |
| 实现风格 | 分层 Provider 抽象 + account service 单点编排（与 NetaClaw `llm_providers/` 对齐） |
| 数据库 | 不写 SQL 文件；Entity + TypeORM `synchronize` 自动建表；菜单 seed 用 `mcp__mysql__execute` |
| 加密 | geo 模块自建 `GeoEncryptService`（复用同一 AES-256-GCM 算法和 `SKILL_SECRET_KEY`/`APP_SECRET` 密钥派生逻辑，但接口签名为 `encrypt(plain: string): string` / `decrypt(cipher: string): string`，适配 cookie/密码等字符串场景。不直接调用 `SkillSecretService`——后者签名为 `encrypt(obj: Record<string,string>)` 且语义是 skill scoped secrets） |

---

## 3. 与 Neta 现有架构契合度审计

| Neta 约定 | S1 实施 |
|---|---|
| 模块根目录 `src/modules/{name}/` | ✅ `src/modules/geo/` |
| `entity/` 文件下划线 + BaseEntity + 字段驼峰 | ✅ |
| `controller/admin/` + `@CoolController` 自动 CRUD | ✅ |
| `service/` 业务编排 | ✅ |
| `entities.ts` 注册 | ✅ 自动生成（`cool entity` 命令扫描 `modules/*/entity` 通配符，无需手动修改） |
| 前端模块 `config.ts` 导出 ModuleConfig | ✅ |
| 加密复用 AES-256-GCM 算法和密钥派生 | ✅ 自建 `GeoEncryptService`（复用算法+密钥，接口适配字符串场景） |
| 菜单走 base_sys_menu | ✅ |
| TypeORM `synchronize: true` 自动建表 | ✅（dev 环境，prod 禁用） |
| 多租户 tenantId 自动注入 | ✅ |
| 不在 S1：gateway/skill/runtime（属过度设计） | ✅ |

---

## 4. 架构与目录

### 4.1 后端目录

```
packages/backend/src/
└── modules/geo/                             # entities.ts 由 `cool entity` 自动生成，无需手动修改
    ├── config.ts
    ├── entity/
    │   ├── account.ts                       # geo_account
    │   ├── proxy_ip.ts                      # geo_proxy_ip
    │   └── browser_profile.ts               # geo_browser_profile
    ├── controller/admin/
    │   ├── account.ts                       # @CoolController + 自定义 launch / captureCookies
    │   ├── proxy_ip.ts                      # @CoolController + 自定义 healthCheck / batchImport
    │   └── browser_profile.ts               # @CoolController + 自定义 open / close
    ├── service/
    │   ├── account.ts                       # ★ 单点编排：bindResources / launch / captureCookies / rebindIp
    │   ├── proxy_ip.ts                      # CRUD 包装 + provider 调度
    │   ├── browser_profile.ts               # CRUD 包装 + provider 调度
    │   ├── browser_automation.ts            # ★ 统一自动化层：playwright-cli 包装（cookie/state/click/type）
    │   └── encrypt.ts                       # GeoEncryptService
    └── provider/                       # geo 模块内部约定（非 NetaClaw plugins/）
                                         # 原因：geo provider 不需要动态加载，且 plugins/ 在 Neta 语义里
                                         # 特指 LLM 适配层（netaclaw/plugins/llm_providers/）
        ├── proxy/
        │   ├── interface.ts                 # IProxyProvider
        │   ├── local.ts                     # LocalProxyProvider
        │   └── tianqi.ts                    # 占位 TianqiProxyProvider（等文档）
        └── browser/
            ├── interface.ts                 # IBrowserProvider（仅进程生命周期）
            ├── plain_chromium.ts            # ★ S1 主实现：playwright-cli + Chromium
            ├── bitbrowser.stub.ts           # 占位（启动 BitBrowser，playwright-cli attach）
            ├── ant_browser.stub.ts          # 占位（等用户提供源码）
            └── adspower.stub.ts             # 占位
```

### 4.2 前端目录

```
packages/frontend/src/modules/geo/
├── config.ts                                # ★ 必须 export ModuleConfig
└── views/                                   # service 代理由 Cool Admin 根据后端 controller 文件名自动生成
                                             # 如 service.geo.account.page() / service.geo.proxy_ip.healthCheck()
                                             # 无需手动创建 service/ 目录
    ├── dashboard.vue                        # 占位（S4 才正式做内容）
    ├── accounts.vue                         # 账号矩阵主页
    ├── proxies.vue                          # IP 池
    └── browser-profiles.vue                 # 指纹浏览器
```

### 4.3 菜单 seed（运行时通过 MCP mysql 执行 INSERT）

```
🌍 GEO（一级目录，icon=icon-trend，order=50）
├── 账号矩阵     viewPath=modules/geo/views/accounts.vue          perms=geo:account:list
├── IP 池        viewPath=modules/geo/views/proxies.vue           perms=geo:proxy:list
└── 指纹浏览器   viewPath=modules/geo/views/browser-profiles.vue  perms=geo:profile:list
```

按钮权限：`geo:account:add` / `update` / `delete` / `launch` / `captureCookies` / `rebindIp`；`geo:proxy:add` / `update` / `delete` / `healthCheck` / `batchImport`；`geo:profile:add` / `update` / `delete` / `open` / `close`。

---

## 5. 数据模型

### 5.1 geo_account

| 字段 | 类型 | 说明 |
|---|---|---|
| `id` | bigint PK | BaseEntity |
| `tenantId` | bigint Index | BaseEntity 自动注入 |
| `name` | varchar(64) | 备注名/昵称 |
| `platform` | varchar(32) Index | xiaohongshu / douyin / weibo / zhihu / wechat |
| `loginAccount` | varchar(128) | 登录手机号/账号 |
| `cookies` | text | **加密** JSON |
| `cookieCapturedAt` | datetime NULL | |
| `loginStatus` | varchar(16) | never / logged_in / expired |
| `status` | varchar(16) | draft / active / risky / banned / deleted |
| `proxyId` | bigint UQ Index | → geo_proxy_ip.id |
| `browserProfileId` | bigint UQ Index | → geo_browser_profile.id |
| `personaId` | bigint NULL | S2 用，S1 占位 |
| `agentConfigId` | bigint NULL | S3 用 |
| `lastActiveAt` | datetime NULL | |
| `extra` | json | 平台特定字段 |
| `createTime` `updateTime` | datetime | BaseEntity |

**约束**：(`platform`, `loginAccount`) 联合唯一；`proxyId` 唯一；`browserProfileId` 唯一。

### 5.2 geo_proxy_ip

| 字段 | 类型 | 说明 |
|---|---|---|
| `id` | bigint PK | |
| `tenantId` | bigint Index | |
| `name` | varchar(64) | |
| `provider` | varchar(32) | local / tianqi |
| `mode` | varchar(16) | local / third_party |
| `host` | varchar(128) NULL | 第三方才有 |
| `port` | int NULL | |
| `protocol` | varchar(8) | http / socks5 |
| `username` | varchar(128) NULL | **加密** |
| `password` | varchar(255) NULL | **加密** |
| `region` | varchar(64) | 城市/省份 |
| `isp` | varchar(32) | 联通/电信/移动 |
| `externalId` | varchar(128) NULL | provider 侧 ID |
| `bindAccountId` | bigint UQ NULL Index | 反向唯一 |
| `status` | varchar(16) | active / expired / error / unbound |
| `latencyMs` | int NULL | |
| `lastCheckAt` | datetime NULL | |
| `expiresAt` | datetime NULL | |
| `extra` | json | |

### 5.3 geo_browser_profile

| 字段 | 类型 | 说明 |
|---|---|---|
| `id` | bigint PK | |
| `tenantId` | bigint Index | |
| `name` | varchar(64) | |
| `provider` | varchar(32) | plain_chromium / bitbrowser / ant_browser / adspower |
| `sessionName` | varchar(128) Index | playwright-cli 的 `-s=xxx` 命名 session（唯一标识） |
| `accountId` | bigint UQ NULL Index | 反向唯一 |
| `profileDir` | varchar(512) NULL | `--profile=/path` 持久化目录 |
| `configPath` | varchar(512) NULL | `--config=xxx.json` 代理配置文件路径 |
| `userAgent` | varchar(512) | |
| `osPlatform` | varchar(32) | windows / mac / linux |
| `timezone` | varchar(32) | |
| `language` | varchar(16) | |
| `screenW` | int | |
| `screenH` | int | |
| `fingerprint` | json | 深度指纹配置（S1 不填，等 ant-browser） |
| `lastOpenAt` | datetime NULL | |
| `status` | varchar(16) | created / running / closed / error / deleted |
| `extra` | json | |

---

## 6. Provider 接口契约

### 6.1 IProxyProvider

```ts
// 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';
  host?: string;
  port?: number;
  protocol: 'http' | 'socks5';
  username?: string;
  password?: string;
  region?: string;
  isp?: string;
  expiresAt?: Date;
}

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

### 6.2 IBrowserProvider（仅浏览器进程生命周期，不含自动化）

```ts
// 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 与 open 解耦） */
  attachProxy(profile: ProfileInfo, proxy: ProxyInfo): Promise<void>;
  /** 启动浏览器进程并打开 URL（最终 BrowserAutomationService 通过 sessionName 操作） */
  open(profile: ProfileInfo, url?: string): Promise<void>;
  /** 关闭浏览器进程 */
  close(profile: ProfileInfo): Promise<void>;
}
```

### 6.3 Provider 实现职责

| 实现 | 关键行为 |
|---|---|
| `LocalProxyProvider` | acquire 直接返回 `mode='local'` 标记的 ProxyInfo（不连出站代理）；healthCheck 走宿主机 https://www.baidu.com |
| `TianqiProxyProvider`（占位） | acquire/release 抛 `NotImplemented` 但不阻塞模块加载；healthCheck 同上；文件头部注释列出对接 TODO |
| **`PlainChromiumProvider`**（★ S1 主实现） | create → 在 `dataDir/geo/profiles/` 下生成 `geo-{accountId}` profile 目录 + 写一个 `geo-proxy-{accountId}.json` 代理配置；attachProxy → 重写代理 JSON；open → exec `playwright-cli -s={session} open {url} --persistent --profile={profileDir} --headed --config={configPath}`；close → exec `playwright-cli -s={session} close`；delete → `playwright-cli -s={session} delete-data` + 删除配置文件 |
| `BitBrowserStub` | 占位。未来实现：调 BitBrowser Local API 启动 profile 拿到 CDP endpoint，playwright-cli 通过 attach 模式连进去做自动化 |
| `AntBrowserStub` | 占位。等用户提供源码后实现 |
| `AdsPowerStub` | 占位。仅声明 name + 抛 NotImplemented |

### 6.4 BrowserAutomationService（统一自动化层，所有 Provider 共用）

```ts
// service/browser_automation.ts
@Provide()
export class BrowserAutomationService {
  /** 列出指定域名的 cookie。底层 exec：playwright-cli -s={session} cookie-list --domain={domain} --raw */
  async getCookies(sessionName: string, domain?: string): Promise<Cookie[]>;

  /** 保存完整登录态到文件。底层 exec：playwright-cli -s={session} state-save {path} */
  async saveState(sessionName: string, filePath: string): Promise<void>;

  /** 恢复登录态。底层 exec：playwright-cli -s={session} state-load {path} */
  async loadState(sessionName: string, filePath: string): Promise<void>;

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

**关键设计**：`BrowserAutomationService` 与 `IBrowserProvider` 完全解耦。无论 provider 启动的是普通 Chromium 还是 BitBrowser/ant-browser，只要进程存在且 `playwright-cli -s={session}` 能命中（或 attach 进去），自动化层无差别工作。

---

## 7. 核心数据流

### 7.1 创建账号（同时分配 IP + Profile）

```
前端 accounts.vue → POST /admin/geo/account/add
   ↓
service/account.ts.add(dto):
  await dataSource.transaction(async manager => {
    // 1. 申请 IP
    const proxyDto = dto.ipMode === 'local'
      ? { provider: 'local', mode: 'local' }
      : { provider: 'tianqi', mode: 'third_party', region: dto.region };
    const ipInfo = await proxyService.acquire(proxyDto);
    const ipEntity = await proxyService.persist(manager, ipInfo);

    // 2. 申请 Profile
    const profileInfo = await browserService.create({
      provider: dto.browserProvider ?? 'bitbrowser',
      ...dto.fingerprint
    });
    const profileEntity = await browserService.persist(manager, profileInfo);

    // 3. Provider 侧挂代理
    await browserService.attachProxy(profileEntity, ipEntity);

    // 4. 创建 account
    const account = manager.create(GeoAccount, {
      ...dto, proxyId: ipEntity.id, browserProfileId: profileEntity.id
    });
    return manager.save(account);
  });

  // 失败补偿：transaction 回滚 + Provider 端
  catch (e) {
    if (ipExternal) await proxyProvider.release(ipExternal);
    if (profileExternal) await browserProvider.delete(profileExternal);
    throw e;
  }
```

### 7.2 启动浏览器环境

```
前端 [启动登录] → POST /admin/geo/account/launch { id, url? }
   ↓
service/account.ts.launch(id, url?):
  const account = repo.findOneOrFail(id);
  const profile = profileRepo.findOneOrFail(account.browserProfileId);
  const targetUrl = url || PLATFORM_URLS[account.platform]; // 如 https://www.xiaohongshu.com
  await browserProvider.open(profile.sessionName, targetUrl);
  // playwright-cli 会弹出有头浏览器窗口，用户在里面登录
  await profileRepo.update(profile.id, { status: 'running', lastOpenAt: new Date() });
  return { sessionName: profile.sessionName };
```

### 7.3 抓 Cookie

```
前端轮询/手动触发 → POST /admin/geo/account/captureCookies { id, domains? }
   ↓
service/account.ts.captureCookies(id, domains?):
  const account = ...findOneOrFail(id);
  const profile = ...findOneOrFail(account.browserProfileId);
  if (profile.status !== 'running') throw new Error('Browser not running, call launch first');

  // 自动化层走 BrowserAutomationService（与底层是哪种浏览器无关）
  const domain = domains?.[0];
  const cookies = await browserAutomationService.getCookies(profile.sessionName, domain);
  if (cookies.length === 0) {
    return { captured: 0 };
  }
  const encrypted = geoEncryptService.encrypt(JSON.stringify(cookies));
  await accountRepo.update(id, {
    cookies: encrypted,
    cookieCapturedAt: new Date(),
    loginStatus: 'logged_in',
  });

  // 同时保存完整登录态（cookie + localStorage）到文件，方便后续 loadState 复活会话
  const statePath = `${dataDir}/geo/states/geo-state-${id}.json`;
  await browserAutomationService.saveState(profile.sessionName, statePath);

  return { captured: cookies.length };
```

### 7.4 IP 健康检查（Neta task 模块 cron）

Neta 的 task 模块通过 `task_info` 表 + `TaskLocalService`（基于 `cron` npm 包）调度。注册方式：在 `task_info` 表中 INSERT 一条记录，`service` 字段指向要调用的 service 方法路径。

```
注册（通过 mcp__mysql__execute INSERT 到 task_info 表）：
  name: 'GEO IP 健康检查'
  service: 'geo.proxy_ip.healthCheckAll'
  type: 0                    # 0=cron 表达式
  cron: '0 0 */6 * * *'     # 每 6 小时
  status: 1                  # 启用

service/proxy_ip.ts:
  async healthCheckAll() {
    const ips = await this.proxyIpEntity.find({ where: { status: 'active' } });
    for (const ip of ips) {
      const provider = this.getProvider(ip.provider);
      const result = await 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} (${ip.host}) health check failed`);
      }
    }
    // S1 仅 logger.warn，不入告警表（S4 才有 geo_alert）
  }
```

### 7.5 解绑/换 IP

```
service/account.ts.rebindIp(accountId, newIpId):
  await dataSource.transaction(async manager => {
    const account = await manager.findOneOrFail(GeoAccount, accountId);
    const oldIp = await manager.findOne(GeoProxyIp, account.proxyId);
    const newIp = await manager.findOneOrFail(GeoProxyIp, newIpId);
    if (newIp.bindAccountId) throw new Error('IP 已被其他账号绑定');

    if (oldIp) {
      await manager.update(GeoProxyIp, oldIp.id, { bindAccountId: null, status: 'unbound' });
    }
    await manager.update(GeoProxyIp, newIp.id, { bindAccountId: accountId, status: 'active' });
    await manager.update(GeoAccount, accountId, { proxyId: newIp.id });

    const profile = await manager.findOneOrFail(GeoBrowserProfile, account.browserProfileId);
    await browserProvider.attachProxy(profile.externalProfileId, toProxyInfo(newIp));
  });
```

### 7.6 删除账号

Neta 现有模块不使用 TypeORM `softRemove`（BaseEntity 没有 `@DeleteDateColumn`）。geo 模块采用**逻辑删除**：account 和 profile 设 `status='deleted'`，与 Neta 其他模块风格一致。

```
service/account.ts.deleteAccount(id):
  await dataSource.transaction(async manager => {
    const account = await manager.findOneOrFail(GeoAccount, { where: { id } });
    const ip = account.proxyId
      ? await manager.findOne(GeoProxyIp, { where: { id: account.proxyId } })
      : null;
    const profile = account.browserProfileId
      ? await manager.findOne(GeoBrowserProfile, { where: { id: account.browserProfileId } })
      : null;

    if (profile) {
      await browserProvider.delete(profile.externalProfileId).catch(() => {/* 容忍外部失败 */});
      await manager.update(GeoBrowserProfile, profile.id, { status: 'deleted', accountId: null });
    }
    if (ip) {
      await manager.update(GeoProxyIp, ip.id, { bindAccountId: null, status: 'unbound' });
    }
    await manager.update(GeoAccount, id, { status: 'deleted', proxyId: null, browserProfileId: null });
  });
```

---

## 8. 错误处理

| 故障 | 处理 |
|---|---|
| playwright-cli 未安装 | `PlaywrightCliProvider` 启动时检测 `playwright-cli --version`，失败抛 `BrowserProviderUnavailable`，前端弹窗提示安装 |
| 天启 API 超时 | 重试 3 次（指数退避），仍失败 → `ProxyAcquireFailed`，前端提示切 local 或重试 |
| Cookie 抓取空 | 不写库，返回 `captured: 0`，前端提示用户先在打开的浏览器里完成登录 |
| 事务中途失败 | DB 自动回滚 + Provider 端补偿 release/delete |
| 并发竞争 IP | UQ 索引兜底；service 层先 `lockMode: 'pessimistic_write'` 锁住 IP |
| 浏览器进程残留 | `close` 失败时 logger.error 但不阻塞业务，运维侧定期清理 |
| 加密密钥丢失 | `GeoEncryptService` 复用 `SKILL_SECRET_KEY`/`APP_SECRET` 环境变量派生密钥，丢失时抛 `EncryptionKeyMissing` |

---

## 9. 测试策略

| 层 | 方法 |
|---|---|
| **Provider 单元** | LocalProxyProvider / BitBrowserProvider 走 mock fetch；TianqiProvider 验证抛 NotImplemented |
| **Service 单元** | jest + sqlite，验证编排逻辑、事务回滚、补偿动作触发 |
| **Controller 集成** | jest + supertest，跑 add → launch → captureCookies 一遍 |
| **手工冒烟** | 真机 BitBrowser + 真小红书账号：创建 → 启动 → 登录 → 抓 cookie → loginStatus 验证 |

测试不在 S1 范围放真账号 token，所有真实凭据只在手工冒烟阶段使用。

---

## 10. 验收标准

1. ✅ 后端 `pnpm dev` 启动，TypeORM 自动建好 `geo_account` `geo_proxy_ip` `geo_browser_profile` 三张表（可用 `mcp__mysql__list_tables` 验证）
2. ✅ Cool Admin 自动 CRUD 接口可用：`/admin/geo/{account,proxy_ip,browser_profile}/{add,delete,update,info,list,page}` 全部返回 200
3. ✅ 自定义接口可用：`/admin/geo/account/launch` `/captureCookies` `/rebindIp`、`/admin/geo/proxy_ip/healthCheck` `/batchImport`、`/admin/geo/browser_profile/open` `/close`
4. ✅ `mcp__mysql__query` 能查到 `base_sys_menu` 中 `🌍 GEO` 顶级菜单 + 3 个子菜单 + 全部按钮权限
5. ✅ 前端登录后菜单出现 `🌍 GEO` + 3 个子项；点击进入对应页面
6. ✅ 在前端能完整跑通：
   - 创建一个 Local IP，能跑 healthCheck 看到延迟数字
   - 创建一个 playwright-cli profile，能 open 弹出有头浏览器窗口
   - 创建一个账号（platform=xiaohongshu），自动绑定 IP+Profile
   - 点击「启动登录」弹出有头浏览器，登录小红书后点「抓取 Cookie」，loginStatus 变 logged_in，cookies 字段非空且加密
7. ✅ 删除账号：DB 中 IP 置 unbound 但记录保留；Profile 状态置 deleted；account 状态置 deleted（逻辑删除，非 softRemove）
8. ✅ 强绑定约束：尝试给已绑账号的 IP 重新绑给别人，DB 报唯一约束错（前端友好提示）
9. ✅ playwright-cli 未安装时，前端 open 操作返回 `BrowserProviderUnavailable` 错误并弹窗

---

## 11. 交付物清单

| 类别 | 文件 |
|---|---|
| **后端 entity** | `entity/account.ts` `entity/proxy_ip.ts` `entity/browser_profile.ts` |
| **后端 controller** | `controller/admin/account.ts` `proxy_ip.ts` `browser_profile.ts` |
| **后端 service** | `service/account.ts` `service/proxy_ip.ts` `service/browser_profile.ts` `service/browser_automation.ts`（统一自动化层） `service/encrypt.ts`（GeoEncryptService） |
| **Provider** | `provider/proxy/{interface,local,tianqi}.ts` `provider/browser/{interface,plain_chromium,bitbrowser.stub,ant_browser.stub,adspower.stub}.ts` |
| **配置** | `modules/geo/config.ts`（`entities.ts` 由 `cool entity` 自动生成，无需手动改） |
| **菜单** | `mcp__mysql__execute` 注入 `base_sys_menu`（4 条 menu + 12+ 条 perms） |
| **前端** | `modules/geo/{config.ts, views/{accounts,proxies,browser-profiles,dashboard}.vue, components/}` |
| **测试** | `test/modules/geo/**` 单元+集成 |
| **文档** | 本 spec + 后续 plan |

---

## 12. 风险与依赖

| 风险/依赖 | 缓解 |
|---|---|
| playwright-cli 未安装 | Provider 启动时检测 + 前端友好提示 + 文档说明安装步骤（`npm i -g @playwright/cli@latest`） |
| 天启 HTTP 文档迟到 | TianqiProvider 占位实现可走通整体流程，文档到位后只改一文件 |
| `synchronize: true` 在 prod 危险 | Neta 现有约定 prod 禁用，S1 不改前提 |
| Cookie 抓取目标域不全 | captureCookies 接受 `domains?: string[]` 参数 |
| Playwright 与代理兼容性 | playwright-cli `--config` 支持 proxy 配置；S1 验证 local + http proxy 两种场景 |
| 测试环境没有 playwright-cli | Provider 抽象允许 mock child_process.exec；CI 用 mock |
| 深度指纹伪装 | S1 不做（playwright-cli 不支持 canvas/webgl 伪装）；等 ant-browser 源码到位后新增 AntBrowserProvider |

---

## 13. 范围红线（不在 S1）

- ❌ 平台特定登录流程（QR 轮询/账密表单/短信） → S3
- ❌ 浏览/发布/评论/指标采集 → S3
- ❌ 关键词、内容、Schema → S2
- ❌ AI 引用监测 → S4
- ❌ 多模态/数字人/爆款拆解 → S5（暂不规划）
- ❌ Skill 包对外暴露给 NetaClaw Agent → S3 起做
- ❌ WebSocket 实时启动日志 → S3 评估是否需要

---

## 14. 工作流

完成本 spec 后：

1. user 复核本文档
2. 调用 `superpowers:writing-plans` 生成 `docs/superpowers/plans/2026-05-03-geo-s1-infrastructure-plan.md`
3. user 复核 plan
4. `superpowers:executing-plans` + TDD 实施
5. `superpowers:verification-before-completion` 逐条核对验收标准
6. `superpowers:requesting-code-review`
7. 更新主路线图：S1 状态 → 已完成；启动 S2 brainstorming

---

## 15. 变更日志

| 日期 | 变更 |
|---|---|
| 2026-05-03 | 初稿 |
| 2026-05-03 | 架构审查修复 8 项：①entities.ts 自动生成不手动改 ②自建 GeoEncryptService 替代直接调用 SkillSecretService ③定时任务改用 task_info 表注册 ④provider/ 目录加说明 ⑤删除前端 service/ 目录 ⑥逻辑删除替代 softRemove ⑦BitBrowser 端口从 config/env 读取 ⑧account/profile status 枚举加 deleted |
| 2026-05-03 | 浏览器层重构：主实现从 BitBrowserProvider 改为 PlaywrightCliProvider（复用 Neta 已有 playwright-cli skill）；BitBrowser 降为 stub；Entity 字段调整（externalProfileId→sessionName，cdpEndpoint→profileDir/configPath）；接口增加 getCookies/saveState/loadState；不再依赖 playwright Node.js 库 |
| 2026-05-03 | 浏览器层二次重构：澄清"自动化工具"与"浏览器进程"是两个正交层。新增 `BrowserAutomationService`（统一 playwright-cli 包装层）。`IBrowserProvider` 缩减为只管浏览器进程生命周期（去掉 getCookies/saveState/loadState）。S1 主实现重命名为 `PlainChromiumProvider`（playwright-cli + Chromium），BitBrowser/AntBrowser/AdsPower 全部 stub，等具体浏览器需求到位时只增加 provider 不改自动化层 |