@kc-one/smart-fill-sdk 0.0.1

package/README.md

@@ -0,0 +1,204 @@
+# Smart Fill SDK
+
+页面内智能录入 SDK，用于在业务页面嵌入「文本 / 图片识别 → 自动表单回填 → 结果反馈」能力。
+
+## 快速开始
+
+```bash
+npm install
+npm run dev
+```
+
+打开 Vite 示例页后，点击右上角「智能录入」悬浮按钮。
+
+## 接入示例
+
+```ts
+import { SmartFill } from '@kc-si/smart-fill-sdk'
+import '@kc-si/smart-fill-sdk/style.css'
+
+await SmartFill.setup({ apiKey: 'seKey_xxxxxxxxxxxxx' })
+// 网关地址在 src/config/defaults.ts 的 DEFAULT_BASE_URL 中配置
+
+const smartFill = SmartFill.create({
+  formCode: 'apply-form',
+  strictFormConfig: true
+})
+
+smartFill.registerFields([
+  {
+    fieldId: 'customerName',
+    label: '客户姓名',
+    type: 'text',
+    element: '[data-smart-fill-key="customerName"]'
+  },
+  {
+    fieldId: 'legalBankMobile',
+    label: '法人手机号',
+    type: 'text',
+    localRuleMode: 'off', // 该字段不走本地规则，仅走后端识别
+    element: '[data-smart-fill-key="legalBankMobile"]'
+  }
+])
+
+smartFill.mountFloatingButton()
+```
+
+## 核心流程
+
+```text
+SmartFill.setup({ apiKey })
+  → 校验 apiKey / 创建会话 / 获取 accessToken
+SmartFill.create({ formCode })
+  → 创建页面实例，绑定网关客户端
+smartFill.registerFields([...])   // 可选：L3 高精度字段注册
+smartFill.mountFloatingButton()   // 挂载悬浮入口 + 弹框 UI
+smartFill.open()
+  → rescan() 扫描字段，生成 scanToken
+用户输入文本 / 上传图片，点击「智能识别回填」
+  → 本地规则预识别（可开关）
+  → 后端识别网关补全
+  → 合并结果，自动回填高置信字段
+  → 返回 applied / skipped / warnings / traceId
+```
+
+## 当前实现范围
+
+| 模块 | 能力 |
+| --- | --- |
+| `SmartFill.setup` | apiKey 校验、会话初始化（网关地址见 `config/defaults.ts`） |
+| `SmartFill.create` | 实例生命周期、单活 UI 管理、SSR mock 实例 |
+| `registerFields / rescan` | 优先注册字段，兜底 DOM 扫描 |
+| `LocalRuleEngine` | 手机号、身份证、邮箱、银行卡、金额、日期、角色化键值对识别 |
+| `FieldSchema.localRuleMode` | 字段级本地规则策略：`inherit / off / only` |
+| `SmartFillPanel` | Shadow DOM 面板、本地优先识别总开关、自动回填进度和结果反馈 |
+| `DomFiller` | 原生控件回填、scanToken / fingerprint 校验、浅蓝高亮反馈 |
+| `GatewayClient` | `/sdk/session`、`/sdk/forms/:code`、`/sdk/recognize` 网关调用 |
+
+## 目录结构
+
+```text
+smart-fill-sdk/
+├─ package.json              # 包配置，exports 指向 dist/
+├─ vite.config.ts            # Vite 库模式构建 + d.ts 生成
+├─ tsconfig.json             # TypeScript 编译配置
+├─ README.md                 # 本文件
+│
+├─ examples/                 # 接入示例
+│  └─ vanilla/
+│     ├─ index.html          # 原生表单 demo 页面
+│     └─ main.ts             # setup → create → registerFields → mountFloatingButton
+│
+└─ src/                      # SDK 源码
+   ├─ index.ts                # 包入口，统一导出对外 API 与类型
+   ├─ style.css              # 回填成功高亮样式（浅蓝背景）
+   ├─ vite-env.d.ts          # CSS 模块类型声明
+   │
+   ├─ core/                  # 生命周期与实例编排
+   │  ├─ smart-fill.ts      # 全局 setup / create 入口，管理会话状态
+   │  ├─ smart-fill-instance.ts  # 页面实例：扫描、识别、自动回填、事件分发
+   │  ├─ instance-manager.ts  # 多实例 UI 互斥，同一时刻仅一个面板激活
+   │  └─ errors.ts           # 统一错误对象、traceId 生成
+   │
+   ├─ scanner/               # 字段扫描与稳定标识
+   │  ├─ dom-scanner.ts      # DOM 字段扫描、弹窗容器定位、scanToken 生成
+   │  └─ fingerprint.ts      # 字段 fingerprint 生成，过滤动态 ID
+   │
+   ├─ rules/                 # 浏览器端本地规则
+   │  └─ local-rules.ts      # 正则 + 键值对 + 角色语义识别引擎
+   │
+   ├─ config/                 # SDK 内置配置
+   │  └─ defaults.ts          # DEFAULT_BASE_URL 网关根地址（前期写死）
+   │
+   ├─ client/                 # 后端网关客户端
+   │  └─ gateway-client.ts   # session / formConfig / recognize 请求封装
+   │
+   ├─ filler/                 # 表单回填
+   │  └─ dom-filler.ts        # DOM 写入、适配器分发、scanToken 校验、高亮
+   │
+   ├─ ui/                     # 页面内 UI
+   │  └─ panel.ts             # Shadow DOM 弹框：输入、开关、识别、结果展示
+   │
+   ├─ events/                 # 事件系统
+   │  └─ event-bus.ts        # 轻量 pub/sub，驱动 ready / recognized / applied 等事件
+   │
+   ├─ adapters/               # 组件库回填适配器
+   │  └─ native.ts           # 原生 input / textarea / select 适配器
+   │
+   └─ types/                  # 对外 TypeScript 类型
+      └─ index.ts             # FieldSchema、RecognizeResult、SmartFillEventMap 等
+```
+
+### 模块职责说明
+
+#### `core/` — 生命周期
+
+- **`smart-fill.ts`**：SDK 全局单例入口。`setup()` 负责 apiKey 校验和会话初始化；`create()` 在 ready 后创建页面实例。
+- **`config/defaults.ts`**：前期写死的网关 `DEFAULT_BASE_URL`，切换环境时改此文件即可。
+- **`smart-fill-instance.ts`**：单页面实例的核心编排器。串联扫描 → 本地规则 → 网关识别 → 自动回填，并通过 EventBus 向外派发事件。
+- **`instance-manager.ts`**：保证同一时刻只有一个实例的 UI 面板处于打开状态，避免多实例互相遮挡。
+- **`errors.ts`**：统一错误码封装（`SmartFillException`）和 `traceId` 生成，供审计和排障使用。
+
+#### `scanner/` — 字段扫描
+
+- **`dom-scanner.ts`**：扫描页面可见输入控件，支持注册字段优先、平台容器、最上层弹窗/抽屉定位。每次扫描生成唯一 `scanToken`。
+- **`fingerprint.ts`**：为每个字段生成稳定指纹，过滤 React/AntD 等框架的动态 ID，用于回填前校验字段是否变化。
+
+#### `rules/` — 本地规则
+
+- **`local-rules.ts`**：浏览器端优先识别引擎。支持正则提取（手机号、身份证等）、键值对解析（`姓名：张三`）、角色语义（法人/紧急联系人/配偶）。匹配时优先角色字段，再退化到通用字段。
+
+#### `client/` — 网关
+
+- **`gateway-client.ts`**：封装后端 `/sdk/session`、`/sdk/forms/:code`、`/sdk/recognize` 三个接口，统一请求 `DEFAULT_BASE_URL`。
+
+#### `filler/` — 回填
+
+- **`dom-filler.ts`**：执行字段写入。校验 `scanToken` 和 `fingerprint` 防止误填；支持注册字段 `setValue`、适配器模式和原生 DOM 事件兜底；回填成功后添加浅蓝背景高亮，用户交互后自动消失。
+
+#### `ui/` — 界面
+
+- **`panel.ts`**：Shadow DOM 隔离的页面内弹框。包含文本输入、图片上传、本地优先识别开关、清空/识别按钮、识别结果列表和状态反馈。支持右上角悬浮 + 拖拽。
+
+#### `events/` — 事件
+
+- **`event-bus.ts`**：实例级和全局级事件总线，事件包括 `ready`、`scanCompleted`、`recognizing`、`recognized`、`applying`、`applied`、`error`。
+
+#### `adapters/` — 适配器
+
+- **`native.ts`**：原生 HTML 表单控件（input / textarea / select）的回填适配器，通过 dispatch `input/change` 事件触发框架响应。
+
+#### `types/` — 类型
+
+- **`index.ts`**：全部对外 TypeScript 类型定义，包括字段模型、识别结果、回填结果、事件映射、适配器接口等。
+
+## 本地规则开关
+
+| 层级 | 配置 | 说明 |
+| --- | --- | --- |
+| 弹框总开关 | UI「启用本地优先识别」 | 一键开启/关闭本地规则，默认开启 |
+| 字段级 | `FieldSchema.localRuleMode` | `inherit` 跟随总开关；`off` 跳过本地规则；`only` 仅本地规则、不走后端 |
+
+## 发布到 npm 公共仓库
+
+包归属 [@kc-si](https://www.npmjs.com/settings/kc-si/packages) 组织，包名为 `@kc-si/smart-fill-sdk`。
+
+```bash
+npm login                    # 使用已加入 kc-si 组织且开启 2FA 的账号
+npm run build
+npm publish --access public  # publishConfig 已配置 public + registry.npmjs.org
+```
+
+安装：
+
+```bash
+npm install @kc-si/smart-fill-sdk
+```
+
+## 构建
+
+```bash
+npm run typecheck   # 类型检查
+npm run build       # 构建 dist/（ESM + UMD + d.ts）
+npm run preview     # 预览构建产物
+```

package/dist/examples/vanilla/main.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=main.d.ts.map

package/dist/examples/vanilla/main.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../../../examples/vanilla/main.ts"],"names":[],"mappings":""}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export * from './src/index'
+export {}