docs(api): 契约补录 POST /api/v1/events（关闭 D-1）

以 AnalyticsController 实测行为为准补录埋点上报端点：批量 1-50、 202 逐条结果（accepted/duplicate/rejected + 4 种拒绝原因）、eventId 幂等、唯一允许匿名的写端点（带 Bearer 则完整校验 401/40101）、 400/40000 整批拒绝。info.version 1.0.0 -> 1.1.0（纯增量）； index.md 端点清单同步为 6 端点。python yaml 解析 + mkdocs build --strict 均通过。 Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
2026-09-07 14:09:45 +08:00
parent 1891d9b7b4
commit 2ceab6b296
2 changed files with 207 additions and 5 deletions
@@ -1,5 +1,8 @@
 # API 契约

-第一迭代认证域的正式契约见 [openapi.yaml](openapi.yaml)（OpenAPI 3）：注册、登录、刷新、退出、当前用户 5 个端点，统一错误信封 `{code, message, data}` 与错误码表（40000/40100/40101/40102/40900/40901/42300），以及会话轮换与登录锁定策略说明。
+正式契约见 [openapi.yaml](openapi.yaml)（OpenAPI 3），当前 6 个端点：
+
+- 认证域（第一迭代冻结）：注册、登录、刷新、退出、当前用户 5 个端点，统一错误信封 `{code, message, data}` 与错误码表（40000/40100/40101/40102/40900/40901/42300），以及会话轮换与登录锁定策略说明。
+- 埋点域（M2 第一波补录）：`POST /api/v1/events` 批量上报产品事件——单批 1–50 条、202 逐条结果（accepted/duplicate/rejected）、`eventId` 幂等去重、唯一允许匿名的写端点（携带 Bearer 则完整校验）。

 约定：契约变更须先改本文件目录下的 OpenAPI，再改实现（契约先行）；错误码只增不改义。