rain
283 lines
41 KiB
Markdown
283 lines
41 KiB
Markdown
# 接口与页面映射总表
|
||
|
||
> 更新日期：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 三个根页面与主要流程
|
||
|
||
```text
|
||
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 导出，再按三人独立首审、交叉补漏、反向质询和共同收敛的顺序更新本文件。每个页面和用户操作都要补齐以下事实：
|
||
|
||
1. 接口分类：App 可直接使用、PC 专用、App/PC 可能共用待确认、App 合同不完整、App 缺失、页面无合理用途或双方需重定义。
|
||
2. 精确合同：路径、方法、鉴权、请求参数、字段类型、必填性、可空性、枚举、响应模型和错误码。
|
||
3. 数据行为：分页、排序、筛选、上传、幂等、防重复提交、并发冲突、权限和数据副作用。
|
||
4. 页面结果：成功、失败、取消、返回、完成、来源页刷新、重复进入和目标数据过期时的表现。
|
||
5. 证据与状态：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 原子更新：**
|
||
|
||
```http
|
||
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`；版本变化返回 HTTP `409` 和 `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 三类计数之和等于总量。可见根与 bucket `focusPersonId` 只能使用 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 实施。
|
||
|
||
当前其余已知但尚未核实的重点依赖包括：微信登录、公共行为验证、完整短信状态机、邀请码验证与直接加入、结构化亲属关系、上级家谱与支系权限、管理员授权与功能开关、上传与系统权限、消息业务目标、系统分享、订单支付与退款。它们只表示审查重点，不预判后端一定缺失。
|