hl-api-changelog/changelogs-v2/2026-09/04_7069_供应商企微在途状态统一审核中-修改接口-管理后台.md

schema, ticket, title, consumer, author, change_type, backend_status, gateway_status, frontend_status, frontend_owner, frontend_ref, target_release, verified_at, status_note, updated_at, base

schema	ticket	title	consumer	author	change_type	backend_status	gateway_status	frontend_status	frontend_owner	frontend_ref	target_release	verified_at	status_note	updated_at	base
hl-changelog/v2	7069	供应商企微在途状态统一审核中	admin	lc(GIT)	修改接口	deployed	verified	verified	mmg	f6ddd94c		2026-09-04	后端已部署并通过 TEST；前端需统一展示 statusName。	2026-09-04	dev-v3

供应商模块：企微在途状态统一显示“审核中”

服务: hl-resource-service Issue: #7069 PR: #7072 影响范围: 管理后台供应商列表、详情和状态动作结果

⚠️ 关键变化

前端统一展示新增的 statusName：已提交企业微信且仍在审批中的供应商显示“审核中”，不再把来源生命周期状态作为展示文案；原 status 字段继续用于筛选和业务判断。

二、变更接口清单

#	接口	方法	路径	变更类型	说明
1	供应商分页	GET	/admin/supplier/items/page	响应新增字段	每行新增 statusName
2	供应商有界列表	GET	/admin/supplier/items/list	响应新增字段	每行新增 statusName
3	供应商基本信息	GET	/admin/supplier/items/{supplierId}/basic-info/view	响应新增字段	详情新增 statusName
4	暂停合作	POST	/admin/supplier/items/{supplierId}/suspend	响应新增字段	返回 statusName=暂停合作
5	列入黑名单	POST	/admin/supplier/items/{supplierId}/blacklist	响应新增字段	企微在途返回 statusName=审核中
6	恢复合作	POST	/admin/supplier/items/{supplierId}/resume	响应新增字段	返回 statusName=合作中
7	解除黑名单	POST	/admin/supplier/items/{supplierId}/unblacklist	响应新增字段	企微在途返回 statusName=审核中
8	清账归档	POST	/admin/supplier/items/{supplierId}/archive	响应新增字段	两类企微归档在途均返回“审核中”

三、接口详情

1. 供应商分页 GET /admin/supplier/items/page

VO: SupplierPageReqVO → PageResult<SupplierListItemRespVO>

使用场景

供应商管理分页展示及按生命周期状态筛选。

入参

字段	位置	类型	必填	约束	说明
page / pageSize	Query	Integer	否	page>=1，1<=pageSize<=100	默认 1 / 20
status	Query	String	否	生命周期枚举	仍按原 status 筛选
keyword / typeCode / creditLevel / creatorId	Query	String	否	沿用原约束	其他筛选条件不变

出参 Result<PageResult<SupplierListItemRespVO>>

字段	类型	说明
data.records[].status	String	原生命周期状态码，保持不变
data.records[].statusName	String	对外展示文案；企微审批在途为“审核中”

请求示例

GET /admin/supplier/items/page?page=1&pageSize=20

响应示例

{"code":200,"message":"成功","data":{"records":[{"supplierId":"2095701432631017473","status":"VETTING","statusName":"审核中"}],"total":1,"page":1,"pageSize":20},"success":true}

空数据 / 降级响应

无匹配供应商时 data.records 为空数组，分页元数据仍正常返回。

错误响应

{"code":401,"message":"未登录或登录已过期","data":null,"success":false}

业务边界

• status 仍只接受既有生命周期状态码；“审核中”是展示文案，不作为筛选值。

2. 供应商有界列表 GET /admin/supplier/items/list

VO: SupplierListReqVO → List<SupplierListItemRespVO>

使用场景

下拉选择及有界供应商列表展示。

入参

字段	位置	类型	必填	约束	说明
limit	Query	Integer	否	1～200	默认 50
status	Query	String	否	生命周期枚举	仍按原 status 筛选
keyword / typeCode / resourceModule / resourceId	Query	String	否	沿用原约束	其他筛选条件不变

出参 Result<List<SupplierListItemRespVO>>

字段	类型	说明
data[].status	String	原生命周期状态码，保持不变
data[].statusName	String	对外展示文案；企微审批在途为“审核中”

请求示例

GET /admin/supplier/items/list?limit=50

响应示例

{"code":200,"message":"成功","data":[{"supplierId":"2095701432631017473","status":"VETTING","statusName":"审核中"}],"success":true}

空数据 / 降级响应

无匹配供应商时返回 data=[]。

错误响应

{"code":401,"message":"未登录或登录已过期","data":null,"success":false}

业务边界

• 返回条数仍受 limit 限制；前端展示 statusName，业务判断继续使用 status。

3. 供应商基本信息 GET /admin/supplier/items/{supplierId}/basic-info/view

VO: Void → SupplierBasicInfoRespVO

使用场景

供应商详情页展示当前对外状态。

入参

字段	位置	类型	必填	约束	说明
supplierId	Path	String	是	正整数	供应商 ID

出参 Result<SupplierBasicInfoRespVO>

字段	类型	说明
data.status	String	原生命周期状态码，保持不变
data.statusName	String	对外展示文案；企微审批在途为“审核中”

请求示例

GET /admin/supplier/items/2095701432631017473/basic-info/view

响应示例

{"code":200,"message":"成功","data":{"supplierId":"2095701432631017473","status":"VETTING","statusName":"审核中"},"success":true}

空数据 / 降级响应

供应商不存在时返回业务失败，不返回空成功详情。

错误响应

{"code":395001,"message":"供应商不存在","data":null,"success":false}

业务边界

• 企微审批结束后刷新本接口，即可获得对应终态展示文案。

4. 暂停合作 POST /admin/supplier/items/{supplierId}/suspend

VO: SupplierStatusChangeReqVO → SupplierStatusChangeRespVO

使用场景

将合作中供应商暂停合作。

入参

字段	位置	类型	必填	约束	说明
supplierId	Path	String	是	正整数	供应商 ID
reason	Body	String	是	1～500 字符	状态变更原因
expectedUpdateTime	Body	String	是	yyyy-MM-dd HH:mm:ss	页面读取到的并发版本

出参 Result<SupplierStatusChangeRespVO>

字段	类型	说明
data.status	String	SUSPENDED
data.statusName	String	“暂停合作”

请求示例

{"reason":"暂停合作","expectedUpdateTime":"2026-09-04 10:00:00"}

响应示例

{"code":200,"message":"成功","data":{"supplierId":"2095000000000000001","status":"SUSPENDED","statusName":"暂停合作"},"success":true}

空数据 / 降级响应

写接口不返回空成功数据；执行失败时状态不变。

错误响应

{"code":395014,"message":"数据已被他人修改，请刷新后重试","data":null,"success":false}

业务边界

• 权限、允许状态、并发版本及幂等规则均保持不变。

5. 列入黑名单 POST /admin/supplier/items/{supplierId}/blacklist

VO: SupplierStatusChangeReqVO → SupplierStatusChangeRespVO

使用场景

对暂停合作供应商发起列入黑名单企微审批。

入参

字段	位置	类型	必填	约束	说明
supplierId	Path	String	是	正整数	供应商 ID
reason	Body	String	是	1～500 字符	列入黑名单原因
expectedUpdateTime	Body	String	是	yyyy-MM-dd HH:mm:ss	页面读取到的并发版本

出参 Result<SupplierStatusChangeRespVO>

字段	类型	说明
data.status	String	审批中仍为 SUSPENDED
data.statusName	String	审批中为“审核中”
data.approval.approvalStatus	String	审批中为 PENDING

请求示例

{"reason":"严重违约","expectedUpdateTime":"2026-09-04 10:00:00"}

响应示例

{"code":200,"message":"成功","data":{"supplierId":"2095000000000000002","status":"SUSPENDED","statusName":"审核中","approval":{"provider":"WECOM","approvalStatus":"PENDING","spNo":"202609040001"}},"success":true}

空数据 / 降级响应

写接口不返回空成功数据；企微提交失败时保持暂停合作。

错误响应

{"code":395005,"message":"当前状态不允许执行该操作","data":null,"success":false}

业务边界

• 审批通过后刷新查询接口显示“黑名单”，驳回后显示“暂停合作”。

6. 恢复合作 POST /admin/supplier/items/{supplierId}/resume

VO: SupplierStatusChangeReqVO → SupplierStatusChangeRespVO

使用场景

将暂停合作供应商恢复合作。

入参

字段	位置	类型	必填	约束	说明
supplierId	Path	String	是	正整数	供应商 ID
reason	Body	String	是	1～500 字符	状态变更原因
expectedUpdateTime	Body	String	是	yyyy-MM-dd HH:mm:ss	页面读取到的并发版本

出参 Result<SupplierStatusChangeRespVO>

字段	类型	说明
data.status	String	ACTIVE
data.statusName	String	“合作中”

请求示例

{"reason":"恢复合作","expectedUpdateTime":"2026-09-04 10:00:00"}

响应示例

{"code":200,"message":"成功","data":{"supplierId":"2095000000000000003","status":"ACTIVE","statusName":"合作中"},"success":true}

空数据 / 降级响应

写接口不返回空成功数据；执行失败时状态不变。

错误响应

{"code":395014,"message":"数据已被他人修改，请刷新后重试","data":null,"success":false}

业务边界

• 权限、允许状态、并发版本及幂等规则均保持不变。

7. 解除黑名单 POST /admin/supplier/items/{supplierId}/unblacklist

VO: SupplierStatusChangeReqVO → SupplierStatusChangeRespVO

使用场景

对黑名单供应商发起解除黑名单企微审批。

入参

字段	位置	类型	必填	约束	说明
supplierId	Path	String	是	正整数	供应商 ID
reason	Body	String	是	1～500 字符	解除原因
expectedUpdateTime	Body	String	是	yyyy-MM-dd HH:mm:ss	页面读取到的并发版本

出参 Result<SupplierStatusChangeRespVO>

字段	类型	说明
data.status	String	审批中仍为 BLACKLIST
data.statusName	String	审批中为“审核中”
data.approval.approvalStatus	String	审批中为 PENDING

请求示例

{"reason":"整改完成","expectedUpdateTime":"2026-09-04 10:00:00"}

响应示例

{"code":200,"message":"成功","data":{"supplierId":"2095000000000000004","status":"BLACKLIST","statusName":"审核中","approval":{"provider":"WECOM","approvalStatus":"PENDING","spNo":"202609040002"}},"success":true}

空数据 / 降级响应

写接口不返回空成功数据；企微提交失败时保持黑名单。

错误响应

{"code":395005,"message":"当前状态不允许执行该操作","data":null,"success":false}

业务边界

• 审批通过后刷新查询接口显示“暂停合作”，驳回后显示“黑名单”。

8. 清账归档 POST /admin/supplier/items/{supplierId}/archive

VO: Void → SupplierArchiveRespVO

使用场景

暂停合作供应商发起“终止且账清”，或黑名单供应商发起“拉黑且账清”企微审批。

入参

字段	位置	类型	必填	约束	说明
supplierId	Path	String	是	正整数	供应商 ID

出参 Result<SupplierArchiveRespVO>

字段	类型	说明
data.status	String	审批中保持 SUSPENDED 或 BLACKLIST
data.statusName	String	两类审批在途均为“审核中”
data.approval.approvalStatus	String	审批中为 PENDING

请求示例

POST /admin/supplier/items/2095000000000000005/archive

响应示例

{"code":200,"message":"成功","data":{"supplierId":"2095000000000000005","status":"SUSPENDED","statusName":"审核中","approval":{"provider":"WECOM","approvalStatus":"PENDING","spNo":"202609040003"}},"success":true}

空数据 / 降级响应

写接口不返回空成功数据；企微提交失败时保持来源状态。

错误响应

{"code":395021,"message":"企业微信申请提交失败，请稍后重试","data":null,"success":false}

业务边界

• 两类审批通过后刷新查询接口均显示“已归档”；驳回后分别显示“暂停合作”或“黑名单”。

四、契约约束与正确调用方式

• 请求参数、鉴权、权限、幂等和错误码均不变。
• status 是生命周期状态码，继续用于筛选、按钮门禁和业务判断；statusName 是中文展示值。
• 状态动作成功后先使用响应中的 statusName，后续刷新分页、列表或详情获取审批终态。

五、数据库行为

本次不修改数据结构和状态迁移规则；写接口原有业务写入、失败零写入及并发规则不变，仅在响应中增加展示字段。

六、边界行为

• 注册审批中：status=VETTING，statusName=审核中。
• 企业微信状态审批仅在 provider=WECOM、approvalStatus=PENDING 且已有审批单号时覆盖展示为“审核中”。
• 审批结束后按当前生命周期状态展示，不继续显示“审核中”。
• 未登录时统一返回业务码 401；其他错误码保持不变。

六.5、枚举 / 数据字典

原状态或审批条件	statusName
注册审批中 VETTING	审核中
企微状态审批在途	审核中
DRAFT	草稿
ACTIVE	合作中
SUSPENDED 且无在途审批	暂停合作
BLACKLIST 且无在途审批	黑名单
ARCHIVED	已归档

六.6、修改前后对比

字段级对比

字段	改前	改后
statusName	不返回	列表、详情及五个状态动作响应返回中文展示值
status	生命周期状态码	保持不变

行为级对比

行为	改前	改后
企微审批在途展示	可能继续显示来源状态	统一显示“审核中”
审批完成展示	读取生命周期状态	保持按最终生命周期状态展示

六.7、影响评估

• 是否破坏向后兼容: 否，响应仅新增字段，原 status 保留。
• 前端是否必须同步上线: 是，需改为展示 statusName。
• 前端 workaround 清理点: 删除前端自行翻译 status 作为展示文案的逻辑。

七、不影响范围

• 仅影响: 管理后台供应商状态文案展示。
• 零影响: 生命周期状态机、审批通过或驳回迁移、请求参数、权限、数据库结构、配置、Redis 和 MQ。

八、测试环境已验证

• 分页、列表和详情均返回 statusName；注册审批中返回“审核中”，稳定态分别返回草稿、合作中、暂停合作、黑名单和已归档。
• 四类企微状态审批的完成态与来源状态一致；未登录请求返回业务码 401。

十、相关文档

• Issue #7069
• PR #7072

前端动作与当前状态

• 列表、详情和动作结果统一展示 statusName；保留 status 做筛选和按钮门禁。
• 状态动作后刷新列表或详情，以最新 statusName 展示审批终态。
• 当前状态：待前端适配。

关联 / 联系人

• Issue: #7069
• PR: #7072
• Merge commit: c95f1de495d4bcdd8579ccd1f0c895deca29e14a
• 后端负责人: @lc