rovina/zsp-project
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
2f7309a45cd0622dde26234c859e559195db25b6
zsp-project/docs/dev/项目开发文档.md
jxw 2f7309a45c first commit
2026-06-03 20:59:39 +08:00

19 KiB
Executable File
Raw Blame History

项目开发文档

作者:rovina
最近修订日期:2026/3/2

一、项目技术栈概览

层级 技术 说明
前端 Vue 3 + TypeScript + Element Plus 基于 pure-admin-thin 模板
后端 Go + Gin + GORM RESTful API，MySQL 存储
数据库 MySQL 8 (Docker) 数据库名 myapp_dev

二、后端已实现的路由与模型

2.1 已有后端路由（route.go）

# 认证
POST   /api/auth/register
POST   /api/auth/login
GET    /api/users/:id

# 合同上传（旧版，Contract 模型）
POST   /api/contract/upload
POST   /api/contract/batch-upload

# 中尚鹏合同管理（ZSPContract 模型）
POST   /api/zsp-contract/folders
GET    /api/zsp-contract/folders
GET    /api/zsp-contract/folders/:id
PUT    /api/zsp-contract/folders/:id
DELETE /api/zsp-contract/folders/:id
POST   /api/zsp-contract/contracts          （上传合同文件）
GET    /api/zsp-contract/contracts           （含详情列表）
GET    /api/zsp-contract/contracts/:id       （含详情）
DELETE /api/zsp-contract/contracts/:id
POST   /api/zsp-contract/contracts/:id/details
GET    /api/zsp-contract/contracts/:id/details
POST   /api/zsp-contract/details/batch
GET    /api/zsp-contract/details/:id
PUT    /api/zsp-contract/details/:id
DELETE /api/zsp-contract/details/:id
POST   /api/zsp-contract/contracts/:id/details/import   （Excel导入）
GET    /api/zsp-contract/contracts/:id/details/export   （Excel导出）

# 财务管理（ZSPFinances 模型）
CRUD   /api/zsp-finances/freight-charges     （货代费用）
CRUD   /api/zsp-finances/misc-charges        （杂费）
CRUD   /api/zsp-finances/service-fees        （服务费）
CRUD   /api/zsp-finances/cost-breakdowns     （成本构成）
CRUD   /api/zsp-finances/profit-records      （利润记录）

2.2 已有后端数据模型

模型 说明 AutoMigrate
User 用户表 是
Contract 合同（旧版，仅名称/编号/甲乙方等基础字段） 是
ContractFile 合同附件（旧版） 是
ZSPContractFolder 合同文件夹 是
ZSPContractFile 合同文件（含合同编号/公司/商品/签订日期/类型） 是
ZSPContractDetail 合同详情（商品/数量/单价/已提货/应提货/提单号） 否，未加入 AutoMigrate
ZSPFreightCharges 货代费用 否，未加入 AutoMigrate
ZSPMiscCharges 杂费 否，未加入 AutoMigrate
ZSPServiceFees 服务费 否，未加入 AutoMigrate
ZSPCostBreakdown 成本构成（关联货代/杂费/服务费） 否，未加入 AutoMigrate
ZSPProfitRecord 利润记录（关联成本构成） 否，未加入 AutoMigrate

2.3 后端完全缺失的模块（前端有 API 定义但后端无路由/模型）

前端 API 文件 调用路径前缀 后端状态
applyDelivery.ts /apply-delivery/* 无路由、无模型、无 handler
deliveryDetails.ts /delivery-details/* 无路由、无模型、无 handler
inventory.ts /inventory/* 无路由、无模型、无 handler
ownershipTrAns1fer.ts /ownership-trAns1fer/* 无路由、无模型、无 handler（且前端大部分 API 函数被注释）
company.ts /company/* 无路由、无模型、无 handler
结算管理 未知 无前端 API 文件、无后端
发票管理 未知 无前端 API 文件、无后端
采购管理 未知 无前端 API 文件、无后端
查询报表 复用 zspContract API 无独立后端

三、已发现的技术问题

3.1 AutoMigrate 不完整

pkg/database/migrate.go 只注册了 5 个模型，缺少 ZSPContractDetail 及所有财务相关模型（共 6 个），后端启动后这些表不会自动创建。

3.2 双套合同模型

后端同时存在 Contract（旧版）和 ZSPContractFile（新版）两套合同模型：

  • Contract 字段：Name/ContractType/ContractCode/BuyParty/SellParty/Count/UnitPrice/BLNumber 等，且 Count、UnitPrice 均为 string 类型。
  • ZSPContractFile + ZSPContractDetail：更完整，有数值类型的 TotalQuantity/UnitPrice/DeliveredQty/PendingQty。

前端 AddContract.vue 调用旧版 contract/upload；中尚鹏合同管理、合同执行等调用新版 zsp-contract/*。

3.3 Auth 中间件已注释

route.go 中 authorized.Use(authMiddleware) 被注释，所有接口无鉴权保护。

3.4 API 基址不统一

  • contract.ts：用 baseUrlApi() 写死 http://127.0.0.1:8080/api/，不走 Vite 代理。
  • 其余 API：用 @/utils/http，走 Vite 代理 /api -> 127.0.0.1:8080。

3.5 财务模型字段与需求不匹配

需求中"货代费用"要求字段为：提单号、上游合同编号、费用项目、金额、付款日期、货代/物流公司名。

当前后端 ZSPFreightCharges 模型仅有：Name、Amount、Currency、Date、Remark，缺少提单号、上游合同编号、货代公司名等关键业务字段。

四、需要你确认的问题

以下问题分为 业务理解 和 技术决策 两类，请逐条回答或标注"暂不考虑"。

A. 合同管理

A1. 旧版 Contract 模型和新版 ZSPContractFile + ZSPContractDetail 模型都在使用中。你的计划是：

  • (a) 废弃旧版，把"新增合同"页面也改用新版模型？
  • (b) 两套并存，各管各的？
  • (c) 其他方案？

Ans1: b新增合同部分要注意区分中尚鹏合同管理和新增合同是两套并行的合同管理，在业务需求端新增合同其实应该是合同管理或者叫做业务合同管理，建议改掉，然后中尚鹏合同管理只用负责公司相关的合同就行

A2. 旧版 Contract 的 Count（数量）和 UnitPrice（单价）字段是 string 类型，无法直接参与数值计算。如果保留旧版，是否需要改成数值类型？ Ans1: 我害怕有浮点计算风险，如果你能解决这个问题也未尝不可。

A3. Talk 中提到"合同管理里空一个 Excel 表格，手动录入合同数据（数量、单价、已提货数量等），系统自动计算未提货数量"。这个"Excel 表格"是否就是当前 ZSPContractDetail（合同详情）表的逐行录入形式？还是甲方期望一个真正可编辑的类 Excel 界面（如可拖拽选区、复制粘贴公式等 SpreadSheet 组件）？ Ans1: 甲方可能希望的是一个表的逐行录入形式类似csv格式的前端显示，但是有并发修改的需求

A4. 甲方说"公式后续会给出"。目前后端 ZSPContractDetail.BeforeCreate 只做了一个公式：PendingQty = TotalQuantity - DeliveredQty。除此之外是否还有其他公式需要实现？如果甲方还没给，是否先只保留这一个？ Ans1: 甲方还没给

A5. 中尚鹏合同管理的搜索：甲方说"我们会备注好文件名包含商品、公司名、合同编号"。当前后端 ZSPContractFile 模型已有独立的 ContractNumber、CompanyName、Commodity 字段。那么搜索逻辑是：

  • (a) 上传时手动填写这三个字段，搜索时按字段查？（当前实现）
  • (b) 从文件名自动解析出这三个字段？如果是，文件名格式是什么？ Ans1: (a)方法

B. 提货管理

B1. 提货管理（我要提货、提货明细、库存、货权转移）的后端完全没有实现。前端已定义了 API 类型和调用路径。开发顺序是否按 我要提货 → 提货明细 → 库存 → 货权转移 依次实现？ Ans1: 是的

B2. "我要提货"需求中说"根据我们提供的提货单模板创建"。模板是否已提供？如果提供了，请告诉我文件位置；如果没有，是否按当前前端 ApplyDelivery.vue 的字段结构先做？ Ans1: 目前还没提供，这个部分先不做

B3. 库存计算公式：库存 = 入库重 − 出库数量 − 货权转移数量。这个计算在后端做（API 返回已算好的库存值），还是前端拿到三个数字自己算？ Ans1: 这个后端来算吧

B4. 货权转移前端 ownershipTrAns1fer.ts 中大部分 API 函数被注释了（create、print、export、delete、upload），只保留了 getOwnershipList。这些注释掉的功能是否都要实现？ Ans1: 可能是Ai生成的内容，可信度不高，你按照自己的想法来

B5. 需求中"货权转移"要求字段包含库方（warehouse）。这里的"库方"是否就是"仓库管理"中已维护的仓库列表？即两者共用同一套仓库数据？ Ans1: 公司是一个对接上游公司和下游公司的业务，从上游公司拿货给下游公司这样的，库方一个指的是仓库管理中的仓库列表

C. 财务管理

C1. 当前后端的 ZSPFreightCharges（货代费用）模型字段很少（仅 name/amount/currency/date/remark），需求要求的"提单号、上游合同编号、费用项目、金额、付款日期、货代/物流公司名"基本都缺。是否需要重新设计这个模型的字段？ Ans1: 是的，重新设计

C2. Talk 中提到"利润表中的成本栏 = 货代费用 + 杂费 + 服务费，且点击成本金额能显示构成明细（如货代费 20 万、杂费 12 万）"。当前后端已有 ZSPCostBreakdown 模型关联了三种费用。这个设计方向是否正确？是否需要调整？ Ans1: 是的，重新设计

C3. 利润明细需要"关联其他表格中数据"。Talk 中提到的"其他表格"，你认为具体是指哪些？我目前的理解是：

  • 收入 ← 来自合同金额（ZSPContractDetail.TotalQuantity × UnitPrice）
  • 成本 ← 来自货代费用 + 杂费 + 服务费（ZSPCostBreakdown）
  • 利润 = 收入 − 成本
  • 这个理解对吗？还是收入来源不同（比如来自结算单）？ Ans1: 应该是对的

C4. 结算管理、发票管理、对账单：前端目前没有独立的 API 文件，后端也没有实现。这三个模块的优先级如何？是否排在合同和提货之后？ Ans1: 需要你来实现

C5. 发票管理中"上游/下游/货代杂费发票"，这三类发票是否共用一个数据表（通过 type 字段区分），还是需要独立三张表？ Ans1: 独立三张表

D. 查询 + 报表中心

D1. 合同执行情况中"差款"的计算规则是什么？是 合同金额 − 已结算金额？还是 合同金额 − 银行流水中已收金额？数据分别来自哪些表？ Ans1: 先不做这一部分

D2. "待开发票情况"的计算规则是什么？是 已结算金额 − 已开票金额？ Ans1: 是

D3. "上传银行流水"：上传后是否需要解析 Excel 内容并自动匹配到合同？还是仅当附件保存，人工查看？如果要解析，Excel 的列格式是什么？ Ans1: 仅当附件保存，人工查看

D4. "其它明细表"下有三个子表：已开票明细表、货代杂费明细表、历史清关成本明细表。当前前端只有一个 OtherDetails.vue。是在一个页面用 Tab 切换三个子表，还是拆成三个独立页面/路由？ Ans1: 用 Tab 切换三个子表

D5. "营业明细表"的具体内容和字段是什么？是按年/月/合同维度汇总的报表？还是某个甲方提供的 Excel 模板？ Ans1: 先不做这一部分

E. 采购管理

E1. 采购管理的四个子模块（采购报单、采购运踪明细、国外供应商、采购预算）目前前端有路由和页面，但前端 API 只有 PurchaseOrder.vue 有部分内容，后端完全没有。这些模块的开发优先级是否排在合同/提货/财务之后？ Ans1: 这是之前用AI生成的前端内容，可信度并不高

E2. 采购预算需求说"已有单独的预算测算系统"。对接方式你倾向哪种：链接跳转、iframe 嵌入、还是接口拉数据？还是说现阶段完全不做？ Ans1: 完全不做

F. 权限管理

F1. 需求中"权限管理 1、2"没有展开。当前系统是否只需要最基础的角色 + 菜单权限（如管理员看全部、普通用户看部分菜单）？还是需要更复杂的数据权限（如只能看自己创建的合同）或审批流？ Ans1: 只需要最基础的

F2. 当前后端 Auth 中间件已注释。是否需要在这一阶段启用 JWT 鉴权？还是等功能都做完再加？ Ans1: 等所有的内容做完了再加吧

G. 整体开发计划

G1. 你期望的模块开发顺序是什么？我建议按依赖关系排序：

  1. 合同管理（基础数据，其他模块依赖合同编号/提单号）
  2. 提货管理（依赖合同）
  3. 库存信息（依赖入库/出库/货权转移）
  4. 财务管理（依赖合同、提货数据）
  5. 查询报表（依赖以上所有数据）
  6. 采购管理（相对独立）
  7. 权限管理（最后统一加）

这个顺序你是否同意？或者有其他优先级安排？ Ans1: 同意

G2. 甲方 Talk 中说"主菜单后面不能再改，二级菜单每次做之前再沟通一次"。是否意味着我每做完一个二级菜单就要等你确认后再做下一个？ Ans1: 不需要

G3. 前端页面大部分已经有了 UI 和模拟逻辑。后续开发的重心是否主要在后端 API 实现 + 前后端联调，前端 UI 改动较少？ Ans1: 前端UI的改动，现在我对新增合同这个菜单并不满意，建议修改为业务合同管理，然后前端UI做的和中尚鹏合同管理一样这些

五、Ans 修改完成备注

以下为根据你的回复已完成的修改及代码位置说明。

Solve A1（两套合同并存 + 业务合同管理命名）

  • 完成：菜单「新增合同」改为「业务合同管理」；业务合同管理仅负责业务合同，中尚鹏合同管理负责公司相关合同。
  • 参考位置：frontend/pure-admin-thin/src/router/modules/contract.ts 中 meta.title 改为「业务合同管理」；frontend/pure-admin-thin/src/views/system/contract/AddContract.vue 页面标题与描述改为「业务合同管理」「管理业务合同信息、上传合同相关文件、录入合同数据」。

Solve A2（Contract 数量/单价改为数值并避免浮点风险）

  • 完成：旧版 Contract 的 Count、UnitPrice 改为 decimal(16,4) 数值类型，后端解析表单字符串为 float64。
  • 参考位置：backend/go-backend/internal/model/contract.go 中 Count、UnitPrice 定义为 float64 且 gorm:"type:decimal(16,4)"；backend/go-backend/internal/handler/contract_handler.go 中 strconv.ParseFloat 解析并赋值。

Solve A3、A4、A5

  • 当前保留：合同详情逐行录入形式（ZSPContractDetail）；公式仅保留 PendingQty = TotalQuantity - DeliveredQty；搜索按手动填写的合同编号/公司名/商品字段查询。无新增代码改动，逻辑维持现状。

Solve C1（货代费用模型重新设计）

  • 完成：ZSPFreightCharges 增加提单号、上游合同编号、费用项目、金额、付款日期、货代/物流公司名等字段。
  • 参考位置：backend/go-backend/internal/model/zsp_freight_charges.go 中 ZSPFreightCharges 结构体；internal/dto/zsp_finances.go 中 Create/Update 请求体；internal/service/zsp_finances_service.go、internal/repository/zsp_finances.go、internal/handler/zsp_finances_handler.go 对应 CRUD；前端 frontend/pure-admin-thin/src/api/zspFinances.ts 类型与接口；frontend/pure-admin-thin/src/views/system/finance/FreightCharges.vue 表格与表单字段。

Solve C2（成本构成重新设计）

  • 完成：ZSPCostBreakdown 改为按金额汇总设计，包含 FreightChargeTotal、MiscChargeTotal、ServiceFeeTotal 及 TotalCost，不再用外键关联单条费用记录。
  • 参考位置：backend/go-backend/internal/model/zsp_freight_charges.go 中 ZSPCostBreakdown；internal/dto/zsp_finances.go 中成本构成 DTO；service/repository 中成本构成的计算与更新逻辑；前端 zspFinances.ts 中 ZSPCostBreakdown 及相关 API。

Solve C3

  • 理解已确认：收入来自合同金额，成本=货代+杂费+服务费，利润=收入−成本。当前后端利润记录与成本构成已按此逻辑实现，无需额外改动。

Solve C4（结算/发票/对账单需实现）

  • 完成：后端新增结算、对账单及三张发票表模型并加入迁移；前端新增对应 API 文件。后端路由与完整 CRUD 待后续补全。
  • 参考位置：backend/go-backend/internal/model/zsp_invoice.go（上游/下游/货代杂费发票）；backend/go-backend/internal/model/zsp_settlement.go（结算、对账单）；backend/go-backend/pkg/database/migrate.go 中 AutoMigrate 新增上述模型；frontend/pure-admin-thin/src/api/settlement.ts、invoice.ts、reconciliation.ts。

Solve C5（发票独立三张表）

  • 完成：已建 ZSPUpstreamInvoice、ZSPDownstreamInvoice、ZSPFreightMiscInvoice 三张独立表及对应模型与迁移。
  • 参考位置：backend/go-backend/internal/model/zsp_invoice.go。

Solve 其他（杂费/服务费字段、API 基址、AutoMigrate）

  • 杂费：ZSPMiscCharges 增加提单号、合同编号、费用项目、付款日期、公司名等，见 zsp_freight_charges.go、DTO、MiscCharges.vue。
  • 服务费：ZSPServiceFees 增加提单号、合同编号，见 zsp_freight_charges.go、DTO、ServiceFees.vue。
  • API 基址统一：业务合同上传改用 @/utils/http，走 Vite 代理。参考 frontend/pure-admin-thin/src/api/contract.ts（submitContract、batchUploadContracts 使用 http.request）。
  • AutoMigrate 补全：ZSPContractDetail、所有财务相关模型、三张发票表、结算、对账单已加入。参考 backend/go-backend/pkg/database/migrate.go。

以上为当前已完成的修改与对应代码位置；提货/库存/货权转移、结算与发票的后端路由及利润明细页与新成本结构的联调等，按开发计划后续迭代。

Reference in New Issue View Git Blame Copy Permalink