# frp-ctrl 产品详解设计文档

这组文档用于把当前总方案拆成可执行的分段设计，便于后续按模块实现代码。

## ⚠ 设计文档维度口径（必读）

项目里"阶段"一词历史上被四套体系共用，导致歧义。开始阅读前请先理解四个维度：

| 维度 | 命名前缀 | 含义 | 权威文档 |
|------|---------|------|---------|
| **维度 A · 商业路线图** | `Biz-1 ~ Biz-4` | 做给谁、什么商业模式、先攻哪类客户 | `playbook-index.html` 系列 |
| **维度 B · 产品实现** | `Impl-1 ~ Impl-5` | 这周开发什么、下周开发什么（功能交付顺序） | 本目录的 `05-implementation-phases.md` |
| **维度 C · 技术架构** | `arch-1 ~ arch-4` | 单体还是微服务、哪些先拆（架构演进） | `index.html` / `design-stage-1.html` |
| **维度 D · 工程就绪度** | `snapshot` | 现在能做什么（事实进度，不是计划） | `stage-1-readiness.md` |

**核心原则**：
- 维度 A 和维度 B 是正交的：一个商业阶段（Biz-N）可以跨多个实现阶段（Impl-N）。
- 维度 D 是事实，其他是计划。冲突时以维度 D 为准。
- 看到任何文档说"阶段N"，先确认它属于哪个维度。
- 完整对照表和全部文档索引见 `design-master-index.html`（项目根目录）。

## 文档结构

- `01-entry-auth.md`
  - 官网、登录、注册、邀请制、租户开通、角色分流
- `02-admin-portal.md`
  - 正式后台 `/admin` 与客户管理端 `/portal` 的功能边界、页面结构、实现顺序
- `03-ai-i18n.md`
  - AI 能力分层、Vercel AI SDK、LangChain、LangGraph、多语言支持
- `04-data-api.md`
  - 同库方案、表命名建议、认证域、内容域、AI 域、接口组织方式
- `05-implementation-phases.md`
  - 分阶段落地策略、第一阶段代码目标、第二阶段商用化收口目标
- `06-egress-deployment.md`
  - 出口节点（Egress）一键部署设计：厂商无关、一行命令安装、端口最小化、WebSSH、安全组引导、映射级可选令牌受控访问
- `07-p2p-agent-connectivity.md`
  - P2P 节点互联 PRD 与技术实施清单：Agent 间直连、租户自有公网节点中转、日志与 AI 分析路线
- `08-rbac-access-design.md`
  - 角色枚举、入口边界、路由权限、菜单权限、后端鉴权与权限码设计
- `09-site-gateway.md`
  - 站点网关 PRD 与技术实施清单：单网关接入整个局域网、站点/网关/目标设备模型、盒子化交付路线
- `10-disable-semantics-matrix.md`
  - 租户 / 平台 / 站点停用语义矩阵：管理面只读、运行面收敛、恢复口径
- `11-tenant-disable-write-guard-coverage.md`
  - 租户停用硬拦截覆盖矩阵：哪些已做后端硬拦截、哪些保留只读观察、哪些故意不拦截

配套关系图与数据库草案：

- `docs/tenant-platform-site-relationship.md`
  - 租户 / 平台 / 站点 关系图（Markdown 版）
- `tenant-platform-site-relationship.html`
  - 租户 / 平台 / 站点 关系图（HTML 可视化版）
- `docs/site-gateway-db-relations.md`
  - 站点网关数据库关系草案（按租户主归属口径）

## 关联的 HTML 总设计文件

以下 HTML 文件位于项目根目录，承载可视化的整体设计和专项设计，和本组 Markdown 文档配合使用：

### 总设计

- `index.html`
  - 控制平面蓝图总纲：系统总拓扑、平台出口矩阵、发布链路、对象建模、冲突控制、容器化部署、SaaS 化结论、AI 能力定位
- `playbook-index.html`
  - 发展阶段纲领目录：从阶段 1 自用验证到阶段 4 SaaS 标准化与海外扩张的完整路线图

### 阶段纲领

- `playbook-stage-1.html` — 自用验证（最小闭环）
- `playbook-stage-2a-industrial.html` — 工业控制优先
- `playbook-stage-2b-oem.html` — 嵌入式硬件商优先
- `playbook-stage-2c-scale.html` — 复制到其它服务商
- `playbook-stage-3-solutionization.html` — 行业方案化与白标/OEM
- `playbook-stage-4-saas-global.html` — 标准化 SaaS 与海外扩张

### 专项设计

- `egress-deployment-design.html`
  - 出口节点一键部署设计：数据流架构、端口规划、安装脚本 8 步流程、WebSSH 网页终端、现有代码基础与待修复项、与整体方案的关系
- `cloud-provisioning-design.html`
  - 云资源引导推荐设计：三层路径（推荐链接 / SSH 自动部署 / OAuth 远期）、厂商能力对比、免费机横向对比、管理端引导面板设计、厂商安全组差异表、变现漏斗、合规红线

### 入口页面原型

- `site-home.html` / `site-about.html` / `site-contact.html` — 官网
- `site-pricing.html` — 套餐与试商用
- `site-solutions.html` / `site-solution-enterprise.html` / `site-solution-industrial.html` / `site-solution-oem.html` — 解决方案
- `site-login.html` / `site-register.html` — 登录注册
- `site-docs.html` / `site-downloads.html` — 文档与下载
- `admin-home.html` — 管理后台首页
- `portal-home.html` — 客户控制台首页
- `release-ops-console.html` — 发布运维控制台

## 当前总原则

- 产品分成两条并行业务线：
- 产品分成三条并行业务线：
  - `公网发布`
    - 现有 `映射 / 出口 / 发布任务` 体系
    - 解决内网服务对公网发布
  - `P2P 节点互联`
    - 新增 `节点 / 隧道 / 中转 / 会话日志` 体系
    - 解决 Agent 与 Agent 间私网互联
  - `站点网关`
    - 新增 `站点 / 网关 / 目标设备 / 站点发布` 体系
    - 解决一个现场只装一个 Agent 的批量接入
- `P2P 节点互联` 不与现有公网发布冲突，不复用 `映射 / 出口 / 发布任务` 的核心业务语义。
- `站点网关` 与 `公网发布` 可协同，但业务对象应该独立建模，不建议直接复用 `P2P` 域模型。
- 官网、登录、注册、后台、客户端是统一产品入口体系，不是互相独立的零散页面。
- 第一阶段接口组织方式已定：先上方案 A，前端直连 `NestJS + Directus`。
- 第二阶段进入正式商用化后，再逐步收成方案 B，由 `NestJS` 统一聚合认证、运营、AI 和内容出口。
- `Directus` 可以与核心业务共用同一个 `frpctrl` 数据库，但不能接管核心控制表写入。
- `Vercel AI SDK` 负责 AI 体验层，`LangChain` 负责 AI 编排层，工具调用权限必须收在服务端。
- 官网和客户端优先国际化，后台先预留 i18n 结构，`/ops` 固定中文。

## 出口节点与云资源策略

这是商用化落地的关键模块，核心原则：

- **厂商无关**：不依赖任何云厂商的 OAuth / RAM / IAM，任意 Linux 服务器都能部署出口节点。
- **一行命令**：用户只需 SSH 粘贴执行 `curl | bash`，30 秒内节点上线。
- **Linkio 只卖软件**：不碰服务器资源转售，规避 IDC 牌照红线；用户自付费给云厂商，Linkio 收软件服务费。
- **控制平面不中转业务流量**：数据走 `用户 → Egress(frps) → Agent(frpc) → 内网服务`，Server 只做编排。

## P2P 节点互联原则

- `P2P 节点互联` 的目标是让 Agent 与 Agent 之间形成可审计、可授权、可回退的私网互联能力。
- 连接策略采用：
  - 优先直连
  - 直连失败后仅允许回落到 `租户自有公网节点`
- 平台不提供共享中转，不承载租户 P2P 数据面流量。
- 具备公网能力的租户自有节点，可以显式启用为 `P2P 中转节点`。
- P2P 的日志、审计和 AI 分析单独建模，不混入现有公网发布日志域。

## 站点网关原则

- `站点网关` 的目标是一个局域网只部署一个 `Gateway Agent`，由它统一代理后面的多台目标设备。
- `站点网关` 第一阶段只支持 `TCP / UDP` 静态目标转发。
- 平台只允许访问已登记目标，不默认做全网扫描与自动发现。
- `站点网关` 最适合延伸成“预装 Agent 的边缘盒子”交付形态。
- `站点网关` 的站点、网关、目标设备、站点发布与健康日志应单独建模，不混入 `p2p_*` 日志域。

详细设计见 `06-egress-deployment.md` 和根目录的 `egress-deployment-design.html` / `cloud-provisioning-design.html`。

## 当前实现目标

这一轮先完成两件事：

1. 把文档拆成可执行的分段设计。
2. 基于现有仓库先实现最小可访问入口骨架：
   - `/`
   - `/login`
   - `/register`
   - `/admin`
   - `/portal`

后续再在这些入口上继续接真实接口和业务模块。