modify: 首页视图与文档更新

2026-08-14 18:06:59 +08:00
parent b478b3d3b5
commit 79d29a8d8d
4 changed files with 116 additions and 125 deletions
@@ -1,42 +1,132 @@
-# chongming-web
+# Chongming Web

-This template should help get you started developing with Vue 3 in Vite.
+Chongming-Zenoh 平台的前端应用，基于 **Vue 3 + TypeScript + Vite + Element Plus** 构建。

-## Recommended IDE Setup
+---

-[VS Code](https://code.visualstudio.com/) + [Vue (Official)](https://marketplace.visualstudio.com/items?itemName=Vue.volar) (and disable Vetur).
+## 技术栈

-## Recommended Browser Setup
+| 层面           | 技术                                               |
+| -------------- | -------------------------------------------------- |
+| **框架**       | 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` |

- Chromium-based browsers (Chrome, Edge, Brave, etc.):
-  - [Vue.js devtools](https://chromewebstore.google.com/detail/vuejs-devtools/nhdogjmejiglipccpnnnanhbledajbpd)
-  - [Turn on Custom Object Formatter in Chrome DevTools](http://bit.ly/object-formatters)
- Firefox:
-  - [Vue.js devtools](https://addons.mozilla.org/en-US/firefox/addon/vue-js-devtools/)
-  - [Turn on Custom Object Formatter in Firefox DevTools](https://fxdx.dev/firefox-devtools-custom-object-formatters/)
+---

-## Type Support for `.vue` Imports in TS
+## 项目结构

-TypeScript cannot handle type information for `.vue` imports by default, so we replace the `tsc` CLI with `vue-tsc` for type checking. In editors, we need [Volar](https://marketplace.visualstudio.com/items?itemName=Vue.volar) to make the TypeScript language service aware of `.vue` types.
+```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/             # 公共组件
+```

-## Customize configuration
+---

-See [Vite Configuration Reference](https://vite.dev/config/).
+## 快速开始

-## Project Setup
+### 环境要求

-```sh
+- Node.js >= 22
+
+### 安装与运行
+
+```bash
+cd src/chongming-web
+
+# 安装依赖
 npm install
-```

-### Compile and Hot-Reload for Development
-
-```sh
+# 启动开发服务器（http://localhost:5173）
 npm run dev
-```

-### Type-Check, Compile and Minify for Production
-
-```sh
+# 类型检查 + 生产构建
 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`
@@ -31,7 +31,6 @@ declare module 'vue' {
    HelloWorld: typeof import('./src/components/HelloWorld.vue')['default']
    RouterLink: typeof import('vue-router')['RouterLink']
    RouterView: typeof import('vue-router')['RouterView']
-    TheWelcome: typeof import('./src/components/TheWelcome.vue')['default']
    WelcomeItem: typeof import('./src/components/WelcomeItem.vue')['default']
  }
 }
@@ -57,6 +56,5 @@ declare global {
  const HelloWorld: typeof import('./src/components/HelloWorld.vue')['default']
  const RouterLink: typeof import('vue-router')['RouterLink']
  const RouterView: typeof import('vue-router')['RouterView']
-  const TheWelcome: typeof import('./src/components/TheWelcome.vue')['default']
  const WelcomeItem: typeof import('./src/components/WelcomeItem.vue')['default']
 }
@@ -1,95 +0,0 @@
-<script setup lang="ts">
-import WelcomeItem from './WelcomeItem.vue'
-import DocumentationIcon from './icons/IconDocumentation.vue'
-import ToolingIcon from './icons/IconTooling.vue'
-import EcosystemIcon from './icons/IconEcosystem.vue'
-import CommunityIcon from './icons/IconCommunity.vue'
-import SupportIcon from './icons/IconSupport.vue'
-
-const openReadmeInEditor = () => fetch('/__open-in-editor?file=README.md')
-</script>
-
-<template>
-  <WelcomeItem>
-    <template #icon>
-      <DocumentationIcon />
-    </template>
-    <template #heading>Documentation</template>
-
-    Vue’s
-    <a href="https://vuejs.org/" target="_blank" rel="noopener">official documentation</a>
-    provides you with all information you need to get started.
-  </WelcomeItem>
-
-  <WelcomeItem>
-    <template #icon>
-      <ToolingIcon />
-    </template>
-    <template #heading>Tooling</template>
-
-    This project is served and bundled with
-    <a href="https://vite.dev/guide/features.html" target="_blank" rel="noopener">Vite</a>. The
-    recommended IDE setup is
-    <a href="https://code.visualstudio.com/" target="_blank" rel="noopener">VSCode</a>
-    +
-    <a href="https://github.com/vuejs/language-tools" target="_blank" rel="noopener"
-      >Vue - Official</a
-    >. If you need to test your components and web pages, check out
-    <a href="https://vitest.dev/" target="_blank" rel="noopener">Vitest</a>
-    and
-    <a href="https://www.cypress.io/" target="_blank" rel="noopener">Cypress</a>
-    /
-    <a href="https://playwright.dev/" target="_blank" rel="noopener">Playwright</a>.
-
-    <br />
-
-    More instructions are available in
-    <a href="javascript:void(0)" @click="openReadmeInEditor"><code>README.md</code></a
-    >.
-  </WelcomeItem>
-
-  <WelcomeItem>
-    <template #icon>
-      <EcosystemIcon />
-    </template>
-    <template #heading>Ecosystem</template>
-
-    Get official tools and libraries for your project:
-    <a href="https://pinia.vuejs.org/" target="_blank" rel="noopener">Pinia</a>,
-    <a href="https://router.vuejs.org/" target="_blank" rel="noopener">Vue Router</a>,
-    <a href="https://test-utils.vuejs.org/" target="_blank" rel="noopener">Vue Test Utils</a>, and
-    <a href="https://github.com/vuejs/devtools" target="_blank" rel="noopener">Vue Dev Tools</a>. If
-    you need more resources, we suggest paying
-    <a href="https://github.com/vuejs/awesome-vue" target="_blank" rel="noopener">Awesome Vue</a>
-    a visit.
-  </WelcomeItem>
-
-  <WelcomeItem>
-    <template #icon>
-      <CommunityIcon />
-    </template>
-    <template #heading>Community</template>
-
-    Got stuck? Ask your question on
-    <a href="https://chat.vuejs.org" target="_blank" rel="noopener">Vue Land</a>
-    (our official Discord server), or
-    <a href="https://stackoverflow.com/questions/tagged/vue.js" target="_blank" rel="noopener"
-      >StackOverflow</a
-    >. You should also follow the official
-    <a href="https://bsky.app/profile/vuejs.org" target="_blank" rel="noopener">@vuejs.org</a>
-    Bluesky account or the
-    <a href="https://x.com/vuejs" target="_blank" rel="noopener">@vuejs</a>
-    X account for latest news in the Vue world.
-  </WelcomeItem>
-
-  <WelcomeItem>
-    <template #icon>
-      <SupportIcon />
-    </template>
-    <template #heading>Support Vue</template>
-
-    As an independent project, Vue relies on community backing for its sustainability. You can help
-    us by
-    <a href="https://vuejs.org/sponsor/" target="_blank" rel="noopener">becoming a sponsor</a>.
-  </WelcomeItem>
-</template>
@@ -1,6 +1,4 @@
-<script setup lang="ts">
-import TheWelcome from '../components/TheWelcome.vue'
-</script>
+<script setup lang="ts"></script>

 <template>
  <main>