新增：文档体系重构+CHANGELOG补充+发布产物清理

2026-05-01 22:22:06 +08:00
parent 3e1a540b83
commit 6eaaa56eb6
164 changed files with 40346 additions and 64 deletions
--- a/docs/03-模块文档/设置功能/settings-quick-reference.md
+++ b/docs/03-模块文档/设置功能/settings-quick-reference.md
@@ -0,0 +1,282 @@
+# 设置功能快速参考
+
+## API 端点
+
+### 获取应用配置
+```go
+// Go 方法
+func (a *App) GetAppConfig() (map[string]interface{}, error)
+
+// 前端调用
+const result = await window.go.main.App.GetAppConfig()
+```
+
+**响应格式：**
+```json
+{
+  "success": true,
+  "data": {
+    "tabs": [
+      {
+        "key": "db-cli",
+        "title": "数据库",
+        "visible": true,
+        "enabled": true
+      }
+    ],
+    "visibleTabs": ["db-cli", "file-system", "device"],
+    "defaultTab": "db-cli"
+  }
+}
+```
+
+### 保存应用配置
+```go
+// Go 方法
+func (a *App) SaveAppConfig(req SaveAppConfigRequest) (map[string]interface{}, error)
+
+// 前端调用
+const result = await window.go.main.App.SaveAppConfig({
+  tabs: [
+    { key: "db-cli", title: "数据库", visible: true, enabled: true }
+  ],
+  visibleTabs: ["db-cli", "file-system"],
+  defaultTab: "db-cli"
+})
+```
+
+**响应格式：**
+```json
+{
+  "success": true,
+  "message": "配置保存成功"
+}
+```
+
+## 数据库表结构
+
+### app_config 表
+```sql
+CREATE TABLE `app_config` (
+  `id` INTEGER PRIMARY KEY AUTOINCREMENT,
+  `key` VARCHAR(50) UNIQUE NOT NULL,
+  `value` TEXT NOT NULL,
+  `description` VARCHAR(200),
+  `created_at` DATETIME,
+  `updated_at` DATETIME
+);
+```
+
+### 示例数据
+```json
+// key = "tab_config"
+{
+  "available_tabs": [
+    { "key": "db-cli", "title": "数据库", "enabled": true },
+    { "key": "file-system", "title": "文件管理", "enabled": true },
+    { "key": "device", "title": "设备调用测试", "enabled": true }
+  ],
+  "visible_tabs": ["db-cli", "file-system", "device"],
+  "default_tab": "db-cli"
+}
+```
+
+## 组件使用
+
+### SettingsPanel 组件
+
+```vue
+<template>
+  <SettingsPanel
+    v-model="showSettings"
+    :config="appConfig"
+    @save="handleSaveConfig"
+  />
+</template>
+
+<script setup>
+import SettingsPanel from './components/SettingsPanel.vue'
+
+const showSettings = ref(false)
+const appConfig = ref({
+  tabs: [],
+  visibleTabs: [],
+  defaultTab: 'db-cli'
+})
+
+const handleSaveConfig = async (config) => {
+  // config 包含:
+  // - tabs: Tab 定义数组
+  // - visibleTabs: 可见 Tab key 数组
+  // - defaultTab: 默认 Tab key
+  console.log('保存配置:', config)
+}
+</script>
+```
+
+## 拖拽实现
+
+### HTML5 Drag & Drop API
+
+```vue
+<template>
+  <div
+    draggable="true"
+    @dragstart="handleDragStart"
+    @dragover.prevent="handleDragOver"
+    @drop="handleDrop"
+    @dragend="handleDragEnd"
+  >
+    拖拽元素
+  </div>
+</template>
+
+<script setup>
+const handleDragStart = (index, event) => {
+  event.dataTransfer.effectAllowed = 'move'
+  event.target.classList.add('dragging')
+}
+
+const handleDragOver = (event) => {
+  event.preventDefault()
+  event.dataTransfer.dropEffect = 'move'
+}
+
+const handleDrop = (index, event) => {
+  event.preventDefault()
+  // 处理排序逻辑
+}
+
+const handleDragEnd = (event) => {
+  event.target.classList.remove('dragging')
+}
+</script>
+```
+
+## 配置验证规则
+
+### 前端验证
+1. **至少保留一个可见 Tab**: `visibleTabs.length >= 1`
+2. **默认 Tab 必须可见**: `visibleTabs.includes(defaultTab)`
+3. **禁用 Tab 不可取消选中**: `!tab.enabled` 时禁用复选框
+
+### 后端验证
+1. **JSON 格式验证**: 使用 `json.Unmarshal` 验证
+2. **业务规则验证**: 与前端相同
+3. **数据库错误处理**: 捕获并返回友好错误信息
+
+## 样式参考
+
+### 拖拽元素样式
+```css
+.tab-sort-item {
+  display: flex;
+  align-items: center;
+  padding: 12px;
+  background: var(--color-fill-1);
+  border: 1px solid var(--color-border);
+  border-radius: 4px;
+  cursor: move;
+  transition: all 0.2s;
+}
+
+.tab-sort-item.dragging {
+  opacity: 0.5;
+  background: var(--color-fill-2);
+  transform: scale(0.98);
+}
+
+.tab-sort-item:hover {
+  background: var(--color-fill-2);
+  border-color: var(--color-border-2);
+}
+```
+
+## 常见问题
+
+### Q: 如何添加新的 Tab？
+A: 在 `defaultTabConfig` 中添加新的 `TabDefinition`，并确保在前端 `getComponent` 方法中添加对应的组件映射。
+
+### Q: 如何禁用某个 Tab？
+A: 将 `TabDefinition.Enabled` 设置为 `false`，前端会自动显示"不可用"标签并禁用复选框。
+
+### Q: 配置存储在哪里？
+A: 配置存储在 SQLite 数据库中，位置：`~/.u-desk/app.db`（Windows: `C:\Users\你的用户名\.u-desk\app.db`），表名：`app_config`。
+
+### Q: 如何重置配置？
+A: 删除数据库中的 `tab_config` 记录，系统会自动使用默认配置。
+
+### Q: 拖拽功能不工作？
+A: 确保元素设置了 `draggable="true"` 属性，并且正确实现了所有拖拽事件处理函数。
+
+## 调试技巧
+
+### 查看当前配置
+```javascript
+console.log('应用配置:', appConfig.value)
+console.log('可见 Tabs:', visibleTabs.value)
+console.log('当前激活 Tab:', activeTab.value)
+```
+
+### 查看数据库
+```bash
+# Windows
+sqlite3 ~/.u-desk/app.db
+
+# 查询配置
+SELECT * FROM app_config WHERE key = 'tab_config';
+```
+
+### 重置配置
+```sql
+DELETE FROM app_config WHERE key = 'tab_config';
+```
+
+## 性能优化建议
+
+1. **减少重新渲染**: 使用 `computed` 属性缓存计算结果
+2. **防抖保存**: 对保存操作添加防抖，避免频繁保存
+3. **懒加载组件**: 使用 `<KeepAlive>` 缓存组件状态
+4. **批量更新**: 使用 `watch` 的 `deep` 选项时注意性能影响
+
+## 扩展建议
+
+### 1. 导出/导入配置
+```javascript
+// 导出
+const exportConfig = () => {
+  const data = JSON.stringify(appConfig.value)
+  const blob = new Blob([data], { type: 'application/json' })
+  const url = URL.createObjectURL(blob)
+  // 下载文件
+}
+
+// 导入
+const importConfig = (file) => {
+  const reader = new FileReader()
+  reader.onload = (e) => {
+    const config = JSON.parse(e.target.result)
+    // 保存配置
+  }
+  reader.readAsText(file)
+}
+```
+
+### 2. 键盘辅助
+```vue
+<a-button @click="moveUp(index)">
+  <template #icon><icon-up /></template>
+</a-button>
+<a-button @click="moveDown(index)">
+  <template #icon><icon-down /></template>
+</a-button>
+```
+
+### 3. 配置预览
+```vue
+<a-modal v-model:visible="showPreview" title="配置预览">
+  <div v-for="tab in visibleTabs" :key="tab.key">
+    {{ tab.title }}
+  </div>
+</a-modal>
+```