rovina/zsp-project
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
2ff3002b19c0c543bb0533ce874939c4b4559dc0
zsp-project/docs/api/前后端路由对接文档.md
jxw 2ff3002b19 feat: 添加项目基础设施、测试框架和路由对接文档 
- 新增 .gitignore、ARCHITECTURE.md 项目基础设施文件
- 新增前后端路由对接文档，完整映射前端页面到后端 API 端点
- 配置前端 Vitest 测试框架，添加 API/Store/Utils/Components 单元测试
- 添加后端 UserService 单元测试
- 新增统一测试运行脚本 scripts/run-tests.sh
- 清理旧文档和过期覆盖率报告文件

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
2026-06-04 08:53:36 +08:00

379 lines
28 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 前后端路由对接文档
> 生成日期: 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` | 同后端 | 一致 |
Reference in New Issue View Git Blame Copy Permalink