fst_editor-dev/README.md

# 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 中按需要继续扩展实际的交互逻辑和接口调用。