145 lines
6.3 KiB
Markdown
145 lines
6.3 KiB
Markdown
# CRM 客户开票信息 · 粘贴快速识别 · 设计说明
|
||
|
||
> Demo：`docs/demo-crm-invoice-paste-recognize.html`（方案 A）
|
||
> 日期：2026-08-20
|
||
> 状态：已实现（待联调验收）
|
||
|
||
## 1. 背景与目标
|
||
|
||
客户管理详情弹窗右侧「开票信息」新增/编辑时，业务常从微信/邮件粘贴整段「开票资料」文本，再手工逐项填入，效率低且易错。
|
||
|
||
**目标：** 在新增/编辑弹窗顶部提供「粘贴识别」区，用**纯前端规则**解析常见开票资料文本，并将结果填入对应表单字段；用户可再微调后保存。不依赖后端、不调用大模型。
|
||
|
||
**非目标：**
|
||
|
||
- 不新增数据库字段（银行行号、邮编、邮寄地址等仍无独立列）
|
||
- 不接阿里云 / OCR / 大模型
|
||
- 不改开票信息保存 API 与权限
|
||
|
||
## 2. 已确认决策
|
||
|
||
| 项 | 结论 |
|
||
|---|---|
|
||
| 入口布局 | 方案 A：新增/编辑弹窗表单顶部「粘贴识别」区 |
|
||
| 识别方式 | 纯前端规则（标签别名 + 行解析），零成本、离线 |
|
||
| 回填策略 | **识别后覆盖对应字段**（已有值一并覆盖） |
|
||
| 无表单字段的信息 | 写入 `remark`（银行行号、邮编、发票邮寄信息等） |
|
||
| 备注合并 | 识别产生的备注内容**追加到 remark 末尾**；若与已有内容重复则不重复追加 |
|
||
| 范围 | 仅 `web-admin` 客户详情 → `InvoiceInfo.vue`；**以及**客户新增弹窗 `CustomerFormDialog.vue` 底部开票信息（二级粘贴弹窗） |
|
||
|
||
## 3. 交互设计
|
||
|
||
组件：`web-admin/src/views/crm/customer/components/InvoiceInfo.vue`
|
||
|
||
在现有 `el-form` 顶部、`.form-grid-2` 字段区之前增加粘贴区：
|
||
|
||
```
|
||
el-dialog「添加/修改开票信息」
|
||
└─ el-form
|
||
├─ 粘贴识别面板（虚线边框 + primary-bg）
|
||
│ ├─ 标题「粘贴识别」+ 简短提示
|
||
│ ├─ el-input type=textarea（粘贴原文）
|
||
│ ├─ [清空] [识别并填入]
|
||
│ └─ 结果提示文案（成功/部分成功/失败）
|
||
└─ 原有字段栅格（单位名称、税号…）
|
||
```
|
||
|
||
行为：
|
||
|
||
1. 打开新增/编辑弹窗时，粘贴区默认**空**（不强制预填样例，避免误覆盖业务数据）。
|
||
2. 点击「识别并填入」→ 调用解析工具 → **覆盖**已映射字段；未映射信息写入/追加 `remark`。
|
||
3. 点击「清空」仅清空粘贴框与提示，**不**清空表单字段。
|
||
4. 关闭弹窗时重置粘贴区与表单（沿用现有 `reset`）。
|
||
5. 识别失败或零字段：`ElMessage.warning`，不改表单。
|
||
6. 部分成功：照常覆盖已识别字段，并用消息列出未识别的关键项（如缺单位名称）。
|
||
|
||
视觉对齐 Fresh Mint：主色 `#10b981` / `#059669` / `#ecfdf5`；按钮带图标（DocumentCopy / Delete / Close / Check 等既有习惯）。
|
||
|
||
## 4. 解析规则
|
||
|
||
新增工具：`web-admin/src/utils/crm-invoice-paste-recognize.ts`
|
||
|
||
参考既有模式：`web-admin/src/utils/pl-paste-recognize.ts`（纯函数、导出样例常量、返回 `warnings`）。
|
||
|
||
### 4.1 输入输出
|
||
|
||
```ts
|
||
interface CrmInvoicePasteResult {
|
||
companyName?: string
|
||
taxNo?: string
|
||
companyAddress?: string
|
||
legalRepresentative?: string
|
||
agent?: string
|
||
phoneFax?: string
|
||
bankName?: string
|
||
bankAccount?: string
|
||
/** 无独立字段的附加信息，供写入 remark */
|
||
remarkParts: string[]
|
||
warnings: string[]
|
||
/** 成功写入表单的字段数（不含 remarkParts） */
|
||
filledCount: number
|
||
}
|
||
```
|
||
|
||
### 4.2 标签别名 → 字段
|
||
|
||
| 字段 | 标签别名（行首，支持全/半角冒号、标签内空格） |
|
||
|---|---|
|
||
| companyName | 公司名称、单位名称、单位名、名称 |
|
||
| taxNo | 纳税人识别号、纳税识别号、统一社会信用代码、税号 |
|
||
| companyAddress | 单位地址、地址（见 4.3 邮寄段排除） |
|
||
| phoneFax | 电话/传真、电话传真、传真、电话 |
|
||
| bankName | 银行开户行、开户银行、开户行 |
|
||
| bankAccount | 银行账号、账号、帐号（去除内部空格） |
|
||
| legalRepresentative | 法定代表人、法人代表、法人 |
|
||
| agent | 代理人、委托代理人 |
|
||
|
||
「地址及电话」单独规则：整行取值后，若末尾匹配固话/手机则拆到 `phoneFax`，其余为 `companyAddress`。
|
||
|
||
### 4.3 段落与冲突
|
||
|
||
- 若存在「发票邮寄地址」标题，其后块内的「姓名 / 电话 / 地址」**不**写入 `companyName` / `phoneFax` / `companyAddress`，而是汇总进 `remarkParts`（如 `邮寄：汪璇 / 188… / 地址…`）。
|
||
- 「开票资料」等总标题行忽略。
|
||
- 银行行号 / 联行号 / 行号 → `remarkParts`：`银行行号：…`（去空格）。
|
||
- 邮编 → `remarkParts`：`邮编：…`。
|
||
|
||
### 4.4 验收样例（必须通过）
|
||
|
||
**样例 1（安庆山峡）：** 公司名称、税号、开户行、帐号、地址、电话/传真正确回填；银行行号、邮编、邮寄信息进 remark。
|
||
|
||
**样例 2（江峰生物）：** 单位名、税号、地址及电话拆分、开户行、带空格账号去空格、电话正确；银行行号进 remark。
|
||
|
||
单测：`web-admin/src/utils/crm-invoice-paste-recognize.test.ts`（与现有 vitest 风格一致，如 `pl-cert-slots.test.ts`）。
|
||
|
||
## 5. 数据流
|
||
|
||
```
|
||
用户粘贴文本
|
||
→ parseCrmInvoicePaste(text)
|
||
→ 覆盖 form 对应键（仅当解析值非空）
|
||
→ remark：将 remarkParts 用「；」拼接后追加到现有 remark
|
||
→ ElMessage 提示 filledCount / warnings
|
||
→ 用户点确定 → 现有 /web/crm/invoice-info/add|update（不变）
|
||
```
|
||
|
||
覆盖规则细节：某字段解析值为空字符串时，**不**清空该表单字段（只覆盖「识别到了」的字段）。
|
||
|
||
## 6. 风险与后续
|
||
|
||
| 风险 | 应对 |
|
||
|---|---|
|
||
| 新标签写法未覆盖 | 补别名；UI 提示可手动改 |
|
||
| 无标签散文文本 | 识别失败，手动填写 |
|
||
| 长期需行号等独立字段 | 另开变更加列；本设计不扩表 |
|
||
|
||
可选后续（本变更不做）：规则失败时降级调大模型。
|
||
|
||
## 7. 实现清单（实现阶段）
|
||
|
||
1. 新增 `crm-invoice-paste-recognize.ts` + 单测（含两段业务样例）
|
||
2. 改 `InvoiceInfo.vue`：顶部粘贴区 + 识别回填
|
||
3. 保留/更新 Demo：`docs/demo-crm-invoice-paste-recognize.html`（与线上规则一致即可）
|
||
4. 更新 graphify（web-admin）
|
||
|
||
不改 backend、不改 SQL、不改 OpenSpec 基线（纯前端体验增强）。
|