chongming-web/README.md

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