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
@@ -230,7 +230,11 @@ def test_public_leads_endpoint_accepts_date_only_and_returns_minimal_response():
|
||||
app.dependency_overrides.clear()
|
||||
|
||||
assert response.status_code == 201
|
||||
assert response.json() == {"id": "lead-test-id", "status": "new"}
|
||||
assert response.json() == {
|
||||
"code": 201,
|
||||
"msg": "success",
|
||||
"data": {"id": "lead-test-id", "status": "new"},
|
||||
}
|
||||
assert fake_db.added[0].phone == "contact handle"
|
||||
assert fake_db.added[0].travelDate == datetime(2027, 1, 1)
|
||||
|
||||
@@ -247,7 +251,7 @@ def test_public_phone_login_creates_customer_and_returns_masked_session(monkeypa
|
||||
app.dependency_overrides.clear()
|
||||
|
||||
assert response.status_code == 200
|
||||
body = response.json()
|
||||
body = response.json()["data"]
|
||||
assert body["token"]
|
||||
assert body["customer"] == {"id": "customer-test-id", "phoneMasked": "100****0000"}
|
||||
assert fake_db.added[0].phone == "10000000000"
|
||||
@@ -268,7 +272,11 @@ def test_public_phone_login_requires_wechat_configuration(monkeypatch):
|
||||
app.dependency_overrides.clear()
|
||||
|
||||
assert response.status_code == 503
|
||||
assert response.json() == {"message": "微信小程序登录未配置"}
|
||||
assert response.json() == {
|
||||
"code": 503,
|
||||
"msg": "微信小程序登录未配置",
|
||||
"data": None,
|
||||
}
|
||||
|
||||
|
||||
def test_public_me_returns_customer_for_customer_token():
|
||||
@@ -284,21 +292,25 @@ def test_public_me_returns_customer_for_customer_token():
|
||||
app.dependency_overrides.clear()
|
||||
|
||||
assert response.status_code == 200
|
||||
assert response.json() == {"id": "customer-test", "phoneMasked": "100****0000"}
|
||||
assert response.json() == {
|
||||
"code": 200,
|
||||
"msg": "success",
|
||||
"data": {"id": "customer-test", "phoneMasked": "100****0000"},
|
||||
}
|
||||
|
||||
|
||||
def test_public_me_requires_customer_token():
|
||||
response = TestClient(create_app()).get("/api/public/auth/me")
|
||||
|
||||
assert response.status_code == 401
|
||||
assert response.json() == {"message": "请先登录"}
|
||||
assert response.json() == {"code": 401, "msg": "请先登录", "data": None}
|
||||
|
||||
|
||||
def test_admin_requires_auth_for_protected_endpoint():
|
||||
response = TestClient(create_app()).get("/api/admin/dashboard")
|
||||
|
||||
assert response.status_code == 401
|
||||
assert response.json() == {"message": "请先登录后台"}
|
||||
assert response.json() == {"code": 401, "msg": "请先登录后台", "data": None}
|
||||
|
||||
|
||||
def test_admin_login_returns_token_and_user():
|
||||
@@ -323,7 +335,7 @@ def test_admin_login_returns_token_and_user():
|
||||
app.dependency_overrides.clear()
|
||||
|
||||
assert response.status_code == 200
|
||||
body = response.json()
|
||||
body = response.json()["data"]
|
||||
assert body["token"]
|
||||
assert body["user"] == {
|
||||
"id": "admin-test",
|
||||
@@ -366,7 +378,7 @@ def test_site_config_create_modules_defaults_fields_and_audits(module, payload,
|
||||
app.dependency_overrides.clear()
|
||||
|
||||
assert response.status_code == 201
|
||||
body = response.json()
|
||||
body = response.json()["data"]
|
||||
for key, value in expected.items():
|
||||
assert body[key] == value
|
||||
assert body["isActive"] is True
|
||||
@@ -389,8 +401,10 @@ def test_site_config_invalid_module_returns_structured_error():
|
||||
|
||||
assert response.status_code == 400
|
||||
assert response.json() == {
|
||||
"message": "模块不存在或无权限操作",
|
||||
"code": "MODULE_CONFIG_FORBIDDEN",
|
||||
"code": 400,
|
||||
"msg": "模块不存在或无权限操作",
|
||||
"data": None,
|
||||
"errorCode": "MODULE_CONFIG_FORBIDDEN",
|
||||
"details": {"module": "unknown"},
|
||||
}
|
||||
|
||||
@@ -413,7 +427,7 @@ def test_site_config_create_rejects_removed_module(module, payload):
|
||||
app.dependency_overrides.clear()
|
||||
|
||||
assert response.status_code == 400
|
||||
assert response.json()["code"] == "MODULE_CONFIG_FORBIDDEN"
|
||||
assert response.json()["errorCode"] == "MODULE_CONFIG_FORBIDDEN"
|
||||
|
||||
|
||||
def test_admin_site_config_hero_slides_use_dedicated_contract_without_targets():
|
||||
@@ -427,7 +441,7 @@ def test_admin_site_config_hero_slides_use_dedicated_contract_without_targets():
|
||||
app.dependency_overrides.clear()
|
||||
|
||||
assert response.status_code == 200
|
||||
hero = response.json()["heroSlides"][0]
|
||||
hero = response.json()["data"]["heroSlides"][0]
|
||||
assert hero["title"] == "测试轮播"
|
||||
assert hero["image"] == "/assets/slide.jpg"
|
||||
assert "targetType" not in hero
|
||||
@@ -444,7 +458,7 @@ def test_admin_site_config_includes_destination_page_modules():
|
||||
app.dependency_overrides.clear()
|
||||
|
||||
assert response.status_code == 200
|
||||
body = response.json()
|
||||
body = response.json()["data"]
|
||||
assert "destinations" not in body
|
||||
assert "ctaBanners" not in body
|
||||
assert "campaigns" not in body
|
||||
@@ -465,7 +479,7 @@ def test_admin_site_config_includes_demand_page_modules():
|
||||
app.dependency_overrides.clear()
|
||||
|
||||
assert response.status_code == 200
|
||||
body = response.json()
|
||||
body = response.json()["data"]
|
||||
assert body["demandHero"] == []
|
||||
assert body["demandFeatureCards"] == []
|
||||
assert body["demandForm"] == []
|
||||
@@ -517,7 +531,7 @@ def test_site_config_create_hero_slide_ignores_target_fields_and_returns_dedicat
|
||||
app.dependency_overrides.clear()
|
||||
|
||||
assert response.status_code == 201
|
||||
body = response.json()
|
||||
body = response.json()["data"]
|
||||
assert body["title"] == "新轮播"
|
||||
assert body["image"] is None
|
||||
assert "targetType" not in body
|
||||
@@ -537,7 +551,7 @@ def test_site_config_create_demand_form_rejects_duplicate_singleton():
|
||||
app.dependency_overrides.clear()
|
||||
|
||||
assert response.status_code == 409
|
||||
assert response.json()["code"] == "MODULE_CONFIG_SINGLETON_EXISTS"
|
||||
assert response.json()["errorCode"] == "MODULE_CONFIG_SINGLETON_EXISTS"
|
||||
assert not fake_db.added
|
||||
assert not fake_db.committed
|
||||
|
||||
@@ -561,7 +575,7 @@ def test_site_config_patch_hero_slide_ignores_target_fields_and_returns_dedicate
|
||||
app.dependency_overrides.clear()
|
||||
|
||||
assert response.status_code == 200
|
||||
body = response.json()
|
||||
body = response.json()["data"]
|
||||
assert body["title"] == "夏日贵州小包团"
|
||||
assert body["image"] is None
|
||||
assert "targetType" not in body
|
||||
@@ -590,8 +604,8 @@ def test_site_config_reorder_reassigns_sort_order_and_returns_items():
|
||||
assert response.status_code == 200
|
||||
assert [item.id for item in items] == ["slide-1", "slide-2", "slide-3"]
|
||||
assert {item.id: item.sortOrder for item in items} == {"slide-2": 0, "slide-1": 1, "slide-3": 2}
|
||||
assert [item["id"] for item in response.json()["items"]] == ["slide-2", "slide-1", "slide-3"]
|
||||
assert [item["sortOrder"] for item in response.json()["items"]] == [0, 1, 2]
|
||||
assert [item["id"] for item in response.json()["data"]["items"]] == ["slide-2", "slide-1", "slide-3"]
|
||||
assert [item["sortOrder"] for item in response.json()["data"]["items"]] == [0, 1, 2]
|
||||
assert fake_db.committed
|
||||
assert fake_db.added[-1].action == "reorder"
|
||||
|
||||
@@ -619,7 +633,7 @@ def test_site_config_reorder_rejects_duplicate_missing_and_unknown_ids(item_ids)
|
||||
app.dependency_overrides.clear()
|
||||
|
||||
assert response.status_code == 400
|
||||
assert response.json()["code"] == "MODULE_CONFIG_REORDER_INVALID"
|
||||
assert response.json()["errorCode"] == "MODULE_CONFIG_REORDER_INVALID"
|
||||
assert not fake_db.committed
|
||||
|
||||
|
||||
@@ -648,7 +662,7 @@ def test_admin_media_upload_streams_image_to_oss_records_asset_and_audits(monkey
|
||||
app.dependency_overrides.clear()
|
||||
|
||||
assert response.status_code == 201
|
||||
body = response.json()
|
||||
body = response.json()["data"]
|
||||
assert body["url"].startswith("https://cdn.example.test/admin/heroSlides/")
|
||||
assert body["name"] == "hero.png"
|
||||
assert body["mimeType"] == "image/png"
|
||||
@@ -675,7 +689,7 @@ def test_admin_media_upload_rejects_non_image_file():
|
||||
app.dependency_overrides.clear()
|
||||
|
||||
assert response.status_code == 400
|
||||
assert response.json()["code"] == "MEDIA_UPLOAD_INVALID_TYPE"
|
||||
assert response.json()["errorCode"] == "MEDIA_UPLOAD_INVALID_TYPE"
|
||||
assert not fake_db.added
|
||||
assert not fake_db.committed
|
||||
|
||||
@@ -700,7 +714,11 @@ def test_admin_leads_endpoint_accepts_source_keyword_and_created_range_filters()
|
||||
app.dependency_overrides.clear()
|
||||
|
||||
assert response.status_code == 200
|
||||
assert response.json() == {"items": []}
|
||||
assert response.json() == {
|
||||
"code": 200,
|
||||
"msg": "success",
|
||||
"data": {"items": []},
|
||||
}
|
||||
stmt = str(fake_db.scalar_statements[0])
|
||||
assert '"Lead".status' in stmt
|
||||
assert '"Lead"."sourcePage"' in stmt
|
||||
@@ -737,7 +755,7 @@ def test_admin_lead_status_update_returns_updated_status_and_audits():
|
||||
app.dependency_overrides.clear()
|
||||
|
||||
assert response.status_code == 200
|
||||
assert response.json()["status"] == "contacted"
|
||||
assert response.json()["data"]["status"] == "contacted"
|
||||
assert lead.status == "contacted"
|
||||
assert fake_db.committed
|
||||
assert fake_db.added[-1].entity == "lead"
|
||||
|
||||
Reference in New Issue
Block a user