代码风格¶

不可变性（关键）¶

始终创建新对象，绝不修改现有对象：

// Pseudocódigo
ERRADO:  modificar(original, campo, valor) → altera o original in-place
CORRETO: atualizar(original, campo, valor) → retorna nova cópia com a alteração

理由：不可变数据可防止隐藏副作用，便于调试，并支持安全并发。

文件组织¶

许多小文件 > 少数大文件： - 高内聚，低耦合 - 典型 200-400 行，最多 800 行 - 从大模块中提取工具函数 - 按功能/领域组织，而不是按类型组织

错误处理¶

始终以全面的方式处理错误： - 在每一层显式处理错误 - 在面向 UI 的代码中提供友好的错误消息 - 在服务器端记录详细的错误上下文 - 绝不静默吞掉错误

输入验证¶

始终在系统边界处进行验证： - 在处理前验证所有用户输入 - 在可用时使用基于 schema 的验证 - 快速失败并提供清晰的错误消息 - 绝不信任外部数据（API 响应、用户输入、文件内容）

代码质量检查清单¶

在将工作标记为完成之前： - [ ] 代码可读且命名良好 - [ ] 函数较小（< 50 行） - [ ] 文件聚焦（< 800 行） - [ ] 无深层嵌套（> 4 层） - [ ] 适当的错误处理 - [ ] 无硬编码值（使用常量或配置） - [ ] 无变异（使用不可变模式）