509 lines
12 KiB
Markdown
509 lines
12 KiB
Markdown
# 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)
|