urbanLifeline/docs/前端完整指南.md

# 泰豪电源 AI 数智化平台 - 前端完整指南

## 📖 目录

1. [技术架构](#1-技术架构)
2. [共享组件方案](#2-共享组件方案)
3. [快速开始](#3-快速开始)
4. [开发指南](#4-开发指南)
5. [构建部署](#5-构建部署)
6. [常见问题](#6-常见问题)

---

## 1. 技术架构

### 1.1 技术栈

**前端框架**
- Vue 3.5+ (`<script setup>`)
- TypeScript 5.7+
- Vite 6.0+
- Pinia 2.2+
- Element Plus 2.9+

**工程化**
- pnpm 9.0+ Monorepo
- Turborepo 2.0+ 构建加速
- unplugin-auto-import 自动导入
- ESLint 9 + Prettier

**通信层**
- ofetch (替代 Axios)
- @vueuse/core

### 1.2 项目结构

```
urbanLifelineWeb/
├── packages/
│   ├── shared/                  # 共享包 ⭐核心
│   │   ├── components/          # UI组件
│   │   ├── utils/               # 工具函数
│   │   ├── api/                 # API封装
│   │   └── composables/         # 组合函数
│   ├── portal/                  # 主应用
│   ├── app-bidding/             # 招投标应用
│   ├── app-customer-service/    # 智能客服应用
│   └── app-knowledge/           # 知识协同应用
├── pnpm-workspace.yaml
└── turbo.json
```

---

## 2. 共享组件方案

### 2.1 核心理念

**业务应用只需关心 `@shared/*` 导入，无需关心底层依赖（Vue、Element Plus 等）**

```
业务应用: import { UlTable } from '@shared/components'
              ↓
浏览器: GET /shared/components.js
              ↓
共享服务: 返回包含 Vue + Element Plus 的 ES Module
              ↓
✅ 所有应用共用，浏览器缓存
```

### 2.2 配置方式

**业务应用配置（极简）**

```html
<!-- index.html -->
<script type="importmap">
{
  "imports": {
    "@shared/components": "/shared/components.js",
    "@shared/utils": "/shared/utils.js",
    "@shared/api": "/shared/api.js"
  }
}
</script>
```

**Vue 组件使用**

```vue
<script setup lang="ts">
// ✅ 直接从 HTTP URL 加载
import { UlTable } from '@shared/components'
import { http } from '@shared/utils'
import { authApi } from '@shared/api'
import { useTable } from '@shared/composables'

const { loading, tableData } = useTable({
  fetchData: authApi.getUserList
})
</script>

<template>
  <UlTable :data="tableData" :loading="loading" />
</template>
```

### 2.3 优势

| 特性 | 传统方式 | Import Maps 方案 |
|------|---------|-----------------|
| 代码共享 | ❌ 每个应用打包一份 | ✅ 所有应用共用一份 |
| 构建体积 | ❌ 重复打包 | ✅ 减少 30-50% |
| 依赖管理 | ❌ 每个应用配置 | ✅ 共享服务统一管理 |
| 版本升级 | ❌ 所有应用改 | ✅ 只改共享服务 |
| 浏览器缓存 | ⚠️ 独立缓存 | ✅ 统一缓存 |

---

## 3. 快速开始

### 3.1 Docker 环境（推荐）

```bash
# 1. 启动所有服务
make up

# 2. 查看状态
make ps

# 3. 访问应用
open http://localhost
```

**访问地址**
- 主应用: http://localhost/
- 招投标: http://localhost/bidding
- 智能客服: http://localhost/customer-service
- 共享组件: http://localhost/shared/components.js
- API网关: http://localhost/api
- Nacos: http://localhost/nacos

### 3.2 本地开发

```bash
# 1. 安装依赖
pnpm install

# 2. 启动所有应用
pnpm dev

# 或启动单个应用
pnpm --filter portal dev
pnpm --filter app-bidding dev
```

---

## 4. 开发指南

### 4.1 创建页面

```vue
<!-- packages/portal/src/views/UserList.vue -->
<script setup lang="ts">
import { UlTable } from '@shared/components'
import { authApi } from '@shared/api'
import { useTable } from '@shared/composables'

interface User {
  id: string
  username: string
  email: string
}

const { loading, tableData, pagination, handlePageChange } = useTable<User>({
  fetchData: authApi.getUserList
})

const columns = [
  { prop: 'username', label: '用户名', minWidth: 150 },
  { prop: 'email', label: '邮箱', minWidth: 200 }
]
</script>

<template>
  <div class="user-list">
    <UlTable
      :data="tableData"
      :columns="columns"
      :loading="loading"
      :pagination="pagination"
      @page-change="handlePageChange"
    />
  </div>
</template>
```

### 4.2 API 调用

```typescript
// 使用封装的 API
import { authApi, systemApi } from '@shared/api'

// GET 请求
const users = await authApi.getUserList({ page: 1, size: 10 })

// POST 请求
await authApi.createUser({ username: 'test', email: 'test@example.com' })

// 直接使用 http
import { http } from '@shared/utils'
const data = await http.get('/custom/endpoint')
```

### 4.3 状态管理

```typescript
// store/user.ts
import { defineStore } from 'pinia'
import { ref, computed } from 'vue'
import { authApi } from '@shared/api'

export const useUserStore = defineStore('user', () => {
  // State
  const userInfo = ref(null)
  const permissions = ref([])
  
  // Getters
  const isLoggedIn = computed(() => !!userInfo.value)
  
  // Actions
  const login = async (loginData) => {
    const res = await authApi.login(loginData)
    userInfo.value = res.userInfo
    permissions.value = res.permissions
  }
  
  return { userInfo, permissions, isLoggedIn, login }
})
```

### 4.4 路由配置

```typescript
// router/index.ts
import { createRouter, createWebHistory } from 'vue-router'

const routes = [
  {
    path: '/',
    component: () => import('@/layouts/MainLayout.vue'),
    children: [
      {
        path: 'home',
        component: () => import('@/views/home/index.vue'),
        meta: { title: '首页' }
      }
    ]
  }
]

const router = createRouter({
  history: createWebHistory(),
  routes
})

export default router
```

### 4.5 常用命令

```bash
# 查看日志
make logs-portal       # 主应用日志
make logs-gateway      # 网关日志
make logs-shared       # 共享包日志

# 重启服务
make restart-portal    # 重启主应用
make restart           # 重启所有服务

# 进入容器
make shell-portal      # 进入容器调试

# 数据库
make db                # 连接数据库
make db-init           # 初始化数据
```

---

## 5. 构建部署

### 5.1 本地构建

```bash
# 构建所有应用
pnpm build

# 构建单个应用
pnpm --filter portal build
pnpm --filter shared build

# 预览
pnpm preview
```

### 5.2 部署到生产

**方式1: Docker 部署**

```bash
# 构建生产镜像
docker build -t urban-lifeline-web .

# 运行
docker run -p 80:80 urban-lifeline-web
```

**方式2: CDN 部署**

```bash
# 部署共享包到 CDN
cd packages/shared
pnpm build
ossutil cp -r dist/esm/ oss://cdn/shared/v1.0.0/

# 部署业务应用
cd packages/portal
pnpm build
ossutil cp -r dist/ oss://cdn/portal/
```

**方式3: Nginx 静态部署**

```nginx
server {
    listen 80;
    server_name taihao.com;
    
    # 主应用
    location / {
        root /var/www/portal/dist;
        try_files $uri $uri/ /index.html;
    }
    
    # 共享包
    location /shared/ {
        root /var/www/shared/dist;
        add_header Access-Control-Allow-Origin "*";
        expires 1y;
    }
    
    # API 代理
    location /api/ {
        proxy_pass http://gateway:8080/;
    }
}
```

### 5.3 环境变量

```bash
# .env.development
VITE_API_BASE_URL=http://localhost/api
VITE_SHARED_URL=http://localhost/shared

# .env.production
VITE_API_BASE_URL=https://api.taihao.com/api
VITE_SHARED_URL=https://cdn.taihao.com/shared/v1.0.0
```

### 5.4 CI/CD

```yaml
# .github/workflows/deploy.yml
name: Deploy

on:
  push:
    branches: [main]

jobs:
  build-and-deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: pnpm/action-setup@v4
        with:
          version: 9
      
      - name: Build
        run: pnpm install && pnpm build
      
      - name: Deploy
        run: ./scripts/deploy-production.sh
```

---

## 6. 常见问题

### 6.1 为什么使用 Import Maps？

**优势**：
- ✅ 浏览器原生支持，无需额外库
- ✅ 真正的运行时共享
- ✅ 开发体验好（支持 HMR）
- ✅ 减小构建体积

**对比 Module Federation**：
- Import Maps 更简单，配置少
- Module Federation 功能更强大，但复杂
- 两者可以结合使用

### 6.2 如何处理 TypeScript 类型？

```typescript
// packages/portal/src/types/shared.d.ts
declare module '@shared/components' {
  export * from '../../../shared/src/components'
}

declare module '@shared/utils' {
  export * from '../../../shared/src/utils'
}
```

### 6.3 如何更新共享组件？

```bash
# 1. 修改共享组件代码
vim packages/shared/src/components/UlTable/index.vue

# 2. 重启共享服务（HMR 自动生效）
make restart-shared

# 3. 浏览器刷新，所有应用自动获得最新版本
```

### 6.4 生产环境如何缓存？

```nginx
# Nginx 配置
location /shared/ {
    # 基于版本号的长期缓存
    expires 1y;
    add_header Cache-Control "public, immutable";
}

# HTML 不缓存
location ~* \.html$ {
    add_header Cache-Control "no-cache";
}
```

### 6.5 如何调试共享组件？

```bash
# 方式1: 查看网络请求
浏览器 F12 → Network → 筛选 JS → 查看 /shared/components.js

# 方式2: 查看日志
make logs-shared

# 方式3: 进入容器
make shell-shared
```

### 6.6 为什么不用 Webpack？

Vite 优势：
- ⚡ 开发启动快（秒级）
- 🔥 HMR 更快
- 📦 生产构建基于 Rollup（体积更小）
- 🎯 原生 ES Module 支持

### 6.7 如何处理样式？

```vue
<!-- 组件级样式 -->
<style scoped>
.ul-table {
  width: 100%;
}
</style>

<!-- 全局样式 -->
<style>
@import '@shared/styles/variables.scss';
</style>
```

共享包会自动处理 CSS 提取和分割。

### 6.8 如何添加新的业务应用？

```bash
# 1. 复制现有应用作为模板
cp -r packages/portal packages/app-newapp

# 2. 修改 package.json
{
  "name": "@apps/newapp",
  "scripts": {
    "dev": "vite --port 3003"
  }
}

# 3. 添加到 pnpm-workspace.yaml（已自动包含）

# 4. 启动
pnpm --filter app-newapp dev
```

---

## 附录

### A. 常用脚本

```bash
# Makefile 命令
make up          # 启动
make down        # 停止
make logs        # 日志
make ps          # 状态
make restart     # 重启
make clean       # 清理

# pnpm 命令
pnpm dev         # 开发
pnpm build       # 构建
pnpm preview     # 预览
pnpm lint        # 检查
pnpm format      # 格式化
```

### B. 目录说明

```
urbanLifeline/
├── urbanLifelineServ/    # 后端（Java Spring Boot）
├── urbanLifelineWeb/     # 前端（Vue 3 Monorepo）
├── docker-compose.dev.yml # Docker 开发环境
├── Makefile              # 快捷命令
└── docs/                 # 文档
    └── 前端完整指南.md   # 📖 本文档
```

### C. 技术支持

- 项目文档：`/docs`
- 问题反馈：GitHub Issues
- 开发规范：ESLint + Prettier
- 提交规范：Conventional Commits

---

**Happy Coding! 🚀**

*最后更新：2025-12-02*