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