WenwuMap/5-api.md

中华文明全图鉴——API 设计文档

1. API 设计目标

本文档定义 PC Web 地图站 MVP、管理后台和后端服务之间的 REST API 契约。第一阶段优先覆盖：登录鉴权、机构、文物、位置、标签、地图点位、数字资产和操作日志。

2. 通用约定

2.1 Base URL

/api/v1

2.2 响应格式

成功：

{
  "success": true,
  "data": {},
  "request_id": "req_20260612_xxx"
}

失败：

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "字段校验失败",
    "details": []
  },
  "request_id": "req_20260612_xxx"
}

2.3 分页格式

请求参数：

参数	类型	默认值	说明
page	number	1	页码
page_size	number	20	每页数量，最大 100

响应：

{
  "items": [],
  "pagination": {
    "page": 1,
    "page_size": 20,
    "total": 100,
    "total_pages": 5
  }
}

2.4 鉴权方式

后台和需要登录的接口使用：

Authorization: Bearer <access_token>

游客地图接口可匿名访问，但会根据匿名权限隐藏敏感坐标。

2.5 常用错误码

code	HTTP 状态	说明
UNAUTHORIZED	401	未登录或 token 无效
FORBIDDEN	403	无权限
NOT_FOUND	404	资源不存在
VALIDATION_ERROR	422	参数校验失败
CONFLICT	409	数据冲突
INTERNAL_ERROR	500	服务异常

---

3. Auth API

3.1 登录

POST /api/v1/auth/login

请求：

{
  "username": "admin",
  "password": "password"
}

响应：

{
  "access_token": "jwt-token",
  "user": {
    "id": "uuid",
    "username": "admin",
    "nickname": "管理员",
    "user_type": "admin",
    "institution_id": null,
    "roles": ["admin"]
  }
}

3.2 当前用户

GET /api/v1/auth/me

3.3 退出登录

POST /api/v1/auth/logout

---

4. Map API

4.1 地图顶部统计

GET /api/v1/map/summary

查询参数：

参数	类型	必填	说明
view	string	否	all、at_home、away、south_migration
category	string	否	门类
dynasty	string	否	年代
institution_id	uuid	否	机构
tags	string	否	标签 code，逗号分隔

响应：

{
  "total_artifacts": 1000,
  "domestic_count": 920,
  "overseas_count": 80,
  "on_display_count": 600,
  "in_storage_count": 300,
  "loaned_count": 20,
  "unknown_location_count": 80
}

4.2 地图点位查询

GET /api/v1/map/points

查询参数：

参数	类型	必填	说明
bbox	string	是	minLng,minLat,maxLng,maxLat
zoom	number	是	地图缩放级别
view	string	否	all、at_home、away、south_migration
category	string	否	门类
dynasty	string	否	年代
level	string	否	级别
display_status	string	否	展出状态
tags	string	否	标签 code，逗号分隔

响应：

{
  "points": [
    {
      "id": "uuid",
      "type": "artifact",
      "artifact_id": "uuid",
      "name": "千里江山图",
      "category": "painting_calligraphy",
      "dynasty": "北宋",
      "level": "level_1",
      "current_status": "at_home",
      "display_status": "on_display",
      "precision": "exact_building",
      "coordinates": [116.397, 39.916],
      "story_hook": "18 岁天才少年留下的唯一作品",
      "persona_quote": "我只画了一次，但你们看了一千年。",
      "institution": {
        "id": "uuid",
        "name": "故宫博物院"
      }
    }
  ],
  "clusters": [
    {
      "id": "cluster_1",
      "type": "cluster",
      "count": 28,
      "coordinates": [116.397, 39.916]
    }
  ]
}

4.3 附近文物

GET /api/v1/map/nearby

查询参数：

参数	类型	必填	说明
lng	number	是	经度
lat	number	是	纬度
radius_km	number	否	半径，默认 10
limit	number	否	数量，默认 20

---

5. Institution API

5.1 机构列表

GET /api/v1/institutions

查询参数：

参数	类型	说明
keyword	string	名称关键词
country	string	国家
province	string	省份
city	string	城市
publish_status	string	发布状态
page	number	页码
page_size	number	每页数量

5.2 机构详情

GET /api/v1/institutions/{id}

5.3 创建机构

POST /api/v1/institutions

权限：管理员。

请求：

{
  "name": "故宫博物院",
  "short_name": "故宫",
  "institution_type": "museum",
  "country": "中国",
  "province": "北京",
  "city": "北京",
  "address": "北京市东城区景山前街4号",
  "location": {
    "lng": 116.397,
    "lat": 39.916
  },
  "official_website": "https://www.dpm.org.cn",
  "description": "明清两代皇家宫殿博物馆"
}

5.4 编辑机构

PATCH /api/v1/institutions/{id}

5.5 启用/禁用机构

PATCH /api/v1/institutions/{id}/status

5.6 机构文物列表

GET /api/v1/institutions/{id}/artifacts

---

6. Artifact API

6.1 文物列表

GET /api/v1/artifacts

查询参数：

参数	类型	说明
keyword	string	名称关键词
category	string	门类
dynasty	string	年代
level	string	级别
current_status	string	当前状态
institution_id	uuid	机构 ID
tags	string	标签 code，逗号分隔
publish_status	string	发布状态
page	number	页码
page_size	number	每页数量

6.2 文物详情

GET /api/v1/artifacts/{id}

响应：

{
  "id": "uuid",
  "unified_map_id": "CN-2026-001234",
  "name": "千里江山图",
  "category": "painting_calligraphy",
  "dynasty": "北宋",
  "level": "level_1",
  "material": "绢本设色",
  "dimensions": "纵51.5厘米，横1191.5厘米",
  "current_status": "at_home",
  "summary": "北宋青绿山水长卷。",
  "story_hook": "18 岁天才少年留下的唯一作品",
  "persona_quote": "我只画了一次，但你们看了一千年。",
  "current_location": {},
  "tags": [],
  "assets": []
}

6.3 创建文物

POST /api/v1/artifacts

权限：管理员、机构用户。

请求：

{
  "name": "千里江山图",
  "category": "painting_calligraphy",
  "dynasty": "北宋",
  "level": "level_1",
  "material": "绢本设色",
  "dimensions": "纵51.5厘米，横1191.5厘米",
  "current_status": "at_home",
  "home_institution_id": "uuid",
  "summary": "北宋青绿山水长卷。",
  "story_hook": "18 岁天才少年留下的唯一作品",
  "persona_quote": "我只画了一次，但你们看了一千年。"
}

6.4 编辑文物

PATCH /api/v1/artifacts/{id}

6.5 发布文物

POST /api/v1/artifacts/{id}/publish

6.6 撤回文物

POST /api/v1/artifacts/{id}/unpublish

6.7 归档文物

POST /api/v1/artifacts/{id}/archive

---

7. Location API

7.1 文物位置列表

GET /api/v1/artifacts/{artifact_id}/locations

7.2 新增文物位置

POST /api/v1/artifacts/{artifact_id}/locations

请求：

{
  "location_type": "domestic",
  "institution_id": "uuid",
  "precise_location": {
    "lng": 116.397,
    "lat": 39.916
  },
  "public_location": {
    "lng": 116.397,
    "lat": 39.916
  },
  "precision": "exact_building",
  "room_name": "武英殿",
  "cabinet_no": "A-01",
  "display_status": "on_display",
  "source_type": "institution_feed",
  "source_description": "机构直供"
}

7.3 编辑位置

PATCH /api/v1/locations/{id}

7.4 设置当前位置

POST /api/v1/locations/{id}/set-current

---

8. Tag API

8.1 标签分类列表

GET /api/v1/tag-categories

8.2 标签列表

GET /api/v1/tags

查询参数：

参数	类型	说明
category_id	uuid	分类 ID
keyword	string	标签名
is_active	boolean	是否启用

8.3 新增标签

POST /api/v1/tags

8.4 编辑标签

PATCH /api/v1/tags/{id}

8.5 启用/禁用标签

PATCH /api/v1/tags/{id}/status

8.6 绑定文物标签

POST /api/v1/artifacts/{artifact_id}/tags

请求：

{
  "tag_id": "uuid",
  "value_text": "南迁北归",
  "source_type": "manual_entry"
}

8.7 解绑文物标签

DELETE /api/v1/artifact-tags/{id}

---

9. Asset API

9.1 获取上传签名

POST /api/v1/assets/upload-token

请求：

{
  "filename": "artifact.jpg",
  "mime_type": "image/jpeg",
  "size_bytes": 1024000
}

9.2 创建数字资产记录

POST /api/v1/assets

请求：

{
  "artifact_id": "uuid",
  "asset_type": "image",
  "title": "文物主图",
  "url": "https://oss.example.com/artifact.jpg",
  "thumbnail_url": "https://oss.example.com/artifact-thumb.jpg",
  "mime_type": "image/jpeg",
  "size_bytes": 1024000,
  "copyright_owner": "故宫博物院",
  "license_scope": "平台展示"
}

9.3 数字资产列表

GET /api/v1/assets

9.4 删除数字资产

DELETE /api/v1/assets/{id}

---

10. Operation Log API

10.1 操作日志列表

GET /api/v1/operation-logs

查询参数：

参数	类型	说明
operator_id	uuid	操作人
action	string	操作类型
target_type	string	目标类型
target_id	uuid	目标 ID
start_time	string	开始时间
end_time	string	结束时间

10.2 操作日志详情

GET /api/v1/operation-logs/{id}

---

11. Health API

11.1 服务健康检查

GET /api/v1/health

响应：

{
  "status": "ok",
  "time": "2026-06-12T15:20:00.000Z",
  "dependencies": {
    "database": "ok",
    "redis": "ok"
  }
}

---

12. 权限矩阵

API 模块	游客	注册用户	机构用户	管理员
Map 读取	允许	允许	允许	允许
Artifact 读取公开数据	允许	允许	允许	允许
Artifact 写入	不允许	不允许	本机构	全部
Institution 读取	允许	允许	允许	允许
Institution 写入	不允许	不允许	本机构部分字段	全部
Location 写入	不允许	不允许	本机构文物	全部
Tag 读取	允许	允许	允许	允许
Tag 管理	不允许	不允许	部分绑定	全部
Asset 管理	不允许	不允许	本机构文物	全部
Operation Log	不允许	不允许	本机构	全部

13. API 测试要点

• 未登录访问后台写接口应返回 401。
• 机构用户访问其他机构文物写接口应返回 403。
• 地图点位接口在 bbox 缺失时应返回 422。
• 游客访问地图点位时不得返回 precise_location。
• 文物发布前缺少必要字段时应返回 422。
• 标签筛选、门类筛选、年代筛选应支持组合查询。
• 操作写接口必须产生 operation_logs 记录。