# Z-Index 层级管理规范

## 当前问题分析

经过代码审查，发现以下z-index混乱问题：
1. **unified-toolbar (1000)** 遮挡了弹窗和popover
2. **popup/popover (1000)** 与toolbar使用相同层级
3. **AI弹窗 (2000)** 被unified-toolbar遮挡
4. **多个组件使用1000** 导致层级冲突
5. **临时修复层出现9999、10000等随意值**

## Z-Index 层级规范

采用**分层设计**，每层预留100个单位空间：

```
┌─────────────────────────────────────────────┐
│ Layer 9: Critical Overlays (9000+)         │  全局最高层
├─────────────────────────────────────────────┤
│ Layer 8: Image Viewer (8000-8999)          │  图片查看器
├─────────────────────────────────────────────┤
│ Layer 7: Auth Dialogs (7000-7999)          │  认证弹窗
├─────────────────────────────────────────────┤
│ Layer 6: Notifications (6000-6999)         │  通知提示
├─────────────────────────────────────────────┤
│ Layer 5: Modals (5000-5999)                │  模态弹窗
├─────────────────────────────────────────────┤
│ Layer 4: Drawers/Panels (4000-4999)        │  抽屉/面板
├─────────────────────────────────────────────┤
│ Layer 3: Popovers (3000-3999)              │  弹出层
├─────────────────────────────────────────────┤
│ Layer 2: Toolbars (2000-2999)              │  工具栏
├─────────────────────────────────────────────┤
│ Layer 1: Canvas Elements (1000-1999)       │  画布元素
├─────────────────────────────────────────────┤
│ Layer 0: Base (0-999)                      │  基础层
└─────────────────────────────────────────────┘
```

### 详细层级定义

#### Layer 0: Base (0-999)
- **0-99**: 默认文档流
- **100-199**: 画布内部元素（selection, drag handlers）
- **200-299**: 预留

#### Layer 1: Canvas Elements (1000-1999)
- **1000-1099**: 画布装饰元素（网格、辅助线）
- **1100-1199**: 临时元素（resize handles, anchors）
- **1200-1299**: 预留

#### Layer 2: Toolbars (2000-2999)
- **2000**: unified-toolbar (主工具栏)
- **2010**: creation-toolbar
- **2020**: popup-toolbar
- **2030**: zoom-toolbar
- **2040**: app-toolbar
- **2050**: pencil-mode-toolbar
- **2100-2199**: 其他工具栏

#### Layer 3: Popovers (3000-3999)
- **3000**: 工具栏popover (freehand-panel, shape-picker, arrow-picker)
- **3010**: feedback-button popover
- **3020**: zoom-toolbar popover
- **3030**: app-toolbar popover
- **3100-3199**: 其他popover
- **3500**: Tooltip (始终在popover之上)

#### Layer 4: Drawers/Panels (4000-4999)
- **4000**: task-queue-panel
- **4010**: chat-drawer
- **4020**: generation-history drawer
- **4100-4199**: 其他侧边栏

#### Layer 5: Modals (5000-5999)
- **5000**: 普通Dialog (ttd-dialog)
- **5010**: clean-confirm
- **5020**: settings-dialog
- **5100**: AI Image Generation Dialog (react-rnd窗口)
- **5110**: AI Video Generation Dialog (react-rnd窗口)
- **5200-5299**: Dialog内部元素（header, footer等）
- **5500-5599**: Dialog内的popover/select

#### Layer 6: Notifications (6000-6999)
- **6000**: active-task-warning
- **6100**: Toast通知
- **6200**: 成功/错误提示

#### Layer 7: Auth Dialogs (7000-7999)
- **7000**: API key auth dialog
- **7100**: 登录/注册弹窗

#### Layer 8: Image Viewer (8000-8999)
- **8000**: Image viewer overlay
- **8010**: Image viewer toolbar
- **8020**: Image viewer close button

#### Layer 9: Critical Overlays (9000+)
- **9000**: Loading spinner (全屏)
- **9100**: 系统级错误提示
- **9999**: 开发调试层

## 实施规则

### 1. 使用CSS变量
```scss
// styles/variables.scss
$z-index: (
  // Layer 0: Base
  'canvas-internal': 100,
  
  // Layer 1: Canvas Elements  
  'canvas-decoration': 1000,
  'canvas-temporary': 1100,
  
  // Layer 2: Toolbars
  'unified-toolbar': 2000,
  'creation-toolbar': 2010,
  'popup-toolbar': 2020,
  'zoom-toolbar': 2030,
  'app-toolbar': 2040,
  'pencil-toolbar': 2050,
  
  // Layer 3: Popovers
  'popover': 3000,
  'popover-feedback': 3010,
  'popover-zoom': 3020,
  'popover-app': 3030,
  'tooltip': 3500,
  
  // Layer 4: Drawers
  'task-queue-panel': 4000,
  'chat-drawer': 4010,
  'generation-history': 4020,
  
  // Layer 5: Modals
  'dialog': 5000,
  'dialog-clean-confirm': 5010,
  'dialog-settings': 5020,
  'dialog-ai-image': 5100,
  'dialog-ai-video': 5110,
  'dialog-inner': 5200,
  'dialog-popover': 5500,
  
  // Layer 6: Notifications
  'active-task-warning': 6000,
  'toast': 6100,
  'message': 6200,
  
  // Layer 7: Auth
  'auth-dialog': 7000,
  
  // Layer 8: Image Viewer
  'image-viewer': 8000,
  'image-viewer-toolbar': 8010,
  'image-viewer-close': 8020,
  
  // Layer 9: Critical
  'loading': 9000,
  'system-error': 9100,
  'debug': 9999,
);

// 辅助函数
@function z($layer) {
  @return map-get($z-index, $layer);
}
```

### 2. TypeScript常量
```typescript
// constants/z-index.ts
export const Z_INDEX = {
  // Layer 0: Base
  CANVAS_INTERNAL: 100,
  
  // Layer 1: Canvas Elements
  CANVAS_DECORATION: 1000,
  CANVAS_TEMPORARY: 1100,
  
  // Layer 2: Toolbars
  UNIFIED_TOOLBAR: 2000,
  CREATION_TOOLBAR: 2010,
  POPUP_TOOLBAR: 2020,
  ZOOM_TOOLBAR: 2030,
  APP_TOOLBAR: 2040,
  PENCIL_TOOLBAR: 2050,
  
  // Layer 3: Popovers
  POPOVER: 3000,
  POPOVER_FEEDBACK: 3010,
  POPOVER_ZOOM: 3020,
  POPOVER_APP: 3030,
  TOOLTIP: 3500,
  
  // Layer 4: Drawers
  TASK_QUEUE_PANEL: 4000,
  CHAT_DRAWER: 4010,
  GENERATION_HISTORY: 4020,
  
  // Layer 5: Modals
  DIALOG: 5000,
  DIALOG_CLEAN_CONFIRM: 5010,
  DIALOG_SETTINGS: 5020,
  DIALOG_AI_IMAGE: 5100,
  DIALOG_AI_VIDEO: 5110,
  DIALOG_INNER: 5200,
  DIALOG_POPOVER: 5500,
  
  // Layer 6: Notifications
  ACTIVE_TASK_WARNING: 6000,
  TOAST: 6100,
  MESSAGE: 6200,
  
  // Layer 7: Auth
  AUTH_DIALOG: 7000,
  
  // Layer 8: Image Viewer
  IMAGE_VIEWER: 8000,
  IMAGE_VIEWER_TOOLBAR: 8010,
  IMAGE_VIEWER_CLOSE: 8020,
  
  // Layer 9: Critical
  LOADING: 9000,
  SYSTEM_ERROR: 9100,
  DEBUG: 9999,
} as const;

export type ZIndexKey = keyof typeof Z_INDEX;
```

### 3. 使用示例

#### SCSS中使用
```scss
@import 'styles/variables';

.unified-toolbar {
  z-index: z('unified-toolbar'); // 2000
}

.my-popover {
  z-index: z('popover'); // 3000
}
```

#### TSX中使用
```tsx
import { Z_INDEX } from '@/constants/z-index';

<Rnd style={{ zIndex: Z_INDEX.DIALOG_AI_IMAGE }}>
  {/* AI Image Dialog */}
</Rnd>

<PopoverContent style={{ zIndex: Z_INDEX.POPOVER }}>
  {/* Popover content */}
</PopoverContent>
```

## 禁止事项

❌ **禁止随意使用魔术数字**
```scss
// ❌ 错误
.my-component {
  z-index: 9999; // 不要使用随意的大数字
}

.another {
  z-index: 10001; // 临时修复会破坏层级体系
}
```

✅ **正确做法**
```scss
// ✅ 正确
@import 'styles/variables';

.my-component {
  z-index: z('dialog'); // 使用预定义的层级
}
```

❌ **禁止在同一层级随意加减**
```scss
// ❌ 错误
.toolbar {
  z-index: 2000;
}
.toolbar-fixed {
  z-index: 2001; // 破坏了层级结构
}
```

✅ **正确做法**
```scss
// ✅ 正确 - 如果需要层内排序，使用DOM顺序或position
.toolbar {
  z-index: z('unified-toolbar');
}
.toolbar-fixed {
  z-index: z('unified-toolbar');
  position: relative; // DOM顺序决定层级
}
```

## Code Review检查清单

在代码审查时，检查以下项目：

- [ ] 所有z-index使用都通过变量/常量引用
- [ ] 没有硬编码的魔术数字
- [ ] 新增组件的z-index符合层级规范
- [ ] 没有超过9999的z-index值
- [ ] Popover/Tooltip使用对应层级(3000+)
- [ ] Dialog/Modal使用对应层级(5000+)
- [ ] 临时修复已转换为规范用法

## 迁移计划

### Phase 1: 创建变量文件
- [ ] 创建 `styles/z-index.scss`
- [ ] 创建 `constants/z-index.ts`

### Phase 2: 修复关键冲突
- [ ] unified-toolbar: 1000 → 2000
- [ ] popovers: 1000 → 3000
- [ ] task-queue-panel: 999 → 4000
- [ ] AI dialogs: 2000 → 5100

### Phase 3: 全面迁移
- [ ] 替换所有SCSS中的硬编码z-index
- [ ] 替换所有TSX中的内联z-index
- [ ] 移除临时修复(9999, 10000等)

### Phase 4: 文档和测试
- [ ] 更新CODEBUDDY.md
- [ ] 添加层级可视化测试页面
- [ ] 团队培训

## 常见问题

**Q: 如果需要在两个预定义层级之间插入新层级怎么办?**  
A: 每层预留了100个单位空间。例如在popover(3000)和drawer(4000)之间，可以使用3100-3999。

**Q: TDesign组件的z-index怎么处理?**  
A: 通过组件的style或className属性覆盖，或使用TDesign的zIndex prop。

**Q: react-rnd的默认z-index是多少?**  
A: 默认没有z-index，需要显式设置。统一使用`Z_INDEX.DIALOG_*`系列。

**Q: 如何调试z-index问题?**  
A: 
1. 使用浏览器DevTools的3D视图
2. 临时添加不同背景色区分层级
3. 使用 `debug: 9999` 层进行调试，完成后移除

## 参考资料

- [MDN: z-index](https://developer.mozilla.org/en-US/docs/Web/CSS/z-index)
- [CSS Stacking Context](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_positioned_layout/Understanding_z-index/Stacking_context)
- [React Portals](https://react.dev/reference/react-dom/createPortal)