front/docs/itfx枚举说明.md
zzh 76d8b473b6 feat: 查价下单加固、待排货 UI 与 EnableStatus 对齐
查价参考价提示与可选尺寸;下单尺寸必填及查价带入;待排货状态展示;货物属性/启用状态工具化及相关页面更新。

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-07-22 19:00:56 +08:00

27 KiB
Raw Blame History

itfx(接口通)枚举说明

本文档含两部分:itfx 接口通枚举(下文)与 OMS 数据字典枚举(见文末「OMS 数据字典枚举说明」)。

与后端 itfx-master / InterfaceForward.Domain.Shared.Enum 保持一致。
前端常量见 src/constants/itfxEnums.ts。


获取方式

运行时(下拉选项)

GET api/Dictionary/GetList?type={枚举名}

返回:

[
  { "key": 1, "value": "String" }
]
  • 有 [Description] 的枚举成员,value 取 Description
  • 否则 value 取枚举成员名

编译期(TypeScript 常量)

import {
  FieldPosition,
  ParameterType,
  ItfxDictionaryType,
} from '@/constants/itfxEnums';

枚举总览

枚举名 Dictionary type 用途
ServiceProviderType ✅ 服务商类型
RequestProtocol ✅ 请求协议
RequestMethod ✅ HTTP 方法
ContentType ✅ 请求 Content-Type
ResponseContentType ✅ 响应 Content-Type
ParameterType ✅ 参数数据类型
ParameterPlaceholder ✅ 固定参数占位符
ParameterParseTypeEnum ✅ 参数解析格式
FieldPosition ✅ 字段位置
FieldOwner ❌ 字段所属(仅 DTO)
AuthParameterFlag ✅ 授权参数标识
EffectTimeUnit ✅ Token 有效时间单位
InterfaceReturnConfigType ✅ 接口返回配置
LabelType ✅ 标签类型
OptionType ✅ 增删改操作
LogListInputTypeEnum ✅ 日志筛选

1. 服务商 / 接口基础

ServiceProviderType — 服务商类型

值 名称
1 运输服务商
2 轨迹服务商
3 关务服务商
4 保险服务商

RequestProtocol — 请求协议

值 名称
1 Http
2 Https
3 WCF
4 SOAP

RequestMethod — HTTP 方法

值 名称
1 GET
2 POST
3 PUT
4 DELETE
5 OPTIONS
6 HEAD
7 PATCH

2. 请求 / 响应 Content-Type

ContentType — 请求体类型

值 名称 脚本注意
1 FormUrlEncoded 用 obj.FormFieldList
2 FormData 表单上传
3 Json 用 obj.OriginalInterfaceMappedInput
4 Xml XML 请求体
0 None 无 HTTP Body,仅 Query / Header

ResponseContentType — 响应体类型

值 名称
1 Json
2 Xml
3 pdf
4 Base64
5 csv

3. 参数相关

ParameterType — 参数数据类型

值 名称
1 String
2 Float
3 Object
4 Boolean
5 Array
6 Integer
7 DateTime
8 DateTimeOffset

ParameterPlaceholder — 固定参数占位符

值 枚举名 实际占位符
1 FromAccount $FromAccount
2 FromBody $FromBody
3 TimeStamp $TimeStamp
4 DateTime $DateTime
5 Url $Url
6 Token $token

占位符在 ReplacePlaceholder 阶段替换,早于 PrefixScript 执行。

ParameterParseTypeEnum — 参数解析类型

值 名称
1 Json
2 Xml

FieldPosition — 字段位置

值 名称 说明
1 Header 请求头
2 Body 请求体
3 Query Query 参数
4 Url URL 路径
5 Nothing 不处理

前置脚本示例(Header):

for (int i = 0; i < obj.FixedFieldList.Count; i++) {
    if (obj.FixedFieldList[i].FieldPosition == 1
        && obj.FixedFieldList[i].FieldName == "sign") {
        obj.FixedFieldList[i].FieldValue = sign;
        break;
    }
}

FieldOwner — 字段所属

itfx 遗留枚举,0 为 ServiceProvider 业务值(非 None)。OMS 自有数值字典不适用此规则。

值 名称
0 ServiceProvider
1 Interface
2 AuthConfig

4. 授权 / Token

AuthParameterFlag — 授权参数标识

值 名称 说明
1 InParameter 入参
2 Token 授权令牌
3 EffectTime 有效时间
4 FixedEffectTime 固定有效时间
5 PrefixScript 前置脚本
6 PostfixScript 后置脚本

EffectTimeUnit — 有效时间单位

值 名称
1 Second
2 Minute
3 Hour

5. 接口返回 / 标签

InterfaceReturnConfigType — 接口返回配置

值 名称
1 StatusCode(状态码)
2 PdfLabel(PDF 标签上传)
3 ErrorMsg(错误信息返回)

LabelType — 标签类型

值 名称
1 Url
2 Base64

6. 通用 / 日志

OptionType — 操作类型

值 名称
0 无
1 新增
2 删除
3 修改

LogListInputTypeEnum — 日志筛选

值 名称
1 应用
2 服务商

前置 / 后置脚本相关速查

场景 关键枚举 / 字段
Header 签名 FieldPosition.Header (=1) → obj.FixedFieldList
Query 签名 FieldPosition.Query (=3) → obj.FixedFieldList
JSON Body 字段 ContentType.Json (=3) → obj.OriginalInterfaceMappedInput
Form 签名 ContentType.FormUrlEncoded (=1) → obj.FormFieldList
账户密钥 obj.GetAccountFieldValueOrNull("字段名")
时间戳占位 固定参数配 $TimeStamp,脚本阶段已替换

后端源码位置

itfx-master/src/InterfaceForward.Domain.Shared/Enum/*.cs
itfx-master/src/InterfaceForward.Domain.Shared/Dtos/FixedFieldWithValueDto.cs  (FieldOwner)
itfx-master/src/InterfaceForward.Application/Services/App/DictionaryService.cs

OMS 数据字典枚举说明

与后端 oms0414-back 中 *Codes / Enums 及前端 src/views/system/dict/dict-batch-import.ts 预置种子对齐。
业务字典落库表 t_dict,唯一键为 dictType + dictCode。


获取方式

运行时(下拉 / 展示)

GET /system/dict/list?dictType={字典类型}
GET /system/dict/list?dictType={字典类型}&page=1&pageSize=500   # 分页拉全量

出参字段:dictType、dictCode、dictName、dictSort。

批量导入

系统管理 → 数据字典 → 下载预置模板 / OMS预置字典模板 / 批量导入。

Excel 表头(与 DICT_IMPORT_HEADERS 一致):

字典类型 字典排序 字典编码 字典名称

规则:

  • 同一 dictType 下 dictCode 唯一;不同 dictType 可重复相同数字编码(如均为 1/2)。
  • 数值 dictCode 从 1 起编;0 表示 None/未设置,不写入字典种子,也不作为业务状态展示项。
  • 通用是否:yes_no;禁用/启用:enable_status;发布快照操作类型:operator_type。
  • 子账号状态与客户主表状态编码一致,复用 customer_status。

种子数据源码:src/views/system/dict/dict-batch-import.ts → OMS_DICT_BATCH_SEED。


字典总览

dictType 预置种子 后端来源 用途
yes_no ✅ 多处 0/1 布尔 通用是否
enable_status ✅ EnableStatus 启用/禁用
order_status ✅ OrderStatusCodes 订单主状态
cargo_attribute ✅ CargoAttributeCodes 货物属性
order_weight_type ✅ OrderWeightTypeCodes 件重尺类型
order_fee_type ✅ OrderFeeTypeCodes 应收/应付
currency ✅ 订单/费用字段 币种
order_template_type ✅ OrderTemplate.Type 订单模板类型
scheme ✅ AllocationSchemeCodes 排货方案
area_type ✅ AreaTypeCodes KPI 分区类型
operator_type ✅ price / rules 常量 发布快照操作类型
forecast_type ✅ ServiceChannel.ForecastType 渠道预报类型
cost_unit ✅ 价格项 CostUnit 计费单位
calculation_formula ✅ ParcelBillingCalculator 计算公式
billable_weight ✅ WeightRuleInfo.BillableWeight 计重取值
weight_rule_condition ✅ WeightRuleInfo.Condition 计重条件表达式
sales_product_group ✅ OrderService.ParcelQuote 卖价分组
customer_waybill ✅ SalesProduct.CustomerWaybill 客户面单类型
label_template_type ✅ LabelTemplate.TemplateType 面单模板类型
number_type ✅ LabelPrintService 打印号码类型
auto_trigger_timing ✅ AutoTriggerTimingCodes 自动触发时机
auto_trigger_operation ✅ AutoTrigger.Operation 自动触发操作
pricing_factor ✅ 卖价/买价因素 定价因素
customer_status ✅ CustomerStatus 客户状态
customer_group ✅ CustomerGroup 客户组
recharge_status ✅ RechargeStatus 充值审核状态
pay_type ✅ PayType 支付方式
principal_type ✅ OmsLoginType / NoticeService 主体类型
notice_type ✅ NoticeService 公告/站内信
receiver_type ✅ NoticeService 接收方类型
warehouse_type ✅ WarehouseTypeCodes 仓库类型
es_snapshot_status ✅ 发布记录设计 快照生效状态
publish_record_type ✅ 发布/回滚设计 发布记录类型
order_task_status ✅ OrderService.Helpers 导入任务状态
export_customs_mode ✅ ExportCustomsModeCodes 出口报关方式
fee_item ✅ 前端/设计文档 费用项(CostItem)
order_handle_status ✅ OrderHandleStatusCodes 订单处理子状态
order_source ✅ OrderSourceCodes 订单来源
issue_type ✅ IssueTypeCodes 问题件类型
issue_notify_method ✅ IssueNotifyMethodCodes 问题通知方式
claim_type ✅ ClaimTypeCodes 理赔类型
order_fee_charging_stage ✅ OrderFeeChargingStageCodes 费用计费阶段
customer_address_type ✅ CustomerAddressTypeCodes 客户地址类型
label_generate_status ✅ LabelGenerateStatusCodes 面单 PDF 生成状态
order_stock_bind_type ✅ OrderStockBindTypeCodes 库存绑定类型
order_stock_bind_status ✅ OrderStockBindStatusCodes 库存绑定状态
warehouse_inbound_type ✅ WarehouseInboundTypeCodes 入库类型
warehouse_receipt_status ✅ WarehouseReceiptStatusCodes 收货状态
warehouse_parcel_lifecycle ✅ WarehouseParcelLifecycleCodes 包裹生命周期
sales_store_auth_status ✅ SalesStoreAuthStatusCodes 店铺授权状态
sales_store_fulfill_status ✅ SalesStoreFulfillStatusCodes 平台店铺履约状态
order_batch_job_status ✅ OrderBatchJobStatusCodes 批量任务状态
order_batch_job_item_status ✅ OrderBatchJobItemStatusCodes 批量任务明细状态
order_template_mapping_status ✅ OrderTemplateMappingStatus 模板映射状态
customer_account_flow_biz_type ✅ CustomerAccountFlowBizTypes 账户流水业务类型
secret_level ✅ DataPermConstants 密级
data_scope ✅ DataPermConstants 数据范围
org_scope ✅ DataPermConstants 组织范围
sales_product — 主数据 API 运输方式(动态)
warehouse — 主数据 API 仓库(动态)

1. 预置种子(可直接导入)

以下项已在 OMS_DICT_BATCH_SEED 中,可在 OMS预置字典模板.xlsx 一键导入。

yes_no — 通用是否

dictCode dictName
1 否
2 是

enable_status — 启用状态

dictCode dictName
1 禁用
2 启用

order_status — 订单状态

dictCode dictName 后端常量
draft 草稿 OrderStatusCodes.Draft
predeclared 已预报 Predeclared
received 已收货 Received
pendingAllocation 待排货 PendingAllocation
pendingPayment 待支付 PendingPayment
pendingShip 待发货 PendingShip
pendingOnline 待上网 PendingOnline
shipping 运输中 Shipping
deliverySuccess 派送成功 DeliverySuccess
deliveryFailed 派送失败 DeliveryFailed
problematic 问题件 Problematic
deleted 已删除 Deleted
claimed 理赔件 Claimed
all 全部 仅筛选用,不落库

cargo_attribute — 货物属性

dictCode dictName
general 普货
electronics 3C&带电
sensitive 敏感货

order_weight_type — 件重尺类型

dictCode dictName
forecast 预报
receive 收货
ship 发货
downstream 下游

order_fee_type — 费用类型

dictCode dictName
receivable 应收
payable 应付

currency — 币种

dictCode dictName
RMB 人民币
USD 美元
EUR 欧元

scheme — 排货方案

dictCode dictName
costLowest 成本最低
timeFastest 时效最快
overallBest 综合最优

operator_type — 发布操作类型

dictCode dictName 说明
price 价格 卖价/买价快照
rules 规则 规则快照

forecast_type — 预报类型

dictCode dictName
customer 客户单号
waybill 运单号
tracking 跟踪号

cost_unit — 计费单位

dictCode dictName
kg 千克
ticket 票
piece 件

calculation_formula — 计算公式

dictCode dictName 说明
total 总价
unit 单价
continue_unit 续单价 后端归一化可能为 continue,见差异说明

billable_weight — 计重取值

dictCode dictName
vw 体积重
gw 实重

weight_rule_condition — 计重条件

dictCode dictName
gw<=vw 实重≤体积重
gw>vw 实重>体积重
gw<vw 实重<体积重
gw>=vw 实重≥体积重
gw==vw 实重=体积重

sales_product_group — 卖价分组

dictCode dictName
line 专线
express 快递
postal 邮政

customer_waybill — 客户面单

dictCode dictName
system 系统面单
customer 客户面单

label_template_type — 面单模板类型

dictCode dictName
lastMile 尾程
customer 客户
inbound 入库
outbound 出库
sku SKU

number_type — 打印号码类型

dictCode dictName 说明
waybill 运单号
customerOrder 客户单号 后端别名 customerorder
tracking 跟踪号
other 其他单号
parcel 包裹跟踪号 后端使用,预置待补
sku SKU 后端使用,预置待补
auto 自动识别 后端使用,预置待补

auto_trigger_timing — 自动触发时机

dictCode dictName
order_create 下单
inbound 入库
outbound 出库

auto_trigger_operation — 自动触发操作

dictCode dictName
intercept 拦截
warn 警告
problem 问题件

pricing_factor — 定价因素

dictCode dictName
cargo 货物类型
zone 分区
weight 重量
warehouse 仓库
customer 客户

customer_status — 客户状态

dictCode dictName 后端 enum
1 禁用 CustomerStatus.Disabled
2 正常 Normal
3 冻结 Frozen

0 = CustomerStatus.None(未设置),不入字典。

customer_group — 客户组

dictCode dictName 后端 enum
1 普通客户 CustomerGroup.Normal
2 VIP1 Vip1
3 VIP2 Vip2
4 VIP3 Vip3
5 VIP4 Vip4
6 VIP5 Vip5

0 = CustomerGroup.None(未设置),不入字典。

recharge_status — 充值审核状态

dictCode dictName 后端 enum
1 待审核 RechargeStatus.Pending
2 审核通过 Approved
3 审核驳回 Rejected

0 = RechargeStatus.None(未设置),不入字典。

pay_type — 支付方式

dictCode dictName 后端 enum
1 微信 PayType.Wechat
2 支付宝 Alipay

0 = PayType.None(未设置),不入字典。

principal_type — 主体类型

dictCode dictName
user 内部用户
customer 客户

notice_type — 通知类型

dictCode dictName
notice 公告
message 站内信

receiver_type — 接收方类型

dictCode dictName
user 用户
customer 客户

warehouse_type — 仓库类型

dictCode dictName
main 主仓
transit 中转仓
return 退货仓
other 其他

es_snapshot_status — 快照生效状态

dictCode dictName
active 生效
inactive 失效

publish_record_type — 发布记录类型

dictCode dictName
publish 发布
rollback 回滚

order_task_status — 订单导入任务状态

dictCode dictName
pending 待处理
processing 处理中
completed 已完成

area_type — 分区类型

dictCode dictName
blacklist 黑名单区
remote 偏远分区
warning 警告区

order_template_type — 订单模板类型

dictCode dictName
standard 标准模板
custom 自定义模板

2. 建议补充导入(后端已有常量,预置未含)

export_customs_mode — 出口报关方式

dictCode dictName
9610Simple 9610简易申报
9610Summary 9610汇总申报
9610Separate 9610分离申报
9710 9710
9810 9810
0110 0110

fee_item — 费用项

业务可配置字典;前端渠道/订单页已引用,编码由运营维护,后端无 *Codes 类。

order_handle_status — 订单处理子状态

dictCode dictName
pending 待处理
processed 已处理

order_source — 订单来源

dictCode dictName
manual 手工录入
pickup 揽收
upload 上传
batch 批量
platform 平台店铺

issue_type — 问题件类型

dictCode dictName
address 地址异常
customs 清关问题
weight 重量异常
document 单证不全
cargo 货物异常
channel 渠道异常
payment 费用异常
other 其他

issue_notify_method — 问题通知方式

dictCode dictName
inApp 站内信
email 邮件
sms 短信
feishu 飞书
wechat 微信

claim_type — 理赔类型

dictCode dictName
lost 丢件
damaged 破损
delay 延误
customs 清关理赔
fee 费用争议
other 其他

order_fee_charging_stage — 费用计费阶段

dictCode dictName
forecast 预报
inbound 入库
outbound 出库

customer_address_type — 客户地址类型

dictCode dictName
sender 发件
return 退件
receiver 收件

label_generate_status — 面单 PDF 生成状态

dictCode dictName 说明
Pending 待生成 PascalCase,与多数 camelCase 不一致
Ready 已就绪
Failed 生成失败

order_stock_bind_type — 库存绑定类型

dictCode dictName
inventory 库存
parcelItem 包裹明细

order_stock_bind_status — 库存绑定状态

dictCode dictName
bound 已绑定
deducted 已扣减
released 已释放

warehouse_inbound_type — 入库类型

dictCode dictName
normal 正常入库
return 退货入库

warehouse_receipt_status — 收货状态

dictCode dictName
forecasted 已预报
received 已收货
completed 已完成

warehouse_parcel_lifecycle — 包裹生命周期

dictCode dictName
inTransit 在途
arrived 已到仓
stored 已上架

sales_store_auth_status — 店铺授权状态

dictCode dictName
active 有效
expired 已过期
revoked 已撤销

sales_store_fulfill_status — 平台店铺履约状态

dictCode dictName
pending 待处理
toShip 待发货
canceled 已取消
suspended 挂起
shipped 已发货
completed 已完成

order_batch_job_status — 批量任务状态

dictCode dictName
pending 待处理
running 执行中
completed 已完成
failed 失败
cancelled 已取消

order_batch_job_item_status — 批量任务明细状态

dictCode dictName
pending 待处理
running 执行中
success 成功
failed 失败
cancelled 已取消

order_template_mapping_status — 模板映射状态

dictCode dictName
draft 草稿
ready 就绪

customer_account_flow_biz_type — 账户流水业务类型

dictCode dictName
recharge 充值入账
orderPay 订单支付

secret_level — 密级

dictCode dictName
1 公开
2 内部
3 机密
4 绝密

data_scope — 数据范围

dictCode dictName
1 个人
2 小组
3 部门
4 组织树
5 全局

org_scope — 组织范围

dictCode dictName
1 仅本级
2 本级及下级

3. 小红书模块(按需)

dictType dictCode 示例 dictName 示例
xhs_agent_status online / offline 在线 / 离线
xhs_task_status pending / claimed / running / succeeded / failed / cancelled 任务状态
xhs_publish_status draft / scheduled / publishing / succeeded / failed / cancelled 发布状态
xhs_task_type engine_start / publish / browse … 任务类型
xhs_task_source web / schedule / skill 任务来源
xhs_analysis_type home_feed / search / my_feeds / feed_detail 分析类型

源码:Oms.Domain/XhsAggregate/Consts/XhsCodes.cs。


4. 预置与后端差异(导入前建议对齐)

数值编码约定(0 = None)

OMS 数值 dictCode 与 C# byte 枚举 对齐规则:

约定 说明
0 None / 未设置,不写入 t_dict 种子
1 起 第一个有效业务状态

已从 0 起编、已修正 的字典/枚举(共 5 类):

dictType / enum 原编码 现编码
yes_no 0=否, 1=是 1=否, 2=是
enable_status / EnableStatus 0=禁用, 1=启用 1=禁用, 2=启用
customer_status / CustomerStatus 0=禁用, 1=正常, 2=冻结 1=禁用, 2=正常, 3=冻结
customer_group / CustomerGroup 0=普通, 1–5=VIP 1=普通, 2–6=VIP
recharge_status / RechargeStatus 0=待审核, 1=通过, 2=驳回 1=待审核, 2=通过, 3=驳回

本就符合(从 1 起或字符串编码):pay_type、secret_level、data_scope、org_scope,以及全部字符串 dictCode 类型。

已有库数据迁移(若曾按旧 0 起编码落库,需执行 +1):

-- 示例:按表字段逐一 +1(执行前请备份)
UPDATE t_customer SET Status = Status + 1 WHERE Status BETWEEN 0 AND 2;
UPDATE t_customer SET CustomerGroup = CustomerGroup + 1 WHERE CustomerGroup BETWEEN 0 AND 5;
UPDATE t_recharge SET RechargeStatus = RechargeStatus + 1 WHERE RechargeStatus BETWEEN 0 AND 2;
-- IsActive / EnableStatus 等同理
dictType 问题 建议
area_type 已统一为 warning(与 AreaTypeCodes 一致) —
calculation_formula 预置 continue_unit,NormalizeCalculationFormula 归一化为 continue 统一编码或改后端归一化
customer_group 预置 VIP1–5;DataPermConstants.CustomerGroupOptions 文案不同 统一一套命名
es_snapshot_status 预置 active/inactive;发布记录曾写中文 "生效" 落库用 dictCode,展示用 dictName
label_generate_status 后端 PascalCase 统一大小写规范
number_type 后端还有 parcel / sku / auto 补入预置种子

5. 不宜字典化

类别 示例 原因
批量动作码 OrderBatchActionCodes 内部任务路由
MQ 拓扑 OrderBatchQueueTopology 基础设施
系统配置键 SystemOtherConfigCodes 配置标识
平台原始状态 Lazada/Shopee PlatformStatus 外部平台枚举
过滤器运算符 DataPermConstants.FilterOperators 技术 DSL
模板字段 Key OrderTemplateKeys 代码注册表

6. 动态字典(主数据,非静态种子)

dictType 加载方式
sales_product 卖价产品列表 API
warehouse 仓库地址列表 API
product_line / kpi_area / region 数据权限业务维度

订单模板 Excel 下拉亦引用:cargo_attribute、export_customs_mode、currency 等静态字典 + 上述动态类型。


7. 可改为读字典的 GetDisplayName

当前方法 建议 dictType
OmsDocHelper.GetOrderStatusName order_status
OmsDocHelper.GetWarehouseTypeName warehouse_type
OrderHandleStatusCodes.GetDisplayName order_handle_status
IssueTypeCodes.GetDisplayName issue_type
ClaimTypeCodes.GetDisplayName claim_type
IssueNotifyMethodCodes.GetDisplayName issue_notify_method
CustomerAddressTypeCodes.GetDisplayName customer_address_type
RechargeService.GetPayTypeName pay_type
RechargeService.GetRechargeStatusName recharge_status
FinanceService.GetFeeTypeName order_fee_type
FinanceService.GetChargingStageName order_fee_charging_stage
CustomerAccountFlowService.GetBizTypeName customer_account_flow_biz_type

OMS 后端源码位置

oms0414-back/src/Oms.Domain/**/Consts/*Codes.cs
oms0414-back/src/Oms.Domain/**/Enums/*.cs
oms0414-back/src/Oms.Application/Services/System/DictService.cs
oms0414-back/src/Oms.Application/Shared/OmsDocHelper.cs
oms0414-back/src/Oms.Application/DataPerm/DataPermConstants.cs
oms0414/src/views/system/dict/dict-batch-import.ts   # 预置种子与导入模板