<!-- 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 示例）。