certd/.codex/agent-rules/coding-style.md

代码风格规则

基本原则

• 中文 README 在部分 PowerShell 环境中可能显示乱码；README_en.md 可读性更好，且包含同样的高层项目说明。
• 根包管理器是 pnpm，不要引入 npm/yarn lockfile。
• 优先沿用现有模块、插件、服务模式，再考虑新增抽象。
• 注意本地数据和配置里可能包含凭据、证书材料等敏感信息。

注释

本仓库代码注释优先使用中文，尤其是解释业务规则、兼容逻辑、协议细节和隐藏风险时；除非文件已有明确英文注释风格或引用外部英文术语，否则不要新增英文说明性注释。

可读性

代码可读性优先于短写法。遇到包含业务分支的复杂三元表达式、内联对象、链式调用或条件组合时，优先拆成命名清晰的中间变量、独立分支或小函数，让读代码的人能一眼看出业务意图；不要为了少写几行把逻辑压成难读的一坨。

在对象字面量、查询条件或函数参数里不要内联调用多层 helper，例如 { domain, ...this.buildUserProjectQuery(userId, projectId) }。应先用命名变量承接结果，例如 const userProjectQuery = this.buildUserProjectQuery(userId, projectId)，再在对象里展开 ...userProjectQuery，让条件构造和业务字段都更容易阅读。

DRY

遵守 DRY 原则：同一业务规则、字段转换、权限判断、Repository 选择、事务传播、金额计算等逻辑不要在多个地方复制粘贴。第二次出现时可以先保持清晰，第三次出现前应优先抽成局部 helper、service 方法或已有公共工具；抽象要服务于减少真实重复和降低修改风险，不要为了形式上的“复用”制造过度设计。

单一职责

遵守单一职责原则：一个方法只负责一个清晰的业务步骤或技术步骤。流程编排方法可以串联多个步骤，但具体的校验、计算、持久化、状态变更、展示数据组装应尽量拆到命名明确的小方法中；不要让一个方法同时承担查询、校验、计算、写库、格式化返回等过多职责。