jiapuapp/docs/superpowers/plans/2026-07-13-product-design-visual-refinement.md

家谱 App Product Design 视觉精修实施计划

现行范围更新：A03 已于 2026-07-14 删除；验证码登录归 A02，绑定手机号归个人中心，微信异常归 A06。历史方案不再作为实现依据。

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task. Do not use parallel agents in this shared workspace.

Goal: 在不改变已验收 A01、G01 可见效果和既有业务交互的前提下，把其余 57 个页面从“可浏览的第一版”精修为同一套、可在 Android 小屏上成立的家祠卷轴界面。

Architecture: A01、G01 是唯一的视觉源，不把它们当作可以随意模仿的截图，而是提炼为“完整图片资产承担可见外观，Vue/CSS 只承担布局、文字和状态”的设计系统。每个模块先完成一张可截图验收的代表页，再将已确认的面板、按钮、列表或状态结构复用到同模块；不得用 ModulePage.vue 的单一通用卡片替代不同任务的页面设计。

Tech Stack: Vue 3、<script setup>、uni-app、SCSS、uni-app 原生 image/input/textarea/button、现有 PowerShell 合同审计、Product Design（index、user-context、audit、image-to-code）和 ImageGen（仅为缺失的最终图片资产生成）。

Global Constraints

• 用户已经验收 A01 启动／登录引导与 G01 我的家谱；这两页的可见结果冻结，不能“顺手优化”。
• 不新增路由、后端接口、依赖、登录逻辑或 Android 打包范围；只做已存在页面的视觉和必要的页面内交互保持。
• 可见的主按钮、次按钮、题签、卡片边框、分隔纹和云纹必须使用真实图片资产；禁止 CSS 色块、border、伪元素、SVG 或文字符号拼出最终装饰。
• 只使用用户正在使用的 Chrome 进行 Product Design 截图；没有可用的浏览器捕获能力时，不得把静态代码检查说成视觉验收。
• 所有新资产先独立检查透明属性、原图尺寸和显示比例；禁止拉伸 A01 两个约 4.49:1 的按钮皮肤。
• 所有视觉页面在 H5 的 320×568、360×640、360×800、412×915 预览；模块收尾前在 HBuilderX/Android 至少复核 360×800、412×915。
• 不执行 git add、git commit、git push、上传或覆盖未知改动；用户自行处理 Git。

---

已确认的视觉基准与当前判断

A01 提炼出的规则

• 上方使用完整朱砂祠堂页头，品牌谱印居中；主内容从纸面中段开始，留白有节奏，不让背景压住任务。
• 标题是画面主角：大号楷体墨褐字、左右小云纹、上下金线／如意结，副文案只承担解释。
• 两个操作都是完整皮肤：朱砂主按钮、宣纸次按钮；按钮字体、图标和边角纹样都保持完整，不能缩成普通表单按钮。
• 淡墨山水只压在背景层，底部成为收束，不能侵入输入内容或降低对比度。

G01 提炼出的规则

• 首页先给“当前家谱”一张有分量的双线题签卡，再给功能快捷入口和列表；信息优先级非常清楚。
• 金色线条不是装饰噪音：只用于题签边框、分区线、图标和关键元信息，朱砂只标记品牌、当前项与主要操作。
• 图标、谱印框、题签框、分区线、底部山水和 Tab 均是成套资产，形成统一密度，不是若干孤立 CSS 卡片。
• 正文保持可读，标题／姓名用楷体形成“谱”的气质，元信息用更小但仍清楚的常规字。

A02 当前截图的失败点

• 登录卡片窄且短，文本、标签和输入线过小；用户首先看到的是背景，而不是“我要登录”。
• A01 的祠堂头、A02 的普通表单卡和红色按钮像三套不同完成度的设计，标题云纹也没有形成真正的层级。
• 红色主按钮虽然替换了皮肤，但当前容器比例不匹配原图，压扁后失去 A01 的端正感。
• 这不是“再加几个装饰”能解决的问题；必须先重新确定 A02 的任务层级、卡片占比和资产比例。

本轮选定方向

家祠卷轴 · 庄重留白。 所有页面以温暖宣纸作为底，朱砂用于品牌和唯一主操作，古金用于题签与层级，墨褐用于信息。不同任务采用不同完整面板：认证是“卷轴登录页”，家谱是“题签／谱册”，世系是“关系图谱”，内容是“档案与相册”，记录是“簿册与时间线”，设置是“折页清单”。

文件职责

文件／目录	责任
docs/design/screens/	只存设计基准与运行时验收图，绝不作为页面运行时图片。
docs/design/D1_安卓视觉规范与页面壳.md	视觉和资产硬规则的唯一规范；本计划实施后补充已确认的组件比例。
docs/design/P00_页面结构与资产清单.md	运行时资产的唯一台账；必须消除其中过时的“按钮未生成”描述。
static/assets/foundation/	所有模块共享的纸纹、页头、完整按钮、全局导航和透明装饰。
static/assets/modules/<module>/	仅归属于认证、家谱、世系、家族、档案或个人模块的完整面板与透明装饰。
components/PageHeader.vue、components/AppTabbar.vue、components/GenealogyCard.vue	已存在稳定公共结构；只有验收后仍被至少两页使用的视觉结构才加入公共组件。
components/ModulePage.vue、data/page-catalog.js	第一版页面覆盖工具；逐模块被确认页面替代后，只保留尚未替换路由所需内容，不把它升级成全站视觉答案。
tests/*.ps1	路由、资产、行为与可见资产锚点的回归；截图是独立的人工／Product Design 验收证据。
docs/交接记录.md	下一个 GPT 的唯一施工停点：已验收页、资产路径、证据、未完成模块、命令和禁区。

Task 1: 建立真实基线与 Product Design 设计审视

Files:

• Create: docs/design/screens/runtime/2026-07-13/A01-360x800.png
• Create: docs/design/screens/runtime/2026-07-13/G01-360x800.png
• Create: docs/design/screens/runtime/2026-07-13/A02-before-360x800.png
• Create: docs/design/2026-07-13-A01-G01-A02-视觉审视.md
• Modify: docs/规划.md
• Modify: docs/交接记录.md

Consumes: 冻结图 docs/design/screens/A01-启动登录引导-栅格验收-412x915.png、docs/design/screens/G01-我的家谱-紧凑版设计稿-v5-Tabbar安全区.png；当前 A02 路由 /#/pages/auth/a02-login?agreed=1。

Produces: 可复核的同尺寸“基准／当前”截图和只针对 A02 的审视结论；没有截图不得进入 A02 实施。

• Step 1: 运行 Product Design 上下文预检并读取现有视觉依据。

  使用 Product Design:index → Product Design:user-context。若本机 Python 或已保存的 Product Design context 不可用，在审视文档明确写“无持久上下文，依据项目内冻结图与本轮 Chrome 截图”，不要伪造已保存上下文。

• Step 2: 用用户当前 Chrome 捕获并检查 360×800 的 A01、G01、A02。

  使用 Product Design:audit 的捕获顺序：观察已打开页 → 截图 → 保存 → 打开检查 → 记录。每张图必须没有 DevTools 覆盖页面主体、加载态、裁切或错误页。

• Step 3: 写审视结论。

  docs/design/2026-07-13-A01-G01-A02-视觉审视.md 必须包含：视觉源、A01/G01 的 6 条可继承规则、A02 的至少 5 个可见问题、每项问题的解决策略、截图文件名、截图不能验证的限制。不得宣称无障碍完全合规。

• Step 4: 纠正文档事实。

  在 docs/规划.md 和 docs/交接记录.md 中明确：只有 A01、G01 用户验收；ModulePage 是第一版覆盖而非最终视觉；A02 当前未验收；P00 中“A01 按钮尚未生成”的文字过期。

• Step 5: 检查。

  运行：powershell.exe -NoProfile -ExecutionPolicy Bypass -File tests/full-page-visual-contract.ps1。

  预期：FULL-PAGE-VISUAL-CONTRACT PASS。再运行 git diff --check，预期仅允许换行符警告，不允许空白错误。

Task 2: 固化 A02 视觉合同与所需资产，而不是继续堆 CSS

Files:

• Create: docs/design/A02_账号登录_设计记录.md
• Create: static/assets/modules/auth/opaque/a02-login-panel.png
• Create only if A01 皮肤无法按原比例容纳登录区: static/assets/modules/auth/opaque/a02-primary-button.png
• Create only if A01 次按钮无法按原比例容纳辅助操作: static/assets/modules/auth/opaque/a02-secondary-button.png
• Create: tests/a02-asset-alpha-audit.ps1
• Modify: docs/design/P00_页面结构与资产清单.md

Consumes: Task 1 的已接受截图、A01 标题／云纹／祠堂／按钮资产和 D1 规则。

Produces: A02 的单一资产合同：完整登录面板、正确比例的完整按钮以及每个资产的路径、原图尺寸、显示比例、透明属性和引用位置。

• Step 1: 写 A02 设计记录，不写代码。

  记录必须把 A02 固定为：同 A01 高度的祠堂头；头下为可见主任务标题；完整卷轴／题签面板承载两个 Tab、输入区和辅助操作；底部山水只在表单后留白出现；主按钮按原图比例显示且高度不低于 88rpx。记录 A02 不新增微信、真实短信或后端登录。

• Step 2: 为缺失的可见面板生成真实图片资产。

  使用 Product Design:image-to-code 所依据的 A01/G01 视觉源和 imagegen。面板必须是完整不透明 PNG，包含自身纸面纹理、双金线、角纹；不要生成整页图、截图切片、文字或不可替换的表单字段。透明云纹、图标仍使用已有 PNG。

• Step 3: 先写并运行红灯资产审计。

  tests/a02-asset-alpha-audit.ps1 至少验证：资产存在；完整面板四角不是透明；若生成 A02 按钮，四角也不是透明；原图宽高比与页面显示宽高比误差不超过 3%；透明资产仍保留 alpha 像素。先运行脚本，预期失败原因只能是“资产尚不存在”。

• Step 4: 生成并检查资产后转绿。

  运行：powershell.exe -NoProfile -ExecutionPolicy Bypass -File tests/a02-asset-alpha-audit.ps1。

  预期：A02-ASSET-ALPHA-AUDIT PASS。然后将所有最终路径、用途、尺寸写入 P00，候选图不进入 static/assets/。

Task 3: 将 A02 做成认证模块的已验收样板

Files:

• Modify: pages/auth/a02-login.vue
• Modify: tests/a01-a02-ui-contract.ps1
• Modify: docs/design/A02_账号登录_设计记录.md
• Create: docs/design/screens/runtime/2026-07-13/A02-after-320x568.png
• Create: docs/design/screens/runtime/2026-07-13/A02-after-360x640.png
• Create: docs/design/screens/runtime/2026-07-13/A02-after-360x800.png
• Create: docs/design/screens/runtime/2026-07-13/A02-after-412x915.png

Consumes: Task 2 的资产合同。保留现有双 Tab、协议回跳判断、忘记密码跳 A05、字段校验与 toast。

Produces: 唯一可用于 A03–A05 的认证表单样板；页面不是 ModulePage 的变体。

• Step 1: 先写红灯页面合同。

  在 tests/a01-a02-ui-contract.ps1 增加 A02 锚点：完整面板图片、正确比例按钮图片、login-panel 的可访问文字层、两个真实 input、两个真实 Tab、A05 跳转。拒绝 A02 主面板／主按钮用 border、background: $brand-red、伪元素拼出最终外观。运行该脚本，预期因新资产或新锚点缺失失败。

• Step 2: 最小实现。

  A02 模板只保留“背景 → 同 A01 祠堂页头 → 页面标题 → 完整面板 → 表单 → 主按钮 → 底部背景”的层级。图片使用绝对底层，输入、Tab、标题和按钮文字使用相对文字层；不要把任何文字烘焙进图片。表单面板宽度跟随安全边距，按钮按资产比例设置高度，不能 scaleToFill 压扁。

• Step 3: 检查逻辑和四尺寸。

  运行：

  powershell.exe -NoProfile -ExecutionPolicy Bypass -File tests/a01-a02-ui-contract.ps1
  powershell.exe -NoProfile -ExecutionPolicy Bypass -File tests/a02-asset-alpha-audit.ps1
  powershell.exe -NoProfile -ExecutionPolicy Bypass -File tests/compile-audit.ps1
  

  预期：三个脚本均 PASS。再用 Product Design:audit 检查四尺寸截图：320 宽不横向裁切；360×640 能滚动且主按钮可达；360×800 卡片仍为主角；412×915 底部山水不侵入输入区。

• Step 4: 用户视觉门。

  只在用户确认 A02 后，将 docs/规划.md 状态更新为“认证样板已验收”。用户未确认时，记录为“实现完成，视觉待验收”，不得假称完成。

Task 4: 完成认证模块 A04–A06

Files:

• Modify: pages/auth/a04-register.vue
• Modify: pages/auth/a05-reset-password.vue
• Modify: pages/auth/a06-auth-status.vue
• Create only after A02 布局被两页复用: components/auth/AuthFormPanel.vue
• Modify: data/page-catalog.js and components/ModulePage.vue only when the corresponding A04–A06 entry is removed from the temporary motherplate
• Modify: tests/full-page-visual-contract.ps1
• Modify: docs/design/P00_页面结构与资产清单.md

Consumes: 已验收的 A02 面板、按钮和文字层级。

Produces: 认证五页同一入口体验：登录、注册、重设和结果状态各有对应任务，不能仍显示泛化的“功能完善中”。

• Step 1: 分别写四条红灯合同。

  A04 有手机号、密码、确认密码和协议提示；A05 有手机号、验证码、新密码；A06 有状态图标、说明和明确返回登录操作，并承接微信授权取消、失败与受限。合同只验证存在的交互和资产锚点，不宣称后端已接入。

• Step 2: 用 A02 的已确认结构分别实现。

  只在两页以上完全相同的面板结构出现时创建 AuthFormPanel.vue；否则页面内实现。每页使用同一头部、卡片比例、输入高度、按钮比例和淡墨留白，但标题、辅助文案、状态图和行动文案按任务不同。

• Step 3: 模块截图与回归。

  对 A04、A05、A06 至少各保存 360×800 一张截图；运行认证合同、compile-audit.ps1、git diff --check。A01 不改动且至少复核 412×915。

Task 5: 完成家谱模块 G02–G12

Files:

• Modify: pages/genealogy/g02-empty-genealogies.vue, g03-create-genealogy.vue, g04-first-ancestor.vue, g05-genealogy-overview.vue, g06-search-genealogies.vue, g07-search-result.vue, g08-join-application.vue, g09-my-applications.vue, g10-application-review.vue, g11-genealogy-settings.vue, g12-generation-poems.vue
• Create as needed after Product Design review: static/assets/modules/genealogy/opaque/*.png, static/assets/modules/genealogy/transparent/*.png
• Modify: components/GenealogyCard.vue, components/ModulePage.vue, data/page-catalog.js only when a confirmed G page replaces the temporary motherplate route
• Modify: tests/g01-visual-contract.ps1, tests/core-flow-contract.ps1, tests/full-page-visual-contract.ps1
• Modify: docs/design/P00_页面结构与资产清单.md

Consumes: G01 题签框、谱印、快捷图标、分区线、底部山水和 Tab；G01 页面本身不改。

Produces: G03（创建家谱）作为表单样板、G07（搜索结果）作为列表样板、G09（申请）作为时间线样板、G12（字辈诗）作为详情样板；其他 G 页只能复用已确认样板，不再保留通用 ModulePage 视觉。

• Step 1: Product Design 审视 G03、G07、G09、G12 的任务和截图。

  明确每页首要动作分别为创建、选择、查看进度、阅读／维护；每页只用一个主操作。生成缺失的完整题签／表单／时间线面板资产前，先把显示槽尺寸写入 P00。

• Step 2: 逐样板写红灯合同、实现、截图。

  每一类样板先有一个页面通过合同和 360×800、412×915 截图，再应用到同类页。按钮统一使用正确比例的完整朱砂或宣纸皮肤；列表和审核卡使用完整题签图，不得继续用圆角 CSS 卡片。

• Step 3: 保持真实跳转。

  G01→G03/G05/G06/G10/G12、G05→G08/G11/G12 的现有跳转不得回退。修改每条路径时，同轮更新合同；无效旧路径不能保留。

• Step 4: 回归。

  运行 tests/g01-visual-contract.ps1、tests/core-flow-contract.ps1、tests/compile-audit.ps1、tests/full-page-visual-contract.ps1。G01 至少复核 412×915 以证明未被公共组件改坏。

Task 6: 完成世系树与成员模块 T01–T08

Files:

• Modify: pages/tree/t01-tree-overview.vue through pages/tree/t08-member-states.vue
• Create as needed: static/assets/modules/tree/opaque/*.png, static/assets/modules/tree/transparent/*.png
• Modify: components/ModulePage.vue, data/page-catalog.js, tests/core-flow-contract.ps1, tests/full-page-visual-contract.ps1, docs/design/P00_页面结构与资产清单.md

Consumes: 已验收 G 模块的表单、题签、列表资产比例；世系图自身需要独立的关系节点和小屏状态设计。

Produces: T01 为横向世系主样板，T03 为人物档案样板，T04 为亲属表单样板，T02/T08 为明确状态样板。

• Step 1: 先完成 T01 与 T03 的 Product Design 截图审视。

  T01 必须在小屏给出清楚的“横向查看／进入成员目录”出口，不能硬塞一张缩小关系图；T03 先突出人物、世代和关系，再给资料和操作。

• Step 2: 建立真实节点、人物题签和状态资产。

  关系节点、状态徽记、人物题签必须使用图片资产；信息文本保留在 Vue 中。没有至少两个复用点不要抽取组件。

• Step 3: 逐页替换临时母版并测试。

  每页保留已有编辑／查看跳转；运行 T 模块合同、编译检查和 360×800、412×915 截图验收。

Task 7: 完成家族内容模块 F01–F10

Files:

• Modify: pages/family/f01-family-feed.vue through pages/family/f10-video-list.vue
• Create as needed: static/assets/modules/family/opaque/*.png, static/assets/modules/family/transparent/*.png
• Modify: components/ModulePage.vue, data/page-catalog.js, tests/core-flow-contract.ps1, tests/full-page-visual-contract.ps1, docs/design/P00_页面结构与资产清单.md

Consumes: G01 底部导航；F01 已有动态流和现有跳转。

Produces: F01 为家族动态样板，F04 为文章档案列表，F07 为相册封面列表，F08 为照片墙，F02/F06/F09 为发布／编辑表单，F10 为未开放状态。

• Step 1: 用 Product Design 先决定“内容不是家谱列表”。

  动态、文章、相册和视频保持纸本档案感，但各自有内容缩略、时间、作者和操作层级；不要复刻 G01 的家谱题签。

• Step 2: 只生成能反复使用的内容资产。

  例如文章档案题签、相册封面框、媒体上传框、评论分隔纹；照片和视频先使用现实感本地 mock，不把纯色方块当最终封面。

• Step 3: 保持 F01 的原有入口。

  F01→F04/F07/R05/R10 的现有导航继续可用；每个进入详情、编辑或上传的路径都要有可返回操作。

• Step 4: 截图和回归。

  F01、F04、F07、F09 在四尺寸预览；其余页面至少 360×800。运行受影响流程合同、编译检查和空白检查。

Task 8: 完成 R、N、M 模块

Files:

• Modify: pages/records/r01-people-list.vue through pages/records/r11-merit-records.vue
• Modify: pages/notification/n01-message-center.vue, pages/notification/n02-message-detail.vue
• Modify: pages/profile/m01-profile-home.vue through pages/profile/m10-about-settings.vue
• Create as needed: static/assets/modules/records/*, static/assets/modules/notification/*, static/assets/modules/profile/*
• Modify: components/ModulePage.vue, data/page-catalog.js, tests/core-flow-contract.ps1, tests/full-page-visual-contract.ps1, docs/design/P00_页面结构与资产清单.md

Consumes: 已确认的列表、详情、表单、时间线和设置样板。

Produces: R 采用簿册／时间线，N 采用清楚的通知层级，M 采用个人身份与设置折页；每个模块都有自己的图标和面板密度，不能留在相同母版外观。

• Step 1: R 先做人物录、礼仪活动、成长日志三类代表页。

  代表页分别确定人物档案、活动簿册和生命时间线资产与布局后，再完成其余 R 页。

• Step 2: N 先做消息中心和详情的已读层级。

  未读、已读、时间和空状态必须在不靠颜色的情况下可区分；点击后的 N02 跳转保持真实。

• Step 3: M 先做 M01 个人首页和 M03 安全设置。

  M01 是身份入口，不是普通列表；M03–M10 使用已确认的设置行／表单，而不是单一通用卡。

• Step 4: 每完成一个模块立即替换对应临时母版入口。

  删除本轮不再使用的 pageCatalog 条目、导入和临时样式；运行全部受影响路由与合同，不能留下“新旧两套页面都可走”的兼容入口。

Task 9: 全量视觉回归与真实交接

Files:

• Modify: docs/规划.md
• Modify: docs/交接记录.md
• Modify: docs/design/D1_安卓视觉规范与页面壳.md
• Modify: docs/design/P00_页面结构与资产清单.md
• Create: docs/design/视觉设计交接手册.md
• Modify: all affected tests/*.ps1

Consumes: 每个模块的已验收截图、资产台账、页面合同和实际执行结果。

Produces: 下一位 GPT 无需猜测即可继续的交接包；文档只写已经发生的事实，未用户验收的页面明确标注为待验收。

• Step 1: 跑全量可自动验证项。

  Get-ChildItem tests -Filter *.ps1 | Sort-Object Name | ForEach-Object {
    & powershell.exe -NoProfile -ExecutionPolicy Bypass -File $_.FullName
    if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
  }
  git diff --check
  

  预期：每个脚本 PASS；git diff --check 没有空白错误。若任何一项失败，按 superpowers:systematic-debugging 先复现、定位、修复并重跑，不能用改测试掩盖问题。

• Step 2: 完成四尺寸视觉门。

  每个路由至少在 360×800 留一张验收截图；每个模块代表页还须有 320×568、360×640、360×800、412×915。将每张图的页面、尺寸、状态、通过／问题写入交接手册。

• Step 3: 写交接手册。

  docs/design/视觉设计交接手册.md 必须包含：

  • 两张冻结视觉源和其禁止改动的可见元素；
  • 每个模块的代表页、状态、截图路径与未完成项；
  • 每项最终资产的路径、opaque/transparent 属性、原图尺寸、显示槽和引用页面；
  • 哪些临时 ModulePage／pageCatalog 条目已经移除，哪些仍待替换；
  • 路由总数、关键跳转、可运行的检查命令；
  • 下一位 GPT 的能力清单：先读 AGENTS.md、D1、P00、交接；再调用 Product Design:index→user-context→audit，有选择的视觉源时调用 image-to-code，缺真实图片资产时调用 imagegen，每次改行为前用 TDD，完成前做视觉截图和自动回归；
  • 禁区：不动 A01/G01、不可把截图当页面资产、不可用 CSS 伪造完整装饰、不可提交／上传、不可把未验收写成已完成。

• Step 4: 用户最终验收。

  按模块而不是一次塞 59 张截图给用户；只有用户确认的模块才在 docs/规划.md 勾选完成。没有用户回复时，状态保持“实现／截图完成，视觉待用户验收”。

执行顺序与停点

1. 先执行 Task 1–3，只做 A02，直到用户确认它是认证样板。
2. 再执行 Task 4，完成 A 模块后更新一次交接记录。
3. 按 Task 5 → 6 → 7 → 8 逐模块推进；任何模块出现不合格截图，先在该模块修复，不跳到下一个模块。
4. Task 9 最后执行，不能提前把 57 页写成“验收完成”。

实施前自检

• 计划覆盖 59 个路由：A、G、T、F、R、N、M 均有明确代表页和替换路径。
• 计划把 A01、G01 作为唯一视觉源，禁止全局母版继续掩盖页面差异。
• 计划把 Product Design 截图审视、真实图片资产、自动合同、四尺寸截图和用户确认串成顺序，避免“代码 PASS 但页面不好看”。
• 本计划不包含 Git 提交步骤，因为用户明确自行上传 Git。