<!-- 2b9f6c44-867e-43e5-b054-01a0ea21c12a -->
---
todos:
  - id: "scaffold"
    content: "创建 webman-log 目录与 composer.json、.gitignore、phpunit.xml.dist"
    status: pending
  - id: "src"
    content: "复制 SeasLogHandler / SeasLogLineFormatter / TraceContext 到 src 并改为 Quanfuxia\\Log 命名空间"
    status: pending
  - id: "tests"
    content: "复制 tests（bootstrap、config/app、config/log、Log 测试）并改命名空间引用"
    status: pending
  - id: "readme"
    content: "编写新库 readme.md（用途、安装、log.php 接入示例、ext-seaslog 要求）"
    status: pending
  - id: "verify"
    content: "容器内 composer install 并运行 phpunit 验证"
    status: pending
isProject: false
---
# webman-log 独立库拆分方案

## 目标与决策

- 位置：同级目录 `/Users/ray/Documents/project/www/ray/webman-log`
- 包名 `quanfuxia/log`，命名空间 `Quanfuxia\Log\`
- 完全独立：自带一份 trace 上下文，不依赖 `slot/foundation`
- 原库 `slot-foundation/src/Log` 及其引用保持不动（仅复制）

## 来源文件（复制并改命名空间）

- [src/Log/SeasLogHandler.php](/Users/ray/Documents/project/www/ray/slot-foundation/src/Log/SeasLogHandler.php) → `webman-log/src/SeasLogHandler.php`，命名空间改为 `Quanfuxia\Log`，`use slot\foundation\Trace\TraceContext` 改为 `use Quanfuxia\Log\Trace\TraceContext`
- [src/Log/SeasLogLineFormatter.php](/Users/ray/Documents/project/www/ray/slot-foundation/src/Log/SeasLogLineFormatter.php) → `webman-log/src/SeasLogLineFormatter.php`，命名空间改为 `Quanfuxia\Log`
- [src/Trace/TraceContext.php](/Users/ray/Documents/project/www/ray/slot-foundation/src/Trace/TraceContext.php) → `webman-log/src/Trace/TraceContext.php`，命名空间改为 `Quanfuxia\Log\Trace`（自带，保证独立）

## 新建库目录结构

```text
webman-log/
  composer.json
  .gitignore
  phpunit.xml.dist
  readme.md
  src/
    SeasLogHandler.php          # Quanfuxia\Log
    SeasLogLineFormatter.php    # Quanfuxia\Log
    Trace/TraceContext.php      # Quanfuxia\Log\Trace
  tests/
    bootstrap.php
    config/
      app.php
      log.php
    Log/
      SeasLogLineFormatterTest.php
```

## composer.json 要点

```json
{
  "name": "quanfuxia/log",
  "type": "library",
  "autoload": { "psr-4": { "Quanfuxia\\Log\\": "src/" } },
  "autoload-dev": { "psr-4": { "Tests\\": "tests/" } },
  "require": {
    "php": ">=8.2",
    "monolog/monolog": "^2.0",
    "workerman/webman-framework": "^2.1"
  },
  "suggest": { "ext-seaslog": "写入 SeasLog 需要该扩展" },
  "require-dev": { "phpunit/phpunit": "^11.5" }
}
```

说明：保留 `workerman/webman-framework`，因为 `TraceContext` 用 `Webman\Context`，`SeasLogHandler` 用 `runtime_path()` / `request()` 辅助函数。

## 依赖关系

```mermaid
graph LR
  Monolog[Monolog Logger] --> Handler[SeasLogHandler]
  Handler --> Formatter[SeasLogLineFormatter]
  Handler --> Trace[TraceContext]
  Handler --> SeasLog[ext-seaslog]
  Trace --> Ctx[Webman Context]
```

## 测试与配置

- 复制并改命名空间：`tests/Log/SeasLogLineFormatterTest.php`（`use Quanfuxia\Log\...`）
- 复制 `tests/bootstrap.php`、`tests/config/app.php`
- 复制 `tests/config/log.php` 并把 handler/formatter 类引用改为 `Quanfuxia\Log\` 命名空间
- `phpunit.xml.dist` 与原库一致（testsuite 名改为 `quanfuxia-log`）
- `.gitignore` 复用原库内容（vendor、runtime、.phpunit.cache 等）

## readme.md

新库 readme 说明：用途（Monolog→SeasLog 适配、自动注入 trace_id）、安装、`config/log.php` 接入示例、对 `ext-seaslog` 的要求。

## 验证

拆分后在容器内运行：

```bash
docker exec php82 sh -lc 'cd /app/www/ray/webman-log && composer install && ./vendor/bin/phpunit'
```