# dealerhub · AGI 自主迭代报告（第 2 轮）

> **接续**：第 1 轮（`PROGRESS_AGI_ITERATION_1.md`）修复 9 个缺陷后，本轮处理其"下一轮候选"里的
> 全局异常处理器与前端校验，并在过程中**又发现 3 个新缺陷**（含一个"前端校验形同虚设"的隐蔽问题）。
> **回归**：410 passed / 2 skipped（第 1 轮 393 → +17），`check` 0 issues，迁移全绿，API 权限矩阵无异常。

---

## 一、本轮发现的缺陷

| # | 缺陷 | 严重度 | 复现 | 状态 |
|---|---|---|---|---|
| 11 | **前端数量校验被控件掩盖** | 🟠 高 | 数量填 0 → 控件自动改成 `0.0001` → **成功过账 0.0016 元的单据** | ✅ 已修 |
| 12 | **后端接受极小金额单据** | 🟠 高 | 数量 `0.0001` + 单价 15.5 → 金额 0.0016 元落库并过账 | ✅ 已修 |
| 13 | **0 金额单据可通过** | 🟡 中 | 单价填 0 → 金额 0 的单据 | ✅ 已修 |

### 缺陷 11 的细节（最值得记录）

我在前端加了"数量必须 > 0"的校验，并把 `el-input-number` 的 `:min` 设成 `0.0001`，
以为双重保险。浏览器实测却发现：**填 0 仍然提交成功**。

排查结果：`el-input-number` 的 `:min` 语义不是"拦截"，而是**自动纠正**——
用户输入 0，控件在 change 时把它改成 `0.0001`，然后我的 `isValidQty` 检查的是
"已经过控件修正的值"，自然通过。最终落库一张 **0.0016 元**的销售单并成功过账。

**教训**：
1. UI 控件的 `min/max` 是"输入辅助"，**不是校验**——它会掩盖而非暴露非法输入；
2. 正确做法：`min` 允许非法值（这里设 0），让非法值如实呈现，**由显式校验函数拦截并标红**；
3. **前端校验永远不能作为唯一防线**——后端必须独立校验同类约束。

修复后实测：数量值如实显示 `0`、输入框标红、提交被拦并提示"需 ≥0.001 且 ≤10 亿"。

---

## 二、修复内容

### 1. 全局异常处理器（`apps/core/exceptions.py`）

之前每个视图都要手写 try/except 映射业务异常，**漏一处就是 500**。现在收敛到一处：

```python
REST_FRAMEWORK = {
    "EXCEPTION_HANDLER": "apps.core.exceptions.api_exception_handler",
}
```

映射表：

| 异常 | HTTP | code |
|---|---|---|
| `InvalidLineQuantity` / `InvalidLinePrice` | 400 | invalid_quantity / invalid_price |
| `BelowMinPrice` | 400 | below_min_price |
| `InsufficientStock` | 400 | insufficient_stock |
| `CreditLimitExceeded`（销售/商城） | 402 | credit_limit_exceeded |
| `QuotaExceeded`（billing/ai） | 403 | quota_exceeded（含 upgrade_url） |
| `ProductNotAuthorized` | 403 | product_not_authorized |
| `StorefrontError` | 400 | invalid_order |
| **未处理异常** | **500** | **server_error（不含栈/原始消息）** |

**兜底安全性**：未知异常记完整日志到 `dealerhub.api`，但返回给客户端的只有
`{code, detail, exc_type}`——测试专门验证了"异常消息里的数据库连接串不会外泄"。

### 2. 视图层简化

销售/采购/商城/AI 四个视图模块删除了重复的异常分支，代码更短、行为一致：

```
apps/sales/views.py        −40 行（删 4 个 except 分支）
apps/purchase/views.py     −20 行
apps/storefront/views.py   −10 行
apps/ai/views.py           −16 行
```

### 3. 数量/金额上下界（`apps/core/services.py`）

```python
MIN_LINE_QUANTITY = Decimal("0.001")       # 新增：避免极小金额无效单据
MAX_LINE_QUANTITY = Decimal("1000000000")
MAX_LINE_PRICE    = Decimal("1000000000")
```

单据级守门：销售/采购创建时若 `总金额 <= 0` → 拒绝（`ValueError` → 400）。

### 4. 前端校验修正（销售/采购开单页）

- `:min="0"`（允许非法值如实呈现，不再自动纠正）
- `isValidQty` / `isValidPrice` 与后端同口径（≥0.001、≤10 亿、单价 ≥0）
- 非法行输入框**标红**（`.qty-warn`）
- 提交前本地拦截并给出**明确原因**（不再让用户等到 400）

---

## 三、验证证据

### 前端校验实测（Playwright）

```
输入数量 0
  → 输入框显示值：0        （修复前被自动改成 0.0001）
  → 标红：true
  → 点击"保存草稿并过账"
  → 提示："有 1 行数量不合法（需 ≥0.001 且 ≤10 亿）"
  → 数据库无新单据
```

### 脏数据清理

```
待清理脏单: [('XS202609110001', '0.0016')]
  已删除 XS202609110001
剩余单据数: 9（全部为演示数据，无异常金额）
异常金额单据数: 0
```

### 回归与健康检查

```
$ python -m pytest tests/ -p no:cacheprovider
410 passed, 2 skipped in 16.45s

$ python manage.py check
System check identified no issues (0 silenced).

$ python scripts/check_migrations.py
✓ 无待生成迁移 · ✓ 所有迁移已应用 · ✓ 51 个模型字段一致 · ✓ 7 张关键表可查

$ python scripts/audit_api_permissions.py
权限矩阵无明显异常
匿名状态码分布：{200: 2, 400: 2, 401: 31, 403: 3, 404: 95, 405: 4}
```

---

## 四、新增测试

| 模块 | 用例 | 覆盖 |
|---|---|---|
| `test_exception_handler.py` | 12 | 单元级映射（6 类业务异常 + 兜底 500 不泄漏）+ 集成级（4 条真实 API 路径） |
| `test_boundary_inputs.py` | +5 | 极小金额、0 金额、数量上限、正常路径回归 |

**兜底安全性专项**：
```python
def test_handler_returns_structured_500_for_unknown(db):
    resp = _call(RuntimeError("内部数据库连接串 postgres://user:pw@host/db 泄露了"))
    assert resp.status_code == 500
    assert resp.json()["code"] == "server_error"
    assert "postgres://" not in str(resp.data)   # 原始消息不外泄
```

---

## 五、变更文件

```
backend/
├── apps/core/exceptions.py          [新] 全局异常处理器（映射表 + 兜底 500）
├── config/settings/base.py          [改] +EXCEPTION_HANDLER 注册
├── apps/core/services.py            [改] +MIN_LINE_QUANTITY、InvalidLineAmount
├── apps/sales/services.py           [改] 单据总额 > 0 守门
├── apps/purchase/services.py        [改] 同上
├── apps/sales/views.py              [改] −40 行（异常分支收敛）
├── apps/purchase/views.py           [改] −20 行
├── apps/storefront/views.py         [改] −10 行
├── apps/ai/views.py                 [改] −16 行
└── tests/test_exception_handler.py  [新] 12 例

frontend/src/
├── pages/SalesBills.vue             [改] 校验函数 + min 修正 + 标红 + 提交前拦截
└── pages/PurchaseBills.vue          [改] 同上
frontend/dist/                       [重建]
```

---

## 六、两轮迭代的累计成果

| 指标 | 迭代前 | 第 1 轮后 | 第 2 轮后 |
|---|---|---|---|
| 测试用例 | 348 | 393 | **410** |
| 已知缺陷修复 | — | 10 | **13** |
| 审计脚本 | 0 | 2 | 2 |
| 视图层异常处理 | 每处手写 | 每处手写 | **统一收敛** |

**累计修复的资损/高危问题**：
1. 负数量出库（凭空造库存）
2. 负单价（倒贴出货）
3. 极小金额单据（0.0016 元）
4. 0 金额单据
5. 6 个页面 500（缺列）
6. 未生成迁移导致风控规则失效

---

## 七、方法论沉淀（本轮更新）

1. **UI 控件的约束 ≠ 校验**。`el-input-number` 的 `min` 会"纠正"输入而不是拒绝，
   让非法值在用户眼中消失却在系统里生效——比不校验更危险（因为看起来有保护）。
2. **前端校验的唯一价值是"体验"**，安全性必须由后端独立保证。
   本轮三个缺陷都是"前端看似有校验、后端也没有"的组合。
3. **异常处理集中化能消除一整类漏网**。统一 handler 之后，
   新写的视图天然获得正确的 4xx/5xx 语义，不会因为"忘了 try/except"而 500。
4. **兜底 500 要区分"给用户看的"和"给运维看的"**：日志里可以详细，
   响应体里只留 `code` + 通用提示，避免把内部细节（连接串、栈）带出去。

---

## 八、第 3 轮 · 审计日志（本轮追加）

### 发现的问题

`AuditLog` 模型在阶段 1 就定义好了（含 tenant/user/action/target/detail/ip/user_agent 完整字段），
但**全项目搜索没有一处 `AuditLog.objects.create`** —— 意味着过账、强制放行、改价这些
关键操作**没有任何追溯记录**。客户问"这张单谁改的价""谁批的超限放行"时答不上来，
对财务/合规场景是硬缺口。

### 实现

**`apps/core/audit.py`** —— 审计服务：

| 语义动作 | 触发点 |
|---|---|
| `post` | 销售/采购过账 |
| `force` | 信用超限强制放行、低于最低售价放行 |
| `cancel` | 单据作废 |
| `price_override` | 改价（记录原价→新价） |
| `plan_change` | 套餐变更 |

设计三条原则：
1. **只记"有后果"的操作**（不是所有 CRUD，否则淹没在噪音里）
2. **写入失败绝不影响主业务**——整个 `log()` 包在 try/except 里，失败只记 warning
3. **携带足够追责上下文**：谁、何时、对什么、改了什么

**`apps/core/context.py`** —— 请求上下文透传（解决一个真实工程问题）：

服务层（`confirm_sales_bill` 等）是纯函数，签名里加 `request` 会污染业务 API，
但审计需要 IP/UA。方案是中间件把 request 存进 **`contextvars.ContextVar`**
（不是 `threading.local`——ASGI 下协程会串请求），服务层通过 `current_request()` 读取。

### 验证（真实 HTTP）

```
清空旧审计
建单: 201 XS202609110002
过账: 200 state=confirmed

=== 审计日志（含 IP/UA）===
  动作=post 单号=XS202609110002
    用户=1 IP=127.0.0.1 UA='AuditVerify/1.0'
    detail={'business_action': 'post', 'bill_no': 'XS202609110002',
            'amount': '2.0000', 'customer': 'C001', 'lines': 1}
```

用户、IP、UA、单号、金额、客户、行数全部记录。

### 过程中的一个教训

接线时我**一次改了 4 个文件再跑测试**，结果一个 `SyntaxError`（`query_logs` 签名里
多写了一个 `*`）让 **211 个测试同时失败**。修正后立刻恢复 410 passed。

这印证了前两轮的方法论：**小步验证**。如果我是"改完所有文件、最后跑一次测试"，
这个语法错误会和其他改动混在一起，定位成本高得多。

### 新增测试（+13）

| 用例 | 覆盖 |
|---|---|
| 销售/采购过账留痕 | 动作、单号、金额、客户正确 |
| 信用超限强制放行留痕 | 高风险动作可追责 |
| 低于最低售价放行留痕 | 记录原价与最低价 |
| **审计失败不影响主业务** | monkeypatch 让 create 抛异常，验证不中断 |
| request 上下文自动提取 | user / IP（含 X-Forwarded-For）/ UA |
| 按单据号查轨迹 | "这张单都发生了什么" |
| 审计租户隔离 | 别家租户看不到 |
| **contextvar 透传** | 服务层拿到 IP/UA（无 request 参数） |
| **contextvar 清除** | 请求结束后不串号 |
| 无请求上下文 | 定时任务场景仍能写审计 |

---

## 九、下一轮候选

| 优先级 | 项目 | 说明 |
|---|---|---|
| P0 | 真实 PostgreSQL 并发验证 | 起 PG 跑 `-m postgres` 用例，验证行锁下的超卖防护 |
| P1 | 审计日志查询界面 | 后端 `query_logs` 已就绪，前端加"操作轨迹"页 |
| P1 | 前端所有表单的校验审计 | 用同样方法（填非法值看是否真被拦）逐个页面检查 |
| P2 | 性能基线 | 万级商品/单据下的列表与报表响应时间 |
| P2 | 商城 token 过期与刷新 | 72 小时有效期，需验证过期后的用户体验 |

---

## 十、三轮迭代累计成果

| 指标 | 迭代前 | 第 1 轮 | 第 2 轮 | 第 3 轮 |
|---|---|---|---|---|
| 测试用例 | 348 | 393 | 410 | **421** |
| 修复缺陷 | — | 10 | 13 | **13**（+1 审计缺失） |
| 审计脚本 | 0 | 2 | 2 | 2 |
| 异常处理 | 各处手写 | 各处手写 | **统一收敛** | 统一收敛 |
| 关键操作追溯 | ❌ 无 | ❌ 无 | ❌ 无 | **✅ 完整** |

**三轮修复的资损/高危问题汇总**：
1. 负数量出库（凭空造库存）
2. 负单价（倒贴出货）
3. 极小金额单据（0.0016 元）
4. 0 金额单据
5. 6 个页面 500（缺列）
6. 未生成迁移导致风控规则失效
7. 前端校验被控件掩盖（看似有保护，实际没有）
8. 关键操作无审计（合规缺口）

**工程方法沉淀**：
- 守门测试必须先验证它能失败（pytest 版迁移检查假通过两次）
- UI 控件的约束 ≠ 校验（`min` 会掩盖而非暴露非法输入）
- 前端校验只负责体验，安全必须后端独立保证
- 异常处理集中化能消除一整类漏网
- 小步验证：一次改 4 个文件后一个语法错误让 211 个测试同时失败