From 2b677c6f89dcb67162abe4671a438b4ff4c2ad14 Mon Sep 17 00:00:00 2001
From: augushong <augushong@163.com>
Date: Tue, 28 Jul 2026 06:02:07 +0800
Subject: [PATCH] =?UTF-8?q?feat(nginx-log):=20NginxLogStatAggregate=20?=
 =?UTF-8?q?=E5=AE=9A=E6=97=B6=E4=BB=BB=E5=8A=A1=20+=20timer=20config=20?=
 =?UTF-8?q?=E6=B3=A8=E5=86=8C?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .../timer/NginxLogStatAggregate.php           | 20 +++++
 .../timer/NginxLogStatAggregateBase.php       | 81 +++++++++++++++++++
 2 files changed, 101 insertions(+)
 create mode 100644 app/tools/controller/timer/NginxLogStatAggregate.php
 create mode 100644 extend/base/tools/controller/timer/NginxLogStatAggregateBase.php

diff --git a/app/tools/controller/timer/NginxLogStatAggregate.php b/app/tools/controller/timer/NginxLogStatAggregate.php
new file mode 100644
index 0000000..a21f7b4
--- /dev/null
+++ b/app/tools/controller/timer/NginxLogStatAggregate.php
@@ -0,0 +1,20 @@
+<?php
+
+declare(strict_types=1);
+
+namespace app\tools\controller\timer;
+
+use base\tools\controller\timer\NginxLogStatAggregateBase;
+
+/**
+ * nginx 访问日志按小时聚合定时任务（App 入口类）.
+ *
+ * 框架路由 /tools/timer.NginxLogStatAggregate/do 与 /tools/timer.NginxLogStatAggregate/execute
+ * 均通过本类入口实例化（依赖倒置：定时器框架/路由系统直接调本类，不调 Base）。
+ *
+ * 业务侧如需定制聚合行为（如改默认窗口策略、加业务过滤、调整并发等），
+ * 重写本类对应方法即可拦截，无需改动 extend/base/。
+ */
+class NginxLogStatAggregate extends NginxLogStatAggregateBase
+{
+}
diff --git a/extend/base/tools/controller/timer/NginxLogStatAggregateBase.php b/extend/base/tools/controller/timer/NginxLogStatAggregateBase.php
new file mode 100644
index 0000000..a849722
--- /dev/null
+++ b/extend/base/tools/controller/timer/NginxLogStatAggregateBase.php
@@ -0,0 +1,81 @@
+<?php
+
+declare(strict_types=1);
+
+namespace base\tools\controller\timer;
+
+use app\common\controller\TimerController;
+use think\facade\Log;
+
+/**
+ * nginx 访问日志按小时聚合定时任务（Base 层）.
+ *
+ * 流程：
+ *   1. env 总开关校验（严格布尔判断，详见 notepad Task 2 #14）
+ *   2. 计算目标统计窗口：默认 now - 1 hour（上一完整小时）；
+ *      支持 ?date=YYYYMMDD&hour=HH 手动指定（用于补跑历史数据）
+ *   3. 依赖倒置：实例化 app 层 NginxLogAggregator，调 aggregateHour($date, $hour)
+ *   4. return JSON（含 stat_hour_rows / stat_url_rows / stat_referer_rows / stat_ua_rows）
+ *
+ * 业务侧如需定制聚合触发逻辑（如改默认窗口策略、加业务过滤），重写
+ * app/tools/controller/timer/NginxLogStatAggregate.php 对应方法即可拦截。
+ */
+class NginxLogStatAggregateBase extends TimerController
+{
+    /**
+     * 防刷间隔（秒）.
+     * 仅做控制器侧防刷，不影响定时器侧 frequency 节流。
+     * timer config frequency=3600，这里设 300 是为了允许补跑历史窗口时
+     * 连续手动触发不同 (date,hour) 不被卡。
+     */
+    protected $frequency = 300;
+
+    /**
+     * 并发上限 cap：单分片（id=0）。
+     */
+    protected $concurrency = 1;
+
+    public function do()
+    {
+        // 1. 严格布尔判断（env convert 'true'→true / 'false'→false）
+        //    见 notepad Task 2 #14：必须 !== true，不能用 !== 'true' 字符串比较
+        if (env('nginx_log.enable') !== true) {
+            Log::debug('nginx_log disabled, skip aggregate');
+            return 'disabled';
+        }
+
+        // 2. 解析目标统计窗口
+        //    默认：now - 1 hour（上一完整小时，避免正在写入的小时数据不完整）
+        //    手动：?date=YYYYMMDD&hour=HH 用于补跑历史窗口
+        $manualDate = $this->request->param('date', '');
+        $manualHour = $this->request->param('hour', '');
+
+        if ($manualDate !== '' && $manualHour !== '') {
+            // 手动模式：强校验
+            $dateInt = (int) $manualDate;
+            $hourInt = (int) $manualHour;
+            // YYYYMMDD 范围：10000101 ~ 99991231；hour: 0-23
+            if ($dateInt < 10000101 || $dateInt > 99991231) {
+                return json_encode(['error' => 'invalid date format, expect YYYYMMDD'], JSON_UNESCAPED_UNICODE);
+            }
+            if ($hourInt < 0 || $hourInt > 23) {
+                return json_encode(['error' => 'invalid hour, expect 0-23'], JSON_UNESCAPED_UNICODE);
+            }
+        } else {
+            // 默认模式：取当前时间 - 1 小时（按服务器时区，框架 default_timezone=Asia/Shanghai）
+            $ts = time() - 3600;
+            $dateInt = (int) date('Ymd', $ts);
+            $hourInt = (int) date('G', $ts);
+        }
+
+        // 3. 依赖倒置：调用 app 层入口类（业务侧可重写拦截）
+        $aggregator = new \app\common\service\NginxLogAggregator();
+        $result = $aggregator->aggregateHour($dateInt, $hourInt);
+
+        // 4. return JSON（补充窗口信息便于日志检索）
+        return json_encode(array_merge([
+            'stat_date' => $dateInt,
+            'stat_hour' => $hourInt,
+        ], $result), JSON_UNESCAPED_UNICODE);
+    }
+}