344 lines
45 KiB
Markdown
344 lines
45 KiB
Markdown
# 家谱 APP 页面样式验收规划
|
||
|
||
> 更新日期：2026-07-20
|
||
> 适用范围：Android `uni-app` 用户端
|
||
> 当前实现：`pages.json` 已收敛为 52 条活动路由；A02 已并入 A01，A06 已从活动路由与验收队列封存。历史上的 7 个验收结果仅作为旧视觉证据，不计入本轮完成状态。
|
||
> 本文件只管理逐页视觉、页面状态外观、弹窗与加载样式、手机适配和表现质量；不替代 `docs/规划.md` 对项目范围和最终路由的管理，也不承担接口与业务功能验收。功能验收规则后续单独编写。
|
||
|
||
## 1. 标记与审核规则
|
||
|
||
| 标记 | 含义 |
|
||
| --- | --- |
|
||
| `[ ]` | 尚未设计或尚未开始全局验收项 |
|
||
| `[~]` | 页面候选已实现，等待用户按本文件逐项审核 |
|
||
| `[x]` | 用户已明确完成基础页面样式验收；可见效果冻结，不代表接口或业务功能通过 |
|
||
| `[!]` | 用户要求返工；只修改该项涉及的页面、组件、资产、测试和证据 |
|
||
| `⚠` | 当前没有真实可达入口或存在明显流程断点，不能用直接路由冒充流程通过 |
|
||
|
||
### 2026-07-20 夜间批量收敛说明
|
||
|
||
- 用户已明确授权：T01 留待次日人工审核，其余未验收页面不再逐页提问，统一按 G01、T07、F01、R01、N01、M01 六个已确认基准推进。
|
||
- 本轮已将 F/R/N/M 的 28 个普通任务页统一到各自模块母版，删除重复的页面编号介绍块；表单、列表、详情、时间轴、设置和状态页仍保留不同业务结构。
|
||
- F02、T03—T06、T08、G03、G08—G12 已移除跨模块旧不透明业务面板引用，改用所属模块或 G01/T07 基准的真实透明资产。
|
||
- T01 已形成纵向世系轴候选：始祖在上、后代向下分代、同代横向扩展、关系线连续、节点可选择、底部人物信息栏独立。
|
||
- 52 条活动路由及 2 个共享组件已通过 5173 Vite 逐文件转换（54/54）；68 项 PowerShell 静态测试中 66 项通过。剩余 2 项为已知仓库治理项：旧基础资产命名审计和历史截图数量上限。
|
||
- 当前 Chrome 项目页仍连接 5173，但没有开放 9222 调试端口；为避免违反“不得新开第二个浏览器或第二个项目标签页”，本轮未伪造 CDP 运行截图、四档响应式和交互 smoke 证据。除用户已明确通过的基准页外，其余页面继续保持 `[~]`，明早人工复核后再决定是否标 `[x]`。
|
||
|
||
页面只有同时满足以下条件才能从 `[~]` 改为 `[x]`：
|
||
|
||
1. 页面在真实运行环境中打开；流程页优先从上游可见入口进入，尚未实现入口时明确标记 `⚠`，不能冒充流程设计完整。
|
||
2. 正常、加载、空、失败、权限、校验和成功等适用状态的视觉呈现均已检查；本阶段只验状态外观，不验证后台结果真伪。
|
||
3. 基础版本只验收当前浅色国风主题，并在 320×568、360×640、360×800、412×915 四个尺寸确认无溢出、裁切、遮挡或错位；深色与跟随系统整体延期到下一版本，不作为本轮 52 页通过条件。
|
||
|
||
G01 公共背景在上述四档验收尺寸之外，额外增加 `412×1000` 超高屏压力测试，用于确认 `1440×3600` 连续长图固定贴底时整屏覆盖、下方列表叠放和横向宽度仍然稳定；该压力尺寸不替代四档基础合同，也不扩大其他 51 个页面的当前验收门槛。
|
||
4. 默认系统字号和约 1.3 倍系统字号均可完整操作；关键按钮、表单错误、姓名、关系和操作结果不得截断，空间不足时允许合理换行或滚动，不得强行缩小文字或遮挡主操作，并使用超长族谱名、生僻姓名完成边界检查。
|
||
5. 状态栏、底部手势区、软键盘、系统返回和长文本不会破坏页面。
|
||
6. 点击反馈、加载、滚动、动画和图片解码在当前静态／Mock 数据下无明显卡顿。
|
||
7. 完成页面样式契约、运行时 smoke、真实运行截图复核和 `git diff --check`；不以接口测试作为本阶段通过条件。
|
||
8. 用户明确确认通过；内部测试或 Product Design 审视不能替代用户确认。
|
||
9. 当前页面涉及的源码通过“工程质量底线”检查；即使真实截图视觉合格，只要存在大段复制样式、难以理解的堆叠逻辑、关键处理缺少中文说明、明显性能隐患或不可维护实现，仍必须标记 `[!]` 返工，不得标记 `[x]`。
|
||
|
||
一个页面编号仍只计算一个验收项，但必须在页面下记录正常态、空态、加载态、失败态、权限态和业务状态等适用视觉子项。全部必测视觉子项通过后，页面才能标记 `[x]`；不为同一路由的不同状态重复增加页面编号。复杂页面用一张联系表展示状态证据。
|
||
|
||
标记 `⚠` 的页面必须执行“真实入口优先”：审核到其上游页面时，先确认入口的目标用户、所在位置、显示条件和不可用状态，再从真实可见入口进入下游页面审核。开发者直达路由只允许用于内部排错，不得作为流程完整或页面可达的验收证据。受权限控制的入口对无权用户应隐藏，同时仍须通过受控状态单独审核下游无权限画面。
|
||
|
||
页面标记 `[x]` 后立即进入视觉冻结：不得在后续页面实施中顺手修改。公共弹窗、导航、字体、色彩、间距、圆角、加载组件或设计变量发生变更前，必须列出全部受影响的冻结页面并执行四档尺寸检查和真实运行截图回归；确认没有视觉变化时保留 `[x]`，发生任何可见变化时自动退回 `[~]` 等待用户复核。紧急缺陷允许解除冻结，但必须记录修改原因、影响范围和新的运行证据，复核通过后重新冻结。
|
||
|
||
接口尚未提供不阻止基础页面样式标记 `[x]`。微信登录、行为验证、邀请码、真实审核、上传、支付、权限控制和数据提交均留到后续功能验收；当前可以审核其入口、容器、加载、成功、失败和禁用状态是否好看，但不得把静态／Mock 画面描述为功能已通过。
|
||
|
||
本轮不沿用任何页面的历史完成标记。A01、A04、A05、G01、G03 也必须重新完成页面结构、视觉状态、兼容性、弹窗加载样式和表现质量检查；用户重新确认后才能标记 `[x]`。A06 已封存，不参与本轮活动页面统计。
|
||
|
||
审核证据默认每页只展示一张 360×800 代表图；复杂状态合成一张联系表，不连续展示多张前后对比图。其余尺寸在内部完成检查，只有发现问题或用户要求时才展开。
|
||
|
||
基础版本的每个页面只按当前浅色国风主题完成适用关键状态、四档尺寸、代码质量和性能验收；用户确认后标记 `[x]` 并冻结。下一版本引入深色与跟随系统时，属于会影响全部冻结页面的全局视觉变更，必须单独建立升级验收计划，并按冻结回归规则重新复核受影响页面。
|
||
|
||
## 2. 已确认的核心用户流程合同
|
||
|
||
本章用于决定页面应该展示什么、入口放在哪里以及不同状态如何变化，是页面样式设计的上下文；不表示相关接口和业务功能已实现或已验收。
|
||
|
||
### 2.1 账户前置与登录后落点
|
||
|
||
- APP 不设游客模式；启动入口为登录页，所有家谱搜索、加入、创建、浏览和管理操作都必须建立在已有账户和有效登录状态上。
|
||
- A01 是认证流程唯一登录页，保留品牌视觉并合入原 A02 的密码登录、短信登录、注册、忘记密码和协议入口；微信登录继续保留并登记为后续接口依赖。
|
||
- A01 首次安装默认展示密码登录；用户主动切换密码／短信方式后，本机只记录上次选择的登录方式，下次打开恢复该方式。不得保存密码；手机号只允许按后续隐私与安全规则合规保存或脱敏展示。微信登录始终保持为独立入口，不参与密码／短信方式记忆。
|
||
- A04 注册成功后直接建立登录状态并进入 G01“我的家谱”，不得要求用户返回 A01 重复输入账号密码；注册接口能否返回有效登录凭证在后续功能验收核对，当前页面样式验收先覆盖提交中、成功过渡和进入 G01 的视觉连续性。
|
||
- A05 重置密码成功后不自动登录：先显示短暂的自定义成功结果，再返回 A01，自动保留刚才使用的手机号、切换到密码登录并聚焦密码框，让用户使用新密码完成登录；不得清空手机号或要求重新寻找登录方式。
|
||
- A01 内部直接处理密码错误、验证码错误和手机号未注册，使用就近校验；微信授权取消仍留在 A01，视为用户取消而非登录失败。A06 已封存，不再作为当前登录结果入口。若未来恢复，只承接账号冻结、停用、风险限制或其他无法继续登录的阻断性状态，必须说明原因、影响范围和明确恢复入口，不得成为普通错误的汇总页。
|
||
- A01 在 320×568 最小验收尺寸下允许自然纵向滚动，不为追求全部核心入口同屏而压缩品牌头、表单、字号或有效触控区；必须保证首屏层级清楚、滚动顺畅、无横向溢出，底部协议和主操作可完整滚动到达。
|
||
- A01 未勾选协议时采用页内校验：协议区域轻微震动并高亮，下方显示明确错误文案；不弹原生 Toast 或确认弹窗，不跳转。用户勾选后错误样式立即消失。
|
||
- A02 从最终路由和验收表移除，不保留兼容入口；A04、A05 的登录返回统一指向 A01。A06 源码仍保留返回 A01 的逻辑，但已从 `pages.json` 和活动验收表移除。
|
||
- A01、A04、A05 后续接入同一真实滑动验证组件，但触发时机不同。A01 登录在账号信息、协议等本地校验通过并点击“登录”后触发，验证成功后自动继续登录；A05 忘记密码在用户请求发送短信验证码前触发，验证成功后自动发送短信，重置提交时不重复验证。A04 注册当前因短信注册接口尚未提供，临时按 A01 方式在完整填写并点击“注册”后触发；注册短信接口提供即为临时契约的移除条件，届时必须迁移为“发送短信验证码前验证”，并删除注册提交前的旧触发路径，不保留双重验证。用户关闭或验证失败时必须保留原表单内容。2026-07-16 用户决定滑块、轨道、拼图及成功／失败等内部视觉采用接入组件的自带样式，延期到接口阶段结合真实组件审核；当前卷轴验证弹窗仅为流程占位，不作为最终视觉或用户验收证据。原始 TAC 运行库保存在 `static/vendor/tac/`，留待功能阶段使用。
|
||
- 短信验证码按钮只设计两种稳定状态：“获取验证码”和“Ns 后重试”倒计时。发送请求期间仅在原按钮内部显示短暂进度并阻止重复点击，不新增独立按钮形态；发送失败立即恢复可发送状态并在按钮附近就近说明原因；频繁限制有明确剩余秒数时进入倒计时，没有剩余秒数时保持可发送并显示限制说明。倒计时的真实到期时间、前后台恢复和接口限流结果归入后续功能验收。
|
||
- 登录成功后统一进入 G01“我的家谱”，不直接跳入上次浏览的家谱。
|
||
- APP 启动时按登录状态分流：首次打开或没有有效凭证进入 A01；已登录且凭证有效时直接进入 G01，不重复显示登录页；凭证过期时先回到 A01，再显示项目自定义单按钮信息对话框，标题“登录状态已过期”，正文“为保障账号安全，请重新登录”，按钮“重新登录”，点击后关闭并聚焦登录表单，不使用 Toast 或原生 `uni.showModal`；主动退出登录后清除登录凭证，但可保留用户上次选择的密码／短信登录方式。凭证有效性、过期检测和启动恢复归入后续功能验收。
|
||
- G01 没有任何家谱和申请记录时，使用同页空状态提供“搜索家谱、邀请码加入、创建家谱”三个入口，不新增独立引导页。
|
||
- G01 空状态的三个入口不做等权堆叠：“搜索家谱”作为主入口，优先引导用户确认家族是否已有家谱；“邀请码加入”作为快捷入口；“创建家谱”作为次入口，并提示“确认没有现有家谱后再创建”，降低重复建谱风险。三个入口始终同时可见，不因视觉降级删除创建能力。
|
||
- 一个账号允许加入或创建多个家谱。
|
||
|
||
### 2.2 G01 我的家谱状态合同
|
||
|
||
- 列表固定分为“我创建的”“我加入的”“加入申请”三组；审核中和被拒绝记录放在“加入申请”中，但仍可点击并切换顶部状态区。
|
||
- 顶部大卡片是“当前选中家谱／申请”的状态展示区；点击下方列表卡片只切换当前项，不直接进入详情。
|
||
- 已加入或我创建：顶部展示家谱信息和快捷入口；点击顶部大卡片进入 G05 家谱总览。
|
||
- 审核中：顶部快捷入口替换为审核进度和“撤回申请”，顶部大卡片不可进入家谱。
|
||
- 被拒绝：顶部快捷入口替换为拒绝原因和“修改申请并重新提交”，顶部大卡片进入申请修改，不进入家谱总览。
|
||
- 已退出或被移除：顶部展示状态原因和“重新申请加入”，不允许访问原家谱内容。
|
||
- 默认选择顺序为：恢复本机保存的上次选择；记录无效时选择第一个可操作家谱；没有可操作家谱时选择列表第一项。上次选择只保存家谱／申请 ID，不依赖新增后台接口。
|
||
- G01 顶部当前选中的“可用家谱”同时作为全局家谱上下文；家族、世系、成员、家谱设置等家谱相关页面顶部必须明确显示当前谱名。用户在 G01 切换可用家谱后，其他业务 Tab 同步使用新上下文。审核中、被拒绝、已退出／移除或待录入始祖的记录仍可作为 G01 顶部展示项，但不得覆盖最近一个可用家谱的全局上下文；没有任何可用家谱时，家谱相关 Tab 显示引导状态并返回 G01 搜索、邀请码加入或创建，严禁展示上一个已失效家谱的缓存内容。
|
||
- 非空列表末尾保留“添加家谱”功能卡；点击后使用自定义底部弹层展示“搜索家谱、邀请码加入、创建家谱”。
|
||
|
||
### 2.3 加入与创建分流
|
||
|
||
- G06 统一命名为“加入家谱”，使用“搜索家谱／邀请码加入”双模式定位目标家谱。
|
||
- G06 搜索结果必须帮助用户区分同名家谱、大家族与下属小家族／支系：结果卡至少展示谱名、姓氏、地区、堂号、所属上级谱、当前支系、管理者或认证信息、成员规模和最近更新时间。用户只申请当前明确选中的家谱或支系；在接口没有明确父子成员继承规则前，不得用文案、勾选状态或成功结果暗示加入小家谱会自动获得上级大家谱身份。
|
||
- G06 结果卡按当前用户关系展示唯一操作：未加入显示“申请加入”；已加入显示“已加入”，点击后返回 G01 并选中该家谱；审核中显示“审核中”，点击进入 G09 查看进度；曾被拒绝显示“修改后重新申请”；已退出或被移除显示“重新申请”，进入表单前说明原状态；当前用户创建的家谱显示“我创建的”，点击后返回 G01 并选中。任何状态都不得再次创建重复申请或把状态按钮做成含义不明的“进入”。
|
||
- 未加入用户点击 G06 结果卡时复用 G05 的“公开预览”状态，不新增路由：只展示家谱身份、来源简介、地区、堂号、支系和公开说明，隐藏成员隐私、世系详情及全部管理入口，底部固定“申请加入”。已加入成员进入同一 G05 时再展示成员可见内容；公开字段范围最终以接口权限规则为准。
|
||
- 搜索模式通过地区筛选和谱名搜索定位家谱；邀请码模式验证邀请码后定位家谱。两种模式都进入 G08 填写真实姓名和亲属关系。
|
||
- G08 当前申请字段以现有可解释契约为准：`realName` 真实姓名必填；`relation` 与家谱关系必填，采用文字输入并提示“请以家谱中一位已知长辈为参照，例如：汤正华堂侄”；`message` 申请说明用于补充祖居地、长辈姓名等核验信息。现有接口没有参照成员 ID、推荐人或结构化关系字段，当前不得虚构关系树选择器；接口提供相关字段后，必须以新结构化契约替换文字关系旧路径并同步更新校验、页面和测试。
|
||
- G08 是同一路由的双来源状态。搜索来源显示“申请说明”，主按钮为“提交申请”，成功后进入 G09 查看审核进度；邀请码来源仍要求真实姓名和关系，将第三字段改为可选的“补充信息”，主按钮为“确认加入”，并明确提示“提交后直接加入，无需等待审核”，成功后返回 G01、刷新列表并选中新加入的家谱。两种来源共用结构与视觉组件，但标题、说明、按钮、成功结果和下一步必须匹配当前状态，不得混用“申请”与“直接加入”语义。
|
||
- 搜索来源的 G08 提交后进入管理员审核，记录在 G01“加入申请”和 G09“我的申请”中。
|
||
- 邀请码来源的 G08 提交后直接加入，不进入审核记录；成功后返回 G01、刷新列表并选中新加入的家谱。
|
||
- 当前 OpenAPI 尚未提供邀请码验证和直接加入接口；本轮只审核相关入口和页面状态外观，不伪造接口已通过，不在 UI 验收阶段对接接口。
|
||
- 创建家谱不需要平台审核：G03 创建成功后直接成为创建者，继续录入首代；始祖保存完成后必须进入 G05 家谱总览，不得沿用当前直接跳入 T01 世系树的旧路径。G05 对新建家谱显示“家谱已创建，可继续完善世系”的引导卡，用户主动点击后再进入 T01。
|
||
- 当前 G03 仅创建独立家谱。现有契约只有姓氏、谱名、堂号、所在地和访问规则，没有上级家谱 ID、独立／支系类型或支系管理权限；因此页面不得展示无法提交的“创建下属支系”。进入创建前及填写姓氏、地区、谱名后，应提示用户先搜索可能已有的家谱，减少重复建谱。“在大家谱下创建支系”登记为产品／接口依赖，待上级家谱字段和权限规则明确后再设计并接入。
|
||
- 家谱记录已创建但始祖尚未录入时，G01“我创建的”必须保留该记录并标记“待录入始祖”，不得静默丢失或再次创建；该记录参与顶部当前项选择，但顶部主操作只能显示“继续完善”，点击恢复 G03 始祖步骤。始祖完成前不进入正式 G05，也不开放世系与管理入口；保存成功后状态转为正常并进入 G05。中断恢复、重复创建防护和真实状态持久化归入后续功能验收，当前先审核相关页面状态外观。
|
||
|
||
### 2.4 G05 家谱总览与权限
|
||
|
||
- G05 首要任务是浏览和确认家谱信息，世系图属于次级入口，不占据首屏最强视觉位置。
|
||
- 新建家谱首次进入 G05 时显示一次“家谱已创建，可继续完善世系”的引导卡；卡片提供进入 T01 的明确操作，但不得自动跳转。引导关闭或完成后不持续占据首屏主位，后续仍从常规次级入口进入世系树。
|
||
- G05 同一路由包含未加入用户的公开预览态和已加入成员的完整浏览态；两种状态必须使用明确身份标签和不同操作区，禁止把隐藏内容留出空白占位，也禁止在公开态短暂闪现成员数据后再隐藏。
|
||
- 首屏必须完整呈现三层信息：身份确认（谱名、姓氏、地区、堂号／支系）；来源确认（始祖、祖籍或迁徙来源）；可信度确认（家谱简介、成员规模、最近更新时间）。
|
||
- 当前接口只明确家谱所有者和普通成员能力，未定义管理员授权、成员功能开关或权限清单。本轮采用最小权限模型：所有者显示管理入口；普通成员只显示浏览和本人相关入口，管理操作直接隐藏。
|
||
- 即使入口已隐藏，接口返回无权限时仍显示自定义无权限页面状态，不使用原生提示。
|
||
- 管理员授权和功能开关登记为产品／接口依赖，不自行虚构授权页面。
|
||
|
||
## 3. 用户身份与非理想操作
|
||
|
||
审核不能只走理想路径，至少覆盖以下身份和行为：
|
||
|
||
- 未登录／首次打开 APP 的用户；除认证、注册、协议和找回密码外不能进入业务页面。
|
||
- 新注册且没有家谱的用户。
|
||
- 创建家谱后的谱主／管理员。
|
||
- 搜索家谱并申请加入的普通用户。
|
||
- 已加入家谱的普通成员。
|
||
- 回访用户、资料不完整用户、无权限用户和账号异常用户。
|
||
- 未勾选协议、漏填、填错、长文本、重复点击、快速返回、切换 Tab、网络失败、空数据、权限拒绝、上传取消和操作中断。
|
||
|
||
## 4. 全局视觉、适配与表现质量验收项
|
||
|
||
所有用户可见提示必须使用项目自定义组件。禁止直接展示 `uni.showToast`、`uni.showModal`、`uni.showLoading`、`uni.showActionSheet` 等原生 UniApp 样式。当前代码中共有 40 处原生提示调用：37 处 `uni.showToast`、3 处 `uni.showModal`，均纳入后续替换范围。
|
||
|
||
弹窗、卡片、按钮和装饰面继续遵守完整位图规则：完整视觉面由独立不透明位图承载，透明 PNG 只作叠加装饰；CSS 只负责布局、文字、遮罩、状态和轻量动效。
|
||
|
||
G01、G03、G05、G06、G08、G09、G10、G11、G12 共 9 个活动 G 页面统一使用用户选定的“旗舰长屏连续云竹亭台宣纸景”公共背景。背景由 `GenealogyPageBackground.vue` 单一维护，运行图为 `1440×3600`，按页面宽度等比完整显示并固定贴底，左右不裁剪、不变形；顶部疏竹淡云属于短屏安全裁切区，高屏不再使用纯色区拼接。用户查看多档 H5 对比后确认共享图片画层使用 `opacity: 0.28`，宣纸底色、标题栏、卡片、文字、按钮和底栏保持原有不透明度。旧 A/B/C 母版和旧 C 运行图保留为历史输入／输出，不再作为当前页面入口。该公共决定不等于任一页面已经验收，各页仍需按真实状态和四档尺寸分别审核；Android/HBuilderX 与 4GB Android 图片解码、切页和回收仍待复核。
|
||
|
||
所有表单采用“就近显示错误”：单字段错误显示在对应输入框下；关联错误同时标记相关字段；页面级错误显示在提交区附近；网络或系统错误使用自定义结果弹层。提交时错误字段执行一次 200–260ms、3–5px 的横向视觉抖动，只使用 `transform`，不调用手机振动、不循环闪烁；动画必须与静态错误描边和文字同时存在，减少动态效果时仅保留静态提示。
|
||
|
||
基础版本固定使用当前浅色国风主题，M10“设置与关于”不展示尚未生效的外观模式入口，也不实现主题切换、持久化或跟随系统。深色与跟随系统统一延期到下一版本；升级时继续使用统一主题变量管理背景、文字、边框、遮罩、状态色、状态栏图标和必要位图资产，禁止依赖系统自动反色或在页面内散落覆盖样式。下一版本的主题切换、过渡、持久化和系统联动必须另建产品合同与验收计划。
|
||
|
||
所有分页列表共用同一套底部加载视觉：接近列表末尾时在内容流内显示轻量水墨／印章动效和“正在展开更多……”；失败时保留已加载内容并显示“加载失败，点击重试”；数据结束时显示“已阅至末尾”；数据不足一页时不强行显示结束文案，也不循环触发加载。底部分页不得使用全屏遮罩、清空现有列表、改变当前滚动位置或造成列表跳动。
|
||
|
||
所有需要获取最新状态的列表页共用下拉刷新视觉，并与底部触底加载明确区分：下拉过程使用短促的水墨聚合／印章落定动效；刷新期间保留原列表，不白屏、不清空内容、不跳动；有新内容时使用自定义轻提示“内容已更新”，内容无变化时安静收起；失败时保留原内容并在列表顶部显示可重试提示。纯静态说明页和不具备刷新语义的短内容不强行加入下拉刷新。
|
||
|
||
所有弹窗按用户决策成本统一分为四级：轻提示用于普通提醒和操作成功，短暂悬浮后自动消失；底部弹层用于选择、筛选、添加家谱等多选项任务；居中确认弹窗用于退出、撤回申请、拒绝审核等需要明确决定的操作；结果弹窗用于提交失败、网络异常、权限不足等结果说明，并必须给出下一步。删除家谱、移除成员等不可逆或高风险操作使用危险色、明确后果说明和二次确认；普通操作不得滥用二次确认。四类弹窗均使用项目自定义组件，不得直接显示原生 UniApp 弹窗或提示。
|
||
|
||
弹窗关闭行为必须统一适配 Android 返回键：普通底部弹层点击遮罩或按返回键均可关闭；弹层存在未保存输入时，关闭前提示是否放弃；普通确认弹窗的返回键等同“取消”；危险操作的二次确认不得因遮罩或返回键而直接确认或无提示消失，必须通过明确按钮完成或取消；加载任务可取消时显示“取消”，不可取消时禁用关闭并持续显示清晰的进行状态。任何关闭方式都不得把取消误判为成功。
|
||
|
||
空状态必须按原因设计，禁止用同一张“暂无数据”画面覆盖所有情况：首次使用时解释页面用途并提供一个主入口；搜索／筛选无结果时保留当前条件并提供清除筛选或更换关键词；确实暂无内容时说明内容如何产生，并按普通成员与管理者权限显示不同操作；加载失败和无权限不得伪装成空数据，必须分别提供重试或权限说明。每种空状态只突出一个主操作，最多提供一个次操作，避免按钮堆叠。
|
||
|
||
从列表进入详情后返回，必须恢复用户离开前的现场，包括滚动位置、搜索关键词、筛选条件、已展开分组、G01 当前选中的家谱和已加载页数；只有用户主动刷新、切换账号或原数据已失效时才重置。返回过程不得闪回列表顶部后再二次跳转。
|
||
|
||
### 4.1 工程质量底线
|
||
|
||
- 项目自有源码必须精准、清晰、可读，不得提交压缩、混淆或机器堆叠后无法维护的代码来代替源代码；第三方原始发行文件可保持压缩，但必须集中隔离在 `static/vendor/` 等明确目录，不得直接改写其压缩内容。
|
||
- 关键业务判断、状态转换、Android／UniApp 兼容处理、生命周期清理、性能取舍和非直观算法必须使用准确的中文注释说明“为什么这样做”；禁止用逐行复述代码的无效注释制造噪音。
|
||
- 组件、样式和状态命名必须表达真实用途；函数保持单一职责，控制嵌套深度，及时清除本次修改产生的废弃分支、无用变量和重复实现，不得遗留临时补丁、神秘常量或无法追溯的复制代码。
|
||
- 弹窗、加载、空状态、表单反馈、色彩、间距、圆角、字号和安全区等共用规则必须有单一维护入口；页面消费统一组件或设计变量，不得在各页复制一套近似实现。只有出现真实复用需求时才抽取公共层，禁止为了“看起来高级”制造过度抽象。
|
||
- 所有页面代码必须便于后续修改：结构、内容、状态和装饰职责清楚；数据状态不得散落在模板和样式中；布局不得依赖偶然可用的固定高度、负边距或设备特例堆叠。
|
||
- 样式实现必须同时通过 320×568、360×640、360×800、412×915 四档尺寸，并覆盖 Android 安全区、系统字体、键盘、长文本和返回手势；动画优先使用 `transform` 与 `opacity`，避免大面积重绘、重复监听和无清理定时器。
|
||
- 性能验收以 4GB 内存的中低端 Android 真机为底线：长列表使用至少 500 条 Mock 数据测试滚动、下拉刷新、触底加载和返回现场恢复；同一详情连续进入／退出 20 次不得越来越慢、白屏或串状态；快速切换 Tab、重复开关弹窗不得堆叠实例或残留遮罩；页面点击 100ms 内出现反馈，动画不得出现肉眼可见的持续掉帧；图片必须按显示槽位解码，禁止同页同时加载多张原始超大图。
|
||
- 每次实现坚持最小、可验证、可回退的外科式修改，只触碰当前验收项必需的文件；实现前明确状态契约，完成后执行相关测试、运行时检查、真机截图复核和 `git diff --check`。未获得真实证据不得宣称完成。
|
||
|
||
### 4.2 全局视觉、适配与表现质量门禁
|
||
|
||
| 状态 | 编号 | 验收项 | 通过标准 |
|
||
| --- | --- | --- | --- |
|
||
| `[~]` | C01 | 自定义轻提示 | 已建立 A 系列卷轴 `AppToast` 并清零活动代码中的 `uni.showToast`；待逐页审核提示位置、时长和长文案 |
|
||
| `[~]` | C02 | 自定义信息弹窗 | 已建立 A 系列卷轴 `AppDialog`，审核说明与关系冲突已接入；待逐页审核内容密度 |
|
||
| `[~]` | C03 | 自定义确认弹窗 | 已建立单双按钮统一结构，撤回与审核确认已接入；危险操作强度待逐页审核 |
|
||
| `[ ]` | C04 | 自定义结果弹窗 | 保存成功、提交失败、网络失败和可重试结果语义明确 |
|
||
| `[~]` | C05 | 页面级加载 | 已建立自定义 `AppLoading` 且活动代码无原生 Loading；骨架、局部加载、下拉刷新和长列表加载仍需逐页及接口阶段补全 |
|
||
| `[ ]` | C06 | 按钮级加载 | 登录、提交、保存期间立即禁用重复点击并显示明确进度 |
|
||
| `[ ]` | C07 | 权限与进度 | 相册、上传、分享权限及上传进度、取消、失败重试均有自定义反馈 |
|
||
| `[~]` | C08 | 基础主题与四尺寸适配 | 52 个活动页面已形成浅色国风基础 H5 候选：G 以 G01 为母体，T/F/R/N/M 各有独立模块风格；Android 与逐页四尺寸视觉审核仍待完成 |
|
||
| `[ ]` | C09 | 安全区适配 | 状态栏、刘海、底部手势区和固定导航不遮挡页面内容或操作 |
|
||
| `[ ]` | C10 | 软键盘适配 | 输入框、校验信息和提交按钮不被软键盘遮挡，页面可滚动到当前字段 |
|
||
| `[ ]` | C11 | 字体与长文本 | 默认字号与约 1.3 倍系统字号下，Android 字体回退、超长族谱名、生僻姓名和长文案均不重叠、不截断关键含义、不遮挡主操作 |
|
||
| `[ ]` | C12 | 触控与误操作 | 点击区不小于约 44dp；连续点击不重复提交；返回前保护未保存内容 |
|
||
| `[ ]` | C13 | 图片性能 | 图片按显示槽位使用；避免同页同时解码多张超大位图；屏外图片延迟加载 |
|
||
| `[ ]` | C14 | 列表性能 | 使用至少 500 条 Mock 数据测试；长列表分批渲染并使用稳定 `key`；下拉刷新和触底加载均保留已有内容、滚动位置与布局高度；短列表不循环触发，滚动时不反复重绘整页 |
|
||
| `[ ]` | C15 | 动画性能 | 优先使用 `transform` 和 `opacity`；不使用大面积模糊、复杂滤镜和重阴影动画；页面过渡不白屏、不持续掉帧 |
|
||
| `[ ]` | C16 | 响应反馈 | 点击后 100ms 内出现反馈；超过 300ms 的操作必须显示自定义加载状态 |
|
||
| `[ ]` | C17 | 页面生命周期 | 离开页面时清理定时器、监听器、上传任务和动画状态，避免越用越卡 |
|
||
| `[ ]` | C18 | 路由压力 | 同一详情连续进入／退出 20 次，快速切 Tab、重复开关弹窗，不白屏、不串状态、不重复堆栈、不残留遮罩且不逐次变慢 |
|
||
| `[ ]` | C19 | Android 真机性能 | 以 4GB 内存中低端 Android 为底线，真机复核启动、键盘、500 条长列表、图片解码、页面切换和系统返回手势，无肉眼可见的持续掉帧 |
|
||
| `[ ]` | C20 | 运行与构建洁净度 | 无控制台错误、资源 404、未处理 Promise、明显重复渲染和构建错误 |
|
||
|
||
## 5. 52 页真实用户流程验收表
|
||
|
||
### 5.1 首次打开与认证
|
||
|
||
| 状态 | 序号 | 页面 | 真实入口与必须覆盖的可能性 |
|
||
| --- | ---: | --- | --- |
|
||
| `[~]` | 1 | A01 登录 | **2026-07-16 用户已确认通过除真实滑动验证外的 7 类 H5 视觉状态**：密码默认、密码掩码、密码明文、短信默认、字段错误 Toast、协议错误、协议已勾选；品牌区、双按钮和 Logo 缩小版同时通过本轮审核。真实滑动验证采用接口组件自带样式，待接入后单独审核；Android/HBuilderX 复核前页面不冻结 |
|
||
| `[~]` | 2 | A04 注册账号 | **2026-07-16 用户已确认通过当前可实现的 8 类 H5 视觉状态**：默认空表单、空提交全量错误、手机号单项错误、两次密码不一致、协议未勾选、填写完成待提交、滑动验证待接入 Toast、协议入口 Toast；Logo、全局楷体、标题分隔、朱砂主按钮和浅色卷轴 Toast 同时通过本轮审核。真实滑动验证采用接口组件自带样式，注册成功／失败和进入 G01 的真实链路待接口阶段审核；Android/HBuilderX 复核前页面不冻结 |
|
||
| `[~]` | 3 | A05 重置密码 | A01→忘记密码；**2026-07-16 用户已确认通过当前 7 类 H5 视觉状态**：默认空表单、空提交全量错误、手机号单项错误、滑动验证待接入 Toast、两次新密码不一致、密码重设成功卷轴、返回 A01 密码登录画面；Logo、全局楷体、标题分隔、两处朱砂按钮和 Toast 同时通过本轮审核。用户决定“成功后回填手机号并聚焦密码框”不阻塞当前样式验收，随真实重置接口链路接入时解决；真实滑动验证、真实短信/重设结果及 Android/HBuilderX 仍待复核，页面保持 `[~]`、不冻结 |
|
||
### 5.2 登录后进入我的家谱并完成首次分流
|
||
|
||
| 状态 | 序号 | 页面 | 真实入口与必须覆盖的可能性 |
|
||
| --- | ---: | --- | --- |
|
||
| `[x]` | 4 | G01 我的家谱 | 用户已在本轮逐项通过正常、空、加载、失败、添加家谱弹层、切换家谱弹层、独立滚动及响应式检查；作为 G 系列基准冻结。Android/HBuilderX 与 4GB Android 长图性能仍待后续平台验证，不等于接口或 Android 功能通过 |
|
||
| `[~]` | 5 | G03 创建家谱 | G01 空态或“添加家谱”→创建独立家谱；姓氏、谱名、堂号、所在地、访问规则，创建前提示搜索潜在已有家谱；覆盖必填校验、创建中、失败和已创建但始祖未完成的中断恢复；成功后直接成为创建者→录入始祖→进入 G05 总览，不直接跳 T01；下属支系创建待接口提供上级谱与权限字段 |
|
||
| `[~]` | 6 | G06 加入家谱 | G01 空态或“添加家谱”→加入；搜索／邀请码双模式、地区与谱名筛选；结果卡展示谱名、姓氏、地区、堂号、所属上级谱、当前支系、管理／认证信息、成员规模和更新时间，并覆盖未加入、已加入、审核中、被拒绝、已退出／移除、我创建的六种操作状态；邀请码验证、初始、加载、结果、无结果、无效／过期邀请码、失败、清空输入 |
|
||
| `[~]` | 7 | G08 关系确认与入谱 | G06 选定家谱→填写真实姓名和以已知长辈为参照的文字关系；搜索态显示申请说明／提交申请并在成功后进入 G09，邀请码态显示可选补充信息／确认加入并明确无需审核，成功后返回 G01 选中新家谱；覆盖校验、重复提交、提交中、成功／失败、返回保护；结构化关系待接口提供后迁移 |
|
||
| `[~]` | 8 | G09 我的申请 | G08 搜索来源提交成功→申请记录；待审、通过、拒绝、修改后重新提交、撤回、空、失败；邀请码来源不进入本页 |
|
||
| `[~]` | 9 | G05 家谱总览 | G06 未加入结果卡→公开预览，或 G01 顶部可用家谱大卡片／G09 已通过→成员总览；公开态仅展示身份、来源、地区、堂号、支系、公开说明和申请入口；成员态展示首屏三层家谱信息；覆盖加载、正常、空、失败、所有者／成员入口差异、无权限，世系图降为次级入口 |
|
||
|
||
### 5.3 所有者管理家谱
|
||
|
||
| 状态 | 序号 | 页面 | 真实入口与必须覆盖的可能性 |
|
||
| --- | ---: | --- | --- |
|
||
| `[~]` | 10 | G10 入谱审核 | G05/G01/N01→审核；列表、空、失败、通过／拒绝确认、无权限 |
|
||
| `[~]` | 11 | G11 家谱设置 | G05→设置；名称校验、公开范围、访问说明、保存中、成功／失败、无权限 |
|
||
| `[~]` | 12 | G12 字辈诗 | G01/G05→字辈诗；列表、空、编辑、校验、保存失败、无权限 |
|
||
|
||
### 5.4 世系树与成员
|
||
|
||
| 状态 | 序号 | 页面 | 真实入口与必须覆盖的可能性 |
|
||
| --- | ---: | --- | --- |
|
||
| `[~]` | 13 | T01 世系树 | 已按方案 1 重构为纵向世系轴候选：始祖居上、后代向下分代、同代横向扩展、关系线连续、节点选中与底部人物信息栏；加载、树、空、失败、阅读提示均保留。52 路由 Vite 转换和聚焦静态契约已通过，等待 2026-07-21 用户视觉审核；9222 缺失导致当夜未完成 CDP 四档和交互 smoke |
|
||
| `[~]` | 14 | T04 新增亲属 | T01→新增；首位成员／普通亲属、关系选择、必填、保存中、结果 |
|
||
| `[x]` | 15 | T07 成员目录 | T01→成员目录；列表、搜索、无结果、失败、成员选择 |
|
||
| `[~]` | 16 | T03 成员档案 | T01/T07→成员；正常、失败、隐私字段、编辑入口 |
|
||
| `[~]` | 17 | T05 编辑成员 | T03→编辑；字段校验、保存中、成功／失败、无权限 |
|
||
| `[~]` | 18 | T06 编辑关系 | T01→编辑关系；冲突、循环关系、说明弹窗、保存失败 |
|
||
| `[~]` ⚠ | 19 | T08 成员状态 | 应由 T03 进入；去世、隐私隐藏、无权限；当前无真实入口 |
|
||
|
||
### 5.5 家族动态与内容
|
||
|
||
| 状态 | 序号 | 页面 | 真实入口与必须覆盖的可能性 |
|
||
| --- | ---: | --- | --- |
|
||
| `[x]` | 20 | F01 家族首页 | 底部“家族”Tab；加载、列表、空、失败、发布及内容入口 |
|
||
| `[~]` | 21 | F02 发布动态 | F01→发布；空内容、键盘、提交中、成功／失败、重复提交 |
|
||
| `[~]` | 22 | F03 动态详情 | F01 动态卡→详情；正文、评论、操作结果、内容失效 |
|
||
| `[~]` | 23 | F04 谱文列表 | F01→谱文；分类、列表、空、失败、新建入口 |
|
||
| `[~]` ⚠ | 24 | F05 谱文详情 | 应由 F04 文章进入；详情、收藏、失效内容；当前卡片只弹提示 |
|
||
| `[~]` ⚠ | 25 | F06 编辑谱文 | 应由 F04 新建／F05 编辑进入；草稿、校验、保存、失败 |
|
||
| `[~]` | 26 | F07 相册列表 | F01→相册；列表、空、失败、新建相册 |
|
||
| `[~]` ⚠ | 27 | F08 相册详情 | 应由 F07 相册进入；照片墙、空相册、预览、失效；当前无跳转 |
|
||
| `[~]` ⚠ | 28 | F09 上传照片 | 应由 F08→添加照片；权限、选择、上传进度、失败重试 |
|
||
| `[~]` ⚠ | 29 | F10 家族视频 | 应由 F01 内容入口进入；未开放、空、列表、失败；当前无入口 |
|
||
|
||
### 5.6 人物、礼仪与档案
|
||
|
||
| 状态 | 序号 | 页面 | 真实入口与必须覆盖的可能性 |
|
||
| --- | ---: | --- | --- |
|
||
| `[x]` | 30 | R01 人物录 | 应由家族档案入口进入；列表、搜索、空、失败、新建 |
|
||
| `[~]` ⚠ | 31 | R02 人物详情 | 应由 R01 人物进入；详情、编辑、隐私、内容失效 |
|
||
| `[~]` ⚠ | 32 | R03 贺礼列表 | 应由家族工具进入；列表、空、失败、新增 |
|
||
| `[~]` ⚠ | 33 | R04 编辑贺礼 | 应由 R03 进入；新增／编辑、校验、保存、删除确认 |
|
||
| `[~]` | 34 | R05 礼仪列表 | F01→礼仪；列表、空、失败、新建 |
|
||
| `[~]` ⚠ | 35 | R06 礼仪详情 | 应由 R05 活动进入；详情、编辑、活动失效 |
|
||
| `[~]` ⚠ | 36 | R07 编辑礼仪 | 应由 R05 新建／R06 编辑进入；校验、保存、失败 |
|
||
| `[~]` ⚠ | 37 | R08 成长日志 | 应由人物／成员档案进入；时间轴、空、失败、新增 |
|
||
| `[~]` ⚠ | 38 | R09 人生事 | 应由人物／成员档案进入；时间轴、空、失败、新增 |
|
||
| `[~]` | 39 | R10 家族备忘 | F01→备忘；列表、空、失败、新增 |
|
||
| `[~]` ⚠ | 40 | R11 功德记录 | 应由家族档案入口进入；列表、空、失败、新增 |
|
||
|
||
### 5.7 消息
|
||
|
||
| 状态 | 序号 | 页面 | 真实入口与必须覆盖的可能性 |
|
||
| --- | ---: | --- | --- |
|
||
| `[x]` | 41 | N01 消息中心 | G01/M01→消息；加载、未读、已读、全部已读、空、失败、审核跳转 |
|
||
| `[~]` ⚠ | 42 | N02 消息详情 | 应由 N01 消息卡进入；详情、已读、失效消息、业务跳转；当前点击只改已读 |
|
||
|
||
### 5.8 个人中心
|
||
|
||
| 状态 | 序号 | 页面 | 真实入口与必须覆盖的可能性 |
|
||
| --- | ---: | --- | --- |
|
||
| `[x]` | 43 | M01 我的首页 | 底部“我的”Tab；资料、提醒、菜单、失败状态 |
|
||
| `[~]` | 44 | M02 个人资料 | M01→资料；头像权限、必填、保存中、成功／失败 |
|
||
| `[~]` | 45 | M03 账号与安全 | M01→安全；密码、手机号、设备、异常提醒 |
|
||
| `[~]` ⚠ | 46 | M04 修改密码 | 应由 M03 进入；旧密码、新密码、不一致、成功／失败 |
|
||
| `[~]` ⚠ | 47 | M05 修改手机号 | 应由 M03 进入；验证码、错误号码、成功／失败 |
|
||
| `[~]` | 48 | M06 帮助中心 | M01→帮助；常见问题、无结果、联系入口 |
|
||
| `[~]` ⚠ | 49 | M07 意见反馈 | 应由 M06 进入；校验、提交中、成功／失败 |
|
||
| `[~]` ⚠ | 50 | M08 应用推广 | 应由 M01 进入；分享权限、生成海报、取消、失败 |
|
||
| `[~]` ⚠ | 51 | M09 VIP 与订单 | 应由 M01 进入；无订单、权益、订单列表、加载失败 |
|
||
| `[~]` | 52 | M10 设置与关于 | M01→设置；协议、隐私、版本、退出确认／取消；基础版本不展示外观模式入口，深色与跟随系统延期到下一版本 |
|
||
|
||
### 5.9 封存页面（不计入 52 页活动验收统计）
|
||
|
||
| 页面 | 封存决定 | 保留内容 | 恢复条件 |
|
||
| --- | --- | --- | --- |
|
||
| A06 登录状态 | 2026-07-16 用户确认当前样式没有问题，但当前产品流程暂时不用该页；采用“从 `pages.json` 和活动验收表移除”的封存方式 | 保留 `pages/auth/a06-auth-status.vue`、静态合同、运行测试、设计记录与截图证据；不删除、不冻结，也不标记为 `[x]` | 产品重新需要独立阻断登录页时，将路由重新加入 `pages.json`，接入真实登录结果与恢复服务，再执行四档 H5、Android/HBuilderX 和用户逐态审核 |
|
||
|
||
## 6. 当前视觉流程断点与后续功能依赖
|
||
|
||
除 APP 启动页 A01 外，目前有 22 个最终页面没有被其他页面真实跳转到：
|
||
|
||
- T08。
|
||
- F05、F06、F08、F09、F10。
|
||
- R01、R02、R03、R04、R06、R07、R08、R09、R11。
|
||
- N02。
|
||
- M04、M05、M07、M08、M09。
|
||
|
||
这些页面必须先确定合理的上游入口和返回位置，再做用户流程验收。直接输入路由只能用于内部开发定位，不能作为用户流程证据。
|
||
|
||
后续功能验收必须覆盖：A01 微信登录、A01/A04/A05 公共行为验证、G06 邀请码验证、G08 邀请码直接加入、角色／权限清单和功能开关。它们不属于本文件的完成门槛，也不得因为页面样式通过而宣称真实数据链路通过。
|
||
|
||
## 7. 每项固定执行顺序
|
||
|
||
1. 从本表上一项或明确的分支入口进入页面。
|
||
2. 捕获本轮真实运行截图并检查是否为正确页面、正确状态、非加载中画面。
|
||
3. 默认展示一张代表图；复杂状态展示一张联系表，不连续铺陈对比截图。
|
||
4. 确认当前浅色国风主题的关键状态、四档尺寸、代码质量和性能均已通过。
|
||
5. 用户确认通过则当前基础版本页面标 `[x]` 并冻结；用户指出问题则整个页面标 `[!]`。
|
||
6. 返工前先更新最小契约测试并确认 RED，再做最小实现。
|
||
7. 测试、构建、截图或路由异常时先复现并定位根因，不盲改样式。
|
||
8. 返工后运行受影响测试、运行时 smoke、当前主题四尺寸复核、真实路由截图和 `git diff --check`。
|
||
9. 接口资料只用于理解功能、字段和状态位置；本阶段不对接接口，也不执行接口功能验收。
|
||
|
||
## 8. 单项验收记录模板
|
||
|
||
```md
|
||
### <编号> <页面或全局项名称>
|
||
|
||
- 当前标记：`[~]`
|
||
- 真实入口：
|
||
- 用户身份：
|
||
- 本轮状态：
|
||
- 状态子项：正常 / 空 / 加载 / 失败 / 权限 / 业务状态
|
||
- 代表截图：
|
||
- 四尺寸结果：320×568 / 360×640 / 360×800 / 412×915
|
||
- 可见交互与误操作样式：
|
||
- 加载动画与表现质量：
|
||
- 页面样式契约与 smoke：
|
||
- 功能／接口状态：不在本阶段验收
|
||
- 用户结论：通过 / 返工
|
||
- 返工范围：
|
||
```
|
||
|
||
## 9. 全量结束条件
|
||
|
||
- C01–C20 全部为 `[x]`。
|
||
- A02 已并入 A01，A06 已封存，`pages.json` 活动路由数为 52，且不存在 A02 旧入口或 A06 活动入口。
|
||
- 52 个活动页面全部为 `[x]`，不存在 `[~]`、`[!]` 或未解释的 `⚠`。
|
||
- 每个页面的适用状态子项全部通过，不以单张正常态截图代替状态验收。
|
||
- 22 个现有流程断点均已通过真实入口和返回路径验证。
|
||
- 40 处原生 UniApp 提示均已替换，运行页面不出现原生弹窗或 Toast 样式。
|
||
- 四尺寸检查、Android 真机复核、受影响测试、运行时 smoke、真实截图和 `git diff --check` 均有最新证据。
|
||
- 页面样式验收阶段未对接业务接口、未修改接口契约、未使用截图作为运行资产；后续另建功能验收规则验证真实数据链路。
|
||
- 未执行 `git add`、commit、push、reset、checkout 或上传。
|