cdspec 0.1.0

package/templates/frontend-develop-standard/references/frontend_develop_standard.md

@@ -0,0 +1,749 @@
+# 前端开发规范
+
+## 一、Vue3 编码规范
+
+### 1.1 命名规范
+
+#### 1.1.1 组件命名
+
+**文件夹和文件名**
+- 使用小驼峰命名法（camelCase）
+- 示例：`testList/testList.vue`
+
+**组件引用**
+```vue
+<template>
+  <!-- 自闭合组件 -->
+  <test-component />
+
+  <!-- 包含内容的组件 -->
+  <container-component>
+    This is content
+  </container-component>
+</template>
+
+<script setup>
+import TestComponent from './components/TestComponent.vue'
+import ContainerComponent from './components/ContainerComponent.vue'
+</script>
+```
+
+#### 1.1.2 变量和常量命名
+
+**变量命名**
+- 使用小驼峰命名法（camelCase）
+- 语义化，见名知意
+
+```javascript
+// 推荐
+let userInfo = {}
+let infoList = []
+let isLoading = false
+
+// 不推荐
+let a = {}
+let data = []
+```
+
+**常量命名**
+- 使用全大写字母，单词间用下划线分隔
+- 语义化，见名知意
+
+```javascript
+// 推荐
+const MAX_NUMBER = 10
+const API_BASE_URL = 'https://api.example.com'
+const DEFAULT_PAGE_SIZE = 20
+
+// 不推荐
+const max = 10
+const url = 'https://api.example.com'
+```
+
+#### 1.1.3 接口类型命名
+
+接口类型以大写字母 `C` 为前缀：
+
+```typescript
+export interface CState {
+  roleList: Object
+  restartVisible: boolean
+  sid: string
+  dialogVisible: boolean
+  loading: boolean
+  list: CDevmemt[]
+  total: number
+  listQuery: CListQuery
+  name: string
+}
+
+export interface CStateParams extends CState {
+  id: string
+}
+```
+
+### 1.2 代码风格
+
+#### 1.2.1 引号使用规范
+
+- HTML 属性使用双引号 `""`
+- JavaScript 代码使用单引号 `''`
+
+```vue
+<template>
+  <test-component data-attributes="test" class="container" />
+</template>
+
+<script setup>
+const str = 'hello world'
+const message = 'This is a message'
+</script>
+```
+
+#### 1.2.2 多属性换行
+
+当元素有多个属性时，每个属性独占一行：
+
+```vue
+<template>
+  <a-table-column
+    data-index="name"
+    title="名称"
+    :width="180"
+    align="center"
+    :sorter="true"
+  />
+
+  <li
+    v-for="(item, index) in testList"
+    :key="index"
+    :span="4"
+    style="margin-bottom: 10px"
+  >
+    {{ item.name }}
+  </li>
+</template>
+```
+
+#### 1.2.3 组件样式作用域
+
+组件样式必须设置作用域，避免样式污染：
+
+```vue
+<style scoped lang="less">
+.test-list {
+  padding: 20px;
+
+  .test-item {
+    margin-bottom: 10px;
+  }
+}
+</style>
+```
+
+#### 1.2.4 样式穿透
+
+使用 `:deep()` 进行样式穿透：
+
+```vue
+<style scoped lang="less">
+:deep(.ant-card-body) {
+  padding: 20px;
+}
+
+:deep(.ant-table) {
+  .ant-table-thead {
+    background-color: #f5f7fa;
+  }
+}
+</style>
+```
+
+### 1.3 组件开发规范
+
+#### 1.3.1 生命周期钩子顺序
+
+按照执行顺序排列生命周期钩子：
+
+```vue
+<script setup lang="ts" name="componentName">
+import { onBeforeMount, onMounted, onBeforeUpdate, onUpdated, onBeforeUnmount, onUnmounted } from 'vue'
+
+// 1. 挂载前
+onBeforeMount(() => {
+  console.log('onBeforeMount')
+})
+
+// 2. 挂载后
+onMounted(() => {
+  console.log('onMounted')
+})
+
+// 3. 更新前
+onBeforeUpdate(() => {
+  console.log('onBeforeUpdate')
+})
+
+// 4. 更新后
+onUpdated(() => {
+  console.log('onUpdated')
+})
+
+// 5. 卸载前
+onBeforeUnmount(() => {
+  console.log('onBeforeUnmount')
+})
+
+// 6. 卸载后
+onUnmounted(() => {
+  console.log('onUnmounted')
+})
+</script>
+```
+
+#### 1.3.2 自定义事件命名
+
+- 事件名使用 `on-` 前缀 + 动词
+- 事件处理函数使用 `handle` 前缀 + 动词
+
+```vue
+<!-- 父组件 -->
+<template>
+  <my-component @on-change="handleChange" @on-submit="handleSubmit" />
+</template>
+
+<script setup>
+const handleChange = (value) => {
+  console.log('value changed:', value)
+}
+
+const handleSubmit = (data) => {
+  console.log('form submitted:', data)
+}
+</script>
+
+<!-- 子组件 -->
+<script setup>
+const emit = defineEmits(['on-change', 'on-submit'])
+
+const onChange = () => {
+  emit('on-change', newValue)
+}
+
+const onSubmit = () => {
+  emit('on-submit', formData)
+}
+</script>
+```
+
+### 1.4 注释规范
+
+#### 1.4.1 模板注释
+
+```vue
+<template>
+  <div>
+    <!-- 用户信息表单 -->
+    <a-form>
+      <!-- 用户名 -->
+      <a-form-item label="用户名" name="username">
+        <a-input v-model:value="form.username" />
+      </a-form-item>
+
+      <!-- 邮箱 -->
+      <a-form-item label="邮箱" name="email">
+        <a-input v-model:value="form.email" />
+      </a-form-item>
+    </a-form>
+  </div>
+</template>
+```
+
+#### 1.4.2 脚本注释
+
+```javascript
+// 删除用户
+const deleteUser = (id) => {
+  // 实现逻辑
+}
+
+// 新增用户
+const addUser = (userData) => {
+  // 实现逻辑
+}
+
+/**
+ * 更新用户信息
+ * @param {string} id - 用户ID
+ * @param {Object} userData - 用户数据
+ * @returns {Promise} 返回更新结果
+ */
+const updateUser = async (id, userData) => {
+  // 实现逻辑
+}
+```
+
+### 1.5 代码质量
+
+#### 1.5.1 移除调试代码
+
+提交代码前必须移除：
+- `console.log()`
+- `debugger`
+- 注释掉的无用代码
+
+```javascript
+// ❌ 不推荐
+const fetchData = () => {
+  console.log('fetching data...')
+  debugger
+  // const oldCode = 'something'
+  return api.getData()
+}
+
+// ✅ 推荐
+const fetchData = () => {
+  return api.getData()
+}
+```
+
+### 1.6 完整示例
+
+```vue
+<template>
+  <div class="user-form">
+    <a-card>
+      <a-form
+        ref="formRef"
+        :model="formState"
+        :rules="rules"
+        :label-col="{ span: 4 }"
+        :wrapper-col="{ span: 20 }"
+      >
+        <!-- 名称 -->
+        <a-form-item label="名称" name="name">
+          <a-input v-model:value="formState.name" placeholder="请输入名称" />
+        </a-form-item>
+
+        <!-- 标签 -->
+        <a-form-item label="标签" name="label">
+          <a-button type="link" @click="addLabel">
+            +添加一行
+          </a-button>
+          <span>(最多 20 个标签)</span>
+        </a-form-item>
+
+        <!-- 描述 -->
+        <a-form-item label="描述" name="describe">
+          <a-textarea
+            v-model:value="formState.describe"
+            :rows="2"
+            placeholder="请输入描述"
+          />
+        </a-form-item>
+
+        <!-- 操作按钮 -->
+        <a-form-item :wrapper-col="{ offset: 4, span: 20 }">
+          <a-button @click="handleCancel">取消</a-button>
+          <a-button type="primary" @click="handleSubmit" style="margin-left: 10px">
+            确认
+          </a-button>
+        </a-form-item>
+      </a-form>
+    </a-card>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { reactive, ref } from 'vue'
+import type { FormInstance, Rule } from 'ant-design-vue/es/form'
+import { useRouter, useRoute } from 'vue-router'
+import { activationApi } from '/@/api/devmgmt'
+
+const route = useRoute()
+const router = useRouter()
+
+const uuid = route.query.uuid
+const type = route.query.type
+
+const formRef = ref<FormInstance>()
+const formState = reactive({
+  name: '',
+  label: [{ label: '' }],
+  longitude: '',
+  latitude: '',
+  address: '',
+  describe: ''
+})
+
+// 表单验证规则
+const rules: Record<string, Rule[]> = {
+  name: [
+    { required: true, message: '请输入设备名称', trigger: 'blur' }
+  ]
+}
+
+// 新增标签
+const addLabel = () => {
+  if (formState.label.length < 20) {
+    formState.label.push({ label: '' })
+  }
+}
+
+// 删除标签
+const removeLabel = (item: any) => {
+  const index = formState.label.indexOf(item)
+  if (index !== -1) {
+    formState.label.splice(index, 1)
+  }
+}
+
+// 取消操作
+const handleCancel = () => {
+  router.back()
+}
+
+// 提交表单
+const handleSubmit = async () => {
+  if (!formRef.value) return
+
+  try {
+    await formRef.value.validate()
+    const label = formState.label.map(item => item.label).filter(Boolean)
+
+    const params = {
+      sid: uuid,
+      name: formState.name,
+      type: type,
+      address: formState.address,
+      longitude: parseFloat(formState.longitude),
+      latitude: parseFloat(formState.latitude),
+      detail: formState.describe,
+      label: label
+    }
+
+    activationApi(params).then((res: any) => {
+      // 处理成功逻辑
+    })
+  } catch (error) {
+    console.log('验证失败:', error)
+  }
+}
+</script>
+
+<style scoped lang="scss">
+.user-form {
+  padding: 20px;
+
+  .width120 {
+    width: 120px;
+  }
+
+  .latitude-text .width300 {
+    width: 300px;
+    margin: 0 10px 0 22px;
+  }
+}
+</style>
+```
+
+---
+
+## 二、项目配置规范
+
+### 2.1 EditorConfig 配置
+
+EditorConfig 帮助团队维护一致的编码风格。
+
+在项目根目录创建 `.editorconfig` 文件：
+
+```ini
+# http://editorconfig.org
+
+root = true
+
+[*]
+charset = utf-8
+indent_style = space
+indent_size = 2
+end_of_line = lf
+trim_trailing_whitespace = true
+insert_final_newline = true
+
+[*.md]
+max_line_length = off
+trim_trailing_whitespace = false
+```
+
+**配置说明：**
+- `charset`: 文件字符集为 UTF-8
+- `indent_style`: 缩进风格（space 或 tab）
+- `indent_size`: 缩进大小为 2 个空格
+- `end_of_line`: 换行符类型（lf、cr 或 crlf）
+- `trim_trailing_whitespace`: 去除行尾空白字符
+- `insert_final_newline`: 文件末尾插入新行
+
+**VSCode 插件：** 需安装 `EditorConfig for VS Code`
+
+### 2.2 Prettier 配置
+
+Prettier 是强大的代码格式化工具，支持多种前端语言。
+
+在项目根目录创建 `.prettierrc` 文件：
+
+```json
+{
+  "useTabs": false,
+  "tabWidth": 2,
+  "printWidth": 80,
+  "singleQuote": true,
+  "trailingComma": "none",
+  "semi": false
+}
+```
+
+**配置说明：**
+
+| 属性 | 说明 |
+|------|------|
+| useTabs | false: 使用空格缩进，true: 使用 tab 缩进 |
+| tabWidth | 缩进空格数，设置为 2 |
+| printWidth | 单行最大字符数，推荐 80 或 100 |
+| singleQuote | true: 使用单引号，false: 使用双引号 |
+| trailingComma | 多行输入尾逗号，设置为 none |
+| semi | false: 不加分号，true: 加分号 |
+
+**VSCode 插件：** 需安装 `Prettier - Code formatter`
+
+**常见问题：**
+
+1. **保存代码无法格式化**
+   - 原因：未设置默认格式化插件
+   - 解决：右键 → 格式化文档 → 选择 Prettier
+
+2. **保存无法自动格式化**
+   - 原因：未开启保存时格式化
+   - 解决：文件 → 设置 → 搜索 "Format On Save" → 勾选
+
+**快速格式化所有文件：**
+
+在 `package.json` 添加脚本：
+
+```json
+{
+  "scripts": {
+    "prettier": "prettier --write ."
+  }
+}
+```
+
+运行命令：
+
+```bash
+npm run prettier
+```
+
+### 2.3 Prettier 忽略配置
+
+在项目根目录创建 `.prettierignore` 文件：
+
+```
+/dist/*
+.local
+.output.js
+/node_modules/**
+**/*.svg
+**/*.sh
+/public/*
+```
+
+### 2.4 ESLint 配置
+
+Vue 项目创建时会自动配置 ESLint。
+
+**VSCode 插件：** 需安装 `ESLint`
+
+**解决 ESLint 和 Prettier 冲突：**
+
+安装插件（Vue 创建项目时选择 Prettier 会自动安装）：
+
+```bash
+npm install eslint-plugin-prettier eslint-config-prettier -D
+```
+
+在 `.eslintrc.js` 文件的 `extends` 中添加：
+
+```javascript
+module.exports = {
+  extends: [
+    // ... 其他配置
+    'plugin:prettier/recommended'
+  ]
+}
+```
+
+**注意：** `plugin:` 和 `prettier` 之间没有空格
+
+---
+
+## 三、Git 提交规范
+
+### 3.1 Husky 配置
+
+Husky 用于在 Git 操作时触发钩子。
+
+**安装 Husky：**
+
+```bash
+npm install husky -D
+```
+
+**配置 prepare 脚本：**
+
+```bash
+npm set-script prepare "husky install"
+npm run prepare
+```
+
+**添加 pre-commit 钩子：**
+
+```bash
+npx husky add .husky/pre-commit "npx eslint ./"
+```
+
+如果自动生成失败，手动创建 `.husky/pre-commit` 文件：
+
+```bash
+#!/bin/sh
+. "$(dirname "$0")/_/husky.sh"
+
+npx eslint ./
+```
+
+### 3.2 Commitlint 配置
+
+**安装 Commitlint：**
+
+```bash
+npm install --save-dev @commitlint/config-conventional @commitlint/cli
+```
+
+**创建配置文件：**
+
+```bash
+echo "module.exports = {extends: ['@commitlint/config-conventional']}" > commitlint.config.js
+```
+
+**注意：** 确保文件编码为 UTF-8
+
+**添加 commit-msg 钩子：**
+
+```bash
+npx husky add .husky/commit-msg "npx --no -- commitlint --edit ${1}"
+```
+
+如果自动生成失败，手动创建 `.husky/commit-msg` 文件：
+
+```bash
+#!/bin/sh
+. "$(dirname "$0")/_/husky.sh"
+
+npx --no-install commitlint --edit $1
+```
+
+**禁用 Husky（如需要）：**
+
+在 `.git/config` 文件中注释掉：
+
+```
+# hooksPath = .husky
+```
+
+### 3.3 Commit 提交规范
+
+**提交类型说明：**
+
+| 类型 | 说明 |
+|------|------|
+| feat | 新增功能 |
+| fix | 修复 Bug |
+| docs | 文档更新 |
+| style | 代码格式调整（不影响功能） |
+| refactor | 代码重构 |
+| perf | 性能优化 |
+| test | 测试相关 |
+| chore | 构建过程或辅助工具的变动 |
+| revert | 回滚提交 |
+| build | 影响构建系统或外部依赖 |
+| ci | CI 配置文件和脚本的变动 |
+| types | 类型定义文件更改 |
+| wip | 开发中（work in progress） |
+
+**提交格式：**
+
+```bash
+git commit -m "type: description"
+```
+
+**示例：**
+
+```bash
+# 新增功能
+git commit -m "feat: 添加用户登录功能"
+
+# 修复 Bug
+git commit -m "fix: 修复用户列表分页问题"
+
+# 文档更新
+git commit -m "docs: 更新 API 文档"
+
+# 代码重构
+git commit -m "refactor: 重构用户模块代码结构"
+
+# 性能优化
+git commit -m "perf: 优化列表渲染性能"
+```
+
+**完整格式（可选）：**
+
+```bash
+git commit -m "feat: 添加用户登录功能
+
+- 实现用户名密码登录
+- 添加记住密码功能
+- 集成第三方登录"
+```
+
+---
+
+## 四、最佳实践建议
+
+### 4.1 代码组织
+
+- 按功能模块组织代码，而非按文件类型
+- 保持组件单一职责
+- 合理拆分大型组件
+- 复用性高的代码抽取为公共组件或工具函数
+
+### 4.2 性能优化
+
+- 合理使用 `v-if` 和 `v-show`
+- 列表渲染使用唯一 `key`
+- 避免在模板中使用复杂表达式
+- 使用 `computed` 缓存计算结果
+- 大型列表使用虚拟滚动
+
+### 4.3 安全规范
+
+- 避免使用 `v-html`，防止 XSS 攻击
+- 敏感信息不要硬编码在前端
+- API 请求添加适当的权限验证
+- 用户输入进行验证和过滤
+
+### 4.4 可维护性
+
+- 编写清晰的注释
+- 保持代码简洁易读
+- 遵循团队统一的编码规范
+- 定期进行代码审查
+- 及时更新文档