2ff3002b19
- 新增 .gitignore、ARCHITECTURE.md 项目基础设施文件 - 新增前后端路由对接文档，完整映射前端页面到后端 API 端点 - 配置前端 Vitest 测试框架，添加 API/Store/Utils/Components 单元测试 - 添加后端 UserService 单元测试 - 新增统一测试运行脚本 scripts/run-tests.sh - 清理旧文档和过期覆盖率报告文件 Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
28 KiB
28 KiB
前后端路由对接文档
生成日期: 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 |
同后端 | 一致 |