Initial TrueGrowth source import

2026-07-07 09:36:36 +08:00
commit 3b6781d695
2283 changed files with 691996 additions and 0 deletions
--- a/docs/Z_INDEX_GUIDE.md
+++ b/docs/Z_INDEX_GUIDE.md
@@ -0,0 +1,362 @@
+# 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)