400 lines
15 KiB
Markdown
400 lines
15 KiB
Markdown
# Vue3 + Python Notepad 应用 - 产品需求文档 (PRD)
|
||
|
||
**文档版本**: 1.0
|
||
**创建日期**: 2025-12-18
|
||
**作者**: BMad Analyst
|
||
**项目状态**: Greenfield (全新开发)
|
||
|
||
---
|
||
|
||
## 1. Goals and Background Context
|
||
|
||
### 1.1 Goals
|
||
|
||
- 提供一个简单、实时的在线文本编辑器，通过URL直接访问特定文件
|
||
- 实现自动保存功能，无需用户手动操作
|
||
- 提供文件列表页面，方便用户管理和访问所有文档
|
||
- 确保应用安全、稳定，能够处理各种边界情况
|
||
- 支持在Ubuntu物理机上通过Docker部署
|
||
|
||
### 1.2 Background Context
|
||
|
||
本项目旨在开发一个轻量级的在线Notepad应用，结合Vue3前端和Python后端技术栈。用户可以通过URL直接访问和编辑文本文件，所有更改会自动保存到服务器。应用设计遵循简单、实时、URL驱动的理念，适合个人或小型团队快速记录和分享文本内容。
|
||
|
||
该应用解决了传统文本编辑器需要手动保存、文件共享不便的问题，通过浏览器即可访问，无需安装额外软件。特别适合需要快速记录、跨设备访问文本内容的场景。
|
||
|
||
### 1.3 Change Log
|
||
|
||
| 日期 | 版本 | 描述 | 作者 |
|
||
|------|------|------|------|
|
||
| 2025-12-18 | 1.0 | 初始PRD文档创建 | BMad Analyst |
|
||
|
||
---
|
||
|
||
## 2. Requirements
|
||
|
||
### 2.1 Functional Requirements
|
||
|
||
**FR1**: 用户可以通过URL路径访问特定文本文件，URL格式为 `/notes/{filename}.txt`
|
||
|
||
**FR2**: 如果访问的文件不存在，系统自动创建空白文件；如果文件已存在，加载并显示内容
|
||
|
||
**FR3**: 提供文本编辑区域，支持用户输入和编辑内容，文件大小限制为10万字符
|
||
|
||
**FR4**: 实现自动保存功能，当用户停止输入或内容发生变化时自动保存到服务器
|
||
|
||
**FR5**: 提供文件列表页面 `/file-list`，显示所有txt文件的列表（文件名、创建时间）
|
||
|
||
**FR6**: 文件列表页面需要后端口令验证，只有通过POST请求提供正确口令才能访问
|
||
|
||
**FR7**: 从文件列表页面点击文件名可以直接跳转到对应的编辑页面
|
||
|
||
**FR8**: 对URL中的文件名进行验证和过滤，阻止包含特殊字符（如 `/`, `\\`, `..`）的文件名
|
||
|
||
**FR9**: 当文件达到10万字符限制时，阻止用户继续输入并显示提示信息
|
||
|
||
**FR10**: 提供适当的错误处理和用户提示，包括网络错误、保存失败、文件访问错误等
|
||
|
||
**FR11**: 支持中文文件名，正确处理URL编码和解码
|
||
|
||
**FR12**: 文件列表页面支持分页或滚动加载，以处理大量文件的情况
|
||
|
||
### 2.2 Non-Functional Requirements
|
||
|
||
**NFR1**: 应用响应时间应在100ms以内（不包括网络延迟）
|
||
|
||
**NFR2**: 自动保存操作应在用户停止输入后500ms内触发
|
||
|
||
**NFR3**: 系统应支持至少100个并发用户编辑不同文件
|
||
|
||
**NFR4**: 应用应部署在Docker容器中，支持在Ubuntu物理机上运行
|
||
|
||
**NFR5**: 前端资源应优化加载，首屏加载时间不超过2秒
|
||
|
||
**NFR6**: 应用日志应记录关键操作（文件创建、保存、访问）以便故障排查
|
||
|
||
**NFR7**: 系统应具备基本的错误恢复能力，网络断开后能自动重连
|
||
|
||
---
|
||
|
||
## 3. User Interface Design Goals
|
||
|
||
### 3.1 Overall UX Vision
|
||
|
||
创建一个简洁、直观的文本编辑体验，界面设计遵循极简主义原则。用户打开页面即可立即开始编辑，无需复杂的设置或学习成本。编辑区域占据主要空间，提供舒适的阅读和写作环境。
|
||
|
||
### 3.2 Key Interaction Paradigms
|
||
|
||
- **直接编辑**: 页面加载完成后，光标自动定位到编辑区域，用户可以立即开始输入
|
||
- **实时反馈**: 自动保存状态通过视觉指示器显示（如"已保存"、"保存中..."）
|
||
- **URL驱动导航**: 用户可以通过修改URL直接访问不同文件，支持浏览器前进/后退
|
||
- **无缝文件管理**: 从文件列表到编辑页面的切换应流畅自然，保持用户体验一致性
|
||
|
||
### 3.3 Core Screens and Views
|
||
|
||
1. **文本编辑页面**: 主要编辑界面，包含文本编辑区域、文件名显示、自动保存状态指示器
|
||
2. **文件列表页面**: 显示所有可用文件的列表，包含文件名、创建时间，以及口令输入表单
|
||
3. **错误提示页面**: 显示各种错误信息，如文件访问被拒绝、文件不存在等
|
||
|
||
### 3.4 Accessibility
|
||
|
||
**WCAG AA** - 遵循WCAG 2.1 AA级标准，确保文本对比度、键盘导航、屏幕阅读器兼容性
|
||
|
||
### 3.5 Branding
|
||
|
||
- 采用现代、简洁的设计风格
|
||
- 使用系统默认字体，确保跨平台一致性
|
||
- 配色方案：浅色背景 + 深色文本，高对比度确保可读性
|
||
|
||
### 3.6 Target Device and Platforms
|
||
|
||
**Web Responsive** - 主要面向桌面浏览器，同时支持平板和手机的基本访问功能
|
||
|
||
---
|
||
|
||
## 4. Technical Assumptions
|
||
|
||
### 4.1 Repository Structure
|
||
|
||
**Monorepo** - 前端和后端代码存放在同一个仓库中，便于协调开发和部署
|
||
|
||
### 4.2 Service Architecture
|
||
|
||
**Monolith** - 采用单体架构，Python后端提供API服务和静态文件服务，Vue3前端构建为静态资源
|
||
|
||
### 4.3 Testing Requirements
|
||
|
||
**Unit + Integration** - 编写单元测试覆盖核心功能，以及集成测试验证端到端流程
|
||
|
||
### 4.4 Additional Technical Assumptions and Requests
|
||
|
||
- **前端框架**: Vue 3 (Composition API) - 选择理由：现代、轻量、易学、生态系统完善
|
||
- **后端框架**: FastAPI - 选择理由：高性能、自动API文档、内置WebSocket支持、类型注解
|
||
- **实时通信**: WebSocket - 用于实现实时自动保存和状态同步
|
||
- **文件存储**: 本地文件系统 - 简单直接，无需数据库，符合项目轻量级定位
|
||
- **部署方式**: Docker容器化 - 便于在Ubuntu物理机上部署和管理
|
||
- **静态文件服务**: Nginx或Python后端直接服务 - 根据性能需求决定
|
||
- **开发语言**: TypeScript (前端) + Python 3.10+ (后端) - 类型安全、现代特性
|
||
- **构建工具**: Vite - 快速的开发服务器和构建工具
|
||
- **包管理器**: npm/pnpm (前端) + pip/poetry (后端)
|
||
|
||
---
|
||
|
||
## 5. Epic List
|
||
|
||
### Epic 1: 基础架构与核心编辑功能
|
||
建立项目基础架构，实现核心文本编辑和自动保存功能
|
||
|
||
### Epic 2: 文件管理与安全控制
|
||
实现文件列表页面和后端口令验证功能
|
||
|
||
### Epic 3: 边界条件处理与部署优化
|
||
完善异常处理、输入验证，配置Docker部署
|
||
|
||
---
|
||
|
||
## 6. Epic 1: 基础架构与核心编辑功能
|
||
|
||
**Epic Goal**: 建立前后端项目基础架构，实现核心文本编辑功能、URL路由和自动保存机制，为应用提供基本可用的文本编辑能力。
|
||
|
||
### Story 1.1: 前端项目初始化与基础UI搭建
|
||
|
||
**作为** 开发者
|
||
**我想要** 初始化Vue3项目并创建基础文本编辑界面
|
||
**以便** 为用户提供文本编辑功能
|
||
|
||
#### Acceptance Criteria
|
||
|
||
1. 使用Vite初始化Vue3项目，配置TypeScript
|
||
2. 创建文本编辑组件，包含textarea元素占据主要界面空间
|
||
3. 实现基本的数据绑定，将textarea内容绑定到Vue响应式变量
|
||
4. 添加简单的CSS样式，确保编辑区域美观易用
|
||
5. 配置开发服务器，能够在本地运行并访问
|
||
|
||
### Story 1.2: 后端项目初始化与文件API开发
|
||
|
||
**作为** 开发者
|
||
**我想要** 搭建Python FastAPI项目并实现文件读写API
|
||
**以便** 为前端提供文件存储服务
|
||
|
||
#### Acceptance Criteria
|
||
|
||
1. 创建FastAPI项目，配置必要的依赖（fastapi, uvicorn, python-multipart）
|
||
2. 实现GET `/api/notes/{filename}` 接口：读取文件内容，文件不存在时创建空文件
|
||
3. 实现POST `/api/notes/{filename}` 接口：接收文本内容并保存到文件
|
||
4. 配置文件存储目录（如 `./data/notes/`），确保目录存在
|
||
5. 添加CORS配置，允许前端跨域访问
|
||
6. 实现基本的错误处理，返回适当的HTTP状态码和错误信息
|
||
|
||
### Story 1.3: URL路由与文件加载集成
|
||
|
||
**作为** 用户
|
||
**我想要** 通过URL访问特定文件并加载其内容
|
||
**以便** 直接编辑特定的文本文件
|
||
|
||
#### Acceptance Criteria
|
||
|
||
1. 使用Vue Router配置路由，支持 `/notes/{filename}` 格式
|
||
2. 从URL参数中提取文件名，调用后端API加载文件内容
|
||
3. 文件存在时，将内容显示在编辑区域
|
||
4. 文件不存在时，创建新文件并显示空白编辑区域
|
||
5. 在界面上方显示当前文件名
|
||
6. 处理URL编码/解码，支持中文文件名
|
||
|
||
### Story 1.4: 自动保存功能实现
|
||
|
||
**作为** 用户
|
||
**我想要** 编辑的内容能够自动保存
|
||
**以便** 无需手动操作即可保留我的更改
|
||
|
||
#### Acceptance Criteria
|
||
|
||
1. 监听文本编辑器的input事件，检测内容变化
|
||
2. 实现防抖机制，用户停止输入500ms后触发保存
|
||
3. 调用后端API将当前内容保存到文件
|
||
4. 在界面上显示保存状态指示器（"已保存"、"保存中..."、"保存失败"）
|
||
5. 保存成功后更新状态为"已保存"
|
||
6. 保存失败时显示错误提示，并提供重试机制
|
||
|
||
### Story 1.5: WebSocket实时通信集成
|
||
|
||
**作为** 用户
|
||
**我想要** 通过WebSocket实现实时自动保存
|
||
**以便** 获得更快的响应和更好的实时体验
|
||
|
||
#### Acceptance Criteria
|
||
|
||
1. 后端集成WebSocket支持，使用FastAPI的websocket功能
|
||
2. 前端建立WebSocket连接，保持长连接
|
||
3. 通过WebSocket发送文本内容到后端，实现实时保存
|
||
4. 后端接收到内容后立即写入文件
|
||
5. 实现连接断开后自动重连机制
|
||
6. 显示WebSocket连接状态（已连接、断开连接、重连中）
|
||
|
||
---
|
||
|
||
## 7. Epic 2: 文件管理与安全控制
|
||
|
||
**Epic Goal**: 实现文件列表页面，展示所有txt文件，并添加后端口令验证机制，保护文件管理功能的安全性。
|
||
|
||
### Story 2.1: 文件列表API开发
|
||
|
||
**作为** 开发者
|
||
**我想要** 实现后端API返回所有txt文件列表
|
||
**以便** 前端可以展示文件列表页面
|
||
|
||
#### Acceptance Criteria
|
||
|
||
1. 实现GET `/api/files/list` 接口，遍历文件存储目录
|
||
2. 返回所有 `.txt` 文件的列表，包含文件名和创建时间
|
||
3. 按创建时间倒序排列，最新文件显示在最前面
|
||
4. 添加分页支持，每页显示50个文件
|
||
5. 返回数据格式为JSON，包含文件总数和当前页信息
|
||
|
||
### Story 2.2: 文件列表页面UI开发
|
||
|
||
**作为** 用户
|
||
**我想要** 查看所有可编辑的文件列表
|
||
**以便** 快速找到并打开需要的文档
|
||
|
||
#### Acceptance Criteria
|
||
|
||
1. 创建文件列表页面组件 `/file-list`
|
||
2. 调用后端API获取文件列表并展示
|
||
3. 每个文件项显示文件名和创建时间（格式化显示）
|
||
4. 点击文件名跳转到对应的编辑页面（`/notes/{filename}`）
|
||
5. 实现加载状态指示器，API调用期间显示加载中
|
||
6. 处理空列表情况，显示友好提示信息
|
||
|
||
### Story 2.3: 后端口令验证机制
|
||
|
||
**作为** 用户
|
||
**我想要** 文件列表页面需要口令验证
|
||
**以便** 保护我的文件不被未经授权的访问
|
||
|
||
#### Acceptance Criteria
|
||
|
||
1. 配置文件列表访问口令（如环境变量 `FILE_LIST_PASSWORD`）
|
||
2. 修改 `/api/files/list` 接口，要求请求包含正确的口令
|
||
3. 实现POST `/api/files/verify-password` 接口，验证口令是否正确
|
||
4. 口令验证通过后，返回访问令牌（简单token）
|
||
5. 后续文件列表请求需要携带令牌才能访问
|
||
6. 令牌设置过期时间（如24小时）
|
||
|
||
### Story 2.4: 前端口令验证UI
|
||
|
||
**作为** 用户
|
||
**我想要** 在文件列表页面输入口令进行验证
|
||
**以便** 访问我的文件列表
|
||
|
||
#### Acceptance Criteria
|
||
|
||
1. 访问文件列表页面时，如果未验证，显示口令输入表单
|
||
2. 用户输入口令后，调用后端验证API
|
||
3. 验证成功后，保存令牌到localStorage
|
||
4. 使用令牌调用文件列表API，显示文件列表
|
||
5. 验证失败时显示错误消息
|
||
6. 提供"记住我"选项，保持登录状态
|
||
|
||
---
|
||
|
||
## 8. Epic 3: 边界条件处理与部署优化
|
||
|
||
**Epic Goal**: 完善应用的异常处理和边界条件，实现输入验证、文件大小限制、错误处理，并配置Docker部署方案。
|
||
|
||
### Story 3.1: 输入验证与安全过滤
|
||
|
||
**作为** 开发者
|
||
**我想要** 对文件名进行严格的验证和过滤
|
||
**以便** 防止安全漏洞和非法访问
|
||
|
||
#### Acceptance Criteria
|
||
|
||
1. 实现文件名验证函数，阻止包含特殊字符的文件名（`/`, `\\`, `..`, `:`等）
|
||
2. 限制文件名长度不超过200个字符
|
||
3. 对URL中的文件名进行解码和验证
|
||
4. 验证失败时返回400 Bad Request错误
|
||
5. 记录验证失败的请求，便于安全审计
|
||
6. 前端同步实现文件名验证，提供实时反馈
|
||
|
||
### Story 3.2: 文件大小限制实现
|
||
|
||
**作为** 用户
|
||
**我想要** 系统限制文件大小不超过10万字符
|
||
**以便** 防止单个文件过大影响性能
|
||
|
||
#### Acceptance Criteria
|
||
|
||
1. 后端实现文件大小检查，读取文件时如果超过10万字符返回错误
|
||
2. 前端实现字符计数器，实时显示当前字符数
|
||
3. 当接近限制（如9.5万字符）时显示警告
|
||
4. 达到10万字符限制时，阻止用户继续输入并显示提示
|
||
5. 保存时检查内容长度，超过限制返回413 Payload Too Large错误
|
||
6. 提供友好的用户提示，说明文件大小限制
|
||
|
||
### Story 3.3: 异常处理与错误提示
|
||
|
||
**作为** 用户
|
||
**我想要** 清晰的错误提示信息
|
||
**以便** 了解发生了什么问题和如何解决
|
||
|
||
#### Acceptance Criteria
|
||
|
||
1. 定义错误码和对应的用户友好消息
|
||
2. 实现全局错误处理组件，捕获并显示错误
|
||
3. 网络错误：显示"网络连接失败，请检查网络"提示
|
||
4. 文件访问错误：显示"无法访问文件，请重试或联系管理员"
|
||
5. 权限错误：显示"访问被拒绝，请确认您有权限访问此文件"
|
||
6. 提供"重试"按钮，允许用户重新尝试失败的操作
|
||
|
||
### Story 3.4: Docker部署配置
|
||
|
||
**作为** 运维人员
|
||
**我想要** 使用Docker部署应用
|
||
**以便** 简化部署流程和环境管理
|
||
|
||
#### Acceptance Criteria
|
||
|
||
1. 创建前端Dockerfile，基于Node.js镜像构建Vue3应用
|
||
2. 创建后端Dockerfile，基于Python 3.10+镜像运行FastAPI
|
||
3. 配置docker-compose.yml，编排前后端服务
|
||
4. 配置Nginx作为反向代理，服务前端静态文件和API请求
|
||
5. 设置环境变量配置（文件存储路径、口令、端口等）
|
||
6. 编写部署文档，说明如何在Ubuntu物理机上部署
|
||
|
||
### Story 3.5: 性能优化与监控
|
||
|
||
**作为** 开发者
|
||
**我想要** 添加性能监控和优化措施
|
||
**以便** 确保应用在生产环境稳定运行
|
||
|
||
#### Acceptance Criteria
|
||
|
||
1. 后端添加请求日志，记录API调用时间、状态码
|
||
2. 实现健康检查接口 `/health`，返回服务状态
|
||
3. 前端添加性能监控，测量页面加载时间、保存响应时间
|
||
4. 配置Gunicorn/Uvicorn参数，优化并发性能
|
||
5. 实现文件缓存机制，减少重复读取
|
||
6. 添加内存使用监控，防止内存泄漏
|
||
|
||
---
|
||
|
||
## 9. Next Steps
|
||
|
||
### UX Expert Prompt
|
||
|
||
基于本PRD文档，设计Vue3 + Python Notepad应用的用户界面架构，包括：
|
||
- 文本编辑页面的布局和交互设计
|
||
- 文件列表页面的视觉设计和用户体验
|
||
- 响应式设计策略，适配不同设备
|
||
- UI组件库选择和设计系统定义
|
||
|
||
### Architect Prompt
|
||
|
||
基于本PRD文档，设计Vue3 + Python Notepad应用的技术架构，包括：
|
||
- 前后端项目结构和代码组织
|
||
- API设计细节和WebSocket通信协议
|
||
- 文件存储策略和数据模型
|
||
- Docker部署架构和配置
|
||
- 安全策略和性能优化方案
|