读用 SQL,写用对象模型
读一次取回、不翻页;写走对象模型,新建后回查拿到自动编号。写法细节以 x-api 规范为准。
SUPPLIER · 04 SERVICE
28 个云函数,全部只给后台调、全部要登录。读走 SQL 一次取回,写走对象模型;排序号、文件清理、重复绑定这几件事在服务端做,地址坐标、合作状态联动这几件事却在后台聚合层做 —— 直接调接口的人绕得过去。
住 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 | 读 | 全部品牌平铺返回(不建树) |
读一次取回、不翻页;写走对象模型,新建后回查拿到自动编号。写法细节以 x-api 规范为准。
没有「删一个」「删一批」两套接口;后台删一家就传一个元素的数组。
没有任何一个接口只返回「正式合作的供应商」或「启用的品牌」。下游要用,今天只能自己拿全量再判断 —— 而下游一个都没判断。
其余函数都是标准写法,这里只讲与众不同、或者与文档对不上的地方。
合作状态不传就写「待审核」,派单优先级不传就写「正常派单」(supplier-create/repo.js:50,55);排序号追加到全表末尾(:62)。而企业类型、服务类目、服务模式、覆盖区域这几项数据库必填,参数校验里全是可选(controller.js:21,35,37,38)。
先读出 Logo 与全部证照图 → 删联系人、删证照、删主档 → 删文件(supplier-delete/service.js:9-23)。绑定表里这家的行一条都不删,下游有没有在用这家也不查。
供应商 Logo、证照图、品牌 Logo 与授权证书都是这个顺序:先算出被移除的旧文件,写库成功后再删;写库失败时旧文件原样保留。新建时不走这一步(前端先建记录、再传图、再回写)。
顺序以 x-file 规范为准先查这一对是否已经绑过,绑过就报「以下品牌已绑定,请勿重复绑定:…」,没绑过就分批写入(supplier-brands-bind/service.js、repo.js:5-19)。不查供应商与品牌是否真实存在,表文档要求的「插入前校验供应商存在」没做(表文档 2026-09-24 已补注为代码缺口)。数据库有「同一对不许重复」的联合唯一兜底。
品牌按名字反查成编号,查不到的名字静默丢掉(supplier-import/repo.js:83-92);联系人与证照先按供应商删光、再逐条新建(syncChildTable)。证照子项的参数里没有图片字段(controller.js:67-78),所以每导入一次,已有证照的图片就被清空,旧图片文件也不删。排序号取文件里带的值(controller.js:54,可选),文件里没有就不补 —— 拖拽专属的排序号,从导入这条路可以被手工改写。
主表一次读出,三张子表按全部供应商编号各读一次,品牌按编号反查名字,再在内存里按供应商挂好(supplier-export/repo.js:62-104)。分组先按全部编号预建空数组,没有子记录的就是空数组。
整张表读出、过滤、建树、按排序号排(brand-read/repo.js:52-69)。父编号找不到的节点当根;以自己为父、或几个品牌互为父的,谁都不是根,会从树里整支消失。服务端新建、编辑都不拦这两种写法。
一组品牌一次改状态(brand-status-toggle),不连带子品牌,也不通知任何下游。下游选择与小程序读取都不按状态过滤,所以今天禁用一个品牌,在后台列表之外没有任何效果。
参数里的供应商编号必填,注释说「用于权限校验」,但数据层把它原样写回(supplier-contacts-update/repo.js:12,15),没有任何「这个联系人是否属于这家」的检查 —— 改一次就能把联系人挂到另一家。「主要联系人」也没有唯一约束。
这个域最该注意的是一批规则只在后台聚合层:它们对后台界面成立,对直接调云函数的人不成立。
| 这件事 | 在哪一层 | 为什么在那里 | 放错层 / 缺层会怎样 |
|---|---|---|---|
| 地址坐标解析 | 后台聚合层 | 保存适配器对注册、办公两组地址各解析一次(supplier.bff.ts:233,236),服务端零解析、三字段原样收 | 直接调更新接口改了地址而不传坐标,坐标就停在旧值 |
| 区划对象转成文本 | 后台聚合层 | 写侧唯一一处序列化(:239),读侧由读接口解析回对象 | 约定见 x-address 规范 |
| 非暂停 / 终止时清空禁用原因 | 后台聚合层 | supplier.bff.ts:229-231 | 服务端不管,直接调接口可以留下与状态矛盾的禁用原因 |
| 子表模式守卫 | 后台聚合层 | 联系人、证照必须是行编辑,品牌必须是关联选择,不对就报系统错误(:244-258) | 配置写错时当场报错,不静默丢数据 |
| 合作状态与派单优先级的默认值 | 服务端数据层 | supplier-create/repo.js:50,55 | 表文档说「禁止默认值」,这里给了 |
| 排序号追加与重排 | 服务端 | 新建时追加、拖拽后一次重写,新建与更新的入参里不收排序号 | 导入接口例外:它收文件里的排序号(F-05) |
| 重复绑定 | 服务端 + 数据库 | 接口先查,数据库联合唯一再兜一次 | 两道都在 |
| 父品牌是否合法 | 没有任何一层 | 前端下拉只列根品牌(页面打开时读一次),编辑根品牌时下拉里包括它自己;服务端不查存在与成环 | 坏数据只会在读的时候表现为「品牌不见了」 |
| 数据库必填的 8 项 | 只有数据库 | 前端只要求全称与简称,参数校验把其余几项放成可选 | 运行时是被数据库拒还是留空,未核 |
这一节的结论:本域有四条业务规则只靠后台界面成立(坐标跟着地址走、禁用原因跟着状态走、父品牌不能成环、必填项必须填)。今天只有后台一个调用方,影响有限;一旦有第二个写入方(导入脚本、别的系统),这四条都要下沉到服务端。
28 个函数的包配置逐个核过:公开访问与「登录即可调」两个开关全部为否,一律按角色授权。
供应商与品牌是内部主数据,没有任何一条需要在未登录时被读到。小程序看到的名字与图标,是商品域的读接口顺手从这两张表里取出来的。
开了列级过滤的是 supplier-read、supplier-contacts-read、supplier-certificates-read、brand-read;supplier-info-read 没开,而详情页的数据取自它。详情页界面会按 supplier-read 的列权限把看不到的字段藏掉,所以界面上这条成立;缺口在接口层 —— 返回体里仍带着全部列,打开开发者工具或直接调接口就能拿到表文档写着「仅管理员可见」的信用代码、法定代表人、合作状态等。
本域自己的函数只读写自己的五张表。反过来读本域的地方有七处,它们都只认「提供者编号」这一个字段。
| 依赖 | 归谁 | 什么时候用到 |
|---|---|---|
| 文件上传 | 文件工具 | 供应商 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 条)。
先列文档与代码对不上的地方(以代码为准),再列代码自身的问题。本轮一条代码都不改,编号与架构设计页边界一节一致。
| # | 文档怎么说 | 代码实际怎样 | 证据 |
|---|---|---|---|
| 1 | 本域 ARCH.md:订单引用在 order_base.supplierId | 在订单行 order_item_node.supplierId,由下单接口从 SKU 取 | order_item_node.md:18 · order-create/service.js:138(ARCH.md 已订正) |
| 2 | supplier_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 已订正 |
| 4 | supplier_brand_relation.md:31-32:插入前查供应商存在、删供应商前查绑定 | 两件都没做 | supplier-brands-bind/service.js · supplier-delete/service.js:16-18。表文档 :31 已补注「当前未实现,登记为代码缺口」(2026-09-24) |
| 5 | supplier_base.md:80-88:若干字段「仅管理员可见」 | 界面按 supplier-read 的列权限藏字段,成立;详情读接口没开列级过滤,返回体带全部列 | supplier-info-read/package.json · detail.tsx:86-88 |
| 6 | 品牌名 64、品牌简介 2000 / 4096、企业介绍 2000 / 4096 | 品牌三个写接口:品牌名 100、品牌简介 512 | brand-create/controller.js:16,28(update、import 同)。品牌简介 ✅ 2026-09-24 已订正,三个接口都限 512;企业介绍新建、编辑限 2000,导入接口不限长(supplier-import/controller.js:22),登记为代码缺口;品牌名 64 与 100 仍对不上 |
| 7 | brand_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 已订正,资质证照与品牌的示例同批订正 |
| 9 | sop_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) |
终止合作、禁用品牌在所有选择与读取里照常出现。要不要「终止即不可选」是业务决定,本轮只登记。
详情保存逐个调接口(supplier.bff.ts:107-185),中途失败留半截。
见 F-05。读代码推断,未实跑。
删供应商、删品牌都留下绑定行。后台界面删父品牌会级联删整棵子树;直接调 brand-delete、走导入里的删除,或勾了父品牌又单独取消某个子品牌时,子品牌的父编号悬空、浮成根品牌。
界面上编辑根品牌时能选它自己;服务端不拦自指与成环,直接调接口能写进去;读接口建树时这类品牌整支消失(F-07)。父品牌下拉只在页面打开时读一次。
见 F-09;「主要联系人」也可以有多个。
品牌状态切换成功时显示「商品上架状态切换成功」(brand.tsx:291 取的键写的是「商品上架状态」)。
左栏搜索按企业全称匹配(supplier.tsx:641),而列表大字是简称。
「自有设备清单」「品类明细」只在导入导出里,详情页没有。
品牌顶部新增表单里「授权状态」是必填开关、没给初始值(brand.tsx:500-506);不碰它时显示「未授权」、值却是空的,会被必填规则拦下。行尾「+」那张表单预填了 false(:651)。读代码推断,未实跑。