From 86d1cf1ffc51a6761d4ab87195f79e7adf7c7ee8 Mon Sep 17 00:00:00 2001
From: Windows <19353512109@163.com>
Date: Sat, 12 Sep 2026 14:26:43 +0800
Subject: [PATCH] =?UTF-8?q?docs:=20=E8=A1=A5=E5=9B=9E=E5=90=88=E5=B9=B6?=
 =?UTF-8?q?=E6=97=B6=E4=B8=A2=E5=A4=B1=E7=9A=84=20ruff=20=E5=9F=BA?=
 =?UTF-8?q?=E7=BA=BF=EF=BC=9B=E5=90=88=E5=B9=B6=E4=B8=BB=E5=B9=B2=206=20?=
 =?UTF-8?q?=E6=8F=90=E4=BA=A4=EF=BC=88=E5=90=AB=E6=9E=B6=E6=9E=84=E5=B8=88?=
 =?UTF-8?q?=E5=AF=B9=E6=88=91=E7=96=8F=E6=BC=8F=E7=9A=84=E4=BF=AE=E6=AD=A3?=
 =?UTF-8?q?=EF=BC=89?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

## 1. 补回被我丢失的门禁条目

主干 `AGENTS.md` 原本有一条 `ruff` 干净，但我在解决 `AGENTS.md` 冲突时**只保留了自己的
mypy/pytest 基线，把这条丢了** —— 合并时丢信息，和代码冲突一样是缺陷。

本次补回，并把命令写准（这点很重要）：

- `ruff check app tests tools alembic` → **`All checks passed`（0 错）**
- 直接 `ruff check .`（全仓）会报 **40 个错，全部来自仓库根目录的 `hq.py` / `nl2sql_yc.py`**
  （袁聪线的演示脚本，不属本项目包结构）

所以"ruff 干净"**必须带范围**，否则会和别人的脚本混在一起、把一个健康状态误报成 40 个错。

## 2. 我的一个真实疏漏（已由架构师修正，本次合并带入）

架构师提交 `ffbcc22`：**`fix: 删掉 NL 合并后残留的未使用变量 role_ids（ruff F841）`**

该疏漏是我引入的：改 `tools/seed_test_rbac.py` 时把
`zip(user_ids, role_ids, strict=True)` 换成显式配对表 `USER_ROLES`，删掉了 `user_ids`
却**没删 `role_ids`**。根因是**我全程没跑过 ruff** —— 项目门禁里有它，
只跑 mypy 和 pytest 是不够的。

已在本机复跑 `ruff check app tests tools alembic` 确认：我改过的文件全部干净
（`role_ids` 已随主干修正进来）。

## 3. 合并主干 6 提交

`fedbf5a..c8cdc06`，含上条修正与投顾线的行情双源、验收归档等，**无冲突**。

## 验证

- `ruff check app tests tools alembic` → `All checks passed`
- `mypy app` → 0 错 / 245 文件
- `pytest tests`（全量）→ `2 failed, 1421 passed, 1 skipped`
  （2 个失败为既有环境项：httpx 把中文序列化成 `\uXXXX`，非本次引入）
---
 AGENTS.md | 10 ++++++++--
 1 file changed, 8 insertions(+), 2 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index cb906f4..cf43f60 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -117,13 +117,19 @@
   **新增模型前先搜一遍 `__tablename__` 有没有被占用。**
 - 测试基线（**2026-09-12 合并主干 PR #7 + 本线记忆投影链路之后实测**）：
   `mypy app` → **245 个文件 0 错**；
-  `pytest tests`（全量）→ `2 failed, 1415 passed, 2 skipped`；
+  `pytest tests`（全量）→ `2 failed, 1421 passed, 1 skipped`；
   `pytest tests/integration` → `102 passed, 1 skipped`。
   ⚠️ **用例数会随开发增减，判断健康看"0 failed"而不是看绝对值**。
-  剩下那 2 个失败**都不是代码缺陷**，接手时不要"修"它们：
+  那 2 个失败**都不是代码缺陷**，接手时不要"修"它们：
   `tests/unit/service/test_offsite_document_recognition_adapter.py` 的 2 个用例 —— **环境相关**：
   它们断言请求体里是中文原文，而 httpx 会把中文序列化成 `\uXXXX`，字节序列自然不匹配。
   功能无影响；若要修，正确做法是断言 `json.loads(body)` 后的字段值（字节级断言不该用来测 JSON）。
+- **`ruff`：`ruff check app tests tools alembic` → 全部 `All checks passed`（0 错）。**
+  ⚠️ **检查范围要写对**：直接 `ruff check .`（全仓）会报 40 个错，**全部来自仓库根目录的两个
+  散落脚本 `hq.py` / `nl2sql_yc.py`**（袁聪线的演示脚本，不属本项目包结构）。
+  所以门禁命令用上面那条；报"ruff 干净"时**必须带范围**，否则会和别人的脚本混在一起。
+  （`pyproject.toml` 的 `[tool.ruff.lint]` 选的是 `E,F,I,B,UP`、`line-length=100`；
+  `tools/*.py` 另配了 `E501/I001/B007` 的 per-file-ignores。）
 - **mypy：`mypy app` → `Success: no issues found in 245 source files`（0 错）。**
   ⚠️ 曾在本机报 184 个错，**已查明是环境版本旧**，与代码质量无关 —— 复现矩阵：