feat(api): 统一公开接口为 /api/v1 前缀

将通用生成、Gemini、可灵、火山、健康检查与 OpenAPI 的推荐入口统一到 /api/v1，并保留历史路径作为兼容别名。同步更新代理配置、接入文档、接口清单和前缀回归测试。\n\n验证：go vet ./...；go test ./...；pnpm openapi；pnpm lint；pnpm test；pnpm build；公开 OpenAPI 71 个方法与接口清单机器比对一致。

apps/api/internal/httpapi/handlers.go

@@ -31,7 +31,7 @@ const (
 // @Tags system
 // @Produce json
 // @Success 200 {object} HealthResponse
-// @Router /healthz [get]
+// @Router /api/v1/healthz [get]
 func (s *Server) health(w http.ResponseWriter, r *http.Request) {
 	writeJSON(w, http.StatusOK, map[string]any{
 		"ok":           true,
@@ -48,7 +48,7 @@ func (s *Server) health(w http.ResponseWriter, r *http.Request) {
 // @Produce json
 // @Success 200 {object} ReadyResponse
 // @Failure 503 {object} ErrorEnvelope
-// @Router /readyz [get]
+// @Router /api/v1/readyz [get]
 func (s *Server) ready(w http.ResponseWriter, r *http.Request) {
 	ctx, cancel := context.WithTimeout(r.Context(), postgresReadinessTimeout)
 	defer cancel()
@@ -1021,7 +1021,7 @@ func (s *Server) listModelRateLimitStatuses(w http.ResponseWriter, r *http.Reque
 
 // createTask godoc
 // @Summary 创建或执行 AI 任务
-// @Description 网关任务接口按 model 选择平台模型；除 /api/v1/chat/completions 以外的 /api/v1 任务路径返回任务受理结果，OpenAI-compatible 路径同步返回兼容响应或 SSE 流。
+// @Description 统一公开入口按 model 选择平台模型并默认同步返回兼容响应；设置 X-Async=true 时异步创建任务并返回 202。
 // @Tags tasks
 // @Accept json
 // @Produce json
@@ -1047,22 +1047,6 @@ func (s *Server) listModelRateLimitStatuses(w http.ResponseWriter, r *http.Reque
 // @Router /api/v1/music/generations [post]
 // @Router /api/v1/speech/generations [post]
 // @Router /api/v1/voice_clone [post]
-// @Router /embeddings [post]
-// @Router /v1/embeddings [post]
-// @Router /reranks [post]
-// @Router /v1/reranks [post]
-// @Router /images/generations [post]
-// @Router /v1/images/generations [post]
-// @Router /images/edits [post]
-// @Router /v1/images/edits [post]
-// @Router /song/generations [post]
-// @Router /v1/song/generations [post]
-// @Router /music/generations [post]
-// @Router /v1/music/generations [post]
-// @Router /speech/generations [post]
-// @Router /v1/speech/generations [post]
-// @Router /voice_clone [post]
-// @Router /v1/voice_clone [post]
 func (s *Server) createTask(kind string, compatible bool) http.Handler {
 	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 		user, ok := auth.UserFromContext(r.Context())
@@ -1214,8 +1198,6 @@ func (s *Server) createAPIV1ChatCompletions() http.Handler {
 // @Failure 403 {object} ErrorEnvelope
 // @Failure 429 {object} ErrorEnvelope
 // @Failure 502 {object} ErrorEnvelope
-// @Router /chat/completions [post]
-// @Router /v1/chat/completions [post]
 func openAIChatCompletionsDoc() {}
 
 // openAIResponsesDoc godoc
@@ -1234,8 +1216,6 @@ func openAIChatCompletionsDoc() {}
 // @Failure 402 {object} ErrorEnvelope
 // @Failure 403 {object} ErrorEnvelope
 // @Failure 503 {object} ErrorEnvelope "response_chain_unavailable"
-// @Router /responses [post]
-// @Router /v1/responses [post]
 // @Router /api/v1/responses [post]
 func openAIResponsesDoc() {}
 
@@ -1660,7 +1640,6 @@ func matchedRateLimitRule(policy map[string]any, metric string) map[string]any {
 // @Failure 500 {object} ErrorEnvelope
 // @Router /api/workspace/tasks [get]
 // @Router /api/v1/tasks [get]
-// @Router /tasks [get]
 func (s *Server) listTasks(w http.ResponseWriter, r *http.Request) {
 	user, ok := auth.UserFromContext(r.Context())
 	if !ok {
@@ -1769,7 +1748,6 @@ func boolValue(body map[string]any, key string) bool {
 // @Failure 500 {object} ErrorEnvelope
 // @Router /api/workspace/tasks/{taskID} [get]
 // @Router /api/v1/tasks/{taskID} [get]
-// @Router /tasks/{taskID} [get]
 func (s *Server) getTask(w http.ResponseWriter, r *http.Request) {
 	task, err := s.store.GetTask(r.Context(), r.PathValue("taskID"))
 	if err == nil {
@@ -1802,8 +1780,6 @@ func (s *Server) getTask(w http.ResponseWriter, r *http.Request) {
 // @Failure 500 {object} ErrorEnvelope
 // @Router /api/workspace/tasks/{taskID}/cancel [post]
 // @Router /api/v1/tasks/{taskID}/cancel [post]
-// @Router /v1/tasks/{taskID}/cancel [post]
-// @Router /tasks/{taskID}/cancel [post]
 func (s *Server) cancelTask(w http.ResponseWriter, r *http.Request) {
 	user, ok := auth.UserFromContext(r.Context())
 	if !ok {
@@ -1840,7 +1816,6 @@ func (s *Server) cancelTask(w http.ResponseWriter, r *http.Request) {
 // @Failure 500 {object} ErrorEnvelope
 // @Router /api/workspace/tasks/{taskID}/param-preprocessing [get]
 // @Router /api/v1/tasks/{taskID}/param-preprocessing [get]
-// @Router /tasks/{taskID}/param-preprocessing [get]
 func (s *Server) taskParamPreprocessing(w http.ResponseWriter, r *http.Request) {
 	task, err := s.store.GetTask(r.Context(), r.PathValue("taskID"))
 	if err != nil {
@@ -1874,7 +1849,6 @@ func (s *Server) taskParamPreprocessing(w http.ResponseWriter, r *http.Request)
 // @Failure 500 {object} ErrorEnvelope
 // @Router /api/workspace/tasks/{taskID}/events [get]
 // @Router /api/v1/tasks/{taskID}/events [get]
-// @Router /tasks/{taskID}/events [get]
 func (s *Server) taskEvents(w http.ResponseWriter, r *http.Request) {
 	task, err := s.store.GetTask(r.Context(), r.PathValue("taskID"))
 	if err != nil {