frost-mqtt-client/docs/代码风格.md

# 代码风格

## 基础格式

- 使用 UTF-8、LF 换行、2 个空格缩进；文件末尾保留换行，删除行尾空白。
- JavaScript、Vue SFC 使用分号结尾。
- 字符串通常使用单引号；模板属性和值使用双引号。
- 对象、数组尾项保留逗号。
- 复杂函数的函数体内常使用空行分隔初始化、分支和返回逻辑；保持与所在文件一致即可。

## JavaScript

- 使用 ES Module：`import` / `export`。
- 导入顺序通常为：框架或第三方依赖、项目内部模块、资源文件；不同分组之间空一行。
- 变量优先使用 `const`；需要重新赋值的局部变量使用 `let`；不使用 `var`。
- 函数以具名 `function` 声明为主；回调和简单映射使用箭头函数。
- 命名使用 camelCase：变量、函数、方法和参数均使用英文语义名称；布尔值常以 `is`、`show`、`has` 等开头。
- 常量或配置集合也多使用 camelCase，例如 `protocolOptions`、`themeOverrides`。
- 错误处理使用 `try...catch`，错误信息通过中文 `console.error` 或界面消息反馈。

## 注释与类型

- 注释、JSDoc 说明和面向用户的提示文案使用简体中文。
- 按职责使用 `// ==================== 模块名 ====================` 分隔较长的文件。
- 公开方法、重要状态和较复杂逻辑使用 JSDoc 描述用途、参数和返回值。
- JavaScript 项目通过 JSDoc 引入或声明类型，例如 `@typedef`、`@param`、`@returns`，公共 MQTT 类型集中引用 `types/jsdoc.d.ts`。
- 简单实现可配合单行中文注释说明意图，避免重复描述显而易见的代码。

## Vue 组件

- 单文件组件按 `<script setup>`、`<template>`、`<style>` 的顺序组织。
- 组件文件使用 PascalCase，例如 `ServerModal.vue`；组件在模板中同样使用 PascalCase。
- `script setup` 中通常依次放置：导入、Props/Emits、响应式状态、静态配置、侦听或生命周期、事件处理函数。
- 事件处理函数以 `handle` 开头，例如 `handleSave`；模板事件名采用 kebab-case，例如 `@edit-server`。
- Naive UI 组件使用 `NButton` 等 PascalCase 导入，在模板中写为 `n-button`。
- 模板属性一行较长时换行，每个属性单独一行，并保持 2 空格缩进。
- 元素标签内文本简短时，将文本与结束标签放在同一行；较长表达式或动态内容可单独成行。
- 样式使用 Less；Vue SFC 中通过 `<style lang="less">` / `<style lang="less" scoped>` 声明。
- 类名使用 kebab-case；布局和组件私有样式就近放在对应组件中。
- 善用嵌套规则、`&` 父选择器减少重复；全局主题色等公共变量在 App.vue 中通过 CSS 自定义属性定义，命名与 `themeOverrides` 对应（例如 `--frost-primary-color`）。
- 组件内直接使用 `var(--xxx)` 引用全局变量，不再单独定义 Less 变量。

## Electron 分层

- `src/main` 处理窗口、IPC 与 MQTT 等主进程逻辑。
- `src/preload` 统一封装并暴露 `window.api`，渲染进程不直接使用 Electron IPC。
- `src/renderer` 放置 Vue 页面、组件和状态管理；通过 `window.api` 调用主进程能力。

## ESLint

- 使用 `@electron-toolkit/eslint-config` 与 Vue 推荐规则作为基础。
- 提交前执行 `pnpm lint`，并修复实际报告的问题。