SUPPLIER · 04 SERVICE

供给方域 · 服务设计

28 个云函数,全部只给后台调、全部要登录。读走 SQL 一次取回,写走对象模型;排序号、文件清理、重复绑定这几件事在服务端做,地址坐标、合作状态联动这几件事却在后台聚合层做 —— 直接调接口的人绕得过去。

版本 v0.3.1复核 2026-09-24端 服务端 + 管理端
01

服务全景:28 个函数,五组

住 x-server/admin/supplier/{base,contact,certificate,brand}/ 与 x-server/admin/brand/base/。没有一个给小程序。

组云函数读写它做什么
供应商主档
8 个
supplier-read读全部供应商,按排序号排;左栏列表用;开了列级过滤
supplier-info-read读按编号取一家,查不到报错;详情页用;没开列级过滤
supplier-create写新建一行:排序号追加到末尾,合作状态与派单优先级缺省时给默认值
supplier-update写改主档;Logo 换了就在写库后删旧图
supplier-delete写删主档连同联系人、证照,再删它们的图片文件
supplier-order-update写拖拽之后一次重写全部排序号
supplier-import写一家一次:新增或覆盖;联系人、证照整组替换;品牌按名字反查成编号
supplier-export读全部供应商连同三张子表一次返回
联系人
5 个
supplier-contacts-read读按供应商取,按排序号排;开了列级过滤
supplier-contacts-create / update / delete / order-update写新建时按所属供应商追加排序号;删除收一组编号
资质证照
5 个
supplier-certificates-read读按供应商取,按排序号排,证照图字段解析成数组;开了列级过滤
supplier-certificates-create / update / delete / order-update写改证照图时写库后删旧图;删证照时删图
品牌绑定
3 个
supplier-brands-read读连表取这家供应商绑定的品牌详情,超过 2000 条报错
supplier-brands-bind写先查这一对是否已绑,再批量写
supplier-brands-unbind写批量删绑定行
品牌
7 个
brand-read读整棵读出,可按名称、类型、授权、状态、产地筛,内存建树、按排序号排;开了列级过滤
brand-create写新建;排序号由表单手工传
brand-update写改品牌;Logo、授权证书换了删旧图
brand-delete写只删传进来的这些编号与它们的两张图;不查子品牌、不动绑定行(后台界面删父品牌时会把整棵子树的编号一起传进来)
brand-status-toggle写一组品牌一次改成启用或禁用
brand-import写一条一次:新增或覆盖
brand-export读全部品牌平铺返回(不建树)
读写分开

读用 SQL,写用对象模型

读一次取回、不翻页;写走对象模型,新建后回查拿到自动编号。写法细节以 x-api 规范为准。

批量是默认

删除、解绑、切换都收一组编号

没有「删一个」「删一批」两套接口;后台删一家就传一个元素的数组。

没有的

「按状态取可用的提供者」

没有任何一个接口只返回「正式合作的供应商」或「启用的品牌」。下游要用,今天只能自己拿全量再判断 —— 而下游一个都没判断。

02

逐个服务:值得单独讲的九条

其余函数都是标准写法,这里只讲与众不同、或者与文档对不上的地方。

F-01

新建供应商 · 服务端替你填了两个默认值

合作状态不传就写「待审核」,派单优先级不传就写「正常派单」(supplier-create/repo.js:50,55);排序号追加到全表末尾(:62)。而企业类型、服务类目、服务模式、覆盖区域这几项数据库必填,参数校验里全是可选(controller.js:21,35,37,38)。

与表文档「禁止默认值」相反
F-02

删供应商 · 三段式,但不碰绑定表

先读出 Logo 与全部证照图 → 删联系人、删证照、删主档 → 删文件(supplier-delete/service.js:9-23)。绑定表里这家的行一条都不删,下游有没有在用这家也不查。

留孤儿绑定行
F-03

改图 · 写库前算差集,写库后删旧图

供应商 Logo、证照图、品牌 Logo 与授权证书都是这个顺序:先算出被移除的旧文件,写库成功后再删;写库失败时旧文件原样保留。新建时不走这一步(前端先建记录、再传图、再回写)。

顺序以 x-file 规范为准
F-04

绑品牌 · 查重不查存在

先查这一对是否已经绑过,绑过就报「以下品牌已绑定,请勿重复绑定:…」,没绑过就分批写入(supplier-brands-bind/service.js、repo.js:5-19)。不查供应商与品牌是否真实存在,表文档要求的「插入前校验供应商存在」没做(表文档 2026-09-24 已补注为代码缺口)。数据库有「同一对不许重复」的联合唯一兜底。

查重有两道
F-05

导入供应商 · 子表整组替换,证照图不在字段里

品牌按名字反查成编号,查不到的名字静默丢掉(supplier-import/repo.js:83-92);联系人与证照先按供应商删光、再逐条新建(syncChildTable)。证照子项的参数里没有图片字段(controller.js:67-78),所以每导入一次,已有证照的图片就被清空,旧图片文件也不删。排序号取文件里带的值(controller.js:54,可选),文件里没有就不补 —— 拖拽专属的排序号,从导入这条路可以被手工改写。

静态推断 · 未实跑
F-06

导出供应商 · 一次读出,内存挂子表

主表一次读出,三张子表按全部供应商编号各读一次,品牌按编号反查名字,再在内存里按供应商挂好(supplier-export/repo.js:62-104)。分组先按全部编号预建空数组,没有子记录的就是空数组。

一次成型
F-07

品牌读 · 内存建树,坏父编号的节点会丢

整张表读出、过滤、建树、按排序号排(brand-read/repo.js:52-69)。父编号找不到的节点当根;以自己为父、或几个品牌互为父的,谁都不是根,会从树里整支消失。服务端新建、编辑都不拦这两种写法。

静态推断 · 未实跑
F-08

品牌状态切换 · 只改自己

一组品牌一次改状态(brand-status-toggle),不连带子品牌,也不通知任何下游。下游选择与小程序读取都不按状态过滤,所以今天禁用一个品牌,在后台列表之外没有任何效果。

状态只是标签
F-09

改联系人 · 供应商编号一并写回

参数里的供应商编号必填,注释说「用于权限校验」,但数据层把它原样写回(supplier-contacts-update/repo.js:12,15),没有任何「这个联系人是否属于这家」的检查 —— 改一次就能把联系人挂到另一家。「主要联系人」也没有唯一约束。

风险在直接调接口
03

关键逻辑在哪一层算

这个域最该注意的是一批规则只在后台聚合层:它们对后台界面成立,对直接调云函数的人不成立。

这件事在哪一层为什么在那里放错层 / 缺层会怎样
地址坐标解析后台聚合层保存适配器对注册、办公两组地址各解析一次(supplier.bff.ts:233,236),服务端零解析、三字段原样收直接调更新接口改了地址而不传坐标,坐标就停在旧值
区划对象转成文本后台聚合层写侧唯一一处序列化(:239),读侧由读接口解析回对象约定见 x-address 规范
非暂停 / 终止时清空禁用原因后台聚合层supplier.bff.ts:229-231服务端不管,直接调接口可以留下与状态矛盾的禁用原因
子表模式守卫后台聚合层联系人、证照必须是行编辑,品牌必须是关联选择,不对就报系统错误(:244-258)配置写错时当场报错,不静默丢数据
合作状态与派单优先级的默认值服务端数据层supplier-create/repo.js:50,55表文档说「禁止默认值」,这里给了
排序号追加与重排服务端新建时追加、拖拽后一次重写,新建与更新的入参里不收排序号导入接口例外:它收文件里的排序号(F-05)
重复绑定服务端 + 数据库接口先查,数据库联合唯一再兜一次两道都在
父品牌是否合法没有任何一层前端下拉只列根品牌(页面打开时读一次),编辑根品牌时下拉里包括它自己;服务端不查存在与成环坏数据只会在读的时候表现为「品牌不见了」
数据库必填的 8 项只有数据库前端只要求全称与简称,参数校验把其余几项放成可选运行时是被数据库拒还是留空,未核

这一节的结论:本域有四条业务规则只靠后台界面成立(坐标跟着地址走、禁用原因跟着状态走、父品牌不能成环、必填项必须填)。今天只有后台一个调用方,影响有限;一旦有第二个写入方(导入脚本、别的系统),这四条都要下沉到服务端。

04

对外与免登录接口:一个都没有

28 个函数的包配置逐个核过:公开访问与「登录即可调」两个开关全部为否,一律按角色授权。

现状

零公开接口

供应商与品牌是内部主数据,没有任何一条需要在未登录时被读到。小程序看到的名字与图标,是商品域的读接口顺手从这两张表里取出来的。

列级过滤

四个读开了,详情读没开

开了列级过滤的是 supplier-read、supplier-contacts-read、supplier-certificates-read、brand-read;supplier-info-read 没开,而详情页的数据取自它。详情页界面会按 supplier-read 的列权限把看不到的字段藏掉,所以界面上这条成立;缺口在接口层 —— 返回体里仍带着全部列,打开开发者工具或直接调接口就能拿到表文档写着「仅管理员可见」的信用代码、法定代表人、合作状态等。

05

域外依赖:本域读谁,谁读本域

本域自己的函数只读写自己的五张表。反过来读本域的地方有七处,它们都只认「提供者编号」这一个字段。

本域用到的外部能力

依赖归谁什么时候用到
文件上传文件工具供应商 Logo、证照图、品牌 Logo 与授权证书的上传(后台聚合层调)
地理编码地图工具保存供应商时解析两组地址的坐标(后台聚合层调)
行政区划树地图工具页面加载时预取,供覆盖区域多选与导入反查共用

读本域、引用本域的地方都只看编号,不看状态

谁归谁怎么用本域校验到哪一步
spu-suppliers-bind服务管理给商品绑提供者编号格式 ^(SUP|BRD)\d{29}$ + 在对应表里存在(controller.js:16)
spu-suppliers-read服务管理列出商品的提供者:BRD 取品牌名与品牌 Logo、公司栏写「品牌方」;SUP 取简称、Logo、全称不过滤状态
sku-maintenance-update服务管理一条「商品 × 提供者」的供给单元编号格式 + 该商品确实绑了这个提供者(controller.js:16)
order-create订单域把提供者编号从 SKU 带出,冻结在订单行上前端不许传,服务端从 SKU 取(service.js:138)
sop-steps-create服务标准「商品 + 提供者」这一对编一套标准只校验非空,不查格式、不查存在(controller.js:16)
service-browse-read、sku-detail-read商品域(小程序读)按编号前缀分流,BRD 取品牌名与 Logo,SUP 取简称与 Logo不过滤状态
服务管理、服务标准的后台聚合层各自模块「选供应商 / 品牌」弹窗:品牌平铺聚合 + supplier-read,名字同样是品牌名与简称不过滤状态

「供给方」这个概念在七处的用法是一致的:都是一个 SUP / BRD 多态编号,显示名一律「品牌取品牌名、供应商取简称」。不一致的是校验强度:商品绑定查格式与存在,服务管理查格式与关系,服务标准只查非空;表文档里的描述口径原先也不一致(服务标准的步骤主表只写了供应商一种),2026-09-24 已订正(见下一节第 9 条)。

06

已知问题

先列文档与代码对不上的地方(以代码为准),再列代码自身的问题。本轮一条代码都不改,编号与架构设计页边界一节一致。

文档说的与代码对不上

#文档怎么说代码实际怎样证据
1本域 ARCH.md:订单引用在 order_base.supplierId在订单行 order_item_node.supplierId,由下单接口从 SKU 取order_item_node.md:18 · order-create/service.js:138(ARCH.md 已订正)
2supplier_base.md:192(订正前;订正后订单行在第 193 行):order_order_info.supplierId 引用本表没有这张表x-data 下查无此文件。✅ 2026-09-24 已订正 改成订单行 order_item_node.supplierId 并补全现役下游
3数据源必填 8 项;supplier_base.md:69「禁止默认值」新建接口五项可选;服务端给两个默认值;界面只收两项supplier-create/controller.js:21,35,37,38,44 · repo.js:50,55。表文档 :95 把可空的法定代表人列为必填那一处 ✅ 2026-09-24 已订正
4supplier_brand_relation.md:31-32:插入前查供应商存在、删供应商前查绑定两件都没做supplier-brands-bind/service.js · supplier-delete/service.js:16-18。表文档 :31 已补注「当前未实现,登记为代码缺口」(2026-09-24)
5supplier_base.md:80-88:若干字段「仅管理员可见」界面按 supplier-read 的列权限藏字段,成立;详情读接口没开列级过滤,返回体带全部列supplier-info-read/package.json · detail.tsx:86-88
6品牌名 64、品牌简介 2000 / 4096、企业介绍 2000 / 4096品牌三个写接口:品牌名 100、品牌简介 512brand-create/controller.js:16,28(update、import 同)。品牌简介 ✅ 2026-09-24 已订正,三个接口都限 512;企业介绍新建、编辑限 2000,导入接口不限长(supplier-import/controller.js:22),登记为代码缺口;品牌名 64 与 100 仍对不上
7brand_base.md:20:品牌类型可多选后台只能单选brand.tsx:507-517。上一版把它记成表文档错,登记错了:数据契约就是多选(数据源是数组、brand-create/controller.js:20 收数组),只是后台表单只做了单选
8表文档示例写 SBAS…、BRND…、'yes'真实是 SUP、BRD、布尔值supplier_contact_node.md:76,82 · supplier_brand_relation.md:53,66。✅ 2026-09-24 已订正,资质证照与品牌的示例同批订正
9sop_step_node.md:137(订正前;订正后在第 138 行):只关联供应商表引用是 SUP / BRD 多态sop_step_node.md:15 自己的字段表写的是多态。✅ 2026-09-24 已订正 上游段改写为多态。spu_sku_node.md:16 同样这么写,但它是整表废弃、待清理的遗留表,不算现役出入
10本域 ARCH.md 的 supplier.tsx 行号、「品牌 11 列」锚点漂移十余行,品牌 10 列ARCH.md 已订正
11日期字段:数据库是日期数字新建接口收文本、更新接口收数字,两边不一样supplier-create/controller.js:25,26,48 · supplier-update/controller.js:25,26,48;品牌授权到期日期新建、更新都收文本(brand-create/controller.js:25)

代码自身的问题

问题 1

下游不看状态

终止合作、禁用品牌在所有选择与读取里照常出现。要不要「终止即不可选」是业务决定,本轮只登记。

问题 2

一次保存无事务

详情保存逐个调接口(supplier.bff.ts:107-185),中途失败留半截。

问题 3

导入清空证照图、丢未知品牌

见 F-05。读代码推断,未实跑。

问题 4

删除不收尾

删供应商、删品牌都留下绑定行。后台界面删父品牌会级联删整棵子树;直接调 brand-delete、走导入里的删除,或勾了父品牌又单独取消某个子品牌时,子品牌的父编号悬空、浮成根品牌。

问题 5

父品牌不设防

界面上编辑根品牌时能选它自己;服务端不拦自指与成环,直接调接口能写进去;读接口建树时这类品牌整支消失(F-07)。父品牌下拉只在页面打开时读一次。

问题 6

改联系人能换主

见 F-09;「主要联系人」也可以有多个。

问题 7

成功提示用错标签

品牌状态切换成功时显示「商品上架状态切换成功」(brand.tsx:291 取的键写的是「商品上架状态」)。

问题 8

搜索只认全称

左栏搜索按企业全称匹配(supplier.tsx:641),而列表大字是简称。

问题 9

两个字段界面上改不了

「自有设备清单」「品类明细」只在导入导出里,详情页没有。

问题 10

授权状态开关没有初始值

品牌顶部新增表单里「授权状态」是必填开关、没给初始值(brand.tsx:500-506);不碰它时显示「未授权」、值却是空的,会被必填规则拦下。行尾「+」那张表单预填了 false(:651)。读代码推断,未实跑。