From b1124fbe1ee9a1fc2da6e1148ed7ff3b5f5e12e4 Mon Sep 17 00:00:00 2001
From: Ed1s0nZ <zhaoyf1104@gmail.com>
Date: Sat, 10 Oct 2026 18:02:52 +0800
Subject: [PATCH] docs: record REST semantics verification and API contract

---
 docs/en-US/api-reference.md              | 9 +++++++++
 docs/feature/rest-error-empty-results.md | 9 +++++++++
 docs/zh-CN/api-reference.md              | 9 +++++++++
 3 files changed, 27 insertions(+)

diff --git a/docs/en-US/api-reference.md b/docs/en-US/api-reference.md
index c1ad1884..cdeec583 100644
--- a/docs/en-US/api-reference.md
+++ b/docs/en-US/api-reference.md
@@ -262,3 +262,12 @@ curl -k https://127.0.0.1:8080/api/eino-agent \
 - Multi-agent: `internal/handler/multi_agent.go`
 - Asset endpoints: `internal/handler/asset.go`
 - Asset storage and deduplication: `internal/database/asset.go`
+
+## Missing deletes and empty lists
+
+After authentication and permission checks, with the requested module available:
+
+- `DELETE /api/c2/profiles/:id` and `DELETE /api/webshell/connections/:id` return `404` for missing or already deleted objects, with `profile not found` and `connection not found` respectively. Genuine database failures return `500` with a generic message; SQL details stay in server logs.
+- Successful `GET /api/vulnerabilities` and `GET /api/batch-tasks` queries with no matching records return `200`, with `"vulnerabilities": []` or `"queues": []` and a normal count of `"total": 0`.
+
+Clients can distinguish failed calls from successful empty results using the HTTP status. Empty collections for these two list endpoints now use `[]` instead of `null`.
diff --git a/docs/feature/rest-error-empty-results.md b/docs/feature/rest-error-empty-results.md
index aea7c924..1446d3ce 100644
--- a/docs/feature/rest-error-empty-results.md
+++ b/docs/feature/rest-error-empty-results.md
@@ -28,3 +28,12 @@
 - 漏洞数据库列表、批量队列业务列表初始化为空切片，成功的无记录查询序列化为 []；后者同时覆盖数据库与内存路径。
 - 独立 httptest 回归覆盖缺失、成功删除、重复删除、SQL 错误脱敏、两类空列表、非空结果和批量内存分支。
 - 修复前回归按预期失败，明确捕获原行为；修复后 `go test ./internal/handler -run '^TestREST(Delete|VulnerabilityList|BatchList)Semantics$' -count=1` 通过。
+
+## F5：验证与消费者文档
+
+- 修复前新增合同测试失败，分别捕获 C2 500、WebShell 表名泄露及两个列表 null（批量数据库/内存均覆盖）。
+- 修复后针对性合同测试通过。
+- `go test ./internal/handler ./internal/database -count=1` 全部通过（handler 20.597s，database 2.551s）。
+- `git diff --check` 通过。新增及改动 Go 文件已 gofmt。
+- 中英文 API 参考补充缺失删除、通用 500 和空列表 [] 合同。
+- 未执行线上请求或部署验证；HTTP 回归使用真实临时 SQLite，通过路由调用 handler，未覆盖完整认证中间件。权限规则未修改。
diff --git a/docs/zh-CN/api-reference.md b/docs/zh-CN/api-reference.md
index feb494c7..e5797357 100644
--- a/docs/zh-CN/api-reference.md
+++ b/docs/zh-CN/api-reference.md
@@ -401,3 +401,12 @@ curl -k https://127.0.0.1:8080/api/eino-agent \
 - 多代理：`internal/handler/multi_agent.go`
 - 资产接口：`internal/handler/asset.go`
 - 资产存储与去重：`internal/database/asset.go`
+
+## 删除与空列表响应约定
+
+请求通过认证、权限检查且模块可用时：
+
+- `DELETE /api/c2/profiles/:id` 和 `DELETE /api/webshell/connections/:id` 对不存在或已删除的对象返回 `404`，分别使用 `profile not found` 和 `connection not found` 错误文案。真正的数据库失败返回 `500` 与通用错误文案，底层 SQL 错误仅记录在服务日志。
+- `GET /api/vulnerabilities` 与 `GET /api/batch-tasks` 成功查询但无匹配记录时返回 `200`；集合字段分别为 `"vulnerabilities": []` 和 `"queues": []`，正常计数为 `"total": 0`。
+
+客户端可按 HTTP 状态区分调用失败和成功的空结果；这两个列表的空集合由 `null` 调整为 `[]`。