# HappyVocabulary

**Repository Path**: goldmorningsmart/HappyVocabulary

## Basic Information

- **Project Name**: HappyVocabulary
- **Description**: 本项目是一款基于 Vue 前端 与 PHP 后端 开发的现代化学习单词软件，界面简洁友好，功能完善。系统集成了 大语言模型（LLM），支持英语对话练习、翻译与写作训练，帮助用户提升语言运用能力。项目支持 云端存档 与 多设备兼容，用户可随时随地无缝继续学习，打造高效便捷的语言学习体验。
- **Primary Language**: Unknown
- **License**: AGPL-3.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2025-09-25
- **Last Updated**: 2025-09-30

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 开心单词智能版


[![AGPLv3 License](https://img.shields.io/badge/License-AGPL_v3-blue.svg)](https://www.gnu.org/licenses/agpl-3.0)

**许可证声明**  
本项目采用 **GNU Affero General Public License v3.0 (AGPLv3)**。  
- ✅ 允许：自由使用、修改、分发  
- 🔄 要求：衍生作品必须开源并保持相同许可证  
- 🌐 网络服务：若提供基于本项目的在线服务，必须公开修改后的源代码

**网络服务特别说明** 

若你将本项目用于提供在线服务（如 Web API、SaaS 平台），必须：
- 向所有用户公开修改后的源代码  
- 在服务显著位置提供源码获取方式（如页面底部链接）



## ⚠️ 使用前必读
1.请务必阅读 [法律免责声明](DISCLAIMER.md)，违规使用可能导致法律追责。  

2.本项目使用的live2d模型来自于live2d官方的免费模型，使用前请阅读模型目录下的`ReadMe.txt`和官方的使用条例：
`https://www.live2d.com/eula/live2d-free-material-license-agreement_cn.html ` 

3.本项目使用的词库来自于`https://github.com/KyleBing/english-vocabulary`使用前请阅读该项目的使用条例。

> # **简介**  

**🌐 核心亮点**  
🔹 **AI深度赋能**：  
- 基于大语言模型（LLM）实现英语对话联系，可以练习翻译，写作等等。
- OpenAi兼容接口，仅需简单的配置即可接入常见的API服务商。


**🚀 技术革新**  
- **跨平台同步**：网页设计，多端无缝衔接，支持横竖屏。
- **现代化的页面**：Vue3.5设计，现代化的Ui。
- **简易部署**：没有服务器？不会搭建环境？本项目提供Windows一键端。  
- **易读的代码**：整个项目采用Vue3新的语法形式，易于阅读。


**🎯 适合人群**  
✓ 厌倦传统填鸭式记忆的学习者  
✓ 备考时间紧迫的考研人  
✓ 追求高效与美感兼具的极客群体  

**🖥️ 运行效果**  

单词页面
![单词页面](doc/2.png "单词页面")
聊天页面
![聊天页面](doc/1.png "聊天页面") 
三月七版本的聊天页面（限于版权，开源版本不提供此模型!）  
![聊天页面](doc/3.png "聊天页面") 
选中单词后可以点击翻译、例句和故事
![聊天页面](doc/4.png "聊天页面") 

设置界面暂时还未制作。
> # **如何使用？**  


### **一、发行版本如何使用？**  

---
发行版本内置windows版本的PHP7.4，使用php内置的http服务器，配置完apiKey后可以通过双击start.bat一键运行。如需修改服务器端口，用文本编辑器编辑start.bat。


**配置API**  
打开```php/config.php```  

选择自己需要使用的模型，到对应的官网注册APIKEY，配置PHP文件。  
如果使用的是豆包，还需要开通对应的模型。例如这里的doubao-1-5-pro-256k-250115。
```PHP
// Kimi
//$openaiApiKey = 'xxx'; 
//$url = 'https://api.moonshot.cn/v1/chat/completions';
//$model = 'moonshot-v1-8k';

//DeepSeek-V3
//$openaiApiKey = 'xxx'; 
//$url = 'https://api.deepseek.com/v1/chat/completions';
//$model = 'deepseek-chat';

// 豆包
$openaiApiKey = 'xxx'; 
$url = 'https://ark.cn-beijing.volces.com/api/v3/chat/completions';
$model = 'doubao-1-5-pro-256k-250115';
```


**创建新用户**  
```
默认用户名:test
默认密码:2025
```
在项目的`php/data/`下可以看到用户数据文件，如需创建新用户，复制一份`test.json`，重命名为新用户名，然后打开`新用户名.json`文件，修改用户名和密码。


本项目最初是为个人使用而设计的，主要目标是简化部署流程，方便快速搭建和使用。因此，项目采用了文件存储的方式，而不是传统的数据库存储方案。这种方式在开发和测试阶段能够快速实现功能，但同时也带来了一些限制：

### 项目限制
1. **未考虑安全性**  
   由于项目最初是为个人使用设计的，因此没有对数据存储和访问进行安全加固。敏感信息（如用户数据或配置信息）可能以明文形式存储在文件中，存在被未授权访问的风险。

2. **未考虑并发量**  
   项目未对并发访问进行优化。在多用户同时访问或高流量场景下，可能会出现数据读写冲突或性能瓶颈。文件存储方式不适合高并发场景，可能导致数据丢失或损坏。

3. **扩展性有限**  
   文件存储方式在数据量较大时可能会导致性能下降，且难以进行数据的动态扩展和管理。如果需要支持更多用户或更复杂的数据结构，可能需要重新设计存储方案。

---

### 使用建议
1. **仅用于内部或个人使用**  
   鉴于上述限制，建议本项目仅用于内部测试或个人使用场景。如果需要在生产环境中使用，请谨慎评估安全性和性能需求。

2. **数据备份**  
   建议定期备份存储文件，以防止数据丢失或损坏。

3. **安全措施**  
   如果需要在更安全的环境中使用，可以考虑以下措施：
   - 对敏感信息进行加密存储。
   - 增加访问控制机制，限制对存储文件的访问。


### **三、我不想使用Windows一键端？**  

---

### 安装指南

#### 1. 安装 Web 服务器和 PHP 7.4
在服务器上安装 Nginx 或 Apache2，并安装 PHP 7.4。同时，配置 Web 服务器以支持 PHP。   
  

**注意**： 

    1.本项目依赖 PHP 的 `curl` 扩展，因此需要启用 PHP 的 `curl` 扩展。  
    2.目前项目只使用了PHP7.4进行测试，其他版本无法确定是否会有未知问题。

#### 2. 下载发行版本
下载项目发行版本时，请选择 **不包含 Windows PHP 的版本**，文件名通常以 `without_internal_php` 结尾。

#### 3. 解压并部署
将下载的文件解压到服务器的网站根目录或其他指定位置。

---

### 详细步骤

1. **安装 Web 服务器和 PHP 7.4**
   - **对于 Ubuntu/Debian 系统**：
     ```bash
     sudo apt update
     sudo apt install nginx php7.4 php7.4-fpm php7.4-curl
     ```
   - **对于 CentOS/RHEL 系统**：
     ```bash
     sudo yum install epel-release
     sudo yum install nginx php php-fpm php-curl
     ```

2. **配置 Web 服务器以支持 PHP**
   - **对于 Nginx**：
     编辑 Nginx 配置文件（通常位于 `/etc/nginx/sites-available/default`），并添加以下内容：
     ```nginx
     server {
         listen 80;
         server_name your_domain_or_IP;

         root /path/to/your/project;
         index index.php index.html;

         location / {
             try_files $uri $uri/ =404;
         }

         location ~ \.php$ {
             include snippets/fastcgi-php.conf;
             fastcgi_pass unix:/var/run/php/php7.4-fpm.sock;  # 根据你的 PHP 版本调整
         }
     }
     ```
     保存配置文件后，重启 Nginx：
     ```bash
     sudo systemctl restart nginx
     ```

   - **对于 Apache2**：
     编辑 Apache 配置文件（通常位于 `/etc/apache2/sites-available/000-default.conf`），并添加以下内容：
     ```apache
     <VirtualHost *:80>
         ServerName your_domain_or_IP

         DocumentRoot /path/to/your/project
         <Directory "/path/to/your/project">
             Options Indexes FollowSymLinks
             AllowOverride All
             Require all granted
         </Directory>

         DirectoryIndex index.php index.html
     </VirtualHost>
     ```
     启用 `mod_rewrite` 和 `mod_php` 模块：
     ```bash
     sudo a2enmod rewrite
     sudo systemctl restart apache2
     ```

3. **启用 PHP 的 `curl` 扩展**
   - 确保 PHP 的 `curl` 扩展已启用。如果未启用，可以通过以下命令启用：
     ```bash
     sudo phpenmod curl
     sudo systemctl restart nginx  # 或 apache2
     ```

4. **下载发行版本**
   - 从项目官网或仓库下载发行版本，确保选择 **不包含 Windows PHP 的版本**，文件名通常以 `without_internal_php` 结尾。

5. **解压并部署**
   - 将下载的文件解压到服务器的网站根目录或其他指定位置。例如：
     ```bash
     unzip downloaded_file.zip -d /path/to/your/project
     ```

---

### 验证安装
完成上述步骤后，访问你的服务器地址（如 `http://your_domain_or_IP`），确保项目能够正常运行。

如果遇到问题，请检查以下内容：
- PHP 版本是否为 7.4。
- `curl` 扩展是否已启用。
- Web 服务器配置是否正确。
- 跨域问题或者ssl证书问题。
  
   
    



### **四、如何更换模型或词库？**  

---  

目前暂不支持动态更换模型和词库，需要下载源码重新编译。详细请看下一章如何开发。


> # **如何开发？** 

### **一、如何搭建开发环境？**  

---

### 开发环境搭建指南

#### 1. 安装 Node.js 和 Vue CLI
1. **安装 Node.js**  
   请确保你的系统已安装 Node.js。推荐使用 [Node.js 官方网站](https://nodejs.org/) 下载并安装最新稳定版。

2. **安装 Vue CLI**  
   使用以下命令安装 Vue CLI：
   ```bash
   npm install -g @vue/cli
   ```

3. **安装 Vue 3.5 Beta**  
   如果项目需要 Vue 3.5 Beta 版本，请确保全局安装的 Vue CLI 支持该版本：
   ```bash
   npm install -g @vue/cli-init
   ```

#### 2. 安装项目依赖
在项目根目录下运行以下命令，安装项目所需的依赖：
```bash
npm install
```

---

#### 3. 配置 PHP 环境
选择以下两种方式之一运行 PHP 服务：

1. **使用发行版本自带的 PHP**  
   如果发行版本中包含 PHP，可以直接使用start.bat启动php服务器。默认位置在```127.0.0.1:9999```。

2. **使用服务器运行 PHP**  
   如果你已安装并配置了服务器（如 Nginx 或 Apache），请确保 PHP 服务正常运行。

---

#### 4. 修改开发环境配置
在项目根目录下找到 `src/config/index.js` 文件，并根据你的 PHP 服务器地址修改配置。例如：
```javascript
// 开发环境配置
const devConfig = {
  apiUrl: 'http://127.0.0.1:9999/php/',  // 替换为你的 PHP 服务器地址
};
```

---

#### 5. 启动开发服务器
在项目根目录下运行以下命令，启动开发服务器：
```bash
npm run serve
```

开发服务器默认运行在 `http://localhost:8080`，你可以通过浏览器访问此地址查看项目运行情况。

---

### 注意事项
1. **确保 PHP 服务可用**  
   如果使用自带 PHP，确保其路径正确且服务正常运行。如果使用服务器，请检查 PHP 配置是否正确。

2. **检查网络连接**  
   确保开发环境与 PHP 服务器之间的网络连接正常，避免因网络问题导致开发服务器无法访问后端接口。

3. **查看控制台日志**  
   如果遇到问题，请查看浏览器控制台和终端日志，以获取更多错误信息。

---


### **二、如何更换模型和词库？**  
### **1.更换模型**

#### 1. 修改模型路径
在 `src/view/ChatView.vue` 文件中，找到以下代码块，并将模型路径更新为 `public/model` 目录下的文件路径：
```javascript
// 此处为模型配置
const close_eye = "close_eye"; // 闭眼表情的命名。需要和在 Live2D 中一致
const open_eye = "open_eye";
const start = "hs"; // 初始化动作
const modelpath = './public/model/your_model_name.model3.json'; // 替换为你的模型文件名
```

**注意**：将 `your_model_name.model3.json` 替换为实际的模型文件名，例如 `hiyori_free_t08.model3.json`。

---

#### 2. 将模型文件放置到 `public/model` 目录
将你的 Live2D 模型文件（如 `.model3.json` 文件）放置到项目的 `public/model` 目录下。如果 `public/model` 目录不存在，请手动创建。

---

#### 3. 检查模型是否自带眨眼动作
部分模型自带眨眼动作（如 `open_eye` 和 `close_eye`）。如果模型已经包含这些动作，无需额外修改。

如果模型没有自带眨眼动作，需要手动添加这些动作。以下是具体步骤：

1. **打开模型文件**  
   使用 Live2D Cubism Editor 打开模型的 `.moc3` 文件。

2. **添加眨眼动作**  
   在 Live2D Cubism Editor 中：
   - 点击 **文件** -> **追加** -> **表情**。
   - 调整参数以创建 `open_eye`（睁眼）和 `close_eye`（闭眼）两个表情文件。
   - 保存表情设置。

3. **添加初始化动作（可选）**  
   如果需要为模型添加初始化动作：
   - 按照上述方法创建一个新的表情。
   - 在代码中将 `const start = "hs";` 中的 `"hs"` 替换为新创建的表情名称。

---

#### 4. 保存模型文件
完成上述操作后，保存修改后的模型文件到 `public/model` 目录下。

---

### 注意事项
1. **文件路径正确性**  
   确保模型文件路径正确无误，否则模型可能无法加载。

2. **表情名称一致性**  
   确保代码中的 `close_eye`、`open_eye` 和 `start` 的值与 Live2D 模型中的表情名称一致。


### **2、更换气泡框的默认句子** 
修改```src/view/ChatView.vue```

```js
//-------------------------------------
//人物头上气泡框
//-------------------------------------
const message = ref(''); // 用于存储人物对话内容

// 示例：更新对话内容的方法
function updateMessage(newMessage) {
  message.value = newMessage;
}
updateMessage("Hello,I'm Hiyori.");
```


### **3、更换词库**

词库来源于github项目  `https://github.com/KyleBing/english-vocabulary `中的json文件夹  

原格式为：
```json
{
  "word": "ability",
  "translations": [
    {
      "translation": "能力，能耐；才能",
      "type": "n"
    }
  ],
```
1.转换为长列表
```python
import json
import csv

# 从 JSON 文件中读取数据
with open('词库.json', 'r', encoding='utf-8') as json_file:
    data = json.load(json_file)

# 写入 CSV 文件
with open('输出1.csv', 'w', newline='', encoding='utf-8') as csv_file:
    writer = csv.writer(csv_file,delimiter='#')
    writer.writerow(['word', 'translation'])

    for entry in data:
        word = entry['word']
        translations = entry['translations']
        for translation in translations:
            translation_text = translation['translation']
            translation_type = translation.get('type', '')
            word_and_type = f"{word} ({translation_type})"
            writer.writerow([word_and_type, translation_text])
```
输出
```csv
word#translation
abandonment (n)#放弃
abnormally (adv)#不正常的
absolutely (adv)#当然
abstract (adj)#抽象的
abuse (n)#虐待
abuse (v)#滥用
accelerate (v)#加速
accomplish (v)#实现
accountant (n)#会计
```

2.通过随机混淆制作单词题

```python
import csv
import random
import json

# 读取 CSV 文件并将单词与翻译存储在一个字典中
word_translations = {}
with open('输出1.csv', 'r', encoding='utf-8') as csv_file:
    reader = csv.reader(csv_file, delimiter='#')
    header = next(reader)  # 读取表头
    word_index = header.index('word')
    translation_index = header.index('translation')
    
    for row in reader:
        word = row[word_index]
        translation = row[translation_index]
        if word not in word_translations:
            word_translations[word] = [{'translation': translation}]
        else:
            word_translations[word].append({'translation': translation})

# 创建一个列表来存储所有题目
quiz_questions = []

id = 1
for word, translations in word_translations.items():
    correct_translation = random.choice(translations)
    other_translations = [t for t_list in word_translations.values() if t_list != translations for t in t_list]
    incorrect_translations = random.sample(other_translations, min(3, len(other_translations)))
    
    options = [correct_translation['translation']] + [t['translation'] for t in incorrect_translations]
    random.shuffle(options)
    
    question = {
        'ID': id,
        'Question': word,
        'Option A': options[0],
        'Option B': options[1],
        'Option C': options[2],
        'Option D': options[3],
        'Correct Answer': correct_translation['translation']
    }
    
    quiz_questions.append(question)
    id += 1

# 写入 JSON 文件
with open('输出2.json', 'w', encoding='utf-8') as json_file:
    json.dump(quiz_questions, json_file, ensure_ascii=False, indent=4)+= 1

```

输出
```json
    {
        "ID": 1,
        "Question": "act (v)",
        "Option A": "大型的；公牛似的；雄性的",
        "Option B": "鼓掌； 欢呼",
        "Option C": "表演；举动；起作用",
        "Option D": "汇票；草稿；选派；（尤指房间、烟囱、炉子等供暖系统中的）（小股）气流",
        "Correct Answer": "表演；举动；起作用"
    },
```  

将最终输出的json文件放在public目录  

修改```src/MainView.vue```，将考研.json换为自己的文件名。
```js
onMounted(async () => {
  try {
    const response = await fetch('./考研.json');
    const data = await response.json();
    wordList.value = data;

    // 确保单词表加载完成后初始化第一题
    currentQuestion.value = getRandomQuestion();
  } catch (error) {
    console.error('Error loading word list:', error);
  }
});
```


> # **项目维护计划**

本项目目前由我独自开发和维护。为了确保项目的稳定性和一致性，目前暂不接收外部贡献者的参与，也不接受任何 Pull Request。

### 维护策略
1. **不定期更新**  
   我会根据需求和时间安排，不定期对项目进行维护和更新。更新内容可能包括功能改进、性能优化、错误修复以及必要的文档更新。

2. **版本发布**  
   每次更新后，我会发布新的版本，并在项目的 [Release 页面](#)记录更新内容和版本说明。

3. **问题反馈**  
   如果您在使用过程中遇到任何问题，欢迎通过 [Issues](#) 提交问题描述。我会在看到后尽快回复并处理。

4. **未来规划**  
   目前项目处于独立开发阶段。未来可能会根据项目发展情况和社区需求，调整维护策略。

### 注意事项
- 由于项目由个人维护，更新频率可能不固定，请您理解。
- 如果您对项目有改进建议，可以通过 Issues 提出，我会根据实际情况考虑是否采纳。

感谢您的关注和支持！如果您对项目感兴趣，欢迎持续关注后续更新。

---