wordval-web 1.0.13

Wordval web layer: router, middleware, extractors, responses, session-based authentication
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
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
//! 批量审计写入器:高并发操作审计的落盘管道。
//!
//! 设计契约(框架组件,与 `middleware/request_log.rs` 的纯 tracing 访问日志互补):
//!
//! - **有界队列**:内部 mpsc 通道容量固定,远端落盘再慢也不会内存膨胀
//! - **满即丢弃 + 计数**:队列满时新记录直接丢弃(审计允许采样降级),
//!   `dropped()` 计数 + 采样告警(首条立即、此后每 1024 条一次)防止日志刷屏;
//!   配置 [`OverflowFile`](`middleware.audit.on_overflow = "file"`)时改为转入
//!   溢出文件,`overflowed()` 计数,溢出文件超出容量上限后回退为丢弃计数
//! - **攒批落盘**:按 `max_batch` 条数或 `flush_interval` 间隔二者先到者攒批,
//!   交给 [`AuditSink`] 实现方批量写入(DB/文件/远端)
//! - **Close 排空语义**:[`AuditWriter::shutdown`] 丢弃发送端后,flush 任务
//!   会把通道与缓冲中的存量记录全部写完再退出,正常关闭零丢失
//! - **at-most-once**:sink 写入失败按丢弃处理(计数 `flush_errors`),
//!   不重试不阻塞调用方——审计管道永远不能拖慢业务请求路径
//!
//! ## 快速开始
//!
//! 常态下业务代码不碰本模块:开启审计层即可,命中路由的请求由框架自动留痕。
//!
//! **1. 声明审计目标**——三选一(可混用,规则冲突时宏优先、更具体的路径优先):
//!
//! ```ignore
//! // 路由宏(推荐:动作名与路由同一行,路径不用抄第二遍)
//! #[wordval::delete("/api/orders/{id}", audit = "order.delete")]
//! async fn delete_order(Path(id): Path<i64>) -> Res<()> { ... }
//! ```
//!
//! ```toml
//! # 或配置文件:middleware.audit.routes 逐条声明
//! [middleware.audit]
//! enabled = true
//! sink = "jsonl"          # 或 "db"(写入 audit_log 表)
//! routes = [{ method = "POST", path = "/api/orders", action = "order.create" }]
//! ```
//!
//! 自动记录已带齐 action / method / resource / status / result / user / tenant /
//! ip / user_agent / request_id / elapsed_ms,结论由状态码推导(401·403·429 → denied,
//! 其余 4xx/5xx → error),无需业务侧配合。
//!
//! **2. 业务自建记录**——只在"审计内容比访问更多信息"时写一行:
//!
//! ```ignore
//! use wordval_web::audit::{AuditRecord, AuditResult};
//! use wordval_web::audit_write;
//!
//! audit_write(
//!     AuditRecord::from_ctx(&ctx, "order.refund", "/api/orders/1", AuditResult::Success)
//!         .with_extra(serde_json::json!({ "amount": 39.9 })),
//! );
//! ```
//!
//! **3. 自定义落盘后端**——实现 [`AuditSink`] 后注入,覆盖内置 sink:
//!
//! ```ignore
//! use std::sync::Arc;
//! use wordval_web::audit::{AuditConfig, AuditWriter};
//!
//! struct KafkaSink; // 实现 AuditSink
//!
//! # async fn demo() -> wordval_core::Result<()> {
//! let writer = AuditWriter::new(Arc::new(KafkaSink), AuditConfig::default())?;
//! // App::new()?.audit_writer(writer).scan().start().await
//! # Ok(())
//! # }
//! ```
//!
//! 优雅关停由 `App` 自动完成(`middleware.audit.shutdown_timeout_secs`,默认 3 秒排空),
//! 自建写入器不需要再手动调用 `shutdown`。

use async_trait::async_trait;
use parking_lot::Mutex;
use std::sync::atomic::{AtomicU64, Ordering};
use std::sync::Arc;
use std::time::Duration;
use tokio::sync::mpsc;
use tokio::task::JoinHandle;
use tokio::time::MissedTickBehavior;
use wordval_core::{Error, Result};

/// 审计记录结果分类
#[derive(Debug, Clone, Copy, PartialEq, Eq, serde::Serialize)]
#[serde(rename_all = "snake_case")]
pub enum AuditResult {
    /// 操作成功
    Success,
    /// 被拒绝(权限/限流/校验)
    Denied,
    /// 执行出错
    Error,
}

impl AuditResult {
    /// 按 HTTP 状态码推导审计结论(审计层自动记录用)
    ///
    /// - `401`/`403`/`429` → [`Denied`](Self::Denied)(认证、权限、限流拒绝);
    /// - 其余 `4xx`(400/404/422…)与 `5xx` → [`Error`](Self::Error);
    /// - `1xx`~`3xx` → [`Success`](Self::Success)。
    pub fn from_status(status: u16) -> Self {
        match status {
            401 | 403 | 429 => Self::Denied,
            s if s >= 400 => Self::Error,
            _ => Self::Success,
        }
    }
}

/// 单条审计记录
///
/// 字段用 [`new`](Self::new) + 链式 `with_*`(或 [`from_ctx`](Self::from_ctx))构造;
/// `#[non_exhaustive]` 保证后续加字段仍是向后兼容的 minor 变更。
#[derive(Debug, Clone, serde::Serialize)]
#[non_exhaustive]
pub struct AuditRecord {
    /// 事件时间(Unix 毫秒)
    pub ts_ms: i64,
    /// 操作者用户标识(匿名时为空串)
    pub user_id: String,
    /// 租户标识(单租户场景为 None)
    pub tenant: Option<String>,
    /// 操作名(如 `user.login`、`order.delete`)
    pub action: String,
    /// HTTP 方法(仅审计层自动记录时有值;`None` 表示业务侧手写记录,
    /// 动作名本身已含语义)
    pub method: Option<String>,
    /// 目标资源(如请求路径、对象 ID)
    pub resource: String,
    /// 操作结果
    pub result: AuditResult,
    /// 附加说明(如拒绝原因)
    pub detail: Option<String>,
    /// 请求 ID(与访问日志 / `x-request-id` 响应头同值,用于审计行与日志对账)
    pub request_id: Option<String>,
    /// 操作耗时(毫秒;配合 [`crate::extract::ClientContext`] 取请求入口以来的耗时)
    pub elapsed_ms: Option<u64>,
    /// 客户端 User-Agent
    pub user_agent: Option<String>,
    /// 客户端 IP(审计层从 `ClientIp` 扩展读取;与访问日志同一代理策略)
    pub ip: Option<String>,
    /// 通用扩展位(任意 JSON:订单号、变更前后快照等结构化附加数据,
    /// 不必再把 JSON 塞进 `detail` 文本再自行编解码)
    pub extra: Option<serde_json::Value>,
    /// HTTP 状态码(仅审计层自动记录时有值;业务侧手写记录一般为 None)
    pub status: Option<u16>,
}

impl AuditRecord {
    /// 创建审计记录(时间戳取当前 Unix 毫秒)
    pub fn new(action: impl Into<String>, resource: impl Into<String>, result: AuditResult) -> Self {
        Self {
            ts_ms: unix_ms(),
            user_id: String::new(),
            tenant: None,
            action: action.into(),
            method: None,
            resource: resource.into(),
            result,
            detail: None,
            request_id: None,
            elapsed_ms: None,
            user_agent: None,
            ip: None,
            extra: None,
            status: None,
        }
    }

    /// 从客户端上下文构造审计记录:自动填充 User-Agent、请求入口以来的耗时与请求 ID
    ///
    /// 配合 [`crate::extract::ClientContext`] 提取器,业务侧无需自行计时:
    ///
    /// ```ignore
    /// async fn handler(ctx: wordval_web::extract::ClientContext) {
    ///     writer.write(AuditRecord::from_ctx(&ctx, "order.delete", "/api/orders/1", AuditResult::Success));
    /// }
    /// ```
    pub fn from_ctx(
        ctx: &crate::extract::ClientContext,
        action: impl Into<String>,
        resource: impl Into<String>,
        result: AuditResult,
    ) -> Self {
        Self::new(action, resource, result)
            .with_user_agent(ctx.user_agent.clone())
            .with_ip(Some(ctx.ip.clone()))
            .with_request_id(ctx.request_id.clone())
            .with_elapsed_ms(ctx.elapsed_ms())
    }

    /// 设置操作者
    pub fn with_user(mut self, user_id: impl Into<String>) -> Self {
        self.user_id = user_id.into();
        self
    }

    /// 设置租户标识
    pub fn with_tenant(mut self, tenant: Option<String>) -> Self {
        self.tenant = tenant;
        self
    }

    /// 设置 HTTP 方法(审计层自动记录时填请求方法)
    pub fn with_method(mut self, method: impl Into<String>) -> Self {
        self.method = Some(method.into());
        self
    }

    /// 设置附加说明
    pub fn with_detail(mut self, detail: impl Into<String>) -> Self {
        self.detail = Some(detail.into());
        self
    }

    /// 设置请求 ID(与访问日志 / `x-request-id` 响应头同值)
    pub fn with_request_id(mut self, request_id: Option<String>) -> Self {
        self.request_id = request_id;
        self
    }

    /// 设置操作耗时(毫秒)
    pub fn with_elapsed_ms(mut self, elapsed_ms: u64) -> Self {
        self.elapsed_ms = Some(elapsed_ms);
        self
    }

    /// 设置客户端 User-Agent
    pub fn with_user_agent(mut self, user_agent: Option<String>) -> Self {
        self.user_agent = user_agent;
        self
    }

    /// 设置客户端 IP
    pub fn with_ip(mut self, ip: Option<String>) -> Self {
        self.ip = ip;
        self
    }

    /// 设置通用扩展数据(任意 JSON)
    pub fn with_extra(mut self, extra: serde_json::Value) -> Self {
        self.extra = Some(extra);
        self
    }

    /// 设置 HTTP 状态码
    pub fn with_status(mut self, status: u16) -> Self {
        self.status = Some(status);
        self
    }
}

/// 当前 Unix 毫秒时间戳(时钟回拨等异常时返回 0,不 panic)
fn unix_ms() -> i64 {
    std::time::SystemTime::now()
        .duration_since(std::time::UNIX_EPOCH)
        .map(|d| d.as_millis() as i64)
        .unwrap_or(0)
}

/// 审计落盘后端:实现方负责把一批记录写入存储(DB / 文件 / 远端等)。
///
/// 实现契约:应尽量快速返回(写慢会间接增大丢弃率);失败返回 `Err`,
/// 写入器按 at-most-once 丢弃该批并计数,不重试。
#[async_trait]
pub trait AuditSink: Send + Sync + 'static {
    /// 写入一批审计记录(批大小 ≤ `max_batch`)
    async fn write_batch(&self, batch: Vec<AuditRecord>) -> Result<()>;
}

// ──── 内置 sink(开箱可用,业务无需自己实现 AuditSink)────────────

/// `AuditRecord` 落库列顺序(与 [`DbAuditSink`] 的 INSERT 列名、建表 DDL 一一对应)
#[cfg(feature = "db")]
const AUDIT_COLUMNS: &[&str] = &[
    "ts_ms",
    "user_id",
    "tenant",
    "action",
    "method",
    "resource",
    "result",
    "detail",
    "request_id",
    "elapsed_ms",
    "user_agent",
    "ip",
    "extra",
    "status",
];

/// 结论的稳定字符串形式(与 serde snake_case 口径一致)
#[cfg(feature = "db")]
fn result_name(result: AuditResult) -> &'static str {
    match result {
        AuditResult::Success => "success",
        AuditResult::Denied => "denied",
        AuditResult::Error => "error",
    }
}

/// JSON Lines 文件 sink:每行一条 JSON,追加写入
///
/// 零额外依赖,适合单机/边缘部署直接 `tail` + `jq` 查。`max_bytes > 0` 时按大小
/// 滚动:超限先把当前文件改名为 `<path>.<unix_ms>` 归档,再开新文件——归档不删除,
/// 审计历史全部保留。
///
/// 每批 `flush` 但不 `fsync`(落盘依赖 OS 页缓存):进程崩溃可能丢最后几批,
/// 需要强持久性请用 [`DbAuditSink`] 或自行实现 sink。本 sink 假定单进程内使用。
pub struct JsonlAuditSink {
    path: std::path::PathBuf,
    max_bytes: u64,
    dir_ready: std::sync::atomic::AtomicBool,
}

impl JsonlAuditSink {
    pub fn new(path: impl Into<std::path::PathBuf>, max_bytes: u64) -> Self {
        Self {
            path: path.into(),
            max_bytes,
            dir_ready: std::sync::atomic::AtomicBool::new(false),
        }
    }

    /// 目标文件路径
    pub fn path(&self) -> &std::path::Path {
        &self.path
    }
}

#[async_trait]
impl AuditSink for JsonlAuditSink {
    async fn write_batch(&self, batch: Vec<AuditRecord>) -> Result<()> {
        use std::sync::atomic::Ordering::Relaxed;
        use tokio::io::AsyncWriteExt;

        if batch.is_empty() {
            return Ok(());
        }
        // 目录只需建一次(首次写入时)
        if !self.dir_ready.load(Relaxed) {
            if let Some(parent) = self.path.parent() {
                if !parent.as_os_str().is_empty() {
                    tokio::fs::create_dir_all(parent).await.map_err(|e| {
                        Error::Server(format!("审计目录创建失败 {}: {e}", parent.display()))
                    })?;
                }
            }
            self.dir_ready.store(true, Relaxed);
        }
        // 超限先滚动归档
        if self.max_bytes > 0 {
            let size = tokio::fs::metadata(&self.path)
                .await
                .map(|m| m.len())
                .unwrap_or(0);
            if size >= self.max_bytes {
                let rotated = format!("{}.{}", self.path.display(), unix_ms());
                match tokio::fs::rename(&self.path, &rotated).await {
                    Ok(()) => tracing::info!("审计文件已滚动归档: {rotated}"),
                    // 文件恰好在检查后被移走:继续追加即可(新文件会自动创建)
                    Err(e) if e.kind() == std::io::ErrorKind::NotFound => {}
                    Err(e) => {
                        return Err(Error::Server(format!(
                            "审计文件滚动失败 {}: {e}",
                            self.path.display()
                        )))
                    }
                }
            }
        }

        let mut payload = String::with_capacity(128 * batch.len());
        for record in &batch {
            payload.push_str(&serde_json::to_string(record).map_err(|e| {
                Error::Server(format!("审计记录序列化失败: {e}"))
            })?);
            payload.push('\n');
        }
        let mut file = tokio::fs::OpenOptions::new()
            .create(true)
            .append(true)
            .open(&self.path)
            .await
            .map_err(|e| {
                Error::Server(format!("审计文件打开失败 {}: {e}", self.path.display()))
            })?;
        file.write_all(payload.as_bytes())
            .await
            .map_err(|e| {
                Error::Server(format!("审计文件写入失败 {}: {e}", self.path.display()))
            })?;
        file.flush().await.map_err(|e| {
            Error::Server(format!("审计文件刷盘失败 {}: {e}", self.path.display()))
        })
    }
}

/// 表名合法性校验(表名来自配置且要拼进 SQL,必须严格白名单)
#[cfg(feature = "db")]
fn validate_audit_table(table: &str) -> Result<()> {
    let ok = !table.is_empty()
        && table.len() <= 64
        && table.starts_with(|c: char| c.is_ascii_alphabetic() || c == '_')
        && table.chars().all(|c| c.is_ascii_alphanumeric() || c == '_');
    if ok {
        Ok(())
    } else {
        Err(Error::Config(format!(
            "audit table 名称非法: '{table}'(仅允许字母/数字/下划线,且不能以数字开头)"
        )))
    }
}

/// 数据库 sink:批量 `INSERT ... VALUES (...),(...)` 落表
///
/// 表结构由 [`ensure_table`](DbAuditSink::ensure_table) 建立(三方言通用,
/// `CREATE TABLE IF NOT EXISTS`),`extra` 列在 PG 用 `jsonb`、MySQL 用 `JSON`、
/// SQLite 用 `TEXT`。表名只允许 `[A-Za-z_][A-Za-z0-9_]*`(要拼进 SQL,严格白名单)。
#[cfg(feature = "db")]
pub struct DbAuditSink {
    db: wordval_db::Db,
    table: String,
}

#[cfg(feature = "db")]
impl DbAuditSink {
    pub fn new(db: wordval_db::Db, table: impl Into<String>) -> Result<Self> {
        let table = table.into();
        validate_audit_table(&table)?;
        Ok(Self { db, table })
    }

    /// 表名
    pub fn table(&self) -> &str {
        &self.table
    }

    /// 建表(幂等:`IF NOT EXISTS`)
    pub async fn ensure_table(&self) -> Result<()> {
        let sql = match self.db.dialect() {
            wordval_db::Dialect::Postgres => format!(
                "CREATE TABLE IF NOT EXISTS {} (ts_ms BIGINT NOT NULL, user_id TEXT NOT NULL, \
                 tenant TEXT, action TEXT NOT NULL, method TEXT, resource TEXT NOT NULL, \
                 result TEXT NOT NULL, detail TEXT, request_id TEXT, elapsed_ms BIGINT, \
                 user_agent TEXT, ip TEXT, extra jsonb, status INT)",
                self.table
            ),
            wordval_db::Dialect::Mysql => format!(
                "CREATE TABLE IF NOT EXISTS {} (ts_ms BIGINT NOT NULL, user_id VARCHAR(255) NOT NULL, \
                 tenant VARCHAR(255), action VARCHAR(255) NOT NULL, method VARCHAR(16), \
                 resource VARCHAR(512) NOT NULL, result VARCHAR(16) NOT NULL, detail TEXT, \
                 request_id VARCHAR(128), elapsed_ms BIGINT, user_agent VARCHAR(1024), \
                 ip VARCHAR(64), extra JSON, status INT)",
                self.table
            ),
            wordval_db::Dialect::Sqlite => format!(
                "CREATE TABLE IF NOT EXISTS {} (ts_ms INTEGER NOT NULL, user_id TEXT NOT NULL, \
                 tenant TEXT, action TEXT NOT NULL, method TEXT, resource TEXT NOT NULL, \
                 result TEXT NOT NULL, detail TEXT, request_id TEXT, elapsed_ms INTEGER, \
                 user_agent TEXT, ip TEXT, extra TEXT, status INTEGER)",
                self.table
            ),
        };
        self.db
            .execute(&sql, &[])
            .await
            .map(|_| ())
            .map_err(|e| Error::Server(format!("审计表 {} 创建失败: {e}", self.table)))
    }

    /// 单条记录 → 与 [`AUDIT_COLUMNS`] 同序的参数列表
    fn row_params(record: &AuditRecord) -> Vec<wordval_db::Param> {
        use wordval_db::Param;
        vec![
            Param::I64(record.ts_ms),
            Param::Str(record.user_id.clone()),
            record
                .tenant
                .as_ref()
                .map(|t| Param::Str(t.clone()))
                .unwrap_or(Param::Null),
            Param::Str(record.action.clone()),
            record
                .method
                .as_ref()
                .map(|m| Param::Str(m.clone()))
                .unwrap_or(Param::Null),
            Param::Str(record.resource.clone()),
            Param::Str(result_name(record.result).to_string()),
            record
                .detail
                .as_ref()
                .map(|d| Param::Str(d.clone()))
                .unwrap_or(Param::Null),
            record
                .request_id
                .as_ref()
                .map(|r| Param::Str(r.clone()))
                .unwrap_or(Param::Null),
            record
                .elapsed_ms
                .map(|e| Param::I64(e as i64))
                .unwrap_or(Param::Null),
            record
                .user_agent
                .as_ref()
                .map(|u| Param::Str(u.clone()))
                .unwrap_or(Param::Null),
            record
                .ip
                .as_ref()
                .map(|i| Param::Str(i.clone()))
                .unwrap_or(Param::Null),
            record
                .extra
                .clone()
                .map(Param::Json)
                .unwrap_or(Param::Null),
            record.status.map(|s| Param::I64(s as i64)).unwrap_or(Param::Null),
        ]
    }
}

#[cfg(feature = "db")]
#[async_trait]
impl AuditSink for DbAuditSink {
    async fn write_batch(&self, batch: Vec<AuditRecord>) -> Result<()> {
        if batch.is_empty() {
            return Ok(());
        }
        let dialect = self.db.dialect();
        let per_row = AUDIT_COLUMNS.len();
        // 绑定参数上限决定单条 SQL 能塞几行(SQLite 32766,PG/MySQL 65535)
        let rows_per_chunk = (dialect.max_bind_params() / per_row).max(1);
        for chunk in batch.chunks(rows_per_chunk) {
            let mut sql = format!(
                "INSERT INTO {} ({}) VALUES ",
                self.table,
                AUDIT_COLUMNS.join(", ")
            );
            let mut params = Vec::with_capacity(chunk.len() * per_row);
            let mut n = 1usize;
            for (i, record) in chunk.iter().enumerate() {
                if i > 0 {
                    sql.push_str(", ");
                }
                sql.push('(');
                let row = Self::row_params(record);
                for (j, p) in row.iter().enumerate() {
                    if j > 0 {
                        sql.push_str(", ");
                    }
                    sql.push_str(&dialect.placeholder_param(n, p));
                    n += 1;
                }
                sql.push(')');
                params.extend(row);
            }
            self.db
                .execute(&sql, params)
                .await
                .map_err(|e| Error::Server(format!("审计落库失败 {}: {e}", self.table)))?;
        }
        Ok(())
    }
}

/// 溢出兜底文件:主队列满(或写入器已关停)时,把记录直接追加到独立文件。
///
/// 这是审计管道的**降级通道**,不是第二条正常路径:只在主队列 `try_send` 失败时
/// 走这里,因此常态请求路径不受任何影响。为避免降级把磁盘写爆,`max_bytes > 0`
/// 时溢出文件是**硬上限**——超限后不再写入,只继续按丢弃计数(宁可丢数据也不占满
/// 磁盘)。每次写一条做一次 `write(2)`(O_APPEND、无用户态缓冲、不 `fsync`),
/// 无异步批处理,因为此时已经没有队列可用。
pub struct OverflowFile {
    path: std::path::PathBuf,
    max_bytes: u64,
    file: Mutex<Option<std::fs::File>>,
    bytes: AtomicU64,
    /// 容量超限后置位,避免每条记录重复 `stat`
    capped: std::sync::atomic::AtomicBool,
}

impl OverflowFile {
    pub fn new(path: impl Into<std::path::PathBuf>, max_bytes: u64) -> Self {
        Self {
            path: path.into(),
            max_bytes,
            file: Mutex::new(None),
            bytes: AtomicU64::new(0),
            capped: std::sync::atomic::AtomicBool::new(false),
        }
    }

    /// 溢出文件路径
    pub fn path(&self) -> &std::path::Path {
        &self.path
    }

    /// 追加一条记录;返回 `false` 表示未能写入(超限或 I/O 失败),调用方按丢弃计数。
    pub fn write(&self, record: &AuditRecord) -> bool {
        use std::io::Write;
        use std::sync::atomic::Ordering::Relaxed;

        if self.capped.load(Relaxed) {
            return false;
        }
        let mut payload = match serde_json::to_string(record) {
            Ok(s) => s,
            Err(e) => {
                tracing::warn!("审计溢出记录序列化失败: {e}");
                return false;
            }
        };
        payload.push('\n');

        let mut guard = self.file.lock();
        if guard.is_none() {
            if let Some(parent) = self.path.parent() {
                if !parent.as_os_str().is_empty() {
                    if let Err(e) = std::fs::create_dir_all(parent) {
                        tracing::warn!("审计溢出目录创建失败 {}: {e}", parent.display());
                        return false;
                    }
                }
            }
            match std::fs::OpenOptions::new().create(true).append(true).open(&self.path) {
                Ok(f) => {
                    // 已存在的文件计入起始体积,容量上限对累计字节负责
                    let existing = f.metadata().map(|m| m.len()).unwrap_or(0);
                    self.bytes.store(existing, Relaxed);
                    *guard = Some(f);
                }
                Err(e) => {
                    tracing::warn!("审计溢出文件打开失败 {}: {e}", self.path.display());
                    return false;
                }
            }
        }
        let file = guard.as_mut().expect("上一步刚建立的句柄");
        if self.max_bytes > 0
            && self.bytes.fetch_add(payload.len() as u64, Relaxed) + payload.len() as u64
                > self.max_bytes
        {
            self.capped.store(true, Relaxed);
            tracing::warn!(
                "审计溢出文件已达上限 {} 字节,后续溢出记录只计数不再落盘: {}",
                self.max_bytes,
                self.path.display()
            );
            return false;
        }
        match file.write_all(payload.as_bytes()) {
            Ok(()) => true,
            Err(e) => {
                tracing::warn!("审计溢出文件写入失败 {}: {e}", self.path.display());
                *guard = None; // 句柄可能已失效,下一条重新打开
                false
            }
        }
    }
}

/// 关停时排空缓冲的默认等待上限(与 `middleware.audit.shutdown_timeout_secs`
/// 的配置默认值同一口径)
pub const DEFAULT_SHUTDOWN_TIMEOUT: Duration = Duration::from_secs(3);

/// 审计写入器配置
#[derive(Debug, Clone)]
pub struct AuditConfig {
    /// 内部队列容量(有界,防内存膨胀;默认 4096)
    pub capacity: usize,
    /// 单批最大条数(攒批上限;默认 128)
    pub max_batch: usize,
    /// 最大落盘延迟(不足一批也定时刷出;默认 1s)
    pub flush_interval: Duration,
}

impl Default for AuditConfig {
    fn default() -> Self {
        Self {
            capacity: 4096,
            max_batch: 128,
            flush_interval: Duration::from_secs(1),
        }
    }
}

/// 批量审计写入器
///
/// 不可克隆(`Clone` 会产生第二个所有者,shutdown 语义变得含糊);需要共享时
/// 用 `Arc<AuditWriter>`,或直接使用框架全局的 [`audit_write`](crate::resources::audit_write)。
pub struct AuditWriter {
    /// 发送端;`None` 表示已 shutdown(Close 排空语义的入口)
    tx: Mutex<Option<mpsc::Sender<AuditRecord>>>,
    /// flush 任务句柄(shutdown 时 take 并等待排空)
    task: Mutex<Option<JoinHandle<()>>>,
    /// 已成功交付 sink 的记录数(与 flush 任务共享)
    written: Arc<AtomicU64>,
    /// 队列满/已关闭而丢弃的记录数
    dropped: AtomicU64,
    /// sink 写入失败而丢弃的记录数(与 flush 任务共享)
    flush_errors: Arc<AtomicU64>,
    /// 溢出转计数(配置了 [`OverflowFile`] 且成功落盘的部分)
    overflowed: AtomicU64,
    /// 降级通道;`None` 表示满即丢弃(默认策略)
    overflow: Option<Arc<OverflowFile>>,
}

impl AuditWriter {
    /// 创建写入器并启动后台 flush 任务(队列满即丢弃)
    ///
    /// 配置校验:`capacity`/`max_batch` 必须大于 0,`flush_interval` 不能为 0。
    pub fn new(sink: Arc<dyn AuditSink>, config: AuditConfig) -> Result<Self> {
        Self::build(sink, config, None)
    }

    /// 同 [`new`](Self::new),但队列满/关停后转入溢出文件而不是直接丢弃
    pub fn with_overflow(
        sink: Arc<dyn AuditSink>,
        config: AuditConfig,
        overflow: Arc<OverflowFile>,
    ) -> Result<Self> {
        Self::build(sink, config, Some(overflow))
    }

    fn build(
        sink: Arc<dyn AuditSink>,
        config: AuditConfig,
        overflow: Option<Arc<OverflowFile>>,
    ) -> Result<Self> {
        if config.capacity == 0 {
            return Err(Error::Config("audit capacity 必须大于 0".into()));
        }
        if config.max_batch == 0 {
            return Err(Error::Config("audit max_batch 必须大于 0".into()));
        }
        if config.flush_interval.is_zero() {
            return Err(Error::Config("audit flush_interval 不能为 0".into()));
        }
        let (tx, rx) = mpsc::channel(config.capacity);
        let written = Arc::new(AtomicU64::new(0));
        let flush_errors = Arc::new(AtomicU64::new(0));
        let task = tokio::spawn(flush_loop(
            sink,
            rx,
            config,
            Arc::clone(&written),
            Arc::clone(&flush_errors),
        ));
        Ok(Self {
            tx: Mutex::new(Some(tx)),
            task: Mutex::new(Some(task)),
            dropped: AtomicU64::new(0),
            overflowed: AtomicU64::new(0),
            overflow,
            written,
            flush_errors,
        })
    }

    /// 提交一条审计记录(非阻塞;队列满时丢弃或转溢出文件,永不拖慢调用方)
    pub fn write(&self, record: AuditRecord) {
        let guard = self.tx.lock();
        let Some(tx) = guard.as_ref() else {
            self.handle_overflow(record, "写入器已关闭");
            return;
        };
        match tx.try_send(record) {
            Ok(()) => {}
            Err(e) => {
                let (reason, record) = match e {
                    mpsc::error::TrySendError::Full(r) => ("队列已满", r),
                    mpsc::error::TrySendError::Closed(r) => ("写入器已关闭", r),
                };
                self.handle_overflow(record, reason);
            }
        }
    }

    /// 队列满/已关闭:有溢出通道则落文件,否则按丢弃计数
    fn handle_overflow(&self, record: AuditRecord, reason: &str) {
        if let Some(ovf) = &self.overflow {
            if ovf.write(&record) {
                let n = self.overflowed.fetch_add(1, Ordering::Relaxed) + 1;
                if n == 1 || n % 1024 == 0 {
                    tracing::warn!("审计写入器: {reason},转入溢出文件(累计 {n} 条)");
                }
                return;
            }
        }
        self.count_dropped(reason);
    }

    /// 批量提交审计记录
    pub fn write_all(&self, records: impl IntoIterator<Item = AuditRecord>) {
        for record in records {
            self.write(record);
        }
    }

    /// 丢弃计数 + 采样告警(首条立即,此后每 1024 条一次)
    fn count_dropped(&self, reason: &str) {
        let n = self.dropped.fetch_add(1, Ordering::Relaxed) + 1;
        if n == 1 || n % 1024 == 0 {
            tracing::warn!("审计写入器: {reason},丢弃审计记录(累计 {n} 条)");
        }
    }

    /// 已成功交付 sink 的记录数
    pub fn written(&self) -> u64 {
        self.written.load(Ordering::Relaxed)
    }

    /// 因队列满/已关闭而丢弃的记录数(配置溢出通道后,成功转入通道的部分不计入)
    pub fn dropped(&self) -> u64 {
        self.dropped.load(Ordering::Relaxed)
    }

    /// 成功转入溢出文件的记录数(未配置溢出通道时恒为 0)
    pub fn overflowed(&self) -> u64 {
        self.overflowed.load(Ordering::Relaxed)
    }

    /// sink 写入失败而丢弃的记录数
    pub fn flush_errors(&self) -> u64 {
        self.flush_errors.load(Ordering::Relaxed)
    }

    /// 关闭写入器并排空缓冲(Close 排空语义:存量记录全部写完再返回)
    ///
    /// - 关闭后继续 [`AuditWriter::write`] 会被丢弃并计数(不 panic)
    /// - 重复调用返回 `Ok(())`(幂等)
    /// - `timeout = None` 表示无限等待;超时不 abort flush 任务(避免丢
    ///   存量记录),任务继续在后台尝试完成,可再次调用等待
    pub async fn shutdown(&self, timeout: Option<Duration>) -> Result<()> {
        // 关闭入口:丢弃 sender → flush 任务的 recv() 在排空后返回 None
        let handle = {
            *self.tx.lock() = None;
            self.task.lock().take()
        };
        let Some(mut handle) = handle else {
            return Ok(()); // 已关闭
        };
        match timeout {
            None => {
                handle.await.map_err(|e| Error::Server(format!("审计 flush 任务异常退出: {e}")))
            }
            Some(d) => {
                let deadline = tokio::time::Instant::now() + d;
                match tokio::time::timeout_at(deadline, &mut handle).await {
                    Ok(Ok(())) => Ok(()),
                    Ok(Err(e)) => Err(Error::Server(format!("审计 flush 任务异常退出: {e}"))),
                    Err(_) => {
                        // 未 abort、句柄放回,允许再次 shutdown 等待排空
                        *self.task.lock() = Some(handle);
                        Err(Error::Server(
                            "审计写入器关闭超时,存量记录可能未完全落盘;flush 任务仍在后台运行,可重试".into(),
                        ))
                    }
                }
            }
        }
    }
}

/// 按 `middleware.audit` 配置装配写入器(框架启动期调用,也可宿主自行调用)
///
/// - `sink = "jsonl"` → [`JsonlAuditSink`](`path`/`max_bytes`)
/// - `sink = "db"` → [`DbAuditSink`](需要 `db` 特性与已初始化的 default 库;
///   启动时 `ensure_table` 建表,建表失败直接返回 `Err` 让启动失败,不留到运行时炸)
/// - `on_overflow = "file"` → 挂 [`OverflowFile`] 降级通道
///
/// 非法取值返回 `Err`([`validate`](wordval_config::AppConfig::validate) 已在启动
/// 前校验过一轮,这里覆盖宿主直接调用本函数的场景)。
pub async fn writer_from_config(
    cfg: &wordval_config::AuditMiddlewareConfig,
) -> Result<Arc<AuditWriter>> {
    let config = AuditConfig {
        capacity: cfg.capacity,
        max_batch: cfg.max_batch,
        flush_interval: Duration::from_secs(cfg.flush_interval_secs),
    };
    let sink: Arc<dyn AuditSink> = match cfg.sink.as_str() {
        "jsonl" => Arc::new(JsonlAuditSink::new(&cfg.path, cfg.max_bytes)),
        "db" => {
            #[cfg(feature = "db")]
            {
                let db = crate::resources::try_using(crate::resources::DEFAULT_DB_NAME).ok_or_else(
                    || Error::Config("audit.sink = \"db\" 需要先初始化数据库".into()),
                )?;
                let sink = DbAuditSink::new(db, &cfg.table)?;
                sink.ensure_table().await?;
                Arc::new(sink)
            }
            #[cfg(not(feature = "db"))]
            {
                return Err(Error::Config(
                    "audit.sink = \"db\" 需要启用 wordval-web 的 db 特性".into(),
                ));
            }
        }
        other => {
            return Err(Error::Config(format!(
                "audit.sink 无效: {other}(应为 jsonl 或 db)"
            )))
        }
    };
    let writer = match cfg.on_overflow.as_str() {
        "drop" => AuditWriter::new(sink, config)?,
        "file" => AuditWriter::with_overflow(
            sink,
            config,
            Arc::new(OverflowFile::new(&cfg.overflow_path, cfg.max_bytes)),
        )?,
        other => {
            return Err(Error::Config(format!(
                "audit.on_overflow 无效: {other}(应为 drop 或 file)"
            )))
        }
    };
    tracing::info!(
        "审计写入器已启动: sink={} 队列={} 批量={}/{}s 溢出={}",
        cfg.sink,
        cfg.capacity,
        cfg.max_batch,
        cfg.flush_interval_secs,
        cfg.on_overflow
    );
    Ok(Arc::new(writer))
}

/// flush 任务:攒批(条数或时间先到者触发)→ 交付 sink → 关闭后排空退出
async fn flush_loop(
    sink: Arc<dyn AuditSink>,
    mut rx: mpsc::Receiver<AuditRecord>,
    config: AuditConfig,
    written: Arc<AtomicU64>,
    flush_errors: Arc<AtomicU64>,
) {
    let AuditConfig { max_batch, flush_interval, .. } = config;
    let mut buf: Vec<AuditRecord> = Vec::with_capacity(max_batch);
    let mut interval = tokio::time::interval(flush_interval);
    // 落盘慢导致的错拍直接顺延,不补拍(补拍会造成连续空转 flush)
    interval.set_missed_tick_behavior(MissedTickBehavior::Delay);
    let mut err_batches: u64 = 0;

    loop {
        // 达到批上限先刷出;下方 select 每轮最多收 1 条,buf 不会超过 max_batch
        if buf.len() >= max_batch {
            flush_batch(&sink, &mut buf, &written, &flush_errors, &mut err_batches).await;
        }
        tokio::select! {
            _ = interval.tick() => {
                if !buf.is_empty() {
                    flush_batch(&sink, &mut buf, &written, &flush_errors, &mut err_batches).await;
                }
            }
            rec = rx.recv() => match rec {
                Some(rec) => buf.push(rec),
                // 所有发送端已丢弃(shutdown):通道已空,退出后排空尾部缓冲
                None => break,
            },
        }
    }
    if !buf.is_empty() {
        flush_batch(&sink, &mut buf, &written, &flush_errors, &mut err_batches).await;
    }
}

/// 交付一批给 sink;失败按 at-most-once 丢弃并采样告警
async fn flush_batch(
    sink: &Arc<dyn AuditSink>,
    buf: &mut Vec<AuditRecord>,
    written: &AtomicU64,
    flush_errors: &AtomicU64,
    err_batches: &mut u64,
) {
    let n = buf.len();
    match sink.write_batch(std::mem::take(buf)).await {
        Ok(()) => {
            written.fetch_add(n as u64, Ordering::Relaxed);
        }
        Err(e) => {
            flush_errors.fetch_add(n as u64, Ordering::Relaxed);
            *err_batches += 1;
            // 首个失败立即告警,此后每 1024 批一次
            if *err_batches == 1 || *err_batches % 1024 == 0 {
                tracing::warn!("审计写入器: sink 落盘失败,丢弃 {n} 条(累计失败批数 {}): {e}", err_batches);
            }
        }
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    /// 测试 sink:记录收到的批(可选延迟模拟慢落盘)
    struct SharedSink {
        batches: Mutex<Vec<Vec<AuditRecord>>>,
        delay: Duration,
    }

    impl SharedSink {
        fn new(delay: Duration) -> Arc<Self> {
            Arc::new(Self { batches: Mutex::new(Vec::new()), delay })
        }

        fn all_records(&self) -> Vec<AuditRecord> {
            self.batches.lock().iter().flatten().cloned().collect()
        }
    }

    #[async_trait]
    impl AuditSink for SharedSink {
        async fn write_batch(&self, batch: Vec<AuditRecord>) -> Result<()> {
            if !self.delay.is_zero() {
                tokio::time::sleep(self.delay).await;
            }
            self.batches.lock().push(batch);
            Ok(())
        }
    }

    fn record(n: usize) -> AuditRecord {
        AuditRecord::new(format!("action.{n}"), "/api/test", AuditResult::Success)
    }

    fn default_config() -> AuditConfig {
        AuditConfig { flush_interval: Duration::from_millis(30), ..AuditConfig::default() }
    }

    #[tokio::test]
    async fn test_close_drains_all_pending() {
        let sink = SharedSink::new(Duration::ZERO);
        let writer = AuditWriter::new(sink.clone(), default_config()).unwrap();
        for n in 0..50 {
            writer.write(record(n));
        }
        // 立即关闭:不足一批的存量也必须全部落盘(Close 排空语义)
        writer.shutdown(None).await.unwrap();
        assert_eq!(sink.all_records().len(), 50, "关闭后排空应零丢失");
        assert_eq!(writer.written(), 50);
        assert_eq!(writer.dropped(), 0);
    }

    #[tokio::test]
    async fn test_batch_respects_max_batch() {
        let sink = SharedSink::new(Duration::ZERO);
        let cfg = AuditConfig {
            capacity: 256,
            max_batch: 16,
            flush_interval: Duration::from_millis(30),
        };
        let writer = AuditWriter::new(sink.clone(), cfg).unwrap();
        for n in 0..64 {
            writer.write(record(n));
        }
        writer.shutdown(None).await.unwrap();
        let batches = sink.batches.lock().clone();
        assert!(batches.iter().all(|b| b.len() <= 16), "每批不得超过 max_batch");
        assert_eq!(batches.iter().map(|b| b.len()).sum::<usize>(), 64);
    }

    #[tokio::test]
    async fn test_interval_flush_without_full_batch() {
        let sink = SharedSink::new(Duration::ZERO);
        let writer = AuditWriter::new(sink.clone(), default_config()).unwrap();
        writer.write(record(1));
        writer.write(record(2));
        // 不足一批,等定时刷出。并行测试负载下调度可能远晚于 4×interval,
        // 因此轮询等待而不是固定 sleep(固定 120ms 在机器繁忙时会假失败)。
        let mut flushed = 0usize;
        for _ in 0..40 {
            tokio::time::sleep(Duration::from_millis(50)).await;
            flushed = sink.all_records().len();
            if flushed == 2 {
                break;
            }
        }
        assert_eq!(flushed, 2, "interval 到期应刷出不足一批的记录");
        writer.shutdown(None).await.unwrap();
        assert_eq!(writer.written(), 2);
    }

    #[tokio::test]
    async fn test_overflow_drops_and_counts() {
        // capacity=4:单线程 runtime 下同步 write 循环期间 flush 任务无法运行,
        // 恰好收满 capacity 后其余全部丢弃,结果完全确定
        let sink = SharedSink::new(Duration::from_millis(300));
        let cfg = AuditConfig {
            capacity: 4,
            max_batch: 8,
            flush_interval: Duration::from_millis(30),
        };
        let writer = AuditWriter::new(sink.clone(), cfg).unwrap();
        for n in 0..100 {
            writer.write(record(n));
        }
        writer.shutdown(None).await.unwrap();
        let written = writer.written();
        let dropped = writer.dropped();
        assert!((1..=8).contains(&written), "应至少写入一批,实际 {written}");
        assert!(dropped >= 90, "溢出应大量丢弃,实际 {dropped}");
        assert_eq!(written + dropped, 100, "写入+丢弃应与提交总数守恒");
        assert_eq!(sink.all_records().len() as u64, written, "落盘数应等于 written 计数");
    }

    #[tokio::test]
    async fn test_write_after_shutdown_counts_dropped() {
        let sink = SharedSink::new(Duration::ZERO);
        let writer = AuditWriter::new(sink.clone(), default_config()).unwrap();
        writer.write(record(1));
        writer.shutdown(None).await.unwrap();
        writer.write(record(2));
        writer.write(record(3));
        assert_eq!(writer.dropped(), 2, "关闭后的写入应被丢弃并计数");
        assert_eq!(sink.all_records().len(), 1);
        // 幂等:重复 shutdown 返回 Ok
        writer.shutdown(None).await.unwrap();
        writer.shutdown(Some(Duration::from_secs(1))).await.unwrap();
    }

    #[tokio::test]
    async fn test_sink_failure_counts_flush_errors() {
        struct FailingSink;
        #[async_trait]
        impl AuditSink for FailingSink {
            async fn write_batch(&self, _batch: Vec<AuditRecord>) -> Result<()> {
                Err(Error::Server("db down".into()))
            }
        }
        let writer = AuditWriter::new(Arc::new(FailingSink), default_config()).unwrap();
        for n in 0..5 {
            writer.write(record(n));
        }
        writer.shutdown(None).await.unwrap();
        assert_eq!(writer.flush_errors(), 5, "sink 失败应计入 flush_errors");
        assert_eq!(writer.written(), 0);
    }

    #[tokio::test]
    async fn test_config_validation() {
        let sink = SharedSink::new(Duration::ZERO);
        assert!(AuditWriter::new(sink.clone(), AuditConfig { capacity: 0, ..default_config() }).is_err());
        assert!(AuditWriter::new(
            sink,
            AuditConfig { max_batch: 0, flush_interval: Duration::from_secs(1), ..AuditConfig::default() }
        )
        .is_err());
    }

    #[tokio::test]
    async fn test_overflow_file_captures_dropped() {
        // 单线程 runtime + 慢 sink:write 循环不让出执行权,主通道恰好收满 capacity,
        // 其余记录全部转入溢出文件(一条不落、也不丢)
        let dir = std::env::temp_dir().join(format!("wv_audit_ovf_{}", std::process::id()));
        let path = dir.join("ovf.log");
        let _ = std::fs::remove_file(&path);
        let sink = SharedSink::new(Duration::from_millis(300));
        let cfg = AuditConfig {
            capacity: 2,
            max_batch: 8,
            flush_interval: Duration::from_millis(30),
        };
        let writer =
            AuditWriter::with_overflow(sink.clone(), cfg, Arc::new(OverflowFile::new(&path, 0)))
                .unwrap();
        for n in 0..20 {
            writer.write(record(n));
        }
        writer.shutdown(None).await.unwrap();

        assert_eq!(writer.overflowed(), 18, "溢出应等于 20 - capacity");
        assert_eq!(writer.dropped(), 0, "配置溢出通道后不该丢记录");
        let lines = std::fs::read_to_string(&path).expect("溢出文件应已写入");
        assert_eq!(lines.lines().count(), 18, "溢出文件行数应与 overflowed 一致");
        let first: serde_json::Value = serde_json::from_str(lines.lines().next().unwrap()).unwrap();
        assert_eq!(first["action"], "action.2", "前 2 条走主通道,溢出从第 3 条开始");
        // 主通道里的存量仍由 sink 正常落盘
        assert_eq!(sink.all_records().len() + 18, 20);
    }

    #[tokio::test]
    async fn test_overflow_file_capacity_cap() {
        // 上限极小:第一条溢出就超限 → 后续只按丢弃计数,绝不写爆磁盘
        let dir = std::env::temp_dir().join(format!("wv_audit_ovfcap_{}", std::process::id()));
        let path = dir.join("ovf-cap.log");
        let _ = std::fs::remove_file(&path);
        let sink = SharedSink::new(Duration::from_millis(300));
        let cfg = AuditConfig {
            capacity: 2,
            max_batch: 8,
            flush_interval: Duration::from_millis(30),
        };
        let writer = AuditWriter::with_overflow(
            sink.clone(),
            cfg,
            Arc::new(OverflowFile::new(&path, 8)),
        )
        .unwrap();
        for n in 0..20 {
            writer.write(record(n));
        }
        writer.shutdown(None).await.unwrap();
        assert_eq!(writer.overflowed(), 0, "超限后不应有记录落入溢出文件");
        assert_eq!(writer.dropped(), 18, "溢出失败回退为丢弃计数");
        assert!(!path.exists() || std::fs::metadata(&path).unwrap().len() == 0);
    }

    #[test]
    fn test_result_from_status() {
        assert_eq!(AuditResult::from_status(200), AuditResult::Success);
        assert_eq!(AuditResult::from_status(302), AuditResult::Success);
        assert_eq!(AuditResult::from_status(401), AuditResult::Denied);
        assert_eq!(AuditResult::from_status(403), AuditResult::Denied);
        assert_eq!(AuditResult::from_status(429), AuditResult::Denied);
        assert_eq!(AuditResult::from_status(400), AuditResult::Error);
        assert_eq!(AuditResult::from_status(500), AuditResult::Error);
    }

    #[test]
    fn test_record_serializes() {
        let rec = AuditRecord::new("user.login", "/api/login", AuditResult::Denied)
            .with_user("u-1")
            .with_tenant(Some("acme".into()))
            .with_detail("权限不足")
            .with_elapsed_ms(42)
            .with_user_agent(Some("Mozilla/5.0 Test".into()))
            .with_extra(serde_json::json!({ "order_id": "o-9", "retry": false }));
        let json = serde_json::to_value(&rec).unwrap();
        assert_eq!(json["action"], "user.login");
        assert_eq!(json["result"], "denied");
        assert_eq!(json["tenant"], "acme");
        assert!(json["ts_ms"].is_i64());
        assert_eq!(json["elapsed_ms"], 42);
        assert_eq!(json["user_agent"], "Mozilla/5.0 Test");
        assert_eq!(json["extra"]["order_id"], "o-9");
        // 未设置的可选字段序列化为 null(与 tenant/detail 同一口径)
        let plain = serde_json::to_value(AuditRecord::new("a", "r", AuditResult::Success)).unwrap();
        assert!(plain["request_id"].is_null());
        assert!(plain["elapsed_ms"].is_null());
        assert!(plain["user_agent"].is_null());
        assert!(plain["ip"].is_null());
        assert!(plain["method"].is_null());
        assert!(plain["extra"].is_null());
        assert!(plain["status"].is_null(), "业务侧手写记录不带状态码");
        let with_st =
            serde_json::to_value(AuditRecord::new("a", "r", AuditResult::Error).with_status(500))
                .unwrap();
        assert_eq!(with_st["status"], 500);
    }

    #[test]
    fn test_record_from_ctx_fills_ua_and_elapsed() {
        use std::time::{Duration, Instant};
        let ctx = crate::extract::ClientContext {
            ip: "1.2.3.4".into(),
            user_agent: Some("UA/1.0".into()),
            started: Instant::now() - Duration::from_millis(3),
            request_id: Some("req-abc-1".into()),
        };
        let rec = AuditRecord::from_ctx(&ctx, "order.delete", "/api/orders/1", AuditResult::Success);
        assert_eq!(rec.user_agent.as_deref(), Some("UA/1.0"));
        assert_eq!(rec.request_id.as_deref(), Some("req-abc-1"));
        assert_eq!(rec.ip.as_deref(), Some("1.2.3.4"), "from_ctx 应带客户端 IP");
        let elapsed = rec.elapsed_ms.expect("from_ctx 应填充耗时");
        // 3ms 前打点,允许调度抖动,取值应落在 [3, 1000) 内
        assert!((3..1000).contains(&elapsed), "elapsed_ms 异常: {elapsed}");
        // 其余字段不受影响
        assert_eq!(rec.action, "order.delete");
        assert_eq!(rec.result, AuditResult::Success);
        assert!(rec.extra.is_none());
    }

    /// 表名来自配置文件还要拼进 DDL/INSERT,非法名必须在装配期失败
    #[cfg(feature = "db")]
    #[test]
    fn test_audit_table_name_whitelist() {
        assert!(validate_audit_table("audit_log").is_ok());
        assert!(validate_audit_table("AuditLog2").is_ok());
        let long = "a".repeat(65);
        for bad in [
            "audit; DROP TABLE users",
            "1audit",
            "audit-log",
            "audit log",
            "\"audit\"",
            "",
            long.as_str(),
        ] {
            assert!(validate_audit_table(bad).is_err(), "应拒绝非法表名: {bad:?}");
        }
    }

    /// `middleware.audit` 装配:jsonl 正常落盘;未知 sink / 溢出策略一律报错,
    /// 不能静默降级成"审计没记上"
    #[tokio::test]
    async fn test_writer_from_config_rejects_unknown_values() {
        let dir = std::env::temp_dir().join(format!("wv_audit_cfg_{}", std::process::id()));
        let _ = std::fs::remove_dir_all(&dir);
        let overflow_path = dir.join("overflow.log");
        let mut cfg = wordval_config::AuditMiddlewareConfig {
            enabled: true,
            path: dir.join("audit.log").to_str().unwrap().to_string(),
            overflow_path: overflow_path.to_str().unwrap().to_string(),
            sink: "parquet".into(),
            ..wordval_config::AuditMiddlewareConfig::default()
        };
        assert!(writer_from_config(&cfg).await.is_err(), "未知 sink 应装配失败");
        cfg.sink = "jsonl".into();
        cfg.on_overflow = "socket".into();
        assert!(writer_from_config(&cfg).await.is_err(), "未知溢出策略应装配失败");
        assert!(
            !overflow_path.exists(),
            "装配失败不应留下半初始化的文件: {:?}",
            cfg.on_overflow
        );
        cfg.on_overflow = "file".into();
        let writer = writer_from_config(&cfg).await.expect("jsonl + 溢出文件通道应可装配");
        writer.write(record(7));
        writer.shutdown(None).await.unwrap();
        let lines = std::fs::read_to_string(&cfg.path).unwrap();
        assert_eq!(lines.lines().count(), 1);
        assert!(lines.contains("action.7"));
        let _ = std::fs::remove_dir_all(&dir);
    }
}