From f1a2e8fd5da24bf6d9bf3fecfe2b89d592967ffa Mon Sep 17 00:00:00 2001
From: augushong <augushong@163.com>
Date: Tue, 28 Jul 2026 06:57:13 +0800
Subject: [PATCH] =?UTF-8?q?fix(nginx-log):=20service=20=E6=96=87=E4=BB=B6?=
 =?UTF-8?q?=E5=8A=A0=20Service=20=E5=90=8E=E7=BC=80=EF=BC=88=E5=91=BD?=
 =?UTF-8?q?=E5=90=8D=E8=A7=84=E8=8C=83=E5=90=88=E8=A7=84=EF=BC=89?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

F2 Code quality review 发现：3 个新增 service 未遵守
.agents/rules/ulthon-naming-convention.md 第 19 行规定
（service 模块文件名需带 Service 后缀）。

变更：
- 重命名 6 个文件（3 Base + 3 App）：
  NginxLogParser(Base)→NginxLogParserService(Base)
  NginxLogReader(Base)→NginxLogReaderService(Base)
  NginxLogAggregator(Base)→NginxLogAggregatorService(Base)
- 同步类名、use、类型 hint、new 引用
- NginxLogReaderServiceBase 异常消息前缀同步加 Service
- controller Base 引用更新（NginxLogImportBase / NginxLogStatAggregateBase）

验证：
- php -l 全部 8 个文件语法通过
- grep 残留旧名 = 0 结果（24 处引用全部带 Service 后缀）
---
 ...gator.php => NginxLogAggregatorService.php} |  4 ++--
 app/common/service/NginxLogParser.php          | 14 --------------
 app/common/service/NginxLogParserService.php   | 14 ++++++++++++++
 app/common/service/NginxLogReader.php          | 18 ------------------
 app/common/service/NginxLogReaderService.php   | 18 ++++++++++++++++++
 ...e.php => NginxLogAggregatorServiceBase.php} |  2 +-
 ...rBase.php => NginxLogParserServiceBase.php} |  4 ++--
 ...rBase.php => NginxLogReaderServiceBase.php} | 10 +++++-----
 .../controller/timer/NginxLogImportBase.php    | 10 +++++-----
 .../timer/NginxLogStatAggregateBase.php        |  4 ++--
 10 files changed, 49 insertions(+), 49 deletions(-)
 rename app/common/service/{NginxLogAggregator.php => NginxLogAggregatorService.php} (70%)
 delete mode 100644 app/common/service/NginxLogParser.php
 create mode 100644 app/common/service/NginxLogParserService.php
 delete mode 100644 app/common/service/NginxLogReader.php
 create mode 100644 app/common/service/NginxLogReaderService.php
 rename extend/base/common/service/{NginxLogAggregatorBase.php => NginxLogAggregatorServiceBase.php} (99%)
 rename extend/base/common/service/{NginxLogParserBase.php => NginxLogParserServiceBase.php} (98%)
 rename extend/base/common/service/{NginxLogReaderBase.php => NginxLogReaderServiceBase.php} (95%)

diff --git a/app/common/service/NginxLogAggregator.php b/app/common/service/NginxLogAggregatorService.php
similarity index 70%
rename from app/common/service/NginxLogAggregator.php
rename to app/common/service/NginxLogAggregatorService.php
index 2243698..22abbc7 100644
--- a/app/common/service/NginxLogAggregator.php
+++ b/app/common/service/NginxLogAggregatorService.php
@@ -2,7 +2,7 @@
 
 namespace app\common\service;
 
-use base\common\service\NginxLogAggregatorBase;
+use base\common\service\NginxLogAggregatorServiceBase;
 
 /**
  * Nginx 访问日志聚合统计 Service（业务入口）.
@@ -10,6 +10,6 @@ use base\common\service\NginxLogAggregatorBase;
  * 继承自 Base 内核，业务侧可在本类中重写 aggregateHour / formatDateStr 等方法
  * 来定制聚合逻辑（依赖倒置：Base 层只调用 app 入口类）。
  */
-class NginxLogAggregator extends NginxLogAggregatorBase
+class NginxLogAggregatorService extends NginxLogAggregatorServiceBase
 {
 }
diff --git a/app/common/service/NginxLogParser.php b/app/common/service/NginxLogParser.php
deleted file mode 100644
index b70ba07..0000000
--- a/app/common/service/NginxLogParser.php
+++ /dev/null
@@ -1,14 +0,0 @@
-<?php
-
-namespace app\common\service;
-
-use base\common\service\NginxLogParserBase;
-
-/**
- * Nginx access log 解析器（App 入口类）.
- *
- * 业务侧可在此覆盖 NginxLogParserBase 的方法实现定制逻辑.
- */
-class NginxLogParser extends NginxLogParserBase
-{
-}
diff --git a/app/common/service/NginxLogParserService.php b/app/common/service/NginxLogParserService.php
new file mode 100644
index 0000000..f7b4211
--- /dev/null
+++ b/app/common/service/NginxLogParserService.php
@@ -0,0 +1,14 @@
+<?php
+
+namespace app\common\service;
+
+use base\common\service\NginxLogParserServiceBase;
+
+/**
+ * Nginx access log 解析器（App 入口类）.
+ *
+ * 业务侧可在此覆盖 NginxLogParserServiceBase 的方法实现定制逻辑.
+ */
+class NginxLogParserService extends NginxLogParserServiceBase
+{
+}
diff --git a/app/common/service/NginxLogReader.php b/app/common/service/NginxLogReader.php
deleted file mode 100644
index 440a1b5..0000000
--- a/app/common/service/NginxLogReader.php
+++ /dev/null
@@ -1,18 +0,0 @@
-<?php
-
-namespace app\common\service;
-
-use base\common\service\NginxLogReaderBase;
-
-/**
- * Nginx 日志增量读取 service（App 入口类）.
- *
- * 框架内部所有调用走本类（依赖倒置）：
- *   `new \app\common\service\NginxLogReader()` 或静态上下文，
- * 业务侧如需定制读取逻辑，重写本类对应方法即可拦截。
- *
- * 全部逻辑由 NginxLogReaderBase 提供，本类默认仅继承不修改。
- */
-class NginxLogReader extends NginxLogReaderBase
-{
-}
diff --git a/app/common/service/NginxLogReaderService.php b/app/common/service/NginxLogReaderService.php
new file mode 100644
index 0000000..2c292a0
--- /dev/null
+++ b/app/common/service/NginxLogReaderService.php
@@ -0,0 +1,18 @@
+<?php
+
+namespace app\common\service;
+
+use base\common\service\NginxLogReaderServiceBase;
+
+/**
+ * Nginx 日志增量读取 service（App 入口类）.
+ *
+ * 框架内部所有调用走本类（依赖倒置）：
+ *   `new \app\common\service\NginxLogReaderService()` 或静态上下文，
+ * 业务侧如需定制读取逻辑，重写本类对应方法即可拦截。
+ *
+ * 全部逻辑由 NginxLogReaderServiceBase 提供，本类默认仅继承不修改。
+ */
+class NginxLogReaderService extends NginxLogReaderServiceBase
+{
+}
diff --git a/extend/base/common/service/NginxLogAggregatorBase.php b/extend/base/common/service/NginxLogAggregatorServiceBase.php
similarity index 99%
rename from extend/base/common/service/NginxLogAggregatorBase.php
rename to extend/base/common/service/NginxLogAggregatorServiceBase.php
index b996db2..82d2ad3 100644
--- a/extend/base/common/service/NginxLogAggregatorBase.php
+++ b/extend/base/common/service/NginxLogAggregatorServiceBase.php
@@ -19,7 +19,7 @@ use think\facade\Db;
  * - 依赖倒置：内部 use app 入口 model（NginxStatHour 等），不 use Base model
  * - 只读 raw 表（ul_nginx_access_log），不做 nginx log line 解析（那是 T5 Parser 的事）
  */
-class NginxLogAggregatorBase
+class NginxLogAggregatorServiceBase
 {
     /**
      * 聚合指定日期的指定小时.
diff --git a/extend/base/common/service/NginxLogParserBase.php b/extend/base/common/service/NginxLogParserServiceBase.php
similarity index 98%
rename from extend/base/common/service/NginxLogParserBase.php
rename to extend/base/common/service/NginxLogParserServiceBase.php
index 23afbc5..9b3302c 100644
--- a/extend/base/common/service/NginxLogParserBase.php
+++ b/extend/base/common/service/NginxLogParserServiceBase.php
@@ -13,9 +13,9 @@ use DateTime;
  * 示例行：
  *   192.168.32.1 - - [27/Jul/2026:16:20:15 +0000] "GET / HTTP/1.1" 499 0 "-" "Mozilla/5.0 (...)" 5.085 5.086 0
  *
- * 业务侧通过 app/common/service/NginxLogParser 覆盖本类方法.
+ * 业务侧通过 app/common/service/NginxLogParserService 覆盖本类方法.
  */
-class NginxLogParserBase
+class NginxLogParserServiceBase
 {
     /** 爬虫 UA 关键词（大小写不敏感匹配） */
     public const SPIDER_KEYWORDS = [
diff --git a/extend/base/common/service/NginxLogReaderBase.php b/extend/base/common/service/NginxLogReaderServiceBase.php
similarity index 95%
rename from extend/base/common/service/NginxLogReaderBase.php
rename to extend/base/common/service/NginxLogReaderServiceBase.php
index c095246..aa76970 100644
--- a/extend/base/common/service/NginxLogReaderBase.php
+++ b/extend/base/common/service/NginxLogReaderServiceBase.php
@@ -17,7 +17,7 @@ use app\admin\model\NginxLogPosition;
  * 依赖倒置：内部 model 调用走 `app\admin\model\NginxLogPosition`（App 入口类），
  * 使用者可在 app/ 重写该 model 拦截行为；本类不直接 `new NginxLogPosition`（静态调用满足多态）。
  */
-class NginxLogReaderBase
+class NginxLogReaderServiceBase
 {
     /** 单次 fread 的 buffer 大小（64KB） */
     protected const BUFFER_SIZE = 65536;
@@ -49,7 +49,7 @@ class NginxLogReaderBase
     {
         $fp = @fopen($filePath, 'rb');
         if ($fp === false) {
-            throw new \RuntimeException("NginxLogReader: 无法打开文件 {$filePath}");
+            throw new \RuntimeException("NginxLogReaderService: 无法打开文件 {$filePath}");
         }
 
         try {
@@ -57,7 +57,7 @@ class NginxLogReaderBase
             clearstatcache(true, $filePath);
             $stat = fstat($fp);
             if ($stat === false) {
-                throw new \RuntimeException("NginxLogReader: fstat 失败 {$filePath}");
+                throw new \RuntimeException("NginxLogReaderService: fstat 失败 {$filePath}");
             }
             $currentInode = (int) $stat['ino'];
             $currentSize  = (int) $stat['size'];
@@ -81,7 +81,7 @@ class NginxLogReaderBase
 
             // 步骤 4：fseek 到 offset
             if ($offset > 0 && fseek($fp, $offset) !== 0) {
-                throw new \RuntimeException("NginxLogReader: fseek 失败 offset={$offset} file={$filePath}");
+                throw new \RuntimeException("NginxLogReaderService: fseek 失败 offset={$offset} file={$filePath}");
             }
 
             $yielded       = 0;
@@ -95,7 +95,7 @@ class NginxLogReaderBase
                 $chunk = fread($fp, self::BUFFER_SIZE);
                 if ($chunk === false) {
                     // 读错误：交上层处理，不保存进度（下次重读）
-                    throw new \RuntimeException("NginxLogReader: fread 失败 file={$filePath}");
+                    throw new \RuntimeException("NginxLogReaderService: fread 失败 file={$filePath}");
                 }
                 if ($chunk === '') {
                     // EOF
diff --git a/extend/base/tools/controller/timer/NginxLogImportBase.php b/extend/base/tools/controller/timer/NginxLogImportBase.php
index 60ce301..1ad764e 100644
--- a/extend/base/tools/controller/timer/NginxLogImportBase.php
+++ b/extend/base/tools/controller/timer/NginxLogImportBase.php
@@ -67,8 +67,8 @@ class NginxLogImportBase extends TimerController
         }
 
         // 3. 依赖倒置：使用 app 层入口类（业务侧可重写拦截）
-        $parser = new \app\common\service\NginxLogParser();
-        $reader = new \app\common\service\NginxLogReader();
+        $parser = new \app\common\service\NginxLogParserService();
+        $reader = new \app\common\service\NginxLogReaderService();
 
         // 静态资源过滤开关
         $excludeStatic = (int) sysconfig('nginx_log', 'exclude_static', 1) === 1;
@@ -119,8 +119,8 @@ class NginxLogImportBase extends TimerController
      * @return array{lines:int,fails:int}
      */
     protected function processFile(
-        \app\common\service\NginxLogParser $parser,
-        \app\common\service\NginxLogReader $reader,
+        \app\common\service\NginxLogParserService $parser,
+        \app\common\service\NginxLogReaderService $reader,
         string $file,
         bool $excludeStatic
     ): array {
@@ -233,7 +233,7 @@ class NginxLogImportBase extends TimerController
      * 这里取当前 position 后用相同 offset 重写，仅更新 failCount / failSamples。
      */
     protected function updateFailStats(
-        \app\common\service\NginxLogReader $reader,
+        \app\common\service\NginxLogReaderService $reader,
         string $file,
         int $fails,
         array $samples
diff --git a/extend/base/tools/controller/timer/NginxLogStatAggregateBase.php b/extend/base/tools/controller/timer/NginxLogStatAggregateBase.php
index a849722..8058c6a 100644
--- a/extend/base/tools/controller/timer/NginxLogStatAggregateBase.php
+++ b/extend/base/tools/controller/timer/NginxLogStatAggregateBase.php
@@ -14,7 +14,7 @@ use think\facade\Log;
  *   1. env 总开关校验（严格布尔判断，详见 notepad Task 2 #14）
  *   2. 计算目标统计窗口：默认 now - 1 hour（上一完整小时）；
  *      支持 ?date=YYYYMMDD&hour=HH 手动指定（用于补跑历史数据）
- *   3. 依赖倒置：实例化 app 层 NginxLogAggregator，调 aggregateHour($date, $hour)
+     *   3. 依赖倒置：实例化 app 层 NginxLogAggregatorService，调 aggregateHour($date, $hour)
  *   4. return JSON（含 stat_hour_rows / stat_url_rows / stat_referer_rows / stat_ua_rows）
  *
  * 业务侧如需定制聚合触发逻辑（如改默认窗口策略、加业务过滤），重写
@@ -69,7 +69,7 @@ class NginxLogStatAggregateBase extends TimerController
         }
 
         // 3. 依赖倒置：调用 app 层入口类（业务侧可重写拦截）
-        $aggregator = new \app\common\service\NginxLogAggregator();
+        $aggregator = new \app\common\service\NginxLogAggregatorService();
         $result = $aggregator->aggregateHour($dateInt, $hourInt);
 
         // 4. return JSON（补充窗口信息便于日志检索）