rain/jiapuapp

Fork 0

Files

T

rain 1015e60ff7 设计完成30%

2026-07-14 07:01:45 +08:00

14 KiB

Raw Blame History

家谱 APP 视觉设计交接手册

更新日期：2026-07-14 用途：在新电脑或交给新的 GPT 后，按本手册恢复当前工作；它只记录已发生的事实，不把待验收写成已完成。

1. 当前停点：先看这一节

项目已有 59 条最终编号路由，第一版都可以浏览；这不等于 59 个页面已完成视觉验收。

用户已经验收的视觉基准只有两个：A01 启动/登录引导、G01 我的家谱。它们的可见效果已冻结。
A02 账号登录已经完成一次资产化重做、功能回归和多尺寸截图，但仍在等待用户审美验收。在用户确认前，不得把 A02 标记为完成，也不得把它的样式批量传播到 A03--A06。
其余模块的页面仍属于后续视觉设计任务；其中不少页面目前由 components/ModulePage.vue 与 data/page-catalog.js 提供第一版可浏览壳。这个壳是过渡方案，不是最终 UI。
不提交、不推送、不上传 Git；由用户自行处理版本库操作。

下一位执行者的第一件事不是开始做新页面，而是请用户查看 A02 的前后对比：

docs/design/screens/runtime/2026-07-13/A02-before-after-360x800.png
docs/design/screens/runtime/2026-07-13/A02-after-412x915.png
docs/design/screens/runtime/2026-07-13/A02-sms-360x800.png

用户若要求调整，只修改 A02 并重新截图、复核；用户若明确通过，才进入 A03--A06。

1.1 迁移前必须保留的文件

本手册和截图工具是本轮新增文件；换电脑前，用户需在自行提交/上传时包含它们，或完整复制当前工作区。我没有执行任何 Git 暂存、提交、推送或上传操作。

至少要保留：docs/design/视觉设计交接手册.md、docs/交接记录.md、scripts/capture-chrome-page.js、A02 页面/资产/测试、docs/design/screens/runtime/2026-07-13/ 的运行证据，以及现有计划与设计记录。只复制已提交的旧版本会丢失当前停点。

2. 必读文件与唯一职责

文件	负责什么
`AGENTS.md`	最小修改、保护既有未提交内容、验证后再交付的项目规则。
`docs/规划.md`	59 个页面的范围、模块顺序和“完成”的定义。
`docs/design/D1_安卓视觉规范与页面壳.md`	Android 页面、资产、布局与中文注释的硬约束。
`docs/design/P00_页面结构与资产清单.md`	路由、页面文件和资产台账的唯一清单。
`docs/superpowers/plans/2026-07-13-product-design-visual-refinement.md`	已批准的分模块视觉精修计划和验收顺序。
`docs/design/2026-07-13-A01-G01-A02-视觉审视.md`	A01/G01 视觉证据与旧 A02 的问题定位。
`docs/design/A02_账号登录_设计记录.md`	A02 当前实现、资产、截图和测试记录。
`design-qa.md`	A02 的 Design QA；当前 `final result: blocked`，原因是缺少用户的审美确认。
`docs/交接记录.md`	简版当前状态与恢复入口；本手册提供完整操作细节。

发生冲突时，按“用户最新明确指令 > AGENTS.md > 上表中的当前台账/计划 > 历史文档”的顺序处理。不要以旧的草案或已废弃的截图切片方案为依据。

3. 已验收的风格与绝对禁区

A01 与 G01 是可观察的品牌真源

A01 参考图：docs/design/screens/A01-启动登录引导-栅格验收-412x915.png
G01 参考图：docs/design/screens/G01-我的家谱-紧凑版设计稿-v5-Tabbar安全区.png

共同语言是“家祠卷轴”：暖宣纸、朱砂主色、古金框线和元数据、墨褐字、低对比淡墨山水。主信息应先于背景被读到，留白是结构的一部分。

必须遵守：

完整按钮、卡片、标题签、页面头图和有边框的装饰面，使用完整的不透明位图资产承载底色、纹理和边框。
透明 PNG 仅承担 Logo、图标、祥云、纹样等叠加元素；CSS 只承担布局、文字、状态与交互，不能伪造完整框、祥云、按钮或卡片。
不能把整张设计截图或局部截图裁进运行页面；运行资产必须是可复用的独立元素。
不要修改 A01/G01 已验收的可见布局、比例、配色或装饰。可读其实现和资产，但不能借“整理”改变效果。
不要用一个通用卡片母版覆盖所有模块。家谱、世系树、内容档案、人物记录、通知和设置必须在同一视觉语言下有各自的信息密度与层级。

4. A02 的精确状态

实现内容

路由与页面：pages/auth/a02-login.vue
新面板资产：static/assets/modules/auth/opaque/a02-login-panel.png
- 实际尺寸：940 × 1672
- 属性：四角不透明，承载宣纸底、双古金框、角饰与淡纹样
主按钮继续复用已验收完整资产：static/assets/foundation/opaque/a01-primary-button.png
账号密码与短信验证码 Tab、输入、忘记密码跳转和原有交互均保留；短信 Tab 已经通过真实 Chrome 调试点击截图。

已保存的运行证据

目录：docs/design/screens/runtime/2026-07-13/

文件	状态
`A02-before-360x800.png`	改造前基线。
`A02-after-320x568.png`	小屏账号密码态；允许纵向滚动，不允许横向裁切。
`A02-after-360x640.png`	中屏账号密码态。
`A02-after-360x800.png`	主对比尺寸。
`A02-after-412x915.png`	大屏账号密码态。
`A02-sms-360x800.png`	真实切换后的短信验证码态。
`A02-before-after-360x800.png`	左旧右新的并排对比。

通过/未通过的界线

已通过的是：资产尺寸与不透明角审计、A01/A02 页面契约、编译检查、A02 的多尺寸运行截图和短信 Tab 交互。

未通过的是：用户对 A02 的最终审美确认。因此 design-qa.md 必须保持 blocked，直至用户明确确认。用户若觉得顶部祥云偏多，只可先移除 A02 标题右侧的单个祥云；不要无根据改动面板框、输入区或交互。

5. 换电脑后如何恢复截图与审视能力

必备环境

Windows、Chrome、HBuilderX（项目当前以 Android uni-app 为目标）。
Node.js 22 或更高版本；当前脚本已在 Node 24 环境使用原生 fetch 与 WebSocket。
先在 HBuilderX 启动本地 H5 调试页，并确认它能在 http://localhost:5173 打开。不要臆测项目的 npm 启动命令。

用专用 Chrome 调试实例开启远程端口；它与用户日常 Chrome 隔离：

$chrome = "$env:ProgramFiles\Google\Chrome\Application\chrome.exe"
Start-Process -FilePath $chrome -ArgumentList `
  '--remote-debugging-port=9222', `
  "--user-data-dir=$env:TEMP\jiapu-chrome-debug", `
  'http://localhost:5173/#/pages/auth/a02-login?agreed=1'

确认调试端口与应用页面存在：

Invoke-RestMethod 'http://127.0.0.1:9222/json/list' | Select-Object title, url

使用项目内的正式脚本截图。它会导航专用调试 Chrome的当前标签页、写出 PNG，并在结束时清除设备尺寸覆盖；不能操作或关闭用户的日常 Chrome。

node scripts/capture-chrome-page.js `
  'http://localhost:5173/#/pages/auth/a02-login?agreed=1' `
  '.login-page' `
  'docs/design/screens/runtime/2026-07-14/A02-after-360x800.png' `
  360 800

截图只作为 docs/design/screens/runtime/<日期>/ 下的设计证据，绝不能放回 static/assets/ 作为运行资源。每个代表页面至少做 360 × 800；模块代表页还要做 320 × 568、360 × 640、360 × 800、412 × 915。最终 Android/HBuilderX 截图仍需补做，H5 Chrome 截图不能替代它。

6. 后续执行顺序与每轮产物

门禁 0：先处理 A02

让用户审 A02 前后对比与 412 × 915、短信 Tab 图。
若不通过：只在 A02 修正明确问题，先调整对应契约测试，再改页面/资产，重新截全尺寸图。
若通过：把 A02 状态同步到 docs/规划.md、docs/交接记录.md、docs/design/A02_账号登录_设计记录.md 与 design-qa.md，再开始 A03--A06。

其后的模块顺序

账号 A03--A06：以已验收 A02 为认证样板，但每个页面保留各自的任务与状态，不能直接复制表单。
家谱 G02--G12：先做空态/创建、家谱概览与世代字等代表页，再扩展搜索、申请、设置。
世系树 T01--T08：先建立树、成员档案、关系编辑三类代表页。
家族内容 F01--F10：动态、文章、相册、媒体上传分别建立内容档案式层级。
人物记录 R01--R11：人物档案、礼仪活动、成长时间线先定样板。
通知 N01--N02：区分未读、已读、时间和详情层级，不只依赖颜色。
我的 M01--M10：个人身份首页与安全设置先做，后续设置页按统一行式结构展开。

ModulePage.vue/page-catalog.js 中属于本轮模块的临时入口，必须在同一轮被真实页面替换并移除相应依赖；不得保留“新旧两套入口”或把通用壳伪称为精修完成。

每个模块的固定工作流

用 Product Design 对已运行页面截图审视，明确该模块与 A01/G01 的继承点、不同的信息结构与验收尺寸。
先补/改最小的页面契约测试并看到失败，再实现页面；只有缺少真实视觉资产时才生成资产。
资产生成后记录路径、尺寸、是否不透明、用途和引用页到 P00；生成图必须经过本地检查后进入 static/assets/。
保留既有可用跳转和返回行为，删除本轮替换后不再使用的临时导入、目录项和样式。
运行受影响的测试、编译审计、真实路由截图，再更新设计记录、规划和交接状态。
在用户验收之前，状态统一写“实现与截图完成，视觉待用户验收”。

7. 下一位 GPT 需要具备并实际调用的能力

这不是“只改 CSS”的任务。执行视觉页前应先读取对应技能说明，并在对用户的工作说明中指出正在使用的技能及目的。

能力/技能	何时使用	项目中的正确做法
`product-design:index`、`product-design:audit`	审视、评价或设计一个已运行页面/流程时。	先拿到真实路由截图，再依据 A01/G01 与页面任务写审视结论；不要靠源码猜好不好看。
Product Design 的 `user-context`、`get-context`、`ideate`、`image-to-code`、Design QA 流程	需要探索方向、选择视觉方案、将已选样稿落地、或交付前比对时。	有明确视觉真源时先忠实落地；没有真源且需要新方向时先给可比较方案，选定后再实现；最后在 `design-qa.md` 诚实记录通过或阻塞。
`imagegen`	现有资产无法承担完整视觉面时。	先用 A01/G01 实图作为参考，明确输出是完整不透明面板还是透明叠加件；检查实际尺寸/Alpha 后再放入项目。不能用截图代替资产。
`superpowers:brainstorming` 与 `superpowers:writing-plans`	新模块或会改变页面行为的创作工作开始前。	先写清用户目标、交互和验收，不以“尽快”跳过设计决定。
`superpowers:test-driven-development`	修改功能、路由契约、可审计视觉结构前。	先让最小契约测试失败，再做实现；视觉资产同样写尺寸/Alpha/引用审计。
`superpowers:systematic-debugging`	截图、路由、构建或测试出现意外时。	先复现和定位单一根因，禁止靠删测试、盲改样式掩盖问题。
`superpowers:verification-before-completion`	任何“完成/修好/通过”的表述前。	以命令输出、运行截图和用户确认作证据；不能用意图代替验证。

若新电脑没有 Product Design 或 ImageGen 插件，应先安装/启用同等能力；在能力缺失时不能假装完成视觉审计或资产生成。当前环境曾因 Windows 的 python/python3 只是商店占位符而无法保存 Product Design 的持久 context，这不影响当前项目文件和截图恢复；新环境若有可用 Python，可重新运行该插件的 context 预检。

8. 验证命令

先看工作区，再运行与改动相匹配的聚焦测试；模块阶段结束前运行全量 PowerShell 审计：

git status --short

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

A02 当前的最小回归集合：

powershell.exe -NoProfile -ExecutionPolicy Bypass -File tests/a02-asset-alpha-audit.ps1
powershell.exe -NoProfile -ExecutionPolicy Bypass -File tests/a01-a02-ui-contract.ps1
powershell.exe -NoProfile -ExecutionPolicy Bypass -File tests/compile-audit.ps1
powershell.exe -NoProfile -ExecutionPolicy Bypass -File tests/full-page-visual-contract.ps1
git diff --check

git diff --check 可能提示仓库既有的 CRLF 行尾警告；只有真正的空白错误或非零退出码才算失败。不要 reset、checkout、清空或覆盖用户已有改动。

9. 文档与资源维护清单

每次完成一个页面/模块，按事实更新：

docs/规划.md：用户验收状态与下一个模块。
docs/design/P00_页面结构与资产清单.md：新旧资产、尺寸、透明属性、引用位置与去留。
docs/design/<页面>_设计记录.md：设计意图、截图、交互与测试。
docs/design/screens/runtime/<日期>/：真实运行截图。
design-qa.md：修复项、未决项与最终 passed/blocked 结果。
docs/交接记录.md 与本手册：真实停点、风险、下一步；未获得用户确认就不能写成“已完成”。

当前工作区已经存在用户和历史任务的未提交改动。后续工作只能触及当前任务需要的文件；若改动与当前设计目标无关，只报告，不清理。

14 KiB Raw Blame History Unescape Escape