Dream-MachineProcurementList/DEPLOYMENT.md

# 部署指南

本文档详细说明如何在不同环境中部署 Dream-Machine 采购清单管理系统。

## 🚀 快速部署

### 使用 Makefile（推荐）

```bash
# 完整部署检查流程
make pre-deploy

# 或分步执行
make clean-install  # 清理并安装依赖
make lint          # 代码质量检查
make build         # 构建生产版本
make preview       # 本地预览测试
```

## 🏗 开发环境设置

### 系统要求

- **操作系统**: Windows 10+, macOS 10.15+, Ubuntu 18.04+
- **Node.js**: v18.0.0 或更高版本
- **内存**: 最少 4GB RAM
- **存储**: 至少 1GB 可用空间

### 开发环境启动

1. **克隆项目**
   ```bash
   git clone <repository-url>
   cd dream-machine-purchase-list
   ```

2. **环境检查**
   ```bash
   make info  # 查看系统信息
   ```

3. **启动开发服务器**
   ```bash
   make dev   # 自动安装依赖并启动
   ```

4. **访问应用**
   - 开发服务器: http://localhost:3003
   - 网络访问: http://[你的IP]:3003

### 开发环境配置

#### Vite 配置
```javascript
// vite.config.ts 关键配置
export default defineConfig({
  server: {
    port: 3003,        // 开发服务器端口
    host: true,        // 允许外部访问
    open: true,        // 自动打开浏览器
    hmr: {
      port: 3003       // 热重载端口
    }
  }
})
```

#### 环境变量
```bash
# .env.local (可选)
VITE_APP_TITLE="Dream-Machine 采购清单"
VITE_APP_VERSION="1.0.0"
```

## 🏭 生产环境部署

### 构建优化

1. **生产构建**
   ```bash
   make build
   ```

2. **构建文件分析**
   ```bash
   make size-check  # 检查文件大小
   ```

3. **生产预览**
   ```bash
   make preview     # 本地预览生产版本
   ```

### 静态托管部署

#### Netlify 部署

1. **构建设置**
   ```yaml
   # netlify.toml
   [build]
     publish = "dist"
     command = "npm run build"
   
   [build.environment]
     NODE_VERSION = "18"
   
   [[redirects]]
     from = "/*"
     to = "/index.html"
     status = 200
   ```

2. **部署步骤**
   ```bash
   # 本地构建
   make build
   
   # 上传 dist 目录到 Netlify
   ```

#### Vercel 部署

1. **配置文件**
   ```json
   {
     "buildCommand": "npm run build",
     "outputDirectory": "dist",
     "framework": "vite"
   }
   ```

2. **自动部署**
   - 连接 GitHub 仓库
   - 自动检测 Vite 项目
   - 推送代码自动部署

#### GitHub Pages 部署

1. **配置 vite.config.ts**
   ```javascript
   export default defineConfig({
     base: '/your-repo-name/',
     build: {
       outDir: 'dist'
     }
   })
   ```

2. **GitHub Actions 配置**
   ```yaml
   # .github/workflows/deploy.yml
   name: Deploy to GitHub Pages
   
   on:
     push:
       branches: [ main ]
   
   jobs:
     deploy:
       runs-on: ubuntu-latest
       steps:
         - uses: actions/checkout@v3
         - uses: actions/setup-node@v3
           with:
             node-version: '18'
         - run: npm ci
         - run: npm run build
         - uses: peaceiris/actions-gh-pages@v3
           with:
             github_token: ${{ secrets.GITHUB_TOKEN }}
             publish_dir: ./dist
   ```

### 服务器部署

#### Nginx 配置

```nginx
server {
    listen 80;
    server_name your-domain.com;
    root /var/www/dream-machine/dist;
    index index.html;

    # 单页应用路由支持
    location / {
        try_files $uri $uri/ /index.html;
    }

    # 静态资源缓存
    location /assets/ {
        expires 1y;
        add_header Cache-Control "public, immutable";
    }

    # Gzip 压缩
    gzip on;
    gzip_types text/plain text/css application/json application/javascript text/xml application/xml application/xml+rss text/javascript;
}
```

#### Docker 部署

1. **Dockerfile**
   ```dockerfile
   # 多阶段构建
   FROM node:18-alpine as builder
   
   WORKDIR /app
   COPY package*.json ./
   RUN npm ci --only=production
   
   COPY . .
   RUN npm run build
   
   # 生产镜像
   FROM nginx:alpine
   COPY --from=builder /app/dist /usr/share/nginx/html
   COPY nginx.conf /etc/nginx/nginx.conf
   
   EXPOSE 80
   CMD ["nginx", "-g", "daemon off;"]
   ```

2. **构建和运行**
   ```bash
   # 构建镜像
   docker build -t dream-machine-app .
   
   # 运行容器
   docker run -p 80:80 dream-machine-app
   ```

## 🔧 性能优化

### 构建优化

1. **Bundle 分析**
   ```bash
   # 安装分析工具
   npm install --save-dev rollup-plugin-visualizer
   
   # 生成分析报告
   npm run build
   ```

2. **代码分割**
   ```javascript
   // 路由级别代码分割
   const HomePage = lazy(() => import('@/pages/HomePage'))
   const NotFoundPage = lazy(() => import('@/pages/NotFoundPage'))
   ```

3. **资源优化**
   ```javascript
   // vite.config.ts
   export default defineConfig({
     build: {
       rollupOptions: {
         output: {
           manualChunks: {
             vendor: ['react', 'react-dom'],
             ui: ['@radix-ui/react-dialog', '@radix-ui/react-select']
           }
         }
       }
     }
   })
   ```

### 运行时优化

1. **图片优化**
   - 使用 WebP 格式
   - 启用懒加载
   - 设置合适的尺寸

2. **缓存策略**
   ```javascript
   // Service Worker 缓存
   const CACHE_NAME = 'dream-machine-v1'
   const urlsToCache = [
     '/',
     '/static/css/main.css',
     '/static/js/main.js'
   ]
   ```

## 📊 监控和维护

### 错误监控

1. **错误边界**
   ```jsx
   class ErrorBoundary extends Component {
     componentDidCatch(error, errorInfo) {
       console.error('Error caught:', error, errorInfo)
     }
   }
   ```

2. **性能监控**
   ```javascript
   // 性能指标收集
   import { getCLS, getFID, getFCP, getLCP, getTTFB } from 'web-vitals'
   
   getCLS(console.log)
   getFID(console.log)
   getFCP(console.log)
   getLCP(console.log)
   getTTFB(console.log)
   ```

### 健康检查

```bash
# 部署后检查清单
make test-flow    # 完整测试流程

# 手动检查项目
- [ ] 页面正常加载
- [ ] 数据导入导出功能正常
- [ ] 响应式设计正常
- [ ] 打印功能正常
- [ ] 数据持久化正常
```

## 🔒 安全考虑

### 内容安全策略

```html
<meta http-equiv="Content-Security-Policy" 
      content="default-src 'self'; 
               script-src 'self' 'unsafe-inline'; 
               style-src 'self' 'unsafe-inline';
               img-src 'self' data: https:;">
```

### HTTPS 配置

```nginx
server {
    listen 443 ssl http2;
    ssl_certificate /path/to/certificate.crt;
    ssl_certificate_key /path/to/private.key;
    
    # 安全头
    add_header X-Frame-Options "SAMEORIGIN" always;
    add_header X-Content-Type-Options "nosniff" always;
    add_header Referrer-Policy "no-referrer-when-downgrade" always;
}
```

## 🚨 故障排除

### 常见问题

1. **构建失败**
   ```bash
   make clean-install  # 清理重装
   make lint          # 检查代码
   ```

2. **内存不足**
   ```bash
   # 增加 Node.js 内存限制
   export NODE_OPTIONS="--max-old-space-size=4096"
   npm run build
   ```

3. **端口冲突**
   ```bash
   # 检查端口占用
   lsof -i :3003
   
   # 杀死进程
   kill -9 <PID>
   ```

### 调试工具

```bash
# 构建详细日志
npm run build -- --debug

# 网络请求调试
npm run dev -- --host 0.0.0.0 --debug

# 内存使用分析
node --inspect npm run build
```

---

需要帮助？查看 [README.md](README.md) 或创建 Issue。