210 lines
16 KiB
Markdown
210 lines
16 KiB
Markdown
# 家谱 APP 视觉设计交接手册
|
||
|
||
> 更新日期：2026-07-14
|
||
> 用途：在新电脑或交给新的 GPT 后，按本手册恢复当前工作；它只记录已发生的事实，不把待验收写成已完成。
|
||
|
||
## 0. 给新 GPT 的可直接执行指令
|
||
|
||
你接手的是一个 **uni-app Android 家谱项目的高质量视觉设计任务**，全程中文工作；它不是只改 CSS 的任务。先不修改代码，完整阅读：`AGENTS.md`、`docs/交接记录.md`、本手册、`docs/规划.md`、`docs/design/D1_安卓视觉规范与页面壳.md`、`docs/design/P00_页面结构与资产清单.md`、`docs/superpowers/plans/2026-07-13-product-design-visual-refinement.md`、`design-qa.md`。随后只向用户简洁复述当前停点和准备如何处理反馈。
|
||
|
||
必须保留已有未提交改动；不使用 worktree 或多代理；不执行 `git add`、`git commit`、`git push`、上传、`git reset` 或 `git checkout`。A01、A02、A04、A05、A06、G01、G03 的可见效果已获用户验收并冻结，不能以重构或顺手优化的名义改变。G07 是 G06 的页面内状态，不得重新建为独立页。
|
||
|
||
用户已授权先完成全部页面候选、后集中审核。54 条最终路由均已覆盖：7 个已验收冻结，其余 47 个统一标 `[~]`；不得把候选写成用户已验收。下一阶段由用户按规划逐页勾选，接口只作功能布局参考，本轮没有对接。
|
||
|
||
新环境必须可用并实际调用：`product-design:index`、`product-design:audit`、`imagegen`、`superpowers:test-driven-development`、`superpowers:systematic-debugging`、`superpowers:verification-before-completion`。没有这些能力时，先安装/启用同等能力，不得假装已经完成设计审视或位图生成。
|
||
|
||
## 1. 当前停点：先看这一节
|
||
|
||
项目已有 54 条最终编号路由；T02 已收敛到 T01 同页状态。这不等于 54 个页面已完成视觉验收。
|
||
|
||
- 用户已经验收的视觉基准有七个：**A01 启动/登录引导**、**A02 账号登录**、**A04 注册账号**、**A05 重置密码**、**A06 登录状态**、**G01 我的家谱**、**G03 创建家谱**。它们的可见效果已冻结。
|
||
- **A02 账号登录**已经完成资产化重做、功能回归和多尺寸截图，并于 2026-07-14 获用户审美验收。A03 已删除；A02 的短信 Tab 是唯一手机号验证码登录入口。A04、A05、A06 均于同日完成独立重做并获用户审美验收；G02 已按用户确认合并为 G01 的 `?state=empty`；G04 已合并为 G03 的 `?step=ancestor`；G07 已合并为 G06 的初始／结果／无结果状态。G06 三态候选截图和内部审视已经完成，但尚未获得用户视觉验收。
|
||
- G05、G06、G08–G12、T01、T03–T08、F01–F10、R01–R11、N01–N02、M01–M10 已完成候选截图和审视；共享 `ModulePage.vue` 已升级为全位图高规格母版，不再是旧 CSS 过渡壳。
|
||
- 不提交、不推送、不上传 Git；由用户自行处理版本库操作。
|
||
|
||
下一位执行者先读取当前停点与已验收页面，然后按 `docs/规划.md` 的 `[~]` 清单协助用户逐页审核。默认只从 `docs/design/视觉证据索引.md` 打开一张代表图或一张状态联系表；多尺寸、before/after 与历史废稿仅在发现问题时展开。旧 `G06-no-panel-*` 图只能帮助理解迭代原因，不能用于当前验收。全部 47 个候选都等待用户逐页确认，不再按模块批量推进新页面。
|
||
|
||
## 1.1 迁移前必须保留的文件
|
||
|
||
本手册、G06 最终候选资产和截图工具均是接管所需文件；换电脑前，用户需在自行提交/上传时包含它们，或完整复制当前工作区。我没有执行任何 Git 暂存、提交、推送或上传操作。
|
||
|
||
至少要保留：`docs/design/视觉设计交接手册.md`、`docs/交接记录.md`、`docs/design/视觉证据索引.md`、`scripts/capture-chrome-page.js`、全部页面/资产/测试、`docs/design/screens/runtime/` 的运行证据，以及现有计划与设计记录。只复制已提交的旧版本会丢失当前停点。
|
||
|
||
## 2. 必读文件与唯一职责
|
||
|
||
| 文件 | 负责什么 |
|
||
| --- | --- |
|
||
| `AGENTS.md` | 最小修改、保护既有未提交内容、验证后再交付的项目规则。 |
|
||
| `docs/规划.md` | 54 条独立路由的范围、模块顺序和“完成”的定义。 |
|
||
| `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: accepted`。 |
|
||
| `docs/交接记录.md` | 简版当前状态与恢复入口；本手册提供完整操作细节。 |
|
||
|
||
发生冲突时，按“用户最新明确指令 > AGENTS.md > 上表中的当前台账/计划 > 历史文档”的顺序处理。不要以旧的草案或已废弃的截图切片方案为依据。
|
||
|
||
## 3. 已验收的风格与绝对禁区
|
||
|
||
### A01 与 G01 是可观察的品牌真源
|
||
|
||
- A01 参考图：`docs/design/screens/A01-启动登录引导-栅格验收-412x915.png`
|
||
- G01 参考图：`docs/design/screens/G01-我的家谱-紧凑版设计稿-v5-Tabbar安全区.png`
|
||
|
||
共同语言是“家祠卷轴”：暖宣纸、朱砂主色、古金框线和元数据、墨褐字、低对比淡墨山水。主信息应先于背景被读到，留白是结构的一部分。
|
||
|
||
必须遵守：
|
||
|
||
1. 完整按钮、卡片、标题签、页面头图和有边框的装饰面，使用完整的**不透明位图资产**承载底色、纹理和边框。
|
||
2. 透明 PNG 仅承担 Logo、图标、祥云、纹样等叠加元素；CSS 只承担布局、文字、状态与交互，不能伪造完整框、祥云、按钮或卡片。
|
||
3. 不能把整张设计截图或局部截图裁进运行页面；运行资产必须是可复用的独立元素。
|
||
4. 不要修改 A01/G01 已验收的可见布局、比例、配色或装饰。可读其实现和资产，但不能借“整理”改变效果。
|
||
5. 不要用一个通用卡片母版覆盖所有模块。家谱、世系树、内容档案、人物记录、通知和设置必须在同一视觉语言下有各自的信息密度与层级。
|
||
|
||
## 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/handoff/2026-07-13/A02-after-360x800.png`。小屏、大屏、短信状态和 before/after 证据保存在项目外完整归档中，按需展开，不在交接正文连续罗列。
|
||
|
||
### 通过/未通过的界线
|
||
|
||
已通过的是：资产尺寸与不透明角审计、A01/A02 页面契约、编译检查、A02 的多尺寸运行截图和短信 Tab 交互。
|
||
|
||
已通过的是：用户对 A02 的最终审美确认，`design-qa.md` 为 `accepted`，A02 可见效果冻结。用户若提出新的明确调整，只改动被指出的区域并重新截图复核；不要无根据改动面板框、输入区或交互。
|
||
|
||
## 5. 换电脑后如何恢复截图与审视能力
|
||
|
||
### 必备环境
|
||
|
||
- Windows、Chrome、HBuilderX（项目当前以 Android `uni-app` 为目标）。
|
||
- Node.js 22 或更高版本；当前脚本已在 Node 24 环境使用原生 `fetch` 与 `WebSocket`。
|
||
- 先在 HBuilderX 启动本地 H5 调试页，并确认它能在 `http://localhost:5173` 打开。不要臆测项目的 npm 启动命令。
|
||
|
||
用专用 Chrome 调试实例开启远程端口；它与用户日常 Chrome 隔离：
|
||
|
||
```powershell
|
||
$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'
|
||
```
|
||
|
||
确认调试端口与应用页面存在：
|
||
|
||
```powershell
|
||
Invoke-RestMethod 'http://127.0.0.1:9222/json/list' | Select-Object title, url
|
||
```
|
||
|
||
使用项目内的正式脚本截图。它会导航**专用调试 Chrome**的当前标签页、写出 PNG，并在结束时清除设备尺寸覆盖；不能操作或关闭用户的日常 Chrome。
|
||
|
||
```powershell
|
||
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、412 × 915，多状态页面优先合成一张联系表。用户确认需要长期交接时，只把代表图复制到 `docs/design/screens/handoff/`。最终 Android/HBuilderX 截图仍需补做，H5 Chrome 截图不能替代它。
|
||
|
||
## 6. 后续执行顺序与每轮产物
|
||
|
||
### 门禁 0：A02 与 A04 已通过
|
||
|
||
1. A02 与 A04 均已通过；不因后续页面改动而触碰其可见效果。
|
||
2. 若用户提出明确调整：只在对应页面修正，先调整对应契约测试，再改页面/资产，重新截图复核。
|
||
3. A05、A06 与 G01 空状态均已通过并完成状态同步；G04 已合并为 G03 `step=ancestor`，该双步骤已获用户通过；G07 已合并为 G06 三态。G06 三态候选和内部审视已完成，仍待用户视觉确认。
|
||
|
||
### 当前唯一顺序：逐页视觉审核
|
||
|
||
54 条路由候选已经全部覆盖。用户从 `docs/规划.md` 指定或按清单顺序审核页面；只有用户明确通过才改 `[x]`，要求返工则改 `[!]` 并只修改对应页面。接口、Android 打包和真机复核均留在视觉审核之后。
|
||
|
||
### 每个模块的固定工作流
|
||
|
||
1. 用 Product Design 对已运行页面截图审视，明确该模块与 A01/G01 的继承点、不同的信息结构与验收尺寸。
|
||
2. 先补/改最小的页面契约测试并看到失败，再实现页面；只有缺少真实视觉资产时才生成资产。
|
||
3. 资产生成后记录路径、尺寸、是否不透明、用途和引用页到 P00；生成图必须经过本地检查后进入 `static/assets/`。
|
||
4. 保留既有可用跳转和返回行为，删除本轮替换后不再使用的临时导入、目录项和样式。
|
||
5. 运行受影响的测试、编译审计、真实路由截图，再更新设计记录、规划和交接状态。
|
||
6. 在用户验收之前，状态统一写“实现与截图完成，视觉待用户验收”。
|
||
|
||
## 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 插件，应先安装/启用同等能力；在能力缺失时不能假装完成视觉审计或资产生成。新环境先执行 `python --version`、`node --version` 确认可用环境；当前用户已确认 Python 已安装。若 Product Design 的持久 context 预检仍失败，记录原因即可，不得阻塞对项目内真实截图、资产和测试的接管。
|
||
|
||
## 8. 验证命令
|
||
|
||
先看工作区，再运行与改动相匹配的聚焦测试；模块阶段结束前运行全量 PowerShell 审计：
|
||
|
||
```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
|
||
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
|
||
```
|
||
|
||
G06 当前候选继续或验收前的最小回归集合：
|
||
|
||
```powershell
|
||
powershell.exe -NoProfile -ExecutionPolicy Bypass -File tests/g06-search-flow-contract.ps1
|
||
node tests/g06-search-flow-runtime-smoke.js http://localhost:5173
|
||
node scripts/capture-chrome-page.js "http://localhost:5173/#/pages/genealogy/g06-search-genealogies" ".search-page" "docs/design/screens/runtime/<日期>/G06-selected-strip-initial-360x800.png" 360 800
|
||
git diff --check
|
||
```
|
||
|
||
若 G06 发生视觉改动，必须用真实输入分别截取有结果和无结果状态，再用 Product Design 审视；只有三态、相关测试与用户确认齐全，才能更新为验收通过。
|
||
|
||
`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` 与本手册：真实停点、风险、下一步；未获得用户确认就不能写成“已完成”。
|
||
|
||
当前工作区已经存在用户和历史任务的未提交改动。后续工作只能触及当前任务需要的文件；若改动与当前设计目标无关，只报告，不清理。
|