【前端完整开发需求文档】1688账期还款模块
一、 任务目标
在【采购记账】模块下新增“1688账期还款”页签,实现账单导入、CFD流水导入(需选渠道)、全量校验提示、按渠道拆单付款、历史还款记录查询及明细查看。
二、 页面整体UI线框图(严格按此结构实现)
text
========================================================================================
| 首页 > 采购记账 > 1688账期还款 |
========================================================================================
【账户选择卡片区】(横向排列,置顶)
| +-----------------------+ +-----------------------+ +-----------------------+ |
| | [选中状态,橙色粗边框] | | [未选中,灰色细边框] | | [未选中,灰色细边框] | |
| | 诚e赊(1688) [账期标签] | | [跨境宝] [账期标签] | | [XX账户] [账期标签] | |
| | | | | | | |
| | 结余金额:¥292,952.31 | | 结余金额:¥0.00 | | 结余金额:¥100.00 | |
| +-----------------------+ +-----------------------+ +-----------------------+ |
| (点击选中卡片,卡片边框高亮为橙色) |
----------------------------------------------------------------------------------------
【操作区】
[ 导入1688账单 ] [ 导入CFD财务流水 ] [ 全量校验 ] [ ⚙渠道配置 ]
----------------------------------------------------------------------------------------
【全量校验动态提示横幅】(动态变色,未校验时隐藏)
| [✅ 绿色状态] 全量校验通过,共 X 条账单,请在下方渠道记录中进行付款。 |
| [❌ 红色状态] 全量校验失败!存在 X 条未匹配,Y 条金额不一致,请先排查数据。 |
----------------------------------------------------------------------------------------
【子Tab切换区】
[ 1688账单明细 ] [ 渠道待付款记录 ] [ 历史还款记录 ]
----------------------------------------------------------------------------------------
【Tab1:1688账单明细表格】(保留原有字段+新增字段,字段较多支持横向滚动)
| [全选] | 订单号(双行) | 订单支付时间 | 订单名称 | 支付金额(元) | 确认收货金额(元) | 确认收货时间 | 账期类型 | 是否有退款 | 退款金额(元) | CFD渠道 | 匹配状态 |
| [√] | 330092... | 2026-05-13 09:40 | 厂家直销...| 4100 | 4100 | 2026-06-01 18:22 | 1个月账期 | 无 | 0.00 | 易采付 | [🟢匹配成功] |
| | 系统单号:SYS_8888 | | | | | | | | | | |
| [ ] | 330092... | 2026-05-12 17:57 | 现货按扣...| 110 | 110 | 2026-06-12 16:38 | 1个月账期 | 无 | 0.00 | - | [🔴金额不一致] |
| | 系统单号:SYS_8889 | | | | | | | | | | |
| [ ] | 330091... | 2026-05-11 17:20 | 亚马逊... | 68 | 68 | 2026-06-12 10:52 | 1个月账期 | 无 | 0.00 | 先采后付 | [⚠️未匹配] |
| | 系统单号:SYS_8890 | | | | | | | | | | |
【Tab2:渠道待付款记录】(全量校验通过后自动切换到此Tab)
| 渠道名称 | 对应公户(下拉) | 记录金额 | CFD导入金额 | 校验状态 | 操作 |
| 易采付明细 | [选择公户 ▾] | ¥5,000.00 | ¥5,000.00 | [🟢匹配成功] | [选择账期账户 ▾] [完成付款] |
| 1688先采后付FD | [选择公户 ▾] | ¥3,000.00 | ¥3,200.00 | [🔴金额不匹配]| (隐藏所有操作按钮) |
| 跨境直采BWST | [选择公户 ▾] | ¥1,200.00 | ¥1,200.00 | [🟢匹配成功] | [选择账期账户 ▾] [完成付款] |
【Tab3:历史还款记录】
| 付款时间 | 付款账户 | 渠道 | 付款公户 | 总付款金额 | 操作人 | 操作 |
| 2026-09-08 | 诚e赊 | 易采付明细 | 某公户A | ¥5000.00 | 张三 | [查看明细] |
----------------------------------------------------------------------------------------
【底部吸底操作栏】
| (Tab1/未校验时) 请先完成全量校验后进行渠道付款 |
| (Tab2有数据时) 当前已有 X 个渠道完成付款,剩余 Y 个渠道待处理 |
========================================================================================
【弹窗A:导入CFD财务流水弹窗】
+------------------------------------------------------+
| X 导入CFD财务流水 |
| |
| * CFD渠道: [下拉框,动态加载渠道配置列表 ▾] |
| * 文件上传:[点击上传 Excel/CSV] |
| |
| [ 取消 ] [ 确认导入 ] |
| (必须同时选择渠道 + 上传文件,才能点击【确认导入】) |
+------------------------------------------------------+
【弹窗B:渠道配置弹窗】
+------------------------------------------------------------+
| X 渠道配置 |
| [ + 新增渠道 ] |
| |
| 渠道名称 | 绑定公户 | 创建时间 | 操作 |
| 易采付明细 | 某公户A | 2026-09-01 | [编辑][删除] |
| 1688先采后付FD | 某公户B | 2026-09-01 | [编辑][删除] |
| 跨境直采BWST | 某公户C | 2026-09-01 | [编辑][删除] |
+------------------------------------------------------------+
【弹窗C:查看明细抽屉(右侧Drawer)】
+------------------------------------------------------------+
| X 付款记录明细详情 |
| |
| 本次付款总金额:¥5,000.00 | 付款账户:诚e赊 | 操作人:张三 |
| 付款时间:2026-09-08 15:30 |
|------------------------------------------------------------|
| 序号 | 订单编号(双行) | 商品信息 | 供应商 | 采购金额 | 费用类型 | 付款金额 | 渠道 | 操作人 |
| 1 | 33009220179778860 | [图] 商品名称 | 某某供应链 | 1400.00 | 货款 | 1400.00 | 易采付明细 | 张三 |
| | 系统单号: SYS_8888 | SKU:XX-123 | | | | | | |
| 2 | 330092041729728860 | [图] 商品名称 | 某服装厂 | 3600.00 | 运费 | 3600.00 | 易采付明细 | 张三 |
| | 系统单号: SYS_8889 | SKU:XX-456 | | | | | | |
|------------------------------------------------------------|
| 合计:共 X 条记录 总付款金额:¥5,000.00 [关闭] |
+------------------------------------------------------------+
三、 UI组件规范与交互细节
1. 账户选择卡片区(置顶)
-
布局:Flex横向排列,间距16px。
-
卡片尺寸:宽约220px,高约100px,圆角8px,边框1px。
-
内容:
-
标题:加粗14px,颜色
#333(如:诚e赊(1688))。 -
账期标签:橘色背景
#FFF7E6,文字橘色#FA8C16,12px,圆角4px,文字“账期”。 -
结余金额:12px,颜色
#666。
-
-
交互:点击卡片切换选中状态,选中后边框变为橙色粗边框(
#FA8C16,1.5px)。
2. 操作区
-
主按钮(蓝底白字):【导入1688账单】
-
次按钮(白底蓝边):【导入CFD财务流水】(点击弹出弹窗A,不再直接唤起文件选择器)
-
主按钮(橙色底白字):【全量校验】
-
次按钮(白底灰边):【
渠道配置】(点击弹出弹窗B)
3. 全量校验动态提示区
-
触发:点击【全量校验】后,接口返回结果,横幅显示出来。未校验时隐藏。
-
正常状态(绿):背景
#F6FFED,边框#B7EB8F,文字#52C41A,图标对勾。文案:“全量校验通过,共 X 条账单,请在下方渠道记录中进行付款。” -
异常状态(红):背景
#FFF1F0,边框#FFA39E,文字#F5222D,图标惊叹号。文案:“全量校验失败!存在 X 条未匹配,Y 条金额不一致,请先排查数据。”
4. 子Tab切换区
-
三个Tab:
1688账单明细、渠道待付款记录、历史还款记录。 -
默认激活:1688账单明细。
-
自动切换:全量校验通过后,自动切换到“渠道待付款记录”Tab。
5. Tab1:1688账单明细表格(字段较多,支持横向滚动)
-
表头:灰底
#F5F7FA,加粗。 -
字段(必须严格按顺序,不可删减):
-
复选框(全选)
-
订单号:双行显示,第一行1688订单号(14px黑字),第二行系统内部订单号(12px灰字)。
-
订单支付时间:
YYYY-MM-DD HH:mm:ss -
订单名称:长文本截断
-
支付金额(元):保留2位小数
-
确认收货金额(元):保留2位小数
-
确认收货时间:
YYYY-MM-DD HH:mm:ss -
账期类型:文本
-
是否有退款:文本(“有”/“无”)
-
退款金额(元):保留2位小数,无则显示
0.00 -
CFD渠道:来自导入时的渠道名,无匹配显示“-”
-
匹配状态:Tag标签。
-
匹配成功:绿底#F6FFED,绿字#52C41A -
金额不一致:红底#FFF1F0,红字#F5222D -
未匹配:橙底#FFF7E6,橙字#FA8C16
-
-
6. Tab2:渠道待付款记录表格
-
展示时机:全量校验通过后,自动切换到该Tab。未校验前不显示。
-
表格表头:渠道名称、对应公户(下拉选择)、记录金额、CFD导入金额、校验状态、操作。
-
行数据逻辑:
-
对应公户:下拉框,数据源为
GET /api/maintenance/channel-account。默认自动选中该渠道已绑定的公户。 -
校验状态:
-
匹配成功(记录金额 == CFD导入金额) -
金额不匹配(两者不相等)
-
-
操作列:
-
状态为
匹配成功:显示 [选择账期账户 ▾] 和 [完成付款] 按钮。 -
状态为
金额不匹配:隐藏所有操作按钮。
-
-
-
【完成付款】按钮联动:必须同时选择了公户和账期账户后,按钮才可点击。
7. Tab3:历史还款记录
-
表格字段:付款时间、付款账户、渠道、付款公户、总付款金额、操作人、操作。
-
操作列:包含【查看明细】按钮。
-
查看明细弹窗:见弹窗C。
8. 底部吸底操作栏(固定在底部)
-
Tab1或未校验时:文案“请先完成全量校验后进行渠道付款”。
-
Tab2有数据时:文案“当前已有 X 个渠道完成付款,剩余 Y 个渠道待处理”。(X和Y根据渠道记录列表实时计算)。
9. 弹窗A:导入CFD财务流水
-
渠道选择下拉框:数据源动态调用
GET /api/maintenance/channel-account接口。 -
文件上传组件:支持 Excel/CSV。
-
按钮联动:必须同时选择渠道 + 上传文件后,【确认导入】按钮才可点击。
-
提交格式:
multipart/form-data,参数包含channel和file。
10. 弹窗B:渠道配置
-
列表:展示所有渠道配置(渠道名称、绑定公户、创建时间、操作)。
-
新增:点击【+新增渠道】弹出表单,填入“渠道名称”和“绑定公户”,提交到后端。
-
编辑/删除:每行提供操作按钮。
11. 弹窗C:查看明细抽屉
-
顶部汇总:本次付款总金额、付款账户、操作人、付款时间。
-
明细表格字段:
-
序号
-
订单编号(双行):第一行1688订单号,第二行系统内部订单号(灰字)。
-
商品信息:左侧图片缩略图(50x50px),右侧分两行显示“商品名称”和“SKU”。
-
供应商
-
采购金额
-
费用类型
-
付款金额
-
操作人
-
渠道
-
-
底部:合计“共 X 条记录”、“总付款金额:¥XXX.XX”,右侧【关闭】按钮。
四、 前端调用的接口清单
-
GET /api/list/accounts:拉取账户卡片数据(账户名、类型、结余金额)。 -
POST /api/import/bill:导入1688账单。 -
POST /api/import/cfd:导入CFD流水(multipart/form-data,包含 channel 和 file)。 -
GET /api/list/bills:拉取账单明细(包含系统内部订单号、CFD渠道、匹配状态)。 -
POST /api/validate:触发全量校验,返回校验结果及拆单后的渠道待付款记录。 -
GET /api/list/channel-records:拉取渠道待付款记录。 -
POST /api/payment/complete-per-channel:提交单渠道付款(入参:channel_record_id, public_account_name, account_id)。 -
GET /api/maintenance/channel-account:获取渠道配置列表(用于弹窗A和B)。 -
POST /api/maintenance/channel-account:新增渠道配置。 -
PUT /api/maintenance/channel-account/{id}:修改渠道配置。 -
DELETE /api/maintenance/channel-account/{id}:删除渠道配置。 -
GET /api/payment/records:拉取历史还款记录。 -
GET /api/payment/details:拉取某次付款的明细(入参:record_id)。
五、 关键交互逻辑汇总(防呆机制)
-
全量校验通过前:隐藏“渠道待付款记录”Tab,底部吸底栏显示提示文案。
-
全量校验通过后:自动切换到“渠道待付款记录”Tab,展示拆单后的各渠道记录。
-
某行渠道金额不匹配时:该行隐藏操作按钮,只有匹配成功的行才能操作付款。
-
点击单行【完成付款】:必须同时选择了“公户”和“账期账户”后,按钮才可点击。点击后调用
POST /api/payment/complete-per-channel,成功后刷新该行状态为“已付款”。 -
导入CFD弹窗:下拉框必须动态获取渠道列表,不可写死。必须同时选择渠道和上传文件才能提交。
-
渠道配置弹窗:支持新增、编辑、删除,是渠道数据的唯一维护入口。
_______________________________________________________________________________________________________________________________________________________
【第二部分】后端开发需求文档
一、 任务目标
为“1688账期还款”模块提供全套后端API支持。实现以下核心业务闭环:
-
动态渠道管理:支持配置渠道并绑定公户。
-
数据导入:导入1688账单(关联系统单号)和CFD流水(指定渠道)。
-
全量强校验:100%匹配校验,存在任何异常则全流程阻断。
-
按渠道拆分:校验通过后,按CFD渠道自动拆分生成多笔“待付款记录”。
-
分笔独立付款:每笔渠道记录独立选择账期账户并完成付款(需事务处理)。
-
记录查询:支持历史还款记录列表和明细查看。
二、 数据库表设计(MySQL参考)
1. t_channel_public_account (渠道-公户配置表)
用于动态维护渠道,并为每个渠道绑定付款公户。
-
id(主键) -
channel_name(渠道名称,唯一,不再限制固定枚举,支持动态新增) -
public_account_name(绑定的公户名称) -
create_time,update_time -
(初始化时,可预置:易采付明细、1688先采后付FD、1688先采后付RP、跨境直采BWST,但业务允许增加任意渠道。)
2. t_1688_bill (1688原始账单表)
存储导入的1688账单,并承载对账中间状态。
原有字段(必须完整保留):
-
id(主键) -
order_no(1688订单号) -
order_pay_time(订单支付时间) -
product_name(订单名称) -
pay_amount(支付金额,存分为单位) -
confirm_receive_amount(确认收货金额,存分为单位) -
confirm_receive_time(确认收货时间) -
账期类型 -
has_refund(是否有退款) -
refund_amount(退款金额,存分为单位)
新增字段:
-
system_order_no(系统内部订单号,建立关联映射) -
cfd_channel(CFD渠道,来自导入时指定的渠道) -
cfd_amount(CFD流水金额,存分为单位) -
match_status(对账状态:success、amount_error、not_found) -
is_paid(是否已付款:0未付款、1已付款) -
create_time,update_time
3. t_channel_payment_record (渠道待付款记录表)
全量校验通过后,按渠道拆分生成。
-
id(主键) -
channel_name(渠道名) -
public_account_name(该渠道绑定的公户,付款时最终确认并写入) -
record_amount(该渠道下所有订单的应付总金额,存分) -
cfd_amount(该渠道从CFD导入的总金额,存分) -
match_status(校验状态:success、amount_error) -
payment_status(付款状态:pending、paid) -
payment_id(关联最终付款主记录ID,付款后写入) -
create_time
4. t_account (账期账户表)
id,account_name,account_type,balance(结余金额,存分)
5. t_payment_record (还款主记录表)
记录每一笔渠道付款的主信息。
id,account_id,channel_name,public_account_name,total_amount,operator,create_time
6. t_payment_detail (还款明细表)
记录付款包含的每条账单明细。
id,payment_id,order_id,system_order_id,product_img,product_name,sku,supplier,purchase_amount,fee_type,paid_amount,operator,channel
三、 API 接口详细设计
1. 渠道配置模块(渠道-公户维护)
GET /api/maintenance/channel-account
-
查询所有渠道配置列表。返回字段:
id,channel_name,public_account_name,create_time。 -
该接口同时供前端“导入CFD流水”时下拉框展示渠道列表。
POST /api/maintenance/channel-account
-
新增渠道。入参:
{ "channel_name": "新渠道", "public_account_name": "新公户" }。 -
校验渠道名唯一性。
PUT /api/maintenance/channel-account/{id}
- 修改渠道名或公户名。
DELETE /api/maintenance/channel-account/{id}
- 删除渠道。注意:如果该渠道已经在
t_1688_bill或t_channel_payment_record中被使用,则禁止删除并返回错误提示。
2. 导入模块
POST /api/import/bill
-
上传1688账单文件,解析并写入
t_1688_bill。同时根据系统内的订单映射关系,填充system_order_no。 -
需做去重处理(基于订单号+支付时间+金额做MD5校验)。
POST /api/import/cfd
-
请求方式:
multipart/form-data -
入参:
file(文件)、channel(渠道名,必填) -
逻辑:
-
强校验渠道:查询
t_channel_public_account,若该渠道不存在,直接报错“请先在渠道配置中新增该渠道”。 -
解析文件,忽略文件内部的渠道列,直接使用入参中的
channel值,写入t_1688_bill的cfd_channel字段。 -
将解析出的每条订单的CFD金额,填充到对应账单的
cfd_amount字段。
-
3. 全量强校验与拆单(核心)
POST /api/validate
-
前置条件:导入完成后,用户点击【全量校验】触发。
-
逻辑:
-
校验所有数据:查询
t_1688_bill中所有未付款数据。检查每条是否有匹配的cfd_amount,且金额一致。 -
金额精度处理:所有金额比对必须转为“分”(整数)进行比较。
-
更新状态:将结果更新回
t_1688_bill的match_status字段(success、amount_error、not_found)。 -
全量拦截:若存在任何一条
amount_error或not_found,校验失败,不进行后续拆单,直接返回失败结果。 -
按渠道拆单:若100%匹配,执行拆单逻辑。根据
cfd_channel字段进行GROUP BY,为每个渠道在t_channel_payment_record中生成一条待付款记录:-
计算
record_amount(该渠道所有未付款账单的pay_amount之和) -
计算
cfd_amount(该渠道所有CFD流水的总额) -
比对两者金额,写入
match_status(此处如果存在不一致,理论上可以在拆分阶段拦截,但更推荐在全量校验前置阶段拦截,确保拆单出来的都是正确的) -
设置
payment_status = 'pending'
-
-
返回给前端:校验结果(
isPass)、总条数、异常条数、拆单后的渠道待付款记录列表。
-
-
返回结构示例:
json
{ "isPass": true, "totalCount": 928, "channelRecords": [ { "id": 1, "channel_name": "易采付明细", "record_amount": 500000, "cfd_amount": 500000, "match_status": "success", "payment_status": "pending" }, { "id": 2, "channel_name": "1688先采后付FD", "record_amount": 300000, "cfd_amount": 300000, "match_status": "success", "payment_status": "pending" } ] }
GET /api/list/channel-records
-
查询
t_channel_payment_record表,返回渠道待付款记录列表,供前端渲染。 -
返回字段必须包含渠道名、绑定的公户、记录金额、CFD金额、校验状态、付款状态。
4. 完成付款(核心事务)
POST /api/payment/complete-per-channel
-
入参:
{ "channel_record_id": 1, "public_account_name": "某公户", "account_id": 2, "operator": "张三" } -
逻辑(必须开启数据库事务):
-
幂等与状态校验:查询
t_channel_payment_record,校验match_status == 'success'且payment_status == 'pending'。若不符,拒绝请求。 -
余额校验:查询
t_account,校验所选账户余额是否充足(balance >= record_amount)。 -
公户校验:校验前端传来的
public_account_name是否与t_channel_public_account中该渠道的绑定关系一致(防止前端篡改)。 -
生成主记录:向
t_payment_record写入一条数据(包含渠道、公户、总金额、操作人)。 -
生成明细记录:查询该渠道下的所有未付款账单(
t_1688_bill中cfd_channel = 当前渠道且is_paid = 0),逐条写入t_payment_detail。 -
扣减账户余额:更新
t_account的balance减去record_amount。 -
更新状态:
-
t_channel_payment_record的payment_status置为paid,记录payment_id。 -
t_1688_bill中对应渠道的账单is_paid标记为1。
-
-
-
返回:成功状态及主记录ID。
5. 历史记录查询
GET /api/payment/records
-
分页查询
t_payment_record。 -
返回字段必须包含:
id,付款时间,付款账户,渠道,付款公户,总付款金额,操作人。
GET /api/payment/details
-
入参:
record_id -
逻辑:根据主记录ID,从
t_payment_detail中查询该次付款的所有明细。 -
返回字段:订单编号、系统内部单号、商品图片、商品名称、SKU、供应商、采购金额、费用类型、付款金额、操作人、渠道。
四、 异常处理与容错边界
-
空文件/格式错误:导入接口必须拦截非Excel/CSV格式的文件。
-
重复导入:对导入的1688账单做去重逻辑(推荐基于订单号+支付时间+金额做MD5唯一校验,避免重复导入相同文件)。
-
渠道未配置:在
POST /api/import/cfd中必须校验渠道存在性,不存在则报错并引导用户去配置。 -
全量校验优先级:只有
POST /api/validate且返回isPass: true后,才会生成t_channel_payment_record记录。前端不允许在未校验的情况下发起付款。 -
金额精度:所有金额比较(包括渠道记录金额 vs CFD金额)必须转为“分”进行比对,杜绝浮点误差。
-
公户校验:付款时必须校验公户绑定关系,防止公户与渠道不匹配导致财务挂账。
-
幂等性:
complete-per-channel接口需做防重复提交处理(如基于channel_record_id+payment_status做幂等)。 -
金额超限:接口层面限制单次付款金额上限,防止极端错误数据引发大额扣款。
五、 关键业务流程总结(供开发自查)
-
用户在【渠道配置】新增渠道A,绑定公户X。
-
用户导入1688账单(无渠道概念)。
-
用户在【导入CFD流水】弹窗中,选择渠道A,上传文件。
-
点击【全量校验】。系统校验:1688账单总额 vs CFD流水总额;且每条账单都有对应的CFD金额。校验通过后,按渠道A拆分出一条待付款记录。
-
用户在【渠道待付款记录】中,看到“渠道A”,金额匹配,点击【完成付款】。选择账期账户,系统自动带入公户X,点击提交。
-
事务处理:生成付款主记录、明细记录、扣减账期账户余额、将该渠道所有账单标记为已付款。
-
用户可在【历史还款记录】中查询到该笔付款,并能查看包含商品图片、SKU、渠道等完整信息的明细。