feat(api): 实现三端统一的JSON API响应契约
- 新增`api_response.py`统一响应封装工具类，提供标准成功/错误响应构造方法 - 重构WonderQ-Admin全局异常处理器，将所有异常转换为标准响应格式 - 修改所有公共和管理端接口的返回逻辑，统一使用`code`（与HTTP状态码一致）、`msg`和`data`的三层结构 - 新增`api-response-contract.md`文档，定义完整的三端统一JSON响应规范 - 更新所有领域API文档，明确业务数据需位于`data`字段内，补充响应格式说明 - 为WonderQ-MiniAPP和WonderQ-Admin-UI新增响应解析逻辑和类型定义，自动完成协议校验和错误处理 - 更新所有测试用例，适配新的响应结构确保接口符合契约要求 - 新增`module-config-api.md`模块配置API文档，补充站点模块配置的接口约定 - 更新项目README文档，调整文档分类顺序将响应契约置于首位
This commit is contained in:
duanshuwen committed
1 parent
d16924584c
commit
e082bd2d98
28 files changed
+993
-383
No files matched your search
@@ -226,7 +226,7 @@ def test_admin_home_experience_list_returns_full_record():
|
||||
app.dependency_overrides.clear()
|
||||
|
||||
assert response.status_code == 200
|
||||
item = response.json()["items"][0]
|
||||
item = response.json()["data"]["items"][0]
|
||||
assert item["id"] == "waterfall-descent"
|
||||
assert item["isActive"] is True
|
||||
assert item["createdAt"] == "2026-01-01T00:00:00"
|
||||
@@ -272,8 +272,8 @@ def test_admin_home_wild_patch_updates_record():
|
||||
app.dependency_overrides.clear()
|
||||
|
||||
assert response.status_code == 200
|
||||
assert response.json()["title"] == "百米自降体验"
|
||||
assert response.json()["isActive"] is False
|
||||
assert response.json()["data"]["title"] == "百米自降体验"
|
||||
assert response.json()["data"]["isActive"] is False
|
||||
assert fake_db.committed
|
||||
|
||||
|
||||
@@ -332,7 +332,11 @@ def test_admin_home_delete_normalizes_remaining_order():
|
||||
app.dependency_overrides.clear()
|
||||
|
||||
assert response.status_code == 200
|
||||
assert response.json() == {"id": "experience-1"}
|
||||
assert response.json() == {
|
||||
"code": 200,
|
||||
"msg": "success",
|
||||
"data": {"id": "experience-1"},
|
||||
}
|
||||
assert second.sortOrder == 0
|
||||
assert fake_db.committed
|
||||
|
||||
@@ -349,7 +353,7 @@ def test_admin_home_reorder_rejects_incomplete_ids():
|
||||
app.dependency_overrides.clear()
|
||||
|
||||
assert response.status_code == 400
|
||||
assert response.json()["code"] == "HOME_REORDER_INVALID"
|
||||
assert response.json()["errorCode"] == "HOME_REORDER_INVALID"
|
||||
assert not fake_db.committed
|
||||
|
||||
|
||||
@@ -372,8 +376,8 @@ def test_admin_home_wanfa_recommendation_create_links_existing_category():
|
||||
app.dependency_overrides.clear()
|
||||
|
||||
assert response.status_code == 201
|
||||
assert response.json()["categoryId"] == "family-route"
|
||||
assert response.json()["categoryLabel"] == "亲子路线"
|
||||
assert response.json()["data"]["categoryId"] == "family-route"
|
||||
assert response.json()["data"]["categoryLabel"] == "亲子路线"
|
||||
assert fake_db.added[0].categoryId == "family-route"
|
||||
|
||||
|
||||
@@ -395,7 +399,7 @@ def test_public_home_returns_active_wanfa_category_recommendations():
|
||||
app.dependency_overrides.clear()
|
||||
|
||||
assert response.status_code == 200
|
||||
assert response.json()["playRecommendations"] == [
|
||||
assert response.json()["data"]["playRecommendations"] == [
|
||||
{
|
||||
"id": "recommendation-1",
|
||||
"categoryId": "family-route",
|
||||
@@ -431,37 +435,41 @@ def test_public_home_returns_rendering_fields_for_all_sections():
|
||||
|
||||
assert response.status_code == 200
|
||||
assert response.json() == {
|
||||
"experiences": [
|
||||
{
|
||||
"id": "waterfall-descent",
|
||||
"badge": "玩过推荐",
|
||||
"category": "瀑降体验",
|
||||
"title": "悬崖瀑降",
|
||||
"englishTitle": "WATERFALL DESCENT",
|
||||
"image": "https://example.test/waterfall.jpg",
|
||||
"demandKeyword": "悬崖瀑降",
|
||||
}
|
||||
],
|
||||
"teamBuildings": [
|
||||
{
|
||||
"id": "wild-challenge",
|
||||
"tag": "户外挑战",
|
||||
"title": "山野挑战，共创极境",
|
||||
"description": "洞穴、瀑降与协作，适合 10-30 人。",
|
||||
"image": "https://example.test/team.jpg",
|
||||
"demandKeyword": "户外团建",
|
||||
}
|
||||
],
|
||||
"wildArchives": [
|
||||
{
|
||||
"id": "hundred-meter-descent",
|
||||
"title": "百米自降",
|
||||
"image": "https://example.test/archive.jpg",
|
||||
"demandKeyword": "悬崖瀑降",
|
||||
"photoCount": 2,
|
||||
}
|
||||
],
|
||||
"playRecommendations": [],
|
||||
"code": 200,
|
||||
"msg": "success",
|
||||
"data": {
|
||||
"experiences": [
|
||||
{
|
||||
"id": "waterfall-descent",
|
||||
"badge": "玩过推荐",
|
||||
"category": "瀑降体验",
|
||||
"title": "悬崖瀑降",
|
||||
"englishTitle": "WATERFALL DESCENT",
|
||||
"image": "https://example.test/waterfall.jpg",
|
||||
"demandKeyword": "悬崖瀑降",
|
||||
}
|
||||
],
|
||||
"teamBuildings": [
|
||||
{
|
||||
"id": "wild-challenge",
|
||||
"tag": "户外挑战",
|
||||
"title": "山野挑战，共创极境",
|
||||
"description": "洞穴、瀑降与协作，适合 10-30 人。",
|
||||
"image": "https://example.test/team.jpg",
|
||||
"demandKeyword": "户外团建",
|
||||
}
|
||||
],
|
||||
"wildArchives": [
|
||||
{
|
||||
"id": "hundred-meter-descent",
|
||||
"title": "百米自降",
|
||||
"image": "https://example.test/archive.jpg",
|
||||
"demandKeyword": "悬崖瀑降",
|
||||
"photoCount": 2,
|
||||
}
|
||||
],
|
||||
"playRecommendations": [],
|
||||
},
|
||||
}
|
||||
|
||||
|
||||
@@ -476,7 +484,7 @@ def test_public_wild_archive_list_returns_photo_count():
|
||||
app.dependency_overrides.clear()
|
||||
|
||||
assert response.status_code == 200
|
||||
assert response.json()["items"][0] == {
|
||||
assert response.json()["data"]["items"][0] == {
|
||||
"id": "hundred-meter-descent",
|
||||
"title": "百米自降",
|
||||
"image": "https://example.test/archive.jpg",
|
||||
@@ -496,8 +504,8 @@ def test_public_wild_archive_detail_returns_all_images():
|
||||
app.dependency_overrides.clear()
|
||||
|
||||
assert response.status_code == 200
|
||||
assert response.json()["title"] == "百米自降"
|
||||
assert response.json()["images"] == [
|
||||
assert response.json()["data"]["title"] == "百米自降"
|
||||
assert response.json()["data"]["images"] == [
|
||||
"https://example.test/archive.jpg",
|
||||
"https://example.test/archive-2.jpg",
|
||||
]
|
||||
@@ -515,17 +523,21 @@ def test_public_team_building_detail_returns_long_form_content():
|
||||
|
||||
assert response.status_code == 200
|
||||
assert response.json() == {
|
||||
"id": "wild-challenge",
|
||||
"tag": "户外挑战",
|
||||
"title": "山野挑战，共创极境",
|
||||
"description": "洞穴、瀑降与协作，适合 10-30 人。",
|
||||
"image": "https://example.test/team.jpg",
|
||||
"demandKeyword": "户外团建",
|
||||
"detailSubtitle": "越过山丘，向来处去",
|
||||
"detailParagraphs": [
|
||||
"真正的贵州，从未被写进攻略里的山野故事。",
|
||||
"我们用一次次出发，把团队重新带回自然。",
|
||||
],
|
||||
"code": 200,
|
||||
"msg": "success",
|
||||
"data": {
|
||||
"id": "wild-challenge",
|
||||
"tag": "户外挑战",
|
||||
"title": "山野挑战，共创极境",
|
||||
"description": "洞穴、瀑降与协作，适合 10-30 人。",
|
||||
"image": "https://example.test/team.jpg",
|
||||
"demandKeyword": "户外团建",
|
||||
"detailSubtitle": "越过山丘，向来处去",
|
||||
"detailParagraphs": [
|
||||
"真正的贵州，从未被写进攻略里的山野故事。",
|
||||
"我们用一次次出发，把团队重新带回自然。",
|
||||
],
|
||||
},
|
||||
}
|
||||
|
||||
|
||||
@@ -538,7 +550,7 @@ def test_public_team_building_detail_returns_not_found_for_missing_item():
|
||||
app.dependency_overrides.clear()
|
||||
|
||||
assert response.status_code == 404
|
||||
assert response.json()["message"] == "团队共创不存在"
|
||||
assert response.json()["msg"] == "团队共创不存在"
|
||||
|
||||
|
||||
def test_public_team_building_detail_falls_back_to_legacy_description():
|
||||
@@ -552,5 +564,5 @@ def test_public_team_building_detail_falls_back_to_legacy_description():
|
||||
app.dependency_overrides.clear()
|
||||
|
||||
assert response.status_code == 200
|
||||
assert response.json()["detailSubtitle"] == team.description
|
||||
assert response.json()["detailParagraphs"] == [team.description]
|
||||
assert response.json()["data"]["detailSubtitle"] == team.description
|
||||
assert response.json()["data"]["detailParagraphs"] == [team.description]
|
||||
Reference in new issue
Block a user