国际贸易采购系统产品系统Vibe Coding

一、行业场景
TPA 位于跨境国际贸易采购代理（代采）行业，处于"境外委托方—代采方—供应商"三方协作的中间环节。境外企业有采购需求但缺当地履约能力；代采方统筹采购、出货、报关、结算；供应商按指令备货出货。系统需在同一单据上支撑三类角色协作：委托方（跟踪）、代采方（执行/编辑）、供应商（执行/回传）。
二、业务背景
白暨智航科技面向代采业务，需构建覆盖"采购—出货—报关—标签—库存—账单"全链路的协同平台。数据模型已落地八大域；并以多租户 + 参与方中间表 + 角色权限（只读/可编辑）实现数据隔离；报关商品基础资料以 record_owner（SUPPLIER/AGENT）+ source_record_id 实现分级持有与溯源。
三、立项原因
1. 代采规模化后，邮件/Excel/群聊协同不可持续；
2. 多方协作必须建立在可控数据权限之上；
3. 报关合规是刚性门槛（HS 编码、申报要素错漏直接清关失败）；
4. 与外部 SRM（汉得 HZERO、GIPT）割裂导致重复录入；
5. 全链路可追溯是客户信任与风控基础；
6. 多租户 SaaS 化是业务扩展必然要求。
四、旨在解决的核心问题
协同效率（信息割裂）→ 统一平台全流程可视；数据隔离（越权风险）→ 多租户 + 角色权限；报关合规（格式不一）→ 结构化主数据可溯源；系统集成（重复录入）→ API 对接自动抓取；可追溯性（无留痕）→ 变更/出入库/邮件全程记录；结算对账（分散）→ 账单 + 发票 + 付款一体化；运营扩展（单体难支撑）→ 多租户架构。
五、系统定位
TPA 是国际贸易代采业务的协同中台，以采购订单为主线，向上承接境外需求、向下统筹供应商出货与报关，横向打通标签、库存、账单与对外集成，实现"订单可视、数据可控、合规可溯、结算可核"的代采运营闭环。

TPA 共 29 个 Controller、约 154 个接口，按 8 大模块组织；接口统一以 /private 为前缀，分代采方、供应商、代采方账单三类视角，与 party_type / viewAuthority 权限双重隔离。
1. 采购管理：代采建单、Excel 导入自动拆单、供应商确认/拒绝明细、采购变更审核闭环（含变更日志）。
2. 供应商与企业管理：供应商机构主数据、供应商编码、免登录注册（邀请码）、境内外企业档案与关联仓库配置。
3. 出货交付：出货单（草稿→已发货→已接收/退回）、箱号追踪、包装录入（同步入库与实时库存）、到货计划、送货单 PDF 下载。
4. 报关出口：出境单全流程（提交/确认出境/确认采购方入库）、出口海关草单、草单与出境单按"商品编码 + 料号"比对、报关商品主数据（供应商/代采方双套 + source_record_id 溯源）。
5. 标签管理：标签层级、装箱规则、标签任务生成、实例批量打印（ZXing 条码）。
6. 库存管理：实时库存、入库/出库流水及统计，可用库存供出境单选择。
7. 账单与结算：供应商提交账单与开票明细、代采方审核核实、申请付款（货款 + 税款两条）。
8. 协同与集成：邮件通知留痕、API 端点配置对接外部 SRM（汉得 HZERO / GIPT）自动抓取采购订单。
各模块均含列表分页、详情、导入/导出、状态流转等标准功能，形成从采购到结算的完整代采业务闭环。

技术栈
Spring Boot 3.5.14（Java17）；MyBatis-Plus+Druid；Redis 锁；Flowable 7.2.0；Spring AI（GLM-5.2）；POI/fastexcel（Excel）、PDFBox+NotoSansSC（PDF）、Tess4j（OCR）、ZXing（条码）；阿里云OSS/七牛存储；Maven 9 模块聚合。数据库 PostgreSQL+MySQL 双库，TPA 现用 MySQL 方言。
架构
Maven 聚合 9 模块，TPA 分层 controller→service→mapper→entity+enums。规约：自定义 BaseEntity/IService/ServiceImpl、@RequiredArgsConstructor、/private 三视角前缀、常量枚举化、乐观锁/逻辑删除、批处理禁循环、AOP 日志、Redis 锁。隔离：tenant_id + participant（party_type/viewAuthority）中间表；报关主数据 record_owner+source_record_id 溯源。
亮点
复合数据隔离；报关主数据双套持有+溯源；库存强一致联动（包装录入同步入库、出境单删除回退）；配置化 SRM 对接（OAuth2+H-Menu-Id 抓单）；草单比对、标签自动化、AI 合规校验。
难点
多方+多租户隔离边界；双库治理与清理；报关合规多规则；SRM 鉴权与映射稳定；库存并发一致；同表多角色三链路；复杂状态机逆向操作。