@yixinshuke/node-log 0.0.1 → 0.0.2

package/AGENTS.md

@@ -163,6 +163,8 @@ async function writeAll(fh: FileHandle, chunk: string, timeoutMs: number): Promi
 
 ## 4. 日志格式（JSONL 单行，强制字段）
 
+宿主可用 `blankLineCategories` 指定需要空行分隔的类别：每条 JSON 记录后追加 `\n\n`，其余类别仍为 `\n`。分隔符与记录作为整体参与批次字节计数、切块和失败回填；按行读取时跳过空行。类别含义由宿主定义，组件不硬编码业务类别。
+
 ```json
 {"timestamp":"2026-09-29T10:00:00.123+08:00","host":"pos-node-03","pid":1234,"level":"info","merchantId":1,"storeId":1,"system":"支付系统","bizKey":"202609290001","message":"订单创建成功"}
 ```
@@ -446,4 +448,21 @@ src/
 - 任何错误在被捕获、包装、向上抛出或返回给调用方时，**必须携带具体、可定位的信息**：实际出错的操作、关键参数、原始错误（message / 错误码 / SQL / HTTP 状态码等至少其一）；
 - 日志与返回信息要让排查者「一眼看出是哪一步、什么数据、什么条件下出的错」，而不是把所有失败都归一成一句空话；
 - 允许降级 / 重试 / 返回默认值等容错处理，但**容错的同时必须把具体原因记下来**（日志告警或在错误信息里附带原始错误），不得静默吞掉真实错误、只留一句「请稍后重试」；
-- 若需对外部用户隐藏内部细节，应「对外给友好文案 + 对内保留完整错误链」，两者不可只取前者而丢弃后者。
+- 若需对外部用户隐藏内部细节，应「对外给友好文案 + 对内保留完整错误链」，两者不可只取前者而丢弃后者。
+
+---
+
+## 三个环境（全工作区标准）
+
+权威出处：`../docs/0业务逻辑/003-开发测试生产环境.md`（改动环境口径先改那份，再同步本节）。
+
+| 环境 | 地址 |
+| --- | --- |
+| 开发 | `127.0.0.1:3101 ~ 3105` |
+| 测试 | `1dl-test` / `2sh-test` / `3pay-test` / `4hy-test` / `5pos-test`.yixinshuke.com |
+| 生产·线路1 | `1dl` / `2sh` / `3pay` / `4hy` / `5pos`.yixinshuke.com |
+| 生产·线路2 | 上列域名各加 `2`（`1dl2` / `2sh2` / `3pay2` / `4hy2` / `5pos2`.yixinshuke.com） |
+
+- 服务器端：`.env` 取值 `dev`(默认) / `test` / `prod`；设置优先级 CLI `--env` > `.env` 的 `NODE_ENV` > 操作系统 `NODE_ENV`；启动时在控制台打印当前环境。
+- 网页端：URL query `?env=dev/test/prod`，不带参数 = 生产；登录卡片下方与主界面右上角可选线路——开发环境显示「开发 线路1 线路2」，测试环境显示「测试 线路1 线路2」，生产环境显示「线路1 线路2」；线路1/线路2 始终是生产环境的线路地址。
+- 桌面端：默认生产模式；`pos.exe --env=dev/test/prod`，或 EXE 同目录 `.env` 的 `env=dev/test/prod`；优先级 启动参数 > `.env` > 默认生产模式；线路选择 UI 与网页端相同。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yixinshuke/node-log",
-  "version": "0.0.1",
+  "version": "0.0.2",
   "description": "Node.js 日志组件 - 环形内存缓冲 + 节流追加写到文件（一单据一文件），写失败绝不阻断业务",
   "type": "module",
   "main": "src/index.ts",
@@ -30,7 +30,7 @@
   "license": "MIT",
   "devDependencies": {
     "@types/node": "^22.0.0",
-    "@yixinshuke/node-lock": "file:../node-lock",
+    "@yixinshuke/node-lock": "^0.2.0",
     "typescript": "^5.5.0",
     "vitest": "^2.0.0",
     "tsx": "^4.7.0"

package/src/config.ts

@@ -20,6 +20,8 @@ export interface LoggerConfig {
   baseDir: string;
   /** 最低记录级别，默认 info */
   minLevel?: LogLevel;
+  /** 指定类别的每条日志后增加一个空行；类别由宿主定义，默认不增加 */
+  blankLineCategories?: readonly string[];
   /** 环形缓冲容量（条），满则覆盖最老，默认 10000 */
   maxBufferSize?: number;
   /** 节流刷盘间隔（毫秒），默认 3000 */
@@ -59,6 +61,7 @@ export interface LoggerConfig {
 export const DEFAULT_CONFIG: Required<LoggerConfig> = {
   baseDir: './logs',
   minLevel: 'info',
+  blankLineCategories: [],
   maxBufferSize: 10000,
   flushIntervalMs: 3000,
   flushJitterMs: 500,

package/src/logger.ts

@@ -272,24 +272,25 @@ export class GlobalLogger {
     this.retryAfter.set(rel, Date.now() + delay);
   }
 
-  /** 按 maxFlushBytes 切块（不切断行） */
+  /** 按 maxFlushBytes 切块（不切断记录及其空行分隔符） */
   private buildChunks(entries: LogEntry[]): Chunk[] {
     const limit = Math.max(1, Math.floor(this.config.maxFlushBytes));
     const chunks: Chunk[] = [];
     let lines: string[] = [];
     let size = 0;
     for (const entry of entries) {
-      const line = this.formatEntry(entry);
-      const lineSize = Buffer.byteLength(line, 'utf8') + 1;
+      const separator = this.config.blankLineCategories.includes(entry.context.category ?? '') ? '\n\n' : '\n';
+      const line = this.formatEntry(entry) + separator;
+      const lineSize = Buffer.byteLength(line, 'utf8');
       if (lines.length > 0 && size + lineSize > limit) {
-        chunks.push({ text: lines.join('\n') + '\n', count: lines.length });
+        chunks.push({ text: lines.join(''), count: lines.length });
         lines = [];
         size = 0;
       }
       lines.push(line);
       size += lineSize;
     }
-    if (lines.length > 0) chunks.push({ text: lines.join('\n') + '\n', count: lines.length });
+    if (lines.length > 0) chunks.push({ text: lines.join(''), count: lines.length });
     return chunks;
   }