# ldesign-captcha

**Repository Path**: ldesign-v1/ldesign-captcha

## Basic Information

- **Project Name**: ldesign-captcha
- **Description**: ????,????/??/????
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-11
- **Last Updated**: 2026-09-10

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# @ldesign/captcha

行为式验证码组件库。当前仓库包含两个可发布包和一个演示站：

- `packages/core` -> `@ldesign/captcha`
- `packages/vue` -> `@ldesign/captcha-vue`
- `playground` -> 基于 Vite 的示例与文档站

本轮整理后，仓库已经形成完整的“核心运行时 + Vue 适配层 + 文档/示例站”结构，支持本地 Mock 和后端 API 双模式联调。

## 当前能力

- 13 种题型已经纳入统一示例矩阵：`slider`、`jigsaw`、`click-word`、`icon-select`、`rotate`、`smart`、`inference-puzzle`、`word-order`、`space-inference`、`idiom-click`、`icon-click`、`math-captcha`、`color-select`
- `@ldesign/builder` 负责 `core` 与 `vue` 包构建
- `playground` 直接使用 Vite 构建，避免依赖异常的 launcher 工具链阻塞演示站发布
- `core` 支持轨迹采样、国际化、音效反馈、Mock 数据、主题变量与插件式题型扩展
- `vue` 提供 `LCaptcha` / `Captcha` 组件和组合式 `useCaptcha`

## 本轮已完成的修复与优化

- 修复 `@ldesign/captcha-vue` 构建外部化错误，避免把 `@ldesign/captcha` 错误打包进 Vue 包
- 修复 `vue` 包发布元数据与真实产物不一致的问题，去掉不存在的 `dist` / `cjs` 导出并收敛为真实可用入口
- 补齐 `math-captcha` 与 `color-select` 在 `core`、`vue` 和 `playground` 的贯通支持
- 将音效反馈真正接入 `CaptchaValidator`
- 用强类型 `EventEmitter` 收紧事件系统，减少 `any` 扩散
- 对轨迹采样增加最小时间间隔与位移过滤，降低无效点采集和内存抖动
- 补齐 `packages/vue` 与 `playground` 的 TypeScript 路径映射，保证源码态 `noEmit` 校验可通过
- 重做 `playground`，把题型说明、接入代码、后端协议和后续规划集中到统一的实验室式界面

## 题型分层

### 基础交互

- `slider`: 低摩擦、适合登录注册和移动端高频入口
- `jigsaw`: 视觉参与感强，适合较高风险链路
- `rotate`: 单手交互友好，适合品牌化素材

### 语义题型

- `click-word`: 中文语义识别，适合内容与社区场景
- `icon-select`: 国际化友好，适合后台和工具型产品
- `word-order`: 词序排序，适合教育与内容产品
- `idiom-click`: 成语拼接，适合本地化中文场景
- `icon-click`: 多图标顺序点击，适合跨语言产品
- `math-captcha`: 无图依赖的轻量输入题型
- `color-select`: 轻量视觉题型，适合简洁品牌页

### 策略题型

- `smart`: 行为采样后按风险直通或降级挑战
- `inference-puzzle`: 更强调观察与关系推理的高风险题型
- `space-inference`: 同时考验路径规划与轨迹自然度

## 快速开始

### 原生 JavaScript

```ts
import { CaptchaValidator, SliderPlugin } from '@ldesign/captcha'

const captcha = new CaptchaValidator({
  container: '#captcha',
  type: 'slider',
  plugins: [SliderPlugin],
  endpoints: {
    init: '/api/captcha/ldesign/init',
    verify: '/api/captcha/ldesign/verify',
  },
  slider: {
    style: 'embed',
    text: '向右滑动完成验证',
  },
  onSuccess(token) {
    console.log('验证通过:', token)
  },
  onFailure(error) {
    console.error('验证失败:', error.message)
  },
})
```

### Vue 3

```vue
<script setup lang="ts">
import { ref } from 'vue'
import { LCaptcha } from '@ldesign/captcha-vue'
import { JigsawPlugin, SmartPlugin } from '@ldesign/captcha'

const visible = ref(true)

const handleSuccess = (token: string) => {
  console.log('验证通过:', token)
}
</script>

<template>
  <LCaptcha
    v-model:visible="visible"
    type="smart"
    mode="dialog"
    :plugins="[SmartPlugin, JigsawPlugin]"
    :smart="{ fallbackType: 'jigsaw', collectDuration: 2200 }"
    :endpoints="{
      init: '/api/captcha/ldesign/init',
      verify: '/api/captcha/ldesign/verify',
    }"
    @success="handleSuccess"
  />
</template>
```

## 核心接入约定

### 前端职责

- 渲染题型 UI
- 收集点击、拖拽、停顿、时长等交互数据
- 统一调用 `init` / `verify` 接口
- 维护重试、超时、成功、失败和状态切换

### 后端职责

- 根据题型返回对应素材与元数据
- 校验交互结果与行为轨迹
- 控制题目有效期、重试策略和风控评分
- 返回最终业务 token 或失败信息

### 推荐接口

```http
GET  /api/captcha/ldesign/init
POST /api/captcha/ldesign/verify
```

示例 `verify` 请求体：

```json
{
  "captchaId": "captcha_xxx",
  "token": "once_token_xxx",
  "type": "slider",
  "data": {
    "x": 184,
    "duration": 920,
    "trail": [{ "x": 0, "y": 0, "t": 0 }, { "x": 184, "y": 1, "t": 920 }]
  },
  "timestamp": 1710000000000,
  "sign": "sha256(...)"
}
```

## 包说明

### `@ldesign/captcha`

- 提供 `CaptchaValidator`
- 提供全部内置题型插件
- 提供 `Mock`、`track`、`sound`、`feedback`、`i18n`、`design-tokens`
- 适合原生 JavaScript、Vue、后续 React/Web Components 适配层复用

### `@ldesign/captcha-vue`

- 提供 `LCaptcha` 与 `Captcha`
- 提供 `useCaptcha`
- 透传 `core` 主要配置项和事件
- 当前以 ESM 入口为准，避免导出不存在的 `dist` / `cjs` 产物

### `playground`

- 首页展示架构、优化结果和后续路线
- 文档页展示核心 API、后端契约与构建命令
- 实验页统一承载 13 种题型的说明、代码和交互示例
- 同时支持 Mock 演示和 API 联调

## 本地开发与验证

### 校验 `packages/core`

```bash
cd packages/core
pnpm exec tsc --noEmit -p tsconfig.json
pnpm test -- --run
pnpm build
```

### 校验 `packages/vue`

```bash
cd packages/vue
pnpm exec tsc --noEmit -p tsconfig.json
pnpm test -- --run
pnpm build
```

### 校验 `playground`

```bash
cd playground
pnpm exec tsc --noEmit -p tsconfig.json
pnpm build
```

说明：

- `packages/core` 与 `packages/vue` 的 `build` 脚本通过 `@ldesign/builder` 执行
- `playground` 当前直接调用 Vite 构建脚本
- `playground/package.json` 中仍保留 `*:launcher` 备用脚本，便于后续排查工作区工具链

## 推荐继续完善的方向

- 无障碍能力：增加音频验证码、键盘交互、色弱友好提示与更完整的 ARIA 描述
- 风险评分协议：让 `smart` 模式输出标准化风险分与降级决策，而不是仅返回单一题型
- 题型编排器：允许服务端根据风险等级动态下发题型队列
- 题库管理：为语义题型增加多语种词库、难度分层和运营配置
- 更多适配层：在 Vue 稳定后扩展 React 与 Web Components

## 项目结构

```text
captcha/
├── packages/
│   ├── core/
│   │   └── src/
│   └── vue/
│       └── src/
├── playground/
│   └── src/
└── README.md
```

## License

MIT