2026-03-16 17:58:57 +08:00
|
|
|
|
# CLAUDE.md
|
|
|
|
|
|
|
|
|
|
|
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
|
|
|
|
|
|
|
|
|
|
|
## 项目概述
|
|
|
|
|
|
|
|
|
|
|
|
这是一个前端工具库 monorepo，使用 **pnpm workspace** 管理，包含以下子包：
|
|
|
|
|
|
|
|
|
|
|
|
| 包名 | 路径 | 描述 |
|
|
|
|
|
|
|------|------|------|
|
|
|
|
|
|
| `@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
|
|
|
|
|
|
|
|
|
|
|
|
# 构建单个包（在包目录内）
|
|
|
|
|
|
cd packages/common && pnpm build
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
> `@r-utils/common` 同时有 `webpack.config.js` 和 `rollup.config.js`，当前 `build` 脚本使用 webpack；rollup 配置备用。
|
|
|
|
|
|
|
|
|
|
|
|
### 测试
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
# 在根目录运行所有测试
|
|
|
|
|
|
pnpm test
|
|
|
|
|
|
|
|
|
|
|
|
# 运行单个测试文件
|
|
|
|
|
|
npx jest packages/common/test/permission.test.ts
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
测试文件位于各包的 `test/` 目录下，使用 Jest + Babel。
|
|
|
|
|
|
|
|
|
|
|
|
### 代码检查与格式化
|
|
|
|
|
|
|
|
|
|
|
|
```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 和 jest 测试，commit-msg 钩子会用 commitlint 校验提交信息格式。
|
|
|
|
|
|
|
2026-03-18 16:32:27 +08:00
|
|
|
|
### 发布
|
|
|
|
|
|
|
|
|
|
|
|
发布分两步：先用 `standard-version` 管理版本，再用脚本构建和发布。
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
# 1. 版本管理（更新版本号 + 生成 CHANGELOG + git commit/tag）
|
|
|
|
|
|
pnpm release # 默认 patch
|
|
|
|
|
|
npx standard-version --release-as minor # 指定版本类型
|
|
|
|
|
|
|
|
|
|
|
|
# 2. 构建并发布到 npm
|
|
|
|
|
|
bash scripts/publish.sh # Linux/macOS
|
|
|
|
|
|
powershell scripts/publish.ps1 # Windows
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
版本配置见 `.versionrc.json`，会同步更新根包和所有子包的版本号。
|
|
|
|
|
|
|
2026-03-16 17:58:57 +08:00
|
|
|
|
## 架构说明
|
|
|
|
|
|
|
|
|
|
|
|
### Monorepo 结构
|
|
|
|
|
|
|
|
|
|
|
|
- 根 `package.json` 定义 devDependencies（构建工具、ESLint、Jest 等），各子包在自身 `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` 生命周期钩子
|
