Project Conventions 是一套面向全栈开发团…

# Next.js + TypeScript 跨境电商后台 API 规范

一、技术前提

• App Router（Next.js 13+）+ Route Handlers
• 仓库分层：页面层与服务层分离，接口统一走 /app/api/**

二、API 命名规范

通用原则

• 全小写，多词用连字符：/order-items、/sku-tags
• RESTful 动词语义：GET 查询 / POST 创建 / PATCH 局部更新 / PUT 全量更新 / DELETE 删除
• 资源复数、嵌套不超过两层：/orders/{id}/items
• 操作型动作用动词子路径：POST /orders/{id}/cancel、POST /orders/{id}/ship

商品模块（约15个）

• GET/POST /products — 列表 / 创建
• GET/PATCH/DELETE /products/{id}
• PATCH /products/{id}/status — 上架/下架
• POST /products/{id}/duplicate — 复制
• GET/POST /products/{id}/skus — 多规格管理
• PATCH /products/{id}/skus/{skuId} — 规格价格/库存
• GET/POST /products/{id}/images — 图片
• GET/POST /categories、PATCH/DELETE /categories/{id}
• POST /products/batch-update — 批量操作
• GET /products/{id}/i18n、PATCH /products/{id}/i18n — 多语言文案

订单模块（约15个）

• GET/POST /orders — 列表 / 手工建单
• GET/PATCH /orders/{id}
• POST /orders/{id}/confirm|ship|deliver|cancel|close
• GET /orders/{id}/logs — 操作日志
• POST /orders/{id}/refunds、GET /refunds — 售后
• GET /orders/{id}/shipments、POST /shipments/{id}/track — 物流
• POST /orders/batch-export、POST /orders/batch-print — 批量发货单
• GET /orders/stats — 统计看板

三、目录结构

```

src/

├── app/

│ ├── (dashboard)/

│ │ ├── products/

│ │ └── orders/

│ └── api/

│ ├── products/

│ │ ├── [id]/

│ │ │ ├── skus/

│ │ │ ├── status/

│ │ │ └── i18n/

│ │ └── batch-update/

│ └── orders/

│ ├── [id]/

│ │ ├── cancel/

│ │ └── shipments/

│ └── stats/

├── features/

│ ├── prod