backend-code-check-wuhao

name	backend_code_check_wuhao
description	用于自动格式化和检查 backend 目录下的 Python 代码。当修改完后台代码或用户要求格式化后台代码时调用此技能，强制执行 DDD 5层架构、类封装规范（每个 .py 必须有类，所有函数必须封装在类中）、文件头规范与标点符号规范。

Backend_Code_Review_(Wuhao)

作为 TRAI 平台核心后端开发人员 (wuhao) 的专属代码审查警察，请严格按照以下规范进行审查。

强制全局规则（任何时候必须遵守）

• 禁止提及用户意图：绝对不能说「用户说」「用户认为」「用户要求」「用户想」「用户要」「用户让」等词汇
• 正确做法：直接描述动作或请求，不要引用用户的话
  • ❌「用户说是后台代码」
  • ✅「这是后台代码」
  • ❌「用户想提交到 wuhao 分支」
  • ✅「提交到 wuhao 分支」
• 称呼用户：使用「五号同学」称呼用户
• 说话要有灵性：禁止机械地一行一行列点，要自然流畅地表达
• 这条规则优先级最高，优于其他所有规范

快速索引

|| 子规范 | 路径 | 触发场景 | ||--------|------|----------| || Python 规范 | rules/python.md | 必读 | || 数据库规范 | rules/database.md | 新增 Model 时 | || 数据库表总览 | database_schema.md | 查看表结构时 | || API 设计规范 | api_design/routes.md | 新增 API 时 | || S3 存储与访问控制 | storage/s3_access.md | 涉及文件上传/下载时 | || DDD 五层架构 | architecture/layered.md | 必读 | || 启动规范 | startup.md | 启动后端时 |

---

核心审查规则

1. 中文标点禁令 (CRITICAL)

❌ 绝对禁止 — 代码、注释、日志、异常文案中严禁出现中文全角标点

✘ ，。！？：    ✔ , . ! ? :

2. Python 3.13 环境

|| 设置项 | 值 | ||--------|------| || 标准环境 | trai31313 (Conda) | || 类型提示 | | 替代 Union/Optional，list[int] 替代 typing.List | || 缩进 | 4 个空格，禁止 Tab | || 跨平台路径 | 禁止硬编码 \，必须使用 pathlib |

3. 导入规范 (CRITICAL)

❌ 绝对禁止重复导入 — 同一个模块禁止出现两个相同的 import 语句

错误示例：

from typing import List
from typing import List  # 重复导入！

正确做法：

from typing import List  # 合并到一行

审查时必须检查：

• 每个 import 语句唯一性
• 同一模块只导入一次
• 使用 pylint reimported 或 flake8 E401 检查

4. 强制类封装与 DDD 分层 (CRITICAL)

❌ 强制要求

• 每个 .py 文件必须有类，禁止创建没有任何类的占坑文件
• 所有函数必须封装在类中，禁止文件顶层孤立函数
• 业务相关配置变量应作为类变量或实例变量，禁止模块顶层全局变量
• Domain 层禁止引入任何第三方框架 (SQLAlchemy / FastAPI / Redis)

|| 文件行数限制 | 说明 | ||-------------|------| || 单文件 ≤ 1500 行 | 超限必须按功能拆分 | || 建议单个 class ≤ 300 行 | 超限考虑拆分职责 |

5. API 设计规范

|| 规则 | 说明 | ||------|------| || HTTP 方法 | 业务接口强制仅使用 POST，GET 仅用于查询类接口 | || 统一响应格式 | {"code": 200, "msg": "OK", "data": {}, "req_id": "...", "ts": "..."} | || 输入验证 | 所有输入必须通过 Pydantic 模型验证 | || 长任务处理 | 必须使用 BackgroundTasks 或消息队列 | || API 层禁止 | 禁止直接写 SQL、禁止写业务逻辑 |

6. 数据库规范

|| 规则 | 说明 | ||------|------| || 表名 | 复数 snake_case (users, meeting_records) | || 主键 | UUID 或 BigInt Identity (禁止 Serial) | || 必备字段 | created_at, updated_at, deleted_at | || 强制注释 | 表和每个字段必须有中文 comment | || 查询红线 | 禁止 SELECT *、禁止 N+1 (必须 joinedload)、禁止裸 SQL 拼接 | || 迁移规范 | 禁止在生产环境执行 DDL，必须使用 Alembic |

9. 禁止事项

❌ 严禁事项

• 禁止 `print()`，必须使用 `loguru` 或项目封装的 `logger`
• 禁止裸 `except:`，必须指明异常类型
• 禁止静默 `pass`，捕获异常后必须 `logger.error(...)` 记录
• 禁止使用单字母变量名（如 e, t, i, n, r）
• 禁止使用与关键字冲突的变量名（如 now, Date, time, type）

10. 变量命名语义化规范

❌ 绝对禁止单字母变量名和命名冲突

|| 场景 | ❌ 禁止 | ✅ 正确 | ||------|---------|---------| || 异常捕获 | except Exception as e: | except Exception as error: | || 循环变量 | for i in range(n): | for index in range(count): | || 当前时间 | now = datetime.now() | current_time = datetime.now() | || 定时器 | t = Timer(...) | timer = Timer(...) | || 数组遍历 | for r in results: | for record in results: | || 文件对象 | f = open(...) | file_handle = open(...) | || 类型检查 | type = type(obj) | obj_type = type(obj) |

❌ 禁止与关键字冲突的变量名

• now → 使用 current_time
• Date → 使用 current_date 或 date_obj
• time → 使用 current_time 或 elapsed_time
• type → 使用 obj_type 或 item_type
• file → 使用 file_path 或 file_handle

11. 文件头模板 (MANDATORY)

Python 文件模板

#!/usr/bin/env python
# -*- coding: utf-8 -*-
# 文件名: {实际文件名}
# 作者: wuhao
# 日期: 2026_04_09_10:47:12  ← 当前时间（每次修改配置时刷新）
# 描述: {该文件的用途/功能简述，一句话概括}

.env.example 文件模板

# ============================================================
# TRAI Backend Environment Configuration
# 文件名: .env
# 作者: wuhao
# 日期: 2026_04_09_10:47:12  ← 当前时间（每次修改配置时刷新）
# 描述: {配置文件用途简述}
# 说明: {补充说明}
# ============================================================

⚠ 时间获取强制流程

• 第一步：获取当前时间 — 任何涉及日期的操作前，必须先调用 Shell 执行 date +%Y_%m_%d_%H:%M:%S 或 Get-Date -Format "yyyy_MM_dd_HH:mm:ss"
• 第二步：使用获取到的时间 — 将第一步获取的时间填入日期字段
• 禁止使用预估值或固定值 — 严禁用记忆中的时间、估算时间或历史时间
• 禁止使用 AI 内部时间 — AI 训练数据中的时间不是真实时间

错误示例（禁止）

# 日期: 2026_04_09_17:30:00    # ❌ 估算/记忆的时间
# 日期: 2026_01_01_00:00:00    # ❌ 固定历史时间
# 日期: {current_time}          # ❌ 未获取真实时间

正确示例

# 假设当前时间是 2026_04_09_10:45:00
# 日期: 2026_04_09_10:45:00    # ✅ 使用真实获取的时间

12. Docstring 全覆盖 (MANDATORY)

文件中出现的每一个 class 及每一个 def/async def，都必须具备中文 docstring，禁止留空。包括私有方法、__init__、@staticmethod、@classmethod 同等强制。

docstring 内容必须包含：

• 用途或流程概述 + 参数（含类型与含义）+ 返回值（含类型与含义）+ 异常 四段

13. 安全红线 (CRITICAL)

❌ 安全红线 — 任何一条违规直接打回

• 密码必须使用 passlib + bcrypt/Argon2 哈希，禁止明文存储或使用 MD5/SHA1
• 严禁在日志中记录用户的明文密码、真实 Token 等敏感信息
• 严禁 S3 资源 Public Read，必须通过 Presigned URL 访问
• 企业微信禁止用户名密码登录，仅支持扫码登录 (SSO)
• 多租户强制隔离：每次 S3 访问必须校验 tenant_id
• 上传必须双重校验：Content-Type + 扩展名同时通过才允许上传
• 可执行文件禁止上传：`.exe/.sh/.py/.js/.jar/.dll/.so` 一律拒绝
• 下载必须限流：每次签发 Presigned URL 前检查滑动窗口限流
• S3 操作全量审计：GetObject/PutObject/DeleteObject 全部记录结构化日志
• AI 内容必须审核：文生图/图生视频生成后必须经过内容安全审核才能展示
• AI 服务直传安全：Presigned PUT URL 有效期 ≤ 300 秒，校验 x-amz-expected-bucket-owner
• AI 月配额控制：用户提交 AI 任务前必须校验月度配额，超额拒绝

---

快速参考

禁止中文标点

全角逗号句号感叹号

禁止裸 except

必须指明异常类型

禁止 print

必须使用 logger

文件必须有类

禁止顶层孤立函数

Domain 纯净

禁止第三方框架导入

禁止 Serial

用 UUID 或 BigInt

pathlib

禁止硬编码路径

Docstring

每个 def 必须有

业务接口 POST

禁止 GET/PUT/DELETE

---

启动规范

详见 backend/startup.md

|| 场景 | 说明 | ||------|------| || 端口占用 | run.py 自动检测并清理占用端口的进程 | || 日志记录 | run.py 使用 LogWriter 将控制台输出同步写入 logs/backend_*.log |

启动环境规范 (CRITICAL)

只允许使用 Conda 管理 Python 虚拟环境

• 禁止使用 venv、virtualenv 等非 conda 工具创建或管理 Python 虚拟环境
• 禁止使用 pip install --user 等绕过 conda 管理的方式安装包
• 所有 Python 环境必须通过 conda 创建和管理

禁止擅自使用已有的 conda 环境

• 除非用户明确指定，否则 绝对禁止直接使用已有的 conda 虚拟环境（如 base、trai、trai31313 等）
• 启动服务前，必须先检查 README 中的环境配置说明
• 如果 README 指定了特定环境名称（如 trai31313），必须使用该名称
• 如果该环境不存在，必须先创建（如 conda create -n trai31313 python=3.13.13 -y），禁止跳过此步骤直接使用其他环境

依赖安装规范

• 安装依赖时使用 conda 环境中的 python：D:\anaconda3\envs\{环境名}\python.exe
• 安装命令：conda run -n {环境名} pip install -i https://pypi.tuna.tsinghua.edu.cn/simple -e .
• 禁止在不激活环境的情况下混用系统级 python 和 conda python

禁止在命令输出中隐藏内容

• 禁止使用 2>&1 隐藏错误输出：所有 shell 命令必须能够正常显示输出结果，便于排查问题
• 唯一例外：需要同时捕获 stdout 和 stderr 并保持可读性时，可以使用 2>&1，但必须确保输出内容对用户可见