# zhora-front

**Repository Path**: coding_13/zhora-front

## Basic Information

- **Project Name**: zhora-front
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-08
- **Last Updated**: 2026-04-08

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 灏米AI前端（`zhora-front`）

基于 Vue 3 + Vite + Element Plus 的社区前端项目，已完成社区列表/详情、发布图片、登录态、个人中心等核心流程，并对接后端分页接口。

## 1. 功能说明（当前实现）

### 1.1 全局框架
- 左侧主导航（创意社区为主入口，其他菜单为规划占位）
- 顶部/侧栏品牌展示统一为「灏米AI」
- 响应式布局（桌面端 + 移动端侧栏弹出）
- 版本切换（本地持久化）

### 1.2 认证与账号能力
- 登录方式：飞书 OAuth（可开关）+ 密码登录
- 本地存储 token 与用户信息（Pinia + localStorage）
- 按需鉴权：浏览社区不强制登录，点赞/收藏/发布等能力需登录
- 个人中心名称优先读取 `name` 字段

### 1.3 社区列表页（`/community`）
- 标签页：最新 / 热门 / 点赞
- 后端分页加载（触底自动加载更多）
- 排序参数对接：
  - 最新：`sortType = LATEST`
  - 热门：`sortType = MOST_LIKED`
- 瀑布流展示：固定高度档位 + 最短列优先分配（不依赖原图尺寸）
- 卡片 hover 操作：下载、点赞
- 头像字段兼容（含协议相对 URL `//xxx` 自动补全为 `https://xxx`）

### 1.4 作品详情页（`/community/:id`）
- 展示标题、标签、统计、轮播图、作品描述
- 时间字段仅使用新协议：
  - 创建时间：`createTime`
  - 更新时间：`updateTime`
- 描述区名称为「作品描述」
- 右侧作者信息、收藏、下载、推荐参数等扩展信息

### 1.5 发布图片（弹窗）
- 本地多图上传、封面选择、分类标签、标题/描述填写
- 提交方式：`POST multipart/form-data`
- 图片字段按嵌套结构提交（`images[i].file`、`images[i].isCover`）

### 1.6 请求层能力（全局）
- 全局 Loading（自动开启/关闭）
- 防重复提交（同 method + url + body 的请求并发时拦截）
- 统一鉴权头注入与统一错误处理

## 2. 后端接口对接约定

> `VITE_API_BASE_URL` 建议指向后端 `/front` 根路径，例如 `http://127.0.0.1:19002/front`。

### 2.1 社区分页接口
- 路径：`POST /v1/artworks/page`（最终请求地址为 `${VITE_API_BASE_URL}/v1/artworks/page`）
- 请求体示例：

```json
{
  "pageNum": 1,
  "pageSize": 20,
  "sortType": "LATEST"
}
```

- 排序枚举：
  - `LATEST`：最新
  - `MOST_LIKED`：点赞最高

- 前端关注字段（核心）：
  - `id`
  - `title`
  - `authorName`
  - `authorAvatarUrl`
  - `coverImageUrls`（列表封面优先）
  - `imageUrls`（详情图优先）
  - `description`
  - `createTime`（`yyyy-MM-dd HH:mm`）
  - `updateTime`（`yyyy-MM-dd HH:mm`）
  - `likes` / `likeCount`（二选一兼容）

### 2.2 图片发布接口
- 路径：`POST /api/v1/artworks/push`
- `Content-Type: multipart/form-data`
- 关键字段：
  - `title`
  - `description`
  - `tagIds`（多值）
  - `images[0].file`, `images[0].isCover` ...

## 3. 开发要求

### 3.1 代码规范要求
- 统一使用 Vue 3 `<script setup>`
- 业务状态放 Pinia，避免组件层跨级传递
- 接口调用统一走 `src/utils/api.js`，禁止散落 `fetch`
- 新接口字段变更要在映射函数集中处理（如 `normalizeCard`）
- 保持 UI 文案和后端字段语义一致（例如「作品描述」对应 `description`）

### 3.2 接口联调要求
- 所有新接口优先在社区页进行最小可用联调（列表、详情、分页、排序）
- 时间字段仅接受 `createTime` / `updateTime`，不再回退旧 `publishTime`
- 列表封面优先 `coverImageUrls`，详情优先 `imageUrls`

### 3.3 交互与体验要求
- 所有请求默认有 Loading
- 防止重复点击导致的重复提交
- 空状态、错误提示、无更多数据提示必须具备

## 4. 技术栈

- Vue 3
- Vite 6
- Vue Router 4
- Pinia 2
- Element Plus 2
- `@element-plus/icons-vue`

## 5. 目录结构（核心）

- `src/layouts/AppLayout.vue`：整体布局
- `src/views/CommunityView.vue`：社区列表 + 瀑布流 + 分页
- `src/views/WorkDetailView.vue`：作品详情
- `src/views/PersonalCenterView.vue`：个人中心
- `src/components/publish/ImagePublishDialog.vue`：图片发布
- `src/stores/auth.js`：登录态、鉴权能力
- `src/stores/community-interaction.js`：点赞/收藏本地交互
- `src/utils/api.js`：请求封装（loading、防重、鉴权、错误处理）
- `src/data/community-works.js`：详情缓存与演示兜底

## 6. 环境变量

参考 `.env.example`。

- `VITE_API_BASE_URL`：后端 API 根地址（建议包含 `/front`）
- `VITE_FEISHU_APP_ID`：飞书应用 ID
- `VITE_FEISHU_REDIRECT_URI`：飞书回调地址
- `VITE_AUTH_EXCHANGE_URL`：后端换票接口（可选）
- `VITE_ENABLE_FEISHU_OAUTH`：是否启用飞书 OAuth
- `VITE_DEV_BYPASS_AUTH`：开发环境是否跳过登录校验
- `VITE_DEV_OAUTH_STORE_CODE`：无后端换票时的开发兜底

## 7. 本地开发

安装依赖：

```bash
npm install
```

启动开发环境：

```bash
npm run dev
```

构建：

```bash
npm run build
```

预览构建产物：

```bash
npm run preview
```

## 8. 备注

- 若后端接口字段新增/变更，请优先更新 `CommunityView` 的数据映射函数并同步 README。
- 生产环境严禁在前端暴露飞书 `app_secret`，换票必须后端完成。