有数据库架构及动画特效开发经验 远程兼职

# 成语+歇后语星云知识库开发文档

## 1. 项目目标

目标是开发一个模拟星系运行的”星云视图气质的成语+歇后语知识库：用星云节点承载成语、歇后语、关键词、首字/次字/末字索引关系；可拖动面板、搜索、筛选、设置与高性能星云渲染作为交互基础。

第一版重点不是做传统列表词典，而是做一个可浏览、可检索、可扩展、可自造内容的星云知识库。用户可以通过顶部搜索框、左侧长度/类型分区、底部字位检索、直接点击星云节点来查看成语或歇后语的释义、出处、例句和关联内容。

## 2. 联网语料调研结论

优先语料源建议采用 `pwxcoo/chinese-xinhua`，仓库说明其包含 31648 个成语和 14032 条歇后语，并提供 `data/idiom.json` 和 `data/xiehouyu.json` 数据文件。该仓库 README 示例显示，成语字段包含 `word`、`pinyin`、`abbreviation`、`explanation`、`derivation`、`example`；歇后语字段包含 `riddle`、`answer`。

数据源链接：

- GitHub 仓库：https://github.com/pwxcoo/chinese-xinhua
- 成语数据：https://github.com/pwxcoo/chinese-xinhua/blob/master/data/idiom.json
- 歇后语数据：https://github.com/pwxcoo/chinese-xinhua/blob/master/data/xiehouyu.json

版权与数据策略：

- 仓库标注 MIT license，但 README 也说明数据来自网上收集整理，且“无任何商业目的”。因此第一版建议仅作为本地/研究/原型语料使用。
- 如果项目未来公开发布或商业化，需要补充数据授权审查，或替换为明确授权的数据源。
- 成语数据可直接进入“释义+出处+例句”面板。
- 歇后语数据原始字段只有谜面和答案，第一版释义可由 `answer` 作为基础解释；出处字段置为“基础语库/未标注”，后续通过补充脚本、人工编辑或用户自造面板完善。

## 3. 推荐工程结构

请借鉴星云视图生成结构`

## 4. 核心数据模型

统一条目模型用于同时承载成语、歇后语和用户自造歇后语。

```ts
type NebulaEntry = {
id: string;
type: "idiom" | "xiehouyu" | "user-xiehouyu";
title: string;
displayText: string;
lengthBucket: "3" | "4" | "5" | "6" | "7" | "8plus" | "idiom";
chars: string[];
firstChar: string;
secondChar: string;
thirdChar: string;
fourthChar: string;
fifthChar: string;
lastChar: string;
pinyin?: string;
abbreviation?: string;
explanation: string;
derivation: string;
example?: string;
riddle?: string;
answer?: string;
sourceType: "base" | "user";
sourceName: string;
createdAt?: string;
updatedAt?: string;
tags: string[];
};
```

归一化规则：

- 成语：`title = word`，`displayText = word`，`type = idiom`，`explanation = explanation`，`derivation = derivation || "未标注"`。
- 歇后语：`title = riddle`，`displayText = riddle + " - " + answer`，`type = xiehouyu`，`explanation = answer`，`derivation = "基础歇后语库/未标注"`。
- 用户自造歇后语：`type = user-xiehouyu`，必须包含 `riddle`、`answer`、`explanation`、`sourceName`，允许用户补充出处、标签和备注。
- 长度分区优先按 `title` 的中文字符数量计算；成语额外进入“成语”分区。

## 5. 五个主要功能模块

### 5.1 顶部标题面板：搜索框+设置

功能定位：

- 作为全局入口，承载项目标题、搜索框、设置按钮、当前数据规模摘要。
- 保持星系视图轻量式悬浮面板，不压住星云主体。

组件内容：

- 标题：`成语歇后语星云`
- 副标题：`成语 / 歇后语 / 自造语库`
- 搜索框：支持输入汉字、拼音、缩写、谜面、答案、释义关键词。
- 设置按钮：打开画质、速度、显示密度、是否显示自造条目、是否显示连线等基础设置。

搜索流程：

- 输入为空：展示当前筛选下的全局星云。
- 输入单字：触发字位索引高亮，显示包含该字的成语/歇后语。
- 输入多字短语：优先精确匹配 `title/displayText`，其次匹配释义、出处、例句。
- 输入拼音或缩写：仅对成语优先匹配 `pinyin/abbreviation`，歇后语可后续扩展拼音索引。

### 5.2 左侧分区面板：长度+类型分区

分区按钮：

- `ALL`
- `3字`
- `4字`
- `5字`
- `6字`
- `7字`
- `＞8字`
- `成语`

交互规则：

- 点击任意分区后重建当前星云节点集合。
- 每个按钮显示当前搜索/底部字位筛选上下文下的数量。
- `成语` 是类型分区，不完全等同于 4 字，因为也存在非四字成语。
- 歇后语按谜面长度进入 3/4/5/6/7/8plus 分区。
- 面板可拖动、可折叠、可通过 `resetView=1` 恢复默认位置。

### 5.3 底部检索面板：字位索引

底部按钮：

- `首字`
- `次字`
- `第3字`
- `第4字`
- `第5字`
- `末字`

交互规则：

- 底部按钮不是直接筛选类别，而是切换搜索框当前字的解释方式。
- 例如搜索框输入“风”，底部选中 `首字`，则显示首字为“风”的条目；选中 `末字`，则显示末字为“风”的条目。
- 如果搜索框为空，点击底部按钮显示该字位的热门字云或高频索引星团。
- 点击星云中的“字索引节点”可自动填入搜索框并触发对应字位筛选。

性能策略：

- 预构建 `positionIndex`，避免每次筛选遍历全库。
- 索引结构建议为 `Map>`。
- 当前视图只渲染可见节点，上限默认 2500，超出时用聚合星团表示。

### 5.4 释义面板：成语或歇后语详情

打开方式：

- 搜索结果精确命中时自动打开。
- 点击星云中的成语/歇后语节点时打开。
- 点击关联节点时打开关联列表或详情。

成语详情字段：

- 成语
- 拼音
- 缩写
- 释义
- 出处
- 例句
- 字位结构：首字、次字、第3字、第4字、第5字、末字
- 关联：同首字、同末字、同关键词、同出处关键词

歇后语详情字段：

- 谜面
- 答案
- 释义：第一版默认使用答案，可后续补充解释字段
- 出处：基础库未标注或用户输入
- 字位结构
- 关联：同首字、同答案关键词、同谜面意象

面板行为：

- 可关闭、可固定、可拖动。
- 支持“加入自造模板”：把当前条目复制到自造歇后语面板中改写。
- 支持“查看星云定位”：点击后镜头飞向该节点。

### 5.5 自造歇后语面板

目标：

- 允许用户按固定格式创建自己的歇后语/短语，并加入星云视图。
- 新增内容必须进入同一套搜索、筛选、字位索引和释义面板。

编辑格式：

```text
谜面：__________
答案：__________
释义：__________
出处/作者：__________
标签：__________
备注：__________
```

校验规则：

- `谜面` 必填，2-24 个中文字符或含少量标点。
- `答案` 必填，1-16 个中文字符。
- `释义` 可为空，空时默认等于答案。
- `出处/作者` 可为空，空时默认“用户自造”。
- 禁止与基础库或用户库中完全相同的 `riddle + answer` 重复。

存储策略：

- 浏览器本地版：使用 `localStorage` 或 `IndexedDB` 存储 `user-entries.json` 等价结构。
- 可转发 HTML 包版本：导出用户自造数据为 JSON 文件，下一次导入合并。
- 后续工程版：支持服务端账户空间或本地文件系统保存。

## 6. 星云视图设计

视觉原则：

- 星云效果：深黑星空、低干扰面板、中心白金星核、青绿/橙红/粉色星团。
- 成语节点更像“亮点星”，歇后语节点略长，可用细小彗尾或淡色轨迹区分。
- 当前筛选结果形成主星团，非命中节点降亮度保留空间背景。

布局原则：

- 成语按首字/拼音缩写/出处关键词形成多臂星系。
- 歇后语按谜面意象和答案关键词形成松散星云团。
- 用户自造条目单独带微弱金色描边，避免和基础库混淆。
- 关联线默认极淡，仅悬停、选中或搜索时增强。

性能原则：

- 预计算布局坐标，运行时只做轻量扰动与镜头投影。
- 20k 以上条目不全部用 DOM，全部走 Canvas/WebGL 星点渲染。
- 面板永远只渲染当前详情和少量列表，不渲染全量数据。
- 搜索和筛选使用索引，不直接遍历全量 JSON。

## 7. 搜索与筛选数据流

```text
加载基础语库
-> normalize 成 NebulaEntry[]
-> 合并 user-entries
-> 构建 lengthIndex / typeIndex / positionIndex / keywordIndex
-> 构建 graph-index
-> 渲染初始星云

用户搜索或点击分区
-> 更新 queryState
-> 从索引取 entryId 集合
-> 合并 leftPartition + bottomPosition + searchText 条件
-> 更新星云节点可见性和数量徽标
-> 若精确命中则打开释义面板
```

状态模型：

```ts
type QueryState = {
searchText: string;
leftPartition: "all" | "3" | "4" | "5" | "6" | "7" | "8plus" | "idiom";
positionFilter: "first" | "second" | "third" | "fourth" | "fifth" | "last";
selectedEntryId: string | null;
includeUserEntries: boolean;
quality: "high" | "low";
};
```

## 8. 开发阶段计划

第一阶段：工程骨架与数据契约

- 新建 `idiom-xiehouyu-nebula` 工程结构。
- 接入 `idiom.json`、`xiehouyu.json` 的下载/导入脚本。
- 完成 `NebulaEntry` 归一化和基础统计。
- 验收：能输出总条目数、成语数、歇后语数、用户条目数、长度分区数量。

第二阶段：星云基础视图

- 星空背景和 WebGL/Canvas 星点层。
- 将成语和歇后语作为基础节点渲染。
- 先不做复杂关联线，只做节点分布、亮度、镜头控制。
- 验收：3 万成语 + 1.4 万歇后语可加载，首屏不卡死。

第三阶段：五大面板 UI

- 顶部标题面板：标题、搜索框、设置。
- 左侧分区面板：3/4/5/6/7/8plus/成语。
- 底部检索面板：首字/次字/第3字/第4字/第5字/末字。
- 释义面板：点击节点弹出详情。
- 自造歇后语面板：新增、保存、进入星云。
- 验收：五个模块都能打开、关闭、拖动或固定。

第四阶段：索引与搜索

- 构建长度索引、类型索引、字位索引、关键词索引。
- 搜索框与底部字位检索联动。
- 左侧分区数量徽标随上下文刷新。
- 验收：搜索单字、多字、成语、歇后语答案均可返回正确结果。

第五阶段：详情与关联

- 成语展示释义、出处、例句、拼音。
- 歇后语展示谜面、答案、补充释义、出处。
- 点击详情里的关联项可定位到星云节点。
- 验收：任意节点点击后详情字段完整，不存在字段时有明确兜底文案。

第六阶段：用户自造语库闭环
- 用户新增歇后语后即时进入搜索索引和星云图。
- 支持编辑、删除、导入、导出。
- 支持“只看自造”和“基础库+自造库”切换。
- 验收：刷新页面后用户条目仍存在；导出 JSON 后可重新导入。
第七阶段：性能与打包
- 大数据分片加载。
- 索引缓存到 IndexedDB。
- 手机浏览器适配。
- 生成可转发 HTML+数据包版本。
- 验收：桌面端流畅；手机端可打开、可搜索、可查看详情。
## 9. 验收标准
功能验收：
- 顶部搜索框可搜索成语、歇后语、拼音缩写和释义关键词。
- 左侧分区可按 3/4/5/6/7/8plus/成语筛选，并显示数量。
- 底部检索可按首字、次字、第3字、第4字、第5字、末字筛选。
- 点击星云节点可打开详情面板。
- 用户可新增自造歇后语，并立即进入星云视图和搜索结果。
性能验收：
- 基础库约 4.5 万条可以加载。
- 初始渲染不创建 4.5 万个 DOM 节点。
- 搜索响应目标小于 200ms。
- 筛选响应目标小于 300ms。
- 手机浏览器低画质模式可正常浏览。
数据验收：
- 成语字段完整率统计：`word/explanation/derivation/pinyin`。
- 歇后语字段完整率统计：`riddle/answer`。
- 用户自造条目必须通过格式校验。
- 所有条目都有稳定 `id`，避免重复导入产生重复节点。
做出通用skill,带入其它知识库数据给予对应检索路径，实现同等星云视图动效

## 10. 后续可扩展方向

- 接入“成语接龙”玩法。
- 接入“歇后语猜答案”游戏。