移动端文件管理器产品需求文档

1. 文档信息

项目	内容
产品模块	NAS 移动端文件管理器
文档状态	可评审
更新时间	2026-06-11
需求来源	原始需求表 + Figma 原型反向补充
Figma 原型	移动端文件管理

2. 背景与目标

2.1 背景

移动端用户需要在手机上访问 NAS 中的文件与文件夹，完成浏览、搜索、预览、上传、下载、收藏、重命名、删除、新建文件夹等常见文件管理操作。Figma 原型已覆盖首页、搜索、目录列表、列表/宫格视图、排序、新增入口、文件夹操作、文件操作、预览和异常状态，本需求文档按原型进行反向补充，统一 UI、开发、测试的实现口径。

2.2 产品目标

1. 支持用户区分并进入不同系统存储空间或挂载位置。
2. 支持按真实目录层级浏览 NAS 文件和文件夹。
3. 支持搜索文件，并按类型筛选搜索结果。
4. 支持列表视图和宫格视图切换。
5. 支持按文件名、文件类型、文件大小、修改时间排序。
6. 支持查看文件/文件夹详情。
7. 支持图片、文本、视频等常见格式预览。
8. 支持不支持格式的明确提示和下载引导。
9. 支持新建文件夹、上传本机文件、下载、删除、重命名、收藏等基础操作。
10. 支持下载/上传文件任务反馈，避免用户误以为操作无响应。

2.3 非目标

1. 暂不支持在线编辑文件内容。
2. 暂不支持复杂权限配置、多人协作、文件版本管理。
3. 暂不支持批量压缩/解压、断点续传、后台任务队列配置。
4. 暂不支持全文内容检索，仅要求基于文件名和基础类型的搜索筛选。
5. 移动、复制能力首期不作为必做项，待接口和产品策略确认后扩展。

3. 用户与场景

用户/场景	用户目标	对应原型
浏览存储空间	查看存储、挂载、收藏目录并进入目标位置	文件管理-首页
查看文件任务	在首页查看下载/上传任务进度与完成状态	文件管理-首页、文件任务区域
搜索文件	输入关键词，查看搜索中、结果、无结果状态	搜索输入、搜索结果、搜索空态
浏览目录	查看当前目录下文件夹和文件，可进入下级	二级列表页
切换视图	在列表和宫格之间切换浏览方式	列表视图、宫格视图
排序筛选	按文件名、类型、大小、修改时间整理展示	排序底部弹窗
新增内容	新建文件夹或上传本机文件	新增底部弹窗、新建文件夹
操作文件夹	对文件夹重命名、收藏、下载、详情、删除	文件夹更多操作
操作文件	对文件重命名、下载、详情、删除	文件操作
预览文件	打开文档、图片、视频或不支持格式提示	文档查看、图片查看、视频播放、不支持格式

4. 需求范围与优先级

编号	功能	优先级	原型依据	说明
F-001	首页与存储空间	P0	文件管理-首页	展示搜索入口、存储空间、挂载位置、收藏、文件任务
F-002	文件/文件夹列表	P0	二级列表页-列表视图	按目录层级展示内容
F-003	搜索文件	P0	搜索输入、结果、空态	支持输入、搜索中、结果分类、无结果
F-004	视图切换	P1	列表视图、宫格视图	支持列表/宫格
F-005	排序	P1	二级列表页-排序	文件名、类型、大小、修改时间
F-006	新建文件夹	P0	新增、新建文件夹	当前目录创建文件夹
F-007	上传文件	P0	新增入口	调起本机文件选择并上传
F-008	下载与文件任务	P0	下载、首页文件任务	下载加入文件任务并反馈进度
F-009	文件/文件夹详情	P0	操作-详情	展示名称、大小、格式、创建/修改时间等
F-010	文件预览	P0	文档/图片/视频/不支持格式	按格式打开或提示
F-011	重命名	P1	操作-重命名	文件和文件夹均支持
F-012	添加到收藏	P1	操作-添加到收藏	文件夹可添加到首页收藏
F-013	删除	P0	永久删除二次确认	删除前二次确认
F-014	多选	P1	二级列表页操作栏	入口已出现，首期可仅保留入口或支持批量操作
F-015	移动/复制	P2	暂未出现在原型	待接口和策略确认

5. 功能需求

F-001 首页与存储空间

需求描述

用户进入文件管理器后，默认进入首页。首页展示搜索入口、文件任务、存储空间、挂载位置和我的收藏。

页面元素

元素	说明
搜索框	点击进入搜索输入页
文件任务	展示下载/上传任务数、进行中进度、完成状态
存储空间	通过 /storages 展示系统存储
挂载位置	如接口返回挂载盘/外部存储，按存储入口展示
我的收藏	展示被收藏的文件夹快捷入口

接口依赖

• GET /storages
• 文件任务列表接口待确认
• 收藏列表接口待确认

交互要求

1. 点击搜索框进入搜索输入页。
2. 点击存储空间或挂载位置进入对应根目录。
3. 点击收藏文件夹进入对应目录。
4. 首页加载时展示 loading，接口失败时展示重试。
5. 文件任务有进行中任务时展示任务名称、进度、速度或状态；无任务时可不展示任务区或展示空状态。

验收标准

• 首页可展示至少一种可访问存储入口。
• 点击入口可进入目录列表。
• 文件任务状态不会遮挡存储和收藏内容。
• 接口异常时不白屏。

F-002 文件/文件夹列表

需求描述

进入存储空间或文件夹后，按真实层级展示当前目录内容。

接口依赖

• GET /file

展示字段

字段	文件夹	文件
名称	必须	必须
图标/缩略图	必须	必须
修改时间	必须	必须
大小	可选	必须
类型	文件夹	根据后缀/服务端类型
更多操作	必须	必须

交互要求

1. 文件夹默认排在文件前。
2. 点击文件夹进入下一级目录。
3. 点击文件按格式进入预览或不支持格式页。
4. 顶部返回：
   • 子目录返回上一级；
   • 根目录返回首页；
   • 搜索结果进入的目录返回搜索结果。
5. 路径过长时中间省略，保留当前目录名。
6. 点击更多按钮打开对应文件/文件夹操作项。
7. 空目录展示空状态，并提供上传/新建文件夹入口。

验收标准

• 多级目录进入和返回路径正确。
• 列表刷新后仍保持当前目录上下文。
• 文件名过长不挤压更多按钮。
• 空、失败、无权限状态都有明确反馈。

F-003 搜索文件

需求描述

用户可通过首页搜索入口按文件名搜索文件和文件夹，并按类型快速过滤结果。

接口依赖

• 搜索接口待确认，建议：GET /file/search

交互要求

1. 点击首页搜索框进入搜索输入页，输入框自动聚焦。
2. 输入关键词后触发搜索；建议防抖 300ms。
3. 搜索中展示 loading 和“搜索中”。
4. 搜索结果页展示分类 Tab：全部、文件夹、文档、视频、图片。
5. Tab 数量按接口结果统计展示，如“全部（112）”。
6. 点击结果：
   • 文件夹：进入该文件夹目录；
   • 文件：进入预览或不支持格式页。
7. 点击取消返回首页。
8. 无结果展示“无搜索结果”。

验收标准

• 搜索中、结果、无结果状态完整。
• 取消搜索后不保留错误 loading。
• 切换分类不丢失关键词。

F-004 视图切换

需求描述

目录页支持列表视图和宫格视图，便于用户在不同文件类型下选择合适浏览方式。

交互要求

1. 点击“视图”切换列表/宫格，或打开视图选择菜单，按原型可直接切换。
2. 列表视图展示名称、修改时间、大小、更多操作。
3. 宫格视图展示缩略图/图标、名称，适合图片和文件夹浏览。
4. 视图切换后保持当前目录、排序、筛选条件。
5. 视图偏好可本地记忆。

验收标准

• 同一目录在两种视图下数据一致。
• 长文件名不会溢出卡片或行。
• 切换视图不重复请求非必要接口；如需请求，应保持 loading。

F-005 排序

需求描述

用户可在目录页按不同规则排序。

排序项

排序项	默认方向	说明
文件名	A-Z	可切换 A-Z/Z-A
文件类型	升序	按类型分组或后缀排序
文件大小	大到小	文件夹大小未知时置后或展示“-”
修改时间	新到旧	默认推荐

交互要求

1. 点击当前排序文案或筛选/排序入口，弹出底部排序面板。
2. 点击排序项后应用排序并关闭面板，或保留面板展示选中态。
3. 再次点击同一排序项可切换升降序。
4. 排序条件应在当前目录内生效。

验收标准

• 排序选中态清晰。
• 文件夹优先规则与排序规则不冲突；如冲突，以“文件夹优先”为默认产品规则。

F-006 新建文件夹

需求描述

用户可在当前目录中新建文件夹。

接口依赖

• 新建文件夹接口待确认，建议：POST /file/folder

交互要求

1. 点击新增入口，底部弹出“新建文件夹 / 上传本机文件”。
2. 点击“新建文件夹”弹出输入面板。
3. 文件夹名称不能为空。
4. 文件名非法字符、同名冲突、无权限等错误需在面板内提示。
5. 创建成功后关闭面板并刷新当前目录。
6. 取消关闭面板，不创建。

验收标准

• 创建成功后新文件夹出现在当前目录。
• 创建失败保留用户输入，便于修改。

F-007 上传文件

需求描述

用户可选择手机本地文件上传到当前 NAS 目录。

接口依赖

• POST /file/upload (v2)

交互要求

1. 点击新增入口，再点击“上传本机文件”。
2. 调起系统文件选择器。
3. 选择文件后回到当前目录，创建文件任务。
4. 上传过程中展示进度、速度或状态。
5. 上传成功后刷新目录列表。
6. 上传失败展示失败原因，支持重试。

验收标准

• 上传目标目录正确。
• 上传过程中用户能看到任务反馈。
• 上传失败不会产生重复文件或错误列表状态。

F-008 下载与文件任务

需求描述

用户可下载 NAS 文件到手机本地，下载任务加入文件任务区。

接口依赖

• GET /file/download

交互要求

1. 点击文件或文件夹操作项中的“下载”。
2. 系统将任务加入文件任务，并展示“已添加到文件任务，请在文件管理首页查看”。
3. 首页文件任务展示下载进度，如 45%、100%、速度等。
4. 下载成功提示完成；下载失败提示原因并支持重试。
5. 文件夹下载如需打包，需服务端明确支持；未支持时置灰或提示暂不支持。

验收标准

• 下载后用户能在首页看到对应任务。
• 多个任务状态不相互覆盖。
• 无权限、文件不存在、本地空间不足均有提示。

F-009 文件/文件夹详情

需求描述

用户可查看文件或文件夹的基础信息。

展示字段

字段	文件	文件夹
名称	必须	必须
路径	必须	必须
文件大小	必须	可选
格式/类型	必须	文件夹
创建时间	必须	必须
最后修改时间	必须	必须

交互要求

1. 更多操作中点击“详情/文件信息”打开底部详情面板。
2. 字段缺失展示“-”。
3. 点击遮罩或返回关闭详情面板。

验收标准

• 详情字段和当前选中对象一致。
• 时间格式统一为 yyyy-mm-dd hh:mm:ss 或客户端规范格式。

F-010 文件预览

需求描述

用户点击文件时，系统根据格式进入对应预览页。

支持格式

类型	格式
图片	jpg、jpeg、png、bmp 等常见格式
文本/文档	txt、md、yml、yaml，原型以文档内容只读展示
视频	mp4、mov、mkv 等常见格式

交互要求

1. 图片进入图片查看页，展示图片内容和底部操作：重命名、下载、详情、删除。
2. 文本/文档进入文档查看页，展示只读内容和底部操作：重命名、下载、文件信息、删除。
3. 视频进入视频播放页，调用视频播放器能力。
4. 不支持格式进入不支持格式页，提示“暂不支持打开当前格式文件，请下载后尝试使用其他应用打开”，并提供下载/信息/删除等操作。
5. 预览页返回后回到进入前目录或搜索结果。

验收标准

• 支持格式可打开。
• 不支持格式不白屏、不自动下载。
• 大文件加载有 loading 和失败反馈。

F-011 重命名

需求描述

用户可对文件或文件夹重命名。

接口依赖

• 重命名接口待确认，建议：PATCH /file

交互要求

1. 点击更多操作中的“重命名”。
2. 底部弹窗展示原名称并允许编辑。
3. 名称为空、非法字符、同名冲突时阻止提交并提示。
4. 确认后调用接口，成功后刷新当前目录或预览页标题。
5. 取消不保存。

验收标准

• 重命名成功后列表和详情名称同步更新。
• 重命名失败保留输入。

F-012 添加到收藏

需求描述

用户可将常用文件夹添加到首页“我的收藏”。

接口依赖

• 收藏接口待确认，建议：POST /file/favorites

交互要求

1. 文件夹更多操作中点击“添加到收藏”。
2. 成功后展示 Toast：“收藏成功”。
3. 已收藏对象再次操作时展示“取消收藏”或置灰，具体策略待确认。
4. 首页我的收藏刷新后出现该文件夹。

验收标准

• 收藏成功后首页快捷入口可用。
• 重复收藏不会产生重复项。

F-013 删除

需求描述

用户可删除文件或文件夹，删除前必须二次确认。

接口依赖

• DELETE /file

交互要求

1. 点击“删除”弹出二次确认。
2. 文案明确对象名称和不可恢复风险。
3. 点击取消关闭弹窗。
4. 点击确认调用删除接口。
5. 删除成功后刷新当前目录；如在预览页删除，返回上一层列表。
6. 删除失败展示失败原因，不改变现有列表。

验收标准

• 未确认不会执行删除。
• 删除成功后对象不再出现。
• 非空文件夹删除策略需服务端确认；未确认前应提示风险或禁止。

F-014 多选

需求描述

原型目录页已出现“多选”入口。首期可根据开发资源选择仅保留入口或支持批量删除/下载。

交互要求

1. 点击多选进入选择态。
2. 选择态下显示复选框、已选数量和底部批量操作栏。
3. 批量操作至少建议支持下载和删除；如接口暂不支持，入口置灰并标注待定。
4. 再次返回或取消退出选择态。

验收标准

• 多选态不会误触进入目录或打开文件。
• 批量删除仍需二次确认。

F-015 移动/复制

需求描述

移动和复制属于后续能力。

待确认

1. 是否已有移动/复制接口。
2. 是否支持文件夹移动/复制。
3. 是否允许跨存储空间。
4. 同名冲突采用覆盖、自动重命名还是阻止。

6. 全局交互规则

6.1 导航

1. 首页 → 存储空间/收藏 → 目录列表。
2. 首页 → 搜索 → 搜索结果 → 目录或文件预览。
3. 目录列表 → 文件夹 → 下级目录。
4. 目录列表 → 文件 → 预览或不支持格式页。
5. 预览页返回进入前位置。
6. 弹窗/底部面板点击取消、遮罩或返回关闭，不改变页面状态。

6.2 状态反馈

状态	展示要求
loading	骨架屏、加载图标或文字
空存储空间	暂无可用存储空间，提供重试
空目录	当前文件夹为空，提供上传/新建
搜索无结果	无搜索结果
网络异常	网络异常，请稍后重试
无权限	暂无访问权限
文件不存在	文件不存在或已被删除，刷新当前列表
不支持格式	明确提示并提供下载引导

6.3 文件命名规则

1. 名称不能为空。
2. 前后空格提交时应 trim。
3. 非法字符规则以服务端为准；客户端需提前校验并提示。
4. 同名冲突策略待确认，默认阻止提交并提示。

6.4 数据展示

1. 文件大小统一转换为 B、KB、MB、GB。
2. 时间格式统一，建议 yyyy-mm-dd hh:mm:ss。
3. 文件名超长时单行省略，详情中展示完整名称。
4. 文件夹大小未知时展示“-”。

7. 接口依赖汇总

功能	接口	当前状态
存储空间	GET /storages	已知
文件/文件夹列表	GET /file	已知
搜索	建议 GET /file/search	待确认
新建文件夹	建议 POST /file/folder	待确认
上传	POST /file/upload (v2)	已知
下载	GET /file/download	已知
删除	DELETE /file	已知
详情	由 /file 返回或单独详情接口	待确认
预览	下载链接、本地缓存或预览接口	待确认
重命名	建议 PATCH /file	待确认
收藏	建议收藏接口	待确认
文件任务	建议任务列表/状态接口	待确认
移动/复制	待定	待确认

8. 埋点建议

事件	触发时机	关键属性
file_home_view	进入首页	storage_count、favorite_count、task_count
storage_open	点击存储/挂载入口	storage_id、storage_type
file_list_view	进入目录	storage_id、path、view_mode、sort_type
file_search	发起搜索	keyword_length、tab、result_count
file_view_mode_change	切换视图	from、to
file_sort_change	修改排序	sort_type、direction
file_open	打开文件	file_type、file_size、result
folder_create	创建文件夹	result、error_code
file_upload	上传文件	file_type、file_size、result、duration
file_download	下载文件	file_type、file_size、result、duration
file_rename	重命名	object_type、result、error_code
file_favorite	添加收藏	result、error_code
file_delete	删除	object_type、result、error_code

9. 验收清单

• 首页展示搜索入口、文件任务、存储空间、挂载位置、我的收藏。
• 点击存储空间/挂载/收藏可进入正确目录。
• 目录可多层级进入和返回。
• 文件夹与文件展示字段完整，长名称不遮挡操作入口。
• 搜索输入、搜索中、搜索结果、无结果状态完整。
• 搜索结果支持按全部、文件夹、文档、视频、图片切换。
• 列表/宫格视图可切换且数据一致。
• 排序项可选择，排序结果符合规则。
• 可新建文件夹，并处理空名称、非法字符、同名冲突。
• 可上传本机文件，并看到任务状态。
• 可下载文件，并在首页文件任务查看进度。
• 可查看文件/文件夹详情。
• 可打开图片、文本/文档、视频。
• 不支持格式有明确提示和下载引导。
• 可重命名文件/文件夹。
• 可将文件夹添加到收藏。
• 删除前必须二次确认，确认后刷新列表。
• 网络异常、无权限、文件不存在、加载失败均有反馈。

10. 待确认问题

1. 搜索接口、搜索范围和是否支持跨存储空间搜索。
2. 首页文件任务接口、任务状态枚举、任务历史保留时长。
3. 新建文件夹接口、文件名非法字符规则、同名冲突策略。
4. 文件/文件夹详情字段由列表接口返回还是单独接口返回。
5. 文件预览使用下载链接、本地缓存还是专用预览接口。
6. 视频播放是否调用系统播放器、内置播放器或影视播放器能力。
7. 文件夹下载是否支持打包下载。
8. 删除非空文件夹是否允许，是否可恢复。
9. 收藏能力是否仅支持文件夹，是否支持取消收藏。
10. 多选首期是否实现批量下载/删除。
11. 移动/复制是否已有服务端接口，是否允许跨存储空间。

11. 里程碑建议

阶段	内容
M1	首页、存储空间、目录列表、目录导航
M2	搜索、排序、视图切换、空/异常状态
M3	新建文件夹、上传、下载、文件任务
M4	详情、预览、不支持格式、重命名、收藏、删除
M5	多选、批量操作、移动/复制能力评估