# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## 项目概述

这是一个前端工具库 monorepo，使用 **pnpm workspace + turbo** 管理，包含以下子包：

| 包名 | 路径 | 描述 |
|------|------|------|
| `@r-utils/common` | `packages/common` | 通用 JS/TS 工具库（不依赖框架） |
| `@r-utils/vue3` | `packages/vue3` | Vue3 专用工具 |
| `@r-utils/uni-app` | `packages/uni-app` | uni-app 专用工具 |
| `@r-utils/vue2` | `packages/vue2` | Vue2 专用工具 |

## 常用命令

### 构建

```bash
# 构建所有包
pnpm build

# 构建单个包（Turbo filter）
pnpm build -- --filter=@r-utils/common

# 构建单个包（在包目录内）
cd packages/common && pnpm build
```

> `@r-utils/common` 同时有 `webpack.config.js` 和 `rollup.config.js`，当前 `build` 脚本使用 webpack；rollup 配置备用。

### 测试

```bash
# 在根目录运行所有测试
pnpm test

# 运行单个测试文件
pnpm vitest run packages/common/test/permission.test.ts
```

测试文件位于各包的 `test/` 目录下，使用 Vitest。

### 代码检查与格式化

```bash
# Lint（从根目录，仅检查 src 目录）
pnpm lint

# 格式化
pnpm format
```

ESLint 使用 v9 flat config（`eslint.config.js`），已整合 TypeScript 和 Prettier 规则。

### Git 提交

```bash
# 使用 commitizen 提交（遵循 conventional commits 规范）
pnpm commit
```

**注意**：提交时 husky pre-commit 钩子会自动运行 lint-staged 和 `pnpm test`，commit-msg 钩子会用 commitlint 校验提交信息格式。

### 发布

发布分四步：先记录 changeset，再校验与构建、更新版本，最后通过 `package.json` 命令发布。

```bash
# 1. 记录变更
pnpm changeset

# 2. 质量检查与构建
pnpm release:check

# 3. 版本管理（更新受影响包版本号 + 生成 CHANGELOG）
pnpm release

# 4. 发布到 npm
pnpm release:publish
```

也可以使用一键命令：

```bash
pnpm release:all
```

changesets 配置见 `.changeset/config.json`，完整发布说明见 `docs/RELEASE.md`。

## 架构说明

### Monorepo 结构

- 根 `package.json` 定义 devDependencies（构建工具、ESLint、Vitest 等），各子包在自身 `package.json` 中声明运行时依赖
- `@r-utils/uni-app` 通过 `workspace:^` 依赖 `@r-utils/common`；其他包目前通过 `file:` 本地路径引用
- 每个包均输出 ES 模块格式，入口为 `dist/index.js`，类型声明在 `dist/index.d.ts`

### 构建工具

- 各包使用 **webpack 5** + **ts-loader** 进行构建，输出 ES module（`experiments.outputModule: true`）
- TypeScript 配置：`target: esnext`、`strict: true`、路径别名 `@` 指向 `src/`

### `@r-utils/common` 模块结构

```
src/
├── permission/   Permission 类：权限字符串格式校验（如 "module:action:resource"）
├── timer/        Countdown（倒计时）、TimeoutTimer
├── printer/      ESC 打印工具，PrintUtil 继承自 JpPrinter（esc.js）
├── knock-test/   KnockTest：按顺序敲击/点击触发回调的状态机
└── time/         时间工具函数
```

### `@r-utils/uni-app` 主要模块

- `request/Request.ts`：类 axios 的 uni.request 封装，支持请求/响应拦截器
- `uni-helper.ts`：uni-app 常用工具（scanCode、toPromise、rpxToPx、pathToBase64、Canvas 工具等）
- `bluetooth-utils/`、`nfc/`、`printer/`：蓝牙、NFC、打印机功能

### `@r-utils/vue3`

- `vue-helper.ts`：Vue class 处理工具（`mergeClass`、`createCustomClassObj`）、`dispatch` 祖先组件事件

### `@r-utils/vue2`

- `plugins/visibility.js`：Vue2 mixin 插件，为组件提供 `onShow`/`onHide` 生命周期钩子