API 参考

本文档列出 HmwCard 后端所有 API 接口，包括公开接口和管理员接口。

# 基础信息

# 认证

# 管理员登录

POST /api/auth/login

请求体：

{
  "username": "admin",
  "password": "your_password"
}

成功响应：

{
  "success": true,
  "data": {
    "id": 1,
    "username": "admin",
    "mustChangePassword": false
  }
}

登录成功后，服务端会设置 HttpOnly Cookie，后续请求自动携带。

# 获取当前管理员信息

GET /api/auth/profile

成功响应：

{
  "success": true,
  "data": {
    "id": 1,
    "username": "admin",
    "createdAt": "2026-01-01T00:00:00.000Z"
  }
}

# 修改密码

POST /api/auth/change-password

请求体：

{
  "currentPassword": "old_password",
  "newPassword": "new_secure_password"
}

# 强制修改密码

首次登录时如果 mustChangePassword 为 true，需调用此接口设置新密码：

POST /api/auth/force-change-password

请求体：

{
  "newPassword": "your_new_password"
}

# 登出

POST /api/auth/logout

# 商品（公开）

# 获取商品列表

GET /api/products

# 获取商品分类

GET /api/products/categories

# 获取商品详情

GET /api/products/:id

# 查询商品库存

GET /api/products/:id/stocks

# 商品管理（管理员）

以下所有接口需要在 Cookie 中携带管理员认证信息。

# 获取商品列表（后台）

GET /api/admin/products

# 创建商品

POST /api/admin/products

请求体：

{
  "name": "Steam 充值卡 ¥100",
  "description": "自动发卡，即时到账",
  "price": 99.00,
  "categoryId": 1,
  "status": "active"
}

# 更新商品

PUT /api/admin/products/:id

# 删除商品（软删除）

DELETE /api/admin/products/:id

# 恢复已删除商品

POST /api/admin/products/:id/restore

# 永久删除商品

DELETE /api/admin/products/:id/hard

# 删除商品分类

DELETE /api/admin/products/categories/:name

# 批量添加卡密

POST /api/admin/products/:id/card-secrets/batch

请求体：

{
  "secrets": "CARD-XXXX-1\nCARD-XXXX-2\nCARD-XXXX-3"
}

# 查询卡密列表

GET /api/admin/products/:id/card-secrets

# 删除单个卡密

DELETE /api/admin/products/card-secrets/:secretId

# 订单（公开）

# 创建订单

POST /api/orders

请求体：

{
  "productId": 1,
  "quantity": 1,
  "paymentMethod": "alipay"
}

# 查询订单

GET /api/orders/:orderNo

# 订单管理（管理员）

# 获取订单列表

GET /api/admin/orders

# 查询订单详情

GET /api/admin/orders/:orderNo

# 更新支付状态

PATCH /api/admin/orders/:orderNo/payment-status

请求体：

{
  "status": "paid"
}

# 登记线下收款

POST /api/admin/orders/:orderNo/offline-payment

# 重发卡密

POST /api/admin/orders/:id/resend

# 订单退款

POST /api/admin/orders/:id/refund

# 查询未知退款（人工对账）

GET /api/admin/orders/refunds/:refundNo/reconcile

# 导出订单

POST /api/admin/orders/export

# 删除订单

DELETE /api/admin/orders/:id

# 恢复订单

POST /api/admin/orders/:id/restore

# 支付

# 创建支付宝订单

POST /api/payment/:orderNo/alipay

# 查询支付宝订单状态

GET /api/payment/:orderNo/alipay/status

# 支付宝同步回调

GET /api/payment/alipay/return

# 支付宝异步通知

POST /api/payment/alipay/notify

# 创建微信支付订单

POST /api/payment/:orderNo/wechatpay

# 查询微信支付订单状态

GET /api/payment/:orderNo/wechatpay/status

# 创建 PayPal 订单

POST /api/payment/:orderNo/paypal

# PayPal 同步返回

GET /api/payment/paypal/return

# PayPal 取消支付

GET /api/payment/paypal/cancel

# PayPal Webhook

POST /api/payment/paypal/webhook

# 创建 Stripe Checkout

POST /api/payment/:orderNo/stripe/:method

:method 支持 stripe_alipay（支付宝）和 stripe_wechat_pay（微信支付）。

# Stripe Webhook

POST /api/payment/stripe/webhook

Stripe Webhook 需要原始请求体验签，请勿对此路径进行 JSON 解析。

# 微信支付回调

POST /api/payment/wechatpay/notify

微信支付回调需要原始请求体验签。

# 文件上传（管理员）

# 单文件上传

POST /api/upload/single

请求格式： multipart/form-data，字段名 file

# 多文件上传

POST /api/upload/multiple

请求格式： multipart/form-data，字段名 files

# 删除文件

DELETE /api/upload/:filename

# 系统配置（管理员）

# 邮箱配置

# 支付配置

# 短信配置

# SEO 配置

# 页脚配置

# Favicon 配置

# 对象存储配置

# 内容管理（管理员）

# 公告管理

# 轮播图管理

# 统计（管理员）

# 审计日志（管理员）

# 公开内容接口

# 健康检查

GET /health

响应：

{
  "success": true,
  "message": "OK",
  "timestamp": "2026-08-10T07:37:12.000Z",
  "uptime": 3600
}

# 安全限制

系统对 API 有以下安全防护：

# 错误响应

当 success 为 false 时，message 字段包含错误原因：

{
  "success": false,
  "message": "用户名或密码错误"
}

常见 HTTP 状态码：