Add Chinese comments for Temporal workflow flow

app/workers/activities/review_activities.py

@@ -1,4 +1,8 @@
-"""Review state management mock activities."""
+"""审核相关 activity。
+
+这里的函数都运行在 worker 侧，可以安全地做数据库 I/O。
+workflow 本身只负责调用这些 activity，不直接写数据库。
+"""
 
 from sqlalchemy import select
 
@@ -18,7 +22,13 @@ from app.workers.workflows.types import (
 
 @activity.defn
 async def mark_waiting_for_review_activity(payload: ReviewWaitActivityInput) -> None:
-    """Mark a workflow as waiting for a human review."""
+    """把 workflow 标记为等待人工审核。
+
+    这一步会做三件事：
+    1. 新增一条 review 类型的 workflow_step，状态是 waiting
+    2. 新增一条 review_task，供 API 查询待审核列表
+    3. 把订单和 workflow_run 都切到 waiting_review
+    """
 
     async with get_session_factory()() as session:
         order, workflow_run = await load_order_and_run(session, payload.order_id, payload.workflow_run_id)
@@ -47,7 +57,12 @@ async def mark_waiting_for_review_activity(payload: ReviewWaitActivityInput) ->
 
 @activity.defn
 async def complete_review_wait_activity(payload: ReviewResolutionActivityInput) -> None:
-    """Resolve the current waiting-review step before the next branch runs."""
+    """收口当前这次 waiting_review。
+
+    这里的职责不是决定后续怎么跑，而是把“等待审核”这个数据库状态结束掉：
+    - approve / rerun -> review step 记为 succeeded
+    - reject -> review step 记为 failed
+    """
 
     async with get_session_factory()() as session:
         order, workflow_run = await load_order_and_run(session, payload.order_id, payload.workflow_run_id)
@@ -62,6 +77,8 @@ async def complete_review_wait_activity(payload: ReviewResolutionActivityInput)
         )
         review_step = step_result.scalars().first()
         if review_step is not None:
+            # 只处理仍处于 waiting 的那条 review_step，
+            # 避免重复 signal 把历史 review 记录覆盖掉。
             review_step.step_status = (
                 StepStatus.FAILED if payload.decision == ReviewDecision.REJECT else StepStatus.SUCCEEDED
             )
@@ -82,7 +99,11 @@ async def complete_review_wait_activity(payload: ReviewResolutionActivityInput)
 
 @activity.defn
 async def mark_workflow_failed_activity(payload: WorkflowFailureActivityInput) -> None:
-    """Mark the persisted workflow state as failed."""
+    """把订单和 workflow_run 持久化为失败。
+
+    这个 activity 是 workflow 的“兜底收尾器”：
+    当任意步骤抛异常时，workflow 调它把数据库状态补完整。
+    """
 
     async with get_session_factory()() as session:
         order, workflow_run = await load_order_and_run(session, payload.order_id, payload.workflow_run_id)