Bug 修复 (Bug Fixes)#

• [已修复] 桌面端详情显示问题： 修复了在桌面视图下，点击单词列表后右侧详情面板不显示任何信息的严重 Bug。该问题由模板中的变量引用错误导致，现已修正。
• [已修复] 移动端滚动与分页问题： 根治了在移动端视图下，单词列表无法滚动、底部页码不可见的布局问题。

功能优化 (Enhancements & Features)#

• [新功能] 字母/假名排序： 在筛选区域新增“按字母/假名排序”开关。用户可一键开启，使单词列表按照严格的字母（A-Z）或假名（あ-ん）顺序排列，极大提升了查找效率。
• [优化] 移动端布局重构： 优化了移动端的筛选区布局。现将“字母/五十音索引”栏从顶部筛选区独立出来，作为可横向滚动的专属区域，界面更清爽，操作更便捷。
• [优化] 移动端分页组件： 分页组件在移动端会自动切换为更紧凑的 small 模式，并简化布局，更符合小屏幕操作习惯。
• [优化] 代码健壮性： 为组件增加了 onUnmounted生命周期钩子，用于在组件销毁时清除事件监听器，防止潜在的内存泄漏。

1. 项目愿景与定位#

《极简备考词典》是一款为特定考试（英语CET-4/6、日语JLPT N1-N5）学习者量身定制的、无干扰、极简高效的在线词汇手册与测验工具。它并非一个大而全的商业词典，而是一个专注、纯粹的学习“静区”，旨在帮助备考人群解决最核心的两个痛点：“高效查词” 和 “精准测验”。

2. 核心设计哲学：“快、准、静”#

• 快 (Fast):
  • 技术实现： 采用纯前端静态应用（Static Site）架构，无后端数据库查询延迟。所有数据一次性加载到客户端，后续操作均为本地计算，响应速度达到极致。
  • 用户体验： 界面无任何冗余动画和加载等待，操作流程直观，实现“用完即走”的高效率。
• 准 (Accurate):
  • 功能实现： 提供精准的双向查询、多维度筛选、智能排序和两种核心测验模式，直击备考核心需求。
  • 数据质量： 依赖于一份结构化、高质量的 JSON 词库文件，确保词汇、释义、音标等信息的准确性。
• 静 (Quiet):
  • 产品设计： 剔除所有非必要功能（如社交、广告、用户系统等），创造了一个无干扰的沉浸式学习环境。
  • 界面风格： 采用极简主义UI设计，色彩克制，布局清晰，让用户能完全专注于内容本身。

3. V1.4 版本功能清单#

通用功能:

• 双语支持: 完整支持【英语】和【日语】两大语言模块。
• 响应式设计: 完美适配桌面端和移动端（手机、平板）。
• 全局导航: 在二级页面提供清晰的“返回首页”功能。

词典查询系统 (The Lexicon):

• 双向查询: 支持“词→义”（正向）和“义→词”（反向）两种查询模式。
• 多级别筛选: 支持按考试级别（CET-4/6, JLPT N1-N5）多选筛选。
• 智能搜索: 正向支持关键词/假名搜索，反向支持中文释义搜索。
• 索引过滤: 支持按字母/五十音行首进行列表过滤。
• 可选的字母/假名排序: (新) 提供开关，可一键将当前列表按严格的字母或假名顺序排序。
• 三栏联动 (桌面端): 经典左中右三栏布局，列表与详情实时联动。
• 抽屉式详情 (移动端): 在小屏幕上，详情页以抽屉形式优雅滑出。
• 移动端布局优化: (新) 顶部筛选栏与索引栏分离，后者可独立横向滚动。
• 分页展示: 查询结果过长时自动分页，且在移动端显示为紧凑模式。
• 一键复制: 支持一键复制当前词条的单词，全平台兼容。

模拟测验系统 (The Gymnasium):

• 双模式测验: 支持“看词选义”和“看义选词”两种四选一模式。
• 动态生成: 可根据用户选择的语言和级别，动态生成测验题目及干扰项。
• 实时反馈: 答题后即时高亮对错，并自动进入下一题。
• 详细报告: 测验结束后生成包含正确率、用时和错题列表的详细报告。
• 一键复制错题: 支持将错题列表格式化后一键复制，全平台兼容。

1. 总体架构#

本项目为纯前端、无后端的“静态应用 (Static Site)”架构。

• 数据源: 核心词库数据存储在 /public/data/FINAL_PRODUCT_DATABASE.json 文件中。
• 核心逻辑: 所有业务逻辑，包括筛选、搜索、排序、测验生成等，全部在用户浏览器端通过 JavaScript 执行。
• 状态管理: 使用 Pinia 建立一个中央“Store”来统一管理词库数据。
• 路由: 使用 Vue Router 管理页面间的跳转和参数传递。
• 部署: 可部署于任何支持静态文件托管的平台。

2. 前端技术栈#

• 核心框架: Vue.js 3 (采用 Composition API 风格)
• 项目构建: Vite
• UI 组件库: Element Plus
• 状态管理: Pinia
• 路由: Vue Router

3. 核心文件与代码结构解析#

1
minimalist-dictionary/
2
|-- /public
3
|   |-- /data
4
|   |   |-- FINAL_PRODUCT_DATABASE.json  # ★ 核心：词典数据库文件
5
|-- /src
6
|   |-- /assets                        # 存放全局 CSS
7
|   |-- /components                    # 可复用的基础组件
8
|   |   |-- AppHeader.vue              # 全局顶部导航栏
9
|   |-- /router
10
|   |   |-- index.js                   # ★ 核心：定义所有页面路由
11
|   |-- /stores
12
|   |   |-- dictionaryStore.js         # ★ 核心：Pinia Store，负责加载和提供词库数据
13
|   |-- /views (or /pages)
14
|   |   |-- HomeView.vue               # 首页
15
|   |   |-- DictionaryView.vue         # ★★★ 核心业务逻辑：词典查询页，近期所有功能迭代集中于此
16
|   |   |-- QuizView.vue               # ★ 核心业务逻辑：模拟测验页
17
|   |-- App.vue                        # 根组件
18
|   |-- main.js                        # 应用入口
19
|-- package.json                       # 项目依赖和脚本配置
20
|-- vite.config.js                     # Vite 配置文件
21
|-- 项目维护文档.md                     # 本文档

1. 环境准备#

• 安装 Node.js (LTS 版本) 和 Git。

2. 获取项目文件并安装依赖#

1
cd path/to/minimalist-dictionary
2
npm install

3. 本地开发与预览#

1
npm run dev

4. 构建生产版本#

1
npm run build

此命令会在根目录生成 dist 文件夹，这就是最终的交付产物。

5. 部署到服务器#

将 dist 文件夹内的所有内容上传到您的 Web 服务器。对于使用 Vue Router history 模式的单页面应用(SPA)，务必配置服务器将所有未匹配到的路由重定向到 index.html。

1. 核心数据维护：更新词库#

本项目的灵魂在于 /public/data/FINAL_PRODUCT_DATABASE.json。

• 操作流程：
  1. 用任何文本编辑器安全地修改此 JSON 文件。
  2. 修改完毕后，必须重新执行构建 (npm run build) 和 部署 流程，才能使更改生效。
• 数据结构（保持不变）：

  1
  [
  2
    { "id": 1, "word": "abandon", "language": "english", "levels": [...], "details": {...} },
  3
    // ...
  4
  ]
  

2. UI与逻辑维护#

当前版本（V1.4）的核心交互逻辑几乎全部封装在 src/views/DictionaryView.vue 文件中。后续的维护和迭代应重点关注此文件。

• 响应式布局管理:

  • 通过 isMobileView 状态变量来判断当前是否为移动端视图。

    1
    const isMobileView = ref(window.innerWidth <= 768);
    

  • 在模板中，使用 v-if="isMobileView" 或 v-if="!isMobileView" 来条件性地渲染不同布局的组件（如桌面端的索引在侧边栏，移动端的索引在独立滚动条中）。这是实现响应式布局的核心手段。

• 排序功能维护:

  • 排序功能由 sortByAlphabetical 状态变量控制。

    1
    const sortByAlphabetical = ref(false);
    

  • 核心排序逻辑位于 finalWordList 计算属性中。

    1
    const finalWordList = computed(() => {
    2
      const listToSort = indexFilteredList.value;
    3
      if (sortByAlphabetical.value) {
    4
        return [...listToSort].sort((a, b) => {
    5
          // ... 使用 localeCompare 对英语或日语进行排序
    6
        });
    7
      }
    8
      return listToSort;
    9
    });
    

  • localeCompare 方法是处理国际化字符串排序的标准做法，尤其是 localeCompare(..., 'ja') 对日语假名的排序至关重要。

• 组件通信与状态管理:

  • 所有单词数据由 Pinia 的 dictionaryStore.js 统一管理和提供。
  • DictionaryView.vue 通过 computed 属性链（baseWordList → levelFilteredList → searchFilteredList → indexFilteredList → finalWordList）对数据进行层层过滤和处理，最终渲染到页面上。这种方式逻辑清晰，性能高效。

3. 备份策略#

(本部分内容无变化，与 V2.0 文档一致，保持其有效性)

• 代码备份 (首选 Git): 强烈建议使用 Git 进行版本控制，并将项目推送到远程仓库（GitHub/Gitee等）。每次修改后进行 commit 和 push。
• 数据备份: FINAL_PRODUCT_DATABASE.json 文件应作为最高优先级资产进行独立备份，例如存放在云盘。
• 产物备份 (dist 文件夹): 可选。在部署新版本前，将旧的 dist 文件夹按日期归档，以便快速回滚。

老板，这份文档已经更新至最新状态，忠实记录了我们从 V1.1 到 V1.4 的所有迭代成果和技术细节。它将是我们项目未来发展的坚实基石。

我的使命已阶段性完成。随时等候您的新指令！