crawlrs 0.2.0

crawlrs - Enterprise-grade web scraping and crawling platform built with Rust
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
// Copyright (c) 2025-2026 Kirky.X🌠
// SPDX-License-Identifier: Apache-2.0

//! 请求合并协调器
//!
//! 从 [`crate::workers::scrape_worker::ScrapeWorker`] 抽取的请求合并协调逻辑,
//! 遵循 SRP:ScrapeWorker 专注任务调度,coalesce 协调由本类型独立负责。
//!
//! # 职责
//!
//! 对同合并键并发请求执行 single-flight 协调:
//! - **Proceed 路径**:首个 worker(leader)获得执行权,成功落库结果后通过 guard
//!   广播 `CoalesceSignal::Completed { success: true }`;失败/取消路径广播
//!   `Completed { success: false }`
//! - **Wait 路径**:等待方监听广播信号(45s 超时):
//!   - `Completed { success: true }` → 按 leader task_id 从 `result_repo` 读取结果,
//!     命中则 mark_completed,未命中则延后 5s 重排(leader 仍在写入)
//!   - `Completed { success: false }` → leader 已失败/取消,不查询结果,直接重排
//!   - `Purged`(僵死条目被清理)/ recv `Closed`(leader 异常)/ 超时 →
//!     不 mark_failed leader 任务,走等待方自身重排(超上限后才 mark_failed 自身)
//!
//! # 信号语义
//!
//! 原代码 `rx.recv.await` 无超时且不区分信号来源,leader panic / 死锁会导致等待方
//! 永久挂起或误判完成。现等待方区分 leader 成功、失败与异常消失:只有成功才按
//! leader task_id 查询结果;失败与异常(Purged/Closed/超时)一律走自身重排,
//! 避免误杀 leader 任务、无条件 purge 全表或做无效的结果查询。

mod key;
mod leader;
// `RequestCoalescer`/`CoalesceKey` 由公开接口(`WorkerManagerDeps.request_coalescer`、
// `ScrapeWorkerDeps.coalesce_coordinator` 的泛型实参)暴露,保持 pub;
// `CoalesceGuard`/`CoalesceResult` 仅在 crate 内使用,收窄为 pub(crate)。
pub(crate) use key::{CoalesceGuard, CoalesceResult};
pub use key::{CoalesceKey, RequestCoalescer};
use leader::{recv_leader_signal, LeaderSignal};

use crate::domain::models::{Task, TaskStatus};
use crate::domain::repositories::scrape_result_repository::ScrapeResultRepository;
use crate::domain::repositories::task_repository::TaskRepository;
use crate::utils::coalesce::CoalesceSignal;
use crate::utils::url_redaction::redact_url_for_log;
use anyhow::Result;
use chrono::Utc;
use log::{error, info, warn};
use serde_json::json;
use std::sync::Arc;

/// 请求合并协调器
///
/// 封装同合并键(租户 + 规范化 URL + 完整请求身份指纹)并发请求的
/// single-flight 协调逻辑,从 ScrapeWorker 抽离。
/// 合并键构造见 [`CoalesceKey`]:跨租户或 `ScrapeOptions` 内容相关字段
/// 任一不同一律不合并;`cache_mode` 本身不参与,但由其派生的
/// `cache_read_allowed` 布尔投影参与(禁止读缓存的请求不与可读缓存请求合并)。
///
/// # 字段
///
/// - `repository`:任务仓储(mark_completed / mark_failed / update)
/// - `result_repository`:抓取结果仓储(等待方从 result_repo 读取首个 worker 结果)
/// - `request_coalescer`:请求合并器(try_start / purge_stale)
///
/// # Clone 语义
///
/// 所有字段均为 `Arc`,`#[derive(Clone)]` 仅增加引用计数(O(1) 原子操作),
/// 不复制底层数据。测试中可在 spawn 的 task 中使用 clone。
#[derive(Clone)]
pub struct CoalesceCoordinator {
    /// 任务仓储
    repository: Arc<dyn TaskRepository>,
    /// 抓取结果仓储
    result_repository: Arc<dyn ScrapeResultRepository>,
    /// 请求合并器
    request_coalescer: Arc<RequestCoalescer>,
}

impl CoalesceCoordinator {
    /// 创建新的协调器
    ///
    /// # 参数
    ///
    /// - `repository`:任务仓储(实现 [`TaskRepository`] trait)
    /// - `result_repository`:抓取结果仓储(实现 [`ScrapeResultRepository`] trait)
    /// - `request_coalescer`:请求合并器(由 `WorkerManager` 从
    ///   `ServicesComponents.request_coalescer` 注入,所有 worker 共享同一实例)
    #[must_use]
    pub fn new(
        repository: Arc<dyn TaskRepository>,
        result_repository: Arc<dyn ScrapeResultRepository>,
        request_coalescer: Arc<RequestCoalescer>,
    ) -> Self {
        Self {
            repository,
            result_repository,
            request_coalescer,
        }
    }

    /// 尝试获取合并键的执行权
    ///
    /// `key` 由调用方按任务上下文构造:租户(`Task::team_id`)+ 规范化 URL +
    /// 本次请求完整 `ScrapeOptions` 的指纹。键不同的请求不会合并(跨租户泄露防护)。
    ///
    /// # 返回值
    ///
    /// - `Ok(Some(guard))`:获得执行权,调用方应继续抓取,guard Drop 时广播
    /// - `Ok(None)`:已被其他 worker 处理(等待方从 result_repo 读到结果,或被延后重排),
    ///   调用方应直接返回 Ok()
    /// - `Err(e)`:协调失败(租户不一致 / 超时 / 仓储错误),调用方应失败处理
    pub(crate) async fn try_coalesce(
        &self,
        key: &CoalesceKey,
        task: &Task,
        worker_id: crate::domain::id::Id,
    ) -> Result<Option<CoalesceGuard>> {
        // 合并键租户必须与任务租户一致。debug 构建直接 panic 暴露编程错误;
        // release 构建显性返回错误,绝不按错误租户静默合并/落库。
        if key.team_id() != task.team_id {
            debug_assert_eq!(
                key.team_id(),
                task.team_id,
                "coalesce key tenant must match task tenant"
            );
            error!(
                "coalesce key tenant mismatch: key team {} vs task team {} (task {})",
                key.team_id(),
                task.team_id,
                task.id
            );
            anyhow::bail!(
                "coalesce key tenant mismatch: key team {} != task team {}",
                key.team_id(),
                task.team_id
            );
        }

        match self.request_coalescer.try_start(key, task.id) {
            CoalesceResult::Proceed(g) => Ok(Some(g)),
            CoalesceResult::Wait(rx, leader_task_id) => {
                self.wait_for_leader(key, task, worker_id, rx, leader_task_id)
                    .await
            }
        }
    }

    /// 等待 leader 完成并处理 `Completed` / `Purged` / 超时 / 通道异常路径
    /// (自 [`Self::try_coalesce`] 提取)。
    async fn wait_for_leader(
        &self,
        key: &CoalesceKey,
        task: &Task,
        worker_id: crate::domain::id::Id,
        mut rx: tokio::sync::broadcast::Receiver<CoalesceSignal>,
        leader_task_id: crate::domain::id::Id,
    ) -> Result<Option<CoalesceGuard>> {
        info!(
            "URL {} (team {}) already in-flight (leader task {}), task {} waiting for coalesce",
            redact_url_for_log(key.url()),
            key.team_id(),
            leader_task_id,
            task.id
        );
        // 等待首个 worker(leader)完成,加 timeout 防止活锁。
        //
        // 45s 选择依据:
        // - 大于浏览器引擎 MRT(30s)+ 缓冲,留足 leader 完成时间
        // - 短于 RequestCoalescer::STALE_TIMEOUT(120s),超时后由 purge_stale
        // 兜底清理 in-flight 条目并广播 Purged
        //
        // 信号语义
        // - Completed { success: true } → 按 leader task_id 查询落库结果
        // - Completed { success: false } → leader 失败/取消,不查结果,直接重排
        // - Purged → leader 僵死被清理,不视为完成,走自身重排
        // - recv Closed / Lagged → leader 异常,不 mark_failed,走自身重排
        // - timeout → leader 仍可能在跑,不无条件 purge 全表,走自身重排
        const COALESCE_RECV_TIMEOUT_SECS: u64 = 45;

        let signal = match recv_leader_signal(&mut rx, COALESCE_RECV_TIMEOUT_SECS).await {
            LeaderSignal::Signal(sig) => sig,
            LeaderSignal::TimedOut => {
                // 超时:leader 未在窗口内完成,可能仍在跑或已 panic/死锁。
                // 超时路径不得无条件 purge 全表,也不 mark_failed
                // leader 的任务;走等待方自身重排(超上限后才 mark_failed 自身)。
                error!(
                    "Coalesce wait for task {} timed out after {}s (leader task {}); \
                                 rescheduling self instead of failing leader",
                    task.id, COALESCE_RECV_TIMEOUT_SECS, leader_task_id
                );
                return self
                    .reschedule_or_fail(task, worker_id, "coalesce wait timeout")
                    .await;
            }
            LeaderSignal::Closed => {
                // recv Closed:leader 的 sender 全部 drop 却未广播完成
                // (panic / 异常终止)。视为 leader 异常,不 mark_failed,走自身重排。
                warn!(
                    "Coalesce channel closed for task {} (leader task {} likely panicked); \
                                 rescheduling self",
                    task.id, leader_task_id
                );
                return self
                    .reschedule_or_fail(task, worker_id, "coalesce channel closed")
                    .await;
            }
            LeaderSignal::Lagged(n) => {
                // Lagged:等待方消费过慢丢失信号(容量 1 理论不应发生)。保守重排。
                warn!(
                    "Coalesce receiver for task {} lagged by {} messages; rescheduling self",
                    task.id, n
                );
                return self
                    .reschedule_or_fail(task, worker_id, "coalesce receiver lagged")
                    .await;
            }
        };

        match signal {
            CoalesceSignal::Purged => {
                // purge_stale 清理僵死条目:不视为完成,不查询结果,走自身重排。
                warn!(
                    "Coalesce entry for task {} purged as stale (leader task {}); \
                             rescheduling self without result lookup",
                    task.id, leader_task_id
                );
                self.reschedule_or_fail(task, worker_id, "coalesce entry purged")
                    .await
            }
            CoalesceSignal::Completed { success: false } => {
                // leader 失败/取消(结果未落库):不查询结果,走自身重排。
                // 这是 M2 修复点:旧实现统一按 Completed 查询,失败路径
                // 必然白烧一次 `find_by_task_id`。
                warn!(
                    "Coalesce leader task {} reported failure for waiter task {}; \
                             rescheduling self without result lookup",
                    leader_task_id, task.id
                );
                self.reschedule_or_fail(task, worker_id, "leader reported failure")
                    .await
            }
            CoalesceSignal::Completed { success: true } => {
                // leader 正常完成:按 leader task_id 查询落库结果
                // (结果落在 leader 名下,非等待方自身 task_id)。
                if self
                    .adopt_leader_result(task, leader_task_id, worker_id)
                    .await?
                {
                    Ok(None)
                } else {
                    // leader 已完成但结果尚未落库/不可见——延后重排
                    self.reschedule_or_fail(task, worker_id, "leader result not yet available")
                        .await
                }
            }
        }
    }

    /// 等待方自身重排(不 mark_failed leader 的任务);超过最大重排次数后 mark_failed 自身。
    ///
    /// 触发场景:recv 超时 / Closed / Lagged、Purged 信号、
    /// `Completed { success: false }`(leader 失败)、Completed 成功但结果尚未落库。
    /// 统一走带锁守卫的 `update_task_guarded`(重排)或 `mark_failed`(超上限),
    /// 避免裸写 status/payload 覆盖并发状态迁移。
    async fn reschedule_or_fail(
        &self,
        task: &Task,
        _worker_id: crate::domain::id::Id,
        reason: &str,
    ) -> Result<Option<CoalesceGuard>> {
        // 追踪 reschedule 次数,超过上限后 mark_failed 防止无限循环
        const MAX_COALESCE_RESCHEDULE: u32 = 3;
        let reschedule_count = task
            .payload
            .get("coalesce_reschedule_count")
            .and_then(|v| v.as_u64())
            .unwrap_or(0) as u32;

        if reschedule_count >= MAX_COALESCE_RESCHEDULE {
            error!(
                "Coalesced task {} exceeded max reschedule count ({}) after [{}], marking failed",
                task.id, MAX_COALESCE_RESCHEDULE, reason
            );
            // 失败原因同时落 payload["error"]:API 状态端点据此回显,
            // 仅日志留存会让客户端只看到通用"任务失败。"。
            self.repository
                .mark_failed_with_reason(
                    task,
                    &format!("Coalesce reschedule limit exceeded after [{reason}]"),
                )
                .await?;
            return Ok(None);
        }

        warn!(
            "Coalesced task {} rescheduling after [{}] (attempt {}/{})",
            task.id,
            reason,
            reschedule_count + 1,
            MAX_COALESCE_RESCHEDULE
        );
        let mut updated = task.clone();
        updated.scheduled_at = Some(Utc::now() + chrono::Duration::seconds(5));
        updated.status = TaskStatus::Queued;
        if !updated.payload.is_object() {
            updated.payload = json!({});
        }
        if let Some(obj) = updated.payload.as_object_mut() {
            obj.insert(
                "coalesce_reschedule_count".to_string(),
                json!(reschedule_count + 1),
            );
        }
        // 守卫式写入:锁被抢占/任务被终结时放弃重排
        self.repository.update_task_guarded(&updated).await?;
        Ok(None)
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::domain::models::{Task, TaskType};
    use crate::domain::repositories::task_repository::{RepositoryError, TaskQueryParams};
    use crate::engines::types::ScrapeOptions;
    use async_trait::async_trait;
    use serde_json::json;
    use std::collections::HashSet;
    use std::sync::atomic::{AtomicU32, Ordering};
    use std::sync::Mutex;

    // === Mock Repositories ===

    struct CountingTaskRepo {
        update_calls: AtomicU32,
        mark_completed_calls: AtomicU32,
        mark_failed_calls: AtomicU32,
        captured_updates: Mutex<Vec<Task>>,
    }

    impl CountingTaskRepo {
        fn new() -> Self {
            Self {
                update_calls: AtomicU32::new(0),
                mark_completed_calls: AtomicU32::new(0),
                mark_failed_calls: AtomicU32::new(0),
                captured_updates: Mutex::new(Vec::new()),
            }
        }
    }

    #[async_trait]
    impl TaskRepository for CountingTaskRepo {
        async fn create(&self, task: &Task) -> Result<Task, RepositoryError> {
            Ok(task.clone())
        }
        async fn find_by_id(
            &self,
            _id: crate::domain::id::Id,
        ) -> Result<Option<Task>, RepositoryError> {
            Ok(None)
        }
        async fn update(&self, task: &Task) -> Result<Task, RepositoryError> {
            self.update_calls.fetch_add(1, Ordering::SeqCst);
            self.captured_updates.lock().unwrap().push(task.clone());
            Ok(task.clone())
        }
        // 守卫式更新与 update 走同一计数/捕获(生产实现中两者互斥使用)
        async fn update_task_guarded(&self, task: &Task) -> Result<u64, RepositoryError> {
            self.update_calls.fetch_add(1, Ordering::SeqCst);
            self.captured_updates.lock().unwrap().push(task.clone());
            Ok(1)
        }
        async fn acquire_next(
            &self,
            _worker_id: crate::domain::id::Id,
        ) -> Result<Option<Task>, RepositoryError> {
            Ok(None)
        }
        async fn mark_completed(
            &self,
            _id: crate::domain::id::Id,
            _lock_token: Option<crate::domain::id::Id>,
        ) -> Result<u64, RepositoryError> {
            self.mark_completed_calls.fetch_add(1, Ordering::SeqCst);
            Ok(1)
        }
        async fn mark_failed(
            &self,
            _id: crate::domain::id::Id,
            _lock_token: Option<crate::domain::id::Id>,
        ) -> Result<u64, RepositoryError> {
            self.mark_failed_calls.fetch_add(1, Ordering::SeqCst);
            Ok(1)
        }
        async fn mark_cancelled(&self, _id: crate::domain::id::Id) -> Result<u64, RepositoryError> {
            Ok(1)
        }
        async fn exists_by_url(&self, _url: &str) -> Result<bool, RepositoryError> {
            Ok(false)
        }
        async fn find_existing_urls(
            &self,
            _urls: &[String],
        ) -> Result<HashSet<String>, RepositoryError> {
            Ok(HashSet::new())
        }
        async fn reset_stuck_tasks(
            &self,
            _timeout: chrono::Duration,
        ) -> Result<u64, RepositoryError> {
            Ok(0)
        }
        async fn cancel_tasks_by_crawl_id(
            &self,
            _crawl_id: crate::domain::id::Id,
        ) -> Result<u64, RepositoryError> {
            Ok(0)
        }
        async fn expire_tasks(&self) -> Result<u64, RepositoryError> {
            Ok(0)
        }
        async fn find_by_crawl_id(
            &self,
            _crawl_id: crate::domain::id::Id,
        ) -> Result<Vec<Task>, RepositoryError> {
            Ok(vec![])
        }
        async fn query_tasks(
            &self,
            _params: TaskQueryParams,
        ) -> Result<(Vec<Task>, u64), RepositoryError> {
            Ok((vec![], 0))
        }
        async fn batch_cancel(
            &self,
            _task_ids: Vec<crate::domain::id::Id>,
            _team_id: crate::domain::id::Id,
            _force: bool,
        ) -> Result<
            (
                Vec<crate::domain::id::Id>,
                Vec<(crate::domain::id::Id, String)>,
            ),
            RepositoryError,
        > {
            Ok((vec![], vec![]))
        }

        async fn renew_lock(
            &self,
            _task_id: crate::domain::id::Id,
            _worker_id: crate::domain::id::Id,
            _extend_seconds: i64,
        ) -> Result<bool, RepositoryError> {
            Ok(true)
        }
    }

    struct ConfigurableResultRepo {
        find_calls: AtomicU32,
        return_some: Mutex<bool>,
        /// 记录最近一次 find_by_task_id 查询的 task_id,
        /// 用于断言等待方按 leader task_id(而非自身)查询。
        last_query_task_id: Mutex<Option<crate::domain::id::Id>>,
        /// 首次查询的 task_id(复制源必须为 leader 结果)。
        first_query_task_id: Mutex<Option<crate::domain::id::Id>>,
        /// save 调用次数与最近一次落库结果的 task_id
        /// (结果须复制并改挂到等待方 task_id 名下)。
        save_calls: AtomicU32,
        last_saved_task_id: Mutex<Option<crate::domain::id::Id>>,
        /// 设定时 find_by_task_id 仅对该 task_id 返回 Some
        /// (模拟真实语义:结果只落在 leader 名下)。
        some_only_for: Mutex<Option<crate::domain::id::Id>>,
    }

    impl ConfigurableResultRepo {
        fn new(return_some: bool) -> Self {
            Self {
                find_calls: AtomicU32::new(0),
                return_some: Mutex::new(return_some),
                last_query_task_id: Mutex::new(None),
                first_query_task_id: Mutex::new(None),
                save_calls: AtomicU32::new(0),
                last_saved_task_id: Mutex::new(None),
                some_only_for: Mutex::new(None),
            }
        }

        /// 模拟"结果只落在 leader 名下":仅 leader 的 task_id 查询返回 Some
        fn new_with_result_only_for(leader_id: crate::domain::id::Id) -> Self {
            Self {
                find_calls: AtomicU32::new(0),
                return_some: Mutex::new(true),
                last_query_task_id: Mutex::new(None),
                first_query_task_id: Mutex::new(None),
                save_calls: AtomicU32::new(0),
                last_saved_task_id: Mutex::new(None),
                some_only_for: Mutex::new(Some(leader_id)),
            }
        }
    }

    #[async_trait]
    impl ScrapeResultRepository for ConfigurableResultRepo {
        async fn save(&self, result: crate::domain::models::ScrapeResult) -> Result<()> {
            self.save_calls.fetch_add(1, Ordering::SeqCst);
            *self.last_saved_task_id.lock().unwrap() = Some(result.task_id);
            Ok(())
        }
        async fn find_by_task_id(
            &self,
            task_id: crate::domain::id::Id,
        ) -> Result<Option<crate::domain::models::ScrapeResult>> {
            self.find_calls.fetch_add(1, Ordering::SeqCst);
            let mut first = self.first_query_task_id.lock().unwrap();
            if first.is_none() {
                *first = Some(task_id);
            }
            drop(first);
            *self.last_query_task_id.lock().unwrap() = Some(task_id);
            let hit = {
                let only_for = self.some_only_for.lock().unwrap();
                match &*only_for {
                    Some(lid) => task_id == *lid,
                    None => *self.return_some.lock().unwrap(),
                }
            };
            if hit {
                Ok(Some(crate::domain::models::ScrapeResult {
                    id: crate::domain::id::Id::generate(),
                    task_id: crate::domain::id::Id::generate(),
                    url: String::new(),
                    status_code: 200,
                    content: String::new(),
                    content_type: "text/html".to_string(),
                    headers: serde_json::json!({}),
                    meta_data: serde_json::json!({}),
                    screenshot: None,
                    response_time_ms: 0,
                    created_at: Utc::now(),
                }))
            } else {
                Ok(None)
            }
        }
        async fn find_by_task_ids(
            &self,
            _task_ids: &[crate::domain::id::Id],
        ) -> Result<Vec<crate::domain::models::ScrapeResult>> {
            Ok(vec![])
        }
        async fn get_team_avg_response_time(&self, _team_id: crate::domain::id::Id) -> Result<f64> {
            Ok(0.0)
        }

        async fn cleanup_expired(&self, _retention_days: i64) -> anyhow::Result<u64> {
            Ok(0)
        }
    }

    fn make_task() -> Task {
        Task::new(
            crate::domain::id::Id::generate(),
            TaskType::Scrape,
            crate::domain::id::Id::generate(),
            crate::domain::id::Id::generate(),
            "https://example.com".to_string(),
            json!({}),
        )
    }

    /// 测试键:取任务自带租户 + URL + 默认 `ScrapeOptions`。
    ///
    /// leader 占位与等待方必须用同一辅助函数构造键,才能命中同一 in-flight 条目。
    fn key_for(task: &Task) -> CoalesceKey {
        CoalesceKey::new(task.team_id, &task.url, &ScrapeOptions::default())
    }

    /// 模拟 leader 成功完成:标记 success 后释放 slot(广播成功信号)
    fn finish_leader_success(result: CoalesceResult) {
        match result {
            CoalesceResult::Proceed(mut guard) => {
                guard.mark_success();
                drop(guard);
            }
            CoalesceResult::Wait(..) => panic!("test leader must acquire coalesce slot"),
        }
    }

    /// 模拟 leader 失败:不标记 success,直接释放 slot(广播失败信号)
    fn finish_leader_failure(result: CoalesceResult) {
        match result {
            CoalesceResult::Proceed(guard) => drop(guard),
            CoalesceResult::Wait(..) => panic!("test leader must acquire coalesce slot"),
        }
    }

    /// Proceed 路径:首个 worker 获得执行权,返回 Some(guard)
    #[tokio::test]
    async fn try_coalesce_proceed_returns_some_guard() {
        let worker_id = crate::domain::id::Id::generate();
        let task_repo = Arc::new(CountingTaskRepo::new());
        let result_repo = Arc::new(ConfigurableResultRepo::new(false));
        let coalescer = Arc::new(RequestCoalescer::new());
        let coord =
            CoalesceCoordinator::new(task_repo.clone(), result_repo.clone(), coalescer.clone());

        let task = make_task();
        let result = coord.try_coalesce(&key_for(&task), &task, worker_id).await;
        assert!(result.is_ok(), "proceed path should succeed");
        let guard = result.unwrap();
        assert!(guard.is_some(), "first call should return Some(guard)");
        // 不应触发仓储调用
        assert_eq!(task_repo.update_calls.load(Ordering::SeqCst), 0);
        assert_eq!(task_repo.mark_completed_calls.load(Ordering::SeqCst), 0);
        assert_eq!(result_repo.find_calls.load(Ordering::SeqCst), 0);
    }

    /// Wait 路径收到广播但 result_repo 未命中:延后 5s 重排
    #[tokio::test]
    async fn try_coalesce_wait_reschedules_when_result_missing() {
        let worker_id = crate::domain::id::Id::generate();
        let task_repo = Arc::new(CountingTaskRepo::new());
        let result_repo = Arc::new(ConfigurableResultRepo::new(false)); // 未命中
        let coalescer = Arc::new(RequestCoalescer::new());
        let coord =
            CoalesceCoordinator::new(task_repo.clone(), result_repo.clone(), coalescer.clone());

        let task = make_task();
        let key = key_for(&task);

        // 占住 slot
        let first_guard = coalescer.try_start(&key, crate::domain::id::Id::generate());
        // 等待 guard 进入 Wait 路径
        let task_clone = task.clone();
        let coord_clone = coord.clone();
        let key_clone = key.clone();
        let handle = tokio::spawn(async move {
            coord_clone
                .try_coalesce(&key_clone, &task_clone, worker_id)
                .await
        });

        // 给一点时间让等待方进入 rx.recv()
        tokio::time::sleep(std::time::Duration::from_millis(50)).await;
        // 释放 guard 触发广播。leader 成功但结果尚未落库 → 等待方查询后重排。
        finish_leader_success(first_guard);

        let result = handle.await.expect("task panicked");
        assert!(result.is_ok(), "should not error");
        let guard = result.unwrap();
        assert!(guard.is_none(), "should return None (rescheduled)");

        // 验证 update 被调用(reschedule 路径),状态为 Queued
        assert_eq!(
            task_repo.update_calls.load(Ordering::SeqCst),
            1,
            "update should be called once for reschedule"
        );
        let captured = task_repo.captured_updates.lock().unwrap();
        let updated = captured.last().expect("captured update");
        assert_eq!(updated.status, TaskStatus::Queued);
        assert!(
            updated.scheduled_at.is_some(),
            "scheduled_at should be set for reschedule"
        );

        // 不应触发 mark_completed
        assert_eq!(
            task_repo.mark_completed_calls.load(Ordering::SeqCst),
            0,
            "mark_completed should not be called when result missing"
        );
    }

    /// M2:leader 失败信号 → 等待方不查询结果,直接重排
    ///
    /// `return_some=true`:若等待方误按成功路径查询会命中并 mark_completed——
    /// 用以反证失败分支确实跳过了结果查询(减少一次无效查询)。
    #[tokio::test]
    async fn try_coalesce_failed_leader_reschedules_without_result_lookup() {
        let worker_id = crate::domain::id::Id::generate();
        let task_repo = Arc::new(CountingTaskRepo::new());
        let result_repo = Arc::new(ConfigurableResultRepo::new(true));
        let coalescer = Arc::new(RequestCoalescer::new());
        let coord =
            CoalesceCoordinator::new(task_repo.clone(), result_repo.clone(), coalescer.clone());

        let task = make_task();
        let key = key_for(&task);

        let leader_guard = coalescer.try_start(&key, crate::domain::id::Id::generate());
        let task_clone = task.clone();
        let coord_clone = coord.clone();
        let key_clone = key.clone();
        let handle = tokio::spawn(async move {
            coord_clone
                .try_coalesce(&key_clone, &task_clone, worker_id)
                .await
        });

        tokio::time::sleep(std::time::Duration::from_millis(50)).await;
        // leader 失败:不标记 success → 广播 Completed { success: false }
        finish_leader_failure(leader_guard);

        let result = handle.await.expect("task panicked");
        assert!(result.is_ok());
        assert!(
            result.unwrap().is_none(),
            "failed leader should reschedule waiter (None)"
        );

        assert_eq!(
            result_repo.find_calls.load(Ordering::SeqCst),
            0,
            "failed leader must NOT trigger result lookup"
        );
        assert_eq!(
            task_repo.mark_completed_calls.load(Ordering::SeqCst),
            0,
            "failed leader must NOT mark waiter completed"
        );
        assert_eq!(
            task_repo.update_calls.load(Ordering::SeqCst),
            1,
            "failed leader should reschedule waiter via guarded update"
        );
    }

    /// Wait 路径收到广播且 result_repo 命中:mark_completed 并返回 None
    #[tokio::test]
    async fn try_coalesce_wait_completes_when_result_found() {
        let worker_id = crate::domain::id::Id::generate();
        let task_repo = Arc::new(CountingTaskRepo::new());
        let result_repo = Arc::new(ConfigurableResultRepo::new(true)); // 命中
        let coalescer = Arc::new(RequestCoalescer::new());
        let coord =
            CoalesceCoordinator::new(task_repo.clone(), result_repo.clone(), coalescer.clone());

        let task = make_task();
        let key = key_for(&task);

        // 占住 slot
        let first_guard = coalescer.try_start(&key, crate::domain::id::Id::generate());
        let task_clone = task.clone();
        let coord_clone = coord.clone();
        let key_clone = key.clone();
        let handle = tokio::spawn(async move {
            coord_clone
                .try_coalesce(&key_clone, &task_clone, worker_id)
                .await
        });

        tokio::time::sleep(std::time::Duration::from_millis(50)).await;
        finish_leader_success(first_guard);

        let result = handle.await.expect("task panicked");
        assert!(result.is_ok(), "should not error");
        let guard = result.unwrap();
        assert!(guard.is_none(), "should return None (completed)");

        // mark_completed 应被调用
        assert_eq!(
            task_repo.mark_completed_calls.load(Ordering::SeqCst),
            1,
            "mark_completed should be called when result found"
        );
        // 不应调用 update(无 reschedule)
        assert_eq!(
            task_repo.update_calls.load(Ordering::SeqCst),
            0,
            "update should not be called when result found"
        );
    }

    /// Wait 路径未触发广播时不应调用 find_by_task_id(仍在 rx.recv() 等待中)
    ///
    /// 这覆盖超时路径的前置条件:在信号到达前,等待方不会读 result_repo。
    /// 完整 45s 超时测试因耗时不实际,超时后的自身重排语义由 Closed/Purged 用例覆盖。
    #[tokio::test]
    async fn try_coalesce_wait_does_not_call_find_while_waiting() {
        let worker_id = crate::domain::id::Id::generate();
        let task_repo = Arc::new(CountingTaskRepo::new());
        let result_repo = Arc::new(ConfigurableResultRepo::new(false));
        let coalescer = Arc::new(RequestCoalescer::new());
        let coord =
            CoalesceCoordinator::new(task_repo.clone(), result_repo.clone(), coalescer.clone());

        let task = make_task();
        let key = key_for(&task);

        // 占住 slot 但不释放(模拟首个 worker 长时间处理)
        let _first_guard = coalescer.try_start(&key, crate::domain::id::Id::generate());

        let task_clone = task.clone();
        let coord_clone = coord.clone();
        let key_clone = key.clone();
        let handle = tokio::spawn(async move {
            coord_clone
                .try_coalesce(&key_clone, &task_clone, worker_id)
                .await
        });

        // 短暂等待,验证仍在等待中
        tokio::time::sleep(std::time::Duration::from_millis(100)).await;
        // find_by_task_id 不应被调用(仍在 recv 等待中)
        assert_eq!(
            result_repo.find_calls.load(Ordering::SeqCst),
            0,
            "find_by_task_id should not be called while waiting for broadcast"
        );
        // 取消避免 45s 阻塞
        handle.abort();
    }

    /// 最大重排次数路径:coalesce_reschedule_count >= 3 时 mark_failed
    #[tokio::test]
    async fn try_coalesce_max_reschedule_exceeded_marks_failed() {
        let worker_id = crate::domain::id::Id::generate();
        let task_repo = Arc::new(CountingTaskRepo::new());
        let result_repo = Arc::new(ConfigurableResultRepo::new(false));
        let coalescer = Arc::new(RequestCoalescer::new());
        let coord =
            CoalesceCoordinator::new(task_repo.clone(), result_repo.clone(), coalescer.clone());

        // 构造已达最大重排次数的任务
        let mut task = make_task();
        task.payload = json!({"coalesce_reschedule_count": 3});
        let key = key_for(&task);

        // 占住 slot
        let first_guard = coalescer.try_start(&key, crate::domain::id::Id::generate());
        let task_clone = task.clone();
        let coord_clone = coord.clone();
        let key_clone = key.clone();
        let handle = tokio::spawn(async move {
            coord_clone
                .try_coalesce(&key_clone, &task_clone, worker_id)
                .await
        });

        tokio::time::sleep(std::time::Duration::from_millis(50)).await;
        finish_leader_success(first_guard);

        let result = handle.await.expect("task panicked");
        assert!(result.is_ok());
        let guard = result.unwrap();
        assert!(
            guard.is_none(),
            "max reschedule exceeded should return None"
        );

        // 超上限路径走带锁守卫的 mark_failed_with_reason:状态迁移 + 原因落
        // payload["error"](API 回显依据),不得走裸 update 或仅 mark_failed。
        assert_eq!(
            task_repo.mark_failed_calls.load(Ordering::SeqCst),
            0,
            "仅 mark_failed 会丢失失败原因,超限路径不得使用"
        );
        assert_eq!(
            task_repo.update_calls.load(Ordering::SeqCst),
            1,
            "超限路径应恰好执行一次守卫式更新"
        );
        let captured = task_repo.captured_updates.lock().unwrap();
        let failed = captured.last().expect("应捕获失败快照");
        assert_eq!(failed.status, TaskStatus::Failed);
        let reason = failed
            .payload
            .get("error")
            .and_then(|v| v.as_str())
            .unwrap_or_default();
        assert!(
            reason.contains("reschedule limit"),
            "失败原因必须落库,实际: {reason}"
        );
    }

    /// find_by_task_id 返回 Err 时应传播错误
    #[tokio::test]
    async fn try_coalesce_wait_find_by_task_id_error_propagates() {
        let worker_id = crate::domain::id::Id::generate();
        let task_repo = Arc::new(CountingTaskRepo::new());
        let coalescer = Arc::new(RequestCoalescer::new());

        // ErrorResultRepo: find_by_task_id returns Err
        struct ErrorResultRepo;
        #[async_trait]
        impl ScrapeResultRepository for ErrorResultRepo {
            async fn save(&self, _result: crate::domain::models::ScrapeResult) -> Result<()> {
                Ok(())
            }
            async fn find_by_task_id(
                &self,
                _task_id: crate::domain::id::Id,
            ) -> Result<Option<crate::domain::models::ScrapeResult>> {
                Err(anyhow::anyhow!("db connection lost"))
            }
            async fn find_by_task_ids(
                &self,
                _task_ids: &[crate::domain::id::Id],
            ) -> Result<Vec<crate::domain::models::ScrapeResult>> {
                Ok(vec![])
            }
            async fn get_team_avg_response_time(
                &self,
                _team_id: crate::domain::id::Id,
            ) -> Result<f64> {
                Ok(0.0)
            }

            async fn cleanup_expired(&self, _retention_days: i64) -> anyhow::Result<u64> {
                Ok(0)
            }
        }

        let result_repo = Arc::new(ErrorResultRepo);
        let coord =
            CoalesceCoordinator::new(task_repo.clone(), result_repo.clone(), coalescer.clone());

        let task = make_task();
        let key = key_for(&task);

        let first_guard = coalescer.try_start(&key, crate::domain::id::Id::generate());
        let task_clone = task.clone();
        let coord_clone = coord.clone();
        let key_clone = key.clone();
        let handle = tokio::spawn(async move {
            coord_clone
                .try_coalesce(&key_clone, &task_clone, worker_id)
                .await
        });

        tokio::time::sleep(std::time::Duration::from_millis(50)).await;
        finish_leader_success(first_guard);

        let result = handle.await.expect("task panicked");
        assert!(result.is_err(), "find_by_task_id error should propagate");
    }

    /// new() 构造器验证字段正确初始化
    #[test]
    fn test_coalesce_coordinator_new() {
        let task_repo = Arc::new(CountingTaskRepo::new());
        let result_repo = Arc::new(ConfigurableResultRepo::new(false));
        let coalescer = Arc::new(RequestCoalescer::new());
        let coord =
            CoalesceCoordinator::new(task_repo.clone(), result_repo.clone(), coalescer.clone());
        // Clone should work (Arc-based)
        let _cloned = coord.clone();
    }

    /// recv Closed(leader 异常消失)→ 等待方不进入 Failed,走自身重排
    #[tokio::test]
    async fn try_coalesce_closed_channel_reschedules_not_failed() {
        let worker_id = crate::domain::id::Id::generate();
        let task_repo = Arc::new(CountingTaskRepo::new());
        // return_some=true:若等待方误走完成路径查询会命中——反证 Closed 分支不查结果
        let result_repo = Arc::new(ConfigurableResultRepo::new(true));
        let coalescer = Arc::new(RequestCoalescer::new());
        let coord =
            CoalesceCoordinator::new(task_repo.clone(), result_repo.clone(), coalescer.clone());

        let task = make_task();
        let key = key_for(&task);

        // leader 占位;_leader_guard 保活到作用域末,避免其提前 Drop 广播 Completed
        let _leader_guard = coalescer.try_start(&key, crate::domain::id::Id::generate());

        let task_clone = task.clone();
        let coord_clone = coord.clone();
        let key_clone = key.clone();
        let handle = tokio::spawn(async move {
            coord_clone
                .try_coalesce(&key_clone, &task_clone, worker_id)
                .await
        });

        // 等待方进入 recv 后,静默移除条目 → sender drop → recv 返回 Closed
        tokio::time::sleep(std::time::Duration::from_millis(50)).await;
        coalescer.drop_entry_silently(&key);

        let result = handle.await.expect("task panicked");
        assert!(result.is_ok(), "closed channel should not error");
        assert!(
            result.unwrap().is_none(),
            "closed channel should reschedule self (None)"
        );

        // 关键断言:leader 异常不 mark_failed 等待方任务,而是走自身重排
        assert_eq!(
            task_repo.mark_failed_calls.load(Ordering::SeqCst),
            0,
            "closed channel must NOT mark waiter task failed"
        );
        assert_eq!(
            task_repo.update_calls.load(Ordering::SeqCst),
            1,
            "closed channel should reschedule self via guarded update"
        );
        assert_eq!(
            result_repo.find_calls.load(Ordering::SeqCst),
            0,
            "closed channel must not query result_repo"
        );
    }

    /// Purged 信号不触发结果查询/完成路径,走自身重排
    #[tokio::test]
    async fn try_coalesce_purged_signal_skips_result_lookup() {
        let worker_id = crate::domain::id::Id::generate();
        let task_repo = Arc::new(CountingTaskRepo::new());
        // return_some=true:若等待方误按完成路径查询会命中并 mark_completed——
        // 用以反证 Purged 分支确实跳过了结果查询与完成路径。
        let result_repo = Arc::new(ConfigurableResultRepo::new(true));
        let coalescer = Arc::new(RequestCoalescer::new());
        let coord =
            CoalesceCoordinator::new(task_repo.clone(), result_repo.clone(), coalescer.clone());

        let task = make_task();
        let key = key_for(&task);

        let _leader_guard = coalescer.try_start(&key, crate::domain::id::Id::generate());

        let task_clone = task.clone();
        let coord_clone = coord.clone();
        let key_clone = key.clone();
        let handle = tokio::spawn(async move {
            coord_clone
                .try_coalesce(&key_clone, &task_clone, worker_id)
                .await
        });

        // 等待方进入 recv 后,强制 purge 该条目 → 广播 Purged
        tokio::time::sleep(std::time::Duration::from_millis(50)).await;
        coalescer.purge_key(&key);

        let result = handle.await.expect("task panicked");
        assert!(result.is_ok());
        assert!(
            result.unwrap().is_none(),
            "purged signal should reschedule self (None)"
        );

        // Purged 分支不视为完成:不查询结果、不 mark_completed、不 mark_failed
        assert_eq!(
            result_repo.find_calls.load(Ordering::SeqCst),
            0,
            "Purged must NOT trigger result lookup"
        );
        assert_eq!(
            task_repo.mark_completed_calls.load(Ordering::SeqCst),
            0,
            "Purged must NOT mark completed"
        );
        assert_eq!(
            task_repo.mark_failed_calls.load(Ordering::SeqCst),
            0,
            "Purged must NOT mark waiter failed"
        );
        assert_eq!(
            task_repo.update_calls.load(Ordering::SeqCst),
            1,
            "Purged should reschedule self via guarded update"
        );
    }

    /// Completed 后等待方按 leader task_id 查询结果(非自身 task_id)
    #[tokio::test]
    async fn try_coalesce_queries_result_by_leader_task_id() {
        let worker_id = crate::domain::id::Id::generate();
        let task_repo = Arc::new(CountingTaskRepo::new());
        // leader_id 先行:mock 需模拟"结果只落在 leader 名下"
        let leader_id = crate::domain::id::Id::generate();
        let result_repo = Arc::new(ConfigurableResultRepo::new_with_result_only_for(leader_id));
        let coalescer = Arc::new(RequestCoalescer::new());
        let coord =
            CoalesceCoordinator::new(task_repo.clone(), result_repo.clone(), coalescer.clone());

        // leader 用已知 task_id 占位;等待方 task.id 与 leader_id 不同
        let waiter_task = make_task();
        assert_ne!(
            leader_id, waiter_task.id,
            "test precondition: leader and waiter task ids differ"
        );
        let key = key_for(&waiter_task);

        let leader_guard = coalescer.try_start(&key, leader_id);

        let task_clone = waiter_task.clone();
        let coord_clone = coord.clone();
        let key_clone = key.clone();
        let handle = tokio::spawn(async move {
            coord_clone
                .try_coalesce(&key_clone, &task_clone, worker_id)
                .await
        });

        tokio::time::sleep(std::time::Duration::from_millis(50)).await;
        // leader 正常完成 → 标记 success 后释放 → 广播 Completed { success: true }
        finish_leader_success(leader_guard);

        let result = handle.await.expect("task panicked");
        assert!(result.is_ok());
        assert!(result.unwrap().is_none());

        // 关键断言 1:复制源查询使用 leader task_id,而非等待方自身 task.id
        let first_queried = *result_repo.first_query_task_id.lock().unwrap();
        assert_eq!(
            first_queried,
            Some(leader_id),
            "waiter must query copy source by leader task_id"
        );
        // 关键断言 2:leader 结果复制为等待方名下的结果后 mark_completed
        // (否则 completed 任务按自身 task_id 查结果为空——静默失败)
        assert_eq!(
            result_repo.save_calls.load(Ordering::SeqCst),
            1,
            "leader result must be copied once under the waiter task"
        );
        assert_eq!(
            *result_repo.last_saved_task_id.lock().unwrap(),
            Some(waiter_task.id),
            "copied result must be re-attributed to the waiter task_id"
        );
        assert_eq!(
            *result_repo.last_query_task_id.lock().unwrap(),
            Some(waiter_task.id),
            "copy must be idempotent-guarded by a waiter-side result lookup"
        );
        // 命中后 mark_completed 等待方自身任务
        assert_eq!(task_repo.mark_completed_calls.load(Ordering::SeqCst), 1);
    }

    // === 合并键租户 / 请求身份(M1 / M5) ===

    /// M5:worker 级——同 URL 不同 team_id 并发,两个都获得执行权
    #[tokio::test]
    async fn worker_same_url_different_team_does_not_coalesce() {
        let worker_id = crate::domain::id::Id::generate();
        let coalescer = Arc::new(RequestCoalescer::new());
        let coord = CoalesceCoordinator::new(
            Arc::new(CountingTaskRepo::new()),
            Arc::new(ConfigurableResultRepo::new(false)),
            coalescer.clone(),
        );

        let task_a = make_task();
        let mut task_b = make_task();
        task_b.team_id = crate::domain::id::Id::generate();
        task_b.url = task_a.url.clone();
        assert_ne!(task_a.team_id, task_b.team_id);

        let key_a = key_for(&task_a);
        let key_b = key_for(&task_b);
        let (result_a, result_b) = tokio::join!(
            coord.try_coalesce(&key_a, &task_a, worker_id),
            coord.try_coalesce(&key_b, &task_b, worker_id),
        );

        assert!(result_a.is_ok(), "tenant A should proceed");
        assert!(result_b.is_ok(), "tenant B should proceed");
        let (guard_a, guard_b) = (result_a.unwrap(), result_b.unwrap());
        assert!(guard_a.is_some(), "tenant A must acquire coalesce slot");
        assert!(
            guard_b.is_some(),
            "tenant B must not wait on tenant A's in-flight entry"
        );
        assert_eq!(coalescer.in_flight_count(), 2);
    }

    /// M5:worker 级——同租户同 URL 但 headers 不同并发,两个都获得执行权
    #[tokio::test]
    async fn worker_same_tenant_different_headers_do_not_coalesce() {
        let worker_id = crate::domain::id::Id::generate();
        let coalescer = Arc::new(RequestCoalescer::new());
        let coord = CoalesceCoordinator::new(
            Arc::new(CountingTaskRepo::new()),
            Arc::new(ConfigurableResultRepo::new(false)),
            coalescer.clone(),
        );

        let task = make_task();
        let mut options_a = ScrapeOptions::default();
        options_a
            .headers
            .insert("X-Trace".to_string(), "a".to_string());
        let mut options_b = ScrapeOptions::default();
        options_b
            .headers
            .insert("X-Trace".to_string(), "b".to_string());

        let key_a = CoalesceKey::new(task.team_id, &task.url, &options_a);
        let key_b = CoalesceKey::new(task.team_id, &task.url, &options_b);
        let (result_a, result_b) = tokio::join!(
            coord.try_coalesce(&key_a, &task, worker_id),
            coord.try_coalesce(&key_b, &task, worker_id),
        );

        assert!(result_a.is_ok());
        assert!(result_b.is_ok());
        let (guard_a, guard_b) = (result_a.unwrap(), result_b.unwrap());
        assert!(guard_a.is_some(), "header set A must proceed");
        assert!(
            guard_b.is_some(),
            "header set B must not coalesce with header set A"
        );
        assert_eq!(coalescer.in_flight_count(), 2);
    }

    /// M1:debug 构建下键租户与任务租户不一致立即 panic(编程错误显性化)
    #[cfg(debug_assertions)]
    #[tokio::test]
    #[should_panic(expected = "coalesce key tenant must match task tenant")]
    async fn try_coalesce_tenant_mismatch_panics_in_debug() {
        let worker_id = crate::domain::id::Id::generate();
        let coalescer = Arc::new(RequestCoalescer::new());
        let coord = CoalesceCoordinator::new(
            Arc::new(CountingTaskRepo::new()),
            Arc::new(ConfigurableResultRepo::new(false)),
            coalescer,
        );

        let task = make_task();
        let other_team = if task.team_id == crate::domain::id::Id::from_u128(0) {
            crate::domain::id::Id::from_u128(1)
        } else {
            crate::domain::id::Id::from_u128(0)
        };
        let key = CoalesceKey::new(other_team, &task.url, &ScrapeOptions::default());

        let _ = coord.try_coalesce(&key, &task, worker_id).await;
    }
}