• api
• {stack}
• {module} level: l3 generated_by: doc-agent source_refs:
• path: AlgoDepartment/04_development/{stack}/{path} lines: "1-1" git_sha: HEAD

---

{模块} · {功能} API

AI 生成 · 待 owner review

本文档由 DocAgent 自动生成,status: draft。owner 工程师 review 通过后请把 status 改为 published,并删除 frontmatter 中的 generated_by 字段。

1. 背景与目标

• 背景:{1-3 句业务/技术背景}
• 目标:
  • {目标 1}
  • {目标 2}
• 非目标:
  • {本版本不做的事}

2. 数据流图

flowchart LR
    A[Caller]:::xyL3 --> B[{API Endpoint}]:::xyL3
    B --> C[{Service}]:::xyL3
    C --> D[{Downstream}]:::xyL0

    classDef xyL0 fill:#2E8D7E,stroke:#2E8D7E,color:#fff
    classDef xyL3 fill:#D4A574,stroke:#D4A574,color:#fff

Mermaid 节点必须用 xyL0~xyL5 classDef,严禁内联 style fill:#xxx(违反 R8 红线)。

3. 接口契约

3.1 输入参数

字段	类型	必填	说明	示例
param1	string	✅	用途说明	"abc"
param2	int	❌	默认 0	42

3.2 输出 Schema

字段	类型	说明
result	object	主体结果
result.id	string	唯一标识
latencyMs	number	处理延迟(毫秒)

3.3 异常码

HTTP Code	Error Code	含义	处置建议
400	INVALID_PARAM	参数校验失败	检查 §3.1 必填字段
404	NOT_FOUND	资源不存在	确认 ID 或先创建
500	INTERNAL_ERROR	服务端异常	上报 SRE,附 trace_id

4. 状态机 / 时序(可选)

sequenceDiagram
    participant C as Caller
    participant A as API
    participant S as Service
    C->>A: POST /api/{endpoint}
    A->>S: invoke()
    S-->>A: result
    A-->>C: 200 OK

5. 关键决策

设计哲思

{一段说明为什么这么设计的引言,或引用 ADR}

参见相关 ADR:{ADR-XXX-NNN}(如有)

6. 验收标准

• 单元测试覆盖率 ≥ 80%
• 端到端延迟 P99 < {N} ms
• 所有异常码均有对应处置文档
• mkdocs build 0 ERROR / 0 新增 WARN

7. 测试验证(S2 模式必填)

测试类型	路径	说明
Unit	AlgoDepartment/04_development/{stack}/test/...	{覆盖范围}
Integration	AlgoDepartment/04_development/{stack}/test/integrationtest/...	{覆盖范围}
E2E	(若适用)	{覆盖范围}

8. 影响面(S2 模式 patch 时填)

• 调用方:{列出已知调用方,grep 代码确认}
• 兼容性:{Breaking / Non-breaking}
• 迁移指引:{若 breaking,给出迁移示例}

9. Changelog(patch 时追加)

版本	日期	改动
0.1.0	YYYY-MM-DD	首版(DocAgent 生成)

---

模板使用说明(DocAgent 内部参考,生成正式文档时删除本节): 1. 替换所有 {...} 占位符 2. 删除不适用的章节(如非 API 类型可删 §3.3) 3. S1 模式下 §7 / §8 可标"代码未完成,待对齐" 4. S2 模式下 §7 / §8 必填