Appearance
财务结算中心重构任务模块
数据表权威设计见
DATA_MODEL.md；可直接执行的开发任务、接口和批次 依赖见IMPLEMENTATION_PLAN.md；异常订单终态与自动交接 规则见ABNORMAL_ORDER_FINANCE_HANDOFF.md。
1. 任务目标
将本目录两份 PRD 与两份 Excel 模板合并为一个可实施的「财务结算中心」模块，直接建立 独立的新财务结算体系，完成以下闭环：
- 系统按结算期为每个卖家生成不可变账单快照。
- 卖家查看汇总和分类明细，导出账单后确认账单。
- 平台财务查看全部卖家账单，仅对卖家已确认账单标记平台结算状态。
- 平台按结算期汇总商店街对上结算数据，并按模板导出。
1.1 结算对象边界（2026-08-22）
- 本期唯一结算对象是卖家，账单、确认、平台结算状态和商店街汇总均以卖家为 主体；“平台结算”表示平台完成对卖家账单的结算。
- 物流域只向本模块提供运单、计费、承担方、赔付等业务源事实。卖家实际承担的物流费 进入卖家账单扣减和运单明细，但不因此生成物流方账单或物流方应付。
- 本期不核算平台与物流方之间的应收应付，不建设物流方独立账单、对账确认、付款、 追偿、余额或结算状态。相关需求必须作为独立物流结算任务设计，不得复用卖家账单 状态表达。
- Admin 模板中的
报关&商店街结算&供应商结算Sheet 名称和表头仅因固定模板保留； 首版只能填充可追溯到卖家冻结账单的字段。任何物流方或其他供应商侧应付金额均留空， 不从物流费用反推。
1.2 体系切换裁决（2026-08-22）
- 新体系使用独立表和独立状态机，不扩展旧 Finance V2 财务表。
- 不迁移、转换、回填或清空旧 Finance V2 派生数据；旧账不进入新体系。
- 后续真实交接只接收
finance_ready_at不早于切换边界的订单终态事实。读取业务源数据 不属于财务数据迁移；首版本轮不运行交接或生成新账。 - 旧 Finance V2 在切换前保持原状；新体系验收后的停写、路由切换、归档和删表另立任务， 不在本任务中静默执行。
- 本裁决覆盖此前“在 Finance V2 上重构”“清空旧派生数据后重建”的描述。
1.3 订单进入财务裁决（2026-08-23）
- 新增独立
order.finance_ready_at，不复用completed_at作为财务交接标志。 - 正常订单的
finance_ready_at取completed_at原值；异常订单取权威异常处理完成时间。 - 15 天保护期和异常终态归订单域，财务不读取签收时间重算，也不根据派生展示状态判断。
- 当前异常订单没有持久化的权威完成时间，因此首版只定义契约，不修改订单表、不扫描、 回填、迁移或消费真实订单。
- 本裁决覆盖此前由财务服务计算
buyer_signed_at + 15 天、按财务资格期主动抓取订单的描述。 - 异常订单的终态、进入时间、金额方向和物流后到调整统一以
ABNORMAL_ORDER_FINANCE_HANDOFF.md为准。 - 末端物流责任按订单终态给默认值：正常终态为
buyer，异常终态为seller；退款等有 人工处理环节的流程可在交接前由授权人员改判。财务按交接时最终责任人冻结：seller扣实际生效末端费用，buyer或没有实际末端物流段时扣0.00。 - 流程时机备注：退款有人工操作过程，可在退款完成前修改末端责任人；存在末端物流且 未签收即取消属于自动流程，默认卖家承担并直接进入财务，不预留人工修改时间。
- 订单以
finance_ready_at首次进入财务时冻结终态、责任人与当时金额快照，不建立“迟到 订单”概念；进入后的纠正一律追加调整或冲正，不覆盖初始快照，也不转换原终态。
2. 已核对的现状与统一口径
2.1 现有能力
- 后端已有
financeRecord、financeSnapshot、financeSnapshotLine、monthlyStatement、monthlyStatementItem、payoutTask和事件表；它们只作为现状核对对象，不作为新体系数据基础。 - 当前月结单按上海时区自然月生成，金额为 TWD、数据库使用
numeric字符串表达，计算使用BigNumber；新实现继续遵守该金额边界，禁止 JS 浮点计算。 - 当前卖家端已有「我的进账」「月度结算单」，管理端已有「全托管货款」，但页面字段、角色动作和 PRD 不一致，需要改造而非新增重复页面。
- 当前
monthlyStatement.status的pending -> settled由管理员操作；本任务改为卖家确认与平台结算两个独立状态轴。
2.2 冲突处理
- 确认责任：以 PRD 为准，卖家确认账单；平台财务不得代替卖家确认。
- 卖家导出：以随附《商家财务对账导出模板.xlsx》为准，固定 4 个 Sheet；物流字段放在「订单详情」，不额外生成物流 Sheet。
- 管理端导出：以随附《admin财务对账单据模板.xlsx》为准，固定 7 个 Sheet。
- 结算金额：账单生成时冻结各明细与合计，列表、详情、导出和商店街汇总均读取同一账单快照，禁止在各接口临时重复计算。
- 核心金额公式：
卖家最终结算金额 = 商品收入 + 平台对卖家赔付 - 物流费用 - 平台扣点 - 税费 - 平台处罚 + 其他有符号调整。物流费用同时独立展示并参与扣减；如果上游终态事实已包含物流影响，交接时必须拆分核对，禁止重复扣减。 - 数据切换：不清空、不迁移旧 Finance V2 派生数据。新体系以
2026-08-01 00:00:00 Asia/Shanghai为边界；未来仅接收finance_ready_at不早于边界的 订单终态，旧历史账单不进入新体系。本轮不处理真实数据。 - 订单进入财务：订单域使用独立
finance_ready_at作为唯一交接时间。正常订单取order.completed_at，异常订单取权威异常处理完成时间；15 天保护期和异常终态由订单域 完成，财务不得重新计算或推断。 - 确认与结算：卖家确认只冻结并认可账单；平台财务仅维护
pending/settled状态，settled不可退回。本期不建设posted、发款台账、自动发款或负额自动结转。 - 结算对象：本期只结算卖家。物流费用是卖家应承担成本的扣减证据，不代表平台对 物流方应付款；不得从卖家物流扣减额生成物流方账单、付款或结算状态。
- 末端物流责任：正常订单默认买家承担；退款、已发货取消、物流赔付等异常终态默认 卖家承担，其中退款等人工处理流程可在交接前有审计地改判。财务不从展示状态推断， 只使用交接快照中的最终
borne_by决定扣实际费用或扣0.00。
2.3 UI 原型使用原则
- 本目录两个 UI ZIP 是页面信息架构和布局参考，不是要求逐像素复刻的最终视觉稿。
- 商家端参考 5 个页面：结算中心汇总、订单结算中心、运单管理、往期已结算订单退款、平台处罚明细；Admin 端参考 3 个页面：结算汇总管理、商店街结算、商店街结算明细。
- 页面大体保持原型的统一骨架：现有系统侧栏与面包屑、页面标题和主操作、顶部指标卡、筛选工具条、数据表格、状态标签、分页；详情可按仓库现有交互选择独立页面、Sheet 或 Dialog。
- 批量平台结算仅在 Admin 结算汇总中出现，勾选记录后展示批量操作区；商家端只提供自身账单确认与导出，不出现平台结算操作。
- 具体颜色、字号、间距、图标、卡片尺寸、表格列宽和示例文案不要求完整照抄；优先复用
@ruten/ui、现有 Sidebar、主题变量和响应式规范，保持 seller/admin 当前产品风格。 - 原型中的统计数字、店铺、订单、状态和日期均为展示样例，不得作为默认业务数据。最终字段、状态、权限和操作规则以本任务文档、后端契约及真实响应为准。
3. 实施模块
M1. 新结算领域模型设计
详细表职责、字段、关系、约束和不变量以 DATA_MODEL.md 为准。
- 将「账单生成状态」「卖家确认状态」「平台结算状态」拆为独立字段：生成状态为
generating/ready/failed；卖家状态为unconfirmed/confirmed；平台状态为pending/settled。 - 月结单补充卖家确认人/时间、平台结算操作人/时间；平台状态变更建立独立事件记录，保存账号、时间、变更前后状态和批量操作批次号。
- 为卖家账单增加冻结汇总字段：订单数、订单金额、物流费用、平台扣点、税费、往期退款扣减、平台处罚、卖家最终结算金额、币种；不增加物流方账单汇总。
- 建立账单分类明细或可追溯快照，覆盖订单、物流、历史退款、处罚，以及管理端模板要求的报关/链路/供应商、广告收入、图片翻译收费数据。每条明细必须带来源类型、来源 ID、归属/生效结算期和金额证据。
- 唯一约束保持「卖家 + 结算期一张账单」；订单进入财务后的初始快照禁止原地重算。 未确认账单可追加绑定调整，已确认账单的调整进入之后最早的未确认结算期。
- 本轮只完成权威数据模型设计，不编写建表迁移或首期生成任务；后续 B0 完成并重新授权后 才能实施新表。任何后续实施也不提供旧财务表清理、旧账转换或旧财务数据回填脚本。
M2. 订单交接与账单生成规则
- 后续实施仍使用上海时区自然月；每月 10 日 02:00 生成上一期账单，并由幂等恢复任务补偿 失败或遗漏。账单生成必须在单个事务内冻结汇总、明细和来源关联。
- 首版仅定义交接契约，不运行定时扫描、事件消费、真实账单生成、历史回填或数据迁移。 后续接入时，财务只消费
finance_ready_at IS NOT NULL且尚未交接的dropship订单。 - 正常订单的
finance_ready_at必须等于order.completed_at；异常订单必须等于订单域持久化 的权威异常处理完成时间。当前派生的异常展示状态不能作为时间来源。 - 交接至少携带
tenant_id、order_id、finance_ready_at、终态类型、事实版本、商品收入、 平台赔付、物流费、平台费、税费、币种、正式跨境包裹实际重量和来源证据；财务只校验 完整性与恒等式。订单快照按包裹冻结整数克实际重量及订单实际总重量，并单独保留 kg 计费重量，不得用预估商品重量替代。 - 财务归属期取
finance_ready_at所在的Asia/Shanghai自然月，不保存或计算buyer_signed_at、protection_ends_at、settlement_eligible_at、eligible_period。 - 15 天内完成退款的订单由订单域交付终态金额：商品收入和对应平台费为
0.00，已有正式 事实且由卖家承担的物流费、税费仍可扣减；结算后不设计卖家侧跨期退款扣减。 dropship没有物流记录时物流费确定为0.00，不形成 blocker；存在费用事实但金额、 币种、最终责任人或版本冲突时不得计入，物流只能扣减一次。正常/异常终态分别默认buyer/seller，授权改判覆盖默认值。已发货取消可先按其他已确认 事实入账，后续正式物流事实按异常专项自动调整。- 订单明细聚合订单成交金额、平台扣点、税费；物流费用按运单归属期聚合。
- 往期退款页面和导出 Sheet 首版保留待接入，但不生成跨期退款调整，账单汇总固定展示
0.00。 - 处罚按处罚生效期归集，关联订单允许为空。缺少正式处罚来源表时，先补齐来源模型，不得从 metadata 猜金额。
- 卖家不同意账单时保持
unconfirmed并转线下沟通；首版不增加拒绝、争议或平台代确认状态。 - 生成完成前执行恒等校验：分类明细合计必须与账单冻结汇总一致；失败则账单标记
failed、记录明确原因，不允许产生可确认账单。 - 商店街汇总只聚合卖家已确认账单；同一期存在未确认账单时同时返回已确认/未确认店铺数，平台整体状态按全部店铺的平台状态计算为「部分待结算」或「全部已结算」。
M3. 卖家端 API 与页面
- 提供结算期汇总列表和详情接口，仅返回当前租户数据；支持结算期、账单状态、分页筛选。
- 详情按四类展示：订单结算、运单、往期已结算订单退款、平台处罚；列表和详情均返回冻结金额字符串、
currency: TWD、时间字段 ISO 8601（上海业务日口径）。 - 新增卖家确认接口，要求账单生成成功且当前为未确认；使用条件更新保证幂等和并发安全，重复确认返回明确冲突错误。
- 新增单期导出接口，严格生成 4 Sheet：
结算汇总（合计数据）、订单详情、往期已结算订单退款明细、平台处罚明细；列名与随附商家模板逐列一致。 - 将现有「月度结算单」升级为「结算中心」汇总页，增加确认与导出操作；将「我的进账」改造为订单结算明细，并新增独立运单、历史退款、处罚页面。
- 卖家页面不得展示平台结算状态；确认操作必须显示不可撤销说明，成功后刷新全部相关查询。
M4. 平台财务 API 与页面
- 新增全店铺账单台账接口，支持结算期、店铺、卖家确认状态、平台结算状态和分页筛选，返回 PRD 规定的完整汇总字段及最后操作记录。
- 新增单条与批量平台状态更新接口。只有卖家已确认账单才能执行
pending -> settled；settled表示平台财务已完成线下结算并人工确认，可填写结算备注，且不可退回。任何一条 不满足条件时整批事务失败，禁止部分成功；批量操作共用本次备注。 - 实际向卖家发款和负余额处理在线下完成。账单允许为负，系统只记录真实金额与平台结算 状态，不创建发款任务，也不自动把负余额结转到后续期。
- 新增商店街按期汇总列表、单期店铺下钻详情和导出接口；汇总金额只能来自冻结账单，不从实时订单表重算。
- 管理端账单导出固定 7 Sheet：
结算汇总（合计数据）、报关&商店街结算&供应商结算、订单详情、往期已结算订单退款明细、平台处罚明细、广告收入明细、图片翻译收费明细；列名与随附管理模板逐列一致。其中供应商相关列不代表本期建设供应商或物流方结算，只输出卖家冻结账单已有的可验证字段，其余保留空表头。 - 将现有「全托管货款」拆分/改造为「结算汇总管理」和「商店街结算」两个菜单；新页面 不接入旧发款任务，实际付款保持线下处理。
- 在
ADMIN_MENU_PERMISSION_TREE增加独立读写权限：账单查看、平台结算操作、商店街查看、财务导出；非财务角色不显示菜单且后端同样拒绝访问。
M5. 运营口径隔离
- 本期确保财务 API 和页面不混入市场成交统计口径。
- 将市场成交统计筛选迁至运营中心的具体菜单、接口和旧入口迁移拆为后续独立任务。
M6. 文档、审计与清理
- API 稳定后同步更新 seller/admin 财务 API 文档，明确状态机、金额单位、币种、时区、分页、导出响应和错误码。
- 对确认、平台状态变更、批量操作、导出记录审计日志；批量日志包含请求数量、成功数量、失败数量和操作者。
- 新链路验收完成后只记录旧页面、旧接口和旧表的下线清单；实际停写、删除和归档安排为 单独、可回滚且需授权的后续任务。
4. 交付顺序与依赖
- 第一阶段：领域模型与数据来源 — 完成 M1、M2，先解决处罚以及卖家账单所需物流、税务等真实来源映射；广告、图片翻译、报关/供应商模板扩展字段只接入已验证的卖家账单数据，不扩展为其他结算对象。
- 第二阶段：卖家闭环 — 完成 M3，使卖家可核对、导出并确认账单。
- 第三阶段：平台闭环 — 完成 M4，接收卖家确认状态并完成平台结算与商店街汇总。
- 第四阶段：口径隔离与收尾 — 完成 M5、M6，补文档并输出旧体系后续下线清单， 不在本任务删除旧实现或旧数据。
每一阶段必须以前一阶段的冻结账单数据为唯一数据源，不允许前端先使用临时 mock 字段推进下一阶段。
5. 验收标准
5.1 后端与数据
- 同一卖家同一期重复触发生成任务只产生一张账单，金额与明细不重复。
finance_ready_at为空的订单不得进入财务；正常订单该字段与completed_at相同，异常 订单与权威异常处理完成时间相同，归属期按该字段所在月份确定。- 任取一期，订单、物流、历史退款、处罚分类合计与汇总字段逐项一致，最终结算金额符合公式。
- 卖家只能查询和确认本店账单；管理员不能调用卖家确认接口。
- 未确认账单无法标记平台已结算；批量请求包含未确认账单时整批无状态变化。
- 初始订单快照无法撤销或原地重算；后续物流事实只通过受控调整或冲销影响账单。
- 首版不产生结算后退款调整；真实差异通过受控人工调整或追加式冲销进入后续期。
- 异常订单自动物流调整属于专项例外：交接后新产生的正式物流事实按异常专项规则自动进入 未确认原账单或之后最早的未确认期，不视为结算后退款链路。
- 异常终态形成后禁止转换；终态或责任纠正只能追加调整或冲正。
- 交接后的退税、税费更正及自动调整留待后续专项裁决，首版不自动消费税费变化。
- 所有金额使用 TWD 主单位、两位小数、数据库
numeric、API 字符串；时区统一为Asia/Shanghai。 - 有正式跨境出库事实的订单快照必须保存订单实际总重量、计费重量及逐包裹实际克重，且 汇总重量与包裹证据一致。
- 并发确认、并发平台结算、重复导出和重复生成均有自动化测试。
5.2 前端
- 卖家五个入口按最终菜单顺序可访问：结算中心、订单结算中心、运单管理、往期已结算订单退款、平台处罚明细。
- 管理端可按期次/店铺/两类状态筛选，可单条或批量变更平台状态，并可下钻商店街单期店铺明细。
- 各页面整体信息架构与对应 ZIP 原型一致，并已适配现有 seller/admin 的导航、组件、主题和可用宽度；不以像素级一致作为验收条件。
- 所有列表处理 loading、error、empty、success；筛选和分页写入路由 search params，筛选变化重置第一页。
- 卖家确认和平台状态变更均有确认对话框、提交中禁用、失败信息可见，且不使用浏览器原生确认框。
- 三类账号验收：卖家只见本店数据；运营只见市场统计；财务见全店账单和商店街结算。
5.3 Excel
- 商家导出严格 4 Sheet，管理端导出严格 7 Sheet，Sheet 名称、顺序、表头与本目录模板一致。
- 导出只包含所选结算期，不跨期；空分类保留 Sheet 和表头。
- 文件名为
【结算期次】结算账单_YYYYMMDDHHmmss.xlsx，金额两位小数、表头冻结、列宽可读。 - Excel 汇总金额与页面、API、数据库冻结快照完全一致。
6. 本任务不包含
- 首版真实订单扫描、订单交接事件消费、历史回填、账单生产数据生成及
finance_ready_at的代码写入；本轮只定义契约与后续实施前置条件。 - 系统发款、发款台账、负余额自动结转和已结算状态回退。
- 平台与物流方之间的应收应付核算，以及物流方独立账单、确认、付款、追偿、余额和 结算状态；卖家账单中的物流费扣减不得作为物流方应付金额。
- 未在 PRD 或模板中定义的付款渠道接入、自动打款、发票开立和外部总公司 API 对接。
- 未经授权执行生产数据库清理、迁移或历史数据覆盖。
- 用人工录入或 metadata 临时字段替代缺失的处罚、广告、图片翻译、报关及供应商结算正式数据源。