[jiuyueQ]

解决的问题

原来的单层文件夹无法表达“家庭 → 账单 → 年份”的归档结构，也无法重命名或整体移动目录。这次增加最多 8 层的文件夹层级，支持带子目录移动、面包屑导航和按目录树搜索。

改动与影响

• 增加可空的上级目录及根目录/同级名称约束。旧文件夹迁移后仍为顶层目录，文档关联保持不变。
• 新建、重命名/移动和移除目录通过事务串行更新层级；拒绝跨用户、循环和导致整个子树超过 8 层的移动。
• 文件夹页面默认显示直接归档的文档；“包含子文件夹”可覆盖后代目录，继续支持搜索、类型/状态筛选和分页。侧栏数量仍为直接文档数。
• 上传和文档归档显示完整路径；子目录卡片支持手机导航。含子目录的文件夹不可移除；移除末级目录会把活动和回收站文档归入上级，顶层则归入待归档。
• 原文件、缩略图、识别结果、任务状态和回收站状态不因目录整理而改变。Windows 本机服务及数据目录约定保持一致。
• 增加层级与迁移测试、浏览器回归脚本、隔离 QA 账户路径选项和虚构资料截图，更新使用说明与架构文档。

验证证据

在 Windows、Python 3.14.6、独立的 qa-output/nested-folders 数据目录完成：

• manage.py check：通过。
• manage.py makemigrations --check --dry-run：无未记录模型变化。
• FOLDERDOCS_TEST_OCR=1 下 manage.py test --verbosity 2：23 项全部通过，包含旧结构迁移、跨用户权限、POST/CSRF、循环/深度校验、目录移动/移除的数据保留，以及真实 Tesseract 对图片和扫描 PDF 的识别；失败重试路径另外使用 mock 验证。
• node qa/browser.cjs：Edge 无头浏览器验证登录、文件夹创建、上传、后台处理、搜索、下载、回收站恢复/永久删除和响应式布局。
• node qa/folders.cjs：Edge 无头浏览器验证三级目录创建、面包屑、递归搜索、重命名和带子目录移动、移动前后下载内容逐字节一致、末级目录安全移除和手机导航。
• 桌面 1440px / 手机 390px 截图已人工检查；手机页面无横向溢出。测试预览及 worker 已停止。
• git diff --check：通过。

GitHub PR CI 在 Windows/Ubuntu、Python 3.12/3.14 的四组检查均通过（对应提交 238e6ee78a229c44bc77df72ca3bd4d0c73a9a63）：运行结果。CI 默认跳过需本机 Tesseract 的集成测试，真实 OCR 已在本机单独验证。

剩余风险

升级前应停止服务并备份整个数据目录。不同上级下使用同名目录后，不能直接回滚到旧的全局文件夹名称约束。本轮没有改动生产用户数据，也没有变更启动器或 worker 实现；未验证其他数据库部署或大规模目录性能。

[jiuyueQ]

@codex review

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-10-14T09:03:28.143479Z	238e6ee	Manual request

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[chatgpt-codex-connector]

Codex Review: Didn't find any major issues. You're on a roll.

Reviewed commit: 238e6ee78a

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".