45 KiB
45 KiB
Apifox 逐页业务接口与页面展示核对台账
权威取证顺序：用户已打开的 Apifox 桌面端文档页 → 同一部署的脱敏只读响应（仅在获准时）→ 导出文档交叉核验。不得以导出文档缺项否定 Apifox 中已存在的 operation，也不得以 operation 存在推定页面已经完成。
记录规则：每一页必须同时给出业务动作、请求合同、响应字段、页面展示字段和完成状态。
已发布是 Apifox 文档状态，不是客户端完成状态；DECLARED_UNVERIFIED不得写成完成。
F 家族内容
F01 家族动态列表
| 核对项 | Apifox 桌面端实读 | 当前页面实情 | 结论 |
|---|---|---|---|
| 读取列表 | GET /genealogy/app/genealogies/{genealogyId}/feeds；鉴权 Authorization；路径 genealogyId:int64 必填；Header clientid:string 必填 |
页面已删除 listFamilyFeedFixtures，不再调用缺 DTO 的列表响应来填充动态卡片 |
读取 owner 存在但展示未接线，等待可消费条目 DTO |
| 响应字段 | 200 ListResult 仅实读到通用 code、msg、data[]，data 元素未声明动态 DTO 字段 |
页面不再展示 id/tag/time/title/content/author 等本地字段；只提示缺失的字段合同 |
不能建立真实字段映射；不得猜测字段名 |
| 页面状态 | 进入发布页与跨模块入口均保留 | 有效家谱下明确显示“动态列表待后端字段合同” | 未完成 / DECLARED_UNVERIFIED：待 Apifox 补充动态条目 DTO，或在获准的登录只读窗口取得脱敏真实响应后再恢复列表与详情入口 |
F02 发布家族动态
| 核对项 | Apifox 桌面端实读 | 当前页面实情 | 结论 |
|---|---|---|---|
| 发布动作 | POST /genealogy/app/genealogies/{genealogyId}/feeds；鉴权 Authorization；路径 genealogyId:int64、Header clientid:string 均必填 |
appApi.createFeed 使用严格请求和离页取消；页面不再生成本地预览 |
已接线，等待真实写入响应核验 |
| 请求体 | application/json：feedContent:string 必填且不能为空；feedType:string 可选，未传默认 text；mediaOssIds:string 可选，多个 OSS ID 用英文逗号分隔；sortOrder:int64 可选，未传默认 0；status:string 可选，未传默认正常状态 0 |
表单只采集并发送 feedContent；可选的媒体、排序、状态没有可用输入/owner，故不发送 |
页面只消费可明确映射的文本动态请求子集 |
| 响应字段 | 200 ObjectResult 只声明通用 code、msg、data:object，未声明新动态 DTO |
仅在严格成功信封后显示“已提交服务端”；不会在 F01 生成本地列表项 | 未完成 / DECLARED_UNVERIFIED：接线不等于已验证；真实写入保留人工可观察窗口 |
F03 动态详情与评论
| 核对项 | Apifox 桌面端实读 | 当前页面实情 | 结论 |
|---|---|---|---|
| 动态详情 | GET /genealogy/app/genealogies/{genealogyId}/feeds/{feedId}；鉴权 Authorization；genealogyId:int64、feedId:int64、clientid:string 必填 |
页面已删除 findFamilyFeedFixture；因详情响应仍未声明动态本体 DTO，不读取并展示猜测字段 |
正文展示仍未接线，等待可消费响应字段 |
| 详情响应 | 200 ObjectResult 只有通用 code、msg、data:object，没有动态本体 DTO |
页面不展示 tag/time/title/content/author 等正文 fixture 字段，只显示字段合同缺口 |
动态本体字段仍不能映射，不能猜测 |
| 一级评论读取 | GET /genealogy/app/genealogies/{genealogyId}/feeds/{feedId}/comments；同样要求鉴权、两个路径 ID 和 clientid。接口说明：仅返回正常展示的一级评论，replyCount 为直属回复数 |
appApi.getFeedComments 真实读取；无远端配置或响应不合同时显示错误，不回退 fixture |
已接线，等待真实响应核验 |
| 评论响应字段 | data: FamilyFeedCommentView[]：commentId、genealogyId、feedId、parentCommentId、appUserId、appUserNickName、appUserAvatar、parentAppUserId、parentAppUserNickName、commentContent、userDeleted、replyCount、commentLevel、status、createTime |
展示 id ← commentId、author ← appUserNickName、time ← createTime、content ← commentContent、replyCount ← replyCount；归属 ID 与重复 ID 在 API 边界校验 |
已接线，等待真实响应字段核验 |
| 发表评论 | POST /genealogy/app/genealogies/{genealogyId}/feeds/{feedId}/comments；请求体 `parentCommentId:int64 |
null可选（不传或null 为一级评论）、commentContent:string` 必填，最大 1000 字符 |
提交 commentContent，限制 1000 字；仅在服务端请求成功并刷新评论列表后提示提交成功 |
F04—F06 谱文列表、详情与编辑
| 页面/动作 | Apifox 桌面端实读 | 当前页面展示或输入 | 结论 |
|---|---|---|---|
| F04 列表 | GET /genealogy/app/genealogies/{genealogyId}/articles；鉴权、genealogyId:int64、clientid:string 必填；200 ListResult 仅通用 code/msg/data[]，条目未声明 DTO |
已删除 fixture、分类和本地搜索；页面明确提示缺失文章 ID、分类、标题、摘要、作者和更新时间投影 | 未完成 / DECLARED_UNVERIFIED：没有可审计的条目字段映射，不能接线或把本地筛选误称服务端能力 |
| F05 详情 | GET /genealogy/app/genealogies/{genealogyId}/articles/{articleId}；鉴权、genealogyId:int64、articleId:int64、clientid:string 必填；200 ObjectResult 仅通用对象 DTO |
已删除 fixture 正文与编辑跳转；只显示正文 DTO 缺口 | 未完成 / DECLARED_UNVERIFIED：正文、作者、时间投影均未由详情响应声明 |
| F06 新建 | POST /genealogy/app/genealogies/{genealogyId}/articles；鉴权、genealogyId:int64、clientid:string 必填 |
appApi.createArticle 严格提交 articleTitle/articleContent；成功仅表示服务端成功信封，不生成本地文章 |
已接线，等待真实写入响应核验 |
| F06 修改 | PUT /genealogy/app/genealogies/{genealogyId}/articles/{articleId}；鉴权、两个路径 ID、clientid:string 必填 |
已移除 fixture 编辑预填；没有可靠详情 DTO 和文章 ID 列表来源时，编辑入口关闭 | 未完成 / DECLARED_UNVERIFIED |
| 新建/修改请求体 | categoryId:int64 可选；articleTitle:string 必填；articleSummary:string 可选；coverOssId:int64 可选；articleContent:string 必填；authorName:string、sortOrder:int64、status:string 均可选。返回均为通用 ObjectResult |
新建页只收集并发送 articleTitle/articleContent；categoryId、摘要、封面、作者、排序、状态没有来源，故不发送 |
已实现请求字段的安全子集；编辑仍需可靠 articleId/详情 owner，所有写入待人工真实响应核验 |
F07—F09 相册、照片墙与上传
| 页面/动作 | Apifox 桌面端实读 | 当前页面展示或输入 | 结论 |
|---|---|---|---|
| F07 相册列表 | GET /genealogy/app/genealogies/{genealogyId}/albums；鉴权、genealogyId:int64、clientid:string 必填；200 ListResult 仅通用数组 DTO |
已删除 fixture 相册卡片和本地预览，页面明确提示缺失相册 ID、封面、名称、照片数、描述和更新时间字段 | 未完成 / DECLARED_UNVERIFIED：相册条目、封面 URL、照片数和更新时间没有响应字段来源 |
| F07 新建相册 | POST /genealogy/app/genealogies/{genealogyId}/albums；请求体 albumName:string 必填，albumDesc:string、coverOssId:int64、sortOrder:int64、status:string 可选；返回通用 ObjectResult |
appApi.createAlbum 严格提交 albumName；成功仅表示服务端成功信封，不生成本地相册卡片 |
已接线，等待真实写入响应核验；描述、封面、排序、状态无输入来源，故不发送 |
| F08 照片墙读取 | GET /genealogy/app/genealogies/{genealogyId}/albums/{albumId}/photos；鉴权、genealogyId:int64、albumId:int64、clientid:string 必填；200 ListResult 仅通用数组 DTO |
已删除 fixture 相册和照片墙，只显示缺失照片展示字段的状态 | 未完成 / DECLARED_UNVERIFIED：缺相册与照片展示 DTO，不能猜 OSS URL、标题或说明字段 |
| F09 写入照片记录 | POST /genealogy/app/genealogies/{genealogyId}/albums/{albumId}/photos；路径两个 ID、鉴权、clientid 必填；ossId:int64 必填，photoTitle/photoDesc/photographer/shootTime/sortOrder/status 可选 |
已删除 mock 图片库、说明表单和本地预览 | 未完成 / BLOCKED_BY_MEDIA_OWNER：接口接受的是既有 ossId，当前页面没有已核实的文件上传 owner 和真实 OSS 回执，不能把本地图片冒充上传成功 |
F10 短视频
| 核对项 | Apifox 桌面端实读 | 当前页面/结论 |
|---|---|---|
| 目录检索 | 以 video 检索，APP 目录仅返回“删除视频”；未返回视频列表、详情、发布、修改、播放地址、评论、点赞或分享 operation |
F10 所需浏览和互动链路没有业务 owner，不能以参考项目或相册接口补造 |
| 唯一命中动作 | DELETE /genealogy/app/genealogies/{genealogyId}/videos/{videoId}；接口说明为逻辑删除并释放视频文件和封面文件引用；鉴权、genealogyId:int64、videoId:int64、clientid:string 必填，200 VoidResult |
单一删除动作不能证明视频页面能读取、播放或发布；F10 未完成 / MISSING_OPERATION。不发起删除请求 |
G 家谱工作区
G01、G03、G05—G11
| 页面/动作 | Apifox 桌面端实读 | 当前页面状态与结论 |
|---|---|---|
| G01 我的家谱 | GET /genealogy/app/genealogies/mine；鉴权、clientid:string 必填；200 ListResult 仅通用 code/msg/data[] |
页面要展示当前家谱、可切换家谱、角色与快捷入口；当前 DTO 没有这些字段。未完成 / DECLARED_UNVERIFIED |
| G03 创建家谱 | POST /genealogy/app/genealogies；genealogyName、surname、regionCode 必填；ancestralHall/originPlace/addressDetail/coverOssId/intro/visibility/joinMode 可选。visibility：0 私密、1 公开、2 成员可见；joinMode：0 关闭、1 审核、2 邀请码 |
已删除本地家谱/首位人物预览。创建后必须从真实响应取得 genealogyId 再创建首位人物；当前没有可恢复查询 owner，不能从泛型 mine 列表按名称猜 ID |
| G05 家谱概览 | GET /genealogy/app/genealogies/{genealogyId}/overview；鉴权、genealogyId:int64、clientid 必填；200 ObjectResult 通用对象 |
页面需要家谱资料、成员/人物等概览显示；响应无 DTO。未完成 / DECLARED_UNVERIFIED |
| G06 搜索公开家谱 | GET /genealogy/app/genealogies/public 已在 Apifox 目录确认；读取结果仍为通用 ListResult |
已删除本地搜索结果和申请跳转；名称、籍贯、简介、可加入状态、稳定 genealogyId 均未获声明。未完成 / DECLARED_UNVERIFIED |
| G08 申请加入 | POST /genealogy/app/genealogies/{genealogyId}/join-applies；路径 genealogyId:int64、鉴权、clientid 必填；body applicantName/phone/relationDesc/applyReason:string、inviterUserId:int64 均可选 |
已删除本地填写预览；没有公开家谱详情、可申请权限或稳定 ID 投影时，不凭“可选”字段虚构申请上下文。未完成 / DECLARED_UNVERIFIED，不发送申请 |
| G09 我的申请 | GET /genealogy/app/genealogies/join-applies/mine；鉴权、clientid 必填；200 ListResult 通用数组 DTO |
已删除 fixture 申请列表；申请名称、状态、原因、时间等展示字段无映射。未完成 / DECLARED_UNVERIFIED |
| G10 审核申请 | PUT /genealogy/app/genealogies/{genealogyId}/join-applies/{applyId}/audit；路径两个 ID、鉴权、clientid 必填；status:string 必填，auditRemark:string 可选，返回 VoidResult |
已删除本地审核流程；待审核列表 DTO 和稳定 applyId 未声明。未完成 / DECLARED_UNVERIFIED，不执行审核写入 |
| G11 家谱设置 | PUT /genealogy/app/genealogies/{genealogyId}；同一组字段为 genealogyName/surname/ancestralHall/originPlace/regionCode/addressDetail/coverOssId/intro/visibility/joinMode，文档均列可选 |
已删除 fixture 预填和本地预览；概览 DTO 不能安全预填，封面仍受上传 owner 阻塞。未完成 / DECLARED_UNVERIFIED |
G12 字辈谱
| 核对项 | Apifox 桌面端实读 | 当前页面实情 | 结论 |
|---|---|---|---|
| 正常字辈读取 | GET /genealogy/app/genealogies/{genealogyId}/generation-poems；鉴权 Authorization、路径 genealogyId:int64、Header clientid:string 均必填。说明为仅返回正常状态字辈，供世系人物录入和展示使用 |
页面通过 appApi.getGenerationPoems 真实读取，展示 generationNo/generationText/status；响应归属、重复 poemId 和重复世代在 API 边界校验 |
已接线，等待真实响应核验；响应没有“当前世代”字段，页面已删除固定当前世代推断 |
| 维护列表读取 | GET /genealogy/app/genealogies/{genealogyId}/generation-poems/management；同一鉴权、路径和 clientid 要求。说明为家谱内容编辑者访问，返回正常与停用字辈，供恢复、纠错和排序调整 |
点击维护先真实请求 appApi.getGenerationPoemManagement，成功才进入编辑；不再用 fixture 或角色推断权限 |
已接线，等待真实响应/权限核验；维护读取失败不伪造“无权限”或本地编辑状态 |
| 单条新增/修改/停用恢复 | POST /genealogy/app/genealogies/{genealogyId}/generation-poems；PUT /genealogy/app/genealogies/{genealogyId}/generation-poems/{poemId}。后者路径另有 poemId:int64 必填；两者 body 均为：generationNo:int64 必填、generationText:string 必填且最大 50 字、description:string 可选且最大 500 字、sortOrder:int64 可选、status:string 可选（0 正常、1 停用） |
当前编辑器以一段本地文本拆分生成字辈行；没有单条 request mapper 或服务端返回处理 | 单条合同已明确，当前页面交互是批量维护模型；不能把本地状态切换写成停用/恢复成功，未完成 / DECLARED_UNVERIFIED |
| 批量预览 | POST /genealogy/app/genealogies/{genealogyId}/generation-poems/batch/preview；body poemText:string 必填、最大 26000 字，最多 500 世，可用空格、逗号、分号、顿号、斜杠或换行分隔；disableMissing:boolean 可选 |
appApi.previewGenerationPoemBatch 只提交 poemText/disableMissing；页面展示服务端 createCount/updateCount/keepCount/disableCount，草稿或策略变化即使旧预览失效 |
响应 GenerationPoemBatchPreviewView 的计数字段和家谱归属已校验，等待真实响应核验；不再使用本地差异作为保存依据 |
| 批量保存 | POST /genealogy/app/genealogies/{genealogyId}/generation-poems/batch/save；请求体与批量预览相同；接口说明为按当前数据生成差异，停用不删除历史字辈记录；返回 VoidResult |
保存仅在当前草稿已有同签名服务端预览时调用，严格成功后读取维护列表；本地不再更新或宣称保存成功 | 未完成 / DECLARED_UNVERIFIED：写入已接线，但无人值守未触发真实保存；需人工可观察结果和真实回读才能升级状态 |
T 世系树与成员
T01 世系树与人物操作面板
| 核对项 | Apifox 桌面端实读 | 当前页面实情 | 结论 |
|---|---|---|---|
| 世系树读取 | GET /genealogy/app/genealogies/{genealogyId}/lineage/tree；鉴权 Authorization、路径 genealogyId:int64、Header clientid:string 均必填；200 LineagePersonTreeResult |
pages/tree/t01-tree-overview.vue 已调用 appApi.getTree，但尚未作真实响应验证 |
不是“无接口”，但不能因代码存在而宣称页面已完成 |
| 树节点响应字段 | data: LineagePersonTreeView[]：personId/genealogyId/genealogyName/genealogyNo/appUserId/appUserNickName/personNo/name/aliasName/sex/generation/generationName/fatherId/fatherName/motherId/motherName/spouseNames/avatarOssId/birthDate/birthLunar/birthPlace/deathDate/deathLunar/deathPlace/burialPlace/personStatus/biography/sortOrder/status/remark/relationType/relationName/spouses[]/children[]；spouses 为配偶节点、children 为递归子女节点 |
当前 mapper 只投影树布局所需 id/parentId/name/relation/generation/branch/years/sex/personStatus；人物卡和操作面板头像固定使用本地占位图，未消费 avatarOssId；父母、配偶、子女等可用响应关系也未完整展示 |
未完成 / DECLARED_UNVERIFIED：必须补头像文件取址与字段投影，并在真实只读响应下核验树形关系，才能满足人物卡要求 |
| 点击人物后的动作 | 页面已有“查看资料、添加父亲/母亲/配偶/兄弟姐妹/儿子/女儿、调整排行、编辑信息”动作入口，分别路由 T03/T04/T06/T05 | 父母、子女的 HTTP 动作实际分别共享 /parents、/children，页面未发送 sex 或 relationName，因此不能区分“父亲/母亲”“儿子/女儿”；邀请绑定在页面中明确标作不可用 |
未完成：操作面板存在不等于每个业务动作闭环；性别语义和邀请绑定仍缺合同闭环 |
| 邀请绑定 | 在 Apifox APP 目录分别以 invite、bind 全文检索，均未命中任何邀请签发、受邀人查询、人物绑定、绑定结果查询 operation |
页面也未伪造该流程 | MISSING_OPERATION：不以入谱申请或普通人物修改替代“邀请绑定” |
T03 成员资料
| 核对项 | Apifox 桌面端实读 | 当前页面实情 | 结论 |
|---|---|---|---|
| 读取详情 | GET /genealogy/app/genealogies/{genealogyId}/lineage/persons/{personId}；鉴权、genealogyId:int64、personId:int64、clientid 均必填；200 LineagePersonResult |
页面调用 appApi.getPerson |
读取路径存在，但不是完成依据 |
| 详情响应字段 | data: LineagePersonView：personId/genealogyId/genealogyName/genealogyNo/appUserId/appUserNickName/personNo/name/aliasName/sex/generation/generationName/fatherId/fatherName/motherId/motherName/spouseNames/avatarOssId/birthDate/birthLunar/birthPlace/deathDate/deathLunar/deathPlace/burialPlace/personStatus/biography/sortOrder/status/remark |
已把别名、性别字典值、人物状态字典值、出生/逝世农历、出生/逝世地点、安葬地、配偶名、生平和备注纳入 T03 mapper 与展示；仍未展示头像（缺 avatarOssId 取址）、appUserNickName、排序/状态原值，亲属仍只可由父母 ID 跳转。 |
未完成 / DECLARED_UNVERIFIED：T03 仍是半成品，不能计入完成；字段已接线但未用真实只读响应核验，头像、完整亲属投影和字典语义仍未闭环。 |
T04 添加亲属、T05 编辑、T06 排行
| 页面/动作 | Apifox 桌面端实读 | 当前页面实情与结论 |
|---|---|---|
| T04 首位成员/新增人物 | POST /genealogy/app/genealogies/{genealogyId}/lineage/persons；鉴权、路径 genealogyId、clientid 必填；body 只有 name:string 必填。可选字段为 appUserId/personNo/aliasName/sex/generation/generationName/fatherId/motherId/avatarOssId/birthDate/birthLunar/birthPlace/deathDate/deathLunar/deathPlace/burialPlace/personStatus/biography/sortOrder/remark/relationName；其中 personNo 由服务端生成，avatarOssId 须来自文件上传组件 |
页面只提交 name/birthDate/biography。请求字段是合法子集，但没有性别、世代、父母、头像、状态、排行等来源；真实写入未验证。未完成 / DECLARED_UNVERIFIED |
| T04 添加父母、子女、兄弟姐妹、配偶 | 分别为 POST .../lineage/persons/{personId}/parents、.../children、.../siblings、.../spouses；路径 genealogyId/personId、鉴权、clientid 均必填，均返回 LineagePersonResult，body 与新增人物同合同。实读 sex:string 仅写“建议使用系统字典值”，示例为 "0"；以“字典/dict/性别”检索 APP/PC 目录均未找到该字典读取 owner 或男/女码值映射。 |
页面现会提交所选亲属的 relationName，不再把路由意图丢掉；父亲/母亲共用 /parents，儿子/女儿共用 /children 仍不能仅凭该显示名获得可靠性别语义。头像仍缺文件上传回执。未完成 / DECLARED_UNVERIFIED，不得拿参考项目的旧 0/1 码值猜填，也不能执行无人值守写入。 |
| T05 修改人物 | PUT /genealogy/app/genealogies/{genealogyId}/lineage/persons/{personId}；两个路径 ID、鉴权、clientid 必填，body 与新增人物同合同，返回 LineagePersonResult |
已读写 name/aliasName/generationName/birthDate/birthLunar/birthPlace/deathDate/deathLunar/deathPlace/burialPlace/biography/remark；静态校验确认表单字段与请求白名单一致。头像仍缺上传回执；性别、人物状态、排行因字典或原子 owner 缺失未写入。 |
| T06 调整排行 | Apifox 只有单人物 PUT .../persons/{personId} 中的可选 sortOrder:int64，没有同辈排行列表、批量重排、原子提交或冲突回显 operation |
页面已明确显示“服务暂未开放”，不逐人写入 |
T07 成员目录、T08 成员状态
| 页面/动作 | Apifox 桌面端实读 | 当前页面实情与结论 |
|---|---|---|
| T07 成员目录分页与搜索 | GET /genealogy/app/genealogies/{genealogyId}/lineage/persons/page；query 可选 pageNum（默认 1）、pageSize（默认 10）、keyword（姓名/别名/人物编号）、generation:int64、personStatus:string；响应 LineagePersonPageResult 为 rows: LineagePersonView[] 与 total。另有 GET .../lineage/persons/options?keyword= 供人物选项读取 |
已移除 listTreeMemberPresentationFixtures；页面使用实际 pageNum/pageSize/keyword 请求、消费 rows/total，支持服务端搜索与继续加载；本地预览明确报真实读取不可用，不伪造目录数据。 |
| T08 成员状态说明 | 人物详情、列表和分页都提供 personStatus、status；停用人物为 DELETE /genealogy/app/genealogies/{genealogyId}/lineage/persons/{personId}，接口说明为逻辑停用且在正常子女时拒绝停用，返回 VoidResult |
已移除 findTreeMemberPresentationFixture 和 privacy/deceased/forbidden 推断；页面读取人物详情并原样展示 personStatus，明确说明当前没有状态字典 owner，也不提供停用写入。 |
R 记录模块
R01 人物录、R02 人物档案
| 页面/动作 | Apifox 桌面端实读 | 当前页面展示或输入 | 结论 |
|---|---|---|---|
| R01 人物录列表、搜索 | 正确读取 owner 是 GET /genealogy/app/genealogies/{genealogyId}/lineage/persons/page；query 为 pageNum/pageSize/keyword/generation/personStatus，响应为 rows: LineagePersonView[]/total。人物选项另有 GET .../lineage/persons/options?keyword= |
已移除 listTreeMemberPresentationFixtures 和本地“新增预览”；页面用 pageNum/pageSize/keyword 请求、消费 rows/total，支持服务端搜索和继续加载。新增人物保持从 T01 亲属关系入口进入。 |
未完成 / DECLARED_UNVERIFIED：读取合同已接线并经静态检查，尚未用登录态获得一次真实响应；世代/人物状态筛选尚未增加页面控件。 |
| R02 人物档案读取 | GET /genealogy/app/genealogies/{genealogyId}/lineage/persons/{personId} 返回已在 T03 实读的 LineagePersonView，含 name/generation/generationName/biography/remark，以及头像、性别、别名、亲属名、地点、生卒、状态等 |
已移除 findTreeMemberPresentationFixture、本地预览/编辑；页面读取详情并展示已声明的资料字段，编辑入口改为跳转 T03 的成员档案，再由 T05 完成可写字段维护。成长日志仍跳 R08，人生事仍为待开放。 |
未完成 / DECLARED_UNVERIFIED：读取已接线并经静态检查，尚未取得真实详情响应；头像取址、性别/状态字典和完整亲属投影仍未闭环。 |
| R02 新建/编辑人物 | POST /lineage/persons、PUT /lineage/persons/{personId} 的完整人物请求合同已在 T04/T05 实读，name 必填，其余有世代、头像、亲属、状态、排序、传记、备注等字段 |
表单只收 name/generationName/generation/biography/remark，保存仅变成本地预览 |
未完成 / DECLARED_UNVERIFIED：是可辨认的字段子集但没有远端读写闭环；不得把“生成本地预览”说成新建或修改成功 |
R03 贺礼簿、R04 往来详情与编辑
| 页面/动作 | Apifox 桌面端实读 | 当前页面展示或输入 | 结论 |
|---|---|---|---|
| R03 列表、R04 详情 | GET /genealogy/app/genealogies/{genealogyId}/relative-records、GET .../relative-records/{relativeId}；均需鉴权、genealogyId、clientid，分别返回通用 ListResult、ObjectResult，未声明条目 DTO |
已删除 R03/R04 fixture 列表、详情和本地编辑预填；页面明确说明缺记录 ID、关系、事项、时间、金额和备注的响应映射 | 未完成 / DECLARED_UNVERIFIED：接口并非缺失，但响应没有声明 relativeId 等展示字段，不能猜字段映射 |
| R04 新增/修改 | POST /genealogy/app/genealogies/{genealogyId}/relative-records、PUT .../relative-records/{relativeId}；body 为 relativeName:string 必填，relationName/eventName/eventTime/giftAmount:number/recordContent/mediaOssIds/sortOrder/status 可选，返回通用 ObjectResult |
创建页通过 appApi.createRelativeRecord 提交 relativeName/relationName/eventName/eventTime/giftAmount/recordContent；媒体字段没有上传 owner，故不发送。详情/修改入口因无记录 DTO/ID 来源关闭 |
创建已接线，等待真实写入响应核验；修改仍 DECLARED_UNVERIFIED |
| R04 删除 | DELETE .../relative-records/{relativeId} 已在 Apifox 同一资源目录确认 |
页面明确显示“删除暂未开放” | 未完成 / DECLARED_UNVERIFIED：不执行删除；存在删除 operation 也不改变其他读写未接线的事实 |
R05—R07 礼仪活动与献礼
| 页面/动作 | Apifox 桌面端实读 | 当前页面展示或输入 | 结论 |
|---|---|---|---|
| R05 礼仪活动列表、R07 新建 | 在 APP 目录以 ceremony 实读到该资源共六个动作：详情、修改、活动献礼列表、新增献礼、删除活动、删除献礼；没有活动列表或新建活动 operation |
已删除 listCeremonyFixtures、新建和编辑预览；R05/R07 显示缺 operation 状态并保留返回路径 |
未完成 / MISSING_OPERATION：不得用详情或修改接口冒充活动列表/新建；R05、R07 的主业务 owner 缺失 |
| R06 礼仪详情 | GET /genealogy/app/genealogies/{genealogyId}/ceremonies/{ceremonyId}；需鉴权、路径 genealogyId/ceremonyId、clientid，返回通用 ObjectResult；未声明活动 DTO |
已删除 fixture、受邀人拼装和编辑入口，只提示详情字段缺口 | 未完成 / DECLARED_UNVERIFIED：详情 operation 存在，但这些展示字段、受邀人及其关系没有响应字段依据 |
| R07 修改礼仪 | PUT .../ceremonies/{ceremonyId}；body ceremonyType:string、ceremonyTitle:string 必填，ceremonyDesc/ceremonyTime/location/coverOssId/sortOrder/status 可选，返回通用 ObjectResult |
无可靠详情 DTO 和活动 ID 来源时关闭修改，且封面另缺上传 owner | 表单字段虽可对应，但没有远端读取、写入和回读；未完成 / DECLARED_UNVERIFIED |
| R06 献礼 | GET .../ceremonies/{ceremonyId}/gifts 返回通用 ListResult；POST .../gifts 的 body 为 giverName:string 可选、giftAmount:number 必填、giftMessage:string 可选，返回通用对象 |
页面有受邀人展示，不是献礼条目展示或写入 | 未完成 / DECLARED_UNVERIFIED：献礼接口不能替代受邀信息，且没有条目 DTO 可映射 |
R08 成长日志、R09 人生事
| 页面/动作 | Apifox 桌面端实读 | 当前页面展示或输入 | 结论 |
|---|---|---|---|
| R08 列表与详情 | GET /genealogy/app/genealogies/{genealogyId}/growth-records、GET .../growth-records/{recordId}；同一 APP 资源另有新增、修改、删除，共五个动作。列表为通用 ListResult、详情为通用 ObjectResult，均未声明记录 DTO |
已删除 listGrowthRecordFixtures 和本地列表预览；页面只保留创建表单 |
未完成 / DECLARED_UNVERIFIED：recordId、标题、日期、内容没有响应字段声明，不能恢复列表或详情 |
| R08 新增/修改 | POST .../growth-records、PUT .../growth-records/{recordId}；新增 body 已实读：lineagePersonId/recordType/recordContent/recordDate/remindTime/mediaOssIds/sortOrder/status 可选，recordTitle:string 必填 |
appApi.createGrowthRecord 提交 recordTitle/recordDate/recordContent；人员绑定、类型、提醒、媒体、状态无来源，故不发送；修改没有记录 ID 来源而关闭 |
创建已接线，等待真实写入响应核验；修改 DECLARED_UNVERIFIED |
| R09 人生事 | 分别以 life 与“人生”在 APP 接口目录检索，均未命中独立人生事件资源；当前文档中不能用成长、备忘或人物资料替代 |
页面已明确提示接口未开放且不展示/提交数据 | 未完成 / MISSING_OPERATION：保持关闭是正确的，不虚构读写链路 |
R10 家族备忘、R11 功德记录
| 页面/动作 | Apifox 桌面端实读 | 当前页面展示或输入 | 结论 |
|---|---|---|---|
| R10 备忘列表与详情 | GET /genealogy/app/genealogies/{genealogyId}/memos、GET .../memos/{memoId}；同一资源另有新增、修改、删除，共五个动作。列表 ListResult、详情 ObjectResult 都只声明通用包装字段 |
已删除 fixture 列表和本地预览，只保留创建表单 | 未完成 / DECLARED_UNVERIFIED：不能从泛型响应推导 memoId 或 completedLabel，状态文案也没有字典依据 |
| R10 新增/修改 | POST .../memos、PUT .../memos/{memoId}；body memoTitle:string 必填，memoContent/remindTime/completed/mediaOssIds/sortOrder/status 可选 |
appApi.createMemo 提交 memoTitle/remindTime/memoContent；完成状态与媒体无可靠来源，故不发送；修改缺 ID 来源关闭 |
创建已接线，等待真实写入响应核验；修改 DECLARED_UNVERIFIED |
| R11 功德列表 | GET /genealogy/app/genealogies/{genealogyId}/merit-records；同资源仅另有新增、删除，共三个动作；列表返回通用 ListResult，未声明条目 DTO |
已删除 fixture 列表和本地预览，只保留创建表单 | 未完成 / DECLARED_UNVERIFIED：列表字段没有合同映射，页面不猜条目字段 |
| R11 新增/修改 | POST .../merit-records；body donorName:string、meritTitle:string 必填，meritType/meritContent/amount:number/meritTime/sortOrder/status 可选；当前 APP 目录未见修改 operation |
appApi.createMeritRecord 提交捐赠人、标题、类型、金额、时间和内容；排序/状态无来源，故不发送 |
新增已接线，等待真实写入响应核验；编辑 MISSING_OPERATION |
N 消息通知
| 页面/动作 | Apifox 桌面端实读 | 当前页面展示或输入 | 结论 |
|---|---|---|---|
| N01 消息中心列表 | GET /genealogy/app/notifications；鉴权 Authorization、Header clientid:string 必填；200 ListResult 只声明通用 code/msg/data[]，条目仍为泛型对象 |
已删除 listNotificationFixtures、未读计数和本地业务跳转，只显示缺失通知字段合同 |
未完成 / DECLARED_UNVERIFIED：没有消息 ID、已读、标题、时间、正文、目标类型和目标参数的响应字段合同；不能把 fixture 的跳转当作通知接口返回能力 |
| N02 消息详情 | 在 APP 消息通知目录实读到的仅有列表、单条标已读、全部标已读三个 operation；没有详情读取 operation | 已删除详情 fixture，只显示缺详情 owner 状态 | 未完成 / MISSING_OPERATION：不能以列表泛型或本地 fixture 冒充单条详情；详情所需正文、来源和跳转字段均无接口 owner |
| N01/N02 单条标已读 | POST /genealogy/app/notifications/{notificationId}/read；鉴权、notificationId:int64、clientid 必填，返回 VoidResult |
无可消费通知 ID 时页面不显示单条标已读，已删除本地 unread 修改 |
正确写入 owner 存在但没有可回读 item/ID，未完成 / DECLARED_UNVERIFIED |
| N01 全部标已读 | POST /genealogy/app/notifications/read-all；鉴权、clientid 必填，返回 VoidResult |
已删除“全部已读”本地 fixture 修改 | 未完成 / DECLARED_UNVERIFIED：无列表回读时不把本地状态改动当服务端写入成功 |
M 个人中心与账号
M01 个人中心、M02 个人资料
| 页面/动作 | Apifox 桌面端实读 | 当前页面展示或输入 | 结论 |
|---|---|---|---|
| M01 当前用户资料 | GET /genealogy/app/auth/profile；鉴权、clientid 必填，返回通用 ObjectResult，data 未声明用户 DTO |
已删除 currentUser.name/role/phone 和 fixture 未读数展示，保留各模块入口 |
未完成 / DECLARED_UNVERIFIED：用户名、角色、手机号及其脱敏规则没有响应字段合同；不可把 mock 当前用户当作已登录资料 |
| M02 读取与修改资料 | 读取为同一 GET /auth/profile；修改为 PUT /genealogy/app/auth/profile。修改 body 已实读：nickName/avatarOssId/sex/birthday/provinceCode/cityCode/districtCode/addressDetail 均可选，返回通用 ObjectResult |
已删除 mock 预填和本地保存；当前 UI 的真实姓名/邮箱与更新合同不相交，页面明确关闭编辑 | nickName 可对应，但 realName/email 不在修改合同；后端的头像、性别、生日、地区、地址未有页面输入或 mapper。未完成 / DECLARED_UNVERIFIED；头像另受上传 owner 阻塞 |
M03—M05 安全设置、改密、换绑手机
| 页面/动作 | Apifox 桌面端实读 | 当前页面展示或输入 | 结论 |
|---|---|---|---|
| M03 账号与安全概览 | 资料读取、改密、换绑均有各自 APP operation，未见独立“安全概览/设备/登录记录”读取 operation | 已删除本地账号摘要，保留改密与换绑入口 | 未完成 / DECLARED_UNVERIFIED：入口可以保留，但安全状态、设备、会话等没有 owner，不能凭本地提示宣称已核验 |
| M04 修改密码 | PUT /genealogy/app/auth/password；鉴权、clientid 必填；body oldPassword:string、newPassword:string 均必填且均为 32 位 MD5；返回 VoidResult |
页面将当前/新密码 MD5 后以 oldPasswordHash/newPasswordHash 传给 api 层，最终字段名映射为 oldPassword/newPassword |
请求字段、摘要格式和页面动作可对齐；但尚未在真实账号下接受响应验证，且不得无人值守改密。未完成 / DECLARED_UNVERIFIED |
| M05 换绑手机号 | PUT /genealogy/app/auth/phone；鉴权、clientid 必填；body clientId:string、phone:string、smsCode:string 均必填，验证码模式为 4 位；响应为 ObjectResult（含 400/200） |
已删除 mock 当前手机号、输入和本地校验，页面明确提示需人工 TAC/短信与资料 DTO | 号码和四位码输入可对应，但缺实际滑动验证、短信发送、clientId 来源、写入与回读。未完成 / DECLARED_UNVERIFIED；不代用户发验证码或换绑 |
M06 帮助、M07 反馈、M08 推广、M09 VIP、M10 关于
| 页面/动作 | Apifox 桌面端实读 | 当前页面展示或输入 | 结论 |
|---|---|---|---|
| M06 帮助中心 | GET /genealogy/app/help-articles、GET /genealogy/app/help-articles/{articleId}；列表为通用 ListResult、详情为通用对象，未声明文章 DTO |
页面本地内置分类、问题、答案和搜索 | 未完成 / DECLARED_UNVERIFIED：帮助读取 owner 存在，但不能从泛型响应推导问题、答案、分类或文章 ID；当前本地说明不是服务端帮助 |
| M07 提交反馈 | POST /genealogy/app/feedback；鉴权、clientid 必填；body feedbackType:string 可选、feedbackContent:string 必填、contactInfo:string 可选，返回通用 ObjectResult |
表单与 api 层正好提交这三字段，页面包含成功、失败、结果不确定的提示 | 请求合同已对应；未经真实接受响应验证，不能把 UI 成功态视为后端成功。未完成 / DECLARED_UNVERIFIED，不代用户提交反馈 |
| M08 应用推广/邀请 | GET /genealogy/app/promotions 已存在，但仅为“应用推广列表”，返回通用 ListResult；全文检索未发现邀请码签发、归因、奖励、受邀绑定或分享回执 operation |
M08 正确保持“推广能力未开放”，没有伪造邀请 | 未完成 / MISSING_OPERATION：普通推广内容列表不能替代邀请推广业务闭环 |
| M09 VIP 与订单 | APP 目录有 GET /genealogy/app/vip/packages、GET /genealogy/app/vip/orders、POST /genealogy/app/vip/orders；前两者列表响应为泛型。创建订单 body 为 packageId:int64 必填，genealogyId:int64、payType:string 可选，返回通用对象 |
页面当前不读取、不会创建订单或扣费 | 未完成 / DECLARED_UNVERIFIED：套餐与订单 owner 存在但 DTO 未声明、页面未接线；支付调起、支付结果、取消/退款等动作在当前 APP 目录未形成可审计合同，故继续禁用付费流程 |
| M10 关于与退出 | 协议、版本为本地静态内容；退出为 DELETE /genealogy/app/auth/logout，鉴权、clientid 必填，返回 VoidResult |
M10 调用 api 层退出并且无论远端结果如何都会清本机会话 | 登出路径与合同一致，但未在真实请求下验证；协议/版本没有远端 owner 的需求。退出动作仍标 DECLARED_UNVERIFIED，不在无人值守状态触发 |
A 认证
| 页面/动作 | Apifox 桌面端实读：业务接口、请求/响应字段 | 当前页面展示或输入字段 | 完成状态 |
|---|---|---|---|
| A01 登录：验证前置与发送短信 | GET /captcha/require：查询 tenantId/clientId/sceneCode/subject，其中 sceneCode 必填；响应 VerificationRequireResult 已声明 required/providerCode/captchaType/sceneCode/ttlSeconds。POST /genealogy/app/auth/sms/code：Header clientid 必填；Body clientId/grantType/tenantId/sceneCode/phone/validToken 均必填，sceneCode 含 APP_SMS_LOGIN；响应 VoidResult。 |
a01-entry.vue 以手机号、密码或四位短信码登录；取码先查验证要求，再由内嵌验证组件提交 validToken。滑动验证采用服务商组件本身，不增加页面自定义样式。 |
未完成 / DECLARED_UNVERIFIED：前置响应字段与发送短信字段已逐项对上，但未发送短信；required=false 时如何签发可消费票据也未由 Apifox 合同说明，不能把页面本地倒计时当发送成功。 |
| A01 账号密码登录 | POST /genealogy/app/auth/login：Header clientid 必填；Body clientId/grantType/tenantId/phone/password 均必填，grantType=password，password 为 32 位 MD5；响应组件为 LoginResult。 |
页面将手机号和 MD5 密码传至 API 层；当前 API 层读取响应 access_token 保存会话。登录接口请求体没有 validToken 字段，页面仅把滑动验证作为前端完成条件。 |
未完成 / DECLARED_UNVERIFIED：请求字段对齐；Apifox 当前只标出 LoginResult 组件，未在该 operation 展开可核的会话字段，且尚未以测试账号获得一次被接受的响应，不能声明登录已完成。 |
| A01 短信登录 | POST /genealogy/app/auth/login/sms：Header clientid 必填；Body clientId/grantType/tenantId/phone/smsCode 均必填，grantType=sms，smsCode 为四位短信码；响应组件为 LoginResult。 |
页面字段为手机号、四位验证码；API 层同样依赖返回的 access_token 建立会话。 |
未完成 / DECLARED_UNVERIFIED：请求合同对齐，但该动作依赖真人收到短信；未发送、未登录，不把页面登录成功提示当成远端成功。 |
| A04 注册 | 短信链路同上但 sceneCode=APP_REGISTER。POST /genealogy/app/auth/register：Header clientid 必填；Body 已实读 clientId/grantType/tenantId/phone/password/smsCode，grantType=password、密码为 32 位 MD5、验证码为四位；响应 LoginResult。 |
页面输入手机号、验证码、密码、确认密码和协议勾选；提交时传手机号、MD5 密码、验证码。 | 未完成 / DECLARED_UNVERIFIED：字段链路可对照，但注册会创建真实账号，按约定不在无人值守时触发；LoginResult 的完整展示字段仍待接受响应核实。 |
| A05 找回密码 | 短信链路同上但 sceneCode=APP_FORGOT_PASSWORD。PUT /genealogy/app/auth/password/reset：Header clientid 必填；Body clientId/grantType/tenantId/phone/newPassword/smsCode 均必填，grantType=password、newPassword 为 32 位 MD5、验证码为四位；响应 VoidResult。 |
页面输入手机号、验证码、新密码、确认密码；提交参数为手机号、MD5 新密码、验证码。 | 未完成 / DECLARED_UNVERIFIED：请求字段对齐；找回会真实改密，未触发，不能以本地“修改成功”状态当接口完成。 |
| A06 账号状态/恢复 | 在 APP 认证目录按 status、frozen、disabled、risk、appeal、recovery 检索，未找到账号状态读取、限制原因、申诉或恢复的独立 operation。 |
页面只读路由参数 status，并用本地 frozen/disabled/risk 文案展示限制原因和恢复说明；“查看恢复方式”仅打开本地弹层；该文件也未注册进 pages.json 的 52 条路由。 |
未完成 / MISSING_OPERATION：没有后端 owner 提供状态、原因、可恢复路径或申诉结果，不能把静态文案当真实账号状态；未注册时也不能由正常路由到达。 |
本轮累计
| 范围 | 已逐页实读 | 可实施映射 | 未完成原因 |
|---|---|---|---|
| F01—F10 | 10/10 | F02 发布、F03 评论读取/提交、F06 谱文创建、F07 相册创建已按声明字段接线；F01/F04/F05/F08/F09 已关闭无 DTO 或上传 owner 的 fixture 展示 | F02/F03/F06/F07 等待真实响应核验；动态、谱文和相册展示仍缺 DTO；F09 缺文件上传 owner，F10 缺读取/发布 owner；写入不得在无人值守时触发 |
| G01、G03、G05—G12 | 9/9 | G12 正常列表、维护列表、批量预览/保存已按声明字段接线；G03/G06/G08—G11 已删除 fixture 或本地预览 | G12 待真实读取/写入响应核验，当前世代字段仍未声明；G03 两阶段结果恢复链、G06/G08—G11 的 DTO/ID/权限缺口仍未闭环 |
| T01、T03—T08 | 7/7 | 树、详情、人物分页/选项、人物与亲属写入合同均已逐项实读；T03、T05、T07、T08 的已声明读取/字段子集已接线 | T03 明确为未完成；T01 头像与邀请绑定未闭环；T04 关系性别语义不完整；T06 缺原子排行 operation；T07/T08 均待真实读取响应核验 |
| R01—R11 | 11/11 | R03/R04、R08、R10、R11 创建已按声明字段接线；R05—R07/R09 已删除本地流程 | 所有 R 列表/详情仍缺 DTO；创建待真实响应核验；R05/R07、R09 另有明确 MISSING_OPERATION |
| N01—N02 | 2/2 | 消息列表、单条标已读、全部标已读 owner 已实读；页面已删除 fixture 消息和本地已读 | 列表条目 DTO 未声明、消息详情 operation 明确缺失，无稳定 ID 时不发送已读 mutation |
| M01—M10 | 10/10 | M01—M03/M05 已删除 mock 资料和本地资料流程；改密、反馈、退出已有独立接线 | M02 字段与合同不一致；读取 DTO 多为泛型；M08 缺邀请业务 owner；VIP 还缺可审计支付闭环；敏感写入均未实测 |
| A01、A04—A06 | 4/4 | 验证要求、短信发送、密码/短信登录、注册、找回密码的请求合同已逐项实读 | 无人值守不发送短信、不注册、不找回、不真实登录；LoginResult 仅见响应组件名，完整会话字段待接受响应；A06 明确缺状态/恢复 owner |