zsp-project/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

企业供应链合同管理系统 (中尚鹏 / ZSP). Monorepo with a Vue 3 SPA frontend and Go REST API backend, managing contracts, deliveries, inventory, finance, purchasing, and reporting for a supply chain business.

目录结构

├── frontend/          # Vue 3 SPA 前端
├── backend/           # Go + Gin REST API 后端
├── docs/              # 项目文档
│   ├── api/           # API 文档
│   ├── deploy/        # 部署文档
│   ├── dev/           # 开发文档与需求分析
│   └── Git提交规范.md # Git 提交规范
├── scripts/           # 部署脚本
└── CLAUDE.md          # Claude Code 配置文件

5 大业务模块（21 个子菜单）

1. 合同管理（3 个子菜单）：业务合同管理、中尚鹏合同管理、公司信息管理
2. 提货管理（5 个子菜单）：我要提货、提货明细、库存信息、货权转移、其他出库
3. 财务管理（7 个子菜单）：货代费用、杂费管理、服务费管理、发票管理、结算管理、对账单、利润明细
4. 采购管理（4 个子菜单）：采购报单、采购运踪明细、国外供应商、采购预算
5. 查询&报表中心（5 个子菜单）：合同执行情况、营业明细表、其他明细表、商品基础资料、其他报表

Commands

Frontend (frontend/)

pnpm dev          # Start Vite dev server (port 5173, proxies /api to 127.0.0.1:8080)
pnpm build        # Production build to frontend/dist/
pnpm typecheck    # tsc --noEmit + vue-tsc --noEmit
pnpm lint:eslint  # ESLint check
pnpm lint:prettier # Prettier check
pnpm lint         # Run all linters

Backend (backend/)

go run cmd/api/main.go         # Start server (port 8080)
air -c .air.toml               # Start with hot-reload
go test ./...                  # Run all tests
go test ./test/                # Run all handler tests (user + contract + delivery)
go build -o ./tmp/main ./cmd/api/main.go  # Build binary

Docker

docker-compose -f docker-compose.dev.yml up --build   # Dev: backend + MySQL + Air
docker-compose --env-file .env.prod up -d             # Production

Architecture

Frontend (Vue 3 + TypeScript + Vite + Pinia + Element Plus)

Based on vue-pure-admin Lite Edition (non-i18n). Key directories:

• src/api/ — Axios-based API client modules, one file per domain (contract.ts, delivery.ts, finance.ts, etc.)
• src/assets/ — Static assets (icons, images)
• src/components/ — Reusable components (ReAuth, ReDialog, ReIcon, etc.)
• src/config/ — App configuration
• src/directives/ — Custom Vue directives (auth, copy, ripple, etc.)
• src/layout/ — App shell with 3 layout modes (vertical/horizontal/mix)
• src/router/modules/ — Route modules, one per feature domain, loaded dynamically via async routes
• src/store/modules/ — Pinia stores (user, app, permission, settings, epTheme, multiTags)
• src/style/ — Global styles (reset, index, sidebar, tailwind)
• src/utils/ — Utility functions (HTTP client, auth, tree operations, etc.)
• src/views/ — Page components by feature: login/, system/contract/, delivery/, finance/, purchase/, query-report/

Backend (Go + Gin + GORM + MySQL 8.0)

Clean layered architecture:

• internal/handler/ — HTTP request handling, parameter parsing, response writing
• internal/service/ — Business logic orchestration
• internal/repository/ — Data access via GORM queries
• internal/model/ — GORM model structs with table tags (27 tables via AutoMigrate)
• internal/dto/ — Request/response DTOs
• internal/middleware/ — JWT auth middleware (enabled for all routes except /auth/* and static files)
• internal/server/route.go — All API route definitions (single source of truth)

API routes are under /api/ prefix with per-domain route groups. JWT middleware is applied to all routes except /auth/register, /auth/login, and static file routes.

API Route Groups

Group	Prefix	Handler	Description
Auth	/api/auth/register, /api/auth/login	UserHandler	Public: user registration/login
Users	/api/users/:id	UserHandler	Protected: user info
Contract	/api/contract	ContractHandler	Business contracts CRUD + folders + batches
ZSP Contract	/api/zsp-contract	ZSPContractHandler	CRUD + details + Excel import/export
Company	/api/company	CompanyHandler	Company info management
Delivery	/api/apply-delivery	DeliveryHandler	Delivery applications
Outbound	/api/delivery-details	DeliveryHandler	Outbound orders
Inventory	/api/inventory	DeliveryHandler	Warehouses/inbound/summary
Ownership	/api/ownership-transfer	DeliveryHandler	Ownership transfer CRUD
Finance	/api/zsp-finances	ZSPFinancesHandler	Freight/misc/service fees, costs, profits

Key patterns

• Backend handler → service → repository — Each layer calls the next. Handlers are thin; business logic lives in services. Tests use mocked service interfaces.
• DTOs for API contracts — Request/response types in internal/dto/, not raw models.
• GORM AutoMigrate — 27 models auto-migrated on startup; schema changes are additive.
• Frontend API modules — Each src/api/*.ts file exports typed functions that return Axios promises with the base response wrapper (Result<T>).
• HTTP interceptors — Auto-attach JWT Authorization header, handle token refresh, NProgress loading bar.
• Async routes — Routes are fetched dynamically post-login; each router module exports an array of route configs.
• 3 layout modes — Adaptive vertical/horizontal/mix layouts with multi-tab + keep-alive caching.
• No i18n — All UI text is hardcoded in Chinese.

Testing

• Backend tests live in backend/test/ and use mocked service interfaces with httptest.NewRecorder().
• Currently 24 tests covering user, contract, and delivery handlers.
• Frontend testing infrastructure is not yet configured.
• Run tests: cd backend && go test ./test/ -v

Known Issues / Technical Debt

1. Dual contract models — Legacy Contract model coexists with new ZSPContractFile/ZSPContractDetail models.
2. API URL inconsistency — Some routes use /list, /create, /update/:id suffixes while others use direct REST patterns.
3. Test coverage — User, contract, and delivery handler tests exist (24 tests); finance and ZSP contract handlers still lack tests.
4. Delivery handler — Refactored to use service/repository layer (was directly using *gorm.DB). The InventorySummary method still accesses DB directly through svc.DB() for complex aggregate queries.

Git Conventions

• Commit format: Conventional Commits with Chinese descriptions. Types: feat, fix, docs, style, refactor, perf, test, chore. Scopes: contract, finance, delivery, inventory, invoice, api, frontend, backend.
• Branch strategy: main → production, dev → development, feature/xxx → features, fix/xxx → fixes.
• Husky hooks: commit-msg (commitlint) + pre-commit (lint-staged).

Docs

Project documentation is in docs/:

• docs/api/ — API documentation and frontend route docs
• docs/deploy/ — Nginx configuration, Docker deployment, environment requirements
• docs/dev/ — Requirements analysis, known issues, finance module pending questions
• docs/Git提交规范.md — Git commit standards (Conventional Commits)