feat(docs): 深入重构和扩展第三章前端开发内容

- 全面采用 Vue 3、Pinia、Vue Router 4 技术栈
- 3.1: 深入讲解 Vue 基础，包括组合式 API, ref/reactive, 生命周期
- 3.2: 深入讲解组件化，包括 Props/Events, Slots
- 3.3: 使用 Pinia 重写状态管理，并介绍持久化插件
- 3.4: 使用 Vue Router 4 重写路由，并介绍导航守卫和懒加载
- 3.5: 提供一个基于新版技术栈的现代化实践项目指南

Author: lizhogn

docs/chapter3/3.1-vue-basics.md

@@ -1,112 +1,259 @@
-# 3.1 Vue.js 基础
+# 3.1 Vue.js 基础：深入核心
 
 ## 📖 概述
 
-本章将带你入门 Vue.js，掌握其核心概念和基本用法，为后续前端开发和与后端 API 的对接打下坚实基础。
+对于前端开发经验较少的同学，本章将是你深入 Vue.js 世界的坚实起点。我们将从 Vue 的核心思想出发，详细讲解其关键概念和现代开发方式，为你后续的学习和实践扫清障碍。
 
-## 🌱 Vue.js 简介
+## 🌱 什么是 Vue.js？
 
-- Vue.js 是一套用于构建用户界面的渐进式 JavaScript 框架。
-- 采用数据驱动和组件化开发思想，易学易用，生态丰富。
-- 适合单页应用（SPA）和复杂前端项目。
+Vue (发音为 /vjuː/，类似于 **view**) 是一套用于构建用户界面的 **渐进式 JavaScript 框架**。
 
-## 🚀 快速上手
+- **构建用户界面 (UI)**: Vue 的核心功能是让你能够声明式地将数据渲染到 DOM (文档对象模型)。你可以将数据和模板组合起来，当数据变化时，Vue 会智能地更新界面。
+- **渐进式框架 (Progressive Framework)**: 这是 Vue 的核心理念。
+    1.  **易于上手**: 你可以像使用 jQuery 一样，只在现有页面的局部使用 Vue，来增强交互性。
+    2.  **逐步采用**: 随着项目复杂度的增加，你可以逐步引入 Vue 的路由 (Vue Router)、状态管理 (Pinia) 等功能，最终构建一个功能完善的单页应用 (SPA)。
+    3.  **灵活多变**: 它既可以用于小型的交互式部件，也可以驱动大型、复杂的企业级应用。
 
-### CDN 方式引入
-```html
-<script src="https://cdn.jsdelivr.net/npm/vue@2/dist/vue.js"></script>
-<div id="app">{{ message }}</div>
-<script>
-  new Vue({
-    el: '#app',
-    data: { message: 'Hello Vue!' }
-  })
-</script>
+## 🚀 创建一个现代 Vue 项目
+
+在现代 Vue 开发中，我们推荐使用 `Vite` 来创建和管理项目。`Vite` 是一个由 Vue 作者开发的前端构建工具，它拥有极快的冷启动速度和热更新能力，能显著提升开发体验。
+
+```bash
+# 确保你已安装 Node.js 16+
+# 使用以下命令创建项目 (npm 7+)
+npm create vue@latest
+
+# 你也可以使用 yarn 或 pnpm
+# yarn create vue
+# pnpm create vue
 ```
 
-### 使用 Vue CLI 创建项目
+在创建过程中，它会提示你选择需要的特性，如 TypeScript、Pinia、Vue Router 等。对于初学者，可以先不选择，后续再手动添加。
+
+创建完成后，进入项目目录并启动开发服务器：
 ```bash
-npm install -g @vue/cli
-vue create my-vue-app
-cd my-vue-app
-npm run serve
+cd <your-project-name>
+npm install
+npm run dev
 ```
 
-## 🏗️ 核心概念
+## 🏗️ Vue 3 核心概念：组合式 API (Composition API)
 
-### 1. 数据绑定
-```html
-<div id="app">
-  <input v-model="msg">
-  <p>{{ msg }}</p>
-</div>
-<script>
-new Vue({
-  el: '#app',
-  data: { msg: '双向绑定' }
+Vue 3 引入了**组合式 API**，这是一种更强大、更灵活的代码组织方式，特别适合大型项目。我们本教程将主要使用这种方式。
+
+与之对应的是 Vue 2 中主要的**选项式 API (Options API)**。
+
+- **选项式 API**: 代码是根据 `data`, `methods`, `computed` 等选项来组织的。当组件变大时，一个功能的逻辑代码会被拆分到多个选项中，难以维护。
+- **组合式 API**: 代码是根据**逻辑功能**来组织的。你可以将同一个功能的代码（如响应式状态、方法、计算属性等）放在一起，提高了代码的可读性和可维护性。
+
+所有组合式 API 都需要在 `<script setup>` 块中使用。这是一种简洁的语法糖。
+
+```vue
+<script setup>
+// 在这里编写组件逻辑
+import { ref } from 'vue'
+
+const message = ref('Hello Vue 3!')
+</script>
+
+<template>
+  <h1>{{ message }}</h1>
+</template>
+```
+
+## ✨ 响应式系统： `ref()` 与 `reactive()`
+
+Vue 的核心是其响应式系统。当你修改了 JavaScript 中的数据，界面会自动更新。Vue 3 提供了两个主要的工具来实现响应性：`ref()` 和 `reactive()`。
+
+### 1. `ref()`
+`ref()` 用于创建任何类型值的响应式引用，包括基本类型 (如字符串、数字) 和对象。
+
+- **使用**: 需要通过 `.value` 来访问和修改其值。
+- **场景**: 最常用于处理单个值，如字符串、数字或布尔值。
+
+```vue
+<script setup>
+import { ref } from 'vue'
+
+const count = ref(0) // 创建一个响应式数字
+
+function increment() {
+  count.value++ // 必须使用 .value
+}
+</script>
+
+<template>
+  <button @click="increment">
+    Count is: {{ count }}
+  </button>
+</template>
+```
+> **注意**: 在模板 (`<template>`) 中使用时，Vue 会自动"解包"，你不需要写 `count.value`，可以直接写 `count`。
+
+### 2. `reactive()`
+`reactive()` **只能**用于创建响应式的**对象**或**数组**。
+
+- **使用**: 直接像普通对象一样访问和修改属性，不需要 `.value`。
+- **场景**: 最适合处理一组相关的、结构化的数据。
+- **限制**: 不能直接替换整个 `reactive` 对象，否则会失去响应性。
+
+```vue
+<script setup>
+import { reactive } from 'vue'
+
+const state = reactive({
+  user: {
+    name: '张三',
+    age: 20
+  }
 })
+
+function updateAge() {
+  state.user.age++
+}
 </script>
 ```
 
-### 2. 条件与循环
+**如何选择？**
+- 倾向于在所有地方都使用 `ref()`，这让代码风格更统一。
+- 当你有一组逻辑上紧密耦合的数据时，使用 `reactive()` 可以让代码更简洁。
+
+## 🔄 生命周期钩子 (Lifecycle Hooks)
+
+每个 Vue 组件实例在创建时都需要经历一系列的初始化步骤——例如，它需要设置数据监听、编译模板、将实例挂载到 DOM 并在数据变化时更新 DOM 等。这个过程允许我们使用**生命周期钩子**函数在特定阶段运行自己的代码。
+
+下面是几个最常用的生命周期钩子：
+
+- `onMounted`: 组件被挂载 (插入到 DOM) 后调用。常用于执行需要访问 DOM 的操作，或发起数据请求。
+- `onUpdated`: 组件因为响应式状态变更而更新其 DOM 树后调用。
+- `onUnmounted`: 组件被卸载 (从 DOM 中移除) 后调用。常用于清理定时器、事件监听器等。
+
+```vue
+<script setup>
+import { ref, onMounted, onUnmounted } from 'vue'
+
+const message = ref('Lifecycle hooks demo')
+
+onMounted(() => {
+  console.log('组件已挂载到 DOM！')
+  // 在这里可以安全地访问 DOM 或请求数据
+})
+
+onUnmounted(() => {
+  console.log('组件即将被卸载！')
+  // 在这里进行清理工作
+})
+</script>
+```
+
+<img src="https://v3.cn.vuejs.org/images/lifecycle.svg" alt="Vue Lifecycle Diagram" width="800">
+
+## 📜 模板语法详解
+
+### 文本插值
+最基本的数据绑定形式是使用"Mustache"语法 (双大括号) 的文本插值：
 ```html
-<div v-if="isShow">显示内容</div>
-<ul>
-  <li v-for="item in list" :key="item.id">{{ item.name }}</li>
-</ul>
+<span>Message: {{ msg }}</span>
 ```
 
-### 3. 事件处理
+### 属性绑定 (`v-bind`)
+双大括号不能在 HTML 属性 (attributes) 中使用。想要响应式地绑定一个属性，应该使用 `v-bind` 指令，通常简写为 `:`。
+
 ```html
-<button @click="count++">点击 {{ count }}</button>
+<!-- 完整语法 -->
+<div v-bind:id="dynamicId"></div>
+
+<!-- 简写 -->
+<div :id="dynamicId"></div>
+
+<!-- 绑定布尔值 -->
+<button :disabled="isButtonDisabled">Button</button>
 ```
 
-### 4. 计算属性与侦听器
-```js
-computed: {
-  reversedMsg() { return this.msg.split('').reverse().join('') }
-},
-watch: {
-  msg(newVal) { console.log('msg changed:', newVal) }
-}
+### Class 与 Style 绑定
+`v-bind` 最常见的用途之一是动态地切换元素的 class 或 style。
+
+```html
+<!-- 动态切换 class -->
+<div :class="{ active: isActive, 'text-danger': hasError }"></div>
+
+<!-- 绑定内联样式 -->
+<div :style="{ color: activeColor, fontSize: fontSize + 'px' }"></div>
 ```
 
-### 5. 组件化开发
-```js
-Vue.component('my-item', {
-  props: ['text'],
-  template: '<li>{{ text }}</li>'
-})
+### 条件渲染 (`v-if`, `v-else-if`, `v-else`)
+用于根据条件来渲染或销毁元素。
+```html
+<div v-if="type === 'A'">A</div>
+<div v-else-if="type === 'B'">B</div>
+<div v-else>Not A/B</div>
 ```
 
-## 🛠️ 与后端 API 交互
+### 列表渲染 (`v-for`)
+用于基于一个数组来渲染一个列表。需要提供一个 `key` 来帮助 Vue 跟踪每个节点的身份。
+```html
+<ul>
+  <li v-for="item in items" :key="item.id">
+    {{ item.text }}
+  </li>
+</ul>
+```
 
-### 使用 axios
-```bash
-npm install axios
+## 🖱️ 事件处理 (`v-on`)
+
+我们可以使用 `v-on` 指令 (通常简写为 `@`) 来监听 DOM 事件。
+
+```html
+<!-- 内联事件处理器 -->
+<button @click="count++">Add 1</button>
+
+<!-- 方法事件处理器 -->
+<button @click="greet">Greet</button>
 ```
-```js
-import axios from 'axios'
-axios.get('/api/users').then(res => { this.users = res.data })
+
+### 事件修饰符
+Vue 提供了一些事件修饰符：
+- `.stop`: 阻止事件继续传播。
+- `.prevent`: 阻止元素的默认行为。
+- `.self`: 只当事件是从侦听器绑定的元素本身触发时才触发处理函数。
+
+```html
+<!-- 阻止单击事件继续传播 -->
+<a @click.stop="doThis"></a>
+
+<!-- 提交事件不再重载页面 -->
+<form @submit.prevent="onSubmit"></form>
 ```
 
-### 异步数据加载
-```js
-created() {
-  axios.get('/api/todos').then(res => { this.todos = res.data })
-}
+## 📝 表单输入绑定 (`v-model`)
+
+`v-model` 指令可以在表单的 `<input>`、`<textarea>` 及 `<select>` 元素上创建双向数据绑定。它会根据控件类型自动选取正确的方法来更新元素。
+
+```html
+<!-- 文本输入 -->
+<input v-model="text" placeholder="Edit me">
+<p>Message is: {{ text }}</p>
+
+<!-- 复选框 -->
+<input type="checkbox" id="checkbox" v-model="checked">
+<label for="checkbox">{{ checked }}</label>
 ```
 
 ## 📚 学习资源
-- [Vue.js 官方文档](https://cn.vuejs.org/)
-- [Vue CLI 文档](https://cli.vuejs.org/zh/)
-- [Vue 组件化开发](https://cn.vuejs.org/v2/guide/components.html)
+
+- **[Vue.js 官方文档 (v3)](https://cn.vuejs.org/)**: 学习 Vue 最权威、最全面的资源。
+- **[Vite 官方文档](https://cn.vitejs.dev/)**: 了解现代前端构建工具。
+- **[Vue 官方示例](https://cn.vuejs.org/guide/examples.html)**: 官方提供的各种功能的小型示例。
 
 ## 🔍 知识检查
-- [ ] 理解 Vue 的数据绑定和响应式原理
-- [ ] 能够使用指令（v-if/v-for/v-model）
-- [ ] 能够编写简单的组件
-- [ ] 能够与后端 API 交互
+
+- [ ] 理解 Vue 的渐进式框架理念是什么？
+- [ ] 知道如何使用 `Vite` 创建一个 Vue 项目。
+- [ ] 能够区分组合式 API 和选项式 API 的不同。
+- [ ] 能够解释 `ref()` 和 `reactive()` 的区别和适用场景。
+- [ ] 了解 `onMounted` 等生命周期钩子的作用。
+- [ ] 熟练使用 `v-bind`, `v-if`, `v-for`, `@click`, `v-model` 等常用指令。
+- [ ] 知道如何使用事件修饰符（如 `.prevent`）。
 
 ---