# G05 家谱总览设计记录

> 日期：2026-07-14  
> 状态：视觉候选已实现并完成本轮 Product Design 截图审计；未获用户审美确认，等待 G 模块完成后集中查看。

## 1. 技能与证据

- 已调用 `Product Design:index`，将任务路由为现有产品的 `audit`、`get-context` 与实现后设计检查。
- 已调用 `Product Design:audit`，以本轮新截的真实 H5 画面为证据，不用旧截图代替。
- 已调用 ImageGen 生成完整不透明位图表面；没有用 CSS 伪造卡片、边框或装饰。
- 改前证据：`screens/runtime/2026-07-14/g-module-audit/before/01-g05-before-360x800.png`。
- 改后证据：`screens/runtime/2026-07-14/g-module-audit/g05/01-g05-ready-360x800.png`、`02-g05-empty-360x800.png`、`03-g05-error-360x800.png`、`04-g05-ready-412x915.png`。
- 同画布对照：`screens/runtime/2026-07-14/g-module-audit/g05/05-g05-before-after-comparison.png`，左侧改前、右侧改后；所有判断均基于这张合并输入，不把两个分离预览冒充并排比较。

## 2. 产品与思维导图参考

外部只读参考位于 `C:\Users\Rain\Desktop\软件\JOB\app设计`。已查看 `思维导图.png`、`家谱主页.png`、`加入家谱.png` 与 `字辈谱.png`。

采用的只有信息结构：谱名、堂号、地点和成员概况置顶；世系、录入、字辈、审核作为核心入口；家族内容作为下一层。没有采用外部灰绿色卡片、现代图标、邀请码加入或底部双按钮视觉。

外部“邀请码加入”与当前产品不一致。当前唯一加入流程是 G06 公开检索 → G08 提交申请 → G09 查看进度 → G10 管理员审核，因此不把邀请码或邀请按钮加入 G05。

## 3. 路由与状态所有权

- 唯一路由：`pages/genealogy/g05-genealogy-overview`。
- 唯一上下文查询键：`genealogyId`；G01 的旧 `id` 链接已同步迁移，不保留兼容读取。
- 同页状态：`loading`、`ready`、`empty`、`error`，不为加载、空数据、无权或失败另建页面。
- “录入族人”进入 G03 `step=ancestor&genealogyId=...`；已删除的 G04 不再被引用。
- G05 不再把 G08 申请加入表单误写成管理员的“邀请亲人”。

## 4. OpenAPI 设计边界

| 页面内容/动作 | OpenAPI 依据 | 页面阶段处理 |
| --- | --- | --- |
| 谱名、堂号、地区、成员数、可见范围 | `GET /genealogy/app/genealogies/{genealogyId}/overview` | 正常态展示真实接口所需字段；本轮继续使用现有 mock |
| 管理设置 | `GET/PUT /genealogy/app/genealogies/{genealogyId}` | 只进入 G11，不在 G05 复制设置表单 |
| 世系树 | `GET /genealogy/app/genealogies/{genealogyId}/lineage/tree` | 进入 T01，不在总览加载完整树 |
| 录入首代 | `POST /genealogy/app/genealogies/{genealogyId}/lineage/persons` | 进入 G03 的始祖步骤 |
| 字辈谱 | `GET/POST /genealogy/app/genealogies/{genealogyId}/generation-poems` | 进入 G12 |
| 入谱审核 | `GET .../join-applies/pending`、`PUT .../{applyId}/audit` | 进入 G10 |

接口响应仍使用通用 `JsonObject/ListResult`，因此页面不臆造邀请码、分享码、视频或多级管理员字段。

## 5. 位图资产

- 最终资产：`static/assets/modules/genealogy/opaque/g05-overview-surface.png`。
- 尺寸：1122×1506；`Format24bppRgb`，四角 alpha 均为 255。
- 内容：墨蓝谱名区、四个完整宣纸入口槽、古金分隔、底部访问说明面；文字和点击层不烘焙进图片。
- ImageGen 使用 `ui-mockup` 模式，参考 G05 改前 360×800 截图，明确要求无文字、无图标、无占位符、无现代玻璃拟态。

## 6. Product Design 审计

### 改前主要风险

1. G05 的“录入族人”指向已删除 G04，核心动作实际不可达。
2. “邀请亲人”跳到申请者填写的 G08，角色和任务语义错误；OpenAPI 也没有邀请端点。
3. 深色头、四宫格卡片和底部邀请面均由 CSS 拼接，不符合完整视觉表面必须使用位图的项目规则。
4. 只有模糊载入文案，没有区分空数据、无权限和加载失败。

### 改后步骤与健康度

1. `ready`：健康。谱名和成员概况在墨蓝区，四个核心任务在首屏可见，家族近况和访问说明层级清楚。
2. `empty`：健康。仍在 G05 路由内说明缺少上下文，并返回“我的家谱”。
3. `error`：健康。说明网络、数据或权限三类可能原因，提供同页重试。
4. 412×915：健康。位图、文字和点击槽同步放大，没有横向溢出或裁切。

### 可访问性边界

- 本轮从截图确认了文字未裁切、主要入口具有完整卡片面积、按钮文案可见。
- 审计后已提高谱名区元信息、入口说明、近况和底部说明字号，降低 360 宽屏小字风险。
- 截图不能证明读屏语义、键盘焦点和 Android 字体放大行为；这些留到真机与可访问性专项验证，不能宣称完整 WCAG 合规。

## 7. 验证

- `tests/g05-overview-contract.ps1`
- `tests/g05-overview-runtime-smoke.js`
- `tests/g01-visual-contract.ps1`

以上在实现后均已通过；最终集中审美确认前不将 G05 标记为视觉冻结。