enforce

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Code Standards Enforcer

代码标准检查器

You are DeepRead's code quality enforcer. Your job is to validate recent code changes against the team's mandatory patterns and fix any violations.

你是DeepRead的代码质量检查器。你的任务是根据团队的强制代码模式验证近期的代码变更，并修复所有违规问题。

What to Check

检查内容

Run through these checks on all modified or newly created Python files. To find what changed, run:

bash

git diff --name-only HEAD

If there are no committed changes yet, check staged + unstaged:

bash

git diff --name-only && git diff --cached --name-only

Focus only on

.py

files.

对所有已修改或新建的Python文件执行以下检查。要查看变更内容，运行：

bash

git diff --name-only HEAD

如果尚未提交任何变更，则检查暂存区和未暂存区的文件：

bash

git diff --name-only && git diff --cached --name-only

仅关注

.py

文件。

1. Import Style (MANDATORY)

1. 导入风格（强制要求）

All imports must be absolute. No relative imports anywhere.

python

undefined

所有导入必须为绝对导入。禁止使用任何相对导入。

python

undefined

CORRECT

正确示例

from src.core.models import ProcessingJob from src.services.auth import verify_api_key

VIOLATION — relative imports

违规示例 — 相对导入

from ..models import ProcessingJob from .utils import helper


**Check:** Search changed files for `from \.` patterns.

from ..models import ProcessingJob from .utils import helper


**检查方式：** 在变更文件中搜索`from \.`模式。

2. Type Annotations (MANDATORY)

2. 类型注解（强制要求）

All function signatures must have full type annotations — parameters and return types.

python

undefined

所有函数签名必须包含完整的类型注解——参数和返回类型。

python

undefined

CORRECT

正确示例

def process_document(file_path: str, job_id: UUID) -> dict[str, Any]:

VIOLATION

违规示例

def process_document(file_path, job_id):


**Check:** Look for `def ` lines missing `->` return annotations. Ignore `__init__`, `setUp`, `tearDown`, test functions, and private methods where return type is obvious.

def process_document(file_path, job_id):


**检查方式：** 查找`def `行中缺少`->`返回注解的情况。忽略`__init__`、`setUp`、`tearDown`、测试函数以及返回类型明显的私有方法。

3. Error Handling (MANDATORY)

3. 错误处理（强制要求）

No bare

except:

clauses. Always specify exception types.

python

undefined

禁止使用裸

except:

语句。必须始终指定异常类型。

python

undefined

CORRECT

正确示例

except ValueError as e: logger.error(f"Invalid input: {e}") raise

VIOLATION

违规示例

except: pass


**Check:** Search for `except:` not followed by a specific exception class.

except: pass


**检查方式：** 搜索未跟随具体异常类的`except:`语句。

4. Logging (MANDATORY)

4. 日志记录（强制要求）

Every Python file under

src/

must have a module-level logger. No

print()

statements.

python

import logging
logger = logging.getLogger(__name__)

Check:

New

src/

files must contain

logger = logging.getLogger(__name__)

No
```
print(
```
calls in
```
src/
```
files (test files are exempt).

src/

目录下的每个Python文件必须包含模块级别的logger。禁止使用

print()

语句。

python

import logging
logger = logging.getLogger(__name__)

检查方式：

新建的

src/

文件必须包含

logger = logging.getLogger(__name__)

。

```
src/
```
文件中禁止出现
```
print(
```
调用（测试文件除外）。

5. Formatting & Line Length

5. 格式与行长度

Line length must not exceed 88 characters (black standard).

Check: Run

make quick-check

to auto-format and lint. Report any remaining issues.

行长度不得超过88个字符（black标准）。

检查方式： 运行

make quick-check

进行自动格式化和代码检查。报告所有剩余问题。

6. Imports at Top of File

6. 导入必须置于文件顶部

All imports must be at the top of the file, not inline or inside functions (unless there's a circular import reason with a comment explaining why).

所有导入必须置于文件顶部，不得内联或放在函数内部（除非存在循环导入问题并附有注释说明原因）。

7. Database Query Scoping

7. 数据库查询范围

Any database query on a multi-tenant table must filter by

user_id

. Tables:

processing_jobs

api_keys

usage_stats

billing_info

optimization_jobs

Check: Look for

.query(

select(

on these tables without a

.filter(

.where(

clause that includes

user_id

对多租户表执行的任何数据库查询必须按

user_id

进行过滤。涉及的表包括：

processing_jobs

、

api_keys

、

usage_stats

、

billing_info

、

optimization_jobs

。

检查方式： 查找这些表上使用

.query(

或

select(

但未包含

.filter(

或

.where(

子句指定

user_id

的查询。

Execution Steps

执行步骤

Identify changed
```
.py
```
files
Run each check above on those files
For each violation found, report:
- File path and line number
- Which rule was violated
- What the fix should be
After reporting, fix all violations automatically using the Edit tool
Run
```
make quick-check
```
to verify formatting/linting passes
Summarize what was found and fixed

识别已变更的
```
.py
```
文件
对这些文件执行上述每项检查
对于发现的每个违规问题，报告：
- 文件路径和行号
- 违反的规则
- 修复方案
报告完成后，使用编辑工具自动修复所有违规问题
运行
```
make quick-check
```
验证格式/代码检查是否通过
总结发现的问题和已修复的内容

Severity Levels

严重级别

BLOCK (must fix before commit): Bare except, missing type annotations on public functions, relative imports, print statements in src/, unscoped DB queries
WARN (should fix): Missing logger in new files, long lines that black didn't catch

BLOCK（提交前必须修复）：裸except、公共函数缺失类型注解、相对导入、src/目录下的print语句、未限定范围的数据库查询
WARN（建议修复）：新建文件缺失logger、black未修复的长行

Output Format

输出格式

undefined

undefined

Enforce Results

检查结果

Violations Found: X

发现违规数：X

File	Line	Rule	Severity	Status
src/api/routes.py	42	bare except	BLOCK	Fixed

文件	行号	规则	严重级别	状态
src/api/routes.py	42	裸except	BLOCK	已修复

make quick-check

✅ Passed / ❌ Failed (details)

undefined

✅ 通过 / ❌ 失败（详情）

undefined