rain
41 KiB
41 KiB
接口与页面映射总表
更新日期：2026-07-22
阶段状态：阶段 0 已完成；导航栈与 T01 专项设计已完成三人终审，业务代码尚未实施
接口状态：已完成 A04 注册响应和 T01 世系图专项核对；其余 OpenAPI 操作仍待逐项审查
一、权威边界
本文件是活动页面、业务目标、进入方式、返回或完成目标、适用状态与接口归属关系的唯一总表。pages.json 是活动路由的唯一注册清单；两者必须同轮更新并保持精确一致。
接口的唯一源头是后端维护的 Apifox 项目。根目录 APP.openapi.json 用于自动分析，APP.openapi.yaml 用于人工阅读与跨工具导入。阶段 0 只保护了两份用户导出；当前仅对导航依赖、A04 注册响应和 T01 世系图做了专项核对，不能把专项结论扩张为 153 个操作均已审查。
当前边界如下：
pages.json注册52条活动路由；A02 已并入 A01，A06 保留源码但不属于活动路由。- 全项目响应式迁移与统一扫描已经完成，实际
66/66个 Vue 文件均在覆盖清单中。 - A 系列及 G01—G10 已由用户在 MuMu 中人工确认；G11、G12 以及 T、F、R、N、M 页面已由上一位代理按用户授权在 MuMu 中逐页、逐状态审核并修复。
- 上述视觉结论是当前继续工作的基线，不等于真实接口、持久化、系统权限、真实短信、微信、支付或跨页数据闭环已经完成。
- 后续发现明确、可复现的样式、交互或业务问题时可以重新打开页面；不得因为旧结论写着“通过”就忽略证据。
二、全局业务与交互合同
2.1 账户、启动与登录
- APP 不设游客模式。首次打开、无有效凭证或凭证过期时进入 A01；有效登录态进入 G01。
- A01 是唯一活动登录页，承载密码登录、短信登录、注册、找回密码、协议入口和微信登录入口。登录成功统一到 G01，不直接恢复上次浏览的深层页面。
- A04 注册成功的目标是建立登录态后进入 G01。当前 OpenAPI 已确认
POST /genealogy/app/auth/register的200响应复用LoginResult，其LoginVo可返回token/accessToken/tokenValue；正式接入应保存有效会话后直接进入 G01，不让用户重复登录。行为验证与短信发送时机仍在后续短信状态机阶段核对。 - A05 重设成功后不自动登录：返回 A01，保留合规的手机号信息，切换密码方式、聚焦密码框并让用户使用新密码登录。
- A04、A05、M04 共用
utils/validation.js的唯一密码策略：密码长度8–32位且必须同时包含字母和数字；M04 的新密码还不得与旧密码相同。页面不得各自复制或放宽该规则。 - A01 未勾选协议时在协议区域就近高亮并显示错误，不弹原生提示、不跳页；用户勾选后立即清除错误状态。
- A01、A04、A05 最终共用真实行为验证能力，但触发时机必须按业务区分：A01 在本地校验通过后、登录请求前触发；A05 在请求发送短信验证码前触发，最终重设提交不重复验证；A04 当前临时在完整注册表单提交后触发，后端提供短信注册接口时必须迁移到发送短信前，并删除旧触发路径。关闭或验证失败时保留表单内容，不得形成两套并行验证路径。
- 短信验证码需要完整状态机：可发送、发送中、倒计时、发送失败、限流、前后台恢复和到期。该状态机在导航栈统一之后单独评估，不在阶段 0 实施。
- 凭证过期先回 A01，再显示项目自定义的单按钮信息弹窗并聚焦登录表单；主动退出清除凭证，但可以保留用户上次选择的密码或短信登录方式，不保存密码。
2.2 家谱上下文与加入、创建
- 一个账号允许创建或加入多个家谱。G01 列表按“我创建的”“我加入的”“加入申请”分组，顶部只表示当前选中项。
- G01 下方列表卡只切换顶部当前项，不直接进入详情；顶部可用家谱卡才进入 G05。默认选择顺序为：本机保存的上次有效 ID、第一个可操作家谱、列表第一项。只保存 ID，不复制整份家谱数据。
- 审核中记录只展示进度和“撤回申请”，顶部卡不可进入家谱；被拒绝记录展示原因和“修改后重新提交”，进入 G08 而不是 G05；已退出或被移除记录展示原因和“重新申请”，不得访问原家谱内容。
- 只有可用家谱能够成为全局家谱上下文；审核中、被拒绝、已退出、被移除或待录入始祖的记录不得覆盖最近一个可用上下文。
- 没有可用家谱时，相关页面不得展示上一个失效家谱的缓存内容，应引导用户搜索家谱、使用邀请码或创建家谱。
- G01 空态的主次顺序为搜索家谱、邀请码加入、创建家谱；非空列表保留“添加家谱”底部弹层。所有者可见世系、成员、字辈诗、申请审核四个快捷入口，普通成员不显示申请审核。
- G06 同时承载搜索与邀请码定位。搜索申请进入审核；邀请码目标是直接加入，不应生成审核记录。邀请码验证和直接加入目前仍是待核对的接口依赖。
- G06 结果至少需要谱名、姓氏、地区、堂号、所属上级谱、当前支系、管理者或认证信息、成员规模和最近更新时间，以区分同名家谱和支系；未加入、已加入、审核中、被拒绝、已退出或移除、我创建的六种关系各自只出现一个明确动作。
- G08 当前用真实姓名、与已知长辈的文字关系和补充说明表达申请；用户可见示例统一使用“某某某堂侄”等通用占位，不出现具体姓名。后端提供结构化参照成员或关系字段后，应以新合同完整替换文字关系旧路径。
- G03 当前只创建独立家谱。创建完成但始祖未录入时，G01 必须保留“待录入始祖”记录；完成始祖后进入 G05，由用户主动进入 T01，不自动越过家谱总览。
- G05 同一路由区分公开预览与成员视图。公开预览不得闪现成员隐私或管理入口；所有者和普通成员采用最小权限模型，最终权限以接口合同为准。
- G05 首屏按身份确认、来源确认、可信度确认三层组织信息；世系是次级入口，不自动抢占首次进入流程。
- G11 只维护当前可解释的名称、公开范围和访问说明；公开范围只有“仅成员可见”和“公开可申请”两个当前枚举，不虚构“转让管理员”等后端尚未确认的能力。G12 字辈保存必须保证代次连续；发现历史缺口时停止向后推导并要求明确处理，不能静默错位。
2.3 页面状态与请求结果
- 每个可请求页面至少判断正常、加载、空、失败、无权限和数据失效是否适用；表单另覆盖本地校验、提交中、成功、失败、取消和重复提交。
- 本地校验先于请求；字段错误就近展示。关联错误必须关联并聚焦到真正相关的字段，页面级或系统级错误在提交区或自定义结果弹窗中说明。
- 提交开始后锁定同一动作，避免重复写入；失败保留用户输入并提供明确重试；成功先完成必要数据刷新，再结束当前流程。
- 列表进入详情后返回，应恢复滚动位置、搜索词、筛选条件、展开分组、已加载页数和当前家谱选择；只有主动刷新、账号切换或原数据失效时才重置。
- 目标数据过期、权限变化、网络失败和取消不是空数据，必须分别呈现可理解的结果和下一步。
- 分页加载必须保留已有内容和滚动位置；失败显示就地重试，结束显示明确末尾状态，数据不足一页时不制造虚假“到底”文案，也不循环触发。
- 下拉刷新保留原列表，成功后只在确有变化时提示更新；失败在列表顶部提供重试，不把刷新和触底加载混成同一状态。
- 空态必须区分首次使用、搜索或筛选无结果、确实没有内容、加载失败和无权限；每种空态只突出一个主操作，最多一个次操作。
2.4 导航、弹层与流程终点
- 当前三个业务根页面是 G01“家谱”、F01“家族”和 M01“我的”，A01 是认证根页；书面栈语义已经在导航设计中收口，业务代码仍须按测试先行和 MuMu 矩阵实施验证。
- 返回、取消、完成和重复进入必须分别验证。页面完成后不得把已经结束的旧流程继续留在栈中，也不得用
navigateBack猜测一个可能不存在的返回目标。 - 普通底部弹层可由遮罩或 Android 返回键关闭；存在未保存输入时先确认是否放弃。确认弹窗的返回键等同取消；任何取消都不得被记录为成功。
- 弹窗高度只允许使用视口
max-height和内部滚动；普通页面内容高度由内容决定，不为单一设备压缩字号、行高或控件尺寸。 - 用户可见反馈使用项目自定义组件，不新增原生 UniApp Toast、Modal、Loading 或 ActionSheet 作为正式体验。
- 轻提示、底部弹层、居中确认、结果说明和危险操作按决策成本分级。不可逆操作必须说明后果并二次确认；普通操作不滥用确认。
- 产品合同已经定案为“邀请码直接加入且不生成审核记录”：只有邀请码校验成功才执行直接加入。M08 当前“邀请码加入后需要管理员审核”的旧文案属于待删除实现债务，导航任务 9 必须同步删除，不能保留审核与直接加入两套分支；邀请码校验和直接加入接口仍按对应业务阶段向后端核对。
2.5 三个根页面与主要流程
A01 登录／A04 注册
→ G01 我的家谱
→ 搜索或邀请码加入（G06 → G08 → G09 或 G01）
→ 创建家谱（G03 创建 → G03 录入始祖 → G05）
→ 家谱浏览与管理（G05 → T01／G10／G11／G12）
G01／G05
→ F01 家族内容
→ 动态、谱文、相册、人物、礼仪、备忘与功德
G01／M01
→ N01 消息中心
→ N02 消息详情
→ 对应业务目标
M01 我的
→ 资料、安全、帮助、反馈、推广、服务与关于
2.6 当前本地数据与路由参数边界
当前 52 条活动页面仍使用页面内本地状态、fixture 或 mock 数据；活动页面没有 appApi 消费者。utils/api.js 的存在不能被解释为已经接入真实接口。以下只记录页面源码当前主动读取的查询参数，供阶段 1 导航栈与接口审查核对；上游传入但页面未读取的参数属于待审债务，不能写成有效合同。
| 页面 | 当前主动读取的查询参数 |
|---|---|
| A01、A04、A05 | 无 |
| G01 | genealogyId、state |
| G03 | step、genealogyId |
| G05 | genealogyId、mode、role、state、genealogyName |
| G06 | mode、state |
| G08 | genealogyId、source、previous、state、genealogyName |
| G09 | state、status |
| G10 | genealogyId、state |
| G11 | genealogyId、state |
| G12 | genealogyId、startGeneration、currentGeneration、state |
| T01 | genealogyId、state、selectedId |
| T03 | genealogyId、personId、state |
| T04 | genealogyId、personId、mode、state |
| T05、T06 | genealogyId、personId、state |
| T07 | genealogyId、state |
| T08 | genealogyId、personId、state |
| F01 | genealogyId、state |
| F02 | state |
| F03 | feedId、commentResult、state |
| F04 | count、state |
| F05 | articleId、state |
| F06 | articleId、mode、state |
| F07 | count、state |
| F08、F09 | albumId、state |
| F10 | 无 |
| R01 | state |
| R02 | mode、personId、state |
| R03 | count、state |
| R04 | giftId、mode、saveResult、state |
| R05 | count、state |
| R06 | ritualId、state |
| R07 | ritualId、mode、saveResult |
| R08、R09 | personName、state |
| R10、R11 | state |
| N01 | genealogyId、state |
| N02 | id、state |
| M01 | state |
| M02—M08、M10 | 无 |
| M09 | state |
state、count、saveResult 等参数目前主要用于本地状态审查和压力测试，不代表后端请求字段。导航注册表已经决定删除 G03 的 step、G05/G08 的 genealogyName 和 G08 的 previous：页内步骤留在页面状态，名称按 genealogyId 从现有 fixture 或后续领域数据取得，来源只由真实栈与受验证 sourceKey 表达。其余参数仍须在对应业务阶段判断为真实输入、页内状态、领域数据或删除项，不得把调试参数固化成接口合同。
2.7 全局非功能门槛
- 默认字号和约
1.3倍系统字号下，超长谱名、生僻姓名、错误说明和主操作不得重叠或丢失关键含义。 - 主要触控目标不小于约
44dp；点击后100ms内出现反馈，预计超过300ms的操作显示明确加载状态。 - 长列表至少用
500条 mock 数据验证分批渲染、稳定 key、刷新、分页、末项可达和返回现场恢复。 - 同一详情连续进入和退出
20次，并快速切换根页面、重复开关弹层；不得出现白屏、串状态、重复堆栈、残留遮罩或逐次变慢。 - Android 性能以约
4GB内存的中低端设备为底线，验证启动、键盘、长列表、图片解码、页面切换和系统返回手势。 - 页面离开时清理本页创建的定时器、监听器、上传任务和动画状态；连续使用不得积累重复请求或实例。
- 当前尚未实施的五个独立阶段依次为：导航栈语义统一、T01 大规模世系树、短信验证码完整状态机、跨页面领域数据持久化、全局文字层级和无障碍第二轮。不得一次混合实施。
三、52 个活动页面映射
表中“返回或完成目标”描述业务意图，不表示现有导航 API 已经正确；导航栈阶段需要用源码扫描、测试和 MuMu 完整流程逐项验证。除 A04 和 T01 已形成专项证据外，其余接口列继续标记“待对应业务阶段 OpenAPI 审查”，避免把旧思维导图、页面 mock 或 PC 接口误当成 App 合同。
| 编号 | 页面 | 路由 | 当前业务目标 | 主要进入方式 | 返回或完成目标 | 必测状态 | 接口业务域 | 当前接口核对状态 |
|---|---|---|---|---|---|---|---|---|
| A01 | 登录 | pages/auth/a01-entry |
完成密码、短信或微信认证并处理协议 | APP 启动、凭证失效、主动退出 | 成功进入 G01；取消或失败留在本页 | 密码、短信、协议错误、发送中、倒计时、授权取消、登录失败、凭证过期 | 认证与账户 | 待对应业务阶段 OpenAPI 审查 |
| A04 | 注册账号 | pages/auth/a04-register |
建立新账号并确认协议 | A01 注册入口 | 成功建立登录态并进入 G01；取消返回 A01 | 本地校验、行为验证、注册中、手机号占用、成功、失败、取消 | 认证与账户 | 已核对注册成功响应为 LoginResult；行为验证与短信流程仍待审 |
| A05 | 重设密码 | pages/auth/a05-reset-password |
验证手机号并设置新密码 | A01 忘记密码 | 成功返回 A01 的密码登录态；取消返回 A01 | 验证码、行为验证、密码策略、不一致、提交中、成功、失败、取消 | 认证与账户 | 待对应业务阶段 OpenAPI 审查 |
| G01 | 我的家谱 | pages/genealogy/g01-my-genealogies |
选择全局家谱并完成加入或创建分流 | 登录成功、根 Tab、业务完成回流 | 进入 G03、G05、G06、G09、G10、G12、T01 或 N01 | 正常、空、加载、失败、审核中、被拒绝、退出或移除、待录入始祖、切换弹层 | 家谱与成员关系 | 待对应业务阶段 OpenAPI 审查 |
| G03 | 创建家谱 | pages/genealogy/g03-create-genealogy |
创建独立家谱并录入始祖 | G01 创建入口或待完善记录 | 创建后续接始祖步骤；始祖完成进入 G05；取消回来源 | 创建、重复提醒、创建失败、待完善、始祖校验、保存中、成功、中断恢复 | 家谱与成员关系 | 待对应业务阶段 OpenAPI 审查 |
| G05 | 家谱总览 | pages/genealogy/g05-genealogy-overview |
浏览家谱身份、来源和可信度并提供管理入口 | G01、G06 公开预览、G09 通过结果、G03 完成 | 返回 G01；进入 T01、G08、G10、G11、G12 或 F01 | 公开预览、成员视图、所有者、加载、空、失败、无权限、新建引导 | 家谱与权限 | 待对应业务阶段 OpenAPI 审查 |
| G06 | 加入家谱 | pages/genealogy/g06-search-genealogies |
通过搜索或邀请码准确定位目标家谱或支系 | G01 空态或添加家谱弹层 | 进入 G05 公开预览、G08、G09；已加入或我创建时回 G01 并选中 | 初始、搜索中、结果、无结果、邀请码无效或过期、失败、六种用户关系 | 家谱搜索与邀请 | 待对应业务阶段 OpenAPI 审查 |
| G08 | 关系确认与入谱 | pages/genealogy/g08-join-application |
填写真实姓名、关系和说明并提交申请或直接加入 | G06 选定目标、G05 公开预览、G09 重新提交 | 搜索来源成功进入 G09；邀请码成功回 G01 并选中新家谱 | 双来源、字段校验、提交中、成功、失败、重复提交、放弃填写 | 加入申请与邀请 | 待对应业务阶段 OpenAPI 审查 |
| G09 | 我的申请 | pages/genealogy/g09-my-applications |
查看、撤回或修改加入申请 | G01 申请分组、G08 搜索申请成功、G06 审核中或被拒绝状态 | 已通过进入 G05；修改进入 G08；撤回后保留明确结果 | 列表、空、失败、待审、通过、拒绝、撤回、重新提交 | 加入申请 | 待对应业务阶段 OpenAPI 审查 |
| G10 | 入谱审核 | pages/genealogy/g10-application-review |
所有者审核加入申请 | G01、G05 或 N01 审核消息 | 完成后刷新审核列表及来源计数；返回来源 | 列表、空、失败、通过确认、拒绝原因、提交中、无权限；拒绝字段使用 aria-invalid、aria-describedby、错误 role="alert" 并在空提交后聚焦 |
加入审核与权限 | 待对应业务阶段 OpenAPI 审查 |
| G11 | 家谱设置 | pages/genealogy/g11-genealogy-settings |
维护家谱名称、公开范围和访问说明 | G05 所有者管理入口 | 保存后刷新 G05；取消恢复原值并返回 | 加载、字段校验、保存中、成功、失败、无权限、未保存返回 | 家谱设置与权限 | 待对应业务阶段 OpenAPI 审查 |
| G12 | 字辈诗 | pages/genealogy/g12-generation-poems |
浏览与维护字辈序列 | G01 快捷入口或 G05 | 保存后刷新列表；取消返回来源 | 列表、空、编辑、校验、保存中、失败、无权限、长列表 | 字辈与权限 | 待对应业务阶段 OpenAPI 审查 |
| T01 | 世系树 | pages/tree/t01-tree-overview |
以当前成员为焦点阅读可扩展世系窗口，并在图、概览和线性列表间定位成员 | G01 快捷入口或 G05 | 返回来源；进入单实例 T03、T04、T06、T07 | 上二代/下二代初始窗口、搜索、四级 LOD、多配偶联合点、宽支系聚合、代际缺口、四类边界、图/列表、空、失败、版本冲突、500 节点性能；节点与线由同一 Canvas/矩阵/帧绘制 | 世系与成员 | 专项已核对：现有递归 LineagePersonTreeView 不满足；待后端按规范图窗口问题单更新 Apifox |
| T03 | 成员档案 | pages/tree/t03-member-profile |
在单个原生页面实例内查看成员资料、亲属与受控状态 | T01、T07、R02 的成员关联 | 页内成员轨迹优先返回；轨迹结束后回实际来源；进入 T05、T08 | A→B→C→B→A 页内轨迹、可编辑、隐私、无权限、成员缺失、加载失败、离世状态；读取成功后才推进轨迹 | 成员档案与权限 | 待对应业务阶段 OpenAPI 审查 |
| T04 | 新增亲属 | pages/tree/t04-add-relative |
录入首位成员或为目标成员新增亲属 | T01 指定节点或空树入口 | 保存后回 T01 并精确定位新建成员；取消回实际来源 | 首位成员、普通亲属、关系选择、必填、长摘要、保存中、成功、失败、放弃确认 | 成员与亲属关系 | 待对应业务阶段 OpenAPI 审查 |
| T05 | 编辑成员 | pages/tree/t05-edit-member |
修改指定成员身份和生平资料 | T03 编辑入口 | 保存后返回 T03 并刷新；取消回 T03 | 加载、字段校验、长简介、保存中、成功、失败、无权限、放弃确认 | 成员档案与权限 | 待对应业务阶段 OpenAPI 审查 |
| T06 | 编辑关系 | pages/tree/t06-edit-relationship |
校正两个现有成员之间的关系 | T01 关系操作 | 保存后返回 T01 并刷新关系；取消回来源 | 成员选择、校验、冲突、循环关系、冲突规则弹窗、保存中、失败、无权限 | 亲属关系与权限 | 待对应业务阶段 OpenAPI 审查 |
| T07 | 成员目录 | pages/tree/t07-member-directory |
搜索、筛选并选择家谱成员 | T01 成员目录入口 | 进入 T03；返回 T01 并恢复目录现场 | 完整列表、筛选、搜索无结果、明确空态、失败重试、加载、长列表、成员选择 | 成员查询 | 待对应业务阶段 OpenAPI 审查 |
| T08 | 成员状态 | pages/tree/t08-member-states |
解释成员隐私、纪念或无权限状态 | T03 人物状态入口 | 返回 T03；家谱不可用时回 G01 | 隐私隐藏、离世纪念、无权限、无效成员、权限变化 | 成员状态与权限 | 待对应业务阶段 OpenAPI 审查 |
| F01 | 家族动态 | pages/family/f01-family-feed |
展示家族动态并承载内容和档案入口 | 根 Tab 或 G05 | 进入 F02—F04、F07、F10、R01、R03、R05、R10、R11 | 加载、列表、空、失败、刷新、分页、无可用家谱 | 家族内容聚合 | 待对应业务阶段 OpenAPI 审查 |
| F02 | 发布动态 | pages/family/f02-publish-feed |
发布家族文字或媒体动态 | F01 发布入口 | 成功回 F01 并刷新；取消保留或确认放弃 | 表单、空内容校验、长内容、媒体权限、提交中、成功、失败、重复提交、取消 | 动态发布与上传 | 待对应业务阶段 OpenAPI 审查 |
| F03 | 动态详情 | pages/family/f03-feed-detail |
阅读动态并查看或提交评论 | F01 动态卡 | 返回 F01 并恢复现场 | 加载、正常、内容失效、失败、评论校验、提交失败、插入成功、无权限 | 动态与评论 | 待对应业务阶段 OpenAPI 审查 |
| F04 | 谱文列表 | pages/family/f04-article-list |
分类、搜索和浏览谱文 | F01 谱文入口 | 进入 F05 或 F06；返回 F01 | 加载、列表、分类、搜索无结果并重置、空、失败、长列表、新建 | 谱文 | 待对应业务阶段 OpenAPI 审查 |
| F05 | 谱文详情 | pages/family/f05-article-detail |
阅读、收藏和按权限编辑谱文 | F04 谱文卡 | 返回 F04；有权限进入 F06 | 加载、正常、收藏切换、编辑、失效、隐私、失败、无权限 | 谱文与权限 | 待对应业务阶段 OpenAPI 审查 |
| F06 | 编辑谱文 | pages/family/f06-article-editor |
新建或编辑谱文草稿 | F04 新建或 F05 编辑 | 保存或发布后回 F04/F05 并刷新；取消确认放弃 | 新建、编辑、校验、加载、草稿、保存中、失败保留并重试、成功回流、长正文 | 谱文编辑 | 待对应业务阶段 OpenAPI 审查 |
| F07 | 相册列表 | pages/family/f07-album-list |
浏览和创建家族相册 | F01 相册入口 | 进入 F08；返回 F01 | 加载、列表、长列表、空、失败、相册导航、创建弹窗、校验、插入和轻提示、权限 | 相册 | 待对应业务阶段 OpenAPI 审查 |
| F08 | 相册详情 | pages/family/f08-album-detail |
浏览照片墙和相册信息 | F07 相册卡 | 返回 F07；进入 F09 | 加载、照片墙、末张预览、Android 返回先关预览、空相册、相册失效、失败、权限 | 相册与媒体 | 待对应业务阶段 OpenAPI 审查 |
| F09 | 上传照片 | pages/family/f09-media-upload |
选择照片、填写逐张说明并上传 | F08 添加照片入口 | 成功回 F08 并刷新；取消确认放弃 | 初始、权限、最多九张、增删、当前照片独立说明、必填、上传锁定与进度、取消、失败重试、成功 | 媒体上传 | 待对应业务阶段 OpenAPI 审查 |
| F10 | 家族视频 | pages/family/f10-video-list |
说明当前视频服务尚未开放 | F01 视频入口 | 当前只返回 F01 | 待开放、返回 F01；未来列表、上传和接口状态只登记为对应业务阶段依赖，不冒充当前功能 | 视频服务 | 待对应业务阶段 OpenAPI 审查 |
| R01 | 人物录 | pages/records/r01-people-list |
搜索和浏览家族人物记录 | F01 人物录入口 | 进入 R02；返回 F01 | 加载、列表、搜索、无结果、空、失败、分页、新建权限 | 人物记录 | 待对应业务阶段 OpenAPI 审查 |
| R02 | 人物详情 | pages/records/r02-person-detail |
查看、新建或编辑人物记录 | R01 人物卡或新建入口 | 保存后回 R01 并刷新；进入 R08/R09；取消回来源 | 查看、新建、编辑、校验、保存中、成功、失败、隐私、失效 | 人物记录与权限 | 待对应业务阶段 OpenAPI 审查 |
| R03 | 贺礼簿 | pages/records/r03-gift-list |
浏览、筛选和新增贺礼记录 | F01 贺礼簿入口 | 进入 R04；返回 F01 | 加载、列表、空、失败、筛选、分页、新增权限 | 贺礼记录 | 待对应业务阶段 OpenAPI 审查 |
| R04 | 贺礼编辑 | pages/records/r04-gift-editor |
查看、新增、编辑或删除贺礼 | R03 记录或新增入口 | 保存或删除后回 R03 并刷新；取消回来源 | 查看、新增、编辑、校验、保存中、成功、失败、删除确认、无权限 | 贺礼记录与权限 | 待对应业务阶段 OpenAPI 审查 |
| R05 | 礼仪列表 | pages/records/r05-ritual-list |
浏览和创建家族礼仪活动 | F01 礼仪入口 | 进入 R06 或 R07；返回 F01 | 加载、列表、空、失败、活动状态、分页、新建权限 | 礼仪活动 | 待对应业务阶段 OpenAPI 审查 |
| R06 | 礼仪详情 | pages/records/r06-ritual-detail |
查看礼仪信息、参与者和状态 | R05 活动卡 | 返回 R05；有权限进入 R07 | 加载、详情、参与者、失败、失效、无权限 | 礼仪活动与参与 | 待对应业务阶段 OpenAPI 审查 |
| R07 | 礼仪编辑 | pages/records/r07-ritual-editor |
新建或编辑礼仪活动 | R05 新建或 R06 编辑 | 保存或删除后回 R05 并刷新；取消回来源 | 新建、编辑、校验、保存中、成功、失败、删除确认、无权限 | 礼仪活动与权限 | 待对应业务阶段 OpenAPI 审查 |
| R08 | 成长日志 | pages/records/r08-growth-journal |
展示人物成长时间轴并新增记录 | R02 或 T03 人物入口 | 保存后插入时间轴并给出轻提示；返回人物来源 | 加载、时间轴、空、失败、新增弹窗、必填、长文内部滚动、保存、权限 | 人物成长记录 | 待对应业务阶段 OpenAPI 审查 |
| R09 | 人生事 | pages/records/r09-life-events |
展示人物人生事件时间轴并新增记录 | R02 或 T03 人物入口 | 保存后插入时间轴并给出轻提示；返回人物来源 | 加载、时间轴、空、失败、新增、校验、保存、权限 | 人生事件 | 待对应业务阶段 OpenAPI 审查 |
| R10 | 家族备忘 | pages/records/r10-memo-list |
管理家族备忘和完成状态 | F01 备忘入口 | 新增或切换完成后刷新本页；返回 F01 | 加载、列表、空、失败、新增校验、完成、重新打开、重复操作、权限 | 家族备忘 | 待对应业务阶段 OpenAPI 审查 |
| R11 | 功德记录 | pages/records/r11-merit-records |
记录贡献并展示汇总 | F01 功德录入口 | 新增后实时刷新汇总和列表并给出轻提示；返回 F01 | 加载、汇总、列表、空、失败、新增、校验、保存中、权限 | 功德与贡献 | 待对应业务阶段 OpenAPI 审查 |
| N01 | 消息中心 | pages/notification/n01-message-center |
汇总消息、维护已读状态并分流业务 | G01 或 M01 消息入口 | 进入 N02 或对应 G10 等业务页面；返回来源 | 加载、未读、已读、全部已读、空、失败、审核消息、分页 | 消息与通知 | 待对应业务阶段 OpenAPI 审查 |
| N02 | 消息详情 | pages/notification/n02-message-detail |
展示消息正文并安全跳转到业务目标 | N01 消息卡 | 返回 N01；有效目标进入对应业务页 | 加载、详情、已读、失效消息、无目标、业务目标过期、失败 | 消息与业务分流 | 待对应业务阶段 OpenAPI 审查 |
| M01 | 我的 | pages/profile/m01-profile-home |
展示个人资料、提醒和服务导航 | 根 Tab | 进入 M02、M03、M06、M08、M09、M10 或 N01 | 加载、正常、失败、提醒、资料不完整、服务可用性 | 个人中心聚合 | 待对应业务阶段 OpenAPI 审查 |
| M02 | 个人资料 | pages/profile/m02-edit-profile |
查看并编辑头像和基础资料 | M01 资料入口 | 保存后回 M01 并刷新；取消回来源 | 加载、头像权限、字段校验、保存中、成功、失败、未保存返回 | 用户资料与上传 | 待对应业务阶段 OpenAPI 审查 |
| M03 | 账号与安全 | pages/profile/m03-security-settings |
汇总密码、手机号和设备安全入口 | M01 安全入口 | 进入 M04 或 M05；返回 M01 | 加载、正常、异常提醒、失败、设备状态 | 账号安全 | 待对应业务阶段 OpenAPI 审查 |
| M04 | 修改密码 | pages/profile/m04-change-password |
验证旧密码并设置新密码 | M03 密码入口 | 成功回 M03 或按安全合同重新登录；取消回 M03 | 旧密码错误、统一密码策略、新旧相同、不一致、提交中、成功、失败、重复提交 | 账号安全 | 待对应业务阶段 OpenAPI 审查 |
| M05 | 修改手机号 | pages/profile/m05-change-phone |
验证并更换绑定手机号 | M03 手机号入口 | 成功回 M03 并刷新；取消回 M03 | 当前身份校验、新号码、验证码、倒计时、号码占用、成功、失败 | 账号安全与短信 | 待对应业务阶段 OpenAPI 审查 |
| M06 | 帮助中心 | pages/profile/m06-help-center |
搜索和浏览帮助内容 | M01 帮助入口 | 返回 M01；无法解决时进入 M07 | 加载、分类、搜索、无结果、失败、内容失效 | 帮助内容 | 待对应业务阶段 OpenAPI 审查 |
| M07 | 意见反馈 | pages/profile/m07-feedback |
提交问题说明和联系信息 | M06 联系入口 | 成功给出明确结果后返回 M06或 M01；取消回来源 | 校验、附件权限、提交中、成功、失败、重复提交、取消 | 用户反馈与上传 | 待对应业务阶段 OpenAPI 审查 |
| M08 | 应用推广 | pages/profile/m08-promotion |
生成并分享家谱邀请信息 | M01 推广入口 | 分享成功、取消或失败均留有明确结果；返回 M01 | 邀请码、海报生成、系统分享权限、取消、失败、过期 | 邀请与系统分享 | 待对应业务阶段 OpenAPI 审查 |
| M09 | VIP 与订单 | pages/profile/m09-vip-orders |
展示服务权益和订单；当前明确未开放付费 | M01 服务入口 | 当前关闭说明并返回 M01；未来进入合规订单流程 | 待开放、无订单、订单列表、加载失败、支付取消、退款边界 | 服务权益、订单与支付 | 待对应业务阶段 OpenAPI 审查 |
| M10 | 关于家谱 | pages/profile/m10-about-settings |
展示版本、协议、隐私并处理退出登录 | M01 设置入口 | 协议关闭留在本页；退出成功清凭证并回 A01；取消留在本页 | 版本、协议、隐私、退出确认、取消、退出失败 | 配置、协议与认证 | 待对应业务阶段 OpenAPI 审查 |
四、封存与已移除页面
| 页面 | 当前决定 | 合同边界 |
|---|---|---|
| A02 账号登录 | 已完整并入 A01，不保留兼容路由 | 任何注册、重设或退出后的登录目标统一指向 A01 |
| A03 | 已移除 | 不恢复无明确业务职责的历史入口 |
| A06 登录状态 | 源码保留、活动路由封存 | 未来只有账号冻结、停用或风险限制等无法继续登录的阻断状态，且产品重新确认独立页面后才能恢复 |
| G02 | 并入 G01 空状态 | 搜索、邀请码加入和创建三个入口由 G01 空状态承载 |
| G04 | 并入 G03 始祖步骤 | 创建家谱与录入始祖属于同一可恢复流程 |
| G07 | 并入 G06 | 搜索、筛选、结果与无结果均由 G06 双模式承载 |
| T02 | 并入 T01 | 世系阅读提示、空态和失败态不再拆分独立路由 |
五、后续接口审查填充规则
每个对应业务阶段都必须先解析并比对两份 OpenAPI 导出，再按三人独立首审、交叉补漏、反向质询和共同收敛的顺序更新本文件。每个页面和用户操作都要补齐以下事实：
- 接口分类：App 可直接使用、PC 专用、App/PC 可能共用待确认、App 合同不完整、App 缺失、页面无合理用途或双方需重定义。
- 精确合同：路径、方法、鉴权、请求参数、字段类型、必填性、可空性、枚举、响应模型和错误码。
- 数据行为：分页、排序、筛选、上传、幂等、防重复提交、并发冲突、权限和数据副作用。
- 页面结果：成功、失败、取消、返回、完成、来源页刷新、重复进入和目标数据过期时的表现。
- 证据与状态：OpenAPI 位置、页面与代码位置、MuMu 操作步骤、三人结论、后端问题编号和关闭条件。
接口问题不能只写“缺接口”或“字段不够”。需要给后端的每一项都必须能够直接用于修改 Apifox，并明确验收步骤。后端更新后由用户重新导出 JSON 和 YAML，先通过语义一致性与差异合同，再允许页面接入。
5.1 已核对结论 API-A04-001
- 页面与动作：A04 提交注册并建立会话。
- 当前接口：
POST /genealogy/app/auth/register。 - 已确认响应：HTTP
200复用LoginResult，data引用LoginVo，可返回token/accessToken/tokenValue。 - 产品结论：取得并保存有效令牌后直接清理认证流程并进入 G01；不保留“注册成功后再登录”的并行终点。
- 尚未关闭范围：短信发送、行为验证、限流和验证码状态机不由本结论代替，按后续短信阶段单独审查。
5.2 后端问题单 API-T01-001
优先级： P0；现有 6 人默认数据已能出现确定性断线，当前合同也无法安全支持几十代、几百代。
受影响页面： T01 主页面，T03 定位，T04 新增亲属，T06 编辑关系，T07 搜索成员；G01/G05 只受入口与焦点参数影响。
当前接口与问题：
GET /genealogy/app/genealogies/{genealogyId}/lineage/tree只接受genealogyId，返回递归LineagePersonTreeView[]。- 递归
children/spouses与fatherId/motherId不能无歧义表达多个家庭联合点、单亲、收养、继亲、监护、主入边、窗口边界和树版本。 - 世系 ID 使用
integer/int64，超过 JavaScript 安全整数时会改变身份。 - 缺少世代×支系概览、人物定位、关系编辑和统一树版本并发合同。
要求后端在 Apifox 原子更新：
GET /genealogy/app/v2/genealogies/{genealogyId}/lineage/tree
GET /genealogy/app/v2/genealogies/{genealogyId}/lineage/tree/overview
GET /genealogy/app/v2/genealogies/{genealogyId}/lineage/persons/{personId}/locator
PATCH /genealogy/app/v2/genealogies/{genealogyId}/lineage/relationships/{relationshipId}
/lineage/tree查询参数固定为mode,focusPersonId,ancestorDepth,descendantDepth,boundaryId,cursor,limit,treeVersion，不接受branchId/generation。FOCUS 模式可省略焦点，但非空焦点只能是 VISIBLE 稳定人物 ID；REDACTED、不可见、过期或不存在的焦点统一返回404 LINEAGE_FOCUS_NOT_AVAILABLE。深度为 0—20 的整数且默认上二代/下二代；BOUNDARY 模式必须同时提供boundaryId/cursor/treeVersion且不得带焦点或深度；limit为最小 1、默认 200、最大 500，非法组合返回422 LINEAGE_QUERY_INVALID。- 响应唯一根模型：
LineageGraphWindow，必含version,state,genealogyId,nodes,familyUnits,edges,window；版本字段固定为schemaVersion,treeVersion,generatedAt，state以EMPTY/POPULATED为 discriminator 使用oneOf。EMPTY 精确要求空 nodes/familyUnits/edges、空entryPersonIds、空 boundaries、focusPersonId=null、generationRange=null、returnedNodeCount=0；POPULATED 要求非空 nodes、引用其中 VISIBLE 节点的焦点、有效入口、非空代际范围，并满足returnedNodeCount === nodes.length。 entryPersonIds精确等于当前窗口无 primary 入边的节点集合，secondary 入边不取消入口身份；入口人物entryReason为GENEALOGY_ROOT/WINDOW_CUT/DISCONNECTED_COMPONENT且恰有零条 primary 入边，非入口entryReason=null且恰有一条 primary 入边。全谱根只由 overview 的可见根/隐私根计数与 locator 的根可见性分支表达；旧rootPersonIds/rootReason不再属于窗口合同。- Node 以
visibility为 discriminator 使用oneOf。VISIBLE 精确包含可见身份字段，稳定人物 ID 不得以redacted:开头，sex固定为MALE/FEMALE/UNKNOWN；REDACTED 只允许id,generation,displayName,order,visibility,entryReason，名称固定为“隐私成员”，opaque ID 精确使用redacted:{treeVersion}:{token}并仅在该版本内作当前图内部引用，不得进入 FOCUS、locator、搜索、写接口或任何focusPersonId/targetPersonId，也不得泄漏头像、性别或支系字段。 FamilyUnit必含id,anchorPersonId,partnerRelationship,partners,order；一个单亲成员或一对伴侣组成一个家庭单元。partnerRole只允许ANCHOR/PARTNER；双人关系对象包含稳定relationshipId、relationshipKind=PARTNER、relationType、status，伴侣relationType为MARRIAGE/PARTNERSHIP/UNKNOWN、status为ACTIVE/ENDED/UNKNOWN，单亲为null，多配偶拆为不同家庭单元。ParentChildEdge必含id,familyUnitId,childId,lineageParentId,parentRelations,primary,order；每项父母关系包含稳定relationshipId,relationshipKind=PARENT_CHILD,personId,parentRole,relationType。parentRole为FATHER/MOTHER/PARENT/GUARDIAN/UNKNOWN，relationType为BIOLOGICAL/ADOPTIVE/STEP/GUARDIAN/UNKNOWN；所有父子关系都检查循环，不能只校验 primary。- boundary 必含稳定 ID、锚点、方向、原因、隐藏数量和 cursor；WINDOW 锚点的
anchorId=null，其他锚点引用对应实体；hiddenCount为非负整数或null，cursor 只在 UNLOADED 时非空。窗口内匿名人用Node.visibility=REDACTED，窗口外隐藏拓扑用 boundary REDACTED，同一对象不得重复表达；运行时网络 FAILED 不写进后端枚举。 - 所有实体、关系和引用 ID 使用非空字符串；
avatarOssId只允许非空字符串或null。 - cursor 绑定
genealogyId/treeVersion/boundaryId；版本变化返回 HTTP409和TREE_VERSION_CHANGED。 - overview 只接受必填
treeVersion，版本变化返回409 TREE_VERSION_CHANGED；响应以state=EMPTY/POPULATED使用oneOf。EMPTY 精确为genealogyPersonCount=0、genealogyRootPersonIds=[]、redactedGenealogyRootCount=0、generationRange=null、buckets=[]；POPULATED 要求正数总量、非空范围和 buckets，并满足可见根数加隐私根数至少为 1、全部 bucket 三类计数之和等于总量。可见根与 bucketfocusPersonId只能使用 VISIBLE 稳定 ID，隐私根只计数不返回 opaque ID。locator 将rootVisibility=VISIBLE/REDACTED与pathCompleteness=COMPLETE/REDACTED_GAPS独立建模；ancestorPathSegments用 VISIBLE 人物 ID 段与不含 ID 的 REDACTED gap 段表达任意中间隐私，支持可见根但中间祖先隐藏，任何路径都不得包含 opaque ID。 - 世系写接口携带
If-Match，成功返回新treeVersion以及受影响人员、家庭和关系 ID；关系 PATCH 以不可变relationshipKind为 discriminator 使用oneOf，PARTNER 只更新relationType/status，PARENT_CHILD 只更新relationType/parentRole。每个分支至少提交一个可修改字段，省略字段保持原值；只有relationshipKind的空更新返回422 RELATIONSHIP_PATCH_EMPTY，不得偷换参与人。 - 客户端 Scene 根固定为
{ sceneVersion, treeVersion, focusPersonId, bounds, items }；utils/lineage/scene.js唯一生成sceneVersion，缺失版本或相同版本对应不同 payload 均拒绝原子替换。瞬时selectedId不进入 Scene 或版本摘要，renderjs 只用它在同一 Canvas 动态重绘光晕。 - OpenAPI 必须列出
400/401/403/404/422/429/5xx、409、字符串 ID、nullable 头像和additionalProperties: false。 - 旧 v1 树路径保持原合同；App 只实现上述四条固定
/genealogy/app/v2/...路径，不双读、不运行时探测版本。
关闭条件： 用户从更新后的 Apifox 重新导出 JSON/YAML；两份文件同时通过 tests/lineage-openapi-contract.ps1；三人逐字段复核后，客户端才能开始规范化、布局和 Canvas 实施。
当前其余已知但尚未核实的重点依赖包括：微信登录、公共行为验证、完整短信状态机、邀请码验证与直接加入、结构化亲属关系、上级家谱与支系权限、管理员授权与功能开关、上传与系统权限、消息业务目标、系统分享、订单支付与退款。它们只表示审查重点，不预判后端一定缺失。