019e26d814
重大变更： - 将医生端所有文档移到 医生端/ 子目录 - 创建 标注端/ 子目录及其 README - 更新根目录 README 为多产品线管理说明 - 保持原有的双轨制文档管理规范（工程态/注册态） 目录结构： Product-Manage/ ├── 医生端/ # 医生端产品线文档 │ ├── 00 模板中心/ │ ├── 01-10 (其他目录) │ └── README.md ├── 标注端/ # 标注端产品线文档 │ └── README.md └── README.md # 多产品线总说明 影响范围： - 所有医生端文档路径变更 - 新增标注端产品线支持 - 统一多产品线管理规范
92 lines
1.9 KiB
Markdown
92 lines
1.9 KiB
Markdown
---
|
||
type: template
|
||
template_id: API-Doc
|
||
tags:
|
||
- 文档/API
|
||
status: design
|
||
created: {{date}}
|
||
updated: {{date}}
|
||
phase: 2025
|
||
attribute: 工程态
|
||
---
|
||
|
||
# 00.3｜API 文档母版
|
||
|
||
> [!summary] 接口基础信息
|
||
> * **时间阶段**：`2025` / `2026` (必填)
|
||
> * **文档属性**：`工程态` / `注册态` (必填)
|
||
> * **接口编号**：`API-XXXX`
|
||
> * **接口名称**：
|
||
> * **所属服务**：`前端` / `后端` / `算法服务`
|
||
> * **接口版本**：`Vx.x`
|
||
> * **维护人**：
|
||
|
||
---
|
||
|
||
## 1. 请求说明 (Request)
|
||
|
||
* **URL**: `/api/v1/resource/...`
|
||
* **Method**: `GET` / `POST` / `PUT` / `DELETE`
|
||
* **Content-Type**: `application/json`
|
||
|
||
### 1.1 Header 说明
|
||
| Key | Value | 必填 | 说明 |
|
||
| :--- | :--- | :--- | :--- |
|
||
| Authorization | Bearer token | 是 | 用户凭证 |
|
||
|
||
### 1.2 请求参数 (Body / Query)
|
||
|
||
| 参数名 | 类型 | 必填 | 示例值 | 说明 |
|
||
| :--- | :--- | :--- | :--- | :--- |
|
||
| `id` | String | 是 | "12345" | 资源 ID |
|
||
| `name` | String | 否 | "Test" | 名称 |
|
||
|
||
---
|
||
|
||
## 2. 返回说明 (Response)
|
||
|
||
### 2.1 成功响应示例 (HTTP 200)
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "success",
|
||
"data": {
|
||
"id": "12345",
|
||
"status": "active"
|
||
}
|
||
}
|
||
```
|
||
|
||
### 2.2 字段说明
|
||
|
||
| 字段名 | 类型 | 说明 |
|
||
| :--- | :--- | :--- |
|
||
| `code` | Number | 业务状态码 |
|
||
| `data` | Object | 业务数据 |
|
||
|
||
---
|
||
|
||
## 3. 错误码定义 (Error Codes)
|
||
|
||
| 错误码 (code) | 含义 | HTTP Status | 处理建议 |
|
||
| :--- | :--- | :--- | :--- |
|
||
| 40001 | 参数错误 | 400 | 检查参数格式 |
|
||
| 40100 | 未授权 | 401 | 跳转登录 |
|
||
| 50000 | 系统内部错误 | 500 | 联系管理员 |
|
||
|
||
---
|
||
|
||
## 4. 权限与安全
|
||
|
||
* **鉴权方式**：`Token` / `Cookie` / `API Key`
|
||
* **权限控制**：仅 `Admin` 角色可调用
|
||
|
||
---
|
||
|
||
## 5. 版本变更记录
|
||
|
||
| 版本 | 日期 | 变更人 | 变更内容 |
|
||
| :--- | :--- | :--- | :--- |
|
||
| V1.0 | {{date}} | | 初始版本创建 |
|