ok

plans/quanfuxialog-27a4a527.plan.md

@@ -0,0 +1,99 @@
+<!-- 27a4a527-c3b0-4e37-b4ed-ba7e02f51f70 -->
+---
+todos:
+  - id: "composer"
+    content: "在 composer.json 增加 vcs repository 并 docker composer require quanfuxia/log:dev-main"
+    status: pending
+  - id: "logconfig"
+    content: "改写 config/log.php 使用 SeasLogHandler + SeasLogLineFormatter + IntrospectionProcessor"
+    status: pending
+  - id: "middleware"
+    content: "新增 app/middleware/TraceId.php 调用 TraceContext::init，并在 config/middleware.php 注册全局中间件"
+    status: pending
+  - id: "verify"
+    content: "php -l 校验、请求验证日志落盘，跑收尾门禁脚本"
+    status: pending
+isProject: false
+---
+# 引入并配置 quanfuxia/log
+
+## 背景
+`quanfuxia/log`（`Quanfuxia\Log\`）是一个 Webman/Monolog → SeasLog 的日志适配库，核心组件：
+- `SeasLogHandler`：Monolog 记录写入 SeasLog，自动 `SeasLog::setRequestID(traceId)`，BasePath 设为 `runtime_path()/logs`
+- `SeasLogLineFormatter`：日志行格式化
+- `Trace\TraceContext`：基于 `Webman\Context` 的 `trace_id` / `request_time` 上下文
+
+环境已确认：`php82` 容器存在 `SeasLog` 扩展，PHP 8.2.24；库要求 `php>=8.2`、`monolog ^2.0`（项目已具备）。仓库仅有 `main` 分支、无 tag，故按 `dev-main` 引入。容器内项目路径 `/app/www/ai-device/ota`。
+
+## 1. composer 引入（在 docker php82 内执行）
+在 [composer.json](composer.json) 增加 `repositories` 与依赖：
+
+- 顶层新增：
+```json
+"repositories": [
+  { "type": "vcs", "url": "https://git.waixingkeji.net/quanfuxia/log.git" }
+]
+```
+- `require` 增加 `"quanfuxia/log": "dev-main"`
+
+执行安装（遵循 dev-environment 规则，宿主机不直接跑 composer）：
+```bash
+docker exec -w /app/www/ai-device/ota php82 composer require quanfuxia/log:dev-main
+```
+> 项目 `minimum-stability: dev` + `prefer-stable: true`，`dev-main` 可正常解析。私有仓库已验证可匿名 clone；若 composer 拉取需鉴权再补充凭据。
+
+## 2. 配置 config/log.php
+将 [config/log.php](config/log.php) 的 `default` channel 由 `RotatingFileHandler` 改为 `SeasLogHandler`，并加上 `IntrospectionProcessor` 注入调用源（`extra.class/function/file/line`）：
+
+```php
+use Monolog\Logger;
+use Monolog\Processor\IntrospectionProcessor;
+use Quanfuxia\Log\SeasLogHandler;
+use Quanfuxia\Log\SeasLogLineFormatter;
+
+return [
+    'default' => [
+        'handlers' => [[
+            'class' => SeasLogHandler::class,
+            'constructor' => ['level' => Logger::DEBUG, 'bubble' => true],
+            'formatter' => [
+                'class' => SeasLogLineFormatter::class,
+                'constructor' => [
+                    "%message% %extra.class%%extra.callType%%extra.function% %extra.file%:%extra.line% %context%\n",
+                    'Y-m-d H:i:s', true, true,
+                ],
+            ],
+        ]],
+        'processors' => [[
+            'class' => IntrospectionProcessor::class,
+            'constructor' => [Logger::DEBUG, ['support\\Log'], 0],
+        ]],
+    ],
+];
+```
+> [config/process.php](config/process.php) 中 `'logger' => Log::channel('default')` 无需改动，框架日志将随之写入 SeasLog。
+
+## 3. 新增 Trace 中间件初始化 trace_id
+每次 HTTP 请求开始时初始化链路 ID，使同一请求内日志 trace_id 一致，并支持上游透传。
+
+- 新增 `app/middleware/TraceId.php`（实现 `Webman\MiddlewareInterface`）：从请求头（如 `X-Trace-Id`）取值，调用 `Quanfuxia\Log\Trace\TraceContext::init($headerTraceId)`，再 `return $handler($request)`。
+- 在 [config/middleware.php](config/middleware.php) 注册为全局中间件：
+```php
+return [
+    '' => [ app\middleware\TraceId::class ],
+];
+```
+> CLI / 非中间件入口无需额外处理：`TraceContext::getTraceId()` 在缺失时会自动生成并写回上下文。
+
+## 4. 验证
+```bash
+docker exec -w /app/www/ai-device/ota php82 php -l config/log.php
+docker exec -w /app/www/ai-device/ota php82 php -l app/middleware/TraceId.php
+# 启动后请求一次接口，检查日志落盘
+docker exec php82 sh -lc 'ls -R /app/www/ai-device/ota/runtime/logs'
+```
+并按 `slot-backend-completion-report` 跑收尾门禁。
+
+## 注意 / 待确认
+- `git_status` 显示 `composer.json`/`composer.lock` 已有 `vlucas/phpdotenv` 改动，本次只追加，不回退既有改动。
+- 日志格式字符串、`X-Trace-Id` 头名称如需调整可后续微调（默认按 readme 示例）。