# 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/)

```bash
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/)

```bash
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

```bash
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](https://github.com/pure-admin/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)