first commit

2025-08-24 15:47:51 +08:00
commit 69bf5500cd
13 changed files with 2262 additions and 0 deletions
--- a/docs/开发指南.md
+++ b/docs/开发指南.md
@@ -0,0 +1,323 @@
+# 项目开发指南（Vue 3 + Vite + Element Plus + Axios）
+
+> 本文档面向日常开发与维护，覆盖环境准备、目录结构、编码规范、网络请求、UI 使用、构建部署与常见问题等。
+
+## 一、项目概览
+
+- 框架：Vue 3（Composition API）
+- 构建：Vite 5
+- 组件库：Element Plus
+- 网络：Axios（已内置实例与拦截器）
+- 运行脚本：`npm run dev | build | preview`
+
+## 二、环境要求
+
+- Node.js：建议 18+（可用 `node -v` 检查）
+- 包管理器：npm（内置于 Node）或 pnpm/yarn（任选其一）
+- 操作系统：Windows / macOS / Linux
+
+## 三、目录结构
+
+当前主要目录：
+
+```
+├─ index.html               # 应用入口 HTML
+├─ vite.config.js           # Vite 配置
+├─ package.json             # 脚本与依赖
+├─ src/
+│  ├─ main.js               # 应用入口，注册 Element Plus
+│  ├─ App.vue               # 示例页面（按钮 + 请求演示）
+│  └─ plugins/
+│     └─ http.js            # Axios 实例与拦截器
+└─ docs/
+   └─ 开发指南.md            # 本文档
+```
+
+推荐扩展（按需新增）：
+
+```
+src/
+├─ api/                     # 接口定义与请求函数（封装到 http 实例上）
+├─ assets/                  # 静态资源（图片、字体等）
+├─ components/              # 通用基础组件
+├─ views/                   # 页面级组件
+├─ router/                  # 路由（如使用 Vue Router）
+├─ store/                   # 状态管理（如使用 Pinia）
+├─ styles/                  # 全局样式、变量、主题定制
+└─ utils/                   # 工具方法（格式化、校验、下载等）
+```
+
+## 四、快速开始
+
+- 安装依赖：`npm install`
+- 启动开发：`npm run dev`（默认 http://localhost:5173）
+- 构建产物：`npm run build`（输出至 `dist/`）
+- 本地预览：`npm run preview`
+
+## 五、配置说明
+
+### 1. 环境变量
+
+建议使用 Vite 的环境文件管理不同环境：
+
+- `.env.development`（开发）
+- `.env.production`（生产）
+
+示例内容：
+
+```
+# .env.development
+VITE_API_BASE=https://dev-api.example.com
+
+# .env.production
+VITE_API_BASE=https://api.example.com
+```
+
+在代码中使用：
+
+```js
+const baseURL = import.meta.env.VITE_API_BASE
+```
+
+### 2. Vite 配置（`vite.config.js`）
+
+常用配置要点：
+- 别名：为 `src` 设置 `@` 方便导入。
+- 代理：开发阶段转发 API，避免 CORS。
+
+示例（按需修改后替换到 `vite.config.js`）：
+
+```js
+import { defineConfig } from 'vite'
+import vue from '@vitejs/plugin-vue'
+import path from 'node:path'
+
+export default defineConfig({
+  plugins: [vue()],
+  resolve: {
+    alias: { '@': path.resolve(__dirname, 'src') },
+  },
+  server: {
+    proxy: {
+      '/api': {
+        target: 'https://dev-api.example.com',
+        changeOrigin: true,
+        rewrite: (p) => p.replace(/^\/api/, ''),
+      },
+    },
+  },
+})
+```
+
+### 3. Axios 配置（`src/plugins/http.js`）
+
+当前实现：
+- `baseURL: '/'`（建议改为 `import.meta.env.VITE_API_BASE`）
+- 超时 15s
+- 预留请求拦截器（注入 Token）与响应拦截器（统一错误处理）
+
+建议修改：
+
+```js
+const http = axios.create({
+  baseURL: import.meta.env.VITE_API_BASE || '/',
+  timeout: 15000,
+})
+```
+
+统一错误处理示例（可在响应拦截器中加入）：
+
+```js
+import { ElMessage } from 'element-plus'
+
+http.interceptors.response.use(
+  (res) => res,
+  (error) => {
+    const msg = error?.response?.data?.message || error.message || '请求失败'
+    ElMessage.error(msg)
+    return Promise.reject(error)
+  }
+)
+```
+
+## 六、代码与组件规范
+
+- 组件目录：一个组件一个目录（可含 `index.vue` / `index.ts`）。
+- 命名规范：
+  - 组件名：`PascalCase`（如 `UserCard.vue`）。
+  - 变量/函数：`camelCase`。
+  - 文件：`kebab-case`（工具类/样式）。
+- 组件结构：`<template>` / `<script setup>` / `<style scoped>` 顺序。
+- 导入顺序：Vue/第三方 → 别名 `@` → 相对路径。
+- 提交信息：语义化（feat/fix/docs/chore/refactor/style/test/build）。
+
+## 七、UI 与交互（Element Plus）
+
+- 全量引入已配置于 `src/main.js`：
+
+```js
+import ElementPlus from 'element-plus'
+import 'element-plus/dist/index.css'
+app.use(ElementPlus)
+```
+
+- 主题定制：
+  - 推荐在 `src/styles/variables.scss` 定义主题变量，按需覆盖 Element Plus 变量。
+  - 也可使用暗色主题与自定义主题（参考官方文档）。
+
+- 常用交互：
+  - 消息：`ElMessage.success('保存成功')`
+  - 弹窗：`ElMessageBox.confirm('确定操作吗？', '提示')`
+  - 加载：`ElLoading.service({ text: '加载中...' })`
+
+## 八、网络请求规范
+
+- 统一通过 `src/plugins/http.js` 导出的 `http` 发起请求：
+
+```js
+import http from '@/plugins/http'
+
+export function fetchUser(id) {
+  return http.get(`/users/${id}`)
+}
+
+export function createUser(payload) {
+  return http.post('/users', payload)
+}
+```
+
+- 结果解构与错误处理：
+
+```js
+try {
+  const { data } = await fetchUser(1)
+  // 根据后端约定判断 code / success
+} catch (e) {
+  // 统一拦截器会提示，这里可按需记录或兜底
+}
+```
+
+- 可选：取消请求（例如在切换路由或重复点击时）：
+
+```js
+const controller = new AbortController()
+http.get('/path', { signal: controller.signal })
+// 需要时取消
+controller.abort()
+```
+
+## 九、常见开发食谱
+
+- 新增页面：
+  - 在 `src/views/` 新建页面组件，如 `UserList.vue`。
+  - 如使用路由，在 `router` 中注册路由并在入口挂载。
+
+- 调用接口 + 加载态示例（参考 `App.vue`）：
+
+```vue
+<script setup>
+import { ref } from 'vue'
+import http from '@/plugins/http'
+
+const loading = ref(false)
+const data = ref(null)
+
+async function load() {
+  loading.value = true
+  try {
+    const res = await http.get('/example')
+    data.value = res.data
+  } finally {
+    loading.value = false
+  }
+}
+</script>
+```
+
+- 表单校验（Element Plus）：
+  - 使用 `el-form` + `rules` + `el-form-item`，提交前 `formRef.validate()`。
+
+- 消息提示：
+  - 成功：`ElMessage.success('操作成功')`
+  - 失败：`ElMessage.error('操作失败')`
+
+## 十、路由与状态（可选集成）
+
+- 安装：
+  - Vue Router：`npm i vue-router`
+  - Pinia：`npm i pinia`
+
+- 快速示例（Router）：
+
+```js
+// src/router/index.js
+import { createRouter, createWebHistory } from 'vue-router'
+
+const routes = [
+  { path: '/', component: () => import('@/views/Home.vue') },
+]
+
+export default createRouter({ history: createWebHistory(), routes })
+```
+
+```js
+// main.js
+import router from '@/router'
+app.use(router)
+```
+
+- 快速示例（Pinia）：
+
+```js
+// src/store/index.js
+import { createPinia, defineStore } from 'pinia'
+export const pinia = createPinia()
+export const useCounter = defineStore('counter', {
+  state: () => ({ count: 0 }),
+})
+```
+
+```js
+// main.js
+import { pinia } from '@/store'
+app.use(pinia)
+```
+
+## 十一、构建与部署
+
+- 构建命令：`npm run build`，产物在 `dist/`
+- 预览构建：`npm run preview`
+- 静态资源路径：如需部署到子路径，设置 `base`（`vite.config.js`）或 `--base`。
+- Nginx 示例：
+
+```
+location / {
+  try_files $uri $uri/ /index.html;
+}
+
+location /api/ {
+  proxy_pass https://api.example.com/;
+}
+```
+
+## 十二、质量保障（可选）
+
+- 代码格式化：建议接入 Prettier + ESLint。
+- 提交规范：建议使用 Commitlint + Husky 规范提交信息。
+- 单元测试：可引入 Vitest 进行组件与函数测试。
+
+## 十三、常见问题（FAQ）
+
+- 无法请求跨域？
+  - 开发环境配置 Vite 代理（见上文 server.proxy）。
+  - 生产环境由网关或 Nginx 统一转发。
+
+- 接口报错但页面无提示？
+  - 确认是否已在响应拦截器中调用 `ElMessage.error`。
+
+- Element Plus 主题不生效？
+  - 确保样式覆盖顺序正确，且未被 `scoped` 限制。
+
+---
+
+如需我帮你接入 Router/Pinia、主题定制或代码规范工具链，请告诉我具体偏好与要求。