# Logging-System 项目事实

工作规则见 [AGENTS.md](AGENTS.md)。此文件维护本项目事实，不复制通用规范。

## 仓库与操作

- 目标/产品边界：结构化日志库与可独立部署的采集服务。把一次请求的日志和错误码对齐到同一个 `trace_id`。不导入错误码模块。
- 源码、资产、文档、机器契约位置：模块路径 `logging-system`。包为 `logsys`、`sink`、`redact`、`config`、`slogadapter`、`server`、`cli`、`conformance`、`examples/trace`。配置示例在 `docs/example.json`。
- 权威远端、集成基线、受保护分支：`ssh://git@git-ssh.u1680832.nyat.app:31411/weichen/Logging-System.git`，基线 `main`。
- 并行共同基线记录位置、合入通知/主动检查方式：Gitea Issue/PR。消费方用自己的 gitlink 固定版本。
- 发布线与批准版本/实际制品查询入口：无独立制品库。`go build -o bin/logctl .` 从当前提交构建。
- 提交/审核/合并/发布身份与权限：仓库所有者 weichen。
- 任务唯一来源：Gitea `weichen/Logging-System` 的 Issue 与 Pull Request。
- 规范性文档目录：`policy/`。
- 过程文档仓/目录：`.task/`（任务卡与交付流程证据）；`docs/records/`（其他过程记录，项目内豁免）。
- 交接记录位置：随任务主记录；需要落盘的交接放入 `docs/records/`（其他过程记录）；任务卡与证据在 `.task/`。
- 凭证查找入口及所需字段：采集 token 来自服务配置或环境，字段名为 token / `X-Log-Token`，值不入库。进程内日志还可由 `LOGSYS_CONFIG`、`LOGSYS_LEVEL`、`LOGSYS_SERVICE`、`LOGSYS_REDACT` 覆盖。

## 依赖组合

| 逻辑 ID | 路径 | 角色 |
|---|---|---|
| development-guidelines | `deps/development-guidelines` | development-only |
| development-manager | `deps/development-manager` | development-only（治理与 Agent 执行工具，不参与构建） |

本库 Go 依赖只有标准库。`examples/trace` 是独立模块，用相对路径引用本库与同级检出的 Error-Code-System，不把错误码库变成主模块依赖。

被消费时：

```
require logging-system v0.0.0

replace logging-system => ./deps/logging-system
```

克隆：

```bash
git clone --recurse-submodules ssh://git@git-ssh.u1680832.nyat.app:31411/weichen/Logging-System.git
```

## 验证命令

| 影响 | 工作目录与真实命令/CI | 前提与不覆盖范围 |
|---|---|---|
| 文档 | 核对 `docs/integration.md` 与示例 | 不证明消费方已接线 |
| 模块/接口 | 仓库根：`go vet ./... && go test -count=1 ./...` | 不含 `examples/trace`（独立模块） |
| 数据/权限/恢复 | 文件滚动与采集 JSONL 由 sink/server 测试覆盖 | 无共享数据库 |
| 跨库追溯示例 | 在 `examples/trace`：`go test ./...` | 需要同级目录 `../../../Error-Code-System` 或该 go.mod 的 replace 目标存在 |
| 工程 Agent 执行与治理 | 仓库根：`scripts/agent-exec validate --repo .` 与 `scripts/dm governance check --repo .`（CI 工作流 `governance` 执行同两条） | 需 `deps/development-manager` 按钉住提交检出；只校验配置与治理文件，不覆盖业务行为 |

## 环境与数据

| 环境/实例 ID | 只读查询入口 | 授权写入入口 | DB/存储归属 | 恢复入口 |
|---|---|---|---|---|
| 本地采集器 | `GET /v1/logs`、`logctl query` | `POST /v1/logs` | 配置的 JSONL 文件，默认由 CLI `--data` 指定 | 重放该 JSONL；SSE 游标过期后从查询接口对账 |

共享项及 ACL：配置 token 时写入与读取都要带令牌。部署、迁移、发布的审批依据与负责角色：合并进 `main` 由仓库所有者批准。
实际制品/配置/schema 的查询方法：以运行中的配置文件与 `LOGSYS_*` 环境变量为准，不以 `docs/example.json` 代替现场配置。