76 lines
9.4 KiB
Markdown
76 lines
9.4 KiB
Markdown
# 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`；不得要求客户端同时发送两套互斥字段。
|