contact-import

联系人批量导入教学领域,说明任务受理、逐行结果、查询与有条件恢复。

SKILL.md

GitHub

联系人批量导入

本域把一批姓名和邮箱转换为租户内的联系人记录,并保留每一行的处理结果。提交者先拿到任务标识,再查询执行结果;教学调度者显式执行排队任务,遇到指定的存储故障时,可以在次数允许的条件下恢复尚未处理的行。

这是内存模拟教学项目,本文中的姓名、邮箱、租户和任务号均为示例。 “异步”指提交与执行分离;任务不会自动运行,执行调用本身会同步处理整批剩余行。没有真实消息队列、持久化存储、鉴权服务或外部通知。

结果、责任与边界

本域拥有两个结果:按租户和归一化邮箱保存的联系人,以及解释本次导入经历的任务和逐行结果。联系人回答“现在这个人的姓名是什么”,任务回答“这一批每一行发生了什么”。二者不能互相替代:同一邮箱连续出现两次,可能有两次成功写入,但最后只有一个联系人。

读者要判断的事 本域的明确口径
谁发起 调用方提供租户标识、幂等键和联系人行;没有实际身份校验
提交完成 新任务进入 queued;尚未写入联系人
业务处理完成 全部行都有结果;任务为 succeeded、partial,或全行拒绝的 failed
故障停止 failed 且 error=storage_unavailable;可能还有未处理行
恢复完成 重新执行后读取最终快照;retry 返回只表示重新排队
不承担的能力 CSV 解析、真实鉴权、邮件验证、外部同步、取消、后台调度和重启恢复

租户标识只是调用方传入的分区键。查询和恢复只允许命中同租户任务,但这不能证明调用者有权声称自己属于该租户。真实鉴权应由集成方另行实现;教学实现没有这个接管模块,也没有任何已验证的跨域调用。

按任务进入模块

模块 什么时候进入 能得到什么
提交与查询 需要创建批次、处理重复提交、解释进度或修正坏行 正确的任务标识、结果读法和重新提交策略
执行与恢复 任务还在等待,或故障后需要决定是否继续 执行边界、部分写入解释和有条件恢复步骤

例如运营者希望导入三行联系人,应先进入“提交与查询”,理解任务受理和幂等键。若查询一直是 queued,再进入“执行与恢复”检查是否有人驱动了任务。若最终是 partial,回到逐行结果处理坏行,不要把整批当成存储故障重试。

贯穿案例从空实例开始:联系人甲首次创建,乙因坏邮箱被拒绝,第三行更新甲,原批次最终写入 2 行但仅有一个联系人。提交者修正乙后用新键建任务,第二批成功后才有两位联系人,第一批仍保留部分成功。另一个恢复案例使用丙、丁,专门核对行前故障、保留结果和恢复次数。两类案例都使用合成数据,不能把任务完成数、写入行数和联系人数量混为一谈。

共享定义从哪里查

专题 主要回答的问题
接口 四个公开入口如何调用,返回时完成到哪一步,异常怎样处理
对象 任务、行结果、联系人和响应字段的含义及写入责任
规则 哪些条件改变结果,判定顺序是什么,正反例怎样复核
状态 受理、执行、终结和恢复之间有哪些真实转换
协作 调用者、队列、执行器和内存记录怎样交接
基础设施 模拟资源、配置、故障注入和排查边界

六个专题定义共享事实,模块解释它们如何参与具体任务。新增需求若改变状态、统计口径或恢复语义,应先修改对应主定义,再同步关联模块中的案例和图。