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
2026-08-19 22:02:20 +08:00
parent d16924584c
commit e082bd2d98
28 changed files with 993 additions and 383 deletions

View File

@@ -143,7 +143,7 @@ def test_admin_concierge_list_returns_full_advisor_record():
app.dependency_overrides.clear()
assert response.status_code == 200
advisor = response.json()["advisors"][0]
advisor = response.json()["data"]["advisors"][0]
assert advisor["id"] == "advisor-amanda"
assert advisor["isActive"] is True
assert advisor["sortOrder"] == 0
@@ -170,7 +170,7 @@ def test_admin_concierge_create_appends_to_the_end():
app.dependency_overrides.clear()
assert response.status_code == 201
assert response.json()["id"] == "concierge-advisor-test-id"
assert response.json()["data"]["id"] == "concierge-advisor-test-id"
assert fake_db.added[0].name == "Mia"
assert fake_db.added[0].sortOrder == 3
assert fake_db.committed
@@ -190,8 +190,8 @@ def test_admin_concierge_patch_updates_details_and_active_state():
app.dependency_overrides.clear()
assert response.status_code == 200
assert response.json()["details"] == [{"icon": "navigate", "label": "擅长领域:亲子与自然探索"}]
assert response.json()["isActive"] is False
assert response.json()["data"]["details"] == [{"icon": "navigate", "label": "擅长领域:亲子与自然探索"}]
assert response.json()["data"]["isActive"] is False
assert advisor.isActive is False
assert fake_db.committed
@@ -208,7 +208,11 @@ def test_admin_concierge_delete_normalizes_remaining_order():
app.dependency_overrides.clear()
assert response.status_code == 200
assert response.json() == {"id": "advisor-1"}
assert response.json() == {
"code": 200,
"msg": "success",
"data": {"id": "advisor-1"},
}
assert second.sortOrder == 0
assert fake_db.deleted == [first]
assert fake_db.committed
@@ -227,7 +231,7 @@ def test_admin_concierge_reorder_rejects_incomplete_ids():
app.dependency_overrides.clear()
assert response.status_code == 400
assert response.json()["code"] == "CONCIERGE_REORDER_INVALID"
assert response.json()["errorCode"] == "CONCIERGE_REORDER_INVALID"
assert not fake_db.committed
@@ -243,6 +247,9 @@ def test_public_concierge_returns_only_frontend_fields_for_active_advisors():
assert response.status_code == 200
assert response.json() == {
"code": 200,
"msg": "success",
"data": {
"advisors": [
{
"avatar": "https://example.test/amanda.jpg",
@@ -255,4 +262,5 @@ def test_public_concierge_returns_only_frontend_fields_for_active_advisors():
"qrImage": "https://example.test/amanda-qr.png",
}
]
},
}