jiapuapp/docs/APP-136请求参数字段核对表-2026-07-26.md

APP 136 请求参数字段核对表

更新时间：2026-07-26

使用规则

• 路径和 operation 数量以桌面 Apifox 当前 APP 目录为准；本机已核对根目录 家谱.openapi.json 的 136 个 method + path 均存在于桌面目录。
• 下表字段来自该次导出快照，用于逐项核对前端 consumer。桌面 Apifox 若显示更严格的 required、枚举、长度、oneOf 或条目 DTO，以桌面详情覆盖本表并重新导出。
• int64 在 H5 JSON 中不得强制转换为 JavaScript number。真实雪花 ID 超过安全整数范围时，必须由后端改为十进制字符串合同，不能截断或猜测。
• “阻塞”表示前端没有安全的参数来源、DTO、operation 或服务端成功响应；不是用本地默认值补齐的许可。

公共路径与查询参数

operation 类别	必填	可选	当前页面/状态
绝大多数 /genealogy/app/**	Header clientid	当前登录 bearer	API 请求层统一注入；实际浏览器验证
资源路径 /{genealogyId}	path genealogyId	—	所有家谱内页面从真实当前家谱上下文取得
世系资源 /{personId}	path personId	—	T03–T08、R01–R02 被首位成员 code:500 阻塞
动态资源 /{feedId}	path feedId	—	F01/F03 实际读取；点赞状态 DTO 阻塞
谱文/相册/礼仪/记录资源 ID	对应 path ID	—	已有真实测试数据的列表/详情/创建按页面验证；编辑/删除需要产品入口或受测试边界限制
分页	pageNum、pageSize 在 Apifox 均为可选	keyword、generation、status 等按各 operation	没有页面分页交互时不以默认假分页替代
行政区划搜索	query keyword	level 1–5、limit	children 已在 G03/G11 实读；其余三个尚无对应交互控件

写入 body 字段

星号为当前导出中的 required 字段。没有写入页面、稳定候选 ID 或枚举的字段均明确列为阻塞，不能手填内部 ID。

Schema / operation	页面	必填字段	可选字段	当前消费结论
VerificationChallengeBody（challenge）	A01/A04/A05	tenantId、subject	—	已接验证组件
VerificationCheckBody（verify）	A01/A04/A05	tenantId、subject、challengeId	providerCode、captchaType、payload	provider 细节以桌面 TAC DTO 为准
PasswordRegisterBody	A04	grantType、tenantId、phone、password、smsCode	nickName、registerSource	短信写入未执行（测试边界）
PasswordLoginBody	A01	grantType、tenantId、phone、password	validToken	已真实登录
SmsLoginBody	A01	grantType、tenantId、phone、smsCode	—	短信写入未执行
SmsCodeBody	A01/A04/A05	grantType、tenantId、phone	validToken	场景路径已接；未发短信
ProfileUpdateBody	M02	—	nickName、avatarOssId、sex、birthday、provinceCode、cityCode、districtCode	头像 ossId 类型冲突；字典/地区回填 DTO 需桌面详情确认
PasswordChangeBody	M04	oldPassword、newPassword	—	敏感操作，不执行
PasswordResetBody	A05	grantType、tenantId、phone、smsCode、newPassword	—	短信/改密不执行
PhoneChangeBody	M05	phone、smsCode	—	敏感操作，不执行
AccountDeactivateBody	M10	smsCode	—	敏感操作，不执行
ResumableInitBody	上传组件	实际服务端：uploadId、fileName、fileMd5、totalSize、chunkSize、totalChunks	contentType	导出快照写为 fileSize 且漏 uploadId；真实请求省略 uploadId 返回“上传ID不能为空”，改用 fileSize 返回“文件大小不能为空”。前端只按已验证的实际契约发送，等待 Apifox 统一（B17）
ResumableCompleteBody	上传组件	实际已验证链路：uploadId、fileName、fileMd5、totalSize、totalChunks	—	导出快照与实际字段冲突待后端统一；回执 ossId 仍为不安全 19 位字符串
FileReferenceBody	业务附件	bizType、bizTable、bizId、bizField	bizName、ossId、ossIds、usageScene、usageName	缺稳定业务表/字段 owner，且 ossId 类型冲突；不能猜绑定
GenealogyCreateBody	G03	genealogyName、surname、regionCode	ancestralHall、originPlace、addressDetail、coverOssId、intro、visibility、joinMode	已真实创建/回读；封面受 ossId 阻塞
GenealogyUpdateBody	G11	—	与创建同名字段	读取已接；写入需页面确切 dirty/权限合同
GenealogyJoinApplyBody	G08	—	applicantName、phone、relationDesc、applyReason、inviterUserId	已真实申请列表回读；内部邀请人 ID 无候选来源
GenealogyJoinAuditBody	G10	status	auditRemark	审核为敏感操作，不执行
GenealogyMemberUpdateBody	无独立成员管理页	—	memberName、relationName、roleType、lineagePersonId	memberId 非 personId；不得误接世系页
GenealogyOwnerTransferBody	无	targetMemberId	—	缺成员候选与产品入口，不能手填 ID
GenerationPoemBody	G12	generationNo、generationText	description、sortOrder、status	已真实维护/回读
GenerationPoemBatchBody	G12	poemText	disableMissing	已真实预览/保存回读
LineagePersonBody	T04/T05/T06、R02	name	appUserId、personNo、aliasName、sex、generation、generationName、fatherId、motherId、avatarOssId、birthDate、birthLunar、birthPlace、deathDate、deathLunar、deathPlace、burialPlace、personStatus、biography、sortOrder、remark、relationName	首位成员最小合法请求仍 code:500；业务用户/父母候选、性别/状态字典、头像 ossId 均无安全闭环
FamilyFeedBody	F02/F03 编辑入口缺失	feedContent	feedType、mediaOssIds、sortOrder、status	文本动态已真实创建/回读；媒体受 ossId 阻塞；编辑无产品入口
FamilyFeedCommentBody	F03	commentContent	parentCommentId	一级评论已真实创建/回读；回复 UI 未设计
ArticleBody	F06	articleTitle、articleContent	categoryId、articleSummary、coverOssId、authorName、sortOrder、status	已真实创建/回读；分类条目 DTO、封面 ossId 阻塞
AlbumBody	F07	albumName	albumDesc、coverOssId、sortOrder、status	已真实创建/回读；封面 ossId 阻塞
AlbumPhotoBody	F09	ossId	photoTitle、photoDesc、photographer、shootTime、sortOrder、status	上传回执成功，但 ossId JSON 类型冲突，不能创建照片记录
CeremonyBody	R07	ceremonyType、ceremonyTitle	ceremonyDesc、ceremonyTime、location、locationAddress、longitude、latitude、coverOssId、sortOrder、status	已真实创建/回读；封面受 ossId 阻塞
CeremonyGiftBody	R06	giftAmount	giverName、giftMessage	礼仪详情/献礼读取已接；写入需从真实礼仪 ID 进入
GrowthRecordBody	R08	recordTitle	lineagePersonId、recordType、recordContent、recordDate、remindTime、mediaOssIds、sortOrder、status	无真实 personId 时人物归属不能填；非人物字段已真实创建/回读
MemoBody	R10	memoTitle	memoContent、remindTime、completed、mediaOssIds、sortOrder、status	已真实创建/回读；附件受 ossId 阻塞
RelativeRecordBody	R04	relativeName	relationName、eventName、eventTime、giftAmount、recordContent、mediaOssIds、sortOrder、status	已真实创建/回读；附件受 ossId 阻塞
MeritRecordBody	R11	donorName、meritTitle	meritType、meritContent、amount、meritTime、sortOrder、status	已真实创建/回读
FeedbackBody	M07	feedbackContent	feedbackType、contactInfo	已真实提交/读取
VipOrderBody	M09	packageId	genealogyId、payType	创建订单属于支付，不执行
CeremonyInviteesBody	R07/R06	inviteeUserIds	—	缺 appUserId 候选列表；不能用 member/person ID 猜代
CeremonyInvitationResponseBody	我的活动邀请页缺失	inviteStatus	—	枚举仅 ACCEPTED/DECLINED；需要产品入口和真实邀请

后端需要优先确认的统一规则

1. 所有 int64 在 APP JSON 请求/响应中是否统一为十进制字符串；至少要覆盖 ossId、所有资源 ID、appUserId、memberId、personId、categoryId 和 packageId。
2. 所有“建议使用字典值”的字段必须在 Apifox 给出 enum 或独立 options operation，特别是 sex、personStatus、roleType、status、visibility、joinMode、payType。
3. 任何需要选择内部用户/成员/人物的操作必须返回明确且同类型的候选 ID，禁止要求客户端用不同资源的 ID 猜代。
4. 上传完成回执和所有消费 ossId 的 DTO 必须同版修复；否则上传成功并不等于业务图片创建成功。
5. 分片上传 init/complete 的 Apifox 导出字段必须与实际服务端校验一致：当前实测要求 uploadId 与 totalSize，而导出写为 fileSize 且未声明 uploadId；不得要求客户端同时发送两套互斥字段。