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

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

2026-01-28

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

Problem:

// 直接在 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:

// 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:

// 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 注释：

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:

// 第一次 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:

// 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:

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 诊断：

// Instead of LSP diagnostics
Bash_tool({ command: "bun run build" });

// Build output contains TypeScript errors

Status: ✅ Resolved (workaround)

Alternative: 对具体文件使用 LSP

LspDiagnostics_tool({ 
    filePath: "/path/to/src/managers/engine-manager.ts", 
    severity: "error" 
});

Lesson Learned:

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

---

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

Problem:

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:

/** 构件详情管理器 */
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:

registry.componentDetail?.show(url, id);
// 是否会在运行时报错？

Analysis:

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

Conclusion: ✅ No issue - 正常工作

---

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

Initial Concern:

// 底层返回
{ 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. 注释规范需遵循现有模式