129 lines
3.7 KiB
Markdown
129 lines
3.7 KiB
Markdown
# 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` 生命周期钩子
|