backend-code-review

# Backend Code Review（后端代码审查）

## 何时使用本 Skill

当用户要求**审查、分析或改进**当前项目的后端代码（如 `.py` 文件）时使用本 skill。审查范围以用户指定或项目约定为准，常见为项目中的后端根目录（如 `backend/`、`api/` 等）。支持以下审查模式：

- **待提交变更审查**：用户要求审查当前变更（查看已暂存/工作区中拟提交的变更）。
- **代码片段审查**：用户粘贴代码片段（如函数/类/模块摘录）并请求审查。
- **按文件审查**：用户指定一个或少量文件（如后端下的 `app/api/...`、`services/...` 等）请求审查。

以下情况**不要**使用本 skill：

- 请求涉及前端代码或 UI（如 `.tsx`、`.ts`、`.js`、`web/`、前端 `app/` 等）。
- 用户并非要求对后端代码进行审查/分析/改进。
- 审查范围不在项目约定的后端目录下（除非用户明确要求审查后端相关但位于别处的改动）。

## 如何使用本 Skill

1. **确定审查模式**（待提交变更 / 片段 / 按文件），并根据用户输入限定范围：只审查用户提供或明确引用的内容。
2. 按 **Checklist** 中的规则执行审查。若没有匹配的 Checklist 规则，则使用 **General Review Rules** 做尽力审查。
3. 最终输出**必须**严格遵循 **Required Output Format**。

注意：
- 始终给出可执行的修复或建议（可含代码示例）。
- 若有文件路径与行号，尽量使用 `File:Line` 引用；否则使用最具体的标识。

## 项目后端结构（审查范围参考）

以下为常见 Python 后端分层示例，实际路径以**当前项目**为准（后端根目录可能是 `backend/`、`api/` 等）：

- **API 层**：路由/控制器（如 `app/api/`、`api/`）
- **服务层**：业务逻辑与编排（如 `services/`）
- **核心/领域**：数据库、配置、领域核心（如 `core/`）
- **数据模型**：ORM 模型与 Session（如 `core/database.py`、`models/`）
- **领域模型**：DTO/实体（如 `app/models/`，无 DB）
- **提供方**：外部能力封装（如 `providers/`）
- **工具**：通用工具（如 `utils/`）
- **Worker**：异步/队列消费（如 `workers/`）
- 若项目**无**独立 repository 层，数据访问多在 API 或 service 中通过 `db.query(Model)` 完成；复杂或重复查询建议收敛到 service 或后续引入 repository。

## Checklist

- **db schema 设计**：若审查范围包含模型定义或迁移/init 逻辑（如 `core/database.py`、`init_db`），按 [references/db-schema-rule.md](references/db-schema-rule.md) 审查。
- **architecture**：若涉及 router/service/core/provider 分层、依赖方向、职责归属，按 [references/architecture-rule.md](references/architecture-rule.md) 审查。
- **data access**：若审查范围包含对表/模型的查询与写入（如 `db.query(...)`、`session.execute(...)`、CRUD），且逻辑分散在 router 或重复出现，按 [references/data-access-rule.md](references/data-access-rule.md) 审查。
- **sqlalchemy 使用**：若涉及 Session/事务、查询构造、knowledge_base_id 作用域、原始 SQL，按 [references/sqlalchemy-rule.md](references/sqlalchemy-rule.md) 审查。

## General Review Rules

### 1. Security

- SQL 注入、SSRF、命令注入、不安全反序列化
- 硬编码密钥或凭证
- 不当的鉴权/授权
- 不安全的直接对象引用（如未校验 knowledge_base_id 即访问文档/分段）

### 2. Performance

- N+1 查询
- 缺失的数据库索引
- 在异步路径中的阻塞操作
- 可缓存而未缓存

### 3. Code Quality

- 向前兼容性、重复代码（DRY）、单职责违反
- 过深嵌套与复杂条件
- 魔法数字/字符串、命名不清
- 缺失错误处理、类型标注不完整

### 4. Testing

- 新代码缺少测试、测试未覆盖行为、不稳定测试模式、缺少边界情况

## Required Output Format

审查结果必须严格采用以下两种模板之一。

### Template A（存在问题时）

```markdown
# Code Review Summary

Found <X> critical issues need to be fixed:

## 🔴 Critical (Must Fix)

### 1. <简要描述>

FilePath: <path> line <line>
<相关代码片段或引用>

#### Explanation

<详细说明与依据>

#### Suggested Fix

1. <修复建议>
2. <代码示例>（可选，不适用可省略）

---
（每个 critical 重复上述结构）

Found <Y> suggestions for improvement:

## 🟡 Suggestions (Should Consider)

### 1. <简要描述>
...
（结构同上）

Found <Z> optional nits:

## 🟢 Nits (Optional)
...
（结构同上）

## ✅ What's Good

- <对良好模式的正面反馈>
```

- 若没有 critical/suggestions/nits/good，则省略对应区块。
- 若某项数量超过 10，可汇总为 "Found 10+ critical issues/..." 且只列出前 10 条。
- 若存在需要改代码的问题，可在结构化输出后附一句简短追问，例如："需要我按上述建议直接改代码吗？"

### Template B（无问题时）

```markdown
## Code Review Summary
✅ No issues found.
```