feat: add utoipa path annotations to all API handlers and wire OpenAPI spec

- Add #[utoipa::path] annotations to all 70+ handler functions across
  auth, config, workflow, and message modules
- Add IntoParams/ToSchema derives to Pagination, PaginatedResponse, ApiResponse
  in erp-core, and MessageQuery/TemplateQuery in erp-message
- Collect all module paths into OpenAPI spec via AuthApiDoc, ConfigApiDoc,
  WorkflowApiDoc, MessageApiDoc structs in erp-server main.rs
- Update openapi_spec handler to merge all module specs
- The /docs/openapi.json endpoint now returns complete API documentation
  with all endpoints, request/response schemas, and security requirements

crates/erp-workflow/src/handler/definition_handler.rs

@@ -12,6 +12,18 @@ use crate::dto::{CreateProcessDefinitionReq, ProcessDefinitionResp, UpdateProces
 use crate::service::definition_service::DefinitionService;
 use crate::workflow_state::WorkflowState;
 
+#[utoipa::path(
+    get,
+    path = "/api/v1/workflow/definitions",
+    params(Pagination),
+    responses(
+        (status = 200, description = "成功", body = ApiResponse<PaginatedResponse<ProcessDefinitionResp>>),
+        (status = 401, description = "未授权"),
+        (status = 403, description = "权限不足"),
+    ),
+    security(("bearer_auth" = [])),
+    tag = "流程定义"
+)]
 /// GET /api/v1/workflow/definitions
 pub async fn list_definitions<S>(
     State(state): State<WorkflowState>,
@@ -39,6 +51,18 @@ where
     })))
 }
 
+#[utoipa::path(
+    post,
+    path = "/api/v1/workflow/definitions",
+    request_body = CreateProcessDefinitionReq,
+    responses(
+        (status = 200, description = "成功", body = ApiResponse<ProcessDefinitionResp>),
+        (status = 401, description = "未授权"),
+        (status = 403, description = "权限不足"),
+    ),
+    security(("bearer_auth" = [])),
+    tag = "流程定义"
+)]
 /// POST /api/v1/workflow/definitions
 pub async fn create_definition<S>(
     State(state): State<WorkflowState>,
@@ -65,6 +89,19 @@ where
     Ok(Json(ApiResponse::ok(resp)))
 }
 
+#[utoipa::path(
+    get,
+    path = "/api/v1/workflow/definitions/{id}",
+    params(("id" = Uuid, Path, description = "流程定义ID")),
+    responses(
+        (status = 200, description = "成功", body = ApiResponse<ProcessDefinitionResp>),
+        (status = 401, description = "未授权"),
+        (status = 403, description = "权限不足"),
+        (status = 404, description = "流程定义不存在"),
+    ),
+    security(("bearer_auth" = [])),
+    tag = "流程定义"
+)]
 /// GET /api/v1/workflow/definitions/{id}
 pub async fn get_definition<S>(
     State(state): State<WorkflowState>,
@@ -81,6 +118,20 @@ where
     Ok(Json(ApiResponse::ok(resp)))
 }
 
+#[utoipa::path(
+    put,
+    path = "/api/v1/workflow/definitions/{id}",
+    params(("id" = Uuid, Path, description = "流程定义ID")),
+    request_body = UpdateProcessDefinitionReq,
+    responses(
+        (status = 200, description = "成功", body = ApiResponse<ProcessDefinitionResp>),
+        (status = 401, description = "未授权"),
+        (status = 403, description = "权限不足"),
+        (status = 404, description = "流程定义不存在"),
+    ),
+    security(("bearer_auth" = [])),
+    tag = "流程定义"
+)]
 /// PUT /api/v1/workflow/definitions/{id}
 pub async fn update_definition<S>(
     State(state): State<WorkflowState>,
@@ -98,6 +149,19 @@ where
     Ok(Json(ApiResponse::ok(resp)))
 }
 
+#[utoipa::path(
+    post,
+    path = "/api/v1/workflow/definitions/{id}/publish",
+    params(("id" = Uuid, Path, description = "流程定义ID")),
+    responses(
+        (status = 200, description = "成功", body = ApiResponse<ProcessDefinitionResp>),
+        (status = 401, description = "未授权"),
+        (status = 403, description = "权限不足"),
+        (status = 404, description = "流程定义不存在"),
+    ),
+    security(("bearer_auth" = [])),
+    tag = "流程定义"
+)]
 /// POST /api/v1/workflow/definitions/{id}/publish
 pub async fn publish_definition<S>(
     State(state): State<WorkflowState>,

crates/erp-workflow/src/handler/instance_handler.rs

@@ -12,6 +12,18 @@ use crate::dto::{ProcessInstanceResp, StartInstanceReq};
 use crate::service::instance_service::InstanceService;
 use crate::workflow_state::WorkflowState;
 
+#[utoipa::path(
+    post,
+    path = "/api/v1/workflow/instances",
+    request_body = StartInstanceReq,
+    responses(
+        (status = 200, description = "成功", body = ApiResponse<ProcessInstanceResp>),
+        (status = 401, description = "未授权"),
+        (status = 403, description = "权限不足"),
+    ),
+    security(("bearer_auth" = [])),
+    tag = "流程实例"
+)]
 /// POST /api/v1/workflow/instances
 pub async fn start_instance<S>(
     State(state): State<WorkflowState>,
@@ -38,6 +50,18 @@ where
     Ok(Json(ApiResponse::ok(resp)))
 }
 
+#[utoipa::path(
+    get,
+    path = "/api/v1/workflow/instances",
+    params(Pagination),
+    responses(
+        (status = 200, description = "成功", body = ApiResponse<PaginatedResponse<ProcessInstanceResp>>),
+        (status = 401, description = "未授权"),
+        (status = 403, description = "权限不足"),
+    ),
+    security(("bearer_auth" = [])),
+    tag = "流程实例"
+)]
 /// GET /api/v1/workflow/instances
 pub async fn list_instances<S>(
     State(state): State<WorkflowState>,
@@ -65,6 +89,19 @@ where
     })))
 }
 
+#[utoipa::path(
+    get,
+    path = "/api/v1/workflow/instances/{id}",
+    params(("id" = Uuid, Path, description = "流程实例ID")),
+    responses(
+        (status = 200, description = "成功", body = ApiResponse<ProcessInstanceResp>),
+        (status = 401, description = "未授权"),
+        (status = 403, description = "权限不足"),
+        (status = 404, description = "流程实例不存在"),
+    ),
+    security(("bearer_auth" = [])),
+    tag = "流程实例"
+)]
 /// GET /api/v1/workflow/instances/{id}
 pub async fn get_instance<S>(
     State(state): State<WorkflowState>,
@@ -81,6 +118,19 @@ where
     Ok(Json(ApiResponse::ok(resp)))
 }
 
+#[utoipa::path(
+    post,
+    path = "/api/v1/workflow/instances/{id}/suspend",
+    params(("id" = Uuid, Path, description = "流程实例ID")),
+    responses(
+        (status = 200, description = "成功"),
+        (status = 401, description = "未授权"),
+        (status = 403, description = "权限不足"),
+        (status = 404, description = "流程实例不存在"),
+    ),
+    security(("bearer_auth" = [])),
+    tag = "流程实例"
+)]
 /// POST /api/v1/workflow/instances/{id}/suspend
 pub async fn suspend_instance<S>(
     State(state): State<WorkflowState>,
@@ -97,6 +147,19 @@ where
     Ok(Json(ApiResponse::ok(())))
 }
 
+#[utoipa::path(
+    post,
+    path = "/api/v1/workflow/instances/{id}/terminate",
+    params(("id" = Uuid, Path, description = "流程实例ID")),
+    responses(
+        (status = 200, description = "成功"),
+        (status = 401, description = "未授权"),
+        (status = 403, description = "权限不足"),
+        (status = 404, description = "流程实例不存在"),
+    ),
+    security(("bearer_auth" = [])),
+    tag = "流程实例"
+)]
 /// POST /api/v1/workflow/instances/{id}/terminate
 pub async fn terminate_instance<S>(
     State(state): State<WorkflowState>,
@@ -113,6 +176,19 @@ where
     Ok(Json(ApiResponse::ok(())))
 }
 
+#[utoipa::path(
+    post,
+    path = "/api/v1/workflow/instances/{id}/resume",
+    params(("id" = Uuid, Path, description = "流程实例ID")),
+    responses(
+        (status = 200, description = "成功"),
+        (status = 401, description = "未授权"),
+        (status = 403, description = "权限不足"),
+        (status = 404, description = "流程实例不存在"),
+    ),
+    security(("bearer_auth" = [])),
+    tag = "流程实例"
+)]
 /// POST /api/v1/workflow/instances/{id}/resume
 pub async fn resume_instance<S>(
     State(state): State<WorkflowState>,

crates/erp-workflow/src/handler/task_handler.rs

@@ -12,6 +12,18 @@ use crate::dto::{CompleteTaskReq, DelegateTaskReq, TaskResp};
 use crate::service::task_service::TaskService;
 use crate::workflow_state::WorkflowState;
 
+#[utoipa::path(
+    get,
+    path = "/api/v1/workflow/tasks/pending",
+    params(Pagination),
+    responses(
+        (status = 200, description = "成功", body = ApiResponse<PaginatedResponse<TaskResp>>),
+        (status = 401, description = "未授权"),
+        (status = 403, description = "权限不足"),
+    ),
+    security(("bearer_auth" = [])),
+    tag = "流程任务"
+)]
 /// GET /api/v1/workflow/tasks/pending
 pub async fn list_pending_tasks<S>(
     State(state): State<WorkflowState>,
@@ -40,6 +52,18 @@ where
     })))
 }
 
+#[utoipa::path(
+    get,
+    path = "/api/v1/workflow/tasks/completed",
+    params(Pagination),
+    responses(
+        (status = 200, description = "成功", body = ApiResponse<PaginatedResponse<TaskResp>>),
+        (status = 401, description = "未授权"),
+        (status = 403, description = "权限不足"),
+    ),
+    security(("bearer_auth" = [])),
+    tag = "流程任务"
+)]
 /// GET /api/v1/workflow/tasks/completed
 pub async fn list_completed_tasks<S>(
     State(state): State<WorkflowState>,
@@ -68,6 +92,20 @@ where
     })))
 }
 
+#[utoipa::path(
+    post,
+    path = "/api/v1/workflow/tasks/{id}/complete",
+    params(("id" = Uuid, Path, description = "任务ID")),
+    request_body = CompleteTaskReq,
+    responses(
+        (status = 200, description = "成功", body = ApiResponse<TaskResp>),
+        (status = 401, description = "未授权"),
+        (status = 403, description = "权限不足"),
+        (status = 404, description = "任务不存在"),
+    ),
+    security(("bearer_auth" = [])),
+    tag = "流程任务"
+)]
 /// POST /api/v1/workflow/tasks/{id}/complete
 pub async fn complete_task<S>(
     State(state): State<WorkflowState>,
@@ -96,6 +134,20 @@ where
     Ok(Json(ApiResponse::ok(resp)))
 }
 
+#[utoipa::path(
+    post,
+    path = "/api/v1/workflow/tasks/{id}/delegate",
+    params(("id" = Uuid, Path, description = "任务ID")),
+    request_body = DelegateTaskReq,
+    responses(
+        (status = 200, description = "成功", body = ApiResponse<TaskResp>),
+        (status = 401, description = "未授权"),
+        (status = 403, description = "权限不足"),
+        (status = 404, description = "任务不存在"),
+    ),
+    security(("bearer_auth" = [])),
+    tag = "流程任务"
+)]
 /// POST /api/v1/workflow/tasks/{id}/delegate
 pub async fn delegate_task<S>(
     State(state): State<WorkflowState>,