# PRD：工商信息配置（美亚风鸟 Key 池） | 项 | 内容 | |----|------| | 产品 | AI 超级销售 CRM | | 模块 | 设置中心 › 系统设置 › **工商信息配置**；客户详情 › **查询工商信息**（额度用尽提示） | | 版本 | **V1.4（对齐 v2.2.55 原型）** | | 状态 | 评审稿 | | 日期 | 2026-10-21 | | 原型 | `工商信息优化/v2.2.55 工商信息-美亚风鸟.html` | | 配套文档 | [飞书 · 风鸟 API Key 获取说明](https://bcn7no1n8jpa.feishu.cn/wiki/LmOowOttYiodT2k0Ei3cKME3nKe?from=from_copylink)（销售侧图文指引） | > **一句话：** 管理员统一维护全公司美亚风鸟 API Key 池（手填、掩码展示）；销售申请 Key 后交给管理员；查询时服务端按列表轮换可用 Key；全部额度用尽时在详情页 **顶部弹出全局 Message**。企查查原样保留作历史兼容。 --- ## 文档变更记录 | 文档版本 | 日期 | 变更摘要 | |---------|------|----------| | V1.4 | 2026-10-21 | API Key 格式校验 **仅校验不含空白字符**（空格、Tab、换行等）；**取消** 8～128 位长度限制与输入 `maxlength`；不校验 `fn_sk_` 等前缀；风鸟 **备注** 改为 **明文输入**（无掩码、无眼睛） | | V1.3 | 2026-10-20 | **获取说明** 跳转改为飞书 wiki（见 §4.3）；额度用尽由顶栏通栏条改为 **顶部居中全局 Message**（可 × 关闭，§5.6）；固定提示文案精简；验收标准与原型右侧标注说明同步 | | V1.2 | 2026-10-19 | 完整对齐原型：API Key / 备注 / 企查查 Key·SecretKey **默认掩码 + 眼睛切换明文**；多行保存时空行、仅备注行改为 **行内红字**；新增原型页「客户详情-工商查询」及额度用尽提示（V1.3 起改为顶部 Message） | | V1.1 | 2026-10-19 | API Key 不再校验 `fn_sk_` 前缀；改为 **8～128 位、不含空格** | | V1.0 | 2026-10-19 | 首版：美亚风鸟多 Key 手填；去掉批量导入与配置页「今日调用」 | > 原型内「修改记录」中曾规划过批量导入、列表「今日调用」。**以当前 HTML 可交互原型为准**：这两项本期不做。上手指南若仍写「批量导入」，以实现/PRD 为准。 --- ## 1. 背景与目标 ### 1.1 背景 工商信息查询依赖第三方数据服务。现有企查查为单 Key + SecretKey，额度与可用性受单账号限制。本期接入 **美亚风鸟（riskbird.com）**，把多名销售在风鸟侧申请的 API Key 汇入公司级 Key 池，查询时由服务端轮换调用，提升成功率和单日可用额度。 ### 1.2 痛点 | 痛点 | 表现 | |------|------| | 单 Key 额度不够 | 全公司共用一个数据源账号时，白天容易打满日上限，后续查询失败 | | Key 失效无兜底 | 当前 Key 过期 / 调用失败时没有自动切换，业务侧直接查不到工商 | | 额度用尽无说明 | 池内 Key 全部打满后，销售不知道是额度问题还是系统故障 | | 销售不该进系统配置 | Key 属于公司级资源，不应让每位销售登录「系统设置」自行粘贴 | | Key 明文暴露 | 配置页若始终明文，截图 / 旁窥容易泄露 | | 历史平台仍在用 | 部分环境仍走企查查，不能直接砍掉旧配置 | ### 1.3 本期目标 | # | 目标 | |---|------| | 1 | 在「系统设置 › 工商信息配置」接入 **美亚风鸟**，默认选中该平台 | | 2 | 支持 **多 API Key 手填维护**（添加一行 / 粘贴 / 删除），保存后全公司共用 | | 3 | 列表回显 Key **状态**（正常 / 失效 / 额度已满等），供管理员判断是否可用 | | 4 | 业务查询时由 **服务端按列表顺序轮询**，自动跳过不可用 Key，失败则试下一个 | | 5 | **企查查** 单 Key + SecretKey 原样保留，切换平台即展示对应表单 | | 6 | 敏感输入 **默认掩码**，右侧眼睛切换明文（风鸟 **API Key**；企查查 Key / SecretKey）；风鸟 **备注** 为普通明文输入 | | 7 | 配置页提供「获取说明」链至 **飞书 wiki** 销售指引；销售 **不登录本配置页** | | 8 | 风鸟 Key 池 **全部额度用尽（或均不可用）** 时，详情页 **顶部弹出全局 Message**，不弹出工商结果 | ### 1.4 非目标（本期不做） - 销售自助在本页配置 / 查看 Key - 批量导入 API Key（Excel / 模板下载） - 配置页展示单 Key「今日调用」次数 - 配置页手动改状态、手动重置额度 - 风鸟 SecretKey（风鸟仅需 API Key） - 工商查询结果区的字段改版、映射、计费对账（沿用现有查询能力；本期只补选 Key 逻辑与额度用尽提示） - 侧边栏其他 CRM 菜单、系统设置其他子 Tab 的配置项 --- ## 2. 产品决策（已冻结） | 决策 | 结论 | |------|------| | 配置入口 | 设置中心 › 系统设置 › **工商信息配置** | | 权限 | **仅管理层**可进入并维护全公司 Key 池 | | 销售职责 | 在风鸟注册并生成 Key，把 Key + 姓名/手机号交给管理员；**不登录本页** | | 默认平台 | **美亚风鸟** | | 企查查 | 历史兼容：单 **Key + SecretKey**，交互原样保留 | | Key 录入方式 | **手填 / 粘贴**；工具栏仅「添加一行」 | | 批量导入 | **不做** | | API Key | **必填**；完整 Key 字符串，**不含任何空白字符**（不校验长度、不校验 `fn_sk_` 等前缀） | | 备注 | **选填**，最多 **30** 字；表头 **无** 必填星号 | | 掩码 | 风鸟 **API Key**、企查查 Key / SecretKey **默认 password 掩码**，右侧眼睛切换明文 / 隐藏；风鸟 **备注** 为 `type=text` 明文，**无** 眼睛 | | 状态 | **只读**，由查询侧 / 风鸟回显，**不是保存项** | | 空行保存 | **多行时不允许完全空行**：须填写 API Key 或删除该行；仅填备注未填 Key 同样拦截 | | 删除 | 二次确认；确认后仅从页面去掉，**需再点「保存」才生效** | | 轮询时机 | 用户发起工商查询时，由 **服务端** 选 Key，配置页不发起轮询 | | 轮询顺序 | 按当前已保存列表 **从上到下**（1→2→3→再回到 1） | | 跳过规则 | 状态非「正常」，或额度已满的 Key **不参与本轮** | | 失败切换 | 当前 Key 调用失败 / 过期时，自动尝试下一个可用 Key | | 全部额度用尽 | 详情页 **顶部居中全局 Message**（可关闭），固定文案见 §5.6；**不**弹出工商结果 | | 日调用计数（后端） | 按 **Key 字符串 + 自然日** 累计；删后重加同一 Key，当天次数 **接续、不从 0 重计** | | 配置页次数展示 | **不展示**「今日调用」 | --- ## 3. 角色与权限 | 角色 | 职责 | 能否进配置页 | |------|------|------------| | **管理层 / 管理员** | 维护平台选择与 Key 池；保存配置 | 能 | | **销售 / 跟进人** | 在风鸟申请 Key 交给管理员；在详情页点「查询工商信息」 | **不能**进配置页；能查工商 | | **CRM 服务端** | 保存 Key 池；查询时选 Key、轮询、回写状态与日调用计数 | — | | **美亚风鸟** | 提供 API Key 申请与工商查询接口 | — | **权限要点** - 配置页为公司级，Key 池全公司共用，不按部门拆分。 - 无配置权限：隐藏「工商信息配置」入口，不做「暂无权限」后再展示表单。 - 销售只通过企微 / 邮件等线下通道交 Key，不在 CRM 内自助提交。 - 「查询工商信息」沿用现网详情页权限；额度用尽提示对有查询入口的用户可见。 --- ## 4. 入口与页面结构 ### 4.1 配置页导航 | 位置 | 说明 | |------|------| | 一级菜单 | 设置中心 | | 二级菜单 | 系统设置 | | 页面 Tab | 系统设置 | | 子 Tab | 短信设置、归属地配置、**工商信息配置**、飞鱼应用配置、抖音来客配置、腾讯广告配置、外呼系统配置、语音转写配置 | 本期配置能力仅 **「工商信息配置」**。其余子 Tab 保持原有能力或占位「暂无配置项」。 页面底部 **「保存」** 仅在「工商信息配置」子 Tab 展示。 ### 4.2 配置页布局（美亚风鸟） 自上而下： 1. **平台**：单选「企查查 / 美亚风鸟」 2. **Key 区** - 一行提示文案 +「获取说明」链接 - 工具栏：右对齐「添加一行」 - 表格：API Key / 备注 / 状态 / 操作 - 表格下方的汇总错误（默认隐藏）；行内错误挂在对应输入框下方 3. **页脚**：居中主按钮「保存」 ### 4.3 「获取说明」 | 项 | 说明 | |----|------| | 提示文案 | 「手填或粘贴风鸟 API Key，可点击「添加一行」维护多条。」 | | 链接文案 | **获取说明** | | 打开方式 | **新标签页**打开飞书 wiki：[风鸟 API Key 获取说明](https://bcn7no1n8jpa.feishu.cn/wiki/LmOowOttYiodT2k0Ei3cKME3nKe?from=from_copylink)（生产环境可映射到帮助中心，**URL 与配置页一致**） | | 固定 URL | `https://bcn7no1n8jpa.feishu.cn/wiki/LmOowOttYiodT2k0Ei3cKME3nKe?from=from_copylink` | | 指南受众 | **销售**（注册风鸟、生成 Key、复制明文、交给管理员） | | 官网 | https://www.riskbird.com/（与获取说明分离，仅作风鸟登录入口） | 管理员侧操作要点： 1. 销售在风鸟注册 → 创建 API Key（每账号 1 个，完整 Key **仅首次展示**） 2. 把 API Key 与可选备注（手机号、姓名）交给管理员 3. 管理员在本页「添加一行」手填或粘贴，备注选填（最多 30 字） 4. 点「保存」生效；查询时由服务端轮换使用各 Key ### 4.4 查询演示页（原型） 原型目录 **「原型页面 › 客户详情-工商查询」** 用于演示额度用尽时的 **顶部全局 Message**（点击「查询工商信息」触发），不是独立业务模块。生产落在现网 **客户 / 线索 / 商机等详情** 中已有的「查询工商信息」入口上，规则见 §5.6。 --- ## 5. 功能说明 ### 5.1 平台切换 | 项 | 规则 | |----|------| | 控件 | 单选：企查查、美亚风鸟 | | 默认 | **美亚风鸟** | | 切换 | 立即切换表单，不自动保存 | | 未保存切换 | 页面内已编辑内容按平台分别暂存在当前会话；点「保存」只提交 **当前选中平台** 的配置 | | 生效平台 | 全公司工商查询只走 **当前已保存的平台**；保存风鸟后查询不再走企查查，反之亦然 | **美亚风鸟表单** - 无 SecretKey - 多 Key 表格 **企查查表单（原样保留 + 掩码）** | 字段 | 必填 | 说明 | |------|------|------| | Key | 是 | 单行；默认掩码，右侧眼睛切换明文 | | SecretKey | 是 | 单行；默认掩码，右侧眼睛切换明文 | 企查查保存校验：Key、SecretKey 均非空。失败 Toast「请完善配置」。 ### 5.2 风鸟 Key 列表 #### 5.2.1 字段 | 字段 | 可编辑 | 必填 | 规则 | |------|--------|------|------| | API Key | 是 | 是 | 手填 / 粘贴完整 Key；等宽字体；关闭自动填充与拼写检查；**不设** 前端长度上限；**默认掩码 + 眼睛** | | 备注 | 是 | 否 | 最多 30 字；超长截断；建议填来源账号 / 负责人 / 手机号；**明文** `type=text`，无眼睛 | | 状态 | 否 | — | 只读标签，见 §5.3 | | 操作 | — | — | 「删除」文字按钮（红色） | 表头：API Key 前带红色 `*`；备注、状态、操作 **不带** 星号。 占位符： - API Key：`请粘贴 API Key` - 备注：`选填，最多30字` #### 5.2.2 掩码与眼睛 适用于：风鸟 **API Key**、企查查 **Key**、企查查 **SecretKey**。 风鸟 **备注** 不适用本节：普通文本框明文展示，**不提供** 眼睛图标。 | 项 | 规则 | |----|------| | 默认 | `type=password`，内容以掩码圆点展示 | | 控件 | 输入框右侧眼睛图标 | | 点击眼睛 | 掩码 ⇄ 明文；图标在「显示明文 / 隐藏」间切换 | | 无障碍 | `aria-label` / `title` 与当前状态一致（显示明文 / 隐藏） | | 重新渲染 | 添加一行、切换平台、重新进入页面后，**重新回到掩码**（不记住本次明文态） | | 存储 / 日志 | 传输 HTTPS；服务端加密存储；日志禁止打印完整 Key | #### 5.2.3 格式校验（API Key） | 规则 | 说明 | |------|------| | 非空 | 去首尾空白后 **至少 1 个字符**（否则视为未填写，走必填 / 空行逻辑） | | 空白 | 字符串 **不含任何空白字符**（空格、Tab、换行等）；首尾空白亦不允许 | | 长度 | **不校验** 最小 / 最大长度；前端 **不设** `maxlength` | | 前缀 | **不校验** `fn_sk_` 或其它固定前缀；按风鸟返回的完整字符串保存 | ``` 去首尾后非空 且 全串不含空白 → 合法 ``` | 时机 | 行为 | |------|------| | 输入过程中 | 已填写但含空白 → 该输入框标红；该行行内错误随输入清空 | | 点击保存 | 见 §5.4 | #### 5.2.4 添加一行 - 工具栏仅 **「添加一行」**，不提供导入。 - 点击后表格底部新增空行：Key 空、备注空；状态在 Key 为空时展示「—」。 - 列表为空时自动补一行空行，避免无录入入口。 #### 5.2.5 删除 | 项 | 规则 | |----|------| | 展示条件 | 行数 > 1，**或** 当前行已填写 Key / 备注；仅剩一行且完全空白时 **不展示** 删除 | | 确认弹窗标题 | 删除确认 | | 确认文案 | 确定删除该 API Key 吗？删除后需点击保存才会生效。 | | 按钮 | 取消 / 删除（主按钮） | | 关闭方式 | 取消、右上角 ×、点遮罩 | | 确认后 | 立即从当前页面列表移除；**尚未写入后端** | | 保存 | 用户必须再点「保存」，删除才对查询生效 | | 删光后 | 自动补一行空行 | ### 5.3 状态（只读回显） 状态由服务端根据风鸟调用结果回写，配置页不可改。 | 内部值 | 展示 | 样式 | 何时出现 | |--------|------|------|----------| | （Key 为空） | — | 灰色 | 空行 | | `pending` | 待同步 | 灰色 | 已填 Key 但尚未被查询侧校验 / 调用 | | `ok` | 正常 | 绿色 | 可用，参与轮询 | | `limit` | 额度已满 | 黄色 | 当日额度用尽，本轮跳过 | | `invalid` | 失效 | 红色 | Key 无效 / 过期 / 被风鸟拒绝，本轮跳过 | **说明** - 状态 **不是保存项**：保存只提交平台、API Key、备注。 - 新录入 Key 保存成功后，在首次真实查询或服务端探活完成前，展示「待同步」。 - 「额度已满」按自然日恢复为「正常」的时机由服务端 / 风鸟额度规则决定；配置页只读展示最新回写值。 ### 5.4 保存 **触发：** 页脚「保存」 保存前先清空上次行内错误，再按下列顺序校验（风鸟）。**失败一律 Toast「请完善配置」**，不提交。 **① 一条合法 Key 都没有** - 表格下方红字：**请至少填写 1 个 API Key** - 完全空行：该行 API Key 下红字 **请填写 API Key**，输入框标红 - 已填写但不合法的行：该行同时给出格式错误（见 ③） **② 已有合法 Key，但存在未完成的行**（行数 > 1） | 行状态 | 行内文案（挂在 API Key 输入框下，输入框标红） | |--------|----------------------------------------------| | Key、备注都未填 | **请填写 API Key 或删除本行** | | 只填了备注、未填 Key | **请填写 API Key** | 此类错误为 **行内错误**，不再依赖表格下方汇总格式文案。 **③ 已填 Key 但格式不合法** - 行内红字：**API Key 格式不正确，请填写不含空格的完整 Key** - 输入框标红 - 表格下方那条「完整 Key」汇总文案 **不再重复展示**（以行内为准） **通过后** - 提交当前列表（不再默默丢掉空行：空行必须先删掉或补齐） - Toast：**保存成功** - 此后工商查询使用本次保存的平台与 Key 池 **其他** - 备注超 30 字在输入时截断，保存不再单独报错。 - 不要求备注非空。重复 Key 的处理见 §6。 ### 5.5 查询时 Key 轮询（服务端，核心逻辑） 配置页不发起工商查询。用户在线索 / 客户等业务场景点击 **「查询工商信息」** 时，服务端按 **已保存的风鸟 Key 列表顺序** 选 Key。 **基本规则** 1. 候选集 = 列表中状态为 **正常**，且当日额度未满的 Key。 2. 按列表从上到下轮询：第 1 次用第 1 个可用 Key，第 2 次用下一个，到末尾后回到第一个可用 Key。 3. 状态非「正常」（含失效、额度已满、待同步）的 Key **本轮跳过**。 4. 当前 Key 调用失败或被判定过期 / 失效时：将该 Key 状态回写为「失效」（或风鸟返回的对应态），**立即尝试下一个可用 Key**。 5. 当前 Key 返回额度用尽：回写「额度已满」，**立即尝试下一个可用 Key**。 6. 全部可用 Key 都失败，或全部为额度已满 / 不可用：走 §5.6，**不**打开工商结果。 **示意 A：3 个 Key 均正常且未达日上限** | 请求次序 | Key1 当日累计 | Key2 当日累计 | Key3 当日累计 | 本次使用 | |----------|---------------|---------------|---------------|----------| | 第 1 次 | 1 | 0 | 0 | Key1 | | 第 2 次 | 1 | 1 | 0 | Key2 | | 第 3 次 | 1 | 1 | 1 | Key3 | | 第 4 次 | 2 | 1 | 1 | Key1 | | 第 5 次 | 2 | 2 | 1 | Key2 | | 第 6 次 | 2 | 2 | 2 | Key3 | **示意 B：Key2 失效或额度已满时自动越过** | 请求次序 | Key1 | Key2 | Key3 | 本次使用 | |----------|------|------|------|----------| | 第 1 次 | 1 | — | 0 | Key1 | | 第 2 次 | 1 | 跳过 | 1 | Key3 | | 第 3 次 | 2 | 跳过 | 1 | Key1 | **日调用计数（后端，配置页不展示）** | 项 | 规则 | |----|------| | 维度 | **Key 字符串** + **自然日**（以服务端时区为准，需与现网一致并在技术方案中写死） | | 用途 | 判断是否「额度已满」、支撑轮询跳过 | | 删除再添加 | 同一 Key 字符串当天次数 **接续**，不因删除行而从 0 重计 | | 配置页 | **不展示**该次数 | ### 5.6 客户详情 · 额度用尽全局 Message **场景：** 当前平台为美亚风鸟，且 Key 池内 **全部 Key 当日额度已用尽（或均不可用）**，用户点击「查询工商信息」。 原型演示页：目录 **客户详情-工商查询**（顶栏 Tab「客户详情」）。生产覆盖所有带「查询工商信息」的详情页（客户 / 线索 / 商机等，与现网入口一致）。 | 项 | 规则 | |----|------| | 形态 | **顶部居中悬浮 Message**（对齐现网 `Message` / 全局通知组件），**禁止**使用顶栏下方通栏 `Alert` 条挤占布局 | | 位置 | 视口 **顶部居中**（原型约 `top: 56px`），`z-index` 高于工作区；**不**随页面滚动常驻占位 | | 动效 | 出现时自上方轻微滑入 + 淡入（原型参考）；关闭即隐藏 | | 样式 | 白底卡片、描边 `#ffccc7`、文案 `#cf1322`、左侧 ⚠ 图标、轻阴影；与字段行内红字、底部居中黑色「保存成功」Toast 区分 | | 固定文案 | **暂无法查询工商信息：风鸟 Key 今日额度已用尽，请联系管理员或明日再试。**（全文仅此一句，禁止加长或改写） | | 结果区 | **不弹出 / 不刷新工商结果** | | 关闭 | 卡片右上角 **×**；关闭后再次点击「查询工商信息」，若仍无可用 Key，**再次弹出同文案** | | 自动消失 | **不**默认几秒自动关闭（错误需用户主动关或离开页）；若现网 Message 有统一时长，以现网组件规范为准且文案不变 | | 离开页面 | Message 关闭，不带到其他路由 / Tab | | 无障碍 | `role="alert"`、`aria-live="assertive"`（或等价实现） | | 接口 | 研发使用 **同一 errorCode** 映射上述文案；前端仅做映射展示，禁止第二套说法 | 企查查额度 / 鉴权失败沿用现网提示，不套用本条文案。 --- ## 6. 异常与边界 | 场景 | 处理 | |------|------| | 未填任何合法 Key 点保存 | 拦截，见 §5.4 ① | | 多行存在完全空行 | 拦截，行内「请填写 API Key 或删除本行」 | | 只填备注未填 Key | 拦截，行内「请填写 API Key」 | | Key 格式错误 | 拦截，行内格式文案，见 §5.4 ③ | | 企查查缺 Key 或 SecretKey | 拦截，Toast「请完善配置」 | | 列表被删空 | 自动补空行；此时不能保存成功 | | 删除未点保存就离开 / 刷新 | 未保存的增删改丢失，以后端已存数据为准 | | 重复粘贴同一 Key | 保存时建议按 Key 字符串去重并 Toast（如「已忽略重复 Key」）；至少保证轮询按唯一 Key 计数。**推荐一期保存去重。** | | 全部 Key 额度用尽 / 均不可用 | 见 §5.6；管理员在配置页按状态补 Key 或等次日额度恢复 | | 无权限访问配置页 | 无入口，不展示他人 Key | --- ## 7. 主流程 ### 7.1 Key 录入 ``` 销售在风鸟注册并创建 API Key ↓ 汇总 Key（+ 姓名 / 手机号备注）交给管理员 ↓ 管理员：手填 / 添加一行录入（默认掩码，必要时点眼睛核对） ↓ 保存配置生效（空行须删除或补齐） ``` ### 7.2 工商查询（运行时轮询） ``` 用户在详情页点击「查询工商信息」 ↓ 按列表顺序轮询 Key1 → Key2 → Key3 → Key1 … ↓ 跳过：失效 / 额度已满 / 待同步 等非可用 Key ↓ 有可用 Key → 调用风鸟并回写状态（及日调用计数）→ 展示工商结果 ↓ 全部不可用 / 额度用尽 → 顶部全局 Message（§5.6），不展示结果 ``` ### 7.3 销售申请 Key（配套指南，非 CRM 页面） > 图文步骤以 **§4.3 飞书 wiki** 为准；管理员配置页「获取说明」链至同一文档。以下为摘要。 1. 打开风鸟官网并注册 / 登录（建议本人常用手机号） 2. 进入「个人中心」 3. 账户设置 › API Key ›「生成个人 API Key」 4. 填写 Key 名称（最多 20 字，风鸟侧限制）并生成 5. **立即复制完整 Key**（风鸟现网一般以 `fn_sk_` 开头，仅显示一次；CRM 按完整字符串保存，不强制此前缀） 6. 将 Key 发给管理员，建议同时注明姓名 + 手机号 7. 不要发到公开群；怀疑泄露则在风鸟停用并重新生成，再让管理员更新 CRM 每人通常 **1 个** 风鸟账号 / 1 个个人 API Key 即可。风鸟 **不需要** SecretKey。 --- ## 8. 数据与接口（实现约束） > 产品侧约束，不规定具体 URL。 **保存工商配置** - 入参：平台（`fengniao` / `qcc`）；风鸟为 Key 列表（value、remark）；企查查为 key、secretKey - 风鸟不传状态、不传今日调用 - 服务端：格式校验（非空、不含空白字符）、拒绝未完成空行、建议 Key 去重、加密存储 **读取工商配置** - 回显平台、Key 列表、备注、状态 - 列表默认掩码，明文仅在用户点眼睛后于当前浏览器会话展示 - 无权限则拒绝 **工商查询（已有能力改造）** - 若当前平台为风鸟：按 §5.5 选 Key 并调用 - 调用后回写对应 Key 的状态；按 Key 字符串 + 自然日累加次数 - 全部额度用尽 / 均不可用：返回约定 **errorCode**，前端以 **顶部 Message** 展示 §5.6 固定文案 - 若当前平台为企查查：保持原单 Key + SecretKey 调用 --- ## 9. 验收标准 ### 9.1 入口与权限 - [ ] 管理层可从「设置中心 › 系统设置 › 工商信息配置」进入本页 - [ ] 非管理层无法维护 Key 池（无入口或不展示表单） - [ ] 默认子 Tab 为工商信息配置时，默认平台为美亚风鸟 - [ ] 其他系统设置子 Tab 不出现本页保存按钮 ### 9.2 风鸟配置页 - [ ] 平台可在「企查查 / 美亚风鸟」间切换，表单立即变化 - [ ] 风鸟无 SecretKey；企查查仍为 Key + SecretKey - [ ] 提示行含「获取说明」，新标签打开飞书 wiki（URL 见 §4.3） - [ ] 工具栏仅「添加一行」，无批量导入、无模板下载 - [ ] 表头：API Key 带 `*`，备注不带 `*` - [ ] 备注最多 30 字，超长无法继续输入 - [ ] API Key 含空格（含首尾、中间）时，输入框标红；无前端长度截断 - [ ] 风鸟 API Key 默认掩码；点击眼睛可看明文，再点恢复掩码 - [ ] 风鸟备注为明文输入框，无眼睛图标 - [ ] 企查查 Key、SecretKey 同样默认掩码 + 眼睛 - [ ] 添加一行或重新进入后，输入框回到掩码态 - [ ] 空列表自动出现一行空输入 - [ ] 删除需二次确认；文案含「删除后需点击保存才会生效」 - [ ] 仅剩空白一行时无删除按钮 - [ ] 列表不展示「今日调用」列 ### 9.3 保存 - [ ] 0 条合法 Key：无法保存，表格下「请至少填写 1 个 API Key」，Toast「请完善配置」 - [ ] 多行时存在完全空行：该行下「请填写 API Key 或删除本行」，无法保存 - [ ] 只填备注未填 Key：该行下「请填写 API Key」，无法保存 - [ ] 已填但格式错误：该行下「API Key 格式不正确，请填写不含空格的完整 Key」，无法保存 - [ ] 任意长度、不含空格的完整 Key 可保存；含任意位置空格不可保存 - [ ] 合法 Key + 空备注（且无多余空行）：可保存，Toast「保存成功」 - [ ] 保存后刷新，平台、Key、备注与保存结果一致（Key 默认仍掩码，备注明文） - [ ] 状态列刷新后仍为服务端回显 - [ ] 删除后不点保存就刷新，Key 仍在 ### 9.4 轮询与额度用尽（联调） - [ ] 多个「正常」Key 时，连续查询按列表顺序轮流使用（1,1,1 → 2,2,2 形态） - [ ] 「失效」「额度已满」的 Key 被跳过 - [ ] 当前 Key 调用失败后自动改试下一个 - [ ] 全部 Key 额度用尽时：详情页 **顶部居中弹出** 固定文案 Message，不弹出工商结果 - [ ] Message 可 × 关闭；关掉后再查且无可用 Key 时，**同一条文案再次弹出** - [ ] Message 形态为悬浮卡片，**不是**顶栏下通栏红条 - [ ] 文案与接口 errorCode 一一对应，前端不写死第二套说法 - [ ] 删除后再添加同一 Key 字符串，当天调用次数不从 0 重计 - [ ] 切换并保存为企查查后，查询走企查查，不再消耗风鸟 Key，也不出本条风鸟额度文案 ### 9.5 企查查兼容 - [ ] 切换到企查查可见 Key、SecretKey（默认掩码） - [ ] 任一项为空时无法保存 - [ ] 两项均填写可保存成功 --- ## 10. 原型对照 | 原型目录 | 对应内容 | |----------|----------| | 文档 › 需求说明 | 背景、范围、字段、非目标（已并入本文） | | 文档 › 流程图 | Key 录入、查询轮询（已并入 §7） | | 文档 › 修改记录 | 原型迭代记录；PRD 以当前 HTML 终态为准 | | 原型页面 › 工商信息配置 | 可交互配置页 + 右侧改动标注 | | 原型页面 › 客户详情-工商查询 | 额度用尽 **顶部 Message** 演示（§5.6） | **右侧改动标注（原型交付用，研发实现不强制水滴 UI）** | 标注主题 | 原型锚点位置 | |----------|----------------| | 入口与权限 | 侧栏「系统设置」 | | 工商信息配置 Tab | 子 Tab 文案旁 | | 平台切换 | 「企查查 / 美亚风鸟」单选组后 | | 获取说明 | 「获取说明」链接旁 | | 工具栏 | 「添加一行」按钮旁 | | Key 列表字段 | 表单标签「Key」旁 | | Key 轮询逻辑 | 表头「状态」列旁 | | 保存 | 页脚「保存」按钮 | | 查询工商信息 | 详情页「查询工商信息」按钮 | | 顶部全局 Message | 弹出后的 Message 卡片（需先点查询触发） | 标注正文与本文 §4～§5 一致；长 URL 等在标注栏内自动换行（依赖公共样式 `shared/crm-proto-anno.css`）。 )