# Next Terminal 前端升级对接文档

## 已完成的工作

### 1. 前端代码替换 ✅
- 从 GitHub 克隆了最新的 next-terminal 前端代码（v2.6.6+）
- 替换了旧的前端代码（v1.3.9）
- 备份了旧前端代码到 `web-backup` 目录

### 2. 前端配置修改 ✅
- 更新了 `package.json`（新依赖：Vite, TypeScript, Tailwind CSS, Ant Design 5 等）
- 配置了 `vite.config.ts`：
  - 添加开发服务器代理（/api -> localhost:8088）
  - 设置前端端口为 3000
  - 配置 PWA 支持
- 修改了 API 基础 URL 配置，使用相对路径 `/api`
- 配置 WebSocket URL 指向后端 8088 端口

### 3. 后端路由重构 ✅
- 重构了 `server/app/server.go` 的路由配置
- 添加了 `/api/admin` 前缀以匹配新前端的 API 调用格式
- 所有 API 路由现在都位于 `/api/admin/` 路径下
- 修复了 access-token 删除接口的路径参数问题

### 4. 新增后端 API 端点 ✅
创建了 `server/api/setup.go` 文件，包含以下新端点：

#### 初始化相关
- `GET /api/admin/setup-status` - 检查系统是否需要初始化
- `POST /api/admin/setup-user` - 创建初始管理员用户

#### 登录认证相关
- `GET /api/admin/login-status` - 获取当前登录状态
- `POST /api/admin/validate-totp` - 验证 TOTP 验证码
- `GET /api/admin/account/password-policy` - 获取密码策略配置

### 5. 数据模型扩展 ✅
- 在 `dto/auth.go` 中添加了 `UserCreate` 结构体

### 6. 后端编译验证 ✅
- Go 后端代码编译成功，无错误

## 技术栈变化

### 旧版本 (v1.3.9)
- **构建工具**: Create React App (react-scripts)
- **UI 框架**: Ant Design 4.x
- **语言**: JavaScript (JSX)
- **状态管理**: React Query 3.x
- **路由**: React Router 6
- **终端**: xterm 4.x

### 新版本 (latest)
- **构建工具**: Vite 7.x
- **UI 框架**: Ant Design 5.x + Tailwind CSS 4.x
- **语言**: TypeScript (TSX)
- **状态管理**: React Query 5.x + Jotai
- **路由**: React Router 7.x
- **终端**: @xterm/xterm 5.x
- **新增功能**:
  - i18n 国际化支持
  - PWA 支持
  - WebAuthn 认证
  - OIDC 支持
  - 更多资产管理功能

## 待完成的工作

### 高优先级
1. **前端依赖安装**
   - 正在执行 npm install（需要较长时间）
   - 安装完成后需要验证依赖完整性

2. **前端构建测试**
   ```bash
   cd web
   npm run build
   ```
   - 可能需要修复 TypeScript 类型错误
   - 可能需要调整 Tailwind CSS 配置
   - 可能需要处理新的依赖兼容性问题

3. **核心功能对接验证**
   - [ ] 用户登录流程
   - [ ] 资产管理（CRUD）
   - [ ] 会话连接（SSH/RDP/VNC）
   - [ ] 终端操作
   - [ ] 权限控制

### 中优先级
4. **缺失 API 端点实现**

   新前端包含许多旧后端不支持的功能，需要逐步实现：

   #### 用户管理增强
   - [ ] 部门管理 API (`/departments`)
   - [ ] 用户部门关联 API
   - [ ] LDAP 同步 API (`/sync-from-ldap`)
   - [ ] 用户导入 API (`/import`)
   - [ ] 用户客户端证书 API (`/client-cert`)
   - [ ] 批量重置密码/TOTP API

   #### 资产管理增强
   - [ ] 资产分组 API (`/groups`, `/tree`)
   - [ ] 资产排序 API (`/sort`)
   - [ ] 资产网关统一接口 (`/change-gateway`)
   - [ ] 资产连接检测 API (`/checking`)
   - [ ] 资产解密 API (`/decrypted`)
   - [ ] Logo 管理 API (`/logos`)

   #### 新功能模块
   - [ ] 数据库资产管理 (`database-assets`)
   - [ ] 网站资产管理 (`websites`)
   - [ ] 证书管理 (`certificates`)
   - [ ] DNS 提供商管理 (`dns-providers`)
   - [ ] 命令过滤器 (`command-filters`, `command-filter-rules`)
   - [ ] 代码片段管理 (`snippets`, `snippet-users`)
   - [ ] Agent 网关管理 (`agent-gateways`, `agent-gateway-tokens`)
   - [ ] SSH 网关管理 (`ssh-gateways`)
   - [ ] 网关组管理 (`gateway-groups`)
   - [ ] 计划任务管理 (`scheduled-tasks`) - 替代旧的 jobs
   - [ ] 操作日志 (`operation-logs`)
   - [ ] 访问日志 (`access-logs`)
   - [ ] 文件系统日志 (`filesystem-logs`)
   - [ ] Shell 助手 (`shell-assistant`)
   - [ ] 会话命令记录 (`session-commands`)
   - [ ] 数据库 SQL 日志 (`database-sql-logs`)
   - [ ] 数据库工单 (`db-work-orders`)

   #### 安全与认证
   - [ ] WebAuthn API (`/webauthn/*`)
   - [ ] 安全令牌 API (`/security-token/*`)
   - [ ] OIDC 客户端管理 (`oidc-clients`)
   - [ ] OIDC Server 功能 (`/oidc/server/*`)
   - [ ] 登录锁定管理 (`login-locked`)
   - [ ] 企业微信集成 (`wechat-work`)

   #### 系统设置
   - [ ] 许可证管理 (`license`)
   - [ ] Logo 管理 (`logo`)
   - [ ] 品牌/自定义设置 (`branding`)
   - [ ] 匿名访问设置 (`anonymous`)
   - [ ] Portal 页面设置 (`portal`)
   - [ ] 访问设置 (`access-setting`)

5. **数据结构适配**
   - 新前端可能期望不同的响应格式
   - 需要检查并调整 API 响应结构
   - 可能需要添加或修改字段

6. **静态资源处理**
   - 配置后端服务前端静态文件
   - 确保 `/api/logo` 等静态资源端点正常工作
   - 处理 PWA 相关资源

### 低优先级
7. **性能优化**
   - 实现新前端需要的分页、排序优化
   - 添加缓存策略
   - 优化大量数据的加载

8. **国际化支持**
   - 配置 i18n 后端支持
   - 添加多语言翻译文件

9. **测试与调试**
   - 编写单元测试
   - 进行端到端测试
   - 性能测试

## 快速开始指南

### 1. 启动后端
```bash
cd next-terminal-1.3.9
# 编辑 config.yml 配置数据库等信息
go run main.go
```

### 2. 安装并启动前端（开发模式）
```bash
cd web
npm install  # 如果尚未完成
npm run dev  # 启动开发服务器，默认在 http://localhost:3000
```

### 3. 访问系统
- 前端地址: http://localhost:3000
- 后端 API: http://localhost:8088/api
- 首次访问会进入初始化页面，需要创建管理员账户

## 注意事项

1. **API 兼容性**: 新前端是为更新的后端版本设计的，部分高级功能暂时不可用
2. **渐进式实现**: 建议优先实现核心功能，然后逐步添加高级功能
3. **数据备份**: 在进行升级前务必备份数据库
4. **测试环境**: 建议先在测试环境中验证所有功能
5. **日志监控**: 升级后密切关注日志，及时发现和解决问题

## 下一步行动

1. 等待 npm install 完成
2. 尝试前端构建，修复可能的错误
3. 启动前后端服务，测试基本功能
4. 根据测试结果补充缺失的 API 端点
5. 逐步完善高级功能

---

**最后更新时间**: 2026-04-16
**当前状态**: 前端代码已替换，后端基础 API 已就绪，等待前端依赖安装完成