# 04. 数据与接口设计

## 1. 数据库策略

当前确定采用：

- 同一个 MySQL 实例
- 同一个数据库：`frpctrl`

不做物理拆库，但必须做逻辑分区：

- 核心域
- 认证域
- 运营内容域
- AI 域
- Directus 系统域

## 2. 命名建议

核心业务：

- `tenant_*`
- `platform_*`
- `edge_*`
- `mapping_*`
- `release_*`
- `agent_*`
- `p2p_*`
- `site_*`
- `audit_*`

认证域：

- `auth_users`
- `auth_identities`
- `auth_tenant_members`
- `auth_role_bindings`
- `auth_registration_requests`

运营与内容域：

- `customer_*`
- `package_*`
- `invite_*`
- `help_*`
- `policy_*`
- `i18n_*`

AI 域：

- `ai_sessions`
- `ai_messages`
- `ai_tool_calls`
- `ai_audit_logs`
- `ai_knowledge_indexes`

P2P 节点互联域：

- `p2p_nodes`
- `p2p_tunnels`
- `p2p_relay_nodes`
- `p2p_connection_logs`
- `p2p_analysis_tasks`

站点网关域：

- `site_sites`
- `site_gateways`
- `site_targets`
- `site_target_mappings`
- `site_gateway_health_logs`

## 3. Directus 规则

Directus 可以接入同一个 `frpctrl` 库，但只主控：

- 客户资料
- 套餐
- 公告
- 帮助中心
- FAQ
- 条款模板
- 多语言内容

Directus 不直接主控：

- `mapping_*`
- `release_*`
- `agent_*`
- `auth_*`

也就是说，同库没问题，但核心写入路径不能乱。

## 4. 接口组织方式

已定策略：

- 第一阶段：方案 A
  - 前端直连 `NestJS` 核心接口
  - 前端直连 `Directus` 运营接口
- 第二阶段：方案 B
  - 前端只调 `NestJS`
  - `NestJS` 聚合 `Directus`、AI、认证、内容能力

## 5. 为什么这么定

第一阶段先追求：

- 跑得快
- 入口完整
- 页面可见
- 模块能开工

第二阶段再追求：

- 权限统一
- 审计统一
- AI 收口
- 内容与认证统一出口

## 6. 第一阶段接口重点

优先需要的接口组：

- 认证接口
- 租户与账号接口
- 官网试用申请接口
- 后台基础概览接口
- 客户门户概览接口
- AI 入口接口

当前还没有这些完整模块，所以第一轮代码先搭页面和路由骨架，再逐步补接口。

## 7. 新增业务线：P2P 节点互联

### 7.1 业务边界

- `公网发布`
  - 现有 `mapping_* / edge_* / release_*`
  - 目标是对公网提供访问
- `P2P 节点互联`
  - 新增 `p2p_*`
  - 目标是 Agent 与 Agent 间建立私网互联

两条业务线并行，不互相替代。

### 7.2 P2P 数据规则

- P2P 中转节点只允许来源于 `租户自有公网节点`。
- 平台不提供共享中转节点，不承载租户 P2P 数据面流量。
- P2P 连接优先直连，失败后仅允许回落到当前租户自己的公网节点。

### 7.3 建议表模型

- `p2p_nodes`
  - Agent 在 P2P 业务线中的节点身份、地域、标签、网络能力
- `p2p_tunnels`
  - 两个节点间的授权连接、目标网段/端口、连接策略
- `p2p_relay_nodes`
  - 租户自有公网节点的中转角色配置、容量、状态、优先级
- `p2p_connection_logs`
  - 每次会话的连接路径、耗时、错误码、回退信息
- `p2p_analysis_tasks`
  - AI 日志分析任务、输入范围、摘要、风险等级、建议动作

### 7.4 关键字段建议

- `p2p_nodes`
  - `tenant_id`
  - `agent_id`
  - `node_name`
  - `is_public_reachable`
  - `public_endpoint`
  - `nat_type`
  - `status`
- `p2p_relay_nodes`
  - `tenant_id`
  - `agent_id`
  - `public_endpoint`
  - `relay_enabled`
  - `relay_status`
  - `relay_priority`
  - `max_sessions`
  - `bandwidth_limit_mbps`
- `p2p_tunnels`
  - `tenant_id`
  - `source_node_id`
  - `target_node_id`
  - `transport_policy`
  - `fallback_policy`
  - `target_service`
  - `status`
- `p2p_connection_logs`
  - `tenant_id`
  - `tunnel_id`
  - `session_id`
  - `connect_path`
  - `relay_node_id`
  - `connect_result`
  - `error_code`
  - `error_stage`
  - `handshake_latency_ms`
  - `duration_ms`
  - `bytes_in`
  - `bytes_out`

### 7.5 接口建议

- `GET /api/admin/p2p/nodes`
- `POST /api/admin/p2p/nodes/:id/relay-enable`
- `POST /api/admin/p2p/nodes/:id/relay-disable`
- `GET /api/admin/p2p/tunnels`
- `POST /api/admin/p2p/tunnels`
- `PATCH /api/admin/p2p/tunnels/:id`
- `GET /api/admin/p2p/connection-logs`
- `GET /api/admin/p2p/connection-logs/:id`
- `POST /api/admin/p2p/connection-logs/analyze`

### 7.6 审计与 AI

- 审计域新增：
  - 启用/停用中转节点
  - 修改 P2P 隧道策略
  - 查看/导出连接日志
  - 发起 AI 分析
- AI 域新增：
  - 先做规则型连接日志分析
  - 后续再接入真实模型做摘要、趋势和根因分析

## 8. 新增业务线：站点网关

### 8.1 业务边界

- `公网发布`
  - 解决内网服务如何对公网发布
- `P2P 节点互联`
  - 解决 Agent 与 Agent 间私网互联
- `站点网关`
  - 解决一个局域网只部署一个 Agent，由它代理后面的多台设备

三条业务线并行，不互相替代。

### 8.2 站点网关数据规则

- 一个 `site` 代表一个客户现场 / 局域网站点
- 一个 `site` 的主归属是 `tenant`
- `site` 是租户功能与租户资产，不是平台级公共资源
- 一个 `site` 通常绑定一个 `gateway`
- 一个 `gateway` 下可以维护多个 `target`
- 平台只允许访问已登记 `target`，不默认做自动发现
- 第一阶段只支持 `TCP / UDP` 静态目标转发

### 8.3 建议表模型

- `site_sites`
  - 站点基本信息、归属租户、负责人、状态
- `site_gateways`
  - 站点网关与 Agent 的绑定关系、配置版本、在线状态
- `site_targets`
  - 网关后面的目标设备清单、协议、地址、端口、标签
- `site_target_mappings`
  - 目标设备和站点发布的映射关系、发布状态、当前版本，可选关联 `platform_id`
- `site_gateway_health_logs`
  - 网关心跳、目标可达性摘要、离线影响范围

### 8.4 接口建议

- `GET /api/admin/sites`
- `POST /api/admin/sites`
- `PATCH /api/admin/sites/:siteId`
- `GET /api/admin/sites/:siteId`
- `GET /api/admin/sites/:siteId/gateway`
- `GET /api/admin/sites/:siteId/targets`
- `POST /api/admin/sites/:siteId/targets`
- `PATCH /api/admin/sites/:siteId/targets/:targetId`
- `GET /api/admin/sites/:siteId/releases`
- `POST /api/admin/sites/:siteId/releases/publish`
- `GET /api/admin/sites/:siteId/health`

接口口径建议：

- `/sites` 默认按当前租户做资源隔离
- 创建站点时不要求先绑定 `platform`
- `platformId` 只在站点发布或目标映射时作为可选参数出现

### 8.5 审计与 AI

- 审计域新增：
  - 新建/修改站点
  - 新建/修改目标设备
  - 站点发布与回滚
  - 查看/导出站点日志
- AI 域新增：
  - 先做站点健康摘要和离线影响解释
  - 后续再扩展到目标可达性分析和批量异常归因