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 空格缩进。
• 样式采用普通 CSS；类名使用 kebab-case；布局和组件私有样式就近放在对应组件中。

Electron 分层

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

ESLint

• 使用 @electron-toolkit/eslint-config 与 Vue 推荐规则作为基础。
• Vue 组件允许单词名称；未强制默认 Prop；模板单行或多行内容换行规则已关闭。
• 提交前执行 pnpm lint，并修复实际报告的问题。