zsp-project/docs/dev/当前程序不足分析.md

中尚鹏管理系统 - 当前程序不足分析

本文档基于对现有前端代码与《项目开发要求文档》的对照，整理当前实现的不足与待确认点。

更新说明：以下问题已在后续迭代中修复：

• JWT 认证中间件已启用（backend/internal/server/route.go），所有业务 API 需携带 Authorization: Bearer <token> 头
• reset_database 已设为 false（配置文件和部署说明均已更新），重启不再清空数据库
• Handler 层测试已编写（backend/test/），覆盖用户注册/登录/查询、合同列表/查询/文件夹管理
• Delivery Handler 已重构为 Handler → Service → Repository 三层架构，不再直接使用 *gorm.DB

---

一、与需求文档的菜单对照

需求文档模块	需求三级菜单概要	当前前端情况
合同管理	新增合同 / 中尚鹏合同管理 / 公司信息	路由与页面均有
提货管理	我要提货 / 提货明细 / 库存 / 货权转移 / 其它	路由与页面均有
财务管理	结算 / 发票 / 利润明细 / 货代杂费+其它 / 对账单	路由与页面均有
查询+报表中心	合同执行 / 营业明细表 / 其它明细表 / 商品基础资料 / 其它	路由与页面均有
采购管理	采购报单 / 采购运踪 / 国外供应商 / 采购预算	路由与页面均有
权限管理	1 / 2（需求未展开）	现有 permission 页面/按钮

---

二、功能与业务层面的不足

2.1 合同管理

• 新增合同

  • 已实现：单合同录入、批量上传、提单号最多 15 个校验。
  • 不足/待确认：需求中“录入合同内容中相关数据的表格（会涉及简单的公式，我们会给出）”是否已按贵方提供的公式在表格中实现？若未提供公式，当前表格是否有明确占位或说明？

• 中尚鹏合同管理

  • 已实现：文件夹归类、上传、按合同编号/公司名/商品/提单号等搜索。
  • 不足：需求要求“通过文件名包含商品、公司名、合同编号”进行搜索。当前是否对上传文件的文件名做解析并写入可搜索字段？若未解析文件名，则与“通过三要素搜索对应合同”的预期存在差距。

• 公司信息管理

  • 已存在页面，需确认：是否仅做“公司相关文件存储（如营业执照、开票信息）”即可，有无额外字段或审批流程要求。

2.2 提货管理

• 我要提货

  • 已实现：新增/变更/取消提货委托，以及模板下载等。
  • 不足/待确认：提货单是否已完全按贵方提供的提货单模板（含车牌号、提单号、司机信息、数量、商品品类等）生成与展示？模板若后续变更，是否有统一维护方式？

• 提货明细

  • 需求：新增出库单、查看出库明细、收货确认单，且“录入数据的表格（后期我们给模板）”。
  • 不足：当前是否已接入“后期给的模板”？若未接入，表格结构与字段是否已与业务方对齐？

• 库存信息

  • 需求公式：入库表格中数量 − 新增出库单中数量 − 货权转移数量 = 库存数量。
  • 不足：该公式是否在前端展示与后端计算中都已严格按此逻辑实现？库存明细是否按“仓库+商品+货主”等维度正确汇总？

• 货权转移

  • 需求字段：货转日期、提单号、数量、商品、库方、货权出让方、货权接收方等。
  • 不足：当前“货权转移”相关表格与表单字段是否已全部包含上述字段，且与扫描件录入需求一致？

2.3 财务管理

• 结算管理

  • 需求：新增结算单（导出下游合同结算单）、按单号查询、上传已结算单备份。
  • 不足：导出下游合同结算单的数据来源与模板是否已定稿？上传备份后的检索与展示是否满足“按单号查询”的完整流程？

• 发票管理

  • 需求：上游发票、下游发票、货代杂费发票的上传及“对应表格录入发票对应信息”。
  • 不足：发票表格的字段是否与后续“待开发票情况”“已开票明细表”等统计完全一致，便于关联与报表使用？

• 利润明细

  • 需求：“根据我们提供的 excel 表格创建一个表格（需要关联其他表格中数据 + 设置好栏目以及函数，后续自行手动录入）”。
  • 不足：当前利润明细页是否已关联合同/结算/发票/货代杂费等其它表数据？栏目与公式是否已按贵方提供的 Excel 定稿？若 Excel 尚未提供，当前页面是占位还是已有临时结构？

• 货代费用 + 其他杂费

  • 需求字段：提单号、上游合同编号、费用项目、金额、付款日期、货代/物流公司名。
  • 不足：当前表单与列表是否已完全覆盖上述字段，并与“利润明细”“历史清关成本”等可关联？

• 对账单

  • 需求文档中“5.对账单”无具体内容描述。
  • 不足：对账单的业务范围、字段、与结算/发票的关系是否已有口头或补充文档说明？当前页面若存在，是否仅为占位？

2.4 查询 + 报表中心

• 查询上下游客户合同执行情况

  • 需求：按合同编号/公司名/商品/提单号/日期查询，且可查询到：
    • 该合同剩余未提数量（与“新增合同”表格关联）；
    • 差款及待开发票情况（与“发票管理”关联）；
    • 支持上传 Excel 表格（银行流水）。
  • 不足：
    • 当前“合同执行”页的付款状态为前端写死的 "unpaid"，并未与真实结算/发票数据关联，无法体现真实“差款”与“待开发票”。
    • “剩余未提数量”是否已与“新增合同”及出库/货权转移数据打通并一致？
    • “上传银行流水”功能是否已实现？若已实现，银行流水与合同、收付款的关联规则是否明确？

• 营业明细表

  • 需求：① 2025 年中尚鹏业务明细表。
  • 不足：当前“营业明细表”路由对应的是 BusinessDetails.vue，从代码看更偏向“合同文件/营业相关合同”的列表与搜索，与需求中的“2025 年业务明细表”可能不是同一张表。需确认：营业明细表 究竟是“按年的业务汇总表”，还是“合同维度明细表”，以便与菜单命名和实现对齐。

• 其它明细表

  • 需求：① 已开票明细表 ② 货代杂费明细表 ③ 历史清关成本明细表。
  • 不足：当前“其它明细表”为单一列表（OtherDetails），未在菜单或页面内拆分为上述三个子表。三个表的字段与数据来源是否已定义？是否需要在同一页用 Tab 区分，还是独立三个页面？

• 商品基础资料

  • 需求：燕麦/大麦/豌豆/亚麻籽/葵粕/菜籽粕等，可批量上传扫描件或文档。
  • 不足：当前是否已按“商品类型”或“品类”做分类归档与展示？批量上传后的检索方式是否明确？

2.5 采购管理

• 采购报单、采购运踪明细、国外供应商

  • 不足：需求为“批量上传扫描件 + 录入扫描件内容的表格”或“根据所提供的 excel 在系统中创建表格”。当前各页是否已接入贵方提供的模板/Excel 结构？若未提供，当前表格是否为暂定结构？

• 采购预算

  • 需求：“已有单独的预算测算系统，最后按该预算系统功能等添加到我们系统中（这个最后有时间慢慢弄）”。
  • 不足：当前采购预算页是占位还是已有部分对接？与“单独预算系统”的对接方式（单点登录、接口、嵌入等）是否有初步方案？

2.6 权限管理

• 需求文档仅写“1”“2”，无具体说明。
• 不足：当前为通用“页面权限 + 按钮权限”结构。贵方是否需要角色名、数据范围（如按公司/部门）、审批流等具体需求？若有，需补充说明以便后续设计。

---

三、技术与实现层面的不足

3.1 API 与后端

• 双套 API 基址

  • 合同模块（如 contract/upload、contract/batch-upload）通过 baseUrlApi 直接写死 http://127.0.0.1:8080/api/。
  • 其余模块（如中尚鹏合同、财务、提货等）通过 @/utils/http 走相对路径（通常为 /api），在开发环境会经 Vite 代理到 127.0.0.1:8080。
  • 不足：基址不统一，不利于环境切换（开发/测试/生产）与后续维护；若后端实际未部署在 8080 或路径不同，合同相关请求易出错。

• 后端存在性

  • 当前仓库内未见后端工程目录，仅前端调用 8080 接口。
  • 不足：需确认后端是否独立仓库或独立服务、接口文档是否齐全、现有前端调用的接口是否已全部实现并联调通过。

3.2 功能未完成或占位

• 合同执行情况

  • 导出功能为“导出功能开发中”提示，未实现真实导出。

• 差款与待开发票

  • 未与结算、发票、银行流水等数据打通，无法展示真实“差款”与“待开发票情况”。

• 银行流水

  • 需求提到“上传 excel 表格（银行流水）”，当前代码中未检索到“银行流水”相关实现，需确认是否未做或位于其他模块。

3.3 数据关联与一致性

• 需求多处强调“关联其他表格”“设置好栏目以及函数”，例如：
  • 利润明细 关联 合同/结算/发票/货代等；
  • 合同执行 关联 新增合同、发票管理；
  • 库存 = 入库 − 出库 − 货权转移。
• 不足：当前实现中，这些跨模块的数据关联与计算是否已在后端或前端全部落地并校验一致，需要逐项对照需求做确认与测试。

---

四、小结

• 菜单与路由：与需求文档的一、二、三级菜单基本对应，但“营业明细表”与“其它明细表”的页面职责与需求描述需要对齐。
• 业务逻辑：合同执行中的“差款”“待开发票”“剩余未提数量”“银行流水”未按需求打通；利润明细、库存公式、对账单、采购/提货模板等依赖贵方提供的表格或公式，需确认是否已提供并已实现。
• 技术：API 基址不统一、后端与接口实现情况不透明、部分导出与上传功能仍为占位或未实现。

建议在进入下一阶段开发前，先根据下文《需求确认问题清单》与业务方确认，再制定实现与联调计划。

---

五、需求确认问题清单（请产品/业务方确认）

以下问题基于《项目开发要求文档》整理，便于明确开发范围与优先级，请逐项确认或补充。

合同管理

1. 新增合同：需求中提到“会涉及简单的公式，我们会给出”。公式是否已提供？若已提供，请说明存放位置或文档名；若未提供，当前表格中的计算逻辑是否按临时规则处理即可？
2. 中尚鹏合同管理：搜索是否必须基于上传文件的文件名解析出“商品、公司名、合同编号”？
   • 若是，文件名命名规范是什么（例如：商品_公司名_合同编号.pdf）？是否需要在系统中做“文件名解析并写入可搜索字段”的功能？
3. 公司信息管理：除“上传扫描件 + 文件夹归类”外，是否需要维护公司主数据（如公司名、税号、开户行等）？还是仅文件存储即可？

提货管理

4. 我要提货：提货单模板（含车牌号、提单号、司机信息、数量、商品品类等）是否已定稿？若已提供，请说明文件位置；若会变更，变更后由谁在系统中更新？
5. 提货明细：需求写“录入数据的表格（后期我们给模板）”。模板是否已提供？若未提供，当前表格字段是否可作为正式版使用？
6. 库存信息：公式“入库 − 出库 − 货权转移 = 库存”是否必须按**仓库 + 商品 + 货主（及合同）**等维度精确到最细粒度？是否有“只按仓库汇总”等简化展示需求？
7. 货权转移：除需求列出的字段外，是否还有必填或必展示字段？已生效的货权转移函“上传”与“新增货权转移函”是两条独立流程还是需要关联？

财务管理

8. 结算管理：“导出下游合同结算单”的数据来源是哪些表？是否有固定 Excel 模板？若有，请提供模板或字段说明。
9. 发票管理：上游/下游/货代杂费发票的“对应表格”字段是否已定稿？是否需要与“已开票明细表”“待开发票情况”完全一致以便关联？
10. 利润明细：需求写“根据我们提供的 excel 表格创建……关联其他表格中数据 + 设置好栏目以及函数”。
    • Excel 模板是否已提供？若已提供，请说明位置。
    • “其他表格”具体指哪些（合同、结算、发票、货代费用、清关成本等）？关联规则（按合同号、提单号、日期等）是什么？
11. 货代费用 + 其他杂费：与“利润明细”“历史清关成本明细表”的关联方式是否已明确（例如通过提单号、合同编号、日期）？
12. 对账单：对账单的业务含义、使用场景、字段与数据来源是否已有说明？若有补充文档或样例，请提供或简述。

查询 + 报表中心

13. 合同执行情况：
    • “差款”的定义是什么（例如：合同金额 − 已收款项）？数据来源是结算单、银行流水还是其它？
    • “待开发票情况”是指：已结算但未开票的金额/列表？数据来源是否与发票管理表一致？
    • “上传银行流水”的 Excel 格式是否已定？上传后是否需要解析并自动匹配到合同/收付款，还是仅作附件存档？
14. 营业明细表：“2025 年中尚鹏业务明细表”与当前菜单中的“营业明细表”是否同一张表？若否，请说明需求中的这张表应展示哪些维度（按合同、按客户、按商品、按月份等）。
15. 其它明细表：已开票明细表、货代杂费明细表、历史清关成本明细表：
    • 三张表是独立页面还是同一页面下三个 Tab/子表？
    • 每张表的字段与数据来源是否已定义？历史清关成本的数据从哪里录入或导入？

采购管理

16. 采购报单 / 采购运踪明细 / 国外供应商：各模块的“我们提供的 excel”或“扫描件内容表格”是否已提供？若未提供，是否同意以当前系统中的表格结构为初版，后续再按模板调整？
17. 采购预算：与“单独的预算测算系统”的对接方式是否有初步方案（例如：链接跳转、单点登录、接口拉取数据、iframe 嵌入等）？优先级是否确认为“最后有时间再弄”？

权限管理

18. 需求中“权限管理 1、2”具体指什么？是否需要角色管理、数据权限（按公司/部门）、审批流、操作日志等？若有，请列出清单或提供简单说明。

其它

19. 是否有未在《项目开发要求文档》中体现的隐藏需求或口头约定（例如：某表需要审批后才能生效、某报表需要定时发送邮件等）？
20. 后端服务与接口：当前后端是否已有独立项目或部署地址？前端调用的接口是否有完整文档（如 Swagger/Word）？若部分接口尚未实现，请标明模块或接口路径，便于排期。

---

文档生成后请根据实际业务与最新需求增删改，本分析不修改任何代码。