133 lines
3.8 KiB
Markdown
133 lines
3.8 KiB
Markdown
# Chongming Web
|
||
|
||
Chongming-Zenoh 平台的前端应用，基于 **Vue 3 + TypeScript + Vite + Element Plus** 构建。
|
||
|
||
---
|
||
|
||
## 技术栈
|
||
|
||
| 层面 | 技术 |
|
||
| -------------- | -------------------------------------------------- |
|
||
| **框架** | Vue 3.5（Composition API + `<script setup>`） |
|
||
| **语言** | TypeScript |
|
||
| **构建** | Vite |
|
||
| **UI 组件库** | Element Plus + `@element-plus/icons-vue` |
|
||
| **状态管理** | Pinia |
|
||
| **路由** | Vue Router（Hash History） |
|
||
| **API 客户端** | `@hey-api/openapi-ts` 自动生成（类型安全） |
|
||
| **格式化** | oxfmt |
|
||
| **自动导入** | `unplugin-auto-import` + `unplugin-vue-components` |
|
||
|
||
---
|
||
|
||
## 项目结构
|
||
|
||
```text
|
||
src/chongming-web/
|
||
├── index.html # 入口 HTML
|
||
├── vite.config.ts # Vite 构建配置
|
||
├── tsconfig.json # TypeScript 配置
|
||
├── package.json # 依赖与脚本
|
||
├── .env.development # 开发环境变量
|
||
├── .env.production # 生产环境变量
|
||
├── public/ # 静态资源
|
||
└── src/
|
||
├── main.ts # 应用入口（挂载 Pinia + Router）
|
||
├── App.vue # 布局框架（Header + Main + Footer）
|
||
├── api/
|
||
│ └── generated/ # 自动生成的 API 客户端
|
||
│ ├── sdk.gen.ts # 类型安全的 API 调用函数
|
||
│ ├── types.gen.ts # 请求/响应 TypeScript 类型
|
||
│ └── client.gen.ts # HTTP 客户端配置
|
||
├── router/
|
||
│ └── index.ts # Vue Router 路由定义
|
||
├── stores/ # Pinia 状态管理
|
||
├── views/ # 页面组件
|
||
└── components/ # 公共组件
|
||
```
|
||
|
||
---
|
||
|
||
## 快速开始
|
||
|
||
### 环境要求
|
||
|
||
- Node.js >= 22
|
||
|
||
### 安装与运行
|
||
|
||
```bash
|
||
cd src/chongming-web
|
||
|
||
# 安装依赖
|
||
npm install
|
||
|
||
# 启动开发服务器（http://localhost:5173）
|
||
npm run dev
|
||
|
||
# 类型检查 + 生产构建
|
||
npm run build
|
||
|
||
# 代码格式化
|
||
npm run format
|
||
```
|
||
|
||
---
|
||
|
||
## 开发指南
|
||
|
||
### 开发代理
|
||
|
||
Vite 开发服务器配置了代理：`/api` 请求自动转发到后端 `http://127.0.0.1:8000`。
|
||
|
||
确保后端已启动后再运行前端开发服务器。
|
||
|
||
### 生成 API 客户端
|
||
|
||
当后端接口变更后，重新生成类型安全的 API 客户端：
|
||
|
||
```bash
|
||
# 确保后端在 8000 端口运行
|
||
npm run openapi
|
||
```
|
||
|
||
该命令调用 `@hey-api/openapi-ts` 从 `http://127.0.0.1:8000/openapi.json` 生成 `src/api/generated/` 中的所有文件。
|
||
|
||
### 使用 API 客户端
|
||
|
||
```typescript
|
||
import { endpointApiV1DoubaoAnalyzePost } from "@/api/generated/sdk.gen";
|
||
|
||
const result = await endpointApiV1DoubaoAnalyzePost({
|
||
body: { image_base64: "...", prompt: "描述图片" },
|
||
});
|
||
```
|
||
|
||
所有 API 函数和类型都是自动生成的，具有完整的 TypeScript 类型推断。
|
||
|
||
### 添加新页面
|
||
|
||
1. 在 `src/views/` 创建 Vue 组件
|
||
2. 在 `src/router/index.ts` 添加路由配置
|
||
3. 在 `src/App.vue` 的导航菜单添加入口
|
||
|
||
### 自动导入
|
||
|
||
项目配置了 `unplugin-auto-import` 和 `unplugin-vue-components`，Element Plus 组件**无需手动导入**：
|
||
|
||
```vue
|
||
<template>
|
||
<!-- 直接使用，自动按需导入 -->
|
||
<el-button type="primary">按钮</el-button>
|
||
<el-input v-model="text" />
|
||
</template>
|
||
```
|
||
|
||
---
|
||
|
||
## 部署说明
|
||
|
||
- **Base Path**：`/static/` — 前端部署在子路径下，后端处理 `/api`，静态资源在 `/static/`
|
||
- 生产构建输出目录：`dist/`
|
||
- 构建命令：`npm run build`
|