Code Review Standards

代码审查标准

Apply this checklist when reviewing code. Report findings in the feedback format below.

进行代码审查时请遵循以下检查清单。按照下方的反馈格式报告审查结果。

Review checklist

审查清单

Correctness and logic

正确性与逻辑

Logic is correct and edge cases are handled.
No obvious bugs or race conditions.
Error handling is present and consistent.

逻辑正确，且已处理边缘情况。
无明显漏洞或竞态条件。
存在错误处理且保持一致。

Security

安全性

No keys, tokens, or secrets in code; use
```
.env
```
or environment variables.
User input is sanitized; no raw SQL (use placeholders).
Pydantic or equivalent used for input validation.

代码中无密钥、令牌或机密信息；使用
```
.env
```
或环境变量管理。
用户输入已做清理；不使用原生SQL（使用占位符）。
使用Pydantic或同类工具进行输入验证。

Code standards

代码规范

Type hints and docstrings (Google style) on public functions.
snake_case for variables/functions/files; PascalCase for classes; UPPER_CASE for constants.
Functions under ~40 lines; DRY and SRP respected.
f-strings and logging (no print for production).
Imports at top; no inline imports.

公共函数包含类型提示和文档字符串（Google风格）。
变量/函数/文件使用snake_case；类使用PascalCase；常量使用UPPER_CASE。
函数代码行数控制在约40行以内；遵循DRY（不重复）和SRP（单一职责）原则。
使用f-strings和日志记录（生产环境不使用print）。
导入语句置于文件顶部；无内联导入。

Tests and quality

测试与质量

Unit tests for new/changed behavior;
```
tests/
```
with
```
test_<module>.py
```
.
Target 80% coverage for touched code.
Version checks:
```
VERSION
```
exists; UI or
```
/version
```
shows "versão:" (or equivalent).

针对新增/变更的行为编写单元测试；测试文件放在
```
tests/
```
目录下，命名为
```
test_<module>.py
```
。
被修改代码的测试覆盖率目标为80%。
版本检查：存在
```
VERSION
```
文件；UI界面或
```
/version
```
接口显示"versão:"（或等效表述）。

Architecture and delivery

架构与交付

Clean separation (domain, use cases, infrastructure); no business logic in controllers.
Repository / Service Layer where applicable; no circular dependencies.
```
funcoes.md
```
updated if functions were added, changed, or removed.
Code formatted (e.g. Black, Ruff); Conventional Commits if applicable.

代码分层清晰（领域层、用例层、基础设施层）；控制器中无业务逻辑。
适用场景下使用仓储/服务层；无循环依赖。
若新增、修改或删除了函数，需更新
```
funcoes.md
```
文档。
代码已格式化（例如使用Black、Ruff）；适用场景下遵循Conventional Commits规范。

DevOps and config

DevOps与配置

Dockerfile and docker-compose (and app-only variant) if the project uses Docker.
```
.env.example
```
documents required variables.
No global deps or cache committed.

若项目使用Docker，需包含Dockerfile和docker-compose（以及仅包含应用的变体配置）。
```
.env.example
```
文件记录了所需的环境变量。
未提交全局依赖或缓存文件。

Feedback format

反馈格式

Classify each finding as:

Critical: Must fix before merge (security, correctness, blocking).
Suggestion: Should improve (readability, performance, consistency).
Nice to have: Optional improvement.

Keep feedback concrete: cite file/line or scope and, when possible, suggest a fix or pattern.

将每个审查发现分为以下类别：

严重问题：合并前必须修复（安全、正确性、阻塞性问题）。
建议改进：应当优化（可读性、性能、一致性方面）。
锦上添花：可选的优化项。

反馈需具体：注明文件/行号或范围，尽可能给出修复建议或参考模式。

code-review-standards

Original

Translation