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

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.数据库客户端/知识库/规范/AI协作检查清单.md
+++ b/docs/04-功能迭代/GO-DESK-2.数据库客户端/知识库/规范/AI协作检查清单.md
@@ -0,0 +1,146 @@
+# AI协作检查清单
+
+**状态**：已确定  
+**最后更新**：2025-01-28
+
+---
+
+## 一、开始任务前检查
+
+### 1.1 读取约束
+- [ ] 已读取 [编码规范.md](./编码规范.md)
+- [ ] 已读取 [架构规范.md](./架构规范.md)
+- [ ] 已读取 [技术栈.md](../参考/技术栈.md)
+
+### 1.2 检查决策
+- [ ] 已检查 [决策记录/](../决策记录/) 中相关决策
+- [ ] 已理解相关决策的约束和影响
+
+### 1.3 检查问题
+- [ ] 已检查 [问题追踪/](../../问题追踪/) 中相关问题
+- [ ] 已理解待解决问题和待实现功能
+
+---
+
+## 二、设计阶段检查
+
+### 2.1 设计文档
+- [ ] 设计文档符合模板格式
+- [ ] 引用了相关的知识库规范
+- [ ] 关联了相关的决策记录（ADR）
+- [ ] 列出了待讨论问题
+
+### 2.2 决策记录
+- [ ] 重要决策已创建ADR
+- [ ] ADR格式符合标准模板
+- [ ] 决策理由清晰明确
+
+---
+
+## 三、实现阶段检查
+
+### 3.1 代码规范
+- [ ] 方法参数不超过3个
+- [ ] 不返回 `RetResult<Void>` 类型
+- [ ] 代码简洁，易于维护
+- [ ] 必要注释已添加
+
+### 3.2 架构规范
+- [ ] 符合分层架构
+- [ ] 职责分离明确
+- [ ] 事件参数使用对象格式
+- [ ] 所有事件有类型定义
+
+### 3.3 样式规范
+- [ ] 使用Arco基础样式
+- [ ] 避免过度自定义样式
+- [ ] 确保主题兼容
+
+---
+
+## 四、文档更新检查
+
+### 4.1 知识库更新
+- [ ] 新确定的知识已加入知识库
+- [ ] 知识库内容已验证
+
+### 4.2 问题追踪更新
+- [ ] 已解决问题已关闭
+- [ ] 新问题已创建
+- [ ] 问题状态已更新
+
+### 4.3 决策记录更新
+- [ ] 新决策已创建ADR
+- [ ] 相关ADR已更新
+
+---
+
+## 五、完成检查
+
+### 5.1 代码检查
+- [ ] 编译通过
+- [ ] 无Linter错误
+- [ ] 符合编码规范
+
+### 5.2 文档检查
+- [ ] 设计文档已更新
+- [ ] 决策记录已更新
+- [ ] 问题追踪已更新
+
+### 5.3 测试检查
+- [ ] 功能测试通过
+- [ ] 测试用例已更新
+
+---
+
+## 六、常见错误避免
+
+### 6.1 代码错误
+- ❌ 方法参数超过3个
+- ❌ 返回 `RetResult<Void>` 类型
+- ❌ 过度设计，增加不必要复杂度
+
+### 6.2 架构错误
+- ❌ 违反分层架构
+- ❌ 事件参数使用多个参数
+- ❌ 缺少类型定义
+
+### 6.3 文档错误
+- ❌ 问题与知识混淆
+- ❌ 决策未记录
+- ❌ 约束未明确
+
+---
+
+## 七、引用规范
+
+### 7.1 引用格式
+- 知识库：`[知识库/规范/编码规范.md](../../知识库/规范/编码规范.md)`
+- 决策记录：`[ADR-001](../决策记录/ADR-001-事件系统设计.md)`
+- 问题追踪：`[问题-001](../../问题追踪/待讨论/问题-001-右键菜单实现方式.md)`
+- 设计文档：`[设计文档/架构设计/事件系统设计.md](../../设计文档/架构设计/事件系统设计.md)`
+
+### 7.2 引用原则
+- 引用要准确，使用相对路径
+- 引用要明确，说明引用内容
+- 引用要完整，包含路径和说明
+
+---
+
+## 八、协作流程
+
+### 8.1 开始任务
+1. 读取约束（知识库/规范）
+2. 检查决策（决策记录）
+3. 检查问题（问题追踪）
+
+### 8.2 执行任务
+1. 遵循约束
+2. 记录决策
+3. 更新问题
+
+### 8.3 完成任务
+1. 更新文档
+2. 创建检查报告
+3. 更新任务状态
+
--- a/docs/04-功能迭代/GO-DESK-2.数据库客户端/知识库/规范/文档编写规范.md
+++ b/docs/04-功能迭代/GO-DESK-2.数据库客户端/知识库/规范/文档编写规范.md
@@ -0,0 +1,190 @@
+# 文档编写规范
+
+**状态**：已确定  
+**最后更新**：2025-01-28
+
+---
+
+## 一、核心原则
+
+### 1.1 抽象与实现分离
+- **设计文档**：描述"做什么"和"为什么"，不描述"怎么做"
+- **实现细节**：在代码中体现，不在设计文档中详细描述
+
+### 1.2 问题与知识分离
+- **问题**：待讨论、待解决的问题 → [问题追踪/](../../问题追踪/)
+- **知识**：已确定、已验证的知识 → [知识库/](./)
+
+### 1.3 确定性先行
+- **约束优先**：先明确约束和规则，再讨论具体实现
+- **决策记录**：所有重要决策都要记录在 [决策记录/](../../决策记录/)
+
+---
+
+## 二、文档分类
+
+### 2.1 知识库文档
+**位置**：`知识库/`  
+**特点**：
+- 已确定、已验证的内容
+- 可被其他文档引用
+- 需要定期维护
+
+**分类**：
+- `规范/` - 约束和规则
+- `参考/` - 技术参考
+- `最佳实践/` - 已验证的最佳实践
+
+### 2.2 设计文档
+**位置**：`设计文档/`  
+**特点**：
+- 描述"做什么"和"为什么"
+- 引用知识库中的规范
+- 关联相关的决策记录
+
+**分类**：
+- `需求设计/` - 功能需求
+- `架构设计/` - 系统架构
+- `功能设计/` - 具体功能设计
+
+### 2.3 决策记录（ADR）
+**位置**：`决策记录/`  
+**特点**：
+- 记录所有重要决策
+- 包含决策背景、选项、理由
+- 格式标准化
+
+### 2.4 问题追踪
+**位置**：`问题追踪/`  
+**特点**：
+- 管理待解决问题
+- 状态明确（待讨论/进行中/已解决）
+- 可追溯
+
+---
+
+## 三、文档模板
+
+### 3.1 设计文档模板
+
+```markdown
+# {功能名称}设计
+
+**状态**：{设计中|已完成|已废弃}  
+**创建日期**：YYYY-MM-DD  
+**最后更新**：YYYY-MM-DD
+
+## 一、设计目标
+
+功能要解决什么问题？
+
+## 二、设计约束
+
+引用：[知识库/规范/编码规范.md](../../知识库/规范/编码规范.md)
+
+## 三、设计方案
+
+### 3.1 方案概述
+
+### 3.2 详细设计
+
+## 四、相关决策
+
+- [ADR-{序号}](../../决策记录/ADR-{序号}.md)
+
+## 五、待讨论问题
+
+- [问题追踪/待讨论/{问题}.md](../../问题追踪/待讨论/{问题}.md)
+
+## 六、实现计划
+
+1. 步骤1
+2. 步骤2
+```
+
+### 3.2 ADR模板
+
+```markdown
+# ADR-{序号}: {决策标题}
+
+**状态**：{已采纳|已拒绝|已替代|待定}  
+**日期**：YYYY-MM-DD  
+**决策者**：{姓名/角色}
+
+## 上下文
+
+为什么需要做这个决策？
+
+## 考虑的选项
+
+### 选项1：{选项名称}
+- 优点：
+- 缺点：
+
+## 决策
+
+选择的方案：{选项名称}
+
+## 理由
+
+为什么选择这个方案？
+
+## 后果
+
+### 正面影响
+- 
+
+### 负面影响
+- 
+
+### 约束
+- 
+```
+
+---
+
+## 四、引用规范
+
+### 4.1 引用格式
+- 知识库：`[知识库/规范/编码规范.md](../../知识库/规范/编码规范.md)`
+- 决策记录：`[ADR-001](../决策记录/ADR-001-事件系统设计.md)`
+- 问题追踪：`[问题-001](../../问题追踪/待讨论/问题-001-右键菜单实现方式.md)`
+- 设计文档：`[设计文档/架构设计/事件系统设计.md](../../设计文档/架构设计/事件系统设计.md)`
+
+### 4.2 引用原则
+- **准确性**：引用路径要准确
+- **明确性**：引用要说明引用内容
+- **完整性**：引用要包含路径和说明
+
+---
+
+## 五、内容要求
+
+### 5.1 精简准确
+- 内容要精简，避免冗余
+- 描述要准确，避免歧义
+- 避免AI幻觉，确保内容真实
+
+### 5.2 结构清晰
+- 使用清晰的标题层级
+- 使用列表和表格组织内容
+- 使用代码块展示代码
+
+### 5.3 可维护性
+- 文档要易于更新
+- 使用模板保持一致性
+- 定期检查和更新
+
+---
+
+## 六、检查清单
+
+### 文档检查
+- [ ] 符合文档分类
+- [ ] 使用了正确的模板
+- [ ] 引用了相关的知识库
+- [ ] 关联了相关的决策记录
+- [ ] 列出了待讨论问题
+- [ ] 内容精简准确
+- [ ] 结构清晰
+
--- a/docs/04-功能迭代/GO-DESK-2.数据库客户端/知识库/规范/架构规范.md
+++ b/docs/04-功能迭代/GO-DESK-2.数据库客户端/知识库/规范/架构规范.md
@@ -0,0 +1,400 @@
+# 架构规范
+
+**状态**：已确定  
+**最后更新**：2025-01-28
+
+---
+
+## 一、后端架构规范
+
+### 1.1 分层架构
+```
+API层 (internal/api/)
+  ↓
+Service层 (internal/service/)
+  ↓
+Repository层 (internal/storage/repository/)
+  ↓
+Infrastructure层 (internal/dbclient/)
+```
+
+### 1.2 职责划分
+
+#### API层
+- **职责**：暴露给前端的接口
+- **约束**：只负责参数验证和调用Service
+- **文件命名**：`{功能}_api.go`
+
+#### Service层
+- **职责**：业务逻辑处理
+- **约束**：不直接访问数据库，通过Repository
+- **文件命名**：`{功能}_service.go`
+
+#### Repository层
+- **职责**：数据访问
+- **约束**：只负责CRUD操作，不包含业务逻辑
+- **文件命名**：`{模型}_repo.go`
+
+#### Infrastructure层
+- **职责**：基础设施（数据库客户端、连接池等）
+- **约束**：提供统一的接口，隐藏实现细节
+
+---
+
+## 二、前端架构规范
+
+### 2.1 组件结构
+```
+Views (views/db-cli/)
+  ↓
+Components (components/)
+  ↓
+Composables (composables/)
+  ↓
+Types (types/)
+```
+
+### 2.2 职责划分
+
+#### Views
+- **职责**：页面级组件，负责布局和状态协调
+- **约束**：不包含具体业务逻辑
+
+#### Components
+- **职责**：可复用组件
+- **约束**：组件应该是无状态的（通过props接收数据）
+
+#### Composables
+- **职责**：状态管理和业务逻辑
+- **约束**：可复用的逻辑封装
+
+#### Types
+- **职责**：TypeScript类型定义
+- **约束**：所有类型定义集中管理
+
+---
+
+## 三、事件系统规范
+
+### 3.1 事件命名
+- **格式**：`<组件>-<动作>` 或 `<功能>-<动作>`
+- **示例**：`connection-select`、`table-structure`
+
+### 3.2 事件参数
+- **格式**：对象格式，不使用多个参数
+- **类型**：所有事件都有TypeScript类型定义
+- **位置**：`types/events.ts`
+
+### 3.3 事件处理
+- **位置**：在父组件中处理
+- **职责**：调用相应的composable方法
+
+---
+
+## 四、架构设计美学原则
+
+### 4.1 参数数量约束（最高优先级）
+
+**原则**：方法参数不得超过 3 个，超过必须使用结构体/对象封装。
+
+**违反示例**（不可接受）：
+```go
+// ❌ 9个参数，完全不可接受
+func SaveDbConnection(id uint, name, dbType, host string, port int, username, password, database, options string) error
+```
+
+**正确示例**：
+```go
+// ✅ 使用结构体封装
+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
+```
+
+**前端同理**：
+```typescript
+// ❌ 参数过多
+function saveConnection(id: number, name: string, type: string, host: string, port: number, username: string, password: string, database: string, options: string)
+
+// ✅ 使用对象封装
+interface SaveConnectionRequest {
+  id: number
+  name: string
+  type: string
+  host: string
+  port: number
+  username: string
+  password: string
+  database: string
+  options: string
+}
+function saveConnection(req: SaveConnectionRequest)
+```
+
+### 4.2 依赖注入美学
+
+**原则**：减少手动依赖注入，优先使用自动依赖获取。
+
+**当前问题**：
+```typescript
+// 需要手动注入依赖
+const { executeSQL } = useSqlExecution(resultState, messageLog)
+```
+
+**优化方向**：
+```typescript
+// 内部自动获取依赖（通过 provide/inject 或全局状态）
+const { executeSQL } = useSqlExecution()
+```
+
+### 4.3 代码简洁性
+
+**原则**：代码应该简洁、直接、易于理解。
+
+**要求**：
+- 避免过度抽象
+- 减少中间层
+- 直接表达意图
+- 移除不必要的包装
+
+### 4.4 一致性原则
+
+**原则**：相同功能在不同实现中保持一致的命名和结构。
+
+**要求**：
+- 统一的错误处理方式
+- 统一的命名规范
+- 统一的数据结构
+- 统一的接口风格
+
+### 4.5 可组合性
+
+**原则**：Composables 应该可以独立使用，也可以组合使用。
+
+**要求**：
+- Composables 之间依赖关系清晰
+- 支持按需组合
+- 避免循环依赖
+- 提供清晰的组合模式
+
+---
+
+## 五、架构优化建议
+
+### 5.1 后端 API 层优化（高优先级）
+
+**问题**：API 方法参数过多，违反设计美学。
+
+**优化方案**：
+1. 所有 API 方法参数超过 3 个时，必须使用请求结构体
+2. 统一请求/响应结构体命名：`{Action}Request` / `{Action}Response`
+3. 结构体定义放在对应的 API 文件中
+
+**示例**：
+```go
+// connection_api.go
+type SaveConnectionRequest struct {
+    ID       uint   `json:"id"`
+    Name     string `json:"name"`
+    Type     string `json:"type"`
+    Host     string `json:"host"`
+    Port     int    `json:"port"`
+    Username string `json:"username"`
+    Password string `json:"password"`
+    Database string `json:"database"`
+    Options  string `json:"options"`
+}
+
+func (api *ConnectionAPI) SaveDbConnection(req SaveConnectionRequest) error {
+    conn := &models.DbConnection{
+        ID:       req.ID,
+        Name:     req.Name,
+        Type:     req.Type,
+        Host:     req.Host,
+        Port:     req.Port,
+        Username: req.Username,
+        Password: req.Password,
+        Database: req.Database,
+        Options:  req.Options,
+    }
+    return api.connService.SaveConnection(conn)
+}
+```
+
+### 5.2 前端 Composables 依赖优化（中优先级）
+
+**问题**：需要手动注入依赖，使用不够优雅。
+
+**优化方案**：
+1. 使用 `provide/inject` 或全局状态管理依赖
+2. Composables 内部自动获取依赖
+3. 保持向后兼容，支持手动注入
+
+**示例**：
+```typescript
+// 使用 provide/inject
+const resultState = useResultState()
+const messageLog = useMessageLog()
+
+provide('resultState', resultState)
+provide('messageLog', messageLog)
+
+// useSqlExecution 内部自动获取
+export function useSqlExecution() {
+  const resultState = inject<ReturnType<typeof useResultState>>('resultState')
+  const messageLog = inject<ReturnType<typeof useMessageLog>>('messageLog')
+  // ...
+}
+```
+
+### 5.3 Service 层验证逻辑提取（中优先级）
+
+**问题**：验证逻辑分散在 Service 方法中，代码重复。
+
+**优化方案**：
+1. 创建独立的验证器（Validator）
+2. 统一验证错误格式
+3. 可复用的验证规则
+
+**示例**：
+```go
+// validator/connection_validator.go
+type ConnectionValidator struct{}
+
+func (v *ConnectionValidator) ValidateSave(conn *models.DbConnection) error {
+    if conn.Name == "" {
+        return fmt.Errorf("连接名称不能为空")
+    }
+    if conn.Type == "" {
+        return fmt.Errorf("数据库类型不能为空")
+    }
+    if conn.Host == "" {
+        return fmt.Errorf("主机地址不能为空")
+    }
+    return nil
+}
+```
+
+### 5.4 Composables 组合优化（低优先级）
+
+**问题**：`index.vue` 中 composables 较多，可以进一步抽象。
+
+**优化方案**：
+1. 创建 `useDbCli` composable 作为统一入口
+2. 内部组合所有相关 composables
+3. 提供简洁的 API
+
+**示例**：
+```typescript
+// composables/useDbCli.ts
+export function useDbCli() {
+  const connection = useDbConnection()
+  const editor = useEditorState()
+  const result = useResultState()
+  const message = useMessageLog()
+  const sql = useSqlExecution(result, message)
+  const structure = useStructureState()
+  const structureEdit = useStructureEdit()
+  
+  return {
+    connection,
+    editor,
+    result,
+    message,
+    sql,
+    structure,
+    structureEdit
+  }
+}
+```
+
+---
+
+## 六、架构检查清单
+
+### 开发优先原则检查
+- [ ] 是否使用了 Vue 的响应式系统管理状态？
+- [ ] 是否使用了模板引用而非 DOM 查询？
+- [ ] 是否在正确的时机执行操作（通过 `nextTick`、`requestAnimationFrame` 等）？
+- [ ] 是否移除了不必要的重试循环？
+- [ ] 是否移除了过多的条件检查和兜底逻辑？
+- [ ] 代码是否简洁直接，易于理解？
+- [ ] 是否避免了防御性编程模式？
+
+### 后端检查
+- [ ] API 方法参数不超过 3 个，超过使用结构体封装
+- [ ] 所有请求/响应结构体命名统一
+- [ ] Service 层验证逻辑清晰
+- [ ] 错误处理统一
+
+### 前端检查
+- [ ] Composables 依赖关系清晰
+- [ ] 减少手动依赖注入
+- [ ] 代码简洁直接
+- [ ] 类型定义完善
+
+### 设计美学检查
+- [ ] 参数数量符合约束（≤3）
+- [ ] 代码简洁易读
+- [ ] 命名一致统一
+- [ ] 结构清晰优雅
+
+---
+
+## 四、数据流规范
+
+### 4.1 数据流向
+```
+用户操作
+  ↓
+组件事件
+  ↓
+Composable方法
+  ↓
+API调用
+  ↓
+后端Service
+  ↓
+Repository
+  ↓
+数据库
+```
+
+### 4.2 状态管理
+- **原则**：使用Composables管理状态
+- **位置**：`composables/` 目录
+- **命名**：`use{功能}State.ts`
+
+---
+
+## 五、约束条件
+
+### 5.1 后端约束
+- 方法参数不超过3个
+- 不返回 `RetResult<Void>` 类型
+- 使用分层架构，职责分离
+
+### 5.2 前端约束
+- 使用Arco基础样式
+- 事件参数使用对象格式
+- 所有事件有类型定义
+
+---
+
+## 六、检查清单
+
+### 架构检查
+- [ ] 分层架构清晰
+- [ ] 职责分离明确
+- [ ] 依赖方向正确
+- [ ] 符合架构规范
+
--- 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 基础样式
+- [ ] 避免过度自定义样式
+- [ ] 事件参数使用对象格式
+- [ ] 所有事件有类型定义
+
+### 文档检查
+- [ ] 文档内容精简准确
+- [ ] 不创建过多报告文件
+- [ ] 必要文档已创建
+