@composy/log-viewer-core 0.0.1 → 0.0.2

package/CHANGELOG.md

@@ -0,0 +1,52 @@
+# Changelog
+
+## [0.0.2] - 2026-10-12
+
+### ✨ 新功能
+
+- **log-viewer**: 重构项目结构并完善文档与示例 ([7844674](https://gitee.com/ldesign-v1/ldesign-log-viewer/commit/78446741f92a4e0fa35e358481246c597c5d3691)) - @swimly
+- **log-viewer**: 添加项目配置文件 ([a952739](https://gitee.com/ldesign-v1/ldesign-log-viewer/commit/a9527395a4999212ec4f0444c7f1a54a021da0ca)) - @swimly
+- auto-generated playground + README for log-viewer sub-packages ([a2250ec](https://gitee.com/ldesign-v1/ldesign-log-viewer/commit/a2250ecd98551c15e822dde8a61389b02f161725)) - @swimly
+- **log-viewer**: 实现核心库、Vue组件和playground演示 ([ec9764a](https://gitee.com/ldesign-v1/ldesign-log-viewer/commit/ec9764a7bc8964b95486f1035ece6783801380a3)) - @swimly
+- init log-viewer project structure ([304c73f](https://gitee.com/ldesign-v1/ldesign-log-viewer/commit/304c73f7c9dbd6886abf059806bf619cb724cc84)) - @swimly
+
+### 🐛 Bug 修复
+
+- **log-viewer**: 规范 EventEmitter 类型 ([58545d3](https://gitee.com/ldesign-v1/ldesign-log-viewer/commit/58545d346c1031471c84cc972b91614cee4c3858)) - @swimly
+
+### 📝 文档更新
+
+- **core**: 更新 README 文档，补充使用说明与示例 ([8e1330e](https://gitee.com/ldesign-v1/ldesign-log-viewer/commit/8e1330e5c293e76554444351ed1be15d5559b634)) - @swimly
+
+### 📦 构建系统
+
+- **packages**: 更新各包依赖与配置项 ([939d05c](https://gitee.com/ldesign-v1/ldesign-log-viewer/commit/939d05c5a3a94e576023c360224cdd0600f73d8f)) - @swimly
+- 调整本地ldesign依赖为本地链接，更新核心包构建配置 ([1a9d4a1](https://gitee.com/ldesign-v1/ldesign-log-viewer/commit/1a9d4a1d8e05ee6773e6e7876eec50663baeaf45)) - @swimly
+- **tsconfig**: 完善 tsconfig 配置，添加声明文件输出与映射配置 ([d5f862a](https://gitee.com/ldesign-v1/ldesign-log-viewer/commit/d5f862a0149af874e78e26116ce0d276c3479a6c)) - @swimly
+- 为 core 和 vue 包添加 ldesign-builder 配置 ([0ded57e](https://gitee.com/ldesign-v1/ldesign-log-viewer/commit/0ded57e7bde3fcfe8fa1a2af05beb9a6c1beb7e1)) - @swimly
+
+### 🔧 其他
+
+- **log-viewer**: 更新项目配置与依赖管理 ([986acd2](https://gitee.com/ldesign-v1/ldesign-log-viewer/commit/986acd26bdecd9096450049f32d067bf4ae8b292)) - @swimly
+- 更新 core 和 vue 包的依赖版本 ([a50b9d7](https://gitee.com/ldesign-v1/ldesign-log-viewer/commit/a50b9d79ed2dfb4296ab960bc605394ad233eb2e)) - @swimly
+- update log-viewer (15 files) ([c45bb7d](https://gitee.com/ldesign-v1/ldesign-log-viewer/commit/c45bb7d3705ff21255c7900f1547d3e23ff6abd0)) - @swimly
+- normalize versions, clean artifacts, update gitignore ([1fa0666](https://gitee.com/ldesign-v1/ldesign-log-viewer/commit/1fa0666c7516c24c943c3bd5e0edd2ce5c664203)) - @swimly
+- update - chore(code-quality): 完成首轮代码优化与æ  ([ac14af0](https://gitee.com/ldesign-v1/ldesign-log-viewer/commit/ac14af054dd10254ed40c7cb2efa4bf9c9b23735)) - @swimly
+- **code-quality**: 完成首轮代码优化与标准化工作 ([82f7750](https://gitee.com/ldesign-v1/ldesign-log-viewer/commit/82f77508bedc8f99c2c0db16098c3bc81f05f185)) - @swimly
+- 批量更新 - 规范 .gitignore 清理源码 ([cf22736](https://gitee.com/ldesign-v1/ldesign-log-viewer/commit/cf22736fbb924cc0a40506e2b06b304d7aa4356d)) - @swimly
+- unified build config and structure ([b193057](https://gitee.com/ldesign-v1/ldesign-log-viewer/commit/b1930571dadec0dbe8240dfc0fcd7fbef046b28e)) - @swimly
+- 添加 ESLint 配置和测试脚本到 core 和 vue 包 ([6742aec](https://gitee.com/ldesign-v1/ldesign-log-viewer/commit/6742aec2dc2d11b66d9a8ecbd7db4f5ab0616cf4)) - @swimly
+- add build config, tsconfig, README ([1c1c88f](https://gitee.com/ldesign-v1/ldesign-log-viewer/commit/1c1c88fc9c35a9f82161b98e6800a8ac98b811e8)) - @swimly
+- clean up project structure - keep only packages/core/src and packages/vue/src ([fed9abd](https://gitee.com/ldesign-v1/ldesign-log-viewer/commit/fed9abd6ac1a5b65123f79d9f60cc394beda1822)) - @swimly
+- 标准化构建配置并更新外部依赖声明 ([645e72d](https://gitee.com/ldesign-v1/ldesign-log-viewer/commit/645e72dfa27e428da23270dc6dbbcbaaee88e384)) - @swimly
+- batch commit submodule changes ([dae1c30](https://gitee.com/ldesign-v1/ldesign-log-viewer/commit/dae1c30d34b23869b357ee1ef6f954d08b7d5781)) - @swimly
+- set versions to 0.0.1 and pin @ldesign deps ([0b6b3a9](https://gitee.com/ldesign-v1/ldesign-log-viewer/commit/0b6b3a98fb6096a0ac735216166ea9e63ed081b3)) - @swimly
+
+### 👥 Contributors
+
+swimly
+
+### 📊 Statistics
+
+- Total Commits: **25**
+- Contributors: **1**

package/README.md

@@ -1,37 +1,175 @@
-# @composy/log-viewer-core
-
-审计日志查看器 - 操作日志可视化与追溯
-
-## 功能特性
-
-- 🚀 高性能核心引擎
-- 🎨 TypeScript 类型完整
-- 📦 支持 ESM / CJS 双格式输出
-
-## 安装
-
-```bash
-npm install @composy/log-viewer-core
-```
-
-## 快速开始
-
-```typescript
-import { /* 需要的导出 */ } from '@composy/log-viewer-core'
-
-// 根据实际 API 使用
-```
-
-## 目录结构
-
-```
-packages/core/
-├── src/              # 源码
-├── package.json
-├── tsconfig.json     # ESM 构建配置
-└── tsconfig.cjs.json # CJS 构建配置
-```
-
-## License
-
-MIT
+# @composy/log-viewer-core
+
+审计日志查看器核心库 — 操作日志的计时线可视化与追溯（渲染库，类实例模式，非 Web Component）。
+
+`log-viewer-core` 通过 `LogViewer` 类实例 + `TimelineRenderer` + `DiffRenderer`
+直接操作宿主 DOM，将审计日志渲染为时间线：支持按操作类型/模块/用户/IP/关键字/时间范围的多条件筛选，时间戳倒序排列与服务端式分页，条目点击展开详情并通过
+`DiffRenderer`
+呈现字段级变更对比（DiffEntry），内置异常标记（非工作时间/敏感操作/高频操作）与明暗主题切换。它不依赖任何 UI 框架，`packages/vue`
+另行提供 Vue 3 适配器；样式通过 `injectStyles()` 注入 `<head>`。
+
+## 安装
+
+```bash
+# pnpm
+pnpm add @composy/log-viewer-core
+# npm
+npm install @composy/log-viewer-core
+```
+
+## 目录结构
+
+```
+packages/core/
+├── src/
+│   ├── index.ts            # 统一导出入口 + createLogViewer 工厂
+│   ├── types/index.ts      # 全部类型与常量（ACTION_LABELS/ACTION_COLORS）
+│   ├── core/               # LogViewer.ts / EventEmitter.ts
+│   ├── filters/            # FilterEngine.ts 多条件筛选引擎
+│   ├── renderers/          # TimelineRenderer.ts / DiffRenderer.ts
+│   ├── styles/index.ts     # 样式定义 + injectStyles 注入
+│   └── utils/index.ts      # formatDate/formatRelativeTime/escapeHtml/debounce/uid/formatValue/deepClone
+├── .ldesign/
+│   ├── builder.config.ts   # @composy/builder（rolldown）构建配置
+│   ├── tsconfig.esm.json   # ESM 类型检查配置
+│   └── tsconfig.cjs.json   # CJS 类型检查配置
+└── package.json
+```
+
+## 核心 API 详表
+
+以下导出均严格来自 `src/index.ts`，按分组列出。
+
+### 常量与核心（core/）
+
+| 名称              | 类型     | 签名                                     | 用途                                   |
+| ----------------- | -------- | ---------------------------------------- | -------------------------------------- |
+| `VERSION`         | const    | `'0.1.0'`                                | 包版本常量                             |
+| `LogViewer`       | class    | `implements LogViewerInstance`           | 主引擎：数据管理、筛选、分页、渲染编排 |
+| `createLogViewer` | function | `(config: LogViewerConfig) => LogViewer` | 创建查看器实例的工厂函数               |
+| `EventEmitter`    | class    | `on/emit/removeAllListeners`             | 轻量事件总线                           |
+
+### 筛选与渲染器
+
+| 名称               | 类型  | 签名                                                                 | 用途                                    |
+| ------------------ | ----- | -------------------------------------------------------------------- | --------------------------------------- |
+| `FilterEngine`     | class | `filter(data, filter) => LogEntry[]`                                 | 按用户/动作/模块/IP/时间范围/关键字过滤 |
+| `TimelineRenderer` | class | `render(pageData, expanded) => HTMLElement`、`renderPagination(...)` | 渲染时间线条目与分页                    |
+| `DiffRenderer`     | class | `renderDetail(entry) => HTMLElement`                                 | 渲染条目字段级变更详情                  |
+
+### 工具与样式
+
+| 名称                                | 类型     | 签名                                    | 用途                    |
+| ----------------------------------- | -------- | --------------------------------------- | ----------------------- |
+| `formatDate` / `formatRelativeTime` | function | `(value) => string`                     | 日期 / 相对时间格式化   |
+| `escapeHtml`                        | function | `(str) => string`                       | HTML 转义（防 XSS）     |
+| `debounce`                          | function | `(fn, wait?) => 包装函数`               | 防抖                    |
+| `uid`                               | function | `() => string`                          | 生成唯一 ID             |
+| `formatValue` / `deepClone`         | function | `(value) => string` / `(obj) => 深拷贝` | 值格式化显示 / 深拷贝   |
+| `injectStyles`                      | function | `() => void`                            | 注入全局样式到 `<head>` |
+
+### 类型与常量（types/）
+
+| 名称                                | 类型      | 说明                                                                                                                                      |
+| ----------------------------------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
+| `ActionType`                        | type      | `'create' \| 'update' \| 'delete' \| 'query' \| 'login' \| 'logout' \| 'export' \| 'import' \| 'approve' \| 'reject' \| 'other'` 操作类型 |
+| `ThemeMode` / `AnomalyType`         | type      | 主题 `'light' \| 'dark'`；异常标记 `'off-hours' \| 'sensitive' \| 'high-frequency' \| 'none'`                                             |
+| `DiffEntry`                         | interface | 字段变更条目 `{ field; label?; oldValue; newValue }`                                                                                      |
+| `LogEntry`                          | interface | 日志条目（id、timestamp、user、action、module、detail、changes、anomaly 等）                                                              |
+| `FilterConfig` / `PaginationConfig` | interface | 筛选配置、分页配置                                                                                                                        |
+| `LogViewerConfig`                   | interface | 查看器配置（container、data/dataSource、filter、pagination、theme、locale、showFilter/showDiff/showAnomalyBadge 及回调）                  |
+| `LogViewerInstance`                 | interface | 实例 API（getData/setData/appendData/setFilter/resetFilter/setTheme/expandEntry/goToPage/on/refresh/destroy）                             |
+| `LogViewerEvents`                   | interface | 事件映射（`filter:change`、`entry:click`、`entry:expand` 等）                                                                             |
+| `ACTION_LABELS` / `ACTION_COLORS`   | const     | 操作类型中文标签 / 颜色映射                                                                                                               |
+
+## 使用示例
+
+```ts
+import { createLogViewer, type LogEntry } from '@composy/log-viewer-core'
+
+const entries: LogEntry[] = [
+  {
+    id: 'e1',
+    timestamp: new Date().toISOString(),
+    user: 'admin',
+    action: 'update',
+    module: '订单',
+    ip: '10.0.0.1',
+    detail: '修改了订单状态',
+    changes: [{ field: 'status', oldValue: '待发货', newValue: '已发货' }],
+  },
+]
+
+const viewer = createLogViewer({
+  container: '#log-viewer',
+  data: entries,
+  theme: 'dark',
+  pageSize: 10,
+  showFilter: true,
+  showDiff: true,
+  showAnomalyBadge: true,
+  onEntryClick: entry => console.log('点击日志', entry.id),
+  onFilterChange: filter => console.log('筛选变更', filter),
+})
+viewer.appendData([
+  { id: 'e2', timestamp: Date.now(), user: 'alice', action: 'login', module: '认证' },
+])
+viewer.setFilter({ action: 'login' })
+viewer.expandEntry('e1')
+console.log('当前分页：', viewer.getPagination())
+viewer.on('theme:change', theme => console.log('主题', theme))
+viewer.destroy() // 卸载时销毁
+```
+
+## 构建脚本 & 验证命令
+
+| 命令                                                              | 说明                                           |
+| ----------------------------------------------------------------- | ---------------------------------------------- |
+| `pnpm --dir packages/core run build`                              | `@composy/builder`（rolldown）产出多格式产物   |
+| `pnpm --dir packages/core run type-check` / `type-check:cjs`      | 分别检查 ESM 与 CJS 配置                       |
+| `pnpm --dir packages/core run lint` / `lint:check` / `lint:fix`   | ESLint 检查 / 零告警严格 / 自动修复            |
+| `pnpm --dir packages/core run test` / `test:coverage` / `test:ui` | `ltesting` 单测 / 覆盖率 / 仪表盘              |
+| `pnpm --dir packages/core run release`                            | `ldesign-release publish --package-dir .` 发布 |
+
+## 产物说明
+
+`exports` 暴露多入口；根入口按 `types/import/require/default` 映射到 `es`、`lib`：
+
+- `es/` — ESM 产物（`index.js` + `index.d.ts`），`import` 与类型入口（`module`/`types` 指向）。
+- `lib/` — CJS 产物（`index.cjs`），`require` 入口（`main` 指向 `lib/index.cjs`）。
+- `esm/` — ESM 与样式源的保留模块目录。
+- `dist/` — UMD 浏览器产物（`index.js`/`index.min.js`），`unpkg`/`jsdelivr`/`browser` 指向。
+
+子路径别名（`./core/*`、`./filters/*`、`./renderers/*`、`./styles`、`./types`、`./utils`）均同时解析到
+`es` 与 `lib`。`sideEffects: false`，可安全 tree-shaking。
+
+## 备注
+
+- **依赖**：`dependencies` 为空，无运行时三方依赖；`devDependencies` 含
+  `@composy/builder`、`@composy/testing`、`@composy/release`、`@antfu/eslint-config`、`typescript`。发布注册中心
+  `http://npm.longrise.cn:6286/`。
+- **渲染库架构**：非 Web Component、无 Shadow DOM；直接操作宿主 DOM，根节点 class 为
+  `lv-root`（内部采用 `lv-*` 前缀），样式由 `injectStyles()` 注入 `<head>`。
+- **浏览器依赖**：使用 `document`/`window`，仅限浏览器环境，SSR 需环境判断。
+- **容器解析**：`container` 传字符串选择器找不到元素时抛出 `[LogViewer] Container not found`。
+- **数据来源**：`LogViewerConfig.dataSource` 支持字符串 URL 或
+  `() => Promise<LogEntry[]>`，异步拉取需自行在回调中 `setData`。
+- **代码任务边界**：CSS 变量/class 前缀、样式 token 和测试覆盖属于源码任务；本工作区结构任务只维护配置、产物契约和文档。
+
+## License
+
+MIT
+
+## Runtime guarantees
+
+- `dataSource` accepts a URL or an async loader. Call `loadData()` to load it explicitly; the
+  constructor also starts the initial load when a source is configured. URL responses may be an
+  array or an object containing `data`, `logs`, `items`, or `entries`.
+- `showFilter`, `showDiff`, and `showAnomalyBadge` control the matching runtime surfaces. Invalid
+  page sizes are normalized and page changes are clamped to the available range.
+- `getData()` and `getFilter()` return deep snapshots. Filtering and timestamp sorting operate on
+  derived arrays, so caller-owned data is not reordered or mutated.
+- Timeline actions and diff metadata are rendered with DOM text nodes. User-provided values do not
+  become HTML or CSS declarations.
+- Injected styles consume `@composy/color` and `@composy/size` CSS variables. The package remains
+  framework-neutral and requires a browser `document` at runtime.