采购记账-1688账期还款(重新设计)

【前端完整开发需求文档】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,不再直接唤起文件选择器)

  • 主按钮(橙色底白字):【全量校验】

  • 次按钮(白底灰边):【:gear:渠道配置】(点击弹出弹窗B)

3. 全量校验动态提示区

  • 触发:点击【全量校验】后,接口返回结果,横幅显示出来。未校验时隐藏。

  • 正常状态(绿):背景#F6FFED,边框#B7EB8F,文字#52C41A,图标对勾。文案:“全量校验通过,共 X 条账单,请在下方渠道记录中进行付款。”

  • 异常状态(红):背景#FFF1F0,边框#FFA39E,文字#F5222D,图标惊叹号。文案:“全量校验失败!存在 X 条未匹配,Y 条金额不一致,请先排查数据。”

4. 子Tab切换区

  • 三个Tab:1688账单明细、渠道待付款记录、历史还款记录。

  • 默认激活:1688账单明细。

  • 自动切换:全量校验通过后,自动切换到“渠道待付款记录”Tab。

5. Tab1:1688账单明细表格(字段较多,支持横向滚动)

  • 表头:灰底#F5F7FA,加粗。

  • 字段(必须严格按顺序,不可删减):

    1. 复选框(全选)

    2. 订单号:双行显示,第一行1688订单号(14px黑字),第二行系统内部订单号(12px灰字)。

    3. 订单支付时间:YYYY-MM-DD HH:mm:ss

    4. 订单名称:长文本截断

    5. 支付金额(元):保留2位小数

    6. 确认收货金额(元):保留2位小数

    7. 确认收货时间:YYYY-MM-DD HH:mm:ss

    8. 账期类型:文本

    9. 是否有退款:文本(“有”/“无”)

    10. 退款金额(元):保留2位小数,无则显示 0.00

    11. CFD渠道:来自导入时的渠道名,无匹配显示“-”

    12. 匹配状态:Tag标签。

      • :green_circle: 匹配成功:绿底#F6FFED,绿字#52C41A

      • :red_circle: 金额不一致:红底#FFF1F0,红字#F5222D

      • :warning: 未匹配:橙底#FFF7E6,橙字#FA8C16

6. Tab2:渠道待付款记录表格

  • 展示时机:全量校验通过后,自动切换到该Tab。未校验前不显示。

  • 表格表头:渠道名称、对应公户(下拉选择)、记录金额、CFD导入金额、校验状态、操作。

  • 行数据逻辑:

    • 对应公户:下拉框,数据源为 GET /api/maintenance/channel-account。默认自动选中该渠道已绑定的公户。

    • 校验状态:

      • :green_circle: 匹配成功(记录金额 == CFD导入金额)

      • :red_circle: 金额不匹配(两者不相等)

    • 操作列:

      • 状态为:green_circle:匹配成功:显示 [选择账期账户 ▾] 和 [完成付款] 按钮。

      • 状态为:red_circle:金额不匹配:隐藏所有操作按钮。

  • 【完成付款】按钮联动:必须同时选择了公户和账期账户后,按钮才可点击。

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”,右侧【关闭】按钮。

四、 前端调用的接口清单

  1. GET /api/list/accounts:拉取账户卡片数据(账户名、类型、结余金额)。

  2. POST /api/import/bill:导入1688账单。

  3. POST /api/import/cfd:导入CFD流水(multipart/form-data,包含 channel 和 file)。

  4. GET /api/list/bills:拉取账单明细(包含系统内部订单号、CFD渠道、匹配状态)。

  5. POST /api/validate:触发全量校验,返回校验结果及拆单后的渠道待付款记录。

  6. GET /api/list/channel-records:拉取渠道待付款记录。

  7. POST /api/payment/complete-per-channel:提交单渠道付款(入参:channel_record_id, public_account_name, account_id)。

  8. GET /api/maintenance/channel-account:获取渠道配置列表(用于弹窗A和B)。

  9. POST /api/maintenance/channel-account:新增渠道配置。

  10. PUT /api/maintenance/channel-account/{id}:修改渠道配置。

  11. DELETE /api/maintenance/channel-account/{id}:删除渠道配置。

  12. GET /api/payment/records:拉取历史还款记录。

  13. GET /api/payment/details:拉取某次付款的明细(入参:record_id)。

五、 关键交互逻辑汇总(防呆机制)

  1. 全量校验通过前:隐藏“渠道待付款记录”Tab,底部吸底栏显示提示文案。

  2. 全量校验通过后:自动切换到“渠道待付款记录”Tab,展示拆单后的各渠道记录。

  3. 某行渠道金额不匹配时:该行隐藏操作按钮,只有匹配成功的行才能操作付款。

  4. 点击单行【完成付款】:必须同时选择了“公户”和“账期账户”后,按钮才可点击。点击后调用 POST /api/payment/complete-per-channel,成功后刷新该行状态为“已付款”。

  5. 导入CFD弹窗:下拉框必须动态获取渠道列表,不可写死。必须同时选择渠道和上传文件才能提交。

  6. 渠道配置弹窗:支持新增、编辑、删除,是渠道数据的唯一维护入口。

_______________________________________________________________________________________________________________________________________________________

【第二部分】后端开发需求文档

一、 任务目标

为“1688账期还款”模块提供全套后端API支持。实现以下核心业务闭环:

  1. 动态渠道管理:支持配置渠道并绑定公户。

  2. 数据导入:导入1688账单(关联系统单号)和CFD流水(指定渠道)。

  3. 全量强校验:100%匹配校验,存在任何异常则全流程阻断。

  4. 按渠道拆分:校验通过后,按CFD渠道自动拆分生成多笔“待付款记录”。

  5. 分笔独立付款:每笔渠道记录独立选择账期账户并完成付款(需事务处理)。

  6. 记录查询:支持历史还款记录列表和明细查看。

二、 数据库表设计(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

  • 前置条件:导入完成后,用户点击【全量校验】触发。

  • 逻辑:

    1. 校验所有数据:查询 t_1688_bill 中所有未付款数据。检查每条是否有匹配的 cfd_amount,且金额一致。

    2. 金额精度处理:所有金额比对必须转为“分”(整数)进行比较。

    3. 更新状态:将结果更新回 t_1688_bill 的 match_status 字段(success、amount_error、not_found)。

    4. 全量拦截:若存在任何一条 amount_error 或 not_found,校验失败,不进行后续拆单,直接返回失败结果。

    5. 按渠道拆单:若100%匹配,执行拆单逻辑。根据 cfd_channel 字段进行 GROUP BY,为每个渠道在 t_channel_payment_record 中生成一条待付款记录:

      • 计算 record_amount(该渠道所有未付款账单的 pay_amount 之和)

      • 计算 cfd_amount(该渠道所有CFD流水的总额)

      • 比对两者金额,写入 match_status(此处如果存在不一致,理论上可以在拆分阶段拦截,但更推荐在全量校验前置阶段拦截,确保拆单出来的都是正确的)

      • 设置 payment_status = 'pending'

    6. 返回给前端:校验结果(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": "张三" }

  • 逻辑(必须开启数据库事务):

    1. 幂等与状态校验:查询 t_channel_payment_record,校验 match_status == 'success' 且 payment_status == 'pending'。若不符,拒绝请求。

    2. 余额校验:查询 t_account,校验所选账户余额是否充足(balance >= record_amount)。

    3. 公户校验:校验前端传来的 public_account_name 是否与 t_channel_public_account 中该渠道的绑定关系一致(防止前端篡改)。

    4. 生成主记录:向 t_payment_record 写入一条数据(包含渠道、公户、总金额、操作人)。

    5. 生成明细记录:查询该渠道下的所有未付款账单(t_1688_bill 中 cfd_channel = 当前渠道 且 is_paid = 0),逐条写入 t_payment_detail。

    6. 扣减账户余额:更新 t_account 的 balance 减去 record_amount。

    7. 更新状态:

      • 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、供应商、采购金额、费用类型、付款金额、操作人、渠道。

四、 异常处理与容错边界

  1. 空文件/格式错误:导入接口必须拦截非Excel/CSV格式的文件。

  2. 重复导入:对导入的1688账单做去重逻辑(推荐基于订单号+支付时间+金额做MD5唯一校验,避免重复导入相同文件)。

  3. 渠道未配置:在 POST /api/import/cfd 中必须校验渠道存在性,不存在则报错并引导用户去配置。

  4. 全量校验优先级:只有 POST /api/validate 且返回 isPass: true 后,才会生成 t_channel_payment_record 记录。前端不允许在未校验的情况下发起付款。

  5. 金额精度:所有金额比较(包括渠道记录金额 vs CFD金额)必须转为“分”进行比对,杜绝浮点误差。

  6. 公户校验:付款时必须校验公户绑定关系,防止公户与渠道不匹配导致财务挂账。

  7. 幂等性:complete-per-channel 接口需做防重复提交处理(如基于 channel_record_id + payment_status 做幂等)。

  8. 金额超限:接口层面限制单次付款金额上限,防止极端错误数据引发大额扣款。

五、 关键业务流程总结(供开发自查)

  1. 用户在【渠道配置】新增渠道A,绑定公户X。

  2. 用户导入1688账单(无渠道概念)。

  3. 用户在【导入CFD流水】弹窗中,选择渠道A,上传文件。

  4. 点击【全量校验】。系统校验:1688账单总额 vs CFD流水总额;且每条账单都有对应的CFD金额。校验通过后,按渠道A拆分出一条待付款记录。

  5. 用户在【渠道待付款记录】中,看到“渠道A”,金额匹配,点击【完成付款】。选择账期账户,系统自动带入公户X,点击提交。

  6. 事务处理:生成付款主记录、明细记录、扣减账期账户余额、将该渠道所有账单标记为已付款。

  7. 用户可在【历史还款记录】中查询到该笔付款,并能查看包含商品图片、SKU、渠道等完整信息的明细。