# turing-frontend

**Repository Path**: Nomini/turing-frontend

## Basic Information

- **Project Name**: turing-frontend
- **Description**: 图灵科竟社官网前端项目
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 3
- **Created**: 2025-10-01
- **Last Updated**: 2025-12-15

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 🌱 Vue3 Template 项目说明

一个现代化的 Vue3 前端模板，支持模块化开发、状态管理、主题切换和丰富的资源管理。

---

## 🚀 快速开始

1. **拉取项目代码**
   ```bash
   git clone <你的仓库地址>
   cd vue-template
   ```

2. **安装依赖**
   ```bash
   npm install
   ```

3. **环境变量配置**
   - 在项目根目录下修改 `.env` 或 `.env.development` 文件，配置你的后端 API 地址等参数：
     ```env
     VUE_APP_API_BASE_URL=http://localhost:3000/api
     VUE_APP_API_TIMEOUT=10000
     ```
   - 如有变更，需重启开发服务器。

4. **本地运行项目**
   ```bash
   npm run serve
   ```

5. **打包生产环境**
   ```bash
   npm run build
   ```

6. **代码检查与修复**
   ```bash
   npm run lint
   ```

---

## 🗂️ 项目结构介绍

项目采用模块化架构，主要分为以下功能模块：

<details>
<summary><b>public/</b> 公共资源</summary>

- <code>index.html</code>：项目入口 HTML  
- <code>favicon.ico</code>：网站图标  
- <code>resources/</code>：文档、视频等大型静态资源（建议少放）

</details>

<details>
<summary><b>src/</b> 前端源码</summary>

- <b>api/</b>  
  <ul>
    <li><code>httpClient.js</code>：axios 封装，统一请求/响应/错误处理</li>
    <li><code>services/</code>：具体业务 API 服务（如认证、用户、设置等）</li>
    <li><code>index.js</code>：API 统一出口</li>
  </ul>
- <b>assets/</b>  
  <ul>
    <li><code>icons/</code>：SVG、PNG 图标</li>
    <li><code>images/</code>：图片资源</li>
    <li><code>media/</code>：音视频等多媒体资源</li>
    <li><code>styles/</code>：全局和主题样式</li>
  </ul>
- <b>components/</b>  
  <ul>
    <li>公共组件（如头部、底部、主题切换、图标等）</li>
  </ul>
- <b>composables/</b>  
  <ul>
    <li>组合式 API 封装（如 <code>useApi</code>），便于逻辑复用</li>
  </ul>
- <b>router/</b>  
  <ul>
    <li><code>index.js</code>：路由配置</li>
    <li><code>guards.js</code>：路由守卫（认证、权限）</li>
  </ul>
- <b>stores/</b>  
  <ul>
    <li>Pinia 状态管理（如认证、主题）</li>
  </ul>
- <b>utils/</b>  
  <ul>
    <li>工具函数（如错误处理）</li>
  </ul>
- <b>views/</b>  
  <ul>
    <li>页面视图（如首页、登录、个人资料、设置、404、Demo 等）</li>
  </ul>
- <code>App.vue</code> / <code>main.js</code>：应用入口和根组件  
- <code>babel.config.js</code> / <code>vue.config.js</code> / <code>jsconfig.json</code>：构建和开发相关配置

</details>

---

## 🛠️ 开发指南

### 页面开发

- **新增页面**：在 <code>src/views/</code> 下创建 `.vue` 文件，并在 <code>src/router/index.js</code> 添加路由配置。
- **修改页面**：直接编辑对应的 `.vue` 文件。

### 组件开发

- **新增组件**：在 <code>src/components/</code> 下创建 `.vue` 文件，按需在页面或其他组件中引用。
- **图标组件**：建议放在 <code>src/components/icons/</code>。

### API 接口开发

- **新增业务接口**：在 <code>src/api/services/</code> 下添加服务文件，并在 <code>src/api/services/index.js</code> 导出。
- **统一请求**：所有接口通过 <code>src/api/httpClient.js</code> 发起。

### 状态管理

- **新增/修改全局状态**：在 <code>src/stores/</code> 下创建或编辑 store 文件，使用 Pinia 管理。

### 路由与权限

- **路由配置**：在 <code>src/router/index.js</code> 添加或修改路由。
- **路由守卫**：如需自定义认证或权限逻辑，编辑 <code>src/router/guards.js</code>。

### 样式与主题

- **全局样式**：编辑 <code>src/assets/styles/main.css</code>。
- **主题样式**：编辑 <code>src/assets/styles/themes.css</code>，并通过 <code>theme.store.js</code> 切换主题。

### 静态资源

- 图片、图标等资源建议放在 <code>src/assets/</code> 下对应目录。
- 大型静态资源建议放在 <code>public/resources/</code>，避免打包进前端。

---

## 📝 发帖编辑器（BlockNote）集成说明

本项目将集成 BlockNote 作为发帖富文本编辑器，前端使用 `@blocknote/vue`，与后端约定上传接口 `POST /v1/posts/upload`（通过 `VUE_APP_API_BASE_URL` 拼接为 `/api/v1/posts/upload`）。

### 依赖安装

```bash
npm i @blocknote/vue @blocknote/core
```

如需 Markdown 导入/导出，将在第二阶段加入相应依赖。

### 路由与文件约定（建议）

- 新页面：`/posts/new`
- 组件：`src/components/PostEditor.vue`（封装 BlockNote 编辑器）
- 页面：`src/views/NewPost.vue`（标题/标签/封面/编辑器/操作栏）

### 后端接口契约

- Method: `POST /v1/posts/upload`
- Request Body（application/json）：
  - `postInfo`（必需）
    - `title`（string，必需）
    - `author`（object，必需）：`{ id, name, avatarUrl, bio }`
    - `excerpt`（string，必需）
    - `publishTime`（string<date-time>，必需）
    - `readCount` | `likeCount` | `commentCount`（integer，前端先传 0 或由后端默认）
    - `previewImage`（string<uri>，可选）
    - `targetUrl`（null 或 string<uri>，本项目约定可传 `null`）
    - `tags`（array<{id,name}>，必需）
  - `postContent`（必需）
    - `format`（enum：`markdown` | `rich_text` | `json_ast`；本项目第一阶段使用 `json_ast`）
    - `content`（string，帖子内容；当为 `json_ast` 时为 BlockNote 文档 JSON 的字符串）
- Response（application/json）：
  - `{ code: number, message: string, data: object }`，成功时 `code = 0`

### 前端服务用法示例

建议在 `src/api/services/post.service.js` 中新增上传方法：

```js
// src/api/services/post.service.js
import httpClient from "../httpClient";

export const uploadPost = async (payload) => {
  // payload 需包含 postInfo 与 postContent
  return await httpClient.post("/v1/posts/upload", payload);
};
```

在页面中调用：

```js
import { uploadPost } from "@/api/services/post.service";

const res = await uploadPost({ postInfo, postContent });
if (res.code === 0) {
  // 成功处理
}
```

### 生成 payload 示例（使用 BlockNote JSON）

假设已在 `PostEditor.vue` 中拿到 BlockNote 文档对象 `doc`（通常通过 BlockNote API `editor.document` 或 `onChange` 获取），第一阶段将其作为 `json_ast` 字符串上送：

```js
const postInfo = {
  title: form.title,
  author: {
    id: currentUser.id,
    name: currentUser.name,
    avatarUrl: currentUser.avatarUrl,
    bio: currentUser.bio,
  },
  excerpt: form.excerpt ?? generateExcerptFromDoc(doc),
  publishTime: new Date().toISOString().slice(0, 19).replace("T", " "),
  readCount: 0,
  likeCount: 0,
  commentCount: 0,
  previewImage: form.previewImage || undefined,
  targetUrl: null,
  tags: form.tags, // e.g. [{ id:101, name:"DP" }]
};

const postContent = {
  format: "json_ast",
  content: JSON.stringify(doc),
};

await uploadPost({ postInfo, postContent });
```

### 草稿与自动保存（建议）

- 本地草稿：以 `draft:new-post` 作为键在 `localStorage` 周期性保存编辑内容
- 页面卸载提醒：存在未发布内容时弹出确认

---

## ❓ 常见问题

- <b>环境变量未生效？</b>  
  检查 <code>.env.development</code> 文件是否正确命名并放在项目根目录。修改后需重启开发服务器。

- <b>接口请求失败？</b>  
  检查 <code>VUE_APP_API_BASE_URL</code> 是否配置正确，后端服务是否已启动。

- <b>页面 404？</b>  
  确认路由配置和页面文件是否存在。

---

> 如有问题欢迎提 Issue 或 PR！