Vue Demo 开发指南

快速开始

1. 安装依赖

cd frontend/vue-demo
yarn install
# 或
npm install

2. 启动开发服务器

yarn dev
# 或
npm run dev

访问: http://localhost:5173

3. 构建生产版本

yarn build
# 或
npm run build

项目结构

vue-demo/
├── src/
│   ├── api/              # API 接口定义
│   │   └── index.js      # 所有 API 方法
│   ├── assets/           # 静态资源
│   ├── components/       # 公共组件
│   │   └── TaskCenter/   # 任务中心组件
│   ├── router/           # 路由配置
│   ├── stores/           # Pinia 状态管理
│   ├── views/            # 页面组件
│   │   ├── Login.vue     # 登录页
│   │   ├── Register.vue  # 注册页
│   │   └── Editor.vue    # 编辑器页
│   ├── App.vue           # 根组件
│   └── main.js           # 入口文件
├── vite.config.js        # Vite 配置
├── package.json          # 项目配置
└── API_GUIDE.md          # API 使用指南

技术栈

Vue 3 - 渐进式 JavaScript 框架
Vite - 下一代前端构建工具
Vue Router - 官方路由管理器
Pinia - Vue 状态管理库
Element Plus - Vue 3 UI 组件库
Axios - HTTP 客户端

开发配置

后端 API 地址配置

编辑 vite.config.js 中的 API_SERVER 变量：

// 本地开发
const API_SERVER = 'http://localhost:18520'

// 远程服务器
const API_SERVER = 'http://服务器IP:18520'

代理配置

Vite 已配置代理，自动转发以下请求：

/api/* → 后端 API
/auth/* → 认证服务

API 使用

详见 API_GUIDE.md

快速示例

import { templateApi, documentApi } from '@/api'

// 获取模板列表
const templates = await templateApi.list()

// 上传文档
const result = await parseApi.upload(file)

状态管理

Task Center Store

import { useTaskCenterStore } from '@/stores/taskCenter'

const taskStore = useTaskCenterStore()

// 添加任务
taskStore.addTask({
  id: 'task-1',
  type: 'parse',
  status: 'running',
  progress: 50
})

// 更新任务
taskStore.updateTask('task-1', { progress: 100, status: 'completed' })

Template Store

import { useTemplateStore } from '@/stores/template'

const templateStore = useTemplateStore()

// 加载模板
await templateStore.loadTemplates()

// 选择模板
templateStore.selectTemplate(templateId)

组件使用

任务中心

<template>
  <TaskCenterFab />
  <TaskCenterPanel />
</template>

<script setup>
import { TaskCenterFab, TaskCenterPanel } from '@/components/TaskCenter'
</script>

路由配置

const routes = [
  { path: '/login', component: Login },
  { path: '/register', component: Register },
  { path: '/editor/:documentId?', component: Editor }
]

环境变量

创建 .env.local 文件：

# API 服务器地址
VITE_API_SERVER=http://localhost:18520

# 其他配置
VITE_APP_TITLE=灵越智报

在代码中使用：

const apiServer = import.meta.env.VITE_API_SERVER

调试技巧

1. 查看网络请求

打开浏览器开发者工具 → Network 标签

2. Vue DevTools

安装 Vue DevTools 浏览器扩展，查看组件状态和 Pinia store

3. API 调试

在 src/api/index.js 中已配置响应拦截器，会自动打印错误：

api.interceptors.response.use(
  response => { /* ... */ },
  error => {
    console.error('API Error:', error)
    return Promise.reject(error)
  }
)

常见问题

1. CORS 跨域问题

已通过 Vite 代理解决，确保 vite.config.js 中的代理配置正确。

2. API 404 错误

检查：

后端服务是否启动（端口 18520）
API 路径是否正确（参考 API_GUIDE.md）
控制器路径是否匹配（graph-service 使用 /api/v1/graph/*）

3. Token 过期

使用 refreshToken 刷新：

const newToken = await authApi.refreshToken(refreshToken)
localStorage.setItem('accessToken', newToken)

后端服务检查

检查后端是否运行

curl http://localhost:18520/actuator/health

预期响应：

{"status":"UP"}

测试 API 接口

# 获取模板列表
curl http://localhost:18520/api/v1/templates

# 获取图谱模板列表
curl http://localhost:18520/api/v1/graph/templates

部署

构建

yarn build

生成的文件在 dist/ 目录

Nginx 配置示例

server {
    listen 80;
    server_name your-domain.com;
    
    root /path/to/dist;
    index index.html;
    
    location / {
        try_files $uri $uri/ /index.html;
    }
    
    location /api {
        proxy_pass http://localhost:18520;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
    
    location /auth {
        proxy_pass http://localhost:18520;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

更新日志

2026-02-12

✅ 适配后端 graph-service 路径变更
✅ 新增图谱相关 API（graphTemplateApi, graphProjectApi, graphReportApi）
✅ 更新 vite.config.js 使用本地后端
✅ 添加 API 使用指南文档

README_DEV.md 5.3 KB Историја Датотека