Vibe Coding 个人规范

Vue

- 复用两处及以上的稳定业务结构才抽取组件，避免无意义的包装组件。
- 组件文件顶部说明用途；存在 props、事件或暴露方法时同时说明接口。
- 注释使用中文，重点说明业务原因、边界和跨端差异，不重复解释直观代码。
- 子元素 class 使用父容器作用域内的短语义 class，例如 `balance`、`detail`、`label`、`value`。
- 禁止使用 BEM 双下划线或双连字符命名，例如 `wallet-hero__balance`、`detail--active`；状态类统一使用 `is-*`，例如 `is-active`、`is-disabled`。
- SCSS 必须按模板父子结构嵌套子类，不得使用 `&` 拼接元素类名，也不得在父级之外重复完整路径。标准写法：

```scss
.wallet-hero {
    .balance {
        // 余额区域样式。
    }

    .detail {
        .label {
            // 明细标签样式。
        }

        .value {
            // 明细数值样式。
        }
    }
}
```

PHP

## 代码注释

- {}内只有一行的，省略大括号（如果可以省略），在一行
- 数组返回值以及数组配置参数，要用 `# 单行注释` 说明字段含义

```php
 if (!is_dir($target_dir)) return "创建目录失败：$target_dir";

 return [
    # 压缩包内有多少文件
    'file' => 0,
    # $source_path 中有多少目录
    'dir' => 0,
    # 既不是文件，也不是目录的路径
    'invalid' => [],
];
```

- 中文注释，对于已有的英文注释，改成中文注释
- 添加的代码必须要有注释。对于复杂抽象的，用多行注释详细说明，方便下一人接手和维护。
- config 内的配置，每个字段必须有单行双斜杠注释，说明字段含义，以及可选值
- 类的方法和单独的函数，都要有多行注释说明函数的用途以及参数和返回值
- 类里的属性，用单行注释 `# 注释xxx` 说明属性含义

注释示例如下：

```php
// 单行注释

/**
 * 多行注释，渲染项目申请分页列表。常规注释。不需要有空行，无论什么时候@param和@return是一个整体，他俩之间无需空行
 * @param Request $request 当前请求。
 * @return Response 申请列表模板。
 */

/**
 * 安全下载远程文件，返回类似 $_FILES 的数组。
 * 该函数只负责：
 * 1. 使用 WordPress 原生接口下载远程文件；
 * 2. 检测文件真实 MIME 类型；
 * 3. 根据允许上传的 MIME 类型确定扩展名；
 * 4. 组装成 wu_upload_file() 可以继续处理的文件数组。
 * 函数说明有多行，此时下方的@param就要有空行
 *
 * @param string $url  远程文件 URL。
 * @return array{
 *     name: string,
 *     type: string,
 *     tmp_name: string,
 *     error: int|string,
 *     size: int,
 *     ext: string
 * }
 *
 * @see unlink 删除临时文件
 * @see download_url wp自带安全下载文件
 * @see media_sideload_image wp专门处理图片，而且远程 URL 通常需要包含可识别的图片扩展名
 * @see media_handle_upload 处理 $_FILES，写入媒体库并生成附件元数据。
 * @see media_handle_sideload 处理远程普通文件，但需要自己准备类似 $_FILES 的数组。
 */

/** 必须用多行注释，但只有一行的，这样写：@use HasFactory<SettingFactory> */


```