# ephron.ren 功能需求文档

> 版本: v1.0
> 更新日期: 2026-05-05
> 状态: 待评审

---

## 概述

本文档记录 ephron.ren 建议新增的功能需求，按优先级和模块分类。

---

## 一、Home 服务

**现状**: 无API实现，仅有页面路由

### 1.1 个人资料 API

**优先级**: P0

| 方法 | 路径 | 权限 | 说明 |
|------|------|------|------|
| GET | `/api/v1/profile` | 🟢 公开 | 获取个人资料 |

**响应示例**:
```json
{
  "username": "ephron",
  "display_name": "Ephron",
  "bio": "全栈开发者",
  "avatar_url": "https://cdn.ephron.ren/avatar.jpg",
  "social": {
    "github": "https://github.com/ephron",
    "twitter": "https://twitter.com/ephron"
  }
}
```

**实现建议**: 从数据库或配置文件读取个人资料

---

### 1.2 技能列表 API

**优先级**: P1

| 方法 | 路径 | 权限 | 说明 |
|------|------|------|------|
| GET | `/api/v1/skills` | 🟢 公开 | 获取技能列表 |

**响应示例**:
```json
{
  "skills": [
    {"name": "Python", "level": 90, "category": "后端"},
    {"name": "React", "level": 85, "category": "前端"}
  ]
}
```

---

### 1.3 项目作品 API

**优先级**: P1

| 方法 | 路径 | 权限 | 说明 |
|------|------|------|------|
| GET | `/api/v1/projects` | 🟢 公开 | 项目列表 |
| GET | `/api/v1/projects/{id}` | 🟢 公开 | 项目详情 |

---

### 1.4 时间线 API

**优先级**: P2

| 方法 | 路径 | 权限 | 说明 |
|------|------|------|------|
| GET | `/api/v1/timeline` | 🟢 公开 | 经历时间线 |

---

## 二、Auth 服务

**现状**: 已实现基础认证，缺少用户管理API

### 2.1 用户资料 API

**优先级**: P0

| 方法 | 路径 | 权限 | 说明 |
|------|------|------|------|
| GET | `/api/v1/users/{username}` | 🟢 公开 | 获取用户公开信息 |
| GET | `/api/v1/me` | 🔵 用户 | 获取当前用户信息 |
| PATCH | `/api/v1/me` | 🔵 用户 | 更新个人资料 |

**实现建议**: 
- 用户公开信息：用户名、头像、简介、注册时间
- 当前用户信息：包含邮箱、角色等私有信息

---

### 2.2 密码管理 API

**优先级**: P1

| 方法 | 路径 | 权限 | 说明 |
|------|------|------|------|
| POST | `/api/v1/me/change-password` | 🔵 用户 | 修改密码 |
| POST | `/api/v1/auth/forgot-password` | 🟢 公开 | 发送重置邮件 |
| POST | `/api/v1/auth/reset-password` | 🟢 公开 | 重置密码 |

**实现建议**:
- 需要集成邮件服务（SMTP）
- 重置Token有效期24小时
- 使用安全的密码哈希（bcrypt/argon2）

---

### 2.3 API Key 管理

**优先级**: P1

| 方法 | 路径 | 权限 | 说明 |
|------|------|------|------|
| POST | `/api/v1/me/api-keys` | 🔵 用户 | 生成 API Key |
| GET | `/api/v1/me/api-keys` | 🔵 用户 | 列出 API Keys |
| DELETE | `/api/v1/me/api-keys/{key_id}` | 🔵 用户 | 删除 API Key |

**实现建议**:
- API Key 格式: `sk-xxxxxxxx`
- 存储时只保存哈希值
- 支持设置权限范围

---

## 三、Blog 服务

**现状**: 已实现文章CRUD和点赞，缺少搜索、收藏、版本管理

### 3.1 公开文章 API

**优先级**: P0

| 方法 | 路径 | 权限 | 说明 |
|------|------|------|------|
| GET | `/api/v1/posts` | 🟢 公开 | 文章列表 |
| GET | `/api/v1/posts/{slug}` | 🟢 公开 | 文章详情 |

**实现建议**:
- 列表支持分页、分类筛选
- 详情包含完整内容和元数据

---

### 3.2 文章搜索 API

**优先级**: P0

| 方法 | 路径 | 权限 | 说明 |
|------|------|------|------|
| GET | `/api/v1/posts/search` | 🟢 公开 | 全文搜索 |

**请求参数**:
| 参数 | 类型 | 说明 |
|------|------|------|
| q | string | 搜索关键词 |
| tag | string | 标签筛选 |
| sort | string | 排序: newest/popular |
| page | int | 页码 |

**实现建议**:
- 使用 SQLite FTS5 全文搜索
- 返回匹配摘要和高亮

---

### 3.3 文章互动 API

**优先级**: P1

| 方法 | 路径 | 权限 | 说明 |
|------|------|------|------|
| POST | `/api/v1/posts/{slug}/view` | 🟢 公开 | 记录阅读 |
| POST | `/api/v1/posts/{slug}/favorite` | 🔵 用户 | 收藏文章 |
| DELETE | `/api/v1/posts/{slug}/favorite` | 🔵 用户 | 取消收藏 |
| GET | `/api/v1/user/favorites` | 🔵 用户 | 收藏列表 |
| GET | `/api/v1/posts/{slug}/stats` | 🟢 公开 | 文章统计 |

**实现建议**:
- 阅读统计基于IP去重
- 收藏需要用户登录

---

### 3.4 图片上传 API

**优先级**: P1

| 方法 | 路径 | 权限 | 说明 |
|------|------|------|------|
| POST | `/api/v1/upload/image` | 🔵 用户 | 上传图片 |

**实现建议**:
- 支持 jpg/png/gif/webp
- 限制文件大小（5MB）
- 生成缩略图
- 存储到 CDN 或本地

---

### 3.5 版本管理 API

**优先级**: P2

| 方法 | 路径 | 权限 | 说明 |
|------|------|------|------|
| GET | `/api/v1/posts/{slug}/versions` | 🔵 用户 | 版本历史 |
| POST | `/api/v1/posts/{slug}/rollback/{id}` | 🔵 用户 | 回滚版本 |

---

## 四、Canvas 服务

**现状**: 已实现服务API CRUD，缺少公开API和互动功能

### 4.1 公开画布 API

**优先级**: P0

| 方法 | 路径 | 权限 | 说明 |
|------|------|------|------|
| GET | `/api/v1/canvas` | 🟢 公开 | 画布列表 |
| GET | `/api/v1/canvas/{slug}` | 🟢 公开 | 画布详情 |
| GET | `/api/v1/canvas/{slug}/raw` | 🟢 公开 | 原始内容 |
| POST | `/api/v1/canvas/{slug}/view` | 🟢 公开 | 记录浏览 |

---

### 4.2 画布互动 API

**优先级**: P1

| 方法 | 路径 | 权限 | 说明 |
|------|------|------|------|
| POST | `/api/v1/canvas/{slug}/like` | 🔵 用户 | 点赞 |
| DELETE | `/api/v1/canvas/{slug}/like` | 🔵 用户 | 取消点赞 |
| POST | `/api/v1/canvas/{slug}/favorite` | 🔵 用户 | 收藏 |
| DELETE | `/api/v1/canvas/{slug}/favorite` | 🔵 用户 | 取消收藏 |

---

### 4.3 画布模板 API

**优先级**: P2

| 方法 | 路径 | 权限 | 说明 |
|------|------|------|------|
| GET | `/api/v1/templates` | 🟢 公开 | 模板列表 |
| GET | `/api/v1/templates/{id}` | 🟢 公开 | 模板详情 |
| POST | `/api/v1/canvas/from-template/{id}` | 🔵 用户 | 从模板创建 |

---

### 4.4 画布分享 API

**优先级**: P2

| 方法 | 路径 | 权限 | 说明 |
|------|------|------|------|
| POST | `/api/v1/canvas/{slug}/share` | 🔵 用户 | 生成分享链接 |
| GET | `/api/v1/shared/{code}` | 🟢 公开 | 访问分享内容 |

---

## 五、Prompt 服务

**现状**: 已实现基础CRUD，缺少搜索、互动、批量操作

### 5.1 高级搜索 API

**优先级**: P0

| 方法 | 路径 | 权限 | 说明 |
|------|------|------|------|
| GET | `/api/v1/prompts/search` | 🟢 公开 | 高级搜索 |
| GET | `/api/v1/prompts/categories` | 🟢 公开 | 分类列表 |
| GET | `/api/v1/prompts/tags` | 🟢 公开 | 标签列表 |
| GET | `/api/v1/prompts/popular` | 🟢 公开 | 热门提示词 |

**实现建议**:
- 搜索支持全文、分类、标签筛选
- 返回分面统计（facets）

---

### 5.2 用户互动 API

**优先级**: P1

| 方法 | 路径 | 权限 | 说明 |
|------|------|------|------|
| POST | `/api/v1/prompts/{key}/use` | 🟢 公开 | 记录使用 |
| POST | `/api/v1/prompts/{key}/like` | 🔵 用户 | 点赞 |
| DELETE | `/api/v1/prompts/{key}/like` | 🔵 用户 | 取消点赞 |
| POST | `/api/v1/prompts/{key}/favorite` | 🔵 用户 | 收藏 |
| DELETE | `/api/v1/prompts/{key}/favorite` | 🔵 用户 | 取消收藏 |
| GET | `/api/v1/user/favorites` | 🔵 用户 | 收藏列表 |

---

### 5.3 批量操作 API

**优先级**: P1

| 方法 | 路径 | 权限 | 说明 |
|------|------|------|------|
| POST | `/api/v1/prompts/batch` | 🟡 服务 | 批量创建 |
| POST | `/api/v1/prompts/batch-delete` | 🟡 服务 | 批量删除 |
| GET | `/api/v1/prompts/export` | 🟡 服务 | 导出 |
| POST | `/api/v1/prompts/import` | 🟡 服务 | 导入 |

---

### 5.4 版本管理 API

**优先级**: P2

| 方法 | 路径 | 权限 | 说明 |
|------|------|------|------|
| GET | `/api/v1/prompts/{key}/versions` | 🟡 服务 | 版本历史 |
| GET | `/api/v1/prompts/{key}/versions/{v}` | 🟡 服务 | 特定版本 |
| POST | `/api/v1/prompts/{key}/rollback/{v}` | 🟡 服务 | 回滚版本 |

---

### 5.5 模板市场 API

**优先级**: P3

| 方法 | 路径 | 权限 | 说明 |
|------|------|------|------|
| GET | `/api/v1/marketplace` | 🟢 公开 | 市场列表 |
| GET | `/api/v1/marketplace/{key}` | 🟢 公开 | 模板详情 |
| POST | `/api/v1/marketplace/{key}/publish` | 🔵 用户 | 发布到市场 |
| POST | `/api/v1/marketplace/{key}/install` | 🔵 用户 | 安装模板 |

---

## 六、通用功能

### 6.1 文件上传服务

**优先级**: P1

| 方法 | 路径 | 权限 | 说明 |
|------|------|------|------|
| POST | `/api/v1/upload` | 🔵 用户 | 上传文件 |

**实现建议**:
- 支持图片、文档
- 生成唯一文件名
- 返回 CDN URL

---

### 6.2 通知服务

**优先级**: P2

| 方法 | 路径 | 权限 | 说明 |
|------|------|------|------|
| GET | `/api/v1/notifications` | 🔵 用户 | 通知列表 |
| POST | `/api/v1/notifications/{id}/read` | 🔵 用户 | 标记已读 |
| POST | `/api/v1/notifications/read-all` | 🔵 用户 | 全部已读 |

---

### 6.3 全局搜索

**优先级**: P2

| 方法 | 路径 | 权限 | 说明 |
|------|------|------|------|
| GET | `/api/v1/search` | 🟢 公开 | 跨服务搜索 |

---

### 6.4 Webhook 服务

**优先级**: P3

| 方法 | 路径 | 权限 | 说明 |
|------|------|------|------|
| POST | `/api/v1/webhooks` | 🔵 用户 | 创建 Webhook |
| GET | `/api/v1/webhooks` | 🔵 用户 | 列出 Webhooks |
| DELETE | `/api/v1/webhooks/{id}` | 🔵 用户 | 删除 Webhook |

---

## 七、数据库扩展

### 7.1 新增表

```sql
-- 用户收藏表
CREATE TABLE user_favorites (
    id INTEGER PRIMARY KEY,
    user_id TEXT NOT NULL,
    resource_type TEXT NOT NULL,  -- post | prompt | canvas
    resource_id TEXT NOT NULL,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    UNIQUE(user_id, resource_type, resource_id)
);

-- 使用统计表
CREATE TABLE usage_stats (
    id INTEGER PRIMARY KEY,
    resource_type TEXT NOT NULL,
    resource_id TEXT NOT NULL,
    user_id TEXT,
    action TEXT NOT NULL,  -- view | like | use
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

-- API Keys 表
CREATE TABLE api_keys (
    id INTEGER PRIMARY KEY,
    key_id TEXT UNIQUE NOT NULL,
    user_id TEXT NOT NULL,
    key_hash TEXT NOT NULL,
    name TEXT,
    permissions TEXT,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    last_used_at TIMESTAMP,
    is_active BOOLEAN DEFAULT TRUE
);

-- 通知表
CREATE TABLE notifications (
    id INTEGER PRIMARY KEY,
    user_id TEXT NOT NULL,
    type TEXT NOT NULL,
    title TEXT NOT NULL,
    message TEXT,
    link TEXT,
    read BOOLEAN DEFAULT FALSE,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);
```

---

## 八、实现优先级总览

### P0 - 核心功能（6个）

| 服务 | 功能 | 说明 |
|------|------|------|
| Home | 个人资料API | 首页展示 |
| Auth | 用户资料API | 用户系统基础 |
| Blog | 公开文章API | 内容展示 |
| Blog | 文章搜索API | 用户体验 |
| Canvas | 公开画布API | 服务完整性 |
| Prompt | 高级搜索API | 用户体验 |

### P1 - 重要功能（12个）

| 服务 | 功能 | 说明 |
|------|------|------|
| Auth | 密码管理 | 用户体验 |
| Auth | API Key | 第三方集成 |
| Blog | 文章互动 | 用户参与 |
| Blog | 图片上传 | 内容创作 |
| Canvas | 画布互动 | 用户参与 |
| Prompt | 用户互动 | 用户参与 |
| Prompt | 批量操作 | 管理效率 |
| 通用 | 文件上传 | 多服务复用 |

### P2 - 增强功能（8个）

| 服务 | 功能 | 说明 |
|------|------|------|
| Home | 技能列表 | 首页展示 |
| Home | 项目作品 | 首页展示 |
| Blog | 版本管理 | 内容管理 |
| Canvas | 画布模板 | 用户便利 |
| Canvas | 画布分享 | 内容传播 |
| Prompt | 版本管理 | 内容管理 |
| 通用 | 通知服务 | 用户提醒 |
| 通用 | 全局搜索 | 用户体验 |

### P3 - 扩展功能（5个）

| 服务 | 功能 | 说明 |
|------|------|------|
| Home | 时间线 | 首页展示 |
| Prompt | 模板市场 | 社区生态 |
| 通用 | Webhook | 自动化 |

---

## 九、相关文档

- [API 文档](./api-specification.md)