tcjlj/OpenFlare
1
0
Fork 0
mirror of https://github.com/Rain-kl/OpenFlare.git synced 2026-10-01 06:36:38 +08:00
Code Issues Packages Projects Releases Wiki Activity

migrate frontend

Browse Source
This commit is contained in:
ryan
2026-06-18 17:43:11 +08:00
parent a9fd0bd128
commit 31b114b0cc
104 changed files with 16735 additions and 874 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/changelog/index.md
+3
View File
@@ -38,6 +38,9 @@ sidebar: false
- 实装数据库可观测性手动/自动清理、WAF IP 组订阅/自动同步与测试接口、UptimeKuma 监控同步、TLS ACME 申请/续期（lego DNS-01）。
- 修复 Wavelet Agent WebSocket 未处理 `status` 消息导致 WS 模式下 `last_seen_at` 停止更新、节点超时显示离线的问题；列表「最近心跳」恢复显示「WS 已连接」。
- 修复节点「强制同步」仍为 stub 导致始终返回「节点不在线或通过 WebSocket 发送同步指令失败」的问题。
- 将 OpenFlare 管理控制台从 `openflare-server/web` 迁移至 `Wavelet/frontend/app/(main)/openflare/`，复用 Wavelet shadcn 组件与 Session 鉴权；新增 `LegacyOpenFlareBaseService` 对接 `/api/*` 业务 API。
- 实装节点、代理规则（6 Section）、配置发布、WAF、网站/证书/DNS、Pages、源站、访问/应用日志、仪表盘、性能调优等业务页面；Admin 设置新增 OpenFlare 运维扩展 Tab。
- 修复静态导出构建中 `useSearchParams` 未包裹 Suspense 的问题；`pnpm build:embed` 全量 46 页通过。
## [v2.3.4] - 2026-06-17
docs/plan/20260618-openflare-wavelet-frontend-migration.md
+1 -1
View File
@@ -2,7 +2,7 @@
> **文档类型**：实现计划（Implementation Plan）
> **创建日期**：2026-06-18
> **状态**：实施中（阶段 0 基建 + 阶段 2 核心链路并行）
> **状态**：基本完成（FC-1~19 已实装；验证见 `docs/plan/verify-frontend-*.md`）
> **前置阅读**：[`Wavelet/AGENTS.md`](../../Wavelet/AGENTS.md)、[`docs/plan/20260618-openflare-wavelet-backend-migration.md`](./20260618-openflare-wavelet-backend-migration.md)
> **依赖**：后端阶段一（旧路径 `/api/*` 兼容）完成后启动；阶段二可与后端阶段五并行
docs/plan/handover-openflare-frontend-migration.md
+33 -93
View File
@@ -1,110 +1,50 @@
# OpenFlare 前端迁移 — 任务拆分与 AI 委派
> **状态**：进行中（阶段 0 基建 + 阶段 2 核心链路并行）
> **状态**：基本完成（验证通过，少量 P1 打磨待办）
> **目标前端**：`Wavelet/frontend/`（Next.js 16 + shadcn/ui + Session 鉴权）
> **业务 API**：阶段一仍调用 `/api/*` legacy 兼容层（响应 `{success,message,data}`）
> **平台 API**：认证/用户/Admin 使用 `/api/v1/*`（响应 `{error_msg,data}`）
## 任务隔离规则
| 规则 | 说明 |
|---|---|
| 文件所有权 | 每个任务 **仅修改** 自己的 `app/(main)/openflare/<module>/`、`lib/services/openflare/<module>.service.ts` |
| 共享文件 | `F0` 独占：`lib/navigation/`、`lib/services/openflare/legacy-base.service.ts`、`lib/services/openflare/index.ts`（注册入口）、`components/layout/sidebar.tsx`（仅新增 OpenFlare 导航组）、`app/(main)/openflare/layout.tsx` |
| 禁止修改 | Wavelet 框架核心：`app/(auth)/*` 逻辑、`lib/services/core/*`、`components/ui/*` 源码 |
| UI 规范 | 标题 `h1 text-2xl font-semibold tracking-tight`；单文件 ≤600 行；参考 `/admin/demo`、`/admin/database` 拆分模式 |
| 组件 | 仅用 `@/components/ui/*`（shadcn），**禁止**复制旧 `openflare-server/web/components/ui` |
| 服务层 | 业务 API 继承 `LegacyOpenFlareBaseService`；平台 API 继续用 `BaseService` |
| 鉴权 | Session Cookie（`withCredentials`），**禁止** `OpenFlare-Token` localStorage |
| 质量门禁 | `cd Wavelet/frontend && pnpm typecheck && pnpm lint` |
> **验证报告**：[`verify-frontend-routes.md`](./verify-frontend-routes.md)、[`verify-frontend-services.md`](./verify-frontend-services.md)、[`verify-frontend-ui.md`](./verify-frontend-ui.md)、[`verify-frontend-build.md`](./verify-frontend-build.md)
## 任务队列
| ID | 板块 | 状态 | 负责目录/文件 |
|---|---|---|---|
| F0 | 基建：Legacy 服务基类 + 导航 + 侧栏 + 路由骨架 | ✅ 完成 | `legacy-base.service.ts`、`openflare-nav.ts`、`sidebar.tsx`、`/home` → `/openflare` |
| F-NODE | 节点列表 + Edge 详情 | ✅ 完成（Relay/Tunnel 详情待补） | `node.service.ts`、`openflare/nodes/` |
| F-PROXY | 代理规则列表 + 详情骨架 | ✅ 骨架完成（6 Tab 待实装） | `proxy-route.service.ts`、`openflare/proxy-routes/` |
| F-CFG | 配置发布 + 应用日志 | ✅ 完成 | `config-version.service.ts`、`apply-log.service.ts` |
| F-DASH | 总览仪表盘 | ⏳ | `dashboard.service.ts`、`openflare/page.tsx` |
| F-WAF | WAF 规则组 + IP 组 | ⏳ | `waf.service.ts`、`openflare/waf/` |
| F-WEB | 网站/证书/DNS | ⏳ | `website.service.ts`、`tls-certificate.service.ts`、`openflare/websites/` |
| F-PAGES | Pages 托管 | ⏳ | `pages.service.ts`、`openflare/pages/` |
| F-ORIGIN | 源站 | ⏳ | `origin.service.ts`、`openflare/origins/` |
| F-LOGS | 访问日志 | ⏳ | `access-log.service.ts`、`openflare/access-logs/` |
| F-ADMIN | 运维设置扩展 Admin | ⏳ | `option.service.ts`、`admin/settings` 扩展块 |
| F-AUTH | 认证复用验证（Wavelet 原生） | ⏳ | 仅导航/回调 URL，不改登录页 |
| ID | 板块 | 状态 |
|---|---|---|
| F0 | 基建 | ✅ |
| F-NODE | 节点（含 Relay/Tunnel 详情） | ✅ |
| F-PROXY | 代理规则（含 6 Section 实装） | ✅ |
| F-CFG | 配置发布 + 应用日志 | ✅ |
| F-DASH | 总览仪表盘 | ✅（缺世界地图） |
| F-WAF | WAF 规则组 + IP 组 | ✅ |
| F-WEB | 网站/证书/DNS | ✅ |
| F-PAGES | Pages 托管 | ✅ |
| F-ORIGIN | 源站 | ✅ |
| F-LOGS | 访问日志 | ✅ |
| F-PERF | 性能调优 | ✅ |
| F-ADMIN | Admin 运维设置扩展 | ✅ |
| F-AUTH | Wavelet 登录/用户复用 | ✅（原生，未改登录页） |
## Legacy API 适配要点
## 验证结果摘要
旧 OpenFlare 业务 API 响应：
```json
{ "success": true, "message": "", "data": { ... } }
```
Wavelet `BaseService` 期望 `{ "error_msg": "", "data": ... }`。业务服务必须使用 `LegacyOpenFlareBaseService`：
```typescript
// lib/services/openflare/legacy-base.service.ts
protected static async legacyGet<T>(path: string, params?: Record<string, unknown>): Promise<T>
protected static async legacyPost<T>(path: string, data?: unknown): Promise<T>
// 解析 success/message/data；success=false 时 throw ApiErrorBase(message)
```
阶段一 `basePath` 示例：`/api/nodes`、`/api/proxy-routes`（无 `/v1` 前缀）。
## 页面规范速查
```tsx
// 标准页面外壳（参考 admin/demo）
<div className="py-6 px-1 space-y-6">
<div className="flex items-center gap-2">
<Icon className="size-5 text-primary" />
<h1 className="text-2xl font-semibold tracking-tight">页面标题</h1>
</div>
{/* 内容 */}
</div>
```
| 旧组件 | Wavelet 替代 |
| 门禁 | 结果 |
|---|---|
| `app-modal` | `Dialog` / `Sheet` |
| `app-table` | `Table` + `@tanstack/react-table` 或简易 Table |
| `status-badge` | `Badge` variant |
| `primary-button` | `Button` |
| ECharts 趋势图 | Recharts（世界地图可暂保留 ECharts） |
| `tsc --noEmit` | ✅ |
| `pnpm lint` | ✅ |
| `pnpm build:embed` | ✅（46 静态页；已修 Suspense） |
| 路由覆盖 FC-1~19 | ✅ 18 完整 + 1 部分 |
| Service 覆盖 | ⚠️ `update` 升级流程待补 |
## 源代码参考
## 剩余 P1 待办
| 类型 | 路径 |
|---|---|
| 旧前端业务 | `openflare-server/web/features/<module>/` |
| 新前端标杆 | `Wavelet/frontend/app/(main)/admin/database/`、`admin/demo/` |
| 服务层范例 | `Wavelet/frontend/lib/services/admin/user.service.ts` |
| 迁移计划 | `docs/plan/20260618-openflare-wavelet-frontend-migration.md` |
| 后端 API | `docs/plan/20260618-openflare-wavelet-backend-migration.md` §12 |
1. **FC-20** About 页或链到 `/docs`
2. **UpdateService** 补全 upgrade/manual-upload/WS 日志
3. **UI 打磨**：部分 Dialog 补 Zod；access-logs/proxy-detail error 态
4. **FC-1** 世界地图（可选，当前用 geo 列表）
## 验收命令
```bash
cd Wavelet/frontend
pnpm typecheck
pnpm exec tsc --noEmit
pnpm lint
pnpm dev # 联调 wavelet api :3000
```
## 阶段验收标准
| 阶段 | 验收 |
|---|---|
| F0 完成 | 登录后侧栏可见 OpenFlare 导航；`/home` → `/openflare`；各路由有占位或骨架页 |
| F-NODE + F-PROXY + F-CFG | 节点 CRUD、规则 CRUD、配置发布/激活、应用日志列表可联调 |
| 全量 | 旧前端 18 个控制台路由功能对等；E2E 核心路径通过 |
## 下一步（F0 完成后）
1. 启动 **F-DASH**（仪表盘，依赖 dashboard API）
2. 启动 **F-WAF** + **F-WEB**（阶段 3 并行）
3. **F-ADMIN** 合并运维设置到 `admin/settings`
4. 更新 `docs/changelog/index.md`（代码变更时）
pnpm build:embed
pnpm dev
```
docs/plan/index.md
+2 -1
View File
@@ -16,7 +16,8 @@
| [OpenFlare → Wavelet 后端迁移计划](./20260618-openflare-wavelet-backend-migration.md) | 将 `openflare-server` 后端迁移至 Wavelet 框架，保留 `/api/*` 路径，复用用户/认证等平台能力 |
| [OpenFlare 后端迁移 — AI 接手](./handover-openflare-backend-migration.md) | 后端迁移当前进度、任务队列、定时任务、goose 版本与下一步行动（阶段 5 收尾） |
| [OpenFlare → Wavelet 前端迁移计划](./20260618-openflare-wavelet-frontend-migration.md) | 将 `openflare-server/web` 业务 UI 按 Wavelet 设计风格重写，复用框架组件与 Admin 基建 |
| [OpenFlare 前端迁移 — AI 委派](./handover-openflare-frontend-migration.md) | 前端迁移任务队列、Legacy API 适配规范、子智能体文件所有权与验收标准 |
| [OpenFlare 前端迁移 — AI 委派](./handover-openflare-frontend-migration.md) | 前端迁移任务队列与验收状态 |
| [前端路由验证](./verify-frontend-routes.md) · [Service 验证](./verify-frontend-services.md) · [UI 验证](./verify-frontend-ui.md) · [构建验证](./verify-frontend-build.md) | 多角度迁移验收报告 |
## 使用建议
docs/plan/verify-frontend-build.md
+151
View File
@@ -0,0 +1,151 @@
# Wavelet Frontend Build Verification
**Date:** 2026-06-18
**Directory:** `/Users/ryan/DEV/Go/OpenFlare/Wavelet/frontend`
**Node/Next:** Next.js 16.2.7 (Turbopack)
## Summary
| Gate | Command | Exit Code | Result |
|------|---------|-----------|--------|
| TypeScript | `pnpm exec tsc --noEmit` | **0** | ✅ Pass |
| Lint | `pnpm lint` | **0** | ✅ Pass |
| Production build | `pnpm build:embed` | **1** | ❌ Fail |
| Standard build | `pnpm build` | **1** | ❌ Fail (same error) |
**Overall:** TypeScript and lint are clean. Both build targets fail during static page generation due to a missing React `Suspense` boundary around `useSearchParams()`.
---
## 1. TypeScript (`pnpm exec tsc --noEmit`)
- **Exit code:** `0`
- **Duration:** ~6.2s
- **Errors:** None
- **Warnings:** None
---
## 2. ESLint (`pnpm lint`)
- **Exit code:** `0`
- **Duration:** ~5.6s
- **Command:** `eslint` (no extra args)
- **Errors:** None
- **Warnings:** None
---
## 3. Production Build (`pnpm build:embed`)
**Production target:** `build:embed` — sets `NEXT_STANDALONE_EXPORT=true`, which enables `output: 'export'` in `next.config.ts` for static export embedded in the Go backend.
- **Exit code:** `1`
- **Duration:** ~57s (compile ~29.5s, TypeScript check ~23.9s)
### Build progress
- ✅ Compiled successfully
- ✅ TypeScript check passed during build
- ❌ Static page generation failed at **0/46** pages
### Error
```
⨯ useSearchParams() should be wrapped in a suspense boundary at page "/openflare/nodes".
Read more: https://nextjs.org/docs/messages/missing-suspense-with-csr-bailout
Error occurred prerendering page "/openflare/nodes".
Export encountered an error on /(main)/openflare/nodes/page: /openflare/nodes, exiting the build.
⨯ Next.js build worker exited with code: 1 and signal: null
```
### Affected files
| File | Issue |
|------|-------|
| `app/(main)/openflare/nodes/page.tsx` | `useSearchParams()` at line 36 (page default export) |
| `app/(main)/openflare/nodes/components/node-type-filter.tsx` | `useSearchParams()` at line 57 (rendered inside nodes page) |
### Build output size
Not available — build aborted before artifact generation completed.
---
## 4. Standard Build (`pnpm build`)
Ran for comparison (uses rewrites instead of static export).
- **Exit code:** `1`
- **Duration:** ~65s
- **Error:** Identical `useSearchParams()` / missing `Suspense` failure on `/openflare/nodes`
---
## Root Cause
Next.js 16 requires `useSearchParams()` to be used inside a `<Suspense>` boundary when pages are statically prerendered/exported. The nodes page is a client component that calls `useSearchParams()` directly in both the page and a child component (`NodeTypeFilter`).
Other pages in the codebase already follow the correct pattern:
- `app/(auth)/login/page.tsx` — wraps content in `<Suspense>`
- `app/(auth)/register/page.tsx` — wraps content in `<Suspense>`
- `app/(main)/admin/tasks/page.tsx` — wraps content in `<Suspense fallback={...}>`
- `app/(main)/openflare/proxy-routes/detail/page.tsx` — splits into `page.tsx` + `page-client.tsx` with `<Suspense>`
---
## Other `useSearchParams()` Usages (likely to fail after nodes fix)
These files also use `useSearchParams()` without a visible `Suspense` wrapper at the page level. They may fail once `/openflare/nodes` is fixed and generation continues:
| File |
|------|
| `app/(main)/openflare/nodes/detail/page.tsx` |
| `app/(main)/openflare/websites/detail/page.tsx` |
| `app/(main)/openflare/origins/detail/page.tsx` |
| `app/(main)/openflare/apply-logs/page.tsx` |
| `app/(main)/openflare/pages/detail/page.tsx` |
| `components/auth/login-form.tsx` |
| `components/auth/login-page.tsx` |
| `components/auth/register-form.tsx` |
(Auth pages are likely safe because `login/page.tsx` and `register/page.tsx` already wrap them in `<Suspense>`.)
---
## Recommendations
### Priority 1 — Fix `/openflare/nodes` build blocker
Refactor using the existing `proxy-routes/detail` pattern:
1. Create `app/(main)/openflare/nodes/page-client.tsx` with the current page logic.
2. Change `page.tsx` to a server component that wraps the client component in `<Suspense fallback={<LoadingState />}>`.
Alternatively, wrap `<NodeTypeFilter />` and the `useSearchParams()` usage in a single child component inside `<Suspense>`.
### Priority 2 — Audit remaining pages
Apply the same `Suspense` pattern to all detail/list pages using `useSearchParams()` (see table above) to avoid repeated build failures at 1/46, 2/46, etc.
### Priority 3 — Add a CI gate
Run all three checks in CI before merge:
```bash
pnpm exec tsc --noEmit
pnpm lint
pnpm build:embed
```
### Priority 4 — Optional lint rule
Consider an ESLint rule or codemod to flag `useSearchParams()` usage outside `Suspense` boundaries, since `tsc` and `eslint` pass even when the production build fails.
---
## Actions Taken
- No code fixes applied. The failure is a structural Next.js `Suspense` requirement, not a trivial one-line lint fix.
docs/plan/verify-frontend-routes.md
+39
View File
@@ -0,0 +1,39 @@
# OpenFlare 前端路由验证报告
> **验证日期**：2026-06-18
> **对照**：`20260618-openflare-wavelet-frontend-migration.md` §6.1（FC-1 ~ FC-20）
## 路由对照
| # | 计划路由 | 状态 | 备注 |
|---|---|---|---|
| FC-1 | `/openflare` | ⚠️ partial | 仪表盘已实现；世界地图以国家列表替代 |
| FC-2 | `/openflare/nodes` | ✅ | |
| FC-3 | `/openflare/nodes/detail` | ✅ | Edge/Relay/Tunnel 三种详情 |
| FC-4 | `/openflare/proxy-routes` | ✅ | |
| FC-5 | `/openflare/proxy-routes/detail` | ✅ | 6 Section + 发布 |
| FC-6 | `/openflare/config-versions` | ✅ | |
| FC-7 | `/openflare/waf` | ✅ | |
| FC-8 | `/openflare/waf/ip-groups` | ✅ | 页内链接 |
| FC-9 | `/openflare/websites` | ✅ | |
| FC-10 | `/openflare/websites/detail` | ✅ | |
| FC-11 | `/openflare/websites/certificates` | ✅ | |
| FC-12 | `/openflare/websites/dns-accounts` | ✅ | |
| FC-13 | `/openflare/pages` | ✅ | |
| FC-14 | `/openflare/pages/detail` | ✅ | |
| FC-15 | `/openflare/origins` | ✅ | |
| FC-16 | `/openflare/origins/detail` | ✅ | |
| FC-17 | `/openflare/access-logs` | ✅ | 4 Tab |
| FC-18 | `/openflare/apply-logs` | ✅ | |
| FC-19 | `/openflare/performance` | ✅ | |
| FC-20 | `/openflare/about` | ❌ | 待实现或复用 `/docs` |
## 覆盖率
- **严格完成**：18/20（90%）
- **加权**：92.5%（FC-1 计 0.5）
- **PlaceholderPage 使用**：0（组件仍存在但未引用）
## 子路由（不在侧栏顶级）
`/openflare/nodes/detail`、`proxy-routes/detail`、`pages/detail`、`websites/detail`、`websites/certificates`、`websites/dns-accounts`、`waf/ip-groups`、`origins/detail`
docs/plan/verify-frontend-services.md
+42
View File
@@ -0,0 +1,42 @@
# OpenFlare 前端 Service 层验证报告
> **验证日期**：2026-06-18
> **目录**：`Wavelet/frontend/lib/services/openflare/`
## §7.1 对照结果
| 计划服务 | 实际文件 | 注册 | 方法覆盖 |
|---|---|---|---|
| dashboard | ✅ | `openflareDashboard` | ✅ |
| node | ✅ | `openflareNode` | ✅ 12 方法 |
| proxy-route | ✅ | `openflareProxyRoute` | ✅ |
| config-version | ✅ | `openflareConfigVersion` | ✅ |
| waf | ✅ | `openflareWaf` | ✅ |
| website | ✅ | `openflareWebsite` | ✅ |
| tls-certificate | ✅ | `openflareTls` | ✅ |
| dns-account | ✅ | `openflareDns` | ✅ |
| acme-account | ⚠️ 合并 | 经 `openflareTls` | `getDefaultAcmeAccount()` |
| pages | ✅ | `openflarePages` | ✅ |
| origin | ✅ | `openflareOrigin` | ✅ |
| access-log | ✅ | `openflareAccessLog` | ✅ |
| apply-log | ✅ | `openflareApplyLog` | ✅ |
| option | ✅ | `openflareOption` | ✅ |
| update | ⚠️ partial | `openflareUpdate` | 仅 `getLatestRelease` |
## 计划外（已实现）
- `status.service.ts` → `openflareStatus`
- `uptimekuma.service.ts` → `openflareUptimeKuma`
- `legacy-base.service.ts`（基类）
## 待补 API
| 端点 | 说明 |
|---|---|
| `POST /api/update/upgrade` | 顶栏升级流程 |
| `POST /api/update/manual-upload` | 手动上传 |
| `POST /api/update/manual-upgrade` | 手动确认升级 |
| `WS /api/update/logs/ws` | 升级日志流 |
| `GET /api/about` | About 页（FC-20） |
业务 `/api/*` 其余端点均已由 Service 覆盖。
docs/plan/verify-frontend-ui.md
+33
View File
@@ -0,0 +1,33 @@
# OpenFlare 前端 UI 规范验收报告
> **验证日期**：2026-06-18
> **范围**：`Wavelet/frontend/app/(main)/openflare/`
## 总体
| 维度 | 结果 |
|---|---|
| 标题 `h1 text-2xl font-semibold tracking-tight` | ✅ |
| 外壳 `py-6 px-1` | ✅ |
| shadcn 组件（无旧 UI） | ✅ |
| 单文件 ≤600 行 | ✅（最大 access-logs 584 行） |
| loading/empty/error | ⚠️ 部分 Tab 缺 error |
| RHF + Zod 表单 | ⚠️ 部分 Dialog 待补 |
## 分模块
| 模块 | 结论 |
|---|---|
| Dashboard | ✅ PASS |
| Nodes | ⚠️ `node-editor-dialog` 缺 Zod |
| Proxy detail | ⚠️ 无效 ID/error 态待统一组件 |
| WAF | ⚠️ `rule-entry-dialog` 缺 RHF+Zod |
| Websites/Certificates | ⚠️ `dns-account-create-dialog` 缺 Zod |
| Access logs | ⚠️ folds/ip-summary Tab 缺 error |
| Config versions | ⚠️ cleanup dialog 缺 Zod |
## P1 修复建议
1. `proxy-routes/detail/page-client.tsx` — `EmptyStateWithBorder` / `ErrorInline`
2. `access-logs/page.tsx` — folds、ip-summary 的 `isError` 分支
3. `node-editor-dialog.tsx`、`rule-entry-dialog.tsx` — 补 Zod schema