Autional
GitHub

POST /points/{user_id}/earn

为用户账户添加积分。如果账户不存在则自动创建。通过 X-Idempotency-Key 请求头实现幂等。 记账运维端点（P0-1）：需要 admin/super_admin 角色且配置了权限校验时需 point:admin 权限，普通用户不可自助发放。

积分服务 `bearerAuth` application/json

请求参数

名称位置类型必填默认值示例约束描述
user_id path string 是 用户ID
X-Idempotency-Key header string 否 幂等键，推荐UUID

请求体

Schema： service-point/internal/handler/dto.EarnPointsRequest

字段类型必填示例约束描述
amount integer 是
description string 否
expires_at string 否
source string 否

响应

状态描述Schema
200积分发放成功，返回账户和交易记录service-point/internal/handler/dto.PointOperationResponse
400请求参数错误或余额不足service-core/base/dto.SimpleResponse
401未认证service-core/base/dto.SimpleResponse
403权限不足（非 admin/super_admin 或缺少 point:admin 权限）service-core/base/dto.SimpleResponse
404账户不存在service-core/base/dto.SimpleResponse
409并发冲突，请重试service-core/base/dto.SimpleResponse
500服务器内部错误service-core/base/dto.SimpleResponse

引用的 Schema

service-core/base/dto.SimpleResponse

字段类型必填示例约束描述
code integer 否
message string 否
timestamp string 否

service-point/internal/handler/dto.PointAccountResponse

字段类型必填示例约束描述
balance integer 否 1500
created_at string 否 2026-01-15T10:30:00Z
exchange_rate integer 否 100
expired_points integer 否 100
frozen_balance integer 否 200
id string 否 01ARZ3NDEKTSV4RRFFQ69G5FAV
points_type string 否 cash_equivalent
status string 否 active
tenant_id string 否 tnt_example_001
total_earned integer 否 5000
total_spent integer 否 3500
updated_at string 否 2026-04-10T14:20:00Z
user_id string 否 usr_example_001
version integer 否 3

service-point/internal/handler/dto.PointOperationData

字段类型必填示例约束描述
account service-point/internal/handler/dto.PointAccountResponse 否
points_earned integer 否 100
transaction service-point/internal/handler/dto.PointTransactionResponse 否

service-point/internal/handler/dto.PointOperationResponse

字段类型必填示例约束描述
code integer 否
data service-point/internal/handler/dto.PointOperationData 否
message string 否
timestamp string 否

service-point/internal/handler/dto.PointTransactionResponse

字段类型必填示例约束描述
account_id string 否 01ARZ3NDEKTSV4RRFFQ69G5FAV
amount integer 否 100
balance_after integer 否 1500
balance_before integer 否 1400
created_at string 否 2026-04-15T10:30:00Z
description string 否 每日签到奖励
expires_at string 否 2027-01-15T10:30:00Z
id string 否 01ARZ3NDEKTSV4RRFFQ69G5FAV
idempotency_key string 否 ik_abc123
reason string 否 签到奖励
related_id string 否 01ARZ3NDEKTSV4RRFFQ69G5FAV
source string 否 daily_checkin
status string 否 completed
type string 否 earn
updated_at string 否 2026-04-15T10:30:00Z
user_id string 否 usr_example_001
在 Scalar 中试用此 API → 下载 OpenAPI 规范（JSON）↓