Skip to content

Commit 8b078c6

Browse files
AparenciaAparencia
committed
docs(knowledge): 新增两篇踩坑记录 + Wiki 布局头脑风暴
- 笔记页动态导入失败：ELECTRON_BUILD 下 dev server 预构建依赖 504（vite base 根因） - 笔记页黑条：面板渐变背景依赖 CSS 变量未全局定义 - Wiki 布局交互设计头脑风暴文档
1 parent 7658c81 commit 8b078c6

3 files changed

Lines changed: 387 additions & 0 deletions

File tree

‎docs/Foresight/wiki-layout-brainstorm.md‎

Lines changed: 216 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,216 @@
1+
# 笔记页布局头脑风暴与重新设计方案
2+
3+
> **状态**: 已澄清并部分实施（2026-08-09 澄清：目标页面为**笔记页 NotesPage**，左栏=文件组，右栏=浏览区）
4+
> **日期**: 2026-08-09
5+
> **模块**: 笔记（Notes）— 布局与交互子系统（三栏式：文件夹 / 笔记列表 / 预览）
6+
> **参考**: [sop-custom-design.md](./sop-custom-design.md)（三栏式布局概念）、[tipTapConverter.ts](../../client/src/features/classroom/utils/tipTapConverter.ts)（结构化数据流模式）
7+
> **澄清说明**: 需求最初指向 WikiPage，实施后经用户澄清实际针对笔记页 NotesPage（左栏=文件组、右栏=浏览区）；WikiPage 的侧边栏改动已回滚（保留自动保存优化），布局方案落地到 NotesPage。
8+
9+
---
10+
11+
## 一、当前布局分析
12+
13+
### 1.1 现状诊断
14+
15+
当前 WikiPage 使用 `grid md:grid-cols-[260px_1fr]` 双栏布局：
16+
17+
```
18+
┌──────────────────────────────────────────────────────┐
19+
│ ModuleRitualHeader (标题 + 仪式感印章) │
20+
├───────────────┬──────────────────────────────────────┤
21+
│ 左侧面板 │ 编辑器主区域 │
22+
│ (260px) │ │
23+
│ │ ┌─ 页面标题 + 版本号 ─────────────┐ │
24+
│ [输入框][+] │ │ 标题文本 v1 │ │
25+
│ │ ├─ ContributionLegend ────────────┤ │
26+
│ ┌─────────┐ │ │ 贡献者颜色图例 │ │
27+
│ │ 页面 A │ │ ├─ WikiQualityBadge ─────────────┤ │
28+
│ │ 页面 B │ │ │ 质量徽章 + 投票 │ │
29+
│ │ 页面 C │ │ ├────────────────────────────────┤ │
30+
│ └─────────┘ │ │ textarea (Markdown 编辑器) │ │
31+
│ │ │ │ │
32+
│ │ │ (自动保存说明) │ │
33+
│ └──┴───────────────────────────────────┘ │
34+
└──────────────────────────────────────────────────────┘
35+
```
36+
37+
### 1.2 现有问题
38+
39+
| 问题 | 严重度 | 描述 |
40+
|------|--------|------|
41+
| **左侧面板不可折叠** | 高 | 页面列表始终占据 260px 宽度，在小屏或需要专注编辑时占用空间 |
42+
| **无右侧详情面板** | 中 | 页面元数据（创建时间、投票数、贡献者详情）与编辑器内容混排，信息密度低 |
43+
| **布局缺乏弹性** | 中 | 固定 grid 布局无法适应不同任务场景（浏览 vs 编辑 vs 审阅） |
44+
| **信息层级扁平** | 低 | 元数据与编辑器在同一个垂直流中，缺乏视觉分区 |
45+
46+
---
47+
48+
## 二、参考设计分析
49+
50+
### 2.1 sop-custom-design.md 的三栏式布局
51+
52+
SOP 编辑器采用三栏式结构，核心设计理念是"**左导航 → 中画布 → 右配置**"：
53+
54+
```
55+
┌──────────────────────────────────────────────────────┐
56+
│ SOP 名称: [________________] 标签: [数学] [课前] [+] │
57+
├──────────┬───────────────────────┬───────────────────┤
58+
│ 步骤面板 │ 步骤画布 │ 步骤配置面板 │
59+
│ │ │ │
60+
│ 拖拽添加 →│ [步骤卡片] [步骤卡片] │ 配置参数 │
61+
│ │ [步骤卡片] │ 检查子项 │
62+
│ 步骤列表 │ [+ 添加步骤] │ │
63+
├──────────┴───────────────────────┴───────────────────┤
64+
│ 预估总时长: 65 分钟 [保存] [另存为模板] [删除] │
65+
└──────────────────────────────────────────────────────┘
66+
```
67+
68+
**可借鉴的设计原则**：
69+
- **左栏导航**：可折叠的步骤面板（类比 Wiki 的页面列表）
70+
- **中栏画布**：主内容区（类比 Wiki 的编辑器）
71+
- **右栏配置**：上下文配置面板（类比 Wiki 的页面详情/元数据）
72+
- **三栏互斥**：左栏展开时右栏自动收起，反之亦然
73+
74+
### 2.2 tipTapConverter.ts 的结构化数据流
75+
76+
tipTapConverter.ts 展示了一种**管道式数据流**模式：
77+
78+
```
79+
输入（Markdown 文本）→ 解析（逐行遍历）→ 加工（stripInlineMd）→ 输出（TipTap JSON）
80+
```
81+
82+
这种模式映射到布局设计中可以理解为：
83+
- **输入层**：页面列表（用户选择要编辑的页面）
84+
- **处理层**：编辑器（用户编写/修改内容）
85+
- **输出/展示层**：页面详情面板（展示结果、元数据、质量评估）
86+
87+
---
88+
89+
## 三、重新布局设计方案
90+
91+
### 3.1 总体布局架构
92+
93+
采用**三栏弹性布局**，左右侧边栏均可独立展开/收起，互斥逻辑确保主编辑区始终有足够空间：
94+
95+
```
96+
┌──────────────────────────────────────────────────────────────┐
97+
│ ModuleRitualHeader (标题 + 保存状态指示器 + 操作按钮) │
98+
├──────┬──┬──────────────────────────┬──┬──────────────────────┤
99+
│ │ │ │ │ │
100+
│ 左栏 │←→│ 主编辑区 │→│ 右栏（页面详情） │
101+
│ │ │ │ │ │
102+
│ 页面 │ │ ┌─ 标题 + 版本号 ────┐ │ │ ┌─ 页面详情 ──────┐ │
103+
│ 列表 │ │ │ 标题文本 v1 │ │ │ │ 📄 创建时间 │ │
104+
│ │ │ ├─ 贡献者/质量 ─────┤ │ │ │ 🕐 更新时间 │ │
105+
│ 可 │ │ │ 图例 + 徽章 │ │ │ │ 📋 版本号 │ │
106+
│ 折 │ │ ├──────────────────┤ │ │ │ 👍 投票数 │ │
107+
│ 叠 │ │ │ textarea 编辑器 │ │ │ │ 👥 贡献者数 │ │
108+
│ │ │ │ │ │ │ ├─ 贡献者图例 ────┤ │
109+
│ 260px│ │ │ │ │ │ │ 颜色图例 │ │
110+
│ │ │ │ │ │ │ ├─ 质量徽章 ─────┤ │
111+
│ │ │ │ 自动保存说明 │ │ │ │ 质量评估 + 投票 │ │
112+
│ │ │ └──────────────────┘ │ │ └─────────────────┘ │
113+
│ │ │ 保存状态: 已保存 │ │ │
114+
├──────┴──┴──────────────────────────┴──┴──────────────────────┤
115+
│ 底部操作栏（可选） │
116+
└──────────────────────────────────────────────────────────────┘
117+
↑ ↑ ↑ ↑
118+
左按钮 左栏展开 主编辑区 右栏展开 右按钮
119+
```
120+
121+
### 3.2 布局状态矩阵
122+
123+
| 左栏 | 右栏 | 主编辑区宽度 | 适用场景 |
124+
|------|------|-------------|----------|
125+
| 展开 | 收起 | `100% - 260px` | 浏览页面列表 + 编辑 |
126+
| 收起 | 展开 | `100% - 220px` | 专注编辑 + 查看详情 |
127+
| 展开 | 展开 | ❌ 互斥禁止 | — |
128+
| 收起 | 收起 | `100%` | 全屏编辑（专注模式） |
129+
130+
### 3.3 布局切换动画
131+
132+
采用 Tailwind `transition-all duration-300 ease-kb-default` 实现平滑过渡：
133+
134+
```tsx
135+
// 左侧边栏动画
136+
<div className={cn(
137+
'transition-all duration-300 ease-kb-default flex-shrink-0',
138+
leftSidebarOpen ? 'w-[260px] opacity-100' : 'w-0 opacity-0 overflow-hidden',
139+
)}>
140+
141+
// 右侧边栏动画
142+
<div className={cn(
143+
'transition-all duration-300 ease-kb-default flex-shrink-0',
144+
rightSidebarOpen ? 'w-[220px] opacity-100' : 'w-0 opacity-0 overflow-hidden',
145+
)}>
146+
```
147+
148+
### 3.4 控制按钮设计
149+
150+
左右侧边栏控制按钮采用**圆形浮动按钮**，位于侧边栏与主编辑区之间的边界：
151+
152+
```
153+
左按钮（贴在左栏右侧边缘）：
154+
┌──────────────┬────┬─────────────────────┐
155+
│ 左栏内容 │ ◀ │ 主编辑区 │
156+
│ │ │ │
157+
└──────────────┴────┴─────────────────────┘
158+
展开时：← 收起 展开时：→ 展开
159+
160+
右按钮（贴在右栏左侧边缘）：
161+
┌─────────────────────┬────┬──────────────┐
162+
│ 主编辑区 │ ▶ │ 右栏内容 │
163+
│ │ │ │
164+
└─────────────────────┴────┴──────────────┘
165+
展开时：→ 收起 展开时：← 展开
166+
```
167+
168+
---
169+
170+
## 四、实施建议
171+
172+
### 4.1 分阶段实施
173+
174+
| 阶段 | 范围 | 内容 |
175+
|------|------|------|
176+
| **P0** | NotesPage | 左右侧边栏独立控制按钮 + 互斥逻辑（**已实施**，见下方落地说明） |
177+
| **P1** | 全页面模板 | 将侧边栏模式抽象为通用布局组件，供其他页面复用 |
178+
| **P2** | 响应式 | 窄屏自动收起侧边栏，改为抽屉式覆盖 |
179+
180+
### 4.1.1 P0 落地说明（2026-08-09 澄清后实施）
181+
182+
- **目标页面**：`client/src/features/notes/pages/NotesPage.tsx`（左栏=文件夹/文件组，右栏=浏览区/预览）
183+
- **互斥机制**：保留既有 `sideMode: 'left' | 'right' | 'none'` 单值三态——天然互斥（一个展开时另一个必为收起态）
184+
- **控制按钮**：由单一循环切换按钮（`cycleSideMode`）改为**两个独立按钮**：
185+
- 左按钮（工具栏首部，`PanelLeftClose/PanelLeft`）：展开/收起左栏文件组，展开时自动把 sideMode 置为 'left'（右栏随之收起）
186+
- 右按钮（搜索栏右侧，`PanelRightClose/PanelRight`）：展开/收起右栏预览区，展开时自动把 sideMode 置为 'right'（左栏随之收起）
187+
- 展开态按钮以品牌色高亮（`text-brand-600 bg-brand-50/60`），展开/收起状态一目了然
188+
- **断点对齐**：左按钮 `hidden md:flex`（与左栏 `md:flex` 一致），右按钮 `hidden lg:flex`（与右栏 `lg:flex` 一致）
189+
- **WikiPage 回滚**：需求澄清前的 WikiPage 侧边栏改动已恢复为原 `grid md:grid-cols-[260px_1fr]` 双栏布局，仅保留自动保存优化（2s idle debounce + 内容变更检测 + blur/visibilitychange 即时落盘 + 保存状态指示）
190+
191+
### 4.2 与现有设计系统的一致性
192+
193+
- 侧边栏控制按钮的样式与 `CaptureSidebar.tsx` 的折叠按钮保持一致（圆形、阴影、hover 效果）
194+
- 图标使用 `lucide-react` 的 `PanelLeftClose/PanelLeft` 和 `PanelRightClose/PanelRight`（折叠/展开图标随状态切换）
195+
- 动画使用项目中已有的 `duration-kb-fast` 和 `ease-kb-default` 时间函数
196+
197+
### 4.3 布局与 sop-custom-design.md 的三栏式概念对照
198+
199+
| SOP 三栏 | NotesPage 三栏 | 功能对应 |
200+
|----------|----------------|----------|
201+
| 步骤面板（左） | 文件夹/文件组（左） | 导航与选择 |
202+
| 步骤画布（中） | 笔记列表（中） | 主内容浏览 |
203+
| 步骤配置面板（右） | 预览/浏览区（右） | 内容详情预览 |
204+
| 底部预估时长 + 操作 | 工具栏操作按钮 | 状态反馈与操作 |
205+
206+
---
207+
208+
## 五、总结
209+
210+
本次重新布局方案的核心改进：
211+
212+
1. **弹性三栏架构**：从固定 grid 布局改为弹性 flex 布局，左右侧边栏可独立展开/收起
213+
2. **互斥逻辑**：左右侧边栏互斥展开，确保主编辑区始终有足够显示空间
214+
3. **新增右侧详情面板**：将页面元数据从编辑器内分离到独立面板，提升信息组织清晰度
215+
4. **平滑动画过渡**：使用 CSS transition 实现侧边栏折叠/展开的流畅动画
216+
5. **与现有设计一致**：控制按钮样式与 `CaptureSidebar.tsx` 保持一致，图标使用 lucide-react 标准图标

‎docs/knowledge/bugs/2026-08-dive-css-vars-missing-panel-transparent.md‎

Lines changed: 79 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,79 @@
1+
# 知识卡片 · 踩坑记录
2+
3+
## 基本信息
4+
5+
| 字段 | 内容 |
6+
|------|------|
7+
| 标题 | 笔记页左/上「黑条」：FunctionalOverlay 面板渐变背景依赖的 CSS 变量未全局定义 |
8+
| 日期 | 2026-08-07 |
9+
| 类型 | 踩坑记录 |
10+
| 标签 | #CSS变量 #按需加载 #FunctionalOverlay #面板背景 #主题变量 |
11+
12+
---
13+
14+
## 症状
15+
16+
笔记页（`/#/notes`）面板内容区左侧、上侧出现「黑条」——面板 padding（p-8，32px）区域呈现
17+
接近纯黑的模糊底色，与内容区（三栏毛玻璃）形成明显断层，看起来"小容器的空间没被应用"。
18+
其他模块（如番茄钟）无此现象。
19+
20+
## 环境
21+
22+
| 项目 | 信息 |
23+
|------|------|
24+
| OS | Windows |
25+
| 运行构建 | 开发模式（Vite dev server + Electron） |
26+
| 复现步骤 | 深色主题下直接进入 `/notes`（不经过番茄钟模块） |
27+
28+
## 排查过程
29+
30+
1. **几何分析**：FunctionalOverlay 面板 `p-3 sm:p-5 md:p-8` padding 32px 区域露出"黑条"，
31+
说明页面内容（三栏有半透明背景）从 padding 内侧才开始，padding 区渲染为深色。
32+
2. **样式取证**（getComputedStyle）：面板 `backgroundImage: "none"`、`backgroundColor: transparent`——
33+
面板内联渐变背景**整体失效**，而非"渲染成黑色"。
34+
3. **变量取证**：面板内联样式为 `background: linear-gradient(180deg, var(--kb-dive-top) ...)`，
35+
但 `getComputedStyle(document.documentElement).getPropertyValue('--kb-dive-top')` 返回**空字符串**，
36+
全部 styleSheets 中均无 `:root`/`[data-theme]` 下的 `--kb-dive-*` 定义。
37+
4. **加载链取证**：`--kb-dive-*` 唯一定义在 `client/src/features/pomodoro/styles/pomodoro-dive.css`，
38+
该文件只被 `DiveBackground.tsx`（番茄钟模块组件）import。用户直接进笔记页（lazy 加载），
39+
DiveBackground 从未挂载 → CSS 从未注入 → 变量未定义 → 面板背景声明无效 → 透明。
40+
41+
## 根因
42+
43+
**共享组件（FunctionalOverlay）的背景依赖模块内 CSS 文件定义的主题变量，而该 CSS 按模块按需加载**：
44+
`--kb-dive-*` 只定义在 `pomodoro-dive.css`（被番茄钟模块组件 import），
45+
未进入番茄模块的会话中变量缺失，`linear-gradient(..., var(--kb-dive-top), ...)` 整体失效，
46+
面板退化为透明 + backdrop-blur → 背后深色 3D 场景透出形成"黑条"。
47+
48+
- 番茄钟页面正常：DiveBackground 挂载时注入 CSS，变量就位。
49+
- 笔记页异常：依赖链不含 DiveBackground → 变量缺失。
50+
- 浅色主题下同样失效（表现为"浅色条/白条"），深色主题下最显眼（黑条）。
51+
52+
## 解决方案
53+
54+
**把 `--kb-dive-*` 变量提升为全局主题变量**（本仓库已修）：
55+
在 `client/src/styles/tokens.css` 的 `:root`（浅色）与 `[data-theme="dark"]`（深色）块末尾
56+
各补充 `--kb-dive-top/mid/bot/bubble/ray/fog` 六项（值与 `pomodoro-dive.css` 一致）。
57+
`tokens.css` 经 `index.css` @import 全局注入，任何模块/页面下变量始终就位；
58+
`pomodoro-dive.css` 内定义保留（同值重复定义，加载顺序靠后者覆盖，无副作用）。
59+
60+
验证：深色主题下进入 `/#/notes`，`--kb-dive-top` 计算值为 `rgba(24, 42, 72, 0.9)`，
61+
面板 computed background 恢复 `linear-gradient(rgba(24,42,72,0.9) 0%, ...)`；
62+
elementFromPoint 探测 padding 区命中面板自身渐变（非透明）。0 控制台错误。
63+
64+
## 教训
65+
66+
- **共享组件（overlay/布局/弹层）的样式不得依赖模块级 CSS 变量的按需注入**：
67+
CSS 变量会随 import 它的组件是否挂载而"时有时无"，导致共享组件背景/主题在部分路由下静默失效。
68+
凡跨模块共享的样式变量必须定义在全局样式入口（tokens.css / index.css）。
69+
- **"透明"不等于"黑色"**：面板失效的视觉表现是背后 3D 场景透出（深色主题下像黑条）。
70+
用 getComputedStyle 核对 backgroundImage 是否真的渲染，而不是直接改颜色值。
71+
- **排查 CSS 变量缺失用三层取证**：① 面板 computed style 是否含该背景；② `getComputedStyle(document.documentElement)`
72+
读变量值是否为空；③ 遍历 styleSheets 找变量定义文件，再反查该 CSS 的 import 链与组件挂载条件。
73+
74+
## 参考
75+
76+
- 全局主题变量：`client/src/styles/tokens.css`（`:root` / `[data-theme="dark"]`）
77+
- 模块内旧定义：`client/src/features/pomodoro/styles/pomodoro-dive.css`
78+
- 共享面板组件：`client/src/components/overlay/FunctionalOverlay.tsx`（内联渐变背景）
79+
- [Debug 标准操作流程](../../standards/debug-sop.md)

0 commit comments

Comments
 (0)