create-dwy 0.5.0 → 0.6.0

package/templates/claude-global/skills/dwy-eapi/references/tasks-integration-guide.md

@@ -0,0 +1,387 @@
+# dwyeapi Tasks 集成指南
+
+基于 ARQ 的全异步耗时任务处理系统。开箱即用，3 步接入。
+
+## 1. 安装
+
+```bash
+pip install dwyeapi[tasks]
+# 或
+uv add "dwyeapi[tasks]"
+```
+
+自动安装 `arq` 异步任务队列依赖。需要运行中的 Redis 实例。
+
+## 2. 快速接入
+
+### 第一步：写任务函数
+
+```python
+# app/tasks.py
+from dwyeapi.tasks import register, TaskContext
+
+
+@register("process_data")
+async def process_data(ctx: TaskContext, params: dict):
+    """数据处理任务。"""
+    file_path = params["file"]
+    await ctx.log(f"开始处理文件: {file_path}")
+
+    async with ctx.db() as session:
+        # 查询数据库
+        result = await session.execute(select(RawData).where(...))
+        rows = result.scalars().all()
+
+    for i, row in enumerate(rows):
+        # 业务处理...
+        await ctx.update_progress(int((i + 1) / len(rows) * 100))
+
+        if await ctx.is_cancelled():
+            await ctx.log("用户取消, 已停止")
+            return
+
+    return {"processed": len(rows)}
+
+
+@register("export_file")
+async def export_file(ctx: TaskContext, params: dict):
+    """文件导出任务。"""
+    await ctx.log("开始导出")
+    # ... 业务逻辑 ...
+    return {"file_url": "/files/report.csv"}
+```
+
+### 第二步：FastAPI 接入
+
+```python
+# app/main.py
+from contextlib import asynccontextmanager
+
+from fastapi import FastAPI
+
+from dwyeapi.database import create_async_engine_factory, create_session_factory
+from dwyeapi.exceptions import register_exception_handlers
+from dwyeapi.tasks import setup_tasks, task_router
+
+from app.config import settings
+
+import app.tasks  # noqa: 触发 @register 装饰器
+
+engine = create_async_engine_factory(settings.database_url)
+session_factory = create_session_factory(engine)
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    await setup_tasks(app, settings, session_factory)
+    yield
+
+
+app = FastAPI(lifespan=lifespan)
+register_exception_handlers(app)
+app.include_router(task_router)  # 挂载 /tasks API
+```
+
+### 第三步：启动 Worker
+
+```python
+# app/worker.py
+from dwyeapi.database import create_async_engine_factory, create_session_factory
+from dwyeapi.tasks import create_worker_settings
+
+from app.config import settings
+
+import app.tasks  # noqa: 触发 @register 装饰器
+
+engine = create_async_engine_factory(settings.database_url)
+session_factory = create_session_factory(engine)
+WorkerSettings = create_worker_settings(settings, session_factory=session_factory)
+```
+
+```bash
+# 终端 1: FastAPI
+uvicorn app.main:app --reload
+
+# 终端 2: Worker
+arq app.worker.WorkerSettings
+
+# 终端 3 (可选): Redis
+redis-server
+```
+
+## 3. .env 配置
+
+```env
+DATABASE_URL=postgresql+asyncpg://user:pass@localhost/mydb
+REDIS_URL=redis://localhost:6379/0
+SECRET_KEY=your-secret-key
+
+# 任务模块配置 (均有默认值, 可不配)
+TASK_MAX_JOBS=5           # Worker 最大并发任务数 (默认 5)
+TASK_JOB_TIMEOUT=3600     # 单个任务超时秒数 (默认 3600)
+TASK_FAILURE_TTL=86400    # 失败任务在 Redis 中保留秒数 (默认 86400)
+```
+
+## 4. API 接口
+
+挂载 `task_router` 后自动获得以下接口：
+
+| 方法 | 路径 | 说明 |
+|------|------|------|
+| POST | `/tasks` | 提交任务 |
+| GET | `/tasks/{task_id}` | 查询单个任务状态 |
+| GET | `/tasks` | 任务列表 (分页 + 筛选) |
+| POST | `/tasks/{task_id}/cancel` | 取消任务 |
+
+### 提交任务
+
+```bash
+curl -X POST http://localhost:8000/tasks \
+  -H "Content-Type: application/json" \
+  -d '{"task_type": "process_data", "params": {"file": "data.csv"}}'
+```
+
+```json
+{
+  "code": 200,
+  "message": "success",
+  "data": {
+    "id": "task_a1b2c3d4...",
+    "task_type": "process_data",
+    "status": "pending",
+    "progress": 0,
+    "logs": "[2026-04-05 10:00:00] 任务已创建, 等待执行\n",
+    "result": null,
+    "params": {"file": "data.csv"},
+    "created_at": "2026-04-05T10:00:00",
+    "updated_at": "2026-04-05T10:00:00"
+  },
+  "timestamp": 1775000000
+}
+```
+
+### 查询状态 (轮询)
+
+```bash
+curl http://localhost:8000/tasks/task_a1b2c3d4...
+```
+
+`status` 会从 `pending` → `running` → `success`/`failed`/`canceled` 变化，`progress` 从 0 递增到 100。
+
+### 任务列表
+
+```bash
+# 分页 + 状态筛选
+curl "http://localhost:8000/tasks?page=1&page_size=20&status=running"
+
+# 按类型筛选
+curl "http://localhost:8000/tasks?task_type=process_data"
+```
+
+### 取消任务
+
+```bash
+curl -X POST http://localhost:8000/tasks/task_a1b2c3d4.../cancel
+```
+
+仅 `pending` 和 `running` 状态的任务可取消。已结束的任务返回 400。
+
+### 自定义路由前缀
+
+```python
+app.include_router(task_router, prefix="/api/jobs")  # /api/jobs/*
+```
+
+## 5. TaskContext API
+
+任务函数收到的 `ctx` 对象，提供以下方法：
+
+| 方法 | 签名 | 说明 |
+|------|------|------|
+| ctx.log | `async (message: str) -> None` | 追加带时间戳的日志 |
+| ctx.update_progress | `async (value: int, message: str = "") -> None` | 更新进度 0-100, 可选附日志 |
+| ctx.is_cancelled | `async () -> bool` | 检查是否被取消 (读 Redis 标记) |
+| ctx.db | `() -> AsyncContextManager[AsyncSession]` | 获取数据库 session |
+
+### 属性
+
+| 属性 | 类型 | 说明 |
+|------|------|------|
+| ctx.task_id | str | 当前任务唯一 ID |
+| ctx.task_type | str | 任务类型 |
+| ctx.params | dict | 提交时的入参 |
+
+### 生命周期 (框架自动管理)
+
+```
+任务入队
+  → 状态设为 RUNNING + 记日志 "任务开始执行"
+    → 调用业务函数 func(ctx, params)
+      → 正常返回 dict → 状态设为 SUCCESS, result = 返回值, progress = 100
+      → 抛异常       → 状态设为 FAILED, result = {"error": "..."}
+      → 取消退出     → 状态设为 CANCELED
+```
+
+业务代码**不需要**手动管理 RUNNING/SUCCESS/FAILED 状态转换。
+
+## 6. 任务注册
+
+### @register 装饰器
+
+```python
+from dwyeapi.tasks import register, TaskContext
+
+@register("unique_task_type")
+async def my_task(ctx: TaskContext, params: dict):
+    ...
+```
+
+- `task_type` 全局唯一，重复注册抛 `ValueError`
+- 必须是 `async def`
+- 签名固定为 `(ctx: TaskContext, params: dict)`
+- 返回 `dict` 或 `None`
+
+### 确保装饰器被执行
+
+任务模块必须被导入才能触发 `@register`：
+
+```python
+# main.py 和 worker.py 中都要加
+import app.tasks  # noqa
+```
+
+## 7. 任务取消机制
+
+协作式取消 — 框架设置 Redis 标记，任务函数自行检查并退出。
+
+```python
+@register("batch_import")
+async def batch_import(ctx: TaskContext, params: dict):
+    for batch in batches:
+        # 每批处理前检查
+        if await ctx.is_cancelled():
+            await ctx.log("用户取消, 已导入到第 N 批")
+            return  # 框架自动设为 CANCELED
+
+        await process_batch(batch)
+        await ctx.update_progress(...)
+```
+
+**注意：** 取消不会回滚已执行的操作。已插入的数据不会被撤销。如需回滚，在检测到取消后执行自定义清理逻辑。
+
+## 8. 任务状态
+
+| 状态 | 值 | 说明 |
+|------|------|------|
+| PENDING | `"pending"` | 已创建, 等待 Worker 执行 |
+| RUNNING | `"running"` | 正在执行中 |
+| SUCCESS | `"success"` | 执行成功 |
+| FAILED | `"failed"` | 执行失败 (异常) |
+| CANCELED | `"canceled"` | 已取消 |
+
+终态：SUCCESS / FAILED / CANCELED，不可再变更。
+
+## 9. Task 数据模型
+
+Task 表自动随业务数据库创建 (复用 eapi 的 `Base`)。
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| id | String(64) | 主键, 自动生成 `task_{uuid}` |
+| task_type | String(50) | 任务类型, 有索引 |
+| status | Enum(TaskStatus) | 任务状态 |
+| params | JSON | 提交时的入参 |
+| result | JSON, nullable | 执行结果 |
+| progress | Integer | 进度 0-100 |
+| logs | Text | 带时间戳的执行日志 |
+| created_at | DateTime | 创建时间 (TimestampMixin) |
+| updated_at | DateTime | 更新时间 (TimestampMixin) |
+
+## 10. Worker 配置
+
+### create_worker_settings
+
+从 eapi 的 `BaseSettings` 自动生成 ARQ Worker 配置：
+
+```python
+from dwyeapi.tasks import create_worker_settings
+
+WorkerSettings = create_worker_settings(settings, session_factory=session_factory)
+```
+
+自动映射：
+- `settings.redis_url` → ARQ `RedisSettings`
+- `settings.task_max_jobs` → `max_jobs` (默认 5)
+- `settings.task_job_timeout` → `job_timeout` (默认 3600s)
+
+### 并发控制
+
+```env
+# 单 Worker, 5 个协程并发
+TASK_MAX_JOBS=5
+
+# 多 Worker 实例: 总并发 = max_jobs x Worker 数
+# 终端 1: arq app.worker.WorkerSettings
+# 终端 2: arq app.worker.WorkerSettings
+# 总并发 = 5 + 5 = 10
+```
+
+IO 密集型任务 (文件导出、第三方 API) 可设 5-10；CPU 密集型任务 (AI 推理) 建议等于 CPU 核心数。
+
+## 11. 公共 API 速查
+
+```python
+from dwyeapi.tasks import (
+    setup_tasks,              # 一站式初始化
+    task_router,              # 开箱即用 APIRouter
+    register,                 # @register 装饰器
+    TaskContext,              # 任务上下文类型
+    TaskStatus,               # 状态枚举
+    create_worker_settings,   # Worker 工厂
+)
+```
+
+| 导出项 | 用途 |
+|--------|------|
+| `setup_tasks(app, settings, session_factory)` | lifespan 中调用, 初始化 ARQ pool |
+| `task_router` | APIRouter, include_router 挂载 |
+| `register(task_type)` | 装饰器, 注册异步任务函数 |
+| `TaskContext` | 任务函数第一个参数的类型 |
+| `TaskStatus` | 枚举: PENDING/RUNNING/SUCCESS/FAILED/CANCELED |
+| `create_worker_settings(settings, session_factory)` | 生成 ARQ WorkerSettings 类 |
+
+## 12. 完整最小示例
+
+```
+myproject/
+├── app/
+│   ├── config.py       # Settings(BaseSettings)
+│   ├── main.py         # FastAPI + setup_tasks + task_router
+│   ├── tasks.py        # @register 任务函数
+│   └── worker.py       # WorkerSettings
+├── .env
+└── pyproject.toml
+```
+
+```toml
+# pyproject.toml
+[project]
+dependencies = ["dwyeapi[tasks]", "asyncpg"]
+```
+
+```env
+# .env
+DATABASE_URL=postgresql+asyncpg://user:pass@localhost/mydb
+REDIS_URL=redis://localhost:6379/0
+SECRET_KEY=your-secret-key
+```
+
+```bash
+# 启动
+uvicorn app.main:app --reload   # API
+arq app.worker.WorkerSettings   # Worker
+
+# 测试
+curl -X POST http://localhost:8000/tasks \
+  -d '{"task_type": "process_data", "params": {"file": "test.csv"}}'
+```

package/templates/claude-global/skills/dwy-ekit/SKILL.md

@@ -0,0 +1,85 @@
+---
+name: dwy-ekit
+description: "@dwydev/ekit 前端工具库速查（v0.7.0）。触发条件：HTTP 请求、dwyeapi 响应契约对接、localStorage/Cookie、表单校验、日期/时区、剪贴板、查询字符串、文件下载、PII 脱敏、Vue composable 工具。"
+---
+
+# @dwydev/ekit 工具库速查（v0.7.0）
+
+Vue 3 项目通用工具库，**薄封装层**：底层用 axios / dayjs / zod / js-cookie / qs / file-saver / @vueuse/core，**对外只暴露 ekit 自有契约**，不泄露底层库类型。
+
+包含 10 个模块：`request` / `storage` / `cookie` / `date` / `validators` / `copy` / `qs` / `file` / `hooks` / `masking`。
+
+## 安装
+
+```bash
+pnpm add @dwydev/ekit
+# peerDependencies: vue ^3.5.0, axios ^1.0.0, dayjs ^1.11.0, zod ^3.25.0, @vueuse/core ^14.2.1
+```
+
+```ts
+import {
+  createRequest, useStorage, useCookie,
+  formatDateTime, isPhone, copyText, stringify, downloadFile,
+  useDebounce, maskPhone,
+} from '@dwydev/ekit'
+```
+
+## 防腐层硬性约束（写代码前必读）
+
+ekit 对外类型 **不允许** 出现底层库类名。下面这些导入 **会失败** —— 因为 ekit 不再 re-export：
+
+```ts
+// ❌ 错误：ekit 不导出底层类型
+import type { AxiosInstance, IStringifyOptions, CookieAttributes } from '@dwydev/ekit'
+import { dayjs } from '@dwydev/ekit'
+
+// ✅ 正确：用 ekit 自有契约
+import type { HttpClient, StringifyOptions, CookieOptions } from '@dwydev/ekit'
+import { now, formatTimestamp } from '@dwydev/ekit'  // 不需要 dayjs 实例
+```
+
+业务代码也 **禁止** 直接调底层 API：
+
+| 禁止 | 改用 |
+|------|------|
+| `new Date()` / `toLocaleString()` | `now()` / `formatTimestamp()` / `formatDateTime()` |
+| `localStorage.setItem(...)` | `storage.set()` 或 `useStorage()` |
+| `navigator.clipboard.writeText(...)` | `copyText()` 或 `useClipboard()` |
+| `document.cookie = ...` | `cookie.set()` 或 `useCookie()` |
+| `document.addEventListener('click', ...)` | `useEventListener()` |
+| 手写 axios 实例 | `createRequest()` |
+
+## 查阅源码
+
+每个模块源码在 `/Users/chances/WebstormProjects/dwy-shared/frontend/ekit/src/{module}/`，函数都很短可以直接读。
+
+## 模块索引
+
+按需读取对应 references 文件，避免一次性加载全部 API 文档。
+
+| 模块 | 用途 | 详见 |
+|---|---|---|
+| `request` | HTTP 客户端（防腐层 + 4 个内置插件 + dwyeapi 响应契约 + 业务错误捕获） | `references/request.md` |
+| `storage` | localStorage 封装（@vueuse/core 的 useStorage + 静态 storage 对象） | `references/data.md` § storage |
+| `cookie` | Cookie 读写（js-cookie 薄封装 + useCookie） | `references/data.md` § cookie |
+| `date` | 日期 / 时间 / 时区格式化（基于 dayjs，不暴露实例） | `references/data.md` § date |
+| `qs` | 查询字符串序列化 / 解析（基于 qs） | `references/data.md` § qs |
+| `validators` | 表单校验（布尔函数 + zod schema 配合 vee-validate） | `references/form.md` § validators |
+| `masking` | PII 数据脱敏（手机/邮箱/身份证/银行卡/姓名/地址等） | `references/form.md` § masking |
+| `copy` | 剪贴板（copyText + @vueuse/core 的 useClipboard） | `references/ui.md` § copy |
+| `file` | 文件下载 / Blob / 文件大小格式化 | `references/ui.md` § file |
+| `hooks` | Vue Composables（全部再导出 @vueuse/core） | `references/ui.md` § hooks |
+
+## v0.6.0 迁移要点
+
+| 旧 | 新 |
+|----|----|
+| `createRequest(): AxiosInstance` | `createRequest(): HttpClient` |
+| `RequestPlugin` | `HttpPlugin` |
+| `import { dayjs } from '@dwydev/ekit'` | 用 `now / formatTimestamp / formatInTimezone / formatDateTime` 等函数 |
+| `CookieAttributes` | `CookieOptions` |
+| `IStringifyOptions / IParseOptions` | `StringifyOptions / ParseOptions` |
+| `DownloadOptions.requestInstance: AxiosInstance` | `DownloadOptions.requester: FileRequester` |
+| 自写 `useDebounce` 返回可写 `Ref` | VueUse `refDebounced` 返回 `Readonly<Ref>` |
+| 自写 `useClipboard` 返回 `{ text, copy, copied, isSupported }`（isSupported 是 boolean） | VueUse 版（isSupported 是 `ComputedRef<boolean>`） |
+| `refreshTokenPlugin` 自动重放 | 必须传 `retry: (cfg) => client.request(cfg)` |

package/templates/claude-global/skills/dwy-ekit/references/data.md

@@ -0,0 +1,135 @@
+# 数据与查询字符串（storage / cookie / date / qs）
+
+> 何时读这份：当用户使用本模块的 API 或问法涉及本模块功能时读取（localStorage 读写、Cookie 读写、日期/时间/时区格式化、查询字符串序列化/解析）。
+
+## storage — localStorage
+
+```ts
+import { useStorage, storage } from '@dwydev/ekit'
+```
+
+### useStorage(key, defaultValue) — 直接再导出 @vueuse/core
+
+跨标签页同步、SSR-safe、自动 JSON 序列化。**API 与 VueUse 一致**（不再是 ekit 自写）。
+
+```ts
+const token = useStorage<string>('token', '')
+const config = useStorage('config', { theme: 'light' }, localStorage, { mergeDefaults: true })
+```
+
+### storage — 静态对象（非组件场景）
+
+| 方法 | 签名 |
+|------|------|
+| `get<T>(key, defaultValue?)` | 返回 `T \| undefined`，JSON 解析失败按字符串返回 |
+| `set(key, value)` | 自动 `JSON.stringify` |
+| `remove(key)` | 删除 |
+| `clear()` | 清空全部（慎用） |
+
+---
+
+## cookie — Cookie 读写
+
+```ts
+import { useCookie, cookie } from '@dwydev/ekit'
+import type { CookieOptions } from '@dwydev/ekit'   // 旧名 CookieAttributes 已废弃
+```
+
+### CookieOptions
+
+```ts
+interface CookieOptions {
+  expires?: number | Date              // 天数或 Date；不传 = 会话级
+  path?: string                        // 默认 '/'
+  domain?: string
+  secure?: boolean                     // 仅 HTTPS
+  sameSite?: 'strict' | 'lax' | 'none'
+}
+```
+
+### cookie（静态）
+
+```ts
+cookie.get<User>('user')
+cookie.set('user', { id: 1, name: 'Alice' }, { expires: 7, secure: true })
+cookie.remove('user', { path: '/' })   // 删除时 path/domain 必须与写入一致
+```
+
+### useCookie(key, defaultValue?) → Ref
+
+```ts
+const lang = useCookie('lang', 'zh-CN')
+lang.value = 'en-US'        // 自动写入 cookie
+lang.value = undefined       // 自动删除
+```
+
+---
+
+## date — 日期 / 时间 / 时区
+
+```ts
+import {
+  now, formatTimestamp, formatInTimezone,
+  formatDate, formatDateTime, formatTime, formatRelativeTime, formatBy,
+} from '@dwydev/ekit'
+```
+
+底层是 dayjs（含 utc + timezone + relativeTime + zh-cn locale 插件），**不导出 dayjs 实例**。所有函数对外用 `string | number | Date`。
+
+### 时间戳工具（v0.6.0 新增）
+
+| 函数 | 签名 | 说明 |
+|------|------|------|
+| `now()` | `(): number` | 当前 UTC Unix 毫秒戳，等价于 `Date.now()` |
+| `formatTimestamp(ts, fmt?)` | `(ts: number, fmt?: string): string` | 把毫秒戳格式化为本地时区字符串。默认 `'YYYY-MM-DD HH:mm:ss'` |
+| `formatInTimezone(tz, ts?, fmt?)` | `(tz: string, ts?: number, fmt?: string): string` | 在指定 IANA 时区下格式化（如 `'Asia/Shanghai'` / `'America/New_York'` / `'UTC'`），ts 不传用当前时间 |
+
+```ts
+const ts = now()                                         // 1745318445000
+formatTimestamp(ts)                                      // '2026-04-22 18:40:45'
+formatTimestamp(ts, 'YYYY/MM/DD')                        // '2026/04/22'
+formatInTimezone('America/New_York', ts)                 // '2026-04-22 06:40:45'
+formatInTimezone('UTC', ts, 'HH:mm')                     // '10:40'
+```
+
+### 普通格式化
+
+| 函数 | 输出 | 输入 |
+|------|------|------|
+| `formatDate(input)` | `YYYY-MM-DD` | `string \| number \| Date` |
+| `formatDateTime(input)` | `YYYY-MM-DD HH:mm:ss` | 同上 |
+| `formatTime(input)` | `HH:mm` | 同上 |
+| `formatRelativeTime(input)` | `刚刚` / `N 分钟前` / `N 小时前` / `N 天前`；> 30 天退化为 `YYYY-MM-DD` | 同上 |
+| `formatBy(input, template)` | 自定义 dayjs 模板 | `formatBy(ts, 'YYYY年MM月DD日')` → `2026年04月22日` |
+
+---
+
+## qs — 查询字符串
+
+```ts
+import { stringify, parse } from '@dwydev/ekit'
+import type { StringifyOptions, ParseOptions } from '@dwydev/ekit'   // 旧名 IStringifyOptions / IParseOptions 已废弃
+```
+
+```ts
+stringify({ ids: [1, 2], name: 'a' })                       // 'ids=1&ids=2&name=a'  默认 arrayFormat: 'repeat'
+stringify({ ids: [1, 2] }, { arrayFormat: 'brackets' })     // 'ids[]=1&ids[]=2'
+stringify({ a: 1 }, { addQueryPrefix: true })               // '?a=1'
+
+parse('?a=1&b=2')                                            // { a: '1', b: '2' }   默认 ignoreQueryPrefix: true
+parse('a.b=1', { allowDots: true })                          // { a: { b: '1' } }
+```
+
+### StringifyOptions / ParseOptions
+
+```ts
+interface StringifyOptions {
+  arrayFormat?: 'repeat' | 'brackets' | 'indices' | 'comma'
+  addQueryPrefix?: boolean
+  skipNulls?: boolean
+}
+interface ParseOptions {
+  ignoreQueryPrefix?: boolean
+  allowDots?: boolean
+}
+```

package/templates/claude-global/skills/dwy-ekit/references/form.md

@@ -0,0 +1,68 @@
+# 表单与脱敏（validators / masking）
+
+> 何时读这份：当用户使用本模块的 API 或问法涉及本模块功能时读取（表单校验、zod schema、vee-validate 集成、PII 数据脱敏）。
+
+## validators — 表单校验
+
+```ts
+import {
+  isPhone, isEmail, isIdCard, isUrl, isRequired, minLength, maxLength,
+  // 也可用 zod schema 配合 vee-validate
+  phoneSchema, emailSchema, idCardSchema, urlSchema,
+  requiredSchema, minLengthSchema, maxLengthSchema,
+} from '@dwydev/ekit'
+```
+
+### 布尔校验函数
+
+| 函数 | 签名 | 规则 |
+|------|------|------|
+| `isPhone(value)` | `string => boolean` | 中国手机号 1[3-9] 开头 11 位 |
+| `isEmail(value)` | `string => boolean` | 基础邮箱 |
+| `isIdCard(value)` | `string => boolean` | 18 位身份证（末位允许 X/x） |
+| `isUrl(value)` | `string => boolean` | 合法 URL |
+| `isRequired(value)` | `any => boolean` | 非空（0 / false 视为有效） |
+| `minLength(value, n)` | `(string, number) => boolean` | 最小长度 |
+| `maxLength(value, n)` | `(string, number) => boolean` | 最大长度 |
+
+### Zod schema（配合 vee-validate）
+
+```ts
+import { useForm } from 'vee-validate'
+import { toTypedSchema } from '@vee-validate/zod'
+import { z } from 'zod'
+import { phoneSchema, emailSchema } from '@dwydev/ekit'
+
+const schema = toTypedSchema(z.object({
+  phone: phoneSchema,
+  email: emailSchema,
+}))
+const { defineField, errors } = useForm({ validationSchema: schema })
+```
+
+> `minLengthSchema(n)` / `maxLengthSchema(n)` 是工厂函数，调用后返回 schema。
+
+---
+
+## masking — PII 脱敏
+
+```ts
+import {
+  maskPhone, maskEmail, maskIdCard, maskBankCard,
+  maskName, maskAddress, maskIp, maskLicensePlate, maskText,
+} from '@dwydev/ekit'
+```
+
+纯函数，无外部依赖。**输入不符合格式时原样返回，不抛异常**。
+
+| 函数 | 规则 | 示例 |
+|------|------|------|
+| `maskPhone(phone)` | 前 3 后 4 | `'138****5678'` |
+| `maskEmail(email)` | 首字符 + `***` + @域名 | `'z***@gmail.com'` |
+| `maskIdCard(id)` | 前 3 后 4（18 位） | `'420***********1234'` |
+| `maskBankCard(card)` | 前 4 后 4（13~19 位） | `'6222********1234'` |
+| `maskName(name)` | 2 字 → 姓+`*`；3+ 字 → 姓+`*`×(n-2)+末字 | `'张*'` / `'张*明'` |
+| `maskAddress(addr)` | 保留省/市/区/县/镇/旗前缀 + `****` | `'浙江省杭州市西湖区****'` |
+| `maskIp(ip)` | IPv4 末段替换 `*` | `'192.168.1.*'` |
+| `maskLicensePlate(plate)` | 前 2 后 1，中间 `***` | `'浙A***8'` |
+| `maskText(text, start=1, end=1, ch='*')` | 通用：保留首尾 N 位 | `maskText('1234567890', 2, 3)` → `'12*****890'` |