重构：文件系统模块化架构，优化应用启动流程

2026-01-28 00:28:54 +08:00
parent 4a9b25a505
commit 8c577f70e7
123 changed files with 32030 additions and 967 deletions
--- a/docs/04-功能迭代/GO-DESK-2.数据库客户端/知识库/规范/编码规范.md
+++ b/docs/04-功能迭代/GO-DESK-2.数据库客户端/知识库/规范/编码规范.md
@@ -0,0 +1,194 @@
+# 编码规范
+
+**状态**：已确定  
+**最后更新**：2025-01-28
+
+---
+
+## 一、通用规范
+
+### 1.1 开发优先原则（最高优先级）
+
+#### 1.1.1 主动性确定性编程
+
+**原则**：主动控制执行时机和状态，确保在确定的状态下执行操作，而非通过防御性检查和重试来弥补时机问题。
+
+**具体要求**：
+
+1. **使用 Vue 响应式系统确保状态一致性**
+   - 优先使用 `ref`、`reactive`、`computed` 管理状态
+   - 通过 `watch` 和 `nextTick` 确保在正确时机执行
+   - 避免手动同步状态，依赖 Vue 的响应式机制
+
+2. **使用模板引用（Template Refs）直接获取 DOM**
+   - 优先使用 `:ref` 绑定获取 DOM 元素
+   - 避免通过 `querySelector` 等 DOM 查询方式
+   - 通过 ref Map 管理多个元素引用
+
+3. **确保执行时机正确**
+   - 使用 `nextTick` 等待 DOM 更新完成
+   - 使用 `requestAnimationFrame` 等待渲染完成
+   - 在正确的生命周期钩子中执行操作
+
+4. **减少防御性编程**
+   - 移除不必要的重试循环
+   - 移除过多的条件检查和兜底逻辑
+   - 确保数据在操作前已准备好，而非通过检查来避免错误
+
+5. **代码简洁直接**
+   - 直接表达意图，避免过度抽象
+   - 减少中间变量和临时状态
+   - 使用明确的函数名和变量名
+
+**示例对比**：
+
+```typescript
+// ❌ 防御性编程（不推荐）
+const findContainer = async (tabKey, retryCount = 8) => {
+  for (let i = 0; i < retryCount; i++) {
+    await new Promise(resolve => setTimeout(resolve, 250))
+    const container = document.querySelector(`.code-editor[data-tab-key="${tabKey}"]`)
+    if (container) {
+      const rect = container.getBoundingClientRect()
+      if (rect.width > 0 && rect.height > 0) {
+        return container
+      }
+    }
+  }
+  return null
+}
+
+// ✅ 主动性确定性编程（推荐）
+const editorContainers = ref(new Map())
+
+// 在模板中直接绑定
+<div :ref="el => setEditorContainerRef(el, tab.key)"></div>
+
+const findContainer = async (tabKey) => {
+  await nextTick()
+  await new Promise(resolve => requestAnimationFrame(resolve))
+  const containerInfo = editorContainers.value.get(tabKey)
+  return containerInfo?.container || null
+}
+```
+
+#### 1.1.2 其他优先原则
+
+- **简洁优先**：代码要简洁，避免过度设计；优先使用简单方案，避免不必要的高级特性
+- **易于维护**：代码结构清晰，便于维护；减少中间层和抽象，直接表达意图
+- **减少AI味**：避免明显的AI生成代码特征；避免过度注释和文档
+- **降低幻觉**：避免不必要的高级特性；优先使用简单、直接的方案
+
+### 1.2 注释规范
+- **必要注释**：只保留必要的注释，便于维护
+- **中文注释**：使用中文编写注释
+- **避免冗余**：不写显而易见的注释
+
+---
+
+## 二、Go后端规范
+
+### 2.1 方法参数（设计美学约束）
+- **参数限制**：方法参数不得超过3个（硬性约束，不可违反）
+- **超过限制**：必须使用结构体/对象封装参数
+- **设计美学**：参数过多严重影响代码可读性和维护性，完全不可接受
+- **示例**：
+  ```go
+  // ❌ 9个参数，完全不可接受
+  func SaveDbConnection(id uint, name, dbType, host string, port int, username, password, database, options string) error
+  
+  // ✅ 使用结构体封装
+  type SaveConnectionRequest struct {
+      ID uint
+      Name string
+      Type string
+      Host string
+      Port int
+      Username string
+      Password string
+      Database string
+      Options string
+  }
+  func SaveDbConnection(req SaveConnectionRequest) error
+  ```
+
+### 2.2 返回值
+- **禁止类型**：不返回 `RetResult<Void>` 类型
+- **错误处理**：统一使用 error 返回错误
+
+### 2.3 代码签名
+- **作者标识**：新增文件使用 `JueChen` 作为代码签名
+
+### 2.4 架构约束
+- **分层架构**：API → Service → Repository → Infrastructure
+- **职责分离**：每层只负责自己的职责
+- **依赖方向**：只能依赖下层，不能依赖上层
+
+---
+
+## 三、前端规范
+
+### 3.1 样式规范
+- **Arco基础样式**：优先使用 Arco Design 提供的基样式
+- **避免自定义**：避免过度自定义样式和硬编码样式
+- **主题兼容**：确保切换主题时样式正常
+
+### 3.2 组件规范
+- **不包含title**：`<a-card>` 元素不包含 title 属性
+- **简洁设计**：组件设计要简洁，避免过度复杂
+
+### 3.3 事件规范
+- **统一格式**：事件参数使用对象格式
+- **类型定义**：所有事件都有 TypeScript 类型定义
+- **命名规范**：事件名称使用 kebab-case
+
+---
+
+## 四、文档规范
+
+### 4.1 文档编写
+- **精简准确**：文档内容要精简、准确、无幻觉
+- **直接回复**：优先直接回复，不创建过多报告文件
+- **必要文档**：只创建必要性和长久性文档
+
+### 4.2 代码签名
+- **文档签名**：文档使用 `JueChen` 作为签名（本地新增文件）
+
+---
+
+## 五、工具使用
+
+### 5.1 命令行优先
+- **文件操作**：文件更名、复制等优先使用命令行
+- **Git Bash**：执行类似命令时使用 Git Bash
+
+---
+
+## 六、检查清单
+
+### 开发优先原则检查
+- [ ] 是否使用了 Vue 的响应式系统管理状态？
+- [ ] 是否使用了模板引用而非 DOM 查询？
+- [ ] 是否在正确的时机执行操作（通过 `nextTick`、`requestAnimationFrame` 等）？
+- [ ] 是否移除了不必要的重试循环？
+- [ ] 是否移除了过多的条件检查和兜底逻辑？
+- [ ] 代码是否简洁直接，易于理解？
+- [ ] 是否避免了防御性编程模式？
+
+### 代码检查
+- [ ] 方法参数不超过3个
+- [ ] 不返回 `RetResult<Void>` 类型
+- [ ] 代码风格简洁，易于维护
+- [ ] 必要注释已添加
+
+### 前端检查
+- [ ] 使用 Arco 基础样式
+- [ ] 避免过度自定义样式
+- [ ] 事件参数使用对象格式
+- [ ] 所有事件有类型定义
+
+### 文档检查
+- [ ] 文档内容精简准确
+- [ ] 不创建过多报告文件
+- [ ] 必要文档已创建
+