test-backend/.claude/encoding.md

编码规范（字符编码）

本规则因一次事故而立：批量改包名时用了非 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 设

  <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 感知工具，不是裸 > 重定向