157 lines
6.4 KiB
Markdown
157 lines
6.4 KiB
Markdown
# FST Editor archi 前端
|
||
|
||
一个基于 React 的「FST Editor 标签管理」前端原型，用于展示和增改 FST 标签列表。
|
||
|
||
## 技术栈
|
||
|
||
- React 18
|
||
- react-scripts（Create React App 工具链）
|
||
- axios（调用后端接口）
|
||
- lucide-react（图标库）
|
||
|
||
## 目录结构（关键文件）
|
||
|
||
- `package.json`：项目依赖和脚本
|
||
- `.env`：环境变量（后端 API 地址）
|
||
- `public/index.html`：HTML 模板
|
||
- `src/index.js`：React 入口文件
|
||
- `App.jsx`：主应用组件，整体布局与页面逻辑
|
||
- `App.css`：布局、侧边栏、标签页、表格等样式
|
||
- `services/api.js`：封装 FST 标签相关接口
|
||
|
||
## 环境准备
|
||
|
||
1. 安装 Node.js（建议 16+，18+ 更佳）
|
||
2. 安装 npm（随 Node 一起安装即可）
|
||
|
||
## 安装依赖
|
||
|
||
在项目根目录执行：
|
||
|
||
```bash
|
||
npm install
|
||
```
|
||
|
||
## 启动开发环境
|
||
|
||
```bash
|
||
npm start
|
||
```
|
||
|
||
默认会在浏览器打开：
|
||
|
||
- `http://localhost:8081/`
|
||
|
||
如未自动打开，可手动在浏览器输入上述地址访问。
|
||
|
||
## 构建生产包
|
||
|
||
```bash
|
||
npm run build
|
||
```
|
||
|
||
构建结果会输出到 `build/` 目录，可用于部署。
|
||
|
||
## 环境变量
|
||
|
||
后端接口地址通过 `.env` 配置（生产环境使用），开发环境通过代理转发：
|
||
|
||
```env
|
||
REACT_APP_API_BASE_URL=http://115.190.223.209:5232/api
|
||
```
|
||
|
||
在 `services/api.js` 中：
|
||
|
||
- 开发环境：axios `baseURL` 为 `/api`，由 `package.json` 的 `proxy` 配置转发到 `http://115.190.223.209:5232`。
|
||
- 生产环境：读取 `.env` 的 `REACT_APP_API_BASE_URL` 作为 axios `baseURL`。
|
||
|
||
你可以根据实际后端地址进行修改。
|
||
|
||
## OIDC 单点登录联动
|
||
|
||
前端已与后端认证流程联动：
|
||
|
||
1. 应用启动时调用 `GET /api/auth/me` 读取当前 Session 用户。
|
||
2. 若未登录（401），前端自动跳转 `/api/login?next=<当前页面>`。
|
||
3. 后端回调成功后会带着 `next` 回跳到前端原页面。
|
||
4. 业务 API 请求若返回 401，也会自动触发登录跳转。
|
||
|
||
相关实现文件：
|
||
|
||
- `src/services/auth.js`：登录跳转、退出、用户信息获取
|
||
- `src/services/api.js`：axios 401 拦截并跳转登录
|
||
- `src/App.jsx`：应用初始化时鉴权和用户显示
|
||
|
||
## 功能说明
|
||
|
||
- 左侧侧边栏
|
||
- FST Editor 标签管理导航
|
||
- 「增改Fst Editor标签」「Version List」菜单入口
|
||
- 顶部
|
||
- 右侧操作图标（夜间模式、全屏、用户）
|
||
- 标签页区域
|
||
- 多个标签 Tab（增改Fst Editor标签、Version List）
|
||
- 内容区域
|
||
- 标签表格展示：Name、Description、Createtime、Updatetime、Operation
|
||
- 支持「编辑」「新增下级」「删除」「release」
|
||
- Name/Description 列缩窄并悬浮显示全称；Name 按后端 level 缩进展示层级
|
||
- 页面加载自动从 `/api/fst/print_tree` 接口获取数据
|
||
|
||
## 版本与 JSON 导入导出
|
||
|
||
- 版本快照存储
|
||
- Release 时，会先创建版本（`POST /versions`），再把当前前端表格中未删除的标签，以 JSON 格式保存到 `fst_stash` 表（`POST /fst/stash`）。
|
||
- 保存结构示例：
|
||
- `nodes`: 扁平化的标签节点数组，包含 `name`、`level`、`createtime`、`updateTime`、`parentId`、`treeLevel`、`deleted` 等字段
|
||
- `meta`: 版本备注、发布时间等元数据（如 `remark`、`released_at`）
|
||
|
||
- 版本导出（Version List）
|
||
- 在 Version List 页面点击导出，会调用 `GET /fst/stash/{version}`。
|
||
- 将 `fst_stash` 中对应版本的 `content` 字段以 JSON 文件形式下载，例如：`Version_1.0.0.json`。
|
||
|
||
- JSON 导入（FstTagPage）
|
||
- 在「增改Fst Editor标签」页面点击「导入」，选择 `.json` 文件：
|
||
- 支持两种结构：
|
||
- 直接数组：`[{...}, {...}]`
|
||
- 带包装：`{ "version": "1.0.0", "nodes": [...], "meta": {...} }`
|
||
- 导入后：
|
||
- 会将 `nodes` 解析并追加到当前前端表格中，恢复层级（依赖 `treeLevel` 顺序计算 `parentId`）。
|
||
- 默认不会直接修改正式 FST 表，只更新前端数据。
|
||
- 同时会尝试将该 JSON 写入 `fst_stash`：
|
||
- 版本号来源优先级：`parsed.version` > 文件名（`Version_xxx.json`）> 用户输入。
|
||
- 若版本不存在，则自动调用 `POST /versions` 创建版本，再调用 `POST /fst/stash` 保存 JSON。
|
||
- 如果写入 `fst_stash` 失败，前端会弹出后端返回的错误信息，便于排查。
|
||
|
||
- Release 与正式 FST 表
|
||
- 导入/临时编辑只影响前端状态和 `fst_stash`（通过 Release 或导入逻辑写入），不会立即写入正式 FST 标签表。
|
||
- 点击 Release 时：
|
||
- 创建版本记录。
|
||
- 将当前前端标签快照保存到 `fst_stash`。
|
||
- 之后再按现有逻辑逐条写入暂存表（通过 `/fst/stash/update`），由后端持久化。
|
||
|
||
### 临时编辑版本与正式版本
|
||
|
||
- 前端在编辑标签时，会使用一个「临时编辑版本」保存当前工作状态（例如 `v1_editing_temp`）。
|
||
- 临时编辑版本只存在于 `versions` 与 `fst_stash` 表中，不会在 Version List 页面展示。
|
||
- 这样可以反复编辑 / 导入 JSON，而不影响已发布的正式版本。
|
||
- 当用户在前端点击 Release：
|
||
- 会根据当前临时编辑版本的内容创建一个新的正式版本（例如 `v1.0.0`）。
|
||
- 将当前标签快照写入对应正式版本的 `fst_stash`。
|
||
- 临时编辑版本及其 `fst_stash` 会在发布成功后被清理掉。
|
||
- 如果后端已删除对应的临时编辑版本，而前端仍在使用：
|
||
- 前端在保存/发布时会收到后端错误。
|
||
- 界面会提示「当前编辑版本已被删除」，引导用户刷新后重新进入编辑流程。
|
||
|
||
### Version List 自动刷新
|
||
|
||
- Version List 页面展示所有正式版本（隐藏所有 `*_editing_*` 或 `_editing_temp` 的临时版本）。
|
||
- 刷新时机：
|
||
- 首次打开 Version List 页面时，会自动请求一次版本列表。
|
||
- 从其他页面切换回 Version List 标签页时，会再次刷新列表，保证看到的是最新版本。
|
||
- 当用户在「增改Fst Editor标签」页面完成 Release 后，会触发一个浏览器事件 `fst:release_success`：
|
||
- 如果此时 Version List 正在当前标签页，会立即刷新列表。
|
||
- 如果当时在别的标签页，切回 Version List 时也会自动刷新。
|
||
- 通过这种方式，用户在发布新版本后，无需手动刷新浏览器即可看到最新的版本记录。
|
||
|
||
你可以在 `App.jsx`、`services/api.js` 以及相关自定义 hooks 中按需要继续扩展实际的交互逻辑和接口调用。
|