feat: 更新工作流 API 合同，补充日期时间字段的 RFC3339 格式描述，优化错误信息返回

Author: LeoQuote

.specify/memory/constitution.md

@@ -1,11 +1,10 @@
 <!--
 Sync Impact Report
-- Version change: 1.0.0 -> 1.1.0
+- Version change: 1.1.0 -> 1.2.0
 - Modified principles:
-	- V. Safe Query and Debuggability -> V. Safe Query, API Errors, and Debuggability
-	- Delivery Workflow & Quality Gates: added breaking-change migration rule
-- Added sections:
 	- None
+- Added sections:
+	- VI. DRF Serializer-First API Responses
 - Removed sections:
 	- None
 - Follow-up TODOs:
@@ -53,6 +52,16 @@ flows MUST assert both success and failure paths. Rationale: predictable debuggi
 safe execution, and controlled error disclosure are core trust requirements for a
 database operations platform.
 
+### VI. DRF Serializer-First API Responses
+API implementations SHOULD return response data through Django REST Framework
+serializers when fields require typed representation, validation, or public
+contract stability. Endpoints MUST NOT hand-encode JSON or bypass serializers for
+typed fields such as datetimes, identifiers, booleans, decimals, or nested
+contract objects unless the exception is explicitly documented and covered by a
+targeted test. Rationale: serializer-driven responses keep runtime output,
+OpenAPI schemas, and generated clients aligned, and prevent ad hoc JSON encoding
+from producing field formats that violate the public API contract.
+
 ## Testing Standards
 
 - Test suites MUST default to pytest invocation and naming conventions configured in
@@ -90,4 +99,4 @@ Versioning policy follows semantic versioning for governance:
 Compliance review is mandatory in planning and PR review. Constitution checks in
 planning artifacts MUST pass or carry an explicit, approved exception record.
 
-**Version**: 1.1.0 | **Ratified**: 2026-04-28 | **Last Amended**: 2026-08-31
+**Version**: 1.2.0 | **Ratified**: 2026-04-28 | **Last Amended**: 2026-09-03

specs/005-workflow-api-contract/contracts/workflow-api-contract.openapi.yaml

@@ -265,6 +265,8 @@ components:
         create_time:
           type: string
           format: date-time
+          description: RFC3339-compatible timestamp rendered with a UTC suffix.
+          example: '2017-07-21T17:32:28Z'
           nullable: true
     WorkflowContent:
       type: object
@@ -307,6 +309,8 @@ components:
         operation_time:
           type: string
           format: date-time
+          description: RFC3339-compatible timestamp rendered with a UTC suffix.
+          example: '2017-07-21T17:32:28Z'
     WorkflowLogList:
       type: object
       additionalProperties: true

specs/005-workflow-api-contract/spec.md

@@ -11,6 +11,10 @@
 
 - Q: 现有 SQL Workflow logs/status/approval/execution API 是否缺少 OpenAPI request/response body 契约？ → A: 是；补齐现有接口 schema，不新增重复接口。
 
+### Session 2026-09-03
+
+- Q: API responses that document fields as `date-time` should use which wire format? → A: Preserve the existing datetime value and render it as an RFC3339-compatible UTC-suffixed string, such as `2017-07-21T17:32:28Z`.
+
 ## User Scenarios & Testing *(mandatory)*
 
 ### User Story 1 - Preserve CLI Review Text From Workflow Results (Priority: P1)
@@ -98,6 +102,7 @@ As a CLI or generated-client consumer, I can rely on a documented extension stra
 - **FR-019**: The existing SQL Workflow approval endpoint MUST document that the acting user and workflow are derived from the authenticated session and path audit identifier, that the request body may contain `audit_remark`, and that the response body is the standard action result.
 - **FR-020**: The existing SQL Workflow execution endpoint MUST document that the acting user and workflow are derived from the authenticated session and path audit identifier, that the request body requires execution `mode`, and that the response body is the standard action result.
 - **FR-021**: SQL Workflow approval and execution contracts MUST NOT require or document an `engineer` request field for these existing audit-id endpoints.
+- **FR-022**: API response fields documented with OpenAPI `format: date-time`, including workflow `create_time` and log `operation_time`, MUST preserve the existing datetime value and render it as an RFC3339-compatible UTC-suffixed string ending in `Z`.
 
 ### Test Strategy Constraints *(mandatory)*
 
@@ -126,6 +131,7 @@ As a CLI or generated-client consumer, I can rely on a documented extension stra
 - **SC-005**: Existing CLI review text and structured review JSON fixtures remain unchanged for all covered happy-path workflow examples.
 - **SC-006**: 100% of unauthorized, missing, and invalid instance or workflow lookup tests return sanitized deterministic failures.
 - **SC-007**: Generated OpenAPI output shows response bodies for SQL Workflow logs and status, and request/response bodies for SQL Workflow approval and execution, in 100% of contract validation runs.
+- **SC-008**: 100% of workflow API `date-time` response fields checked in this feature end in `Z` and parse as RFC3339-compatible timestamps.
 
 ## Assumptions
 

sql/archiver.py

@@ -215,7 +215,7 @@ def archive_apply(request):
         try:
             audit_handler.create_audit()
         except AuditException as e:
-            logger.error(f"新建审批流失败: {str(e)}")
+            logger.info("新建审批流失败, reason=%s", e)
             return JsonResponse(
                 {"status": 1, "msg": "新建审批流失败, 请联系管理员", "data": {}}
             )
@@ -278,7 +278,7 @@ def archive_audit(request):
                 audit_status, request.user, audit_remark
             )
         except AuditException as e:
-            return render(request, "error.html", {"errMsg": f"审核失败: {str(e)}"})
+            return render(request, "error.html", {"errMsg": f"审核失败: {e}"})
         auditor.workflow.status = auditor.audit.current_status
         if auditor.audit.current_status == WorkflowStatus.PASSED:
             auditor.workflow.state = True

sql/models.py

@@ -316,6 +316,11 @@ def get_audit(self) -> Optional["WorkflowAudit"]:
         except WorkflowAudit.DoesNotExist:
             return None
 
+    @property
+    def audit_id(self) -> Optional[int]:
+        audit = self.get_audit()
+        return audit.audit_id if audit else None
+
 
 class SqlWorkflow(models.Model, WorkflowAuditMixin):
     """

sql/query_privileges.py

@@ -312,7 +312,7 @@ def query_priv_apply(request):
         with transaction.atomic():
             audit_handler.create_audit()
     except AuditException as e:
-        logger.error(f"新建审批流失败, {str(e)}")
+        logger.info("新建审批流失败, reason=%s", e)
         result["status"] = 1
         result["msg"] = "新建审批流失败, 请联系管理员"
         return HttpResponse(json.dumps(result), content_type="application/json")
@@ -482,7 +482,7 @@ def query_priv_audit(request):
                 audit_status, request.user, audit_remark
             )
         except AuditException as e:
-            return render(request, "error.html", {"errMsg": f"审核失败: {str(e)}"})
+            return render(request, "error.html", {"errMsg": f"审核失败: {e}"})
         # 统一 call back, 内部做授权和更新数据库内容
         _query_apply_audit_call_back(
             auditor.audit.workflow_id, auditor.audit.current_status

sql/utils/workflow_audit.py

@@ -33,7 +33,7 @@
 
 
 class AuditException(Exception):
-    pass
+    """审核流程中的业务异常，异常消息会直接展示给终端用户。"""
 
 
 class ReviewNodeType(Enum):

sql_api/api_workflow.py

@@ -257,7 +257,7 @@ def post(self, request):
                 action, user, serializer.data["audit_remark"]
             )
         except AuditException as e:
-            raise serializers.ValidationError({"errors": f"操作失败, {str(e)}"})
+            raise serializers.ValidationError({"errors": f"操作失败, {e}"})
 
         # 最后处置一下原本工单的状态
         if auditor.workflow_type == WorkflowType.QUERY:

sql_api/api_workflow_operations.py

@@ -416,9 +416,9 @@ def post(self, request, audit_id):
                 detail = auditor.operate(
                     WorkflowAction.PASS, request.user, data["audit_remark"]
                 )
-            except AuditException:
-                logger.exception("审核工单失败，audit_id=%s", audit_id)
-                raise ValidationError({"detail": "审核工单失败"})
+            except AuditException as e:
+                logger.info("审核工单失败，audit_id=%s, reason=%s", audit_id, e)
+                raise ValidationError({"detail": f"审核工单失败, 失败原因: {e}"})
             if auditor.audit.current_status == WorkflowStatus.PASSED:
                 auditor.workflow.status = "workflow_review_pass"
                 auditor.workflow.save(update_fields=["status"])
@@ -449,9 +449,9 @@ def post(self, request, audit_id):
                 detail = auditor.operate(
                     WorkflowAction.REJECT, request.user, data["reject_remark"]
                 )
-            except AuditException:
-                logger.exception("拒绝工单失败，audit_id=%s", audit_id)
-                raise ValidationError({"detail": "拒绝工单失败"})
+            except AuditException as e:
+                logger.info("拒绝工单失败，audit_id=%s, reason=%s", audit_id, e)
+                raise ValidationError({"detail": f"拒绝工单失败, 失败原因: {e}"})
             workflow.status = "workflow_abort"
             workflow.save(update_fields=["status"])
             if was_scheduled:
@@ -587,9 +587,9 @@ def post(self, request, audit_id):
             auditor = get_auditor(workflow=workflow, sys_config=config)
             try:
                 detail = auditor.operate(action, request.user, data["cancel_remark"])
-            except AuditException:
-                logger.exception("取消工单失败，audit_id=%s", audit_id)
-                raise ValidationError({"detail": "终止工单失败"})
+            except AuditException as e:
+                logger.info("取消工单失败，audit_id=%s, reason=%s", audit_id, e)
+                raise ValidationError({"detail": f"终止工单失败, 失败原因: {e}"})
             workflow.status = "workflow_abort"
             workflow.save(update_fields=["status"])
             if was_scheduled:
@@ -661,4 +661,7 @@ def get(self, request, audit_id):
                 "operation_time",
             )
         )
-        return Response({"total": len(rows), "rows": rows})
+        serializer = WorkflowLogListResponseSerializer(
+            {"total": len(rows), "rows": rows}
+        )
+        return Response(serializer.data)

sql_api/serializers.py

@@ -470,17 +470,13 @@ class Meta:
 
 
 class SqlWorkflowDetailSerializer(serializers.ModelSerializer):
-    audit_id = serializers.SerializerMethodField()
+    audit_id = serializers.IntegerField(read_only=True, allow_null=True)
     workflow_id = serializers.IntegerField(source="id", read_only=True)
     instance_name = serializers.CharField(
         source="instance.instance_name", read_only=True
     )
     status_display = serializers.CharField(source="get_status_display", read_only=True)
 
-    def get_audit_id(self, obj):
-        audit = obj.get_audit()
-        return audit.audit_id if audit else None
-
     class Meta:
         model = SqlWorkflow
         fields = [