jsharness 1.11.0 → 1.12.2

package/files/front-coding-rules.md

@@ -0,0 +1,665 @@
+---
+description: 通用前端开发规范（CSS / JavaScript / TypeScript / 模块化），适用于所有前端项目；项目专属规范（技术栈版本、目录结构、组件约定等）请配合具体项目规则文件
+alwaysApply: true
+enabled: true
+Source:
+  HarnessRule: rules/project/frontend-coding-basics.md
+  Relation: 本文件为公司原始规范归档，.harness/rules/project/frontend-coding-basics.md 为去重精简版（与 coding-standard.md 和 frontend-vue3.md 去重后）
+---
+
+# 通用前端开发规范
+
+> 版本：v1.0.0 | 适用范围：所有前端项目（HTML / CSS / JavaScript / TypeScript）
+> 说明：本规范为通用约束，**项目专属约束**（技术栈选型、目录结构、Vue/React 组件命名、状态管理、构建工具等）请参考各项目对应的项目规则文件（如 `frontend-project-rules.md`），两者必须同时遵守。
+
+---
+
+## 一、CSS 编码规范
+
+### 1.1 BEM 命名规范
+
+class 命名使用 BEM（Block、Element、Modifier），使用 `__` 与 `--` 连接：
+
+```css
+.block {}                  /* 块 */
+.block__element {}         /* 元素 */
+.block--modifier {}        /* 修饰符 */
+```
+
+**为什么使用 BEM？** CSS 引擎查找样式表按从右到左顺序匹配，BEM 可减少嵌套层级，提升性能。
+
+```css
+/* ❌ 错误：深层嵌套 */
+.main .content .title .name { color: #fff; }
+
+/* ✅ 正确：BEM 扁平化 */
+.main-title .name { color: #fff; }
+```
+
+### 1.2 样式属性顺序
+
+按照以下顺序书写属性：
+
+1. **布局位置**（position, top, right, z-index, display, float 等）
+2. **尺寸大小**（width, height, padding, margin）
+3. **文字系列**（font, line-height, letter-spacing, color, text-align 等）
+4. **视觉效果**（background, border 等）
+5. **其他**（animation, transform 等）
+
+```css
+/* ❌ 错误 */
+.header {
+    background: #CCC;
+    font-size: 20px;
+    height: 50px;
+    border: 1px solid #bbb;
+    position: absolute;
+    left: 0;
+    top: 0;
+    width: 100%;
+}
+
+/* ✅ 正确 */
+.header {
+    position: absolute;
+    left: 0;
+    top: 0;
+    width: 100%;
+    height: 50px;
+    font-size: 20px;
+    color: #f94000;
+    background: #CCC;
+    border: 1px solid #bbb;
+}
+```
+
+### 1.3 选择器规范
+
+- 选择器嵌套层级不大于 **3 级**
+- 避免使用 ID 选择器及全局标签选择器
+- CSS 选择器中避免使用标签名
+- 尽量不要使用 `@import`（与 `<link>` 相比速度较慢）
+
+```css
+/* ❌ 错误 */
+div { padding-bottom: 0px; margin: 0em; }
+button { border: 1px solid #ccc; }
+
+/* ✅ 正确 */
+.header { padding-bottom: 0px; margin: 0em; }
+.custom-form { margin: 20px; }
+```
+
+### 1.4 规则声明块样式规范
+
+1. 每条样式独占一行
+2. 列表属性用逗号分隔，逗号后必须跟空格
+3. 选择器与左大括号 `{` 之间必须加空格
+4. 属性名与冒号之间不允许包含空格，冒号与属性值之间必须包含空格
+5. 每条样式以分号 `;` 结尾
+6. 右大括号 `}` 独占一行
+7. 每个规则声明间用空行分隔
+
+### 1.5 数值与长度规范
+
+```css
+/* ✅ 0-1 小数省略整数部分的 0 */
+.panel { opacity: .8; }
+
+/* ✅ 长度为 0 时省略单位 */
+.list { padding: 0 5px; }
+
+/* ✅ 颜色缩写 */
+.header { color: #f40; }     /* 非 #ff4400 */
+
+/* ❌ 避免使用命名色值 */
+.button--success { color: lightgreen; }
+```
+
+### 1.6 字体排版规范
+
+- 字号应不小于 **12px**（Windows 平台中文显示限制）
+- `font-weight` 使用数值方式（如 `700` 而非 `bold`）
+- `line-height` 使用数值而非像素值（浏览器会基于 font-size 自动计算）
+
+```css
+/* ❌ 错误 */
+.title { font-weight: bold; }
+.container { line-height: 15px; }
+
+/* ✅ 正确 */
+.title { font-weight: 700; }
+.container { line-height: 1.5; }
+```
+
+### 1.7 其他 CSS 规范
+
+- 除公共样式外，业务代码中尽量不使用 `!important`
+- 建议 z-index 分层管理
+- Media Query 不得单独编排，须与相关规则一起定义
+- 变量集中配置在全局变量中，方便统一管理
+
+---
+
+## 二、JavaScript / TypeScript 规范
+
+### 2.1 命名约定
+
+| 类型 | 规范 | 示例 |
+|------|------|------|
+| 普通 | camelCase | `userData`, `handleClick` |
+| 事件处理函数 | `handle` 前缀 | `handleSubmit`, `handleDelete`, `handleSearch` |
+| 布尔值 | `is`/`has`/`can` 前缀 | `isLoading`, `hasError`, `canEdit` |
+| 常量 | UPPER_SNAKE_CASE | `MAX_COUNT`, `API_BASE_URL` |
+
+### 2.2 对象规范
+
+#### 2.2.1 使用字面量值创建对象
+
+```javascript
+// ❌ 错误
+const obj = new Object()
+
+// ✅ 正确
+const obj = {}
+```
+
+#### 2.2.2 对象属性简写
+
+```javascript
+const job = 'FrontEnd'
+
+// ❌ 错误
+const item = { job: job }
+
+// ✅ 正确
+const item = { job }
+```
+
+#### 2.2.3 对象拷贝 — 优先使用展开运算符
+
+```javascript
+// ❌ 错误
+const copy = Object.assign({}, original, { c: 3 })
+
+// ✅ 正确
+const copy = { ...original, c: 3 }
+const { a, ...noA } = copy  // noA => { b: 2, c: 3 }
+```
+
+#### 2.2.4 非法标识符引号
+
+只对非法标识符的属性使用引号：
+
+```javascript
+// ❌ 错误
+const bad = { 'foo': 3, 'bar': 4, 'data-blah': 5 }
+
+// ✅ 正确
+const good = { foo: 3, bar: 4, 'data-blah': 5 }
+```
+
+#### 2.2.5 属性访问
+
+使用 `.` 来访问对象属性：
+
+```javascript
+const joke = { name: 'haha', age: 28 }
+
+// ❌ 错误
+const name = joke['name']
+
+// ✅ 正确
+const name = joke.name
+```
+
+### 2.3 数组规范
+
+#### 2.3.1 创建数组 — 使用字面量
+
+```javascript
+// ❌ 错误
+const items = new Array()
+
+// ✅ 正确
+const items = []
+```
+
+#### 2.3.2 添加元素 — 使用 push
+
+```javascript
+const items = []
+// ❌ 错误
+items[items.length] = 'test'
+
+// ✅ 正确
+items.push('test')
+```
+
+#### 2.3.3 复制数组 — 使用展开运算符
+
+```javascript
+// ❌ 错误：手动循环复制
+// ✅ 正确
+itemsCopy = [...items]
+```
+
+#### 2.3.4 类数组转数组 — 使用 Array.from
+
+```javascript
+const arrLike = { 0: 'foo', 1: 'bar', 2: 'baz', length: 3 }
+
+// ❌ 错误
+const arr = Array.prototype.slice.call(arrLike)
+
+// ✅ 正确
+const arr = Array.from(arrLike)
+```
+
+#### 2.3.5 数组解构赋值
+
+```javascript
+const arr = [1, 2, 3, 4]
+
+// ❌ 错误
+const first = arr[0]
+const second = arr[1]
+
+// ✅ 正确
+const [first, second] = arr
+```
+
+#### 2.3.6 数组 map 方法 — 必须有 return
+
+```javascript
+// ❌ 错误
+[[0, 1], [2, 3]].reduce((memo, item) => {
+  const flatten = memo.concat(item)
+})
+
+// ✅ 正确
+[1, 2, 3].map(x => x + 1)
+
+[1, 2, 3].map(x => {
+  const y = x + 1
+  return x * y
+})
+```
+
+### 2.4 字符串规范
+
+#### 2.4.1 定义 — 统一使用单引号
+
+```javascript
+// ❌ 错误
+const department = "JDC"
+
+// ✅ 正确
+const department = 'JDC'
+```
+
+#### 2.4.2 动态生成 — 使用模板字符串
+
+```javascript
+const test = 'test'
+
+// ❌ 错误
+const str = ['a', 'b', test].join()
+const str = 'a' + 'b' + test
+
+// ✅ 正确
+const str = `ab${test}`
+```
+
+#### 2.4.3 谨慎使用 eval()
+
+尽量不要对字符串使用 `eval()`，会导致安全漏洞。
+
+### 2.5 函数规范
+
+#### 2.5.1 函数签名和函数体之间使用空格
+
+```javascript
+// ❌ 错误
+const f = function(){}
+const g = function (){}
+
+// ✅ 正确
+const x = function b() {}
+const y = function a() {}
+```
+
+#### 2.5.2 不要使用 Function 构造函数创建函数
+
+```javascript
+// ❌ 错误
+const add = new Function('a', 'b', 'return a + b')
+
+// ✅ 正确
+const add = (a, b) => a + b
+```
+
+#### 2.5.3 不要在非函数代码块中声明函数
+
+```javascript
+// ❌ 错误
+if (isUse) {
+  function test() { /* ... */ }
+}
+
+// ✅ 正确
+let test
+if (isUse) {
+  test = () => { /* ... */ }
+}
+```
+
+#### 2.5.4 不要使用 arguments，使用剩余运算符 ...
+
+```javascript
+// ❌ 错误
+function test() {
+  const args = Array.prototype.slice.call(arguments)
+  return args.join('')
+}
+
+// ✅ 正确
+function test(...args) {
+  return args.join('')
+}
+```
+
+#### 2.5.5 使用参数默认值语法
+
+```javascript
+// ❌ 错误
+function handleThings(opts) {
+  opts = opts || {}
+}
+
+// ✅ 正确
+function handleThings(opts = {}) {}
+```
+
+#### 2.5.6 将默认值的参数放在最后
+
+```javascript
+// ❌ 错误
+function handleThings(opts = {}, name) {}
+
+// ✅ 正确
+function handleThings(name, opts = {}) {}
+```
+
+#### 2.5.7 不要更改参数和对参数重新赋值
+
+```javascript
+// ❌ 错误
+const foo = function(bar) {
+  bar = 13
+}
+
+// ✅ 正确
+const foo = function(bar) {
+  let baz = bar
+}
+```
+
+### 2.6 箭头函数规范
+
+#### 2.6.1 使用场景 — 传递匿名函数时优先使用箭头函数
+
+```javascript
+// ❌ 错误
+[1, 2, 3].map(function (x) {
+  return x + 1
+})
+
+// ✅ 正确
+[1, 2, 3].map((x) => x + 1)
+```
+
+#### 2.6.2 简写规则
+
+- 函数体只包含一条无副作用的返回表达式 → 省略花括号，隐式 return
+- 否则 → 保留花括号并使用 return 语句
+
+```javascript
+// ✅ 正确：单一表达式
+[1, 2, 3].map(number => `A string containing the ${number}.`)
+
+// ✅ 正确：多行语句
+[1, 2, 3].map((number) => {
+  const nextNumber = number + 1
+  return `A string containing the ${nextNumber}.`
+})
+
+// ✅ 正确：返回对象需加括号
+[1, 2, 3].map((number, index) => ({ index: number }))
+```
+
+### 2.7 Switch 规范
+
+每个 case 做好防穿透处理（break），最后必须有 default 默认出口：
+
+```javascript
+// ❌ 错误
+switch (foo) {
+  case 1:
+    bar()
+    break
+  default:
+    baz()
+    break
+  case 2:
+    quux()  // 缺少 break
+    break
+}
+
+// ✅ 正确
+switch (foo) {
+  case 1:
+    bar()
+    break
+  case 2:
+    quux()
+    break
+  default:
+    baz()
+    break
+}
+```
+
+### 2.8 ES6 语法规范
+
+开发中优先使用 ES6 新增语法糖和函数简化代码逻辑，使代码灵活可复用：
+
+- **箭头函数** → 匿名函数场景
+- **await/async** → 异步操作
+- **解构赋值** → 对象、数组取值
+- **let/const** → 变量声明（优先 const）
+- **for...of** → 迭代遍历
+- **展开运算符 ...** → 对象/数组拷贝、合并
+
+### 2.9 TypeScript 类型规范
+
+- 优先使用具体类型，避免滥用 `any`
+- 不确定类型时使用 `unknown` 而非 `any`
+- 接口（interface）用于描述对象结构，类型别名（type）用于联合类型/工具类型
+- 公共 API 入参/出参 MUST 显式声明类型
+
+```typescript
+// ❌ 错误
+function process(data: any): any { return data }
+
+// ✅ 正确
+interface UserData { id: string; name: string }
+function process(data: UserData): UserData { return data }
+```
+
+---
+
+## 三、模块化开发规范
+
+### 3.1 使用标准 ES6 模块语法
+
+```javascript
+// ❌ 错误
+const util = require('./util')
+module.exports = util
+
+// ✅ 正确
+import Util from './util'
+export default Util
+
+// 更好
+import { Util } from './util'
+```
+
+### 3.2 确保只有一个默认 export
+
+```javascript
+// ❌ 错误
+import * as Util from './util'
+
+// ✅ 正确
+import Util from './util'
+```
+
+### 3.3 同个文件每个模块只允许 import 一次
+
+```javascript
+// ❌ 错误
+import foo from 'foo'
+// ... 其他 imports ...
+import { named1, named2 } from 'foo'
+
+// ✅ 正确
+import foo, { named1, named2 } from 'foo'
+```
+
+### 3.4 import 语句放在文件最前方
+
+```javascript
+// ❌ 错误
+import foo from 'foo'
+foo.init()
+import bar from 'bar'
+
+// ✅ 正确
+import foo from 'foo'
+import bar from 'bar'
+
+foo.init()
+```
+
+### 3.5 多行导入格式
+
+多行导入像多行数组和对象一样缩进：
+
+```javascript
+// ❌ 错误
+import { longNameA, longNameB, longNameC, longNameD, longNameE } from 'path'
+
+// ✅ 正确
+import {
+  longNameA,
+  longNameB,
+  longNameC,
+  longNameD,
+  longNameE
+} from 'path'
+```
+
+### 3.6 禁止在 import 声明中使用 Webpack loader 语法
+
+```javascript
+// ❌ 错误
+import fooSass from 'css!sass!foo.scss'
+
+// ✅ 正确
+import fooSass from 'foo.scss'
+```
+
+---
+
+## 四、注释规范
+
+### 4.1 函数注释（JSDoc）
+
+```typescript
+/** 打开创建弹窗 */
+function openCreate(): void { ... }
+
+/**
+ * 提交表单
+ * @param form - 表单数据
+ * @param isEdit - 是否编辑模式
+ */
+async function submitForm(form: any, isEdit: boolean): Promise<void> { ... }
+```
+
+### 4.2 文件级注释
+
+每个公共模块/工具文件 MUST 在顶部添加文件级注释，说明文件用途：
+
+```typescript
+/**
+ * HTTP 请求工具
+ * 封装 Axios 实例，统一处理 token、错误码、响应拦截
+ */
+```
+
+### 4.3 注释要点
+
+- 注释内容 MUST 准确描述业务语义，禁止无意义注释（如 `// 处理` / `// 操作`）
+- 复杂业务逻辑 MUST 添加注释，说明 **为什么** 这么做，而非 **做了什么**
+- 已废弃代码 MUST 删除，禁止注释保留
+
+---
+
+## 五、通用禁止事项清单（MUST NOT）
+
+| 编号 | 规则 | 说明 |
+|------|------|------|
+| C001 | 禁止滥用 `any` | 优先使用具体类型或 `unknown` |
+| C002 | 禁止使用 `new Object()` / `new Array()` | 使用字面量 `{} / []` |
+| C003 | 禁止使用 `eval()` | 存在安全漏洞 |
+| C004 | 禁止深层 CSS 嵌套（>3 层） | 使用 BEM 命名扁平化 |
+| C005 | 禁止全局标签选择器修改样式 | 使用类名选择器 |
+| C006 | 禁止在非函数块中声明函数 | 改用变量赋值箭头函数 |
+| C007 | 禁止使用 `arguments` | 使用剩余参数 `...args` |
+| C008 | 禁止重复 import 同一模块 | 合并为单条 import 语句 |
+| C009 | 禁止使用 `var` 声明变量 | 优先使用 `const`，必要时用 `let` |
+| C010 | 禁止使用双引号定义字符串 | 统一使用单引号，动态字符串使用模板字符串 |
+| C011 | 禁止 Switch 缺少 default 分支 | 必须包含 default 默认出口 |
+| C012 | 禁止 import 后再添加 import | import 语句必须置于文件顶部 |
+
+---
+
+## 六、通用最佳实践检查清单
+
+在提交代码前，逐项确认：
+
+**样式规范**
+- [ ] CSS 选择器嵌套不超过 3 层
+- [ ] 样式属性按 布局→尺寸→文字→视觉→其他 顺序排列
+- [ ] 使用 BEM 命名规范组织 class
+- [ ] 字号不小于 12px，font-weight 使用数值
+
+**JS/TS 规范**
+- [ ] 函数命名遵循 `handleXxx` 事件处理 / `isXxx` 布尔值 规范
+- [ ] 优先使用 ES6 语法（箭头函数、解构、展开运算符等）
+- [ ] 对象/数组使用字面量创建
+- [ ] 常量使用 UPPER_SNAKE_CASE 命名
+- [ ] 字符串统一使用单引号
+- [ ] Switch 语句包含 default 分支
+- [ ] import 语句置于文件顶部，无重复导入
+- [ ] TypeScript 不滥用 `any`，公共 API 类型显式声明
+
+**注释规范**
+- [ ] 公共函数添加 JSDoc 注释
+- [ ] 复杂业务逻辑添加说明性注释
+- [ ] 无废弃注释代码
+
+> 项目专属检查项（如 Vue/React 组件规范、状态管理、目录结构、构建工具等）请参考具体项目规则文件。