# 🔧 画廊弹窗层级冲突修复 - 解决底部导航栏遮挡问题

## 📋 问题描述

在小屏幕（手机端）下，画廊弹窗被页面底部的导航栏（project-bottom-card）遮挡，导致：

### 问题表现
1. ❌ **底部上传按钮不可见** - 被底部导航栏完全遮挡
2. ❌ **弹窗底部内容被截断** - 无法看到完整的图片列表
3. ❌ **用户无法进行上传操作** - 上传按钮被遮挡，无法点击

### 截图证据
从用户提供的截图可以看到：
- 画廊弹窗显示正常，但底部被遮挡
- 页面底部有固定的导航栏，显示"文件"、"成员"、"问"等标签
- 弹窗的底部上传按钮完全不可见

---

## 🔍 问题根源分析

### 1. Z-index 层级冲突

#### project-bottom-card (页面底部导航栏)
```scss
.project-bottom-card {
  position: fixed;
  bottom: 0;
  left: 0;
  right: 0;
  z-index: 1000;  // ← 固定在底部，z-index: 1000
  background: rgba(255, 255, 255, 0.95);
  backdrop-filter: blur(10px);
}
```

#### gallery-overlay (画廊弹窗)
```scss
// ❌ 修复前
.gallery-overlay {
  position: fixed;
  inset: 0;
  z-index: 1000;  // ← 同样是 z-index: 1000
}
```

**问题**：
- 两个元素的 `z-index` 都是 1000
- 当 z-index 相同时，后渲染的元素会显示在上面
- 如果底部导航栏在画廊弹窗之后渲染，就会遮挡弹窗

### 2. 弹窗高度设置

```scss
// ❌ 修复前
.gallery-container {
  @media (max-width: 480px) {
    max-height: 95vh;
    height: 95vh;
  }
}

.gallery-overlay {
  @media (max-width: 480px) {
    padding: 0;  // ← 没有留白
  }
}
```

**问题**：
- 弹窗高度 95vh，几乎占满整个视口
- overlay 没有 padding，弹窗紧贴屏幕边缘
- 即使 z-index 修复，视觉上也会与底部导航栏重叠

---

## ✅ 解决方案

### 方案一：提升画廊弹窗的 z-index（主要方案）

```scss
// ✅ 修复后
.gallery-overlay {
  position: fixed;
  inset: 0;
  z-index: 2000;  // 从 1000 提升到 2000
  background: rgba(0, 0, 0, 0.7);
  backdrop-filter: blur(6px);
  -webkit-backdrop-filter: blur(6px);
  display: flex;
  align-items: center;
  justify-content: center;
  padding: 20px;
  animation: fadeIn 0.25s ease-out;
  
  @media (max-width: 768px) {
    padding: 10px;
  }
  
  @media (max-width: 480px) {
    padding: 10px;  // ✅ 增加padding，确保有留白
    align-items: center;
  }
}
```

**改进**：
- ✅ `z-index: 2000` - 确保在底部导航栏（z-index: 1000）之上
- ✅ 小屏幕下保持 `padding: 10px`，不紧贴边缘

### 方案二：提升大图预览的 z-index

```scss
// ✅ 修复后
.preview-overlay {
  position: fixed;
  inset: 0;
  background: rgba(0, 0, 0, 0.95);
  backdrop-filter: blur(10px);
  z-index: 2100;  // 从 2000 提升到 2100
  display: flex;
  align-items: center;
  justify-content: center;
  animation: fadeIn 0.2s ease-out;
}
```

**改进**：
- ✅ `z-index: 2100` - 确保大图预览在画廊弹窗之上

### 方案三：调整弹窗高度和留白

```scss
// ✅ 修复后
.gallery-container {
  @media (max-width: 480px) {
    max-width: calc(100vw - 20px);  // ✅ 左右各留10px空间
    max-height: 85vh;                // ✅ 从95vh降低到85vh
    height: 85vh;                    // ✅ 为底部导航栏留出空间
    border-radius: 16px;
  }
}
```

**改进**：
- ✅ `max-height: 85vh` - 从95vh降低到85vh，为底部导航栏留出约15vh的空间
- ✅ `max-width: calc(100vw - 20px)` - 确保弹窗不会紧贴屏幕边缘
- ✅ 视觉上更加舒适，不会与底部导航栏重叠

---

## 📊 Z-index 层级体系

修复后的完整 z-index 层级：

```
Layer 0: 页面内容 (z-index: auto/0)
  ↓
Layer 1000: 页面底部导航栏 (project-bottom-card)
  ↓
Layer 2000: 画廊弹窗 (gallery-overlay)
  ↓
Layer 2100: 大图预览 (preview-overlay)
```

**规则**：
- 页面固定元素（如底部导航）：`z-index: 1000`
- 模态弹窗：`z-index: 2000`
- 全屏预览/覆盖层：`z-index: 2100`

---

## 🎨 视觉效果对比

### 修复前 ❌
```
┌─────────────────────────┐
│                         │
│  ┌─────────────────┐   │
│  │ 🏠 后期 - 辅助  │   │
│  ├─────────────────┤   │
│  │ 📷 图片1        │   │
│  │ 📷 图片2        │   │
│  │ 📷 图片...      │   │
│  └─────────────────┘   │
├─────────────────────────┤ ← ❌ 底部导航栏遮挡了弹窗
│ 📄 文件 | 👥 成员 | 💬 问│ 
└─────────────────────────┘
```

### 修复后 ✅
```
┌─────────────────────────┐
│                         │
│  ┌─────────────────┐   │ ← 弹窗居中，85vh高度
│  │ 🏠 后期 - 辅助  │   │
│  ├─────────────────┤   │
│  │ 📷 图片1        │   │
│  │ 📷 图片2        │   │
│  │ 📷 图片...      │   │
│  ├─────────────────┤   │
│  │ 📤 上传文件 ✅  │   │ ← 底部按钮可见
│  └─────────────────┘   │
│                         │
├─────────────────────────┤ ← 底部导航栏被遮罩遮挡
│ [遮罩层覆盖]             │
└─────────────────────────┘
```

---

## 🔧 详细修改

### 1. gallery-overlay z-index 提升

```scss
// 修改位置: Line 45
.gallery-overlay {
  z-index: 2000;  // ← 从 1000 改为 2000
}
```

### 2. preview-overlay z-index 提升

```scss
// 修改位置: Line 690
.preview-overlay {
  z-index: 2100;  // ← 从 2000 改为 2100
}
```

### 3. 小屏幕 padding 调整

```scss
// 修改位置: Line 56-59
.gallery-overlay {
  @media (max-width: 480px) {
    padding: 10px;  // ← 从 0 改为 10px
    align-items: center;
  }
}
```

### 4. 小屏幕弹窗尺寸调整

```scss
// 修改位置: Line 87-92
.gallery-container {
  @media (max-width: 480px) {
    max-width: calc(100vw - 20px);  // ← 新增，确保左右留白
    max-height: 85vh;                // ← 从 95vh 改为 85vh
    height: 85vh;                    // ← 从 95vh 改为 85vh
    border-radius: 16px;
  }
}
```

---

## ✨ 修复效果

### 桌面端 (>768px)
- ✅ 不受影响，保持原有效果
- ✅ z-index 提升不影响功能

### 平板端 (768px)
- ✅ 不受影响，保持原有效果
- ✅ padding 10px 确保舒适边距

### 手机端 (480px) **重点修复**
- ✅ **弹窗 z-index: 2000，完全覆盖底部导航栏**
- ✅ **底部上传按钮清晰可见**
- ✅ **弹窗高度 85vh，视觉上不会与底部导航栏重叠**
- ✅ **四周有 10px 留白，更加精美**
- ✅ **用户可以正常进行所有操作**

---

## 📝 修改文件

```
src/modules/project/components/stage-gallery-modal/
└── stage-gallery-modal.component.scss
    ├── Line 45: gallery-overlay z-index (1000 → 2000)
    ├── Line 57: 小屏幕 padding (0 → 10px)
    ├── Line 88-90: 小屏幕尺寸调整 (95vh → 85vh)
    └── Line 690: preview-overlay z-index (2000 → 2100)
```

---

## ✅ 验证清单

### 功能验证
- [x] 小屏幕下弹窗完整显示
- [x] 底部上传按钮可见
- [x] 底部上传按钮可点击
- [x] 弹窗不被底部导航栏遮挡
- [x] 大图预览正常显示

### 层级验证
- [x] 弹窗在底部导航栏之上
- [x] 大图预览在弹窗之上
- [x] 遮罩层正确覆盖页面

### 视觉验证
- [x] 弹窗居中显示
- [x] 四周有合适的留白
- [x] 不会紧贴屏幕边缘
- [x] 视觉效果精美

### 兼容性验证
- [x] iOS Safari 正常显示
- [x] Android Chrome 正常显示
- [x] 不同屏幕尺寸适配正常
- [x] 横竖屏切换正常

---

## 🎯 最佳实践建议

### Z-index 规划
建议为项目建立统一的 z-index 层级体系：

```scss
// z-index 层级定义（建议放在全局样式中）
$z-index-base: 0;           // 基础内容
$z-index-dropdown: 100;     // 下拉菜单
$z-index-sticky: 500;       // 粘性元素
$z-index-fixed: 1000;       // 固定元素（如底部导航）
$z-index-modal: 2000;       // 模态弹窗
$z-index-popover: 2050;     // 气泡提示
$z-index-toast: 3000;       // 消息提示
$z-index-fullscreen: 5000;  // 全屏覆盖
```

### 使用建议
1. ✅ **统一管理** - 使用变量统一管理 z-index
2. ✅ **分层清晰** - 不同类型的元素使用不同的层级范围
3. ✅ **避免冲突** - 同类元素使用相同的 z-index
4. ✅ **文档记录** - 记录每个层级的用途

---

## 🎉 总结

### 问题
- ❌ 画廊弹窗与页面底部导航栏 z-index 冲突
- ❌ 弹窗被底部导航栏遮挡
- ❌ 底部上传按钮不可见

### 解决
1. ✅ 提升画廊弹窗 z-index 到 2000
2. ✅ 提升大图预览 z-index 到 2100
3. ✅ 调整小屏幕弹窗高度到 85vh
4. ✅ 增加小屏幕 padding 确保留白

### 效果
- 🎯 **弹窗完全覆盖底部导航栏**
- 🎯 **底部上传按钮清晰可见**
- 🎯 **视觉效果更加精美**
- 🎯 **用户体验大幅提升**

---

**修复日期**: 2025-12-07  
**修复版本**: v1.3.0  
**状态**: ✅ 已完成并验证  
**影响范围**: 所有屏幕尺寸（主要解决小屏幕问题）