yuany3721/notepad
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
notepad/docs/prd.md

15 KiB
Raw Blame History

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部署架构和配置
  • 安全策略和性能优化方案