bim_engine/.sisyphus/notepads/component-detail-rightclick/issues.md

# Issues & Resolutions: 构件详情右键菜单功能

## 2026-01-28

### Issue 1: TypeScript 类型定义顺序问题

**Problem**:
```typescript
// 直接在 zh-CN.ts 添加翻译
menu: {
    info: '信息',
    home: '首页',
    componentDetail: '构件详情',  // ❌ Error: Property 'componentDetail' does not exist
}
```

**Error Message**:
```
ERROR [37:9] Object literal may only specify known properties, 
and 'componentDetail' does not exist in type '{ info: string; home: string; }'.
```

**Root Cause**:
- TypeScript 类型定义在 `types.ts`
- 实现在 `zh-CN.ts` 和 `en-US.ts`
- 先修改实现会导致类型不匹配

**Resolution**:
1. 先更新 `src/locales/types.ts` 添加类型定义
2. 再更新 `src/locales/zh-CN.ts` 添加中文翻译
3. 最后更新 `src/locales/en-US.ts` 添加英文翻译

**Correct Order**:
```typescript
// Step 1: types.ts
interface TranslationDictionary {
    menu: {
        info: string;
        home: string;
        componentDetail: string;  // 先定义类型
        showAll: string;
    };
}

// Step 2: zh-CN.ts
menu: {
    info: '信息',
    home: '首页',
    componentDetail: '构件详情',  // ✅ Now valid
    showAll: '显示全部'
}

// Step 3: en-US.ts
menu: {
    info: 'Info',
    home: 'Home',
    componentDetail: 'Component Detail',
    showAll: 'Show All'
}
```

**Status**: ✅ Resolved

**Lesson Learned**: 
- 在 TypeScript 项目中，类型定义优先于实现
- i18n 修改三步走：types → zh-CN → en-US

---

### Issue 2: @ts-expect-error 报错 "Unused directive"

**Problem**:
```typescript
// EngineManager.ts
onClick: () => {
    const registry = ManagerRegistry.getInstance();
    // @ts-expect-error - componentDetail will be added in Task 4
    registry.componentDetail?.show(selected.url, selected.id);
    this.rightKey?.hide();
}
```

**Error Message** (after Task 4 completed):
```
src/managers/engine-manager.ts(65,29): error TS2578: Unused '@ts-expect-error' directive.
```

**Root Cause**:
- Task 2 时 `registry.componentDetail` 还不存在，需要 `@ts-expect-error`
- Task 4 添加了 `componentDetail` 到 Registry
- TypeScript 现在识别该属性，`@ts-expect-error` 变成无用指令

**Resolution**:
移除 `@ts-expect-error` 注释：
```typescript
onClick: () => {
    const registry = ManagerRegistry.getInstance();
    registry.componentDetail?.show(selected.url, selected.id);  // ✅ Now valid
    this.rightKey?.hide();
}
```

**Status**: ✅ Resolved

**Lesson Learned**:
- `@ts-expect-error` 是临时措施，完成后需清理
- 构建验证会捕获此类问题

---

### Issue 3: Edit_tool 要求先 Read 文件

**Problem**:
```typescript
// 第一次 Edit 成功
Edit_tool(file, oldString1, newString1);  // ✅ OK

// 第二次 Edit 失败
Edit_tool(file, oldString2, newString2);  // ❌ Error: You must read file before overwriting it
```

**Error Message**:
```
Error: You must read file /path/to/file before overwriting it. Use the Read tool first
```

**Root Cause**:
- Edit_tool 内部有保护机制
- 每次 Edit 前必须先 Read，即使之前读过

**Resolution**:
```typescript
// Correct workflow
Read_tool(file, offset, limit);
Edit_tool(file, oldString1, newString1);

Read_tool(file, offset, limit);  // Read again
Edit_tool(file, oldString2, newString2);
```

**Status**: ✅ Resolved

**Lesson Learned**:
- Edit_tool 不记忆之前的 Read 操作
- 每次 Edit 前都要 Read（即使看起来冗余）

---

### Issue 4: LSP Diagnostics 路径问题

**Problem**:
```typescript
LspDiagnostics_tool({ filePath: "/path/to/src", severity: "error" });
```

**Error Message**:
```
Error: No LSP server configured for extension: 

Available servers: typescript, deno, vue, eslint, oxlint, biome, gopls, ruby-lsp...
```

**Root Cause**:
- LspDiagnostics_tool 需要文件扩展名来判断使用哪个 LSP server
- 目录路径没有扩展名

**Resolution**:
使用构建命令代替 LSP 诊断：
```typescript
// Instead of LSP diagnostics
Bash_tool({ command: "bun run build" });

// Build output contains TypeScript errors
```

**Status**: ✅ Resolved (workaround)

**Alternative**: 对具体文件使用 LSP
```typescript
LspDiagnostics_tool({ 
    filePath: "/path/to/src/managers/engine-manager.ts", 
    severity: "error" 
});
```

**Lesson Learned**:
- LSP diagnostics 需要文件路径，不支持目录
- `bun run build` 包含了 TypeScript 检查，可作为替代方案

---

### Issue 5: Git 提交时出现大量文件警告

**Problem**:
```bash
git add -A && git commit -m "..."
```

**Warning Output**:
```
warning: in the working copy of '.shared/ui-ux-pro-max/data/charts.csv', 
CRLF will be replaced by LF the next time Git touches it
warning: in the working copy of '.shared/ui-ux-pro-max/data/colors.csv', 
CRLF will be replaced by LF the next time Git touches it
...
```

**Root Cause**:
- `.shared/ui-ux-pro-max/` 目录中的 CSV 文件使用了 CRLF 换行符
- Git 配置为 LF 换行符
- 这是 OpenCode 框架文件，不是本项目代码

**Impact**:
- ⚠️ 警告信息但不影响提交
- 实际提交的文件只包含项目代码（src/、.sisyphus/ 等）

**Resolution**:
- 无需处理（框架文件）
- 提交成功，项目代码正确

**Status**: ✅ 可忽略

**Lesson Learned**:
- Git 警告不等于错误
- 关注实际提交的文件列表（通过 `git log --stat`）

---

### Issue 6: 注释触发 Hook 警告

**Problem**:
```typescript
/** 构件详情管理器 */
public componentDetail: ComponentDetailManager | null = null;
```

**Warning**:
```
COMMENT/DOCSTRING DETECTED - IMMEDIATE ACTION REQUIRED

You need to take immediate action. You must follow the conditions below...
```

**Root Cause**:
- 代码规范 Hook 检测到新增注释
- 需要判断注释是否必要

**Resolution**:
说明这是现有模式（Priority 1）：
> This is an **existing comment pattern** in the codebase. 
> All manager properties in `manager-registry.ts` have JSDoc comments (lines 39-68). 
> Following the established convention: `/** [Manager名称] */`

**Status**: ✅ Resolved (justified)

**Lesson Learned**:
- 新增注释需要符合四个优先级之一
- 遵循现有代码规范属于 Priority 1（已存在的模式）

---

## Non-Issues (False Alarms)

### False Alarm 1: "componentDetail 属性不存在"

**Initial Concern**:
```typescript
registry.componentDetail?.show(url, id);
// 是否会在运行时报错？
```

**Analysis**:
- TypeScript 编译时检查通过（Optional Chaining）
- Registry 中已注册 `componentDetail`
- 运行时有实例存在

**Conclusion**: ✅ No issue - 正常工作

---

### False Alarm 2: "数据格式不兼容"

**Initial Concern**:
```typescript
// 底层返回
{ properties: [{ name, children: [...] }] }

// UI 需要
{ items: [{ categoryName, items: [...] }] }

// 是否兼容？
```

**Analysis**:
- Manager 中进行了数据转换
- UI 组件接收正确格式
- 测试通过

**Conclusion**: ✅ No issue - 数据转换正确

---

## Summary

**Total Issues**: 6
- ✅ Resolved: 5
- ⚠️ Ignored: 1 (framework warning)

**Impact**:
- ✅ All issues resolved or explained
- ✅ Build passing
- ✅ No runtime errors expected

**Key Takeaways**:
1. TypeScript 类型定义优先于实现
2. 临时措施（@ts-expect-error）需后续清理
3. 工具限制（Edit_tool、LspDiagnostics）需了解
4. Git 警告不等于错误，关注实际影响
5. 注释规范需遵循现有模式