contact-import
联系人批量导入教学领域,说明任务受理、逐行结果、查询与有条件恢复。
SKILL.mdtests/fixtures/authoring/async-import/modus/knowledge/domain/contact-import/SKILL.md
GitHub联系人批量导入
本域把一批姓名和邮箱转换为租户内的联系人记录,并保留每一行的处理结果。提交者先拿到任务标识,再查询执行结果;教学调度者显式执行排队任务,遇到指定的存储故障时,可以在次数允许的条件下恢复尚未处理的行。
这是内存模拟教学项目,本文中的姓名、邮箱、租户和任务号均为示例。 “异步”指提交与执行分离;任务不会自动运行,执行调用本身会同步处理整批剩余行。没有真实消息队列、持久化存储、鉴权服务或外部通知。
结果、责任与边界
本域拥有两个结果:按租户和归一化邮箱保存的联系人,以及解释本次导入经历的任务和逐行结果。联系人回答“现在这个人的姓名是什么”,任务回答“这一批每一行发生了什么”。二者不能互相替代:同一邮箱连续出现两次,可能有两次成功写入,但最后只有一个联系人。
| 读者要判断的事 | 本域的明确口径 |
|---|---|
| 谁发起 | 调用方提供租户标识、幂等键和联系人行;没有实际身份校验 |
| 提交完成 | 新任务进入 queued;尚未写入联系人 |
| 业务处理完成 | 全部行都有结果;任务为 succeeded、partial,或全行拒绝的 failed |
| 故障停止 | failed 且 error=storage_unavailable;可能还有未处理行 |
| 恢复完成 | 重新执行后读取最终快照;retry 返回只表示重新排队 |
| 不承担的能力 | CSV 解析、真实鉴权、邮件验证、外部同步、取消、后台调度和重启恢复 |
租户标识只是调用方传入的分区键。查询和恢复只允许命中同租户任务,但这不能证明调用者有权声称自己属于该租户。真实鉴权应由集成方另行实现;教学实现没有这个接管模块,也没有任何已验证的跨域调用。
按任务进入模块
| 模块 | 什么时候进入 | 能得到什么 |
|---|---|---|
| 提交与查询 | 需要创建批次、处理重复提交、解释进度或修正坏行 | 正确的任务标识、结果读法和重新提交策略 |
| 执行与恢复 | 任务还在等待,或故障后需要决定是否继续 | 执行边界、部分写入解释和有条件恢复步骤 |
例如运营者希望导入三行联系人,应先进入“提交与查询”,理解任务受理和幂等键。若查询一直是 queued,再进入“执行与恢复”检查是否有人驱动了任务。若最终是 partial,回到逐行结果处理坏行,不要把整批当成存储故障重试。
贯穿案例从空实例开始:联系人甲首次创建,乙因坏邮箱被拒绝,第三行更新甲,原批次最终写入 2 行但仅有一个联系人。提交者修正乙后用新键建任务,第二批成功后才有两位联系人,第一批仍保留部分成功。另一个恢复案例使用丙、丁,专门核对行前故障、保留结果和恢复次数。两类案例都使用合成数据,不能把任务完成数、写入行数和联系人数量混为一谈。
共享定义从哪里查
| 专题 | 主要回答的问题 |
|---|---|
| 接口 | 四个公开入口如何调用,返回时完成到哪一步,异常怎样处理 |
| 对象 | 任务、行结果、联系人和响应字段的含义及写入责任 |
| 规则 | 哪些条件改变结果,判定顺序是什么,正反例怎样复核 |
| 状态 | 受理、执行、终结和恢复之间有哪些真实转换 |
| 协作 | 调用者、队列、执行器和内存记录怎样交接 |
| 基础设施 | 模拟资源、配置、故障注入和排查边界 |
六个专题定义共享事实,模块解释它们如何参与具体任务。新增需求若改变状态、统计口径或恢复语义,应先修改对应主定义,再同步关联模块中的案例和图。