# 编码规范（字符编码）

> 本规则因一次事故而立：批量改包名时用了非 UTF-8 感知的脚本，把中文注释整成乱码（`鐗堟湰`=版本、`寰湇鍔`=微服务），且引入 BOM。以下为硬性约束。

## 不变式（违反即 Bug）

1. **所有源码/配置/文本文件一律 UTF-8 编码**：`.java` `.xml` `.yml` `.yaml` `.properties` `.sql` `.md` `.vue` `.ts` `.js` `.json` 等。
2. **禁止 BOM**：UTF-8 文件不得带 BOM（`EF BB BF`）。BOM 会让 XML/YAML 解析、shell 脚本、diff 出错。
3. **禁止 GBK / GB2312 / GB18030 / Latin1 落盘**：任何环节（编辑器、脚本、终端重定向）都不得以非 UTF-8 写文件。
4. **禁止用非 UTF-8 感知的工具批量改写文本**：如必须批量替换，工具必须显式按 UTF-8 读、UTF-8 写（Python 用 `io.open(p, encoding='utf-8')`；`sed`/`grep` 在 UTF-8 locale 下运行）。
5. **换行**：统一 LF（`\n`），`.gitattributes` 固化，避免 CRLF 混入触发整文件 diff。

## 构建/工程配置（必须存在）

- **Maven**：父 pom 设
  ```xml
  <properties>
    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    <project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding>
  </properties>
  ```
- **`.editorconfig`**（后端仓库和前端仓库根目录各一个 `.editorconfig` 文件）：
  ```
  root = true
  [*]
  charset = utf-8
  end_of_line = lf
  insert_final_newline = true
  ```
- **前端**：Vite/Node 默认 UTF-8，源文件保持 UTF-8 无 BOM 即可。
- **Windows 终端**：PowerShell 默认输出可能是 GBK；**不要用 `>`/`>>` 重定向把含中文的内容写进源文件**（会按当前代码页编码）。要写文件用 UTF-8 感知的程序，不要靠 shell 重定向。

## 处理已损坏文件（mojibake 还原）

经典双重编码（UTF-8 被当 GBK 再存 UTF-8）可逆转：`坏文本.encode('gbk').decode('utf-8')`。
但若 mojibake 中已出现 `?`（0x3F），该字节已丢失、不可逆，只能按上下文重写注释。

## 检查表（提交前）

- [ ] 新增/修改的文本文件是 UTF-8 无 BOM（`file *.xml` 或编辑器状态栏确认）
- [ ] 没有出现 `鐗堟湰`/`寰湇`/`锛` 这类乱码片段
- [ ] 仓库根有 `.editorconfig`（charset=utf-8）
- [ ] 父 pom 有 `project.build.sourceEncoding=UTF-8`
- [ ] 批量文本替换用的是 UTF-8 感知工具，不是裸 `>` 重定向