Shopee工具的输入输出要对得上

输入输出指的是什么

输出指的是这一段交给下一段的那份东西，不是它自己看的报表。这一点经常被混淆。一段工作内部可能看着七八张表，但真正交给下游的往往只有一张，甚至只有其中几列。定义接口的时候要认的是那份交出去的东西。

输入指的是这一段开工时必须先拿到的东西。它可能是上一段的一张清单，也可能是上一段给出的一个范围，比如这一轮只看某几个类目。范围这种东西很容易被忽略，因为它不是一张表，但它决定了这一段怎么干。

一个完整的接口描述至少要说清四件事：交的是什么、以什么为单位、多久更新一次、谁来维护。少任何一项，下游都可能在自己的场景里做出不同的假设，而这些假设往往要等到出问题的时候才会被发现。

还有一个常被跳过的问题是谁是接口的负责人。两边都觉得对方会盯着，结果两边都不盯。指定一个人之后，字段变动要经过他，出问题也找他，接口才不会在两段的夹缝里慢慢走样。

接口和文件是两件事。文件是一个载体，接口是一份约定。同一份约定可以有多种载体，导出表格、复制粘贴、系统之间对接，都只是方式不同。约定没写清，换什么载体都还是接不上。

实际定义接口的时候，可以按一个固定的顺序走。先写下这一段的输入是从哪来的、长什么样，再写下输出交给谁、以什么形式交，然后写清两处的更新时点，最后指定负责人。四步走完，一份最简单的接口说明就成形了。

写的时候有一个原则：以实际在用的为准，不以模板为准。很多团队的模板上列着十几个字段，实际天天用的只有五六列。按模板写出来的接口说明看着完整，实际上没有约束力，因为没人真的按它对接。

写完之后的第一个动作是把这份说明拿到下游那一边去对。让对方用自己的话复述一遍他要拿到什么东西，复述得和说明一致，才算真的说清了。这一步花十分钟，能省掉后面很多次来回解释。

对完之后的第二个动作是定一个变动的通知方式。多数团队用一个固定的位置存放说明，改动之后就更新那一份，下游定期看。也有团队用群消息通知，效率更高但容易漏。两种都行，关键是要固定，不要每次换一种方式。

最后给这份说明标上版本和日期。接口说明是会变的，版本号让两边在沟通的时候能确认说的是不是同一份。这一点在换人接手的时候尤其有用，翻出旧消息时一眼就能看出两边看的是不是同一版。

有一个细节值得单独说：范围也是一种输入。上一段说这一轮只看某个价格带的品，这句话不是一张表，但它决定了下一段的工作边界。范围没有被明确写下来的时候，每一段都会自己划定一个范围，几个范围叠起来就完全对不上了。

边界条件是当一段的输入来自多个人时。同一个人给的数据通常风格一致，几个人给的数据往往格式都不一样。这时候要做的不是在收的时候逐个适配，而是先定一个统一的交法，让所有提供方按同一个格式交。

记录方法上，建议给每一段建一张小卡片。正面写输入从哪来、长什么样，背面写输出给谁、什么格式、多久更新一次。卡片做出来贴在工位旁边或者放进共享文档，一段一段接着补，几张卡片下来整条链就清楚了。

还有一个容易忽略的输入是时间。这一轮从什么时候开始、到什么时候截止，这个信息经常只存在于排期表上，具体干活的人反而不知道。把它写进接口说明，能避免两段在不同时间区间上各算一遍。

有一个案例可以说明范围的重要性。一家店铺的几个环节各自按自己的口径统计在售商品数，三个数分别是四百多、五百多和七百多。差异的原因不是算错，而是一个含了下架未清的、一个不含配件。范围写清楚之后，三个数自然就接近了。

对上不是结果一致，而是每一列都有明确的落点

工具之间对不上的常见情况

最常见的一种是名称不同。同一个东西，上游叫商品编号，下游叫货号，两处都对，就是接不上。人在中间看一眼就能认出来，工具按名称匹配就会当成两个不同的字段，于是下游那一列永远是空的。

第二种是时间口径。上游按订单创建时间统计，下游按付款时间统计，正常时候两边的数很接近，遇到大促或者支付延迟时就会拉开。这种差异的麻烦在于它平时不出现，一旦出现往往是在最忙的时候。

第三种是颗粒度。上游出的是一天一条的汇总，下游要的是按小时的明细，粗的没法拆成细的。反过来的情况也存在，上游出的是逐条明细，下游只需要每天一个总数，虽然能算，但每次都算一遍增加了出错的机会。

第四种是取值范围。含不含优惠券、含不含运费、含不含税，这三种排列组合能出八种口径。两段之间取的不是同一种，数字就会稳定地差一截，而且这个差距通常还看不出趋势上的异常，很容易被当成规模变化。

还有一种是更新频率。上游每周一更新一次，下游每天早上取数，周二到周日取到的其实都是同一份东西。这不是错，但如果下游按天算趋势，就会得到一条台阶状的曲线，然后为这条曲线找出一堆不存在的解释。

遇到对不上的时候，处理顺序建议是先分类再动手。先判断属于六种里的哪一种，是名称、时间、颗粒度、取值范围、空值还是频率。分对了类，处理办法基本就定了，多数情况不需要两边开很久的会。

分类的办法很简单，把两边同一个指标的多期数据放在一起看。差值是固定的还是随机的，是稳定比例还是没规律，这几种形态分别对应不同的原因。固定比例多半是取值范围的问题，时大时小多半是时间口径的问题。

分完类之后，选一个成本最低的改法。名称不同就统一名称，加一份对照表；时间不同就约定一个取数时点，多在说明里写一句话。多数接口问题都不需要动系统，改一句约定就够了，动系统反而会把事情做大。

改完要做一次验证。拿改动之后的最近一期数据，按新的约定重新对一遍，确认差异消失了。验证不通过就说明原因判断错了，回到分类那一步重新看。不要在没有验证的情况下就把改动当成完成了。

最后把这一个案例记下来。写清表现、判断过程、处理方式和结果，积成一页一页的案例。下次遇到类似的情况，翻一翻就能直接动手，不必再从头分析一遍。这是最省时间的做法。

有一个细节是关于时间跨度的。上游出的是自然月，下游按四周一组看，两者在月初月末会错开好几天。这种差异在月度复盘时常常被当成业绩波动来解释，实际上只是两个时间跨度没有对齐，业务上什么都没发生。

边界情况是多站点经营。不同站点的结算周期、节假日安排都不一样，同一个时间口径搬到另一个站点可能就不适用。跨站点对比的时候，要么统一口径但接受一定的偏差，要么分站点各自比，不要混着比。

记录方法上，建议维护一份对不上的案例库。每遇到一次就补一条：表现是什么、怎么判断出来的、最后怎么处理的。案例积累到十条左右，新问题基本都能在里面找到相似的情况，处理速度会明显变快。

还有一个细节是币种。多币种经营时，换算的时点不同会带来小差异，这个差异平时很小，汇率波动大的时候会放大。约定一个统一的换算时点，比如统一按结算日，这类差异就变成一个可解释的固定偏差。

有一个案例是关于状态的。上游把已取消的订单也放在表里并标了状态，下游的公式没有过滤状态，直接把所有行都加了起来。两边的数差得非常多，但两份表其实都没有错。加一个状态筛选条件，问题立刻消失。

多数接不上都是名称与口径这两类，真正缺字段的情况反而少

对不上会怎样

最直接的代价是返工。下游拿到数据之后要先做一轮手工调整，改名称、补时间列、把颗粒度对上。这一轮调整通常没人把它记在工时里，因为它分散在每一天，看起来只是顺手做一下，累计起来却不小。

第二个代价是结论被削弱。数据在转换中被改过之后，谁也没法确认它有没有被改错。于是每次要用这个结论做决定的时候，都要先花时间确认一遍数字。这种来回确认消耗的不只是时间，还有团队对数据的信任。

第三个代价是排查变慢。当结果不对的时候，可能的原因从几处变成十几处：是上游算错了、还是转换改错了、还是下游理解错了。排查的范围一扩大，找出真正原因的时间就会成倍增加。

第四个代价比较隐蔽，是慢慢没人用这套数据了。因为不放心，大家开始各看各的后台，各算各的数。这时候链路形式上还在，实际上已经断了，只是没有人正式宣布这件事。

这几种代价有一个共同点：都不在发生的时候显现，而是延后出现。所以单看某一天，手工补一下确实没什么，只有把时间拉长到几个月，差别才会明显。这也是接口这件事容易被拖延的原因。

判断代价大不大，可以看两件事：返工发生在多少天里、每次返工要花多久。前者说明频率，后者说明强度。两个都低的时候可以暂时忍着，等量涨上来再处理；两个里有一个明显偏高，就该把它排进待办。

还有一个判断角度是看这个数字会不会被用来做决定。仅供看看的数字，对不上关系不大；要被用来决定下一批做什么品、投多少预算的数字，对不上就要立刻处理。重要程度不同，处理的紧迫程度也应该不同。

处理的动作建议从最影响决策的那一列开始。同样是差一个字段，差的是销量还是差的是备注，意义完全不同。通常每个环节都有一两列是关键列，先把关键列对上，这一段的接口就基本能用了。

处理的时候要留一个观察期。改完之后的两三周里，注意看有没有新的差异冒出来。接口改动常常会带来连带影响，比如统一了时间口径之后，某些历史对不上的地方反而变得更容易看出问题了。

还有一件事值得做：把返工本身记录下来。每次手工调整花了多久、调整了哪些列，写两三周。这份记录是把接口问题量化出来的最直接材料，比拍脑袋说感觉效率低有说服力得多。

有一个细节是返工的位置往往不在发现问题的环节。问题在下游被发现，但根因可能在上游两段之前。所以处理的时候不要只在下游打补丁，要顺着接口往前追一段，看看是不是更早的地方就已经偏了。

边界条件是当差异很小的时候。差百分之零点几，多数时候不影响判断，这时候花大力气去查并不划算。可以先记下来观察，如果这个差异在几个月里保持稳定，说明它是一个固定偏差，写进说明里注明就可以了。

记录方法上，建议给每次返工记一条：什么时候发现、影响了哪几个结论、补了多久。这份记录不需要给任何人看，它只是用来判断这件事值不值得投入。一个月下来，答案通常就很清楚了。

还有一个细节是团队对数据的信心。这个指标不好量化，但能观察：开会讨论的时候，有争议的数字大家会不会先去后台重新查一遍。如果经常发生，说明内部的这套数据还没有被信任，这时候修接口比加报表更急。

有一个案例是某团队连续几个月在做月度复盘时都要先花两个小时对数。后来他们把两段之间的时间口径统一，并对齐了含不含券的处理，这两个小时直接省了下来，而且是每个月都省。这笔账算下来很可观。

怎么检查对得上

检查从列字段开始。把上游的输出列一遍，把下游实际在用的列列一遍，两张清单各写一栏。写的时候不要直接复制下游的模板，因为模板里往往有早就没人用的历史列，照抄会把噪音也带进来。

两份清单出来之后做三种标记：两边都有且含义相同、两边都有但含义不同、只有一边有。第三种里，如果缺的是下游要用的，就是真实的缺口，需要补；如果缺的是上游有但下游不用的，可以先放着，不必强求同步。

标记完之后要拿真实数据验证，不能只看清单。挑最近一次实际输出，按清单手工映射一遍，从头到尾走一遍。走的过程中一定会遇到清单上没写的情况，比如某几行的日期格式和其余行不一样，这些就是清单里的漏洞。

验证的时候重点看边界行。取数区间的第一天和最后一天、金额为零的行、刚上架还没有数据的商品、退款之后的状态，这几类行最容易暴露口径差异。中间的常规行反而很少出问题。

最后把验证结果写成一页纸：对上了哪些、没对上哪些、打算怎么处理、什么时候处理完。这页纸贴在两个环节都能看到的地方，下次接口变动的时候直接在它上面改，比重新做一遍要快。

检查的时候可以先做一次反向走查。不看上游交了什么，而是从下游最近一次用过的结果倒推，看它需要哪些输入。倒推出来的清单往往比正着列更接近真实需求，因为它是从实际使用出发的。

正反两份清单摆在一起，缺口就很清楚了。只有下游需要而上游没给的，是必须补的；只有上游给了而下游没用的，可以先标着观察，看是不是下游还没用上，而不是急着删掉。

接下来做一次抽查。挑三期数据，每期随机选十来行，逐行核对两边的值。抽查不追求覆盖全部，追求的是随机性，随机抽样比专门挑显眼的行更能发现系统性的问题。

抽查里发现的不一致要逐条写下来，写清是哪一期、哪一行、哪一列、差了多少。写下来之后再看这些不一致能不能归成几类。能归类说明是口径问题，归不了类说明可能有随机因素，两种情况处理方法不同。

检查结束之后定一个复查时间。通常是一个月之后。复查的内容很简单，就看上次发现的那几类问题有没有再出现。没有再出现，这次接口检查就算做完了；又出现了，说明当时的处理只是绕过去了，根因还在。

有一个细节是检查的顺序。建议先查时间口径，再查取值范围，最后查颗粒度。原因是时间口径的影响最大，先把最大的差异找出来，后面的差异就更容易看清。反过来查容易被大差异掩盖住小问题。

边界条件是当上游的输出一直在变的时候。如果上游的口径每个月都要调，接口检查就很难有一个稳定状态。这种情况下，与其反复检查，不如先把上游的口径固定下来，检查的频率自然就降下去了。

记录方法上，可以把检查结果做成一张单行表：检查日期、检查的字段数、对上的数量、未对上的清单、处理状态。一行一次，几十行下来就是这份接口的完整经历，也方便看出哪几个字段总是在出问题。

还有一个细节是要区分对不上和对不准。对不上是两边的口径不一样，对不准是同一口径下精度不够。前者要改约定，后者要改计算方式。混在一起查，容易把一个简单的精度问题当成口径问题来处理。

有一个案例是团队在检查时发现，两段之间的一个关键字段有将近三成的行是空的。追下去才知道，上游只在有促销的时候才填这一列，平时的行都是空的。这个字段被下游当成必填在用，于是三成的行全部落空。

格式与口径两项校验

格式校验是最容易做也最容易见效的一层。它只关心形状：字段名对不对得上、数字带几位小数、日期是哪种写法、单位是件还是箱。这一层不需要理解业务，谁都能上手，通常半天就能把两段之间的格式过一遍。

格式校验里有一项经常被忽略，就是数值的格式。同一列里有的单元格是数字、有的是文本，看起来一样，排序和求和的时候结果却不同。这种问题在导出之后再导入的过程中特别容易出现，检查的时候要特意看一眼。

口径校验要理解业务才能做，所以放在第二层。它关心的是这个数字到底算了什么：时间段怎么切、包含哪些订单状态、含不含优惠券和运费、是下单口径还是完成口径。这几项逐条问清楚并写下来，口径就固定了。

口径校验有一个好用的方法，就是拿一个已知的案例去对。挑一笔你完全清楚的订单，看它在上游表里怎么体现、在下游表里怎么体现。如果这一笔在两处的处理一致，多数情况下其余订单也会一致；不一致的话，问题就找到了。

两项校验都做完之后，把结论合并成一份接口说明。格式部分写成列表，口径部分写成几句话。这份说明不用求全，能覆盖当前在用的字段就够，后面的新字段在加进来的时候顺手补上。

过格式这一层的时候，可以做一个固定的动作清单。看字段名、看类型、看单位、看小数位、看日期写法、看是否有前后空格。六项逐一过一遍，多数格式问题都能被发现，而且这六项不需要业务知识，谁都能做。

前后的空格是一个特别常见但特别难查的问题。两个看起来一模一样的字段名，一个末尾多一个空格，匹配就失败。肉眼基本看不出来，处理办法是在检查的时候顺便做一次清理，把空格统一去掉。

过口径这一层的时候，用提问的方式比用核对的方式更有效。直接问下游：这一列你打算拿它算什么？再问上游：这一列你是怎么算出来的？两句话的答案放在一起，差异往往立刻显形，不需要去翻公式。

口径校验做完之后，把结论写成三句话：这一列统计的是什么时间段、包含哪些状态、含不含附加项。三句话放在表头或者说明里，任何人拿到这份数据都能自己判断能不能用，不必每次都来问。

两项校验都通过之后，建议在两个环节之间放一个轻量的检查动作。比如每次取数之后看一眼必需列是不是都非空。这个动作只需要几秒钟，却能在问题刚出现的时候就把它拦下来。

有一个细节是关于日期格式。同样是某年某月某日，有的地方写完整年份，有的地方只写月和日，有的用斜杠有的用短横线。几种写法混在一列里，排序会乱，筛选会漏。统一成一种写法，是格式校验里最容易见效的一项。

边界条件是当一列里既有数字又有文字时，比如金额栏里偶尔出现「待定」两个字。只看平均值看不出来，一求和就会报错。这类情况要在格式校验时专门抽查，做法是看看这一列里有没有非数字的行。

记录方法上，建议把格式约定写成一份简短清单：日期怎么写、金额保留几位小数、空值用什么标记、编号是否保留前导零。四项写清，格式层面基本就不会再出问题，这份清单也只需要写一次。

还有一个细节是编号的前导零。纯数字格式的表格里，编号开头的零会被自动去掉，导致两个本来不同的编号变成了同一个。这类问题在导入导出的时候特别常见，检查的时候要专门看一眼编号列。

有一个案例是一家店铺的两个环节都在统计同一批商品，但一边用商品规格编号，一边用上架时自己编的流水号。两份清单各自都对，就是对不上。统一到规格编号之后，两边才第一次真正把同一批商品放在一起比较。

越靠后的接口越依赖人的判断，越需要把字段规则写细

接不上时的处理办法

处理的第一步是判断在哪边改。如果只涉及格式，改哪边都一样，通常改下游更省事，因为上游的输出可能已经被别的环节在用。如果涉及口径，就要看哪边的口径更接近原始数据，让另一边靠过来。

第二步是决定要不要加中间层。两边都不方便改的时候，在中间加一层转换是最常见的做法。这一层的职责单一：只做映射和换算，不做判断。加了中间层之后，接口的关系从一条变成两条，但每条都更简单。

第三步是处理历史数据。口径改了之后，之前的数据要不要按新口径重算，这个问题经常被跳过。多数情况下不需要重算，但一定要在表里注明从哪一天起口径变了，否则以后有人把前后两段拿来对比，会得出错误的趋势判断。

第四步是通知下游。这件事听起来简单，实际上是最常被漏掉的一步。通知至少要包含三句话：改了什么、从哪天起生效、下游需要做什么。三句话说清，多数误解都可以避免。

最后一步是留一次复盘的时点。改完之后过一个月，回头看看还有没有因为这次改动产生的新问题。接口调整往往会带来一些意想不到的连带影响，留一个复盘点能及时把它们收住。

决定在哪边改的时候，可以按一条简单的规则来：改离数据源头更近的那一边，或者改用的人更少的那一边。前者能减少后续的换算层数，后者能减少沟通成本。两条冲突的时候，通常选前者。

加中间层的时候要控制它的数量。每加一层就多一次维护，也多是出错的一个位置。如果发现同一对环节之间加了两三层转换，说明这两段本身的分工可能有问题，值得回头看看是不是该重新划分。

改完之后，把改动写进接口说明，并把说明的版本号加一。同时给下游发一次通知，写清改了什么、什么时候生效。这两件事连在一起做，不要只做一件，只更新不通知等于没改。

历史数据的处理要有一个明确态度。多数情况下是保留原样、标注生效日期，而不是全部重算。重算的成本很高，而且重算之后旧结论和新结论对不上，反而会带来新的混乱。标注是更划算的选择。

处理完之后设定一个复盘时点，通常是一个月。复盘只看一件事：这次改动之后，那类问题还有没有再出现。没有再出现就结束，又出现就说明当时的改法只是把症状盖住了。

有一个细节是关于改动的最小化。能用一句话约定解决的，就不要去改表结构。改表结构会牵动所有用到这张表的地方，范围一大就容易出连带问题。多数接口问题的解法其实就是一句话的事。

边界条件是当两边都坚持自己的做法时。这种情况下，比较实用的做法是先在一个小范围内按一边的做法跑一段时间，拿实际结果来说话。多数关于口径的争论，在真实数据面前很快就会收敛到一个答案。

记录方法上，建议把每次接口调整写成一条变更记录：日期、改了什么、谁提的、影响哪些环节、什么时候生效。几条下来之后，回看这段历史就能明白现在这套口径是怎么一步步形成的，接手的人也更容易理解。

还有一个细节是要给改动留缓冲。今天决定改、今天就生效，下游可能还没来得及调整。通常的做法是提前一到两周通知，给下游一个准备期，重要口径的调整甚至可以留一个月的并行期。

有一个案例是某团队为了解决两段之间的时间错位，没有去改任何一边的统计逻辑，只是在中间加了一列注明取数时点。这一列让下游自己判断数据覆盖到哪一天，两边的争议就此消失了。

接口例检固定下来之后，返工和排查都明显变少

接口的例检节奏

例检可以分两个层次。日常层次的检查很轻，每次取数的时候顺手看一眼行数和总量有没有明显异常，一两分钟就能做完。这个层次解决的是明显的错位，比如某一列整列空了。

定期层次是每季度一次的完整检查。这一天把两段之间的字段逐条对一遍，看有没有新增、有没有不再使用的、有没有含义悄悄变了的。完整检查耗时多一些，但因为只做季度一次，整体负担并不重。

除了这两个层次，还要有触发式的检查。触发条件通常有几个：上游换了工具或者换了取数方式、上游负责人换人、下游发现连续几期数据异常、业务范围有调整比如新开站点或者新上类目。

例检的执行者建议固定。由下游那一方来查更合适，因为接口的问题最先影响的就是下游。让上游自查容易出现自证清白的倾向，让下游来查则会带着实际使用中的疑问，检查的质量通常更高。

例检的记录要留下来。每次查完之后写一段简短的结论：这次查了哪些字段、发现了什么、改了什么。记录积累几次之后，就能看出接口的稳定程度，也能看出哪几处总是反复出问题，那些地方往往需要从设计上重新处理。

日常层次的检查可以做成一个固定动作：每次取完数，先看三件事。行数是不是和上一期在一个量级、总量有没有突然跳变、关键列是不是都非空。三件事加起来一分钟，能拦掉大部分明显的问题。

季度检查可以按一份固定清单来做。清单上列着所有必需字段，逐条标记对上、没对上、含义有变化。这份清单做一次之后，下一次在它上面改就行，不必重新设计检查内容，越做越快。

触发式检查最容易被忘，所以最好是把它挂到一个已有的动作上。比如上游换工具的那一次上线流程里，加一条接口复查。挂在已有动作上，比单独设一个提醒更容易被执行下去。

检查的执行者固定之后，还要给他一个明确的输出要求：查完之后写三行结论，写清查了什么、发现了什么、下一步做什么。有了固定的输出要求，检查才不会流于形式，也不会因为执行者不同而质量忽高忽低。

例检本身也要有调整机制。如果连续几次检查都没发现问题，可以把频率降低一些；如果连续几次都查到同类问题，说明这个接口本身设计得不稳，应该考虑重新处理，而不是靠更频繁的检查去盯。

有一个细节是例检的时点。建议放在一段工作结束、下一段开始之前的那段时间做，这时候两边的注意力都在交接上，发现问题能立刻处理。放在中间做，容易被打断，也容易被当成额外负担。

边界条件是人员变动。换人的时候一定要做一次完整的接口检查，因为很多隐性的约定是跟着人走的，人不在了，约定也就散了。交接单上把接口说明作为一个必交项，能避免这类问题。

记录方法上，建议给每次例检留一行结论，写在接口说明的末尾。写清这次查了什么、改了没有、下次要注意什么。几行积累下来，这份说明本身就变成了一份可以翻阅的历史，比重新写一份文档有用。

还有一个细节是不要在业务最忙的时候做例检。旺季期间接口一旦出问题，影响面会被放大。把例检安排在淡季或者业务平稳期，即使发现问题也有余量去处理，不会造成当期的损失。

有一个案例是团队把接口例检和季度复盘放在一起做，一下午的时间，前半段复盘业务，后半段过一遍接口。两件事合在一起做，省掉了单独找时间的麻烦，也让接口检查变得更容易坚持。

常见问题（FAQ）