create-dwy 0.7.1 → 0.9.0

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

@@ -1,135 +0,0 @@
-# 数据与查询字符串（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

@@ -1,68 +0,0 @@
-# 表单与脱敏（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'` |

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

@@ -1,183 +0,0 @@
-# request — HTTP 客户端（防腐层）
-
-> 何时读这份：当用户使用本模块的 API 或问法涉及本模块功能时读取（HTTP 请求、createRequest、内置插件、refreshToken、dwyeapi 响应契约对接、业务错误捕获）。
-
-```ts
-import {
-  createRequest, tokenPlugin, headerPlugin, unwrapPlugin, refreshTokenPlugin,
-  SUCCESS_CODE, extractValidationErrors, isApiBusinessError,
-} from '@dwydev/ekit'
-import type {
-  HttpClient, HttpConfig, HttpResponse, HttpError, HttpPlugin,
-  HttpMethod, HttpResponseType, CreateRequestOptions,
-  ApiResponse, PageData, ValidationErrorData, ValidationFieldError,
-  CommonBusinessCode, BusinessCode, ApiBusinessError,
-} from '@dwydev/ekit'
-```
-
-## createRequest(options?) → HttpClient
-
-底层是 axios，但**返回 `HttpClient` 而不是 `AxiosInstance`**。
-
-```ts
-const http: HttpClient = createRequest({
-  baseURL: '/api',                       // 默认 '/api'
-  timeout: 30000,                        // 默认 30000
-  headers: { 'X-Client': 'web' },        // 共享默认请求头
-  plugins: [
-    tokenPlugin({ getToken: () => localStorage.getItem('token') }),
-    unwrapPlugin(),
-  ],
-})
-
-// HttpClient 接口
-const res = await http.get<User>('/users/1')           // res: HttpResponse<User>
-const res = await http.post<User>('/users', { ... })
-const res = await http.request({ method: 'PUT', url: '/users/1', data })
-// 还有 put / delete / patch / head
-```
-
-## HttpConfig / HttpResponse / HttpError
-
-```ts
-interface HttpConfig {
-  url?: string
-  method?: HttpMethod                     // 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH' | 'HEAD' | 'OPTIONS'
-  baseURL?: string
-  headers?: Record<string, string>
-  params?: Record<string, any>
-  data?: any
-  timeout?: number
-  responseType?: HttpResponseType         // 'json' | 'blob' | 'text' | 'arraybuffer'
-  extra?: Record<string, unknown>         // 逃生舱：透传 axios 特有配置
-}
-
-interface HttpResponse<T = any> {
-  data: T
-  status: number
-  statusText: string
-  headers: Record<string, string>
-  config: HttpConfig
-}
-
-interface HttpError<T = any> extends Error {
-  config?: HttpConfig
-  response?: HttpResponse<T>
-  code?: string
-  businessCode?: string                  // v0.7.0 新增：后端业务错误码（如 "NOT_FOUND"）
-  apiResponse?: ApiResponse<unknown>     // v0.7.0 新增：原始 dwyeapi 响应信封
-}
-```
-
-## HttpPlugin 接口
-
-```ts
-interface HttpPlugin {
-  onRequest?: (config: HttpConfig) => HttpConfig | Promise<HttpConfig>
-  onResponse?: (response: HttpResponse) => HttpResponse | Promise<HttpResponse>
-  // 返回非 undefined 视为已恢复，终止后续插件
-  onResponseError?: (error: HttpError) => any
-}
-```
-
-> 旧版的 `RequestPlugin` 已重命名为 `HttpPlugin`，所有钩子参数类型从 axios 类型改为 ekit 自有契约。
-
-## 内置插件
-
-| 插件 | 用途 | 参数 |
-|------|------|------|
-| `tokenPlugin` | 注入 `Authorization: Bearer <token>` | `{ getToken: () => string \| null }` |
-| `headerPlugin` | 注入自定义动态 header | `{ name: string, getValue: () => string \| null }` |
-| `unwrapPlugin` | 解包 dwyeapi `{ code, message, data, timestamp }`，code !== `"SUCCESS"` 时 reject（附带 `businessCode` / `apiResponse`）；非该格式原样透传 | 无 |
-| `refreshTokenPlugin` | 401 自动刷新并重放 | 见下 |
-
-## refreshTokenPlugin（带 retry 注入）
-
-新版需要传 `retry`，因为插件不再持有 client 引用：
-
-```ts
-let http: HttpClient
-http = createRequest({
-  plugins: [
-    tokenPlugin({ getToken: () => localStorage.getItem('token') }),
-    refreshTokenPlugin({
-      getRefreshToken: () => localStorage.getItem('refreshToken'),
-      refreshFn: async (refreshToken) => {
-        const res = await http.post<{ token: string }>('/auth/refresh', { refreshToken })
-        localStorage.setItem('token', res.data.token)
-        return res.data.token
-      },
-      onRefreshFail: () => {
-        localStorage.clear()
-        window.location.href = '/login'
-      },
-      retry: (cfg) => http.request(cfg),       // 必填：重放请求
-      isLoginUrl: (url) => url.includes('/auth/login'),  // 可选
-    }),
-    unwrapPlugin(),
-  ],
-})
-```
-
-## 响应契约对齐 dwyeapi v0.7.0
-
-所有接口统一信封 `{ code, message, data, timestamp }`，`code === "SUCCESS"` 表示业务成功。unwrapPlugin 自动按此契约解包，业务代码拿到的 `response.data` 就是纯业务数据或 `PageData<T>`。
-
-```ts
-import { SUCCESS_CODE } from '@dwydev/ekit'
-import type { ApiResponse, PageData } from '@dwydev/ekit'
-
-// 单体响应
-const res = await http.get<User>('/users/1')
-// res.data: User（unwrap 后是 User 不是 ApiResponse<User>）
-
-// 分页响应
-const list = await http.get<PageData<User>>('/users?page=1&page_size=20')
-list.data.items          // User[]
-list.data.total          // number
-list.data.page           // number
-list.data.page_size      // number（保持 snake_case 对齐后端 JSON）
-```
-
-**内置业务错误码（`CommonBusinessCode`）：**
-
-| code | HTTP | 含义 |
-|------|------|------|
-| `SUCCESS` | 200 | 业务成功，unwrap 自动解包 data |
-| `NOT_FOUND` | 404 | 资源不存在 |
-| `BUSINESS_ERROR` | 422 | 业务规则不允许（基础码；业务常自定义为 `INSUFFICIENT_BALANCE` 等） |
-| `PERMISSION_DENIED` | 403 | 无权限 |
-| `AUTHENTICATION_FAILED` | 401 | 认证失败 |
-| `VALIDATION_ERROR` | 422 | 请求参数校验失败，`data.errors` 为字段错误数组 |
-| `INTERNAL_ERROR` | 500 | 服务器错误 |
-| `HTTP_{status_code}` | 原状态 | 第三方 HTTPException 透传（如 OAuth2 的 `HTTP_401`） |
-
-`BusinessCode = CommonBusinessCode | (string & {})`：既自动补全常见码，又允许业务 `BusinessError(code="CUSTOM")` 自定义。
-
-## 捕获业务错误：isApiBusinessError + extractValidationErrors
-
-unwrapPlugin 失败时抛 `HttpError`，附带 `businessCode`（业务错误码）和 `apiResponse`（原始信封）。业务 catch 直接按 code 分支：
-
-```ts
-import { isApiBusinessError, extractValidationErrors } from '@dwydev/ekit'
-
-try {
-  await http.post('/orders', body)
-} catch (err) {
-  if (!isApiBusinessError(err)) {
-    message.error('网络异常')
-    return
-  }
-  switch (err.businessCode) {
-    case 'INSUFFICIENT_BALANCE': showRecharge(); break
-    case 'NOT_FOUND': message.warning('订单不存在'); break
-    case 'VALIDATION_ERROR':
-      // err.apiResponse.data.errors: [{ field: "body.email", message: "..." }, ...]
-      form.setErrors(extractValidationErrors(err))
-      break
-    default: message.error(err.message)
-  }
-}
-```
-
-`extractValidationErrors` 自动剥离 `body. / query. / path. / header. / cookie.` 前缀，返回 `{ field: message }` 扁平对象，与 vee-validate 的 `form.setErrors` 直接兼容。嵌套字段路径（如 `body.items.0.name`）保留为 `items.0.name`。输入可以是 HttpError、完整 ApiResponse、或裸 `ValidationErrorData`，非校验错误时返回空对象。

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

@@ -1,109 +0,0 @@
-# UI 交互（copy / file / hooks）
-
-> 何时读这份：当用户使用本模块的 API 或问法涉及本模块功能时读取（剪贴板、文件下载/Blob/文件大小、Vue Composables 工具）。
-
-## copy — 剪贴板
-
-```ts
-import { copyText, useClipboard } from '@dwydev/ekit'
-```
-
-### copyText(text)
-
-非组件场景一次性复制：
-
-```ts
-await copyText('hello')
-```
-
-### useClipboard — 直接再导出 @vueuse/core
-
-```ts
-const { text, copy, copied, isSupported } = useClipboard({ source: '', copiedDuring: 1500 })
-copy('hello')
-// copied: ComputedRef<boolean>，1500ms 后自动复位
-// isSupported: ComputedRef<boolean>，注意是 computed 不是 ref
-```
-
-> 旧版 ekit 自写的 `useClipboard` 返回结构略有不同，迁移时需对照新签名。
-
----
-
-## file — 文件下载 / Blob / 文件大小
-
-```ts
-import { downloadFile, saveBlob, formatFileSize } from '@dwydev/ekit'
-import type { DownloadOptions, FileRequester } from '@dwydev/ekit'   // requester 不是 requestInstance
-```
-
-### downloadFile(url, options?)
-
-```ts
-await downloadFile('/api/export.xlsx')                                // GET，自动从 Content-Disposition 解析文件名
-await downloadFile('/api/export', {
-  filename: '报表.xlsx',
-  method: 'POST',
-  data: { dateRange: [start, end] },
-  headers: { Authorization: `Bearer ${token}` },
-})
-
-// 用自己的 HTTP 客户端发请求（不传则动态 import axios）
-await downloadFile('/api/export', { requester: myAxiosInstance })
-```
-
-### FileRequester 契约
-
-任何满足以下结构的对象都可以作为 requester（axios 实例天然满足）：
-
-```ts
-interface FileRequester {
-  request(config: {
-    url: string
-    method?: 'GET' | 'POST'
-    data?: any
-    headers?: Record<string, string>
-    responseType: 'blob'
-  }): Promise<{
-    data: Blob | ArrayBuffer
-    headers?: Record<string, string | undefined>
-  }>
-}
-```
-
-> 旧版字段 `requestInstance: AxiosInstance` 已改名 `requester: FileRequester`，类型不再泄露 axios。
-
-### 其他
-
-```ts
-saveBlob(blob, 'data.json')               // 直接保存已有 Blob
-formatFileSize(1234567)                    // '1.18 MB'
-formatFileSize(1234567, 0)                 // '1 MB'
-```
-
----
-
-## hooks — Vue Composables
-
-**全部再导出 `@vueuse/core`**，ekit 不再自写。从 `@dwydev/ekit` 主入口导入即可：
-
-```ts
-import {
-  // src/hooks/index.ts
-  useDebounce, useClickOutside, useEventListener,
-  // src/hooks/vueuse.ts
-  useThrottle, useWindowSize, useMediaQuery, useIntersectionObserver, useResizeObserver,
-} from '@dwydev/ekit'
-```
-
-| ekit 名 | VueUse 实现 | 说明 |
-|---------|-------------|------|
-| `useDebounce(value, delay=300)` | `refDebounced` | 默认 300ms（VueUse 默认 200ms） |
-| `useClickOutside(target, handler)` | `onClickOutside` | 点击元素外部触发 |
-| `useEventListener(target, event, handler, options?)` | 同名 | 自动绑/解绑，支持 `Ref<EventTarget>` |
-| `useThrottle(fn, ms)` | `useThrottleFn` | 节流函数 |
-| `useWindowSize()` | 同名 | `{ width, height }` |
-| `useMediaQuery(query)` | 同名 | `useMediaQuery('(max-width: 768px)')` |
-| `useIntersectionObserver(target, cb)` | 同名 | 监听元素出现/消失 |
-| `useResizeObserver(target, cb)` | 同名 | 监听元素尺寸变化 |
-
-> 旧版 ekit 自写的 `useDebounce` 返回普通 `Ref<T>`，新版返回 VueUse 的 `Readonly<Ref<T>>`，**不能** `debouncedSearch.value = '...'`。