# Vue Demo 开发指南

## 快速开始

### 1. 安装依赖

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

### 2. 启动开发服务器

```bash
yarn dev
# 或
npm run dev
```

访问: http://localhost:5173

### 3. 构建生产版本

```bash
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` 变量：

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

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

### 代理配置

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

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

## API 使用

详见 [API_GUIDE.md](./API_GUIDE.md)

### 快速示例

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

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

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

## 状态管理

### Task Center Store

```javascript
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

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

const templateStore = useTemplateStore()

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

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

## 组件使用

### 任务中心

```vue
<template>
  <TaskCenterFab />
  <TaskCenterPanel />
</template>

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

## 路由配置

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

## 环境变量

创建 `.env.local` 文件：

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

# 其他配置
VITE_APP_TITLE=灵越智报
```

在代码中使用：

```javascript
const apiServer = import.meta.env.VITE_API_SERVER
```

## 调试技巧

### 1. 查看网络请求

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

### 2. Vue DevTools

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

### 3. API 调试

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

```javascript
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 刷新：

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

## 后端服务检查

### 检查后端是否运行

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

预期响应：
```json
{"status":"UP"}
```

### 测试 API 接口

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

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

## 部署

### 构建

```bash
yarn build
```

生成的文件在 `dist/` 目录

### Nginx 配置示例

```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 使用指南文档