# 前后端路由对接文档

> 生成日期: 2026-06-03

本文档记录前端页面 → 前端 API 模块 → 后端 API 端点 → 后端 Handler 方法的完整映射关系，以及已发现的对接问题。

---

## 1. 认证模块 (Auth)

### 1.1 用户登录

| 前端页面 | 前端 API 函数 | 前端请求 URL | 方法 | 后端路由 | 后端 Handler |
|---|---|---|---|---|---|
| `/login` | `getLogin()` | `/login` | POST | — (由框架处理) | — |

### 1.2 用户注册

| 前端页面 | 前端 API 函数 | 前端请求 URL | 方法 | 后端路由 | 后端 Handler |
|---|---|---|---|---|---|
| `/login` (注册页) | `registerApi()` | `/api/auth/register` | POST | `POST /api/auth/register` | `UserHandler.Register` |

### 1.3 Token 刷新

| 前端页面 | 前端 API 函数 | 前端请求 URL | 方法 | 后端路由 | 后端 Handler |
|---|---|---|---|---|---|
| (拦截器自动) | `refreshTokenApi()` | `/refresh-token` | POST | — | — |

### 1.4 用户信息

| 前端页面 | 前端 API 函数 | 前端请求 URL | 方法 | 后端路由 | 后端 Handler |
|---|---|---|---|---|---|
| Layout (Navbar) | — | `GET /api/users/:id` | GET | `GET /api/users/:id` | `UserHandler.GetUser` |

---

## 2. 合同管理模块 (Contract)

### 2.1 业务合同管理 — `/system/contract/manage/index`

| 操作 | 前端 API 函数 | 前端请求 URL | 方法 | 后端路由 | 后端 Handler |
|---|---|---|---|---|---|
| 合同列表 | `getContractList()` | `GET /api/contract` | GET | `GET /api/contract` | `ContractHandler.List` |
| 合同详情 | `getContract()` | `GET /api/contract/:id` | GET | `GET /api/contract/:id` | `ContractHandler.Get` |
| 上传合同 | `submitContract()` | `POST /api/contract/upload` | POST | `POST /api/contract/upload` | `ContractHandler.Upload` |
| 批量上传 | `batchUploadContracts()` | `POST /api/contract/batch-upload` | POST | `POST /api/contract/batch-upload` | `ContractHandler.BatchUpload` |
| 更新合同(含文件) | `updateContractWithFiles()` | `POST /api/contract/:id/update-files` | POST | `POST /api/contract/:id/update-files` | `ContractHandler.UpdateWithFiles` |
| 更新合同(仅字段) | `updateContract()` | `PUT /api/contract/:id` | PUT | `PUT /api/contract/:id` | `ContractHandler.Update` |
| 删除合同 | `deleteContract()` | `DELETE /api/contract/:id` | DELETE | `DELETE /api/contract/:id` | `ContractHandler.Delete` |
| 文件夹列表 | `getContractFolders()` | `GET /api/contract/folders` | GET | `GET /api/contract/folders` | `ContractHandler.ListFolders` |
| 创建文件夹 | `createContractFolder()` | `POST /api/contract/folders` | POST | `POST /api/contract/folders` | `ContractHandler.CreateFolder` |
| 更新文件夹 | `updateContractFolder()` | `PUT /api/contract/folders/:id` | PUT | `PUT /api/contract/folders/:id` | `ContractHandler.UpdateFolder` |
| 删除文件夹 | `deleteContractFolder()` | `DELETE /api/contract/folders/:id` | DELETE | `DELETE /api/contract/folders/:id` | `ContractHandler.DeleteFolder` |
| 批次列表 | `getContractBatches()` | `GET /api/contract/batches` | GET | `GET /api/contract/batches` | `ContractHandler.ListBatches` |
| 创建批次 | `createContractBatch()` | `POST /api/contract/batches` | POST | `POST /api/contract/batches` | `ContractHandler.CreateBatch` |
| 批次详情 | `getContractBatch()` | `GET /api/contract/batches/:id` | GET | `GET /api/contract/batches/:id` | `ContractHandler.GetBatch` |
| 删除批次 | `deleteContractBatch()` | `DELETE /api/contract/batches/:id` | DELETE | `DELETE /api/contract/batches/:id` | `ContractHandler.DeleteBatch` |

**状态**: 全部对接

### 2.2 业务合同新增 — `/system/contract/add-contract/index`

与 2.1 共用同一套 API，主要使用 `submitContract()` 和 `batchUploadContracts()`。

### 2.3 中尚鹏合同管理 — `/system/contract/zsp-contract/index`

| 操作 | 前端 API 函数 | 前端请求 URL | 方法 | 后端路由 | 后端 Handler |
|---|---|---|---|---|---|
| 文件夹列表 | `getZSPContractFolders()` | `GET /api/zsp-contract/folders` | GET | `GET /api/zsp-contract/folders` | `ZSPContractHandler.GetFolders` |
| 创建文件夹 | `createZSPContractFolder()` | `POST /api/zsp-contract/folders` | POST | `POST /api/zsp-contract/folders` | `ZSPContractHandler.CreateFolder` |
| 更新文件夹 | `updateZSPContractFolder()` | `PUT /api/zsp-contract/folders/:id` | PUT | `PUT /api/zsp-contract/folders/:id` | `ZSPContractHandler.UpdateFolder` |
| 删除文件夹 | `deleteZSPContractFolder()` | `DELETE /api/zsp-contract/folders/:id` | DELETE | `DELETE /api/zsp-contract/folders/:id` | `ZSPContractHandler.DeleteFolder` |
| 合同列表 | `getZSPContracts()` | `GET /api/zsp-contract/contracts` | GET | `GET /api/zsp-contract/contracts` | `ZSPContractHandler.ListContractsWithDetails` |
| 合同详情 | `getZSPContract()` | `GET /api/zsp-contract/contracts/:id` | GET | `GET /api/zsp-contract/contracts/:id` | `ZSPContractHandler.GetContractWithDetails` |
| 上传合同 | `uploadZSPContract()` | `POST /api/zsp-contract/contracts` | POST | `POST /api/zsp-contract/contracts` | `ZSPContractHandler.UploadContract` |
| 更新合同 | `updateZSPContract()` | `PUT /api/zsp-contract/contracts/:id` | PUT | `PUT /api/zsp-contract/contracts/:id` | `ZSPContractHandler.UpdateContract` |
| 删除合同 | `deleteZSPContract()` | `DELETE /api/zsp-contract/contracts/:id` | DELETE | `DELETE /api/zsp-contract/contracts/:id` | `ZSPContractHandler.DeleteContract` |
| 详情列表 | `getZSPContractDetails()` | `GET /api/zsp-contract/contracts/:id/details` | GET | `GET /api/zsp-contract/contracts/:id/details` | `ZSPContractHandler.ListContractDetails` |
| 创建详情 | `createZSPContractDetail()` | `POST /api/zsp-contract/contracts/:id/details` | POST | `POST /api/zsp-contract/contracts/:id/details` | `ZSPContractHandler.CreateContractDetail` |
| 更新详情 | `updateZSPContractDetail()` | `PUT /api/zsp-contract/details/:id` | PUT | `PUT /api/zsp-contract/details/:id` | `ZSPContractHandler.UpdateContractDetail` |
| 删除详情 | `deleteZSPContractDetail()` | `DELETE /api/zsp-contract/details/:id` | DELETE | `DELETE /api/zsp-contract/details/:id` | `ZSPContractHandler.DeleteContractDetail` |
| 批量创建详情 | `batchCreateZSPContractDetails()` | `POST /api/zsp-contract/details/batch` | POST | `POST /api/zsp-contract/details/batch` | `ZSPContractHandler.BatchCreateContractDetails` |
| Excel 导入 | `importZSPContractDetailsFromExcel()` | `POST /api/zsp-contract/contracts/:id/details/import` | POST | `POST /api/zsp-contract/contracts/:id/details/import` | `ZSPContractHandler.ImportContractDetailsFromExcel` |
| Excel 导出 | `exportZSPContractDetailsToExcel()` | `GET /api/zsp-contract/contracts/:id/details/export` | GET | `GET /api/zsp-contract/contracts/:id/details/export` | `ZSPContractHandler.ExportContractDetailsToExcel` |

**状态**: 全部对接

### 2.4 公司信息管理 — `/system/contract/company-info/index`

| 操作 | 前端 API 函数 | 前端请求 URL | 方法 | 后端路由 | 后端 Handler |
|---|---|---|---|---|---|
| 文件夹列表 | `getCompanyFolders()` | `GET /api/company/folders` | GET | `GET /api/company/folders` | `CompanyHandler.ListFolders` |
| 创建文件夹 | `createCompanyFolder()` | `POST /api/company/folders` | POST | `POST /api/company/folders` | `CompanyHandler.CreateFolder` |
| 更新文件夹 | `updateCompanyFolder()` | `PUT /api/company/folders/:id` | PUT | `PUT /api/company/folders/:id` | `CompanyHandler.UpdateFolder` |
| 删除文件夹 | `deleteCompanyFolder()` | `DELETE /api/company/folders/:id` | DELETE | `DELETE /api/company/folders/:id` | `CompanyHandler.DeleteFolder` |
| 文件列表 | `getCompanyFiles()` | `GET /api/company/files` | GET | `GET /api/company/files` | `CompanyHandler.ListFiles` |
| 上传文件 | `uploadCompanyFile()` | `POST /api/company/files/upload` | POST | `POST /api/company/files/upload` | `CompanyHandler.UploadFiles` |
| 更新文件 | `updateCompanyFile()` | `PUT /api/company/files/:id` | PUT | `PUT /api/company/files/:id` | `CompanyHandler.UpdateFile` |
| 删除文件 | `deleteCompanyFile()` | `DELETE /api/company/files/:id` | DELETE | `DELETE /api/company/files/:id` | `CompanyHandler.DeleteFile` |
| 下载文件 | `downloadCompanyFile()` | `GET /api/company/files/:id/download` | GET | ❌ 缺失 | — |

**问题**: `GET /api/company/files/:id/download` 在前端已定义，但后端 `route.go` 中无对应路由。

---

## 3. 提货管理模块 (Delivery)

### 3.1 我要提货 — `/system/delivery/apply-delivery/index`

| 操作 | 前端 API 函数 | 前端请求 URL | 方法 | 后端路由 | 后端 Handler |
|---|---|---|---|---|---|
| 委托列表 | `getDeliveryList()` | `GET /api/apply-delivery` | GET | `GET /api/apply-delivery` | `DeliveryHandler.ListApply` |
| 委托详情 | `getDeliveryDetail()` | `GET /api/apply-delivery/:id` | GET | `GET /api/apply-delivery/:id` | `DeliveryHandler.GetApply` |
| 创建委托 | `createDelivery()` | `POST /api/apply-delivery` | POST | `POST /api/apply-delivery` | `DeliveryHandler.CreateApply` |
| 更新委托 | `updateDelivery()` | `PUT /api/apply-delivery/:id` | PUT | `PUT /api/apply-delivery/:id` | `DeliveryHandler.UpdateApply` |
| 取消委托 | `cancelDelivery()` | `PUT /api/apply-delivery/:id/cancel` | PUT | `PUT /api/apply-delivery/:id/cancel` | `DeliveryHandler.CancelApply` |
| 删除委托 | `deleteDelivery()` | `DELETE /api/apply-delivery/:id` | DELETE | `DELETE /api/apply-delivery/:id` | `DeliveryHandler.DeleteApply` |
| 下载模板 | `downloadDeliveryTemplate()` | `GET /api/apply-delivery/template/download` | GET | ❌ 缺失 | — |
| 导出列表 | `exportDeliveryList()` | `GET /api/apply-delivery/export` | GET | ❌ 缺失 | — |

**问题**: 模板下载和导出列表两个端点在后端未实现。

### 3.2 提货明细 — `/system/delivery/delivery-details/index`

| 操作 | 前端 API 函数 | 前端请求 URL | 方法 | 后端路由 | 后端 Handler |
|---|---|---|---|---|---|
| 明细列表 | `getDeliveryDetails()` | `GET /api/delivery-details` | GET | `GET /api/delivery-details` | `DeliveryHandler.ListOutbound` |
| 明细详情 | `getDeliveryDetail()` | `GET /api/delivery-details/:id` | GET | `GET /api/delivery-details/:id` | `DeliveryHandler.GetOutbound` |
| 创建出库单 | `createOutboundOrder()` | `POST /api/delivery-details` | POST | `POST /api/delivery-details` | `DeliveryHandler.CreateOutbound` |
| 更新出库单 | `updateOutboundOrder()` | `PUT /api/delivery-details/:id` | PUT | `PUT /api/delivery-details/:id` | `DeliveryHandler.UpdateOutbound` |
| 删除出库单 | `deleteDeliveryDetail()` | `DELETE /api/delivery-details/:id` | DELETE | `DELETE /api/delivery-details/:id` | `DeliveryHandler.DeleteOutbound` |
| 收货确认 | `confirmReceipt()` | `PUT /api/delivery-details/confirm-receipt/:id` | PUT | ❌ 缺失 | — |
| 收货历史 | `getReceiptHistory()` | `GET /api/delivery-details/receipt-history/:id` | GET | ❌ 缺失 | — |
| 下载模板 | `getOutboundOrderTemplate()` | `GET /api/delivery-details/template/download` | GET | ❌ 缺失 | — |
| 导出数据 | `exportDeliveryDetails()` | `GET /api/delivery-details/export` | GET | ❌ 缺失 | — |
| 打印提货单 | `printDeliveryOrder()` | `GET /api/delivery-details/print/:id` | GET | ❌ 缺失 | — |

**问题**: 5 个端点在后端未实现（收货确认、收货历史、模板下载、导出、打印）。

### 3.3 库存信息 — `/system/delivery/inventory-info/index`

| 操作 | 前端 API 函数 | 前端请求 URL | 方法 | 后端路由 | 后端 Handler |
|---|---|---|---|---|---|
| 仓库列表 | `getWarehouseList()` | `GET /api/inventory/warehouses` | GET | `GET /api/inventory/warehouses` | `DeliveryHandler.ListWarehouses` |
| 创建仓库 | `createWarehouse()` | `POST /api/inventory/warehouses` | POST | `POST /api/inventory/warehouses` | `DeliveryHandler.CreateWarehouse` |
| 更新仓库 | `updateWarehouse()` | `PUT /api/inventory/warehouses/:id` | PUT | `PUT /api/inventory/warehouses/:id` | `DeliveryHandler.UpdateWarehouse` |
| 删除仓库 | `deleteWarehouse()` | `DELETE /api/inventory/warehouses/:id` | DELETE | `DELETE /api/inventory/warehouses/:id` | `DeliveryHandler.DeleteWarehouse` |
| 入库单列表 | `getInventoryList()` | `GET /api/inventory/inbound` | GET | `GET /api/inventory/inbound` | `DeliveryHandler.ListInbound` |
| 入库单详情 | `getInventoryDetail()` | `GET /api/inventory/inbound/:id` | GET | — (无单独详情路由) | — |
| 创建入库单 | `createInventoryInbound()` | `POST /api/inventory/inbound` | POST | `POST /api/inventory/inbound` | `DeliveryHandler.CreateInbound` |
| 更新入库单 | `updateInventoryInbound()` | `PUT /api/inventory/inbound/:id` | PUT | `PUT /api/inventory/inbound/:id` | `DeliveryHandler.UpdateInbound` |
| 删除入库单 | `deleteInventoryInbound()` | `DELETE /api/inventory/inbound/:id` | DELETE | `DELETE /api/inventory/inbound/:id` | `DeliveryHandler.DeleteInbound` |
| 库存汇总 | `getInventorySummary()` | `GET /api/inventory/summary` | GET | `GET /api/inventory/summary` | `DeliveryHandler.InventorySummary` |
| 货权转移(库存) | `createCargoTransfer()` | `POST /api/inventory/transfer/create` | POST | ❌ 缺失 | — |
| 下载模板 | `getInventoryInboundTemplate()` | `GET /api/inventory/template/download` | GET | ❌ 缺失 | — |
| 导出库存 | `exportInventoryList()` | `GET /api/inventory/export` | GET | ❌ 缺失 | — |
| 批量上传 | `uploadInventoryFiles()` | `POST /api/inventory/upload` | POST | ❌ 缺失 | — |

**问题**: 5 个端点在后端未实现。

### 3.4 货权转移 — `/system/delivery/ownership-transfer/index`

| 操作 | 前端 API 函数 | 前端请求 URL | 方法 | 后端路由 | 后端 Handler |
|---|---|---|---|---|---|
| 转移列表 | `getOwnershipList()` | `GET /api/ownership-transfer` | GET | `GET /api/ownership-transfer` | `DeliveryHandler.ListOwnership` |
| 创建(无文件) | `createOwnershipTransfer()` | `POST /api/ownership-transfer` | POST | `POST /api/ownership-transfer` | `DeliveryHandler.CreateOwnership` |
| 创建(含文件) | `createOwnershipTransfer()` | `POST /api/ownership-transfer/with-files` | POST | `POST /api/ownership-transfer/with-files` | `DeliveryHandler.CreateOwnershipWithFiles` |
| 删除 | `deleteOwnershipTransfer()` | `DELETE /api/ownership-transfer/:id` | DELETE | `DELETE /api/ownership-transfer/:id` | `DeliveryHandler.DeleteOwnership` |

**问题**: 无 `GET /api/ownership-transfer/:id` 详情接口，前端也未调用。

### 3.5 其他出库 — `/system/delivery/other-delivery/index`

暂无对应 API 调用，页面为占位。

---

## 4. 财务管理模块 (Finance)

### 4.1 货代费用 — `/system/finance/freight-charges/index`

| 操作 | 前端 API 函数 | 前端请求 URL | 方法 | 后端路由 | 后端 Handler |
|---|---|---|---|---|---|
| 列表 | `getFreightCharges()` | `GET /zsp-finances/freight-charges` | GET | `GET /api/zsp-finances/freight-charges` | `ZSPFinancesHandler.ListFreightCharges` |
| 详情 | `getFreightCharge()` | `GET /zsp-finances/freight-charges/:id` | GET | `GET /api/zsp-finances/freight-charges/:id` | `ZSPFinancesHandler.GetFreightCharge` |
| 创建 | `createFreightCharge()` | `POST /zsp-finances/freight-charges` | POST | `POST /api/zsp-finances/freight-charges` | `ZSPFinancesHandler.CreateFreightCharge` |
| 更新 | `updateFreightCharge()` | `PUT /zsp-finances/freight-charges/:id` | PUT | `PUT /api/zsp-finances/freight-charges/:id` | `ZSPFinancesHandler.UpdateFreightCharge` |
| 删除 | `deleteFreightCharge()` | `DELETE /zsp-finances/freight-charges/:id` | DELETE | `DELETE /api/zsp-finances/freight-charges/:id` | `ZSPFinancesHandler.DeleteFreightCharge` |

### 4.2 杂费管理 — `/system/finance/misc-charges/index`

| 操作 | 前端 API 函数 | 前端请求 URL | 方法 | 后端路由 | 后端 Handler |
|---|---|---|---|---|---|
| 列表 | `getMiscCharges()` | `GET /zsp-finances/misc-charges` | GET | `GET /api/zsp-finances/misc-charges` | `ZSPFinancesHandler.ListMiscCharges` |
| 详情 | `getMiscCharge()` | `GET /zsp-finances/misc-charges/:id` | GET | `GET /api/zsp-finances/misc-charges/:id` | `ZSPFinancesHandler.GetMiscCharge` |
| 创建 | `createMiscCharge()` | `POST /zsp-finances/misc-charges` | POST | `POST /api/zsp-finances/misc-charges` | `ZSPFinancesHandler.CreateMiscCharge` |
| 更新 | `updateMiscCharge()` | `PUT /zsp-finances/misc-charges/:id` | PUT | `PUT /api/zsp-finances/misc-charges/:id` | `ZSPFinancesHandler.UpdateMiscCharge` |
| 删除 | `deleteMiscCharge()` | `DELETE /zsp-finances/misc-charges/:id` | DELETE | `DELETE /api/zsp-finances/misc-charges/:id` | `ZSPFinancesHandler.DeleteMiscCharge` |

### 4.3 服务费管理 — `/system/finance/service-fees/index`

| 操作 | 前端 API 函数 | 前端请求 URL | 方法 | 后端路由 | 后端 Handler |
|---|---|---|---|---|---|
| 列表 | `getServiceFees()` | `GET /zsp-finances/service-fees` | GET | `GET /api/zsp-finances/service-fees` | `ZSPFinancesHandler.ListServiceFees` |
| 详情 | `getServiceFee()` | `GET /zsp-finances/service-fees/:id` | GET | `GET /api/zsp-finances/service-fees/:id` | `ZSPFinancesHandler.GetServiceFee` |
| 创建 | `createServiceFee()` | `POST /zsp-finances/service-fees` | POST | `POST /api/zsp-finances/service-fees` | `ZSPFinancesHandler.CreateServiceFee` |
| 更新 | `updateServiceFee()` | `PUT /zsp-finances/service-fees/:id` | PUT | `PUT /api/zsp-finances/service-fees/:id` | `ZSPFinancesHandler.UpdateServiceFee` |
| 删除 | `deleteServiceFee()` | `DELETE /zsp-finances/service-fees/:id` | DELETE | `DELETE /api/zsp-finances/service-fees/:id` | `ZSPFinancesHandler.DeleteServiceFee` |

### 4.4 利润明细 — `/system/finance/profit-details/index`

| 操作 | 前端 API 函数 | 前端请求 URL | 方法 | 后端路由 | 后端 Handler |
|---|---|---|---|---|---|
| 成本列表 | `getCostBreakdowns()` | `GET /zsp-finances/cost-breakdowns` | GET | `GET /api/zsp-finances/cost-breakdowns` | `ZSPFinancesHandler.ListCostBreakdowns` |
| 成本详情 | `getCostBreakdown()` | `GET /zsp-finances/cost-breakdowns/:id` | GET | `GET /api/zsp-finances/cost-breakdowns/:id` | `ZSPFinancesHandler.GetCostBreakdown` |
| 创建成本 | `createCostBreakdown()` | `POST /zsp-finances/cost-breakdowns` | POST | `POST /api/zsp-finances/cost-breakdowns` | `ZSPFinancesHandler.CreateCostBreakdown` |
| 更新成本 | `updateCostBreakdown()` | `PUT /zsp-finances/cost-breakdowns/:id` | PUT | `PUT /api/zsp-finances/cost-breakdowns/:id` | `ZSPFinancesHandler.UpdateCostBreakdown` |
| 删除成本 | `deleteCostBreakdown()` | `DELETE /zsp-finances/cost-breakdowns/:id` | DELETE | `DELETE /api/zsp-finances/cost-breakdowns/:id` | `ZSPFinancesHandler.DeleteCostBreakdown` |
| 利润列表 | `getProfitRecords()` | `GET /zsp-finances/profit-records` | GET | `GET /api/zsp-finances/profit-records` | `ZSPFinancesHandler.ListProfitRecords` |
| 利润详情 | `getProfitRecord()` | `GET /zsp-finances/profit-records/:id` | GET | `GET /api/zsp-finances/profit-records/:id` | `ZSPFinancesHandler.GetProfitRecord` |
| 创建利润 | `createProfitRecord()` | `POST /zsp-finances/profit-records` | POST | `POST /api/zsp-finances/profit-records` | `ZSPFinancesHandler.CreateProfitRecord` |
| 更新利润 | `updateProfitRecord()` | `PUT /zsp-finances/profit-records/:id` | PUT | `PUT /api/zsp-finances/profit-records/:id` | `ZSPFinancesHandler.UpdateProfitRecord` |
| 删除利润 | `deleteProfitRecord()` | `DELETE /zsp-finances/profit-records/:id` | DELETE | `DELETE /api/zsp-finances/profit-records/:id` | `ZSPFinancesHandler.DeleteProfitRecord` |

### 4.5 发票管理 — `/system/finance/invoice/index`

| 操作 | 前端 API 函数 | 前端请求 URL | 方法 | 后端路由 | 后端 Handler |
|---|---|---|---|---|---|
| 上游发票列表 | `getUpstreamInvoices()` | `GET /zsp-finances/upstream-invoices` | GET | ❌ 缺失 | — |
| 创建上游发票 | `createUpstreamInvoice()` | `POST /zsp-finances/upstream-invoices` | POST | ❌ 缺失 | — |
| 删除上游发票 | `deleteUpstreamInvoice()` | `DELETE /zsp-finances/upstream-invoices/:id` | DELETE | ❌ 缺失 | — |
| 上传上游发票文件 | `uploadUpstreamInvoiceFile()` | `POST /zsp-finances/upstream-invoices/:id/upload` | POST | ❌ 缺失 | — |
| 下游发票列表 | `getDownstreamInvoices()` | `GET /zsp-finances/downstream-invoices` | GET | ❌ 缺失 | — |
| 创建下游发票 | `createDownstreamInvoice()` | `POST /zsp-finances/downstream-invoices` | POST | ❌ 缺失 | — |
| 删除下游发票 | `deleteDownstreamInvoice()` | `DELETE /zsp-finances/downstream-invoices/:id` | DELETE | ❌ 缺失 | — |
| 上传下游发票文件 | `uploadDownstreamInvoiceFile()` | `POST /zsp-finances/downstream-invoices/:id/upload` | POST | ❌ 缺失 | — |
| 杂费发票列表 | `getFreightMiscInvoices()` | `GET /zsp-finances/freight-misc-invoices` | GET | ❌ 缺失 | — |
| 创建杂费发票 | `createFreightMiscInvoice()` | `POST /zsp-finances/freight-misc-invoices` | POST | ❌ 缺失 | — |
| 删除杂费发票 | `deleteFreightMiscInvoice()` | `DELETE /zsp-finances/freight-misc-invoices/:id` | DELETE | ❌ 缺失 | — |
| 上传杂费发票文件 | `uploadFreightMiscInvoiceFile()` | `POST /zsp-finances/freight-misc-invoices/:id/upload` | POST | ❌ 缺失 | — |

**问题**: 整个发票模块（3 类发票共 12 个端点）后端路由全部缺失。Model 已定义（`ZSPUpstreamInvoice`, `ZSPDownstreamInvoice`, `ZSPFreightMiscInvoice`）且在 AutoMigrate 中，但 Handler/Service/Repository 层均未实现。

### 4.6 结算管理 — `/system/finance/settlement/index`

| 操作 | 前端 API 函数 | 前端请求 URL | 方法 | 后端路由 | 后端 Handler |
|---|---|---|---|---|---|
| 结算列表 | `getSettlements()` | `GET /zsp-finances/settlements` | GET | ❌ 缺失 | — |
| 结算详情 | `getSettlement()` | `GET /zsp-finances/settlements/:id` | GET | ❌ 缺失 | — |
| 创建结算 | `createSettlement()` | `POST /zsp-finances/settlements` | POST | ❌ 缺失 | — |
| 更新结算 | `updateSettlement()` | `PUT /zsp-finances/settlements/:id` | PUT | ❌ 缺失 | — |
| 删除结算 | `deleteSettlement()` | `DELETE /zsp-finances/settlements/:id` | DELETE | ❌ 缺失 | — |
| 上传结算文件 | `uploadSettlementFile()` | `POST /zsp-finances/settlements/:id/upload` | POST | ❌ 缺失 | — |

**问题**: 整个结算模块（6 个端点）后端路由全部缺失。

### 4.7 对账单 — `/system/finance/statement/index`

| 操作 | 前端 API 函数 | 前端请求 URL | 方法 | 后端路由 | 后端 Handler |
|---|---|---|---|---|---|
| 对账列表 | `getReconciliations()` | `GET /zsp-finances/reconciliations` | GET | ❌ 缺失 | — |
| 对账详情 | `getReconciliation()` | `GET /zsp-finances/reconciliations/:id` | GET | ❌ 缺失 | — |
| 创建对账 | `createReconciliation()` | `POST /zsp-finances/reconciliations` | POST | ❌ 缺失 | — |
| 更新对账 | `updateReconciliation()` | `PUT /zsp-finances/reconciliations/:id` | PUT | ❌ 缺失 | — |
| 删除对账 | `deleteReconciliation()` | `DELETE /zsp-finances/reconciliations/:id` | DELETE | ❌ 缺失 | — |
| 上传对账文件 | `uploadReconciliationFile()` | `POST /zsp-finances/reconciliations/:id/upload` | POST | ❌ 缺失 | — |

**问题**: 整个对账单模块（6 个端点）后端路由全部缺失。

---

## 5. 采购管理模块 (Purchase)

| 前端页面 | 路由路径 | 后端 API |
|---|---|---|
| 采购报单 | `/system/purchase/purchase-order/index` | 无 |
| 采购运踪明细 | `/system/purchase/shipment-tracking/index` | 无 |
| 国外供应商 | `/system/purchase/overseas-supplier/index` | 无 |
| 采购预算 | `/system/purchase/procurement-budget/index` | 无 |

**状态**: 整个采购模块前后端均未实现 API。4 个页面为占位。

---

## 6. 查询&报表中心 (Reports)

| 前端页面 | 路由路径 | 后端 API |
|---|---|---|
| 合同执行情况 | `/system/query-report/contract-execution/index` | 无 |
| 营业明细表 | `/system/query-report/business-details/index` | 无 |
| 其它明细表 | `/system/query-report/other-details/index` | 无 |
| 商品基础资料 | `/system/query-report/product-basic-info/index` | 无 |
| 其它报表 | `/system/query-report/other-reports/index` | 无 |

**状态**: 整个报表模块前后端均未实现 API。5 个页面为占位。

---

## 7. 对接问题汇总

### 7.1 严重：API 前缀不一致 (Bug)

**影响模块**: 财务管理全部子模块（货代费用、杂费、服务费、成本构成、利润记录）

前端 `zspFinances.ts` 中所有请求 URL 使用 `/zsp-finances/` 前缀，而其他 API 模块使用 `/api/zsp-finances/`。后端路由定义在 `/api/zsp-finances/` 下。

| 文件 | 前端 URL 前缀 | 后端路由前缀 | 是否匹配 |
|---|---|---|---|
| `contract.ts` | `/api/contract` | `/api/contract` | OK |
| `zspContract.ts` | `/api/zsp-contract` | `/api/zsp-contract` | OK |
| `company.ts` | `/api/company` | `/api/company` | OK |
| `applyDelivery.ts` | `/api/apply-delivery` | `/api/apply-delivery` | OK |
| `deliveryDetails.ts` | `/api/delivery-details` | `/api/delivery-details` | OK |
| `inventory.ts` | `/api/inventory` | `/api/inventory` | OK |
| `ownershipTransfer.ts` | `/api/ownership-transfer` | `/api/ownership-transfer` | OK |
| **`zspFinances.ts`** | **`/zsp-finances`** | **`/api/zsp-finances`** | **不匹配** |
| `invoice.ts` | `/zsp-finances` | (不存在) | — |
| `settlement.ts` | `/zsp-finances` | (不存在) | — |
| `reconciliation.ts` | `/zsp-finances` | (不存在) | — |

**修复方案**: 将 `zspFinances.ts`、`invoice.ts`、`settlement.ts`、`reconciliation.ts` 中所有 `/zsp-finances/` 改为 `/api/zsp-finances/`。

### 7.2 严重：前端已实现但后端缺失的路由

以下端点在 Model 层已定义（AutoMigrate），但 Handler / Service / Repository 层未实现，`route.go` 中无对应路由：

| 模块 | 缺失端点数量 | 详情 |
|---|---|---|
| **发票管理** | 12 | 上游发票/下游发票/货代杂费发票 各 CRUD + 文件上传 |
| **结算管理** | 6 | 结算单 CRUD + 文件上传 |
| **对账单** | 6 | 对账单 CRUD + 文件上传 |

### 7.3 中等：前端调用了后端未实现的路由

以下端点在前端 API 模块中已定义和调用，但 `route.go` 中不存在：

| 端点 | 所属模块 |
|---|---|
| `GET /api/company/files/:id/download` | 公司信息 |
| `GET /api/apply-delivery/template/download` | 我要提货 |
| `GET /api/apply-delivery/export` | 我要提货 |
| `PUT /api/delivery-details/confirm-receipt/:id` | 提货明细 |
| `GET /api/delivery-details/receipt-history/:id` | 提货明细 |
| `GET /api/delivery-details/template/download` | 提货明细 |
| `GET /api/delivery-details/export` | 提货明细 |
| `GET /api/delivery-details/print/:id` | 提货明细 |
| `GET /api/inventory/inbound/:id` | 库存信息 |
| `POST /api/inventory/transfer/create` | 库存信息 |
| `GET /api/inventory/template/download` | 库存信息 |
| `GET /api/inventory/export` | 库存信息 |
| `POST /api/inventory/upload` | 库存信息 |

### 7.4 较低：采购管理和报表模块未开发

采购管理（4 页面）和查询报表中心（5 页面）仅有前端占位页面，无任何 API 调用，后端也无对应 Model/Handler。属于待开发模块。

---

## 8. 静态文件路由

| 用途 | 后端路由 | 前端访问方式 |
|---|---|---|
| 合同文件 | `GET /api/contract-files/*` | 直接 URL 访问（公开） |
| ZSP 合同文件 | `GET /api/zsp-contract-files/*` | 直接 URL 访问（公开） |
| 公司文件 | `GET /api/company-files/*` | 直接 URL 访问（公开） |
| 健康检查 | `GET /health` | — |

---

## 9. 路由命名规范对比

| 后端规范 | 前端规范 | 一致性 |
|---|---|---|
| RESTful: `GET /resource`, `POST /resource`, `PUT /resource/:id`, `DELETE /resource/:id` | 同后端 | 一致 |
| 嵌套资源: `/resource/:id/sub-resource` | 同后端 | 一致 |
| 动作后缀: `/resource/:id/cancel`, `/resource/export` | 同后端 | 一致 |
| zsp-contract 用 `/contracts` 作为子资源 | 同后端 | 一致 |
| zsp-finances 用连字符命名: `freight-charges` | 同后端 | 一致 |