「好学云谱」液态玻璃家谱软件策划文档

版本：v1.0 · 日期：2026-07-03 · 产品代号：Yunpu（好学云谱）定位：一款账号保护、强隐私、高颜值的全功能家庭/家族谱系管理软件

一、项目概述

1.1 一句话定位

「好学云谱」是一款以**液态玻璃（Liquid Glass）**视觉语言打造的家谱管理工具，支持多家族管理、世代树可视化、成员全息档案、事件时间线、统计洞察与标准家谱数据互通。产品入口必须账号登录；Docker 后端承担统一云端数据中心，Web、手机端、电脑端登录同一账号后共享同一套谱牒数据。

1.2 核心价值

维度	价值主张
功能完整	覆盖家谱采集、整理、可视化、传承、导出的全生命周期
隐私优先	账号用于身份验证，家谱资料默认保存在当前设备浏览器中
颜值即生产力	液态玻璃质感界面，毛玻璃、折射、动效、明暗主题
即装即用	Web/桌面由本项目服务提供静态资源与账号认证代理；移动端需配置认证 API
跨平台	浏览器即开即用，适配桌面/平板/移动端

1.3 目标用户

普通家庭用户（记录家庭关系、纪念先人）
家族/宗族修谱人（整理大族世系、数字化老谱）
族谱文化爱好者、历史研究者
想给长辈留一份"看得见"家族记忆的人

二、功能需求（齐全度目标）

2.1 功能全景图

好学云谱
├── 家族工作区
│   ├── 多家族管理（创建/切换/归档/删除）
│   ├── 家族元信息（堂号/郡望/始祖/源流/家训）
│   └── 概览仪表盘（人口/世代/统计）
├── 成员档案（全息）
│   ├── 基本信息（姓名/字号/性别/生卒/籍贯/民族/职业）
│   ├── 头像与相册（多图）
│   ├── 生平传记（富文本）
│   ├── 关系网（父/母/配偶/子女/兄弟姐妹）
│   ├── 事件时间线（出生/婚嫁/迁徙/升学/逝世/自定义）
│   └── 备注 & 标签
├── 谱系可视化（核心）
│   ├── 世系树（横向展开，缩放/平移/居中/小地图）
│   ├── 世代列表（按辈分分组）
│   ├── 宝塔图（纵向世系）
│   ├── 列表视图（表格，支持排序/筛选/分页）
│   └── 关系检索（血缘路径、亲等计算）
├── 检索与统计
│   ├── 多条件搜索（姓名/字号/世代/性别/生卒/标签）
│   ├── 统计洞察（性别比/平均寿命/代际间隔/人口曲线）
│   └── 数据看板（可视化图表）
├── 数据互通
│   ├── JSON 导入/导出（全量备份）
│   ├── GEDCOM 导入/导出（国际标准家谱格式）
│   ├── 头像/相册资源管理
│   └── 版本快照与撤销
└── 系统体验
    ├── 明暗主题 + 多玻璃色调
    ├── 字号/动效可调节（无障碍）
    ├── 国际化骨架（中/英）
    └── 引导与帮助

2.2 功能清单（详细需求矩阵）

模块	编号	功能点	优先级	完成标准
家族	F-01	创建家族（堂号/始祖/源流/家训）	P0	可创建并持久化
家族	F-02	多家族切换与归档	P0	侧边栏可切换
家族	F-03	家族概览仪表盘	P1	展示人口/世代/图表
成员	F-04	新增成员（含关系绑定）	P0	完整字段持久化
成员	F-05	编辑/删除成员	P0	删除前二次确认
成员	F-06	成员详情面板	P0	全息信息展示
成员	F-07	头像上传（本地压缩）	P1	自动压缩缩略图
成员	F-08	相册（多图管理）	P2	上传/查看/删除
成员	F-09	富文本生平传记	P1	所见即所得编辑
关系	F-10	父母/配偶/子女关系	P0	双向一致性校验
关系	F-11	血缘路径与亲等计算	P1	给出最近共同祖先
视图	F-12	世系树（SVG，缩放/平移）	P0	流畅可交互
视图	F-13	世代列表	P0	按辈分聚合
视图	F-14	宝塔图	P1	纵向布局
视图	F-15	成员列表（排序/筛选/分页）	P0	多列可排序
事件	F-16	事件时间线	P1	可增删事件
事件	F-17	自定义事件类型	P2	用户可扩展
搜索	F-18	全局搜索 + 高级筛选	P0	实时检索
统计	F-19	统计图表看板	P1	图表可视化
数据	F-20	JSON 导入/导出	P0	全量无损
数据	F-21	GEDCOM 导入/导出	P1	兼容主流软件
数据	F-22	快照备份与恢复	P2	一键回滚
系统	F-23	明暗主题 + 玻璃色调	P0	平滑切换
系统	F-24	响应式（桌面/平板/移动）	P0	关键页可用
系统	F-25	无障碍（字号/动效/键盘）	P1	可调节

完成标准：P0/P1 全部实现且通过自测，P2 视情况交付。

三、UI/UX 设计规范（液态玻璃 Liquid Glass）

3.1 设计理念

继承 Apple Liquid Glass 美学：半透明、模糊、边缘折射、悬浮层次、动态光泽。界面如同层层悬浮的玻璃面板，内容"浮"于背景之上，既有未来感又保留东方家谱的庄重典雅。

3.2 视觉要素

① 玻璃面板（Glass）

backdrop-filter: blur(24px) saturate(180%)
半透明白/黑叠色（亮色 rgba(255,255,255,.55)，暗色 rgba(20,22,30,.55)）
1px 半透发光描边（inset 高光 + 渐变 border）
多层柔和投影（近/中/远）

② 动态背景（Aurora 极光）

全屏缓慢流动的彩色光晕（3–4 个径向渐变 blob）
随主题切换颜色基调（青/紫/金/朱）
prefers-reduced-motion 时静止

③ 节点卡片（成员节点）

玻璃胶囊，头像 + 姓名 + 世代标
悬停上浮 + 边缘高光增强
选中态：环形发光描边

④ 圆角与间距

基础圆角阶梯：8 / 14 / 20 / 28 / 999（胶囊）
间距 4 的倍数节奏

⑤ 排版

标题：思源宋体 / Noto Serif SC（家谱典雅感）
正文：思源黑体 / Noto Sans SC / 系统字体
数字：等宽数字

3.3 色彩系统（多主题）

主题	主基调	强调色
晨曦（浅·青）	青蓝极光	#2f7df6
朱砂（浅·暖）	金红极光	#d4604a
墨韵（深·靛）	深靛极光	#6d8bff
夜阑（深·紫）	深紫极光	#b07cff

3.4 动效

过渡：cubic-bezier(.22,.61,.36,1)，180–280ms
入场：淡入 + 轻微上移/缩放
玻璃层 hover：边光呼吸
树交互：拖拽/缩放惯性

四、技术架构

4.1 技术选型与理由

层	选型	理由
渲染	原生 HTML + CSS + 原生 JS (ES Module)	前端零构建；需配合云端数据中心进入工作台；液态玻璃用现代 CSS 即可表达
存储	IndexedDB（封装 Promise）	容量大、异步、结构化；适合多家族/多成员/多图片
图表/树	原生 SVG + 自研布局算法	矢量清晰、可缩放、可交互；世系树布局自主可控
富文本	内嵌轻量 `contenteditable` 编辑器	零依赖
打包/构建	Docker 数据中心 + 客户端打包	`server.js` 提供静态资源、账号认证与 `/api/sync/state` 云端数据 API；手机/电脑端可在登录页填写云端地址

结论：单页应用（SPA） + 账号认证 + 本机数据存储。账号负责准入，家谱资料仍需用户主动备份。

4.2 目录结构

d:\jiapu
├── index.html                 # 入口（引入所有模块）
├── css/
│   ├── tokens.css             # 设计 token（颜色/间距/玻璃变量）
│   ├── glass.css              # 液态玻璃核心样式
│   ├── components.css         # 组件（按钮/卡片/模态/Toast/表单）
│   ├── tree.css               # 谱系树样式
│   └── responsive.css         # 响应式与无障碍
├── js/
│   ├── main.js                # 应用入口、路由、初始化
│   ├── store/                 # 状态管理（发布订阅）
│   │   ├── state.js
│   │   └── events.js
│   ├── data/                  # 数据层
│   │   ├── db.js              # IndexedDB 封装
│   │   ├── repository.js      # 仓储（家族/成员/事件）
│   │   └── sample.js          # 示例数据
│   ├── core/                  # 核心算法
│   │   ├── graph.js           # 家族图与关系算法
│   │   ├── layout.js          # 世系树布局算法
│   │   └── kinship.js         # 亲等/血缘路径计算
│   ├── ui/                    # UI 组件
│   │   ├── shell.js           # 整体框架/侧边栏/顶栏
│   │   ├── components.js      # 通用组件工厂
│   │   ├── modal.js
│   │   ├── toast.js
│   │   └── theme.js
│   ├── views/                 # 页面视图
│   │   ├── families.js        # 家族工作区
│   │   ├── dashboard.js       # 仪表盘
│   │   ├── tree.js            # 世系树视图
│   │   ├── generations.js     # 世代列表
│   │   ├── pagoda.js          # 宝塔图
│   │   ├── members.js         # 成员列表
│   │   ├── statistics.js      # 统计
│   │   ├── member-detail.js   # 成员详情
│   │   └── settings.js        # 设置/导入导出
│   ├── render/                # SVG 渲染器
│   │   └── svg.js
│   ├── io/                    # 导入导出
│   │   ├── json.js
│   │   └── gedcom.js
│   └── utils/
│       ├── date.js
│       ├── dom.js
│       └── id.js
├── docs/
│   └── 策划文档.md
└── README.md

4.3 架构分层（数据流）

视图层 Views ──调用──▶ 状态 Store(发布订阅) ──调用──▶ 仓储 Repository
      ▲                                                       │
      └────────── 状态变更通知(re-render) ◀── publish ──────┘
                                                            │
                              IndexedDB ◀── 读写 ────────────┘

单向数据流：视图只读 Store，变更经 Repository 落库后发布事件，视图订阅重渲染。
纯函数算法：graph/layout/kinship 为纯函数，便于测试与复用。

五、数据模型设计

5.1 核心实体（IndexedDB Object Stores）

Family（家族）

jsonc

{
  "id": "fam_xxx",
  "name": "李氏宗族",        // 家族名
  "tanghao": "陇西堂",       // 堂号
  "junwang": "陇西郡",       // 郡望
  "origin": "始祖李利贞...", // 源流
  "motto": "忠孝传家",       // 家训
  "rootMemberId": "mem_xxx", // 始祖（第一世）
  "namingRule": "字辈：…",   // 字辈谱
  "createdAt": 0, "updatedAt": 0
}

Member（成员）

jsonc

{
  "id": "mem_xxx",
  "familyId": "fam_xxx",
  "name": "李世民",
  "courtesyName": "字：世民", // 字号
  "alias": "别号/小名",
  "gender": "male|female|unknown",
  "alive": true,
  "birth": {"date":"0598-01-28","solar":true,"place":"长安"},
  "death": {"date":"0649-07-10","place":"...","cause":""},
  "generation": 1,            // 第几世
  "generationName": "世",     // 字辈字（可选）
  "fatherId": null,
  "motherId": null,
  "spouseIds": [],
  "childrenIds": [],
  "hometown": "陇西", "nation":"汉","occupation":"皇帝",
  "avatar": "data:image/...", "gallery": [],
  "bio": "<富文本>", "tags": [], "note":"",
  "createdAt":0,"updatedAt":0
}

Event（事件）

jsonc

{ "id":"evt_xxx","memberId":"mem_xxx","familyId":"fam_xxx",
  "type":"birth|marriage|death|migration|education|promotion|custom",
  "title":"","date":"...","place":"","desc":"","createdAt":0 }

5.2 关系一致性

父/母：fatherId/motherId；其父/母的 childrenIds 必须反向含本成员。
配偶：spouseIds 双向对称。
删除成员：拦截依赖，提示并清理引用（或转孤节点）。
世代计算：generation = max(父generation, 母generation) + 1，始祖 = 1。

六、信息架构（页面与导航）

顶栏：家族选择器 │ 全局搜索 │ 主题/设置
侧边栏（玻璃胶囊）：
  · 概览  Dashboard
  · 世系  Tree（默认）
  · 世代  Generations
  · 宝塔  Pagoda
  · 名录  Members
  · 统计  Statistics
  · 设置  Settings（导入导出/主题/关于）
主内容区：根据路由切换

七、里程碑与开发计划

里程碑	内容	产出
M0 策划	本文档	策划文档.md
M1 骨架	入口 + 设计系统 + 框架	可见玻璃界面外壳
M2 数据层	IndexedDB + 仓储 + 状态 + 示例数据	可读写持久化
M3 家族&成员	家族工作区 + 成员CRUD + 详情面板	可录入真实数据
M4 谱系树	图算法 + 布局 + SVG 渲染 + 交互	世系树可用
M5 多视图	世代/宝塔/名录/统计/时间线	视图齐全
M6 数据互通	JSON/GEDCOM + 快照 + 头像	可迁移备份
M7 打磨上线	响应式/无障碍/测试/README	完整上线版本

八、测试与质量策略

算法单测：generation 计算、亲等、血缘路径（控制台 Yunpu.test() 暴露，自检）。
集成自测：示例数据加载 → 树渲染 → CRUD → 导出回环。
兼容性：Chrome/Edge/Safari/Firefox 现代版（backdrop-filter 支持）。
降级：不支持 backdrop-filter 时回退实色。

九、上线与部署方案

本地预览：node server.js，通过 http://localhost:5173 访问。
Web 部署：部署 server.js，由它同时提供静态资源与账号认证代理。
Android APK：用户在登录页填写可访问的 Docker 云端数据中心地址；YUNPU_CLOUD_URL 仅用于预填默认值。
Windows 桌面：使用 Electron 解压版或便携包，启动前清理 ELECTRON_RUN_AS_NODE 环境变量。
PWA 离线：仅限已登录并通过验证的同一会话继续使用缓存应用；联网后继续与 Docker 数据中心同步。

十、风险与应对

风险	影响	应对
家族数据复杂致布局错乱	树渲染乱	分支合并 + 折叠子树算法
大族性能（>5000 人）	卡顿	虚拟化列表 + 按需渲染子树
浏览器兼容	玻璃失效	feature 检测回退
数据误删	数据丢失	删除二次确认 + JSON 快照恢复
GEDCOM 方言差异	导入不全	宽松解析 + 字段映射表

十一、交付验收标准（上线完整版定义）

[x] P0/P1 功能全部实现
[x] 液态玻璃 UI 落地，明暗 + 多色调
[x] 数据本地持久化，刷新不丢
[x] 世系树流畅可交互（缩放/平移/居中/点击）
[x] 导入导出闭环（JSON 全量 + GEDCOM）
[x] 响应式适配
[x] README 上线说明 + 一键启动脚本
[x] 自测通过

本文档为「好学云谱」v1.0 策划基线，后续迭代以版本号管理。

「好学云谱」液态玻璃家谱软件 策划文档 ​

一、项目概述 ​

1.1 一句话定位 ​

1.2 核心价值 ​

1.3 目标用户 ​

二、功能需求（齐全度目标） ​

2.1 功能全景图 ​

2.2 功能清单（详细需求矩阵） ​

三、UI/UX 设计规范（液态玻璃 Liquid Glass） ​

3.1 设计理念 ​

3.2 视觉要素 ​

3.3 色彩系统（多主题） ​

3.4 动效 ​

四、技术架构 ​

4.1 技术选型与理由 ​

4.2 目录结构 ​

4.3 架构分层（数据流） ​

五、数据模型设计 ​

5.1 核心实体（IndexedDB Object Stores） ​

5.2 关系一致性 ​

六、信息架构（页面与导航） ​

七、里程碑与开发计划 ​

八、测试与质量策略 ​

九、上线与部署方案 ​

十、风险与应对 ​

十一、交付验收标准（上线完整版定义） ​

「好学云谱」液态玻璃家谱软件策划文档

一、项目概述

1.1 一句话定位

1.2 核心价值

1.3 目标用户

二、功能需求（齐全度目标）

2.1 功能全景图

2.2 功能清单（详细需求矩阵）

三、UI/UX 设计规范（液态玻璃 Liquid Glass）

3.1 设计理念

3.2 视觉要素

3.3 色彩系统（多主题）

3.4 动效

四、技术架构

4.1 技术选型与理由

4.2 目录结构

4.3 架构分层（数据流）

五、数据模型设计

5.1 核心实体（IndexedDB Object Stores）

5.2 关系一致性

六、信息架构（页面与导航）

七、里程碑与开发计划

八、测试与质量策略

九、上线与部署方案

十、风险与应对

十一、交付验收标准（上线完整版定义）