refactor(phase8/task53/g4d-be): conversation chat ops prefix /api/v1 → /api/v2 (chat-rooted)

[earayu]

Summary

G4d backend: hard-cut chat_router mount from /api/v1 to /api/v2, keeping the chat-rooted /chats/{chat_id}/... nesting unchanged (Option A canonical, locked by 符炫炜 ≈2026-04-25 16:18 in #模块化重构).

Routes migrated

Method	Old	New
GET	/api/v1/chats/{chat_id}/feedback	/api/v2/chats/{chat_id}/feedback
POST	/api/v1/chats/{chat_id}/turns/{turn_id}/feedback	/api/v2/chats/{chat_id}/turns/{turn_id}/feedback
DELETE	/api/v1/chats/{chat_id}/turns/{turn_id}/feedback	/api/v2/chats/{chat_id}/turns/{turn_id}/feedback
POST	/api/v1/chats/{chat_id}/search	/api/v2/chats/{chat_id}/search
POST	/api/v1/chats/{chat_id}/documents	/api/v2/chats/{chat_id}/documents
GET	/api/v1/chats/{chat_id}/documents/{document_id}	/api/v2/chats/{chat_id}/documents/{document_id}

bots_router v2 chat CRUD (/api/v2/bots/{bot_id}/chats/...) is untouched; both routers now coexist under /api/v2 with non-overlapping paths.

Scope discipline

• Hard cut, not alias per D7-4 canonical (/api/v1/chats/* removed entirely)
• aperag/app.py:239 — single mount prefix change chat_router /api/v1 → /api/v2
• aperag/mcp/server.py:342 — server-internal MCP search call retargeted to keep this PR self-consistent (no FE/external dep)
• No FE writes — web/src/api-v2/schema.d.ts regen + web/src/features/bot/client-api.ts caller swap + Hurl/e2e + test_web_typed_api_contract.py assertion update belong to companion task fix: husky hooks #54 G4d-FE (@dongdong claimed)

Cross-task sequencing

After this PR merges to main, FE clients calling /api/v1/chats/... will get 404 until #54 G4d-FE PR also merges. dongdong has #54 claimed and is waiting on this PR's OpenAPI diff to regen schema.d.ts. Coordinate merge windows to keep the gap minimal.

Gate

• uv run pytest tests/unit_test/test_chat_ops_v2_openapi_contract.py — 3/3 pass (3 new contract gates)
• uv run pytest tests/unit_test/test_modularization_boundaries.py — 21/21 pass (G1-G19 invariants intact)
• uv run ruff format --check / ruff check — clean
• make openapi-generate regenerates spec; tracked artifacts in web/src/api-v2/ will be regenerated by fix: husky hooks #54 G4d-FE

OpenAPI diff (5 paths)

After regen, openapi.public.json shifts the chat-rooted paths:

- /api/v1/chats/{chat_id}/feedback
+ /api/v2/chats/{chat_id}/feedback
- /api/v1/chats/{chat_id}/turns/{turn_id}/feedback
+ /api/v2/chats/{chat_id}/turns/{turn_id}/feedback
- /api/v1/chats/{chat_id}/search
+ /api/v2/chats/{chat_id}/search
- /api/v1/chats/{chat_id}/documents
+ /api/v2/chats/{chat_id}/documents
- /api/v1/chats/{chat_id}/documents/{document_id}
+ /api/v2/chats/{chat_id}/documents/{document_id}

Bot-rooted chat CRUD (/api/v2/bots/{bot_id}/chats/...) is unchanged.

Test plan

• All chat_router routes mounted under /api/v2
• No /api/v1/chats/ ghost remains
• Nesting stays chat-rooted (Option A, no /bots/ prefix)
• CI lint-and-unit green
• Companion fix: husky hooks #54 G4d-FE merges into main (sequencing dependency)

Closes

Task #53 — Phase 8 第二批 G4d-BE conversation chat ops prefix migrate to /api/v2 (chat-rooted)

🤖 Generated with Claude Code