user · 用户体系

import { UserDomain } from '@hfyidu/api/user'

用户领域覆盖账号登录、用户信息、消费/充值/订单流水、订阅、青少年模式、设备绑定、广告/付费权益、邀请、系统消息等能力，服务前缀 user。

用例总览

用例	说明	请求方式
UserDomain.cases.login	登录（支持手机号验证码 / 微信授权 / 外推 / 邀请等多种登录场景）	POST user/login
UserDomain.cases.state	获取当前登录用户的最新状态信息	GET user/state
UserDomain.cases.feedback	提交意见反馈	POST user/feedback
UserDomain.cases.consumes	消费记录（分页）	GET user/consumes
UserDomain.cases.recharges	充值记录（分页）	GET user/recharges
UserDomain.cases.myOrder	我的订单（分页）	GET user/myOrder
UserDomain.cases.subscribe	我的订阅/追更（分页）	GET user/subscribe
UserDomain.cases.logout	退出登录	PUT user/logout
UserDomain.cases.logoff	注销账号	PUT user/logoff
UserDomain.cases.updateProfile	更新用户资料（昵称/头像等）	PUT user/info
UserDomain.cases.children	开启青少年模式	PUT user/children
UserDomain.cases.deleteChildrenPassword	关闭青少年模式（校验密码）	DELETE user/children
UserDomain.cases.bindPhone	绑定手机号	PUT user/phone
UserDomain.cases.bindProviderPhone	绑定第三方（一键登录）手机号	PUT user/phone
UserDomain.cases.install	上报"添加到桌面/安装"	PUT user/add-desk
UserDomain.cases.adBenefit	广告免广告权益记录（分页）	GET user/ad/equities
UserDomain.cases.payBenefit	付费免广告权益记录（分页）	GET user/pay/equities
UserDomain.cases.invite	获取邀请信息	GET user/invite
UserDomain.cases.removeSubscribe	取消订阅/追更	DELETE user/subscribe
UserDomain.cases.report	行为埋点上报	POST user/actionMonitor
UserDomain.cases.systemMessage	系统/站内信（分页）	GET user/systemMsg
UserDomain.cases.removePhone	解绑手机号	DELETE user/phone

login · 登录

const { data } = await UserDomain.cases.login.run({
  phone: '13800000000',
  captcha: '1234',
})

console.log(data) // UserLoginDto
console.log(data.token) // 登录凭证，登录成功后请自行写入业务项目的状态管理

登录支持多种场景，参数按需传入即可（详见下表），常见组合：

• 手机号验证码登录：phone + captcha
• 微信授权登录：wx_code / wxoa_code / theatre_code
• 结合外推链接：spread_id + spread_params + source_package_name
• 结合邀请关系：inviter_uid + inviter_spread_id + inviter_cid + inviter_time
• 结合设备信息：brand_type / brand_name / app_version / reg_id / device_oaid / device_adid / device_imei

请求参数 UserLoginBodyParams

字段	类型	必填	说明
authorization	string	否	第三方授权信息
encrypted_data	string	否	AES 加密数据
iv	string	否	AES 加解密初始向量（base64 编码后的字符串）
spread_id	string | number	否	外推 ID
spread_params	string	否	外推参数
source_package_name	string	否	外推进入时的场景，或来源包名
phone	string	否	手机号码
captcha	string	否	验证码
inviter_uid	string | number	否	邀请人 ID
inviter_spread_id	string | number	否	邀请注册时的外推 ID
inviter_cid	string | number	否	邀请注册的 cid
inviter_time	string	否	邀请时间
brand_type	string	否	移动生产商
brand_name	string	否	设备品牌
app_version	string	否	App 版本（版本号），例如 1.0.0(100000)
reg_id	string	否	快应用消息推送 RegID
device_oaid	string	否	设备 OAID
device_adid	string	否	设备 AdId
device_imei	string	否	设备 IMEI
theatre_code	string	否	微信小程序 code
wxoa_code	string	否	微信公众号 code
wx_code	string	否	微信小程序 code

响应 UserLoginDto

字段	类型	说明
token	string	登录凭证，必填
user	UserInfoDto	用户信息，默认新建一个 UserInfoDto 实例

UserInfoDto 用户信息

字段	类型	后台原始字段	说明
id	string | number	id	用户 ID，必填
openid	string | null	openid	一键登录/微信/抖音/快手等第三方 openid，默认 null
password	number | string | null	password	密码，默认 null
nickname	string	nickname	昵称，默认 ''
avatar	string | null	headimg	用户头像，默认 null
sex	number	sex	性别原始值，默认 0，可通过 UserSexType.find 反查得到 UserSexType 枚举成员
email	string	email	邮箱，默认 ''
phone	string | null	phone	手机号，默认 null
isRisk	number	is_risk	风险标识，默认 0
coins	number	balance_coin	虚拟币余额，默认 0
coupons	number	theatre_volume	虚拟券余额，默认 0
superExpireDate	string | null	super_expire_date	会员过期时间，默认 null
superStartDate	string | null	super_start_date	会员开始时间，默认 null
totalOrderMoney	string	total_order_amount	历史总充值金额，默认 ''
totalOrderNumber	number	total_order_num	历史总充值订单笔数，默认 0
totalReadTime	number	total_read_time	历史阅读时长（秒），默认 0
spreadId	number	spread_id	当前所属外推 ID，默认 0
isChildren	boolean	is_children	是否开启青少年模式，默认 false
childrenPassword	number | string	children_password	青少年模式密码，默认 ''
adid	string	device_adid	当前绑定的 AdId，默认 ''
imei	string	device_imei	当前绑定的 IMEI，默认 ''
oaid	string	device_oaid	当前绑定的 OAID，默认 ''
deviceUserId	string	device_uid	当前绑定的设备 userId，默认 ''
regId	number | string	reg_id	当前绑定的 RegID，默认 0
createdAt	string	created_at	用户创建时间，格式 yy-mm-dd hh-mm-ss，默认 '2999-12-31 23:59:59'
inviterCid	number	inviter_cid	邀请注册的 cid，默认 0
inviterSpreadId	number	inviter_spread_id	邀请外推 ID，默认 0
inviterTime	number	inviter_time	邀请时间（10 位秒级时间戳），默认 0
inviterUid	number	inviter_uid	邀请人的 uid，默认 0
lastActiveTime	number	last_active_time	上次活跃时间（10 位秒级时间戳），默认 0

state · 获取用户状态

const { data } = await UserDomain.cases.state.run({})

console.log(data.user) // UserInfoDto，同 login 返回的用户信息结构

请求参数 UserStateQueryParams

无字段，直接传 {} 即可。

响应 UserStateDto

字段	类型	说明
user	UserInfoDto	用户信息，默认新建一个 UserInfoDto 实例，字段同 login 用例

feedback · 提交意见反馈

const { data } = await UserDomain.cases.feedback.run({
  item_id: '1001',
  content: '播放卡顿',
  phone: '13800000000',
  imgs: 'https://xxx/1.jpg,https://xxx/2.jpg',
})

console.log(data.feedback_id)

请求参数 UserFeedbackBodyParams

字段	类型	必填	说明
item_id	string | number	是	反馈关联的内容/条目 ID
content	string	是	反馈内容
phone	string	否	联系电话
imgs	string	否	反馈截图，多个地址以逗号分隔

响应 UserFeedbackDto（不可变，@Freeze）

字段	类型	说明
feedback_id	string	反馈记录 ID，必填

consumes · 消费记录（分页）

这是分页列表用例，返回结构为 { list: UserConsumesDto[] }，建议参考快速开始 · 分页列表请求的用法只 new 一次并复用实例：

const consumesCase = UserDomain.cases.consumes

await consumesCase.refresh()

if (consumesCase.hasMore.value) {
  await consumesCase.loadNextPage()
}

console.log(consumesCase.list) // UserConsumesDto[]

请求参数 UserConsumesQueryParams

字段	类型	必填	说明
page	number	是	页码（由分页机制自动管理，无需手动传入）
limit	number	是	每页条数（由分页机制自动管理，无需手动传入）

响应 UserConsumesDto[]（不可变，@Freeze）

字段	类型	后台原始字段	说明
id	number | string	id	消费记录 ID，必填
remark	string	remark	备注，默认 ''
createdAt	string	created_at	消费时间
coins	string	theatre_coin	消耗的虚拟币数量
coupons	string	theatre_volume	消耗的虚拟券数量
sourceType	string	source_type	消费来源类型
detailType	string	detail_type	消费明细类型
type	string	—	记录类型标识，默认 'myconsumes'

recharges · 充值记录（分页）

这是分页列表用例，返回结构为 { list: UserRechargesDto[] }，建议参考快速开始 · 分页列表请求的用法只 new 一次并复用实例：

const rechargesCase = UserDomain.cases.recharges

await rechargesCase.refresh()

console.log(rechargesCase.list) // UserRechargesDto[]

请求参数 UserRechargesQueryParams

字段	类型	必填	说明
page	number	是	页码（由分页机制自动管理，无需手动传入）
limit	number	是	每页条数（由分页机制自动管理，无需手动传入）

响应 UserRechargesDto[]

字段	类型	后台原始字段	说明
id	string | number	id	充值记录 ID，必填
remark	string	remark	备注，默认 ''
createdAt	string	created_at	充值时间
dateOn	string | null	date_on	到期时间，默认 null
sourceType	string	source_type	充值来源类型
detailType	string	detail_type	充值明细类型
detailNumber	number	detail_number	充值到账数量，默认 0
type	string	—	记录类型标识，默认 'mycharge'

myOrder · 我的订单（分页）

这是分页列表用例，返回结构为 { list: UserMyOrderDto[] }，建议参考快速开始 · 分页列表请求的用法只 new 一次并复用实例：

const myOrderCase = UserDomain.cases.myOrder

await myOrderCase.refresh()

console.log(myOrderCase.list) // UserMyOrderDto[]

请求参数 UserMyOrderQueryParams

字段	类型	必填	说明
currentPage	number	是	页码（继承自 PagedQueryParams，由分页机制自动管理）
pageSize	number	是	每页条数（继承自 PagedQueryParams，由分页机制自动管理）
id	string	是	查询条件 ID（按需业务过滤字段）

响应 UserMyOrderDto[]（不可变，@Freeze）

字段	类型	后台原始字段	说明
id	string	id	订单 ID，必填
product	UserMyOrderProductDto	product_info	订单关联的商品信息，默认新建一个 UserMyOrderProductDto 实例
createdAt	string	created_at	下单时间
type	string	—	记录类型标识，默认 'myorder'

UserMyOrderProductDto

字段	类型	后台原始字段	说明
name	string	product_name	商品名称，默认 ''
describe	string	product_describe	商品描述，默认 ''

subscribe · 我的订阅/追更（分页）

这是分页列表用例，返回结构为 { list: UserSubscribeDto[] }，建议参考快速开始 · 分页列表请求的用法只 new 一次并复用实例：

const subscribeCase = UserDomain.cases.subscribe

await subscribeCase.refresh()

console.log(subscribeCase.list) // UserSubscribeDto[]

请求参数 UserSubscribeQueryParams

字段	类型	必填	说明
currentPage	number	是	页码（继承自 PagedQueryParams，由分页机制自动管理）
pageSize	number	是	每页条数（继承自 PagedQueryParams，由分页机制自动管理）
id	string	是	查询条件 ID（按需业务过滤字段）

响应 UserSubscribeDto[]

字段	类型	后台原始字段	说明
id	number	id	订阅记录 ID，必填
videoId	number	theatre_id	订阅的短剧 ID，默认 0
bookId	number	book_id	订阅的小说 ID，默认 0
theatre	UserSubscribeTheatreDto	—	关联的短剧信息，默认新建一个 UserSubscribeTheatreDto 实例
book	UserSubscribeBookDto	—	关联的小说信息，默认新建一个 UserSubscribeBookDto 实例

UserSubscribeTheatreDto

字段	类型	后台原始字段	说明
id	number | string	id	短剧 ID
title	string	title	短剧标题，默认 ''
cover	string	cover_url	短剧封面，默认 ''
heat	number	heat	热度，默认 80
status	number	update_status	更新状态，默认 2（2 表示完结）

UserSubscribeBookDto

字段	类型	后台原始字段	说明
id	number | string	id	小说 ID
title	string	book_name	小说书名，默认 ''
cover	string	book_cover	小说封面，默认 ''
heat	number	score	热度，默认 80
status	number	update_status	更新状态，默认 2（2 表示完结）

logout · 退出登录

await UserDomain.cases.logout.run(null)

请求参数 UserLogoutBodyParams

类型为 null，无需传入任何参数（也无请求体）。

响应

无返回值（Promise<void>），仅关注请求是否成功（不抛出异常即成功）。

logoff · 注销账号

await UserDomain.cases.logoff.run(null)

请求参数 UserLogoffBodyParams

类型为 null，无需传入任何参数（也无请求体）。

响应

无返回值（Promise<void>），仅关注请求是否成功。

updateProfile · 更新用户资料

await UserDomain.cases.updateProfile.run({
  nickname: '新昵称',
  headimg: 'https://xxx/avatar.png',
})

请求参数 UserUpdateProfileBodyParams

字段	类型	必填	说明
nickname	string	否	昵称
headimg	string	否	头像地址
encrypted_data	string	否	AES 加密数据
iv	string	否	AES 加解密初始向量
spread_id	number | string	否	外推 ID
inviter_uid	number | string	否	邀请人 ID
inviter_cid	number | string	否	邀请注册的 cid
inviter_time	string	否	邀请时间

响应

无返回值（Promise<void>），仅关注请求是否成功。

children · 开启青少年模式

await UserDomain.cases.children.run(null)

请求参数 UserChildrenBodyParams

类型为 null，无需传入任何参数（也无请求体）。

响应

无返回值（Promise<void>），仅关注请求是否成功。

deleteChildrenPassword · 关闭青少年模式

await UserDomain.cases.deleteChildrenPassword.run({
  password: '123456',
})

请求参数 UserDeleteChildrenPasswordBodyParams

字段	类型	必填	说明
password	number | string	是	青少年模式密码，用于校验关闭权限

响应

无返回值（Promise<void>），仅关注请求是否成功。

bindPhone · 绑定手机号

await UserDomain.cases.bindPhone.run({
  code: '123456',
})

请求参数 UserBindPhoneBodyParams

字段	类型	必填	说明
code	string	是	手机号验证码

响应

无返回值（Promise<void>），仅关注请求是否成功。

bindProviderPhone · 绑定第三方一键登录手机号

await UserDomain.cases.bindProviderPhone.run({
  code: 'provider_auth_code',
})

请求参数 UserBindProviderPhoneBodyParams

字段	类型	必填	说明
code	string	是	第三方（一键登录厂商）授权 code

响应

无返回值（Promise<void>），仅关注请求是否成功。

install · 上报"添加到桌面"

await UserDomain.cases.install.run(null)

请求参数 UserInstallBodyParams

类型为 null，无需传入任何参数（也无请求体）。

响应

无返回值（Promise<void>），仅关注请求是否成功。

adBenefit · 广告免广告权益记录（分页）

这是分页列表用例，返回结构为 { list: UserAdBenefitDto[] }，建议参考快速开始 · 分页列表请求的用法只 new 一次并复用实例：

const adBenefitCase = UserDomain.cases.adBenefit

await adBenefitCase.refresh()

console.log(adBenefitCase.list) // UserAdBenefitDto[]

请求参数 UserAdBenefitQueryParams

字段	类型	必填	说明
currentPage	number	是	页码（继承自 PagedQueryParams，由分页机制自动管理）
pageSize	number	是	每页条数（继承自 PagedQueryParams，由分页机制自动管理）
id	string | number	是	查询条件 ID
resource_type	ResourceType['value']（number）	是	资源类型，见 ResourceType

响应 UserAdBenefitDto[]

字段	类型	后台原始字段	说明
id	number	id	权益记录 ID，必填
uid	number	uid	用户 ID
remark	string	remark	备注，默认 ''
expiredAt	number	limit_time	过期时间
surplus	number	surplus_value	剩余数量，默认 0
volume	number	volume_value	券类剩余数量，默认 0
resource_type	number	—	资源类型原始值，默认 3，对应 ResourceType（可通过 ResourceType.find 反查）
bookId	number	book_id	关联小说 ID，默认 0
theatreId	number	theatre_id	关联短剧 ID，默认 0
createdAt	string	created_at	创建时间，默认 '2099-12-31'

payBenefit · 付费免广告权益记录（分页）

这是分页列表用例，返回结构为 { list: UserPayBenefitDto[] }，建议参考快速开始 · 分页列表请求的用法只 new 一次并复用实例：

const payBenefitCase = UserDomain.cases.payBenefit

await payBenefitCase.refresh()

console.log(payBenefitCase.list) // UserPayBenefitDto[]

请求参数 UserPayBenefitQueryParams

字段	类型	必填	说明
currentPage	number	是	页码（继承自 PagedQueryParams，由分页机制自动管理）
pageSize	number	是	每页条数（继承自 PagedQueryParams，由分页机制自动管理）
id	string | number	是	查询条件 ID
resource_type	ResourceType['value']（number）	是	资源类型，见 ResourceType

响应 UserPayBenefitDto[]

字段	类型	后台原始字段	说明
id	number	id	权益记录 ID，必填
uid	number	uid	用户 ID
remark	string	remark	备注，默认 ''
expiredAt	number	limit_time	过期时间
surplus	number	surplus_value	剩余数量，默认 0
volume	number	volume_value	券类剩余数量，默认 0
resource_type	number	—	资源类型原始值，默认 3，对应 ResourceType（可通过 ResourceType.find 反查）
bookId	number	book_id	关联小说 ID，默认 0
theatreId	number	theatre_id	关联短剧 ID，默认 0
createdAt	string	created_at	创建时间，默认 '2099-12-31'
type	string	—	记录类型标识，默认 'mybenefit'

invite · 获取邀请信息

const { data } = await UserDomain.cases.invite.run(null)

console.log(data.id) // 邀请信息 ID

请求参数 UserInviteQueryParams

类型为 null，无需传入任何参数。

响应 UserInviteDto

字段	类型	说明
id	string	邀请信息 ID，必填

removeSubscribe · 取消订阅/追更

// 取消短剧订阅
await UserDomain.cases.removeSubscribe.run({ theatre_id: '2001' })

// 或取消小说订阅
await UserDomain.cases.removeSubscribe.run({ book_id: '3001' })

请求参数 UserRemoveSubscribeBodyParams

联合类型，theatre_id（短剧）与 book_id（小说）二选一必填：

字段	类型	必填	说明
theatre_id	string | number	与 book_id 二选一	要取消订阅的短剧 ID
book_id	string | number	与 theatre_id 二选一	要取消订阅的小说 ID

响应

无返回值（Promise<void>），仅关注请求是否成功。

report · 行为埋点上报

await UserDomain.cases.report.run({
  action: 'read_page_enter',
  ext_json: JSON.stringify({ book_id: '3001', chapter_id: '5001' }),
})

请求参数 UserReportBodyParams

字段	类型	必填	说明
action	string	是	行为标识
ext_json	string	是	扩展参数，JSON 字符串

响应

无返回值（Promise<void>），仅关注请求是否成功。

systemMessage · 系统/站内信（分页）

这是分页列表用例，返回结构为 { list: UserSystemMessageDto[] }，建议参考快速开始 · 分页列表请求的用法只 new 一次并复用实例：

const systemMessageCase = UserDomain.cases.systemMessage

await systemMessageCase.refresh()

console.log(systemMessageCase.list) // UserSystemMessageDto[]

请求参数 UserSystemMessageQueryParams

字段	类型	必填	说明
currentPage	number	是	页码（继承自 PagedQueryParams，由分页机制自动管理）
pageSize	number	是	每页条数（继承自 PagedQueryParams，由分页机制自动管理）
type	MessageType['value']（number）	是	消息类型，见 MessageType

响应 UserSystemMessageDto[]（不可变，@Freeze）

字段	类型	说明
id	string	消息 ID，必填

removePhone · 解绑手机号

await UserDomain.cases.removePhone.run(null)

请求参数 UserRemovePhoneBodyParams

类型为 null，无需传入任何参数（也无请求体）。

响应

无返回值（Promise<void>），仅关注请求是否成功。

枚举

CurrencyType 货币类型

枚举成员	value	code	说明
COIN	1	coin	剧币
VOLUME	2	volume	剧券
unlockAll	5	unlock	解锁全集

MessageType 站内信类型

枚举成员	value	code	说明
ALL	0	all	所有站内信
POST	1	post	系统推送
FEED	2	feed	回复用户

ResourceType 资源类型

枚举成员	value	code	说明
DEFAULT	0	default	未指定是小说还是短剧免广告特权
NOVEL	1	novel	小说阅读免广告特权
VIDEO	2	video	短剧观看免广告特权
ALL	3	all	通用免广告特权

UserSexType 性别

枚举成员	value	code	说明
UNKNOWN	0	unknown	保密
MALE	1	male	男性
FEMALE	2	female	女性