document-management/docs/planning/项目进展与后续工作计划.md

方案计划文档管理系统：项目进展与后续工作计划

更新日期：2026-07-30
当前契约基线：DMS_FUNCTION_CONTRACT.md 1.2、DMS_API_CONTRACT.md 1.2
当前 OpenAPI 版本：1.2.0
文档用途：统一记录当前完成范围、未完成事项、风险、验收条件和建议执行顺序。

1. 当前总体结论

项目已经完成第一阶段核心业务系统的前后端框架、MySQL 持久化、文件存储、认证鉴权、审计、统计、回收站和大部分真实业务闭环。

从代码和自动化测试角度看，第一阶段核心功能已经基本完成；从正式交付角度看，仍有以下关键事项需要关闭：

1. 将正式 dms 主库从迁移 0001_initial_schema 升级至 0002_add_restore_audit_action，验证三类文档恢复；
2. 固化数据库、JWT、文件存储和 UI 字典等部署配置；
3. 建立稳定 Git 提交基线；
4. 如需支持 DOC、DOCX、XLS、XLSX 在线预览，需单独升级契约并实现 Office 转 PDF 预览链路。

因此，当前状态可概括为：

• 核心业务开发：基本完成
• 自动化测试：覆盖较完整
• 测试环境真实联调：Q1 已通过独立验收
• 正式数据库升级：未完成
• 可重复部署与正式交付：未完成
• Office 文档在线预览：未实现

2. 已确认的系统范围

2.1 第一阶段已纳入范围

• 用户登录、退出和登录状态恢复；
• 组织机构、人员查询；
• 方案分类树查询和管理；
• 主案、子方案管理；
• 全员共享附件库；
• 共享附件与主案的多对多挂载；
• 主案权限配置及子方案动态继承；
• 文档上传、批量导入、元数据编辑、逻辑删除；
• PDF 在线预览和原始文件下载；
• 操作日志审计和统计分析；
• 回收站查询和单条文档恢复；
• MySQL 结构化数据持久化；
• 后端指定目录文件持久化；
• 统一 UI 中文字典配置。

2.2 当前明确暂缓

• Milvus、文档向量化和语义检索；
• 现有 AI 抽取、标注和修复模块改造；
• 电子签章；
• 审批工作流；
• 在线 Office 编辑；
• Office 转 PDF；
• 国产数据库和国产操作系统适配；
• 动态角色与菜单配置平台；
• 复杂文档历史版本；
• 匿名访问；
• 分类、用户和组织恢复；
• 批量恢复、物理删除和回收站自动清理；
• 子方案独立权限；
• 共享附件独立 ACL。

3. 已完成的基础架构

3.1 前端基础

• 已建立统一 HTTP 客户端；
• 已统一处理 /api/v1 基础路径；
• 已实现 Bearer Token 注入；
• 已实现统一响应、业务错误和 requestId 解析；
• 已实现统一 401 登录失效处理；
• 已实现 sessionStorage 与 localStorage 两种登录保持策略；
• 已实现 DTO 运行时严格校验；
• 已实现加载、空数据、失败、重试和并发请求保护；
• 已使用 AbortController、防抖和请求版本号避免旧响应覆盖；
• 已建立认证、分类、组织人员、文档、附件、挂载、权限、审计、统计、回收站和字典等功能模块。

3.2 后端基础

• 已建立 Flask /api/v1 业务接口框架；
• 已建立统一成功响应、错误响应和 X-Request-Id；
• 已实现 JWT 认证和 auth_version 旧 Token 失效机制；
• 已采用 Argon2id 保存密码哈希；
• 已实现角色、状态、密级、可见范围和 ACL 集中授权；
• 已实现统一审计服务；
• 已建立 OpenAPI 3.0.3 机器可读契约；
• 已建立 Alembic 数据库迁移机制；
• 已实现显式、幂等的开发数据初始化命令；
• 已保留现有 AI 模块，不与 DMS 持久化改造耦合。

3.3 持久化和文件存储

• 结构化数据库使用 MySQL 8；
• 采用 7 张核心业务表的最小化设计；
• 核心数据采用逻辑删除；
• 业务表包含新增、更新和删除时间；
• 使用适量冗余字段降低列表和统计查询复杂度；
• 文件保存在后端存储根目录，数据库只保存安全相对路径；
• 正式默认目录为 backend/dms-storage/；
• 测试环境使用独立的 backend/dms-test-storage/；
• 临时上传文件和正式原文件分目录管理；
• 文件名使用 UUID，保留原始文件名元数据；
• 已实现文件大小、SHA-256、扩展名、文件头和 Office 容器校验；
• 已实现路径穿越、ZIP 炸弹、异常容器和越界符号链接防护；
• 已实现文件操作与数据库事务之间的失败补偿。

4. 已完成的业务功能

4.1 认证和角色入口

已实现：

• 登录；
• 当前用户查询；
• 登录状态恢复；
• 退出登录；
• 注销后旧 Token 失效；
• 用户禁用、删除和认证版本检查；
• 登录成功、登录失败和退出审计；
• 后端返回 allowedModules，前端据此展示导航。

当前角色边界：

角色	当前入口和能力
ADMIN	文档浏览、后台管理；管理分类、方案、附件、挂载和权限
AUDITOR	日志审计和审计统计；默认不能管理文档
USER	浏览有权访问的已发布方案；查看、下载共享附件

4.2 组织机构和人员

已实现：

• 组织树查询；
• 组织名称和编码搜索；
• 命中节点保留祖先；
• 人员关键词、组织、状态和分页查询；
• 包含下级组织查询；
• 管理员权限配置界面使用真实组织和人员数据。

当前系统只提供组织和人员只读查询，用户、组织的完整增删改管理不在第一阶段范围内。

4.3 方案分类

已实现：

• 分类树查询；
• 分类名称和编码搜索；
• 新增顶级分类和子分类；
• 编辑名称、类型和排序；
• 移动分类；
• 逻辑删除；
• 分类占用冲突检查；
• rowVersion 乐观锁；
• 分类路径递归更新；
• 关联方案分类冗余同步；
• 分类管理审计。

前端已实现分类层级下拉展示：

• 父分类在子分类之前；
• 子级相对父级缩进；
• 每级使用两个全角空格；
• 使用字符串 ID；
• 只向后端提交 categoryId，不提交路径和中文标签。

4.4 主案和子方案

已实现：

• 主案列表、全部方案和最近更新；
• 关键词、分类、状态、密级、时间、排序和分页查询；
• 文档详情；
• 主案直属子方案查询；
• 主案和子方案上传；
• 批量导入；
• 元数据编辑；
• 逻辑删除；
• 主案存在子方案时阻止删除；
• 子方案动态继承主案可见范围和 ACL；
• 独立状态和密级授权判断；
• 查看次数和下载次数统计；
• 查看和下载审计。

4.5 共享附件库

已实现：

• 独立共享附件列表；
• 附件详情；
• 关键词、类型、扩展名、更新时间、排序和分页；
• 单文件上传和批量导入；
• 元数据编辑；
• 逻辑删除；
• 已挂载附件删除冲突；
• 附件反向查询已挂载主案；
• 所有正常登录用户查看和下载共享附件。

共享附件当前固定规则：

• documentType = ATTACHMENT
• securityLevel = PUBLIC
• visibilityType = ALL_AUTHENTICATED
• 不进入方案分类；
• 不配置独立 ACL；
• 文件和元数据只保存一份。

4.6 附件挂载

已实现：

• 主案挂载一个或多个共享附件；
• 请求内去重；
• 已有挂载幂等处理；
• 稳定挂载排序；
• 解除挂载；
• 解除后重新挂载创建新关系；
• 主案附件计数重算；
• 主案版本控制；
• 正向和反向挂载查询同步；
• 挂载、解绑审计；
• 并发冲突和关系不存在错误处理。

挂载只建立引用，不复制文件；解除挂载也不会删除附件或影响其他主案。

4.7 文档权限

已实现：

• 主案权限读取和全集保存；
• 子方案动态继承主案权限；
• 共享附件不配置 ACL；
• ALL_AUTHENTICATED、ORGANIZATION、CUSTOM 三种可见范围；
• 组织、人员和混合主体；
• VIEW、DOWNLOAD、EDIT、DELETE、CONFIG_PERMISSION 五类动作；
• 主体有效性检查；
• 权限名称快照；
• 权限全集差异保存；
• rowVersion 乐观锁；
• 权限修改审计；
• 文档列表、详情和下载共用集中授权逻辑。

当前为固定三角色加文档 ACL 的最小权限模型，不是完整动态 RBAC 平台。

4.8 文件上传、预览和下载

已实现：

• PDF、DOC、DOCX、XLS、XLSX 上传；
• 单文件上传；
• 多文件批量导入；
• 文件逐项成功或失败结果；
• PDF 浏览器内在线预览；
• DOC、DOCX、XLS、XLSX 返回 415 PREVIEW_UNAVAILABLE；
• 所有支持类型的原始文件下载；
• Content-Disposition filename* 中文文件名；
• CORS 暴露 Content-Disposition 和 X-Request-Id；
• 下载计数和下载审计；
• Blob URL 和临时下载节点清理。

当前出现“当前文件类型暂不支持在线预览”是已定义行为，不是接口故障。若要在线预览 Office 文件，需要新增服务端 Office 转 PDF 能力。

4.9 审计日志和统计

已实现：

• 审计日志分页查询；
• 关键词、用户、组织、目标、动作、结果、目标类型和 UTC 时间筛选；
• 文档数量统计；
• 今日查看人数；
• 日、周、月操作趋势；
• 动作分布；
• 活跃用户；
• 数据库聚合和稳定排序；
• 查询审计日志本身不再产生审计；
• 审计页面按角色隔离。

4.10 回收站和恢复

已实现：

• 管理员回收站入口；
• 已删除文档筛选、排序和分页；
• 主案、子方案和共享附件单条恢复；
• 严格文件完整性复检；
• 主案 ACL 和挂载关系按删除批次及契约规则恢复；
• 子方案父主案和分类有效性校验；
• 共享附件恢复后保持固定共享属性；
• 关系冲突检测；
• 恢复计数重算；
• RESTORE_DOCUMENT 审计；
• rowVersion 乐观锁；
• 废止旧恢复路径。

对应数据库迁移为：

0002_add_restore_audit_action

该迁移扩展恢复审计动作约束，并增加回收站查询索引。

4.11 统一 UI 中文字典

后端 Q1-B 已完成：

• 统一 UI 字典 JSON 配置；
• 14 组正式字典；
• 启动时严格校验；
• 外部 UTF-8 JSON 覆盖；
• 加载后使用只读内存结构；
• GET /api/v1/config/ui-dictionaries；
• 字典接口不产生业务查询或审计；
• 契约升级至 1.2；
• OpenAPI 升级至 1.2.0。

前端 Q1-F 已完成：

• 登录恢复后统一加载字典；
• 严格响应 DTO 校验；
• 并发请求去重；
• 登出和 401 时清理；
• 字典加载失败时阻止关键表单提交；
• 密级、状态、可见范围、文档类型、附件类型、审计枚举等统一显示中文；
• 请求仍提交正式英文 code；
• 分类选择项按层级缩进。

Q1-R1 已恢复三个标准测试账号密码，Q1-F-R1 已使用真实账号完成登录、刷新恢复、退出、旧 Token 失效、字典加载、分类层级和英文 code 提交验证。Q1-V 独立验收结论为通过，未使用人工签发 JWT。

5. 当前接口和契约状态

正式 OpenAPI 当前共定义 31 条 /api/v1 路径，覆盖：

• 健康检查；
• 认证；
• 当前用户；
• 组织和人员；
• UI 字典；
• 分类；
• 文档和附件；
• 预览和下载；
• 子方案；
• 挂载；
• 权限；
• 审计和统计；
• 回收站和恢复。

契约优先级为：

1. 用户在统领会话中最新确认的规则；
2. DMS_FUNCTION_CONTRACT.md；
3. DMS_API_CONTRACT.md；
4. FUNCTION_AND_API_SPECIFICATION.md；
5. CODEX_BACKEND_PERSISTENCE_GUIDE.md；
6. 当前代码、模拟数据和历史对话。

后续功能如果改变正式业务语义，应先升级契约，再修改 OpenAPI 和代码。

6. 测试和质量状态

各阶段已经持续执行：

• 后端 DMS 自动化测试；
• 既有 AI 回归测试；
• 前端单元测试；
• 前端类型检查；
• 前端生产构建；
• Python 编译检查；
• OpenAPI 解析和外部引用检查；
• Flask 路由与 OpenAPI 一致性检查；
• MySQL 真实接口测试；
• Edge 浏览器真实页面测试；
• 文件路径、大小和 SHA-256 检查；
• 逻辑删除、版本冲突、权限和审计验证。

最近阶段报告结果：

验证项	最近报告结果
Q1-B 后端完整回归	337 passed
Q1-B 无测试环境变量	79 passed, 258 skipped
Q1-F 前端测试	40 个测试文件，226 项通过
Q1-F 类型检查	通过
Q1-F 构建	通过
Python compileall	通过

注意：

• 上述数字来自各执行会话的阶段报告；
• 最终交付前仍应由集成验证会话基于固定 Git 基线再执行一次全量回归；
• 前端仍有单块体积过大的构建警告；
• 当前工作区存在大量未提交和未跟踪文件，尚未形成稳定交付版本。

7. 当前运行和访问状态

Q1 验收时使用的前端 9346 和后端 8755 均已完成真实浏览器验证。2026-07-30 工程整理时未发现上述端口仍有监听进程，后续点测应按部署或开发启动说明重新启动服务。

不得把当前临时启动参数直接作为生产部署配置。

8. 后续必须完成的工作

8.1 已完成：恢复测试账号并完成 Q1 真实登录验收

执行顺序：

1. 会话3仅在 dms_test 中恢复已存在的 admin、auditor、user 测试密码；
2. 禁止新建用户、重建测试库或清理其他业务数据；
3. 使用正式登录接口确认三类账号均可登录；
4. 会话2禁止手工签发 JWT，使用真实密码完成 Q1-F 浏览器补验；
5. 验证每个会话只加载一次 UI 字典；
6. 验证分类缩进、中文标签和英文 code 提交；
7. 由集成验证会话复核结果。

完成标准：

• 三类账号通过真实登录页面登录；
• 登录、字典加载、刷新恢复和退出形成闭环；
• 不再使用临时或人工签发 JWT 作为验收依据；
• Q1-F 报告不存在环境阻塞。

完成结果：Q1-R1-A、Q1-F-R1 和 Q1-V 均已通过，本项不再阻塞后续工作。

8.2 P0：升级正式主库至 0002

集成审查已经发现 dms 主库仍为 0001_initial_schema。这会导致正式主库不能写入 RESTORE_DOCUMENT 审计，并缺少回收站索引。

执行要求：

1. 备份正式主库；
2. 核对当前数据库确实为 dms；
3. 执行 Alembic 升级至 0002_add_restore_audit_action；
4. 检查审计 CHECK 已包含 RESTORE_DOCUMENT；
5. 检查回收站索引存在；
6. 分别对 MAIN、SUB_PLAN、ATTACHMENT 执行一次正式恢复冒烟；
7. 验证文档、关系、计数和审计同一事务提交；
8. 验证失败恢复不会留下部分数据。

该工作涉及正式主库写操作，必须在备份和明确授权后执行。

8.3 P0：固化安全运行配置

需要形成可重复部署配置，至少包括：

• DMS_DATABASE_URL
• DMS_JWT_SECRET
• DMS_STORAGE_ROOT
• DMS_UI_DICTIONARY_CONFIG_PATH
• DMS_MAX_FILE_SIZE
• DMS_MAX_UPLOAD_SIZE
• DMS_BATCH_MAX_FILES
• DMS_BUSINESS_TIMEZONE
• 前端 VITE_API_BASE_URL

要求：

• 使用独立 MySQL 应用账号，不使用 root 作为生产账号；
• JWT 使用足够长度的随机密钥；
• 密钥和数据库密码不提交 Git；
• 存储目录具有明确读写权限和备份策略；
• UI 字典配置修改后通过重启生效；
• 区分开发、测试和生产环境；
• 编写启动、迁移、回滚、备份和健康检查说明。

8.4 P0：建立稳定 Git 交付基线

当前前后端、契约、迁移和测试存在大量未提交或未跟踪文件。

需要：

1. 核对所有工作区差异；
2. 排除密码、Token、测试临时文件和本地存储文件；
3. 确认 .gitignore；
4. 运行最终全量测试；
5. 按契约、后端、前端和部署文档合理拆分或形成一个明确基线提交；
6. 为该版本打标签或记录发布版本；
7. 后续功能基于稳定分支继续开发。

9. 建议后续完善的工作

9.1 P1：Office 文档在线预览

当前只有 PDF 可以在线预览。DOC、DOCX、XLS、XLSX 返回 415 是正式契约规定的当前行为。

如需要在线预览，建议采用：

原始 Office 文件
    → 服务端转换服务
    → 生成受控 PDF 派生文件
    → 浏览器使用现有 PDF 预览器展示

建议要求：

• 优先使用无界面的服务端转换组件；
• WPS 或 LibreOffice 作为可替换转换适配器；
• 不依赖人工打开桌面 WPS；
• 原始文件保持唯一事实来源；
• 转换产物保存到独立派生目录；
• 使用源文件 SHA-256、转换器版本和参数生成缓存键；
• 转换失败不得影响原始文件下载；
• 转换进程设置超时、并发、隔离目录和资源限制；
• 对宏、外链、嵌入对象和畸形文档进行安全限制；
• 保持权限检查、审计和 requestId；
• Windows/WPS 和后续国产化环境通过适配层隔离。

该功能会改变正式预览语义，建议：

• 功能契约升级至 1.3；
• API 契约升级至 1.3；
• OpenAPI 升级至 1.3.0；
• 先由后端会话完成契约设计和转换接口；
• 再由前端会话接入加载、转换中、失败、重试和 PDF 预览状态；
• 最后由集成验证会话测试 DOC、DOCX、XLS、XLSX 和 PDF。

9.2 P1：外部用户和权限系统对接准备

当前系统的固定三角色和文档 ACL 可以支持现阶段业务，但不是最终统一身份权限平台。

建议在接入外部系统前明确：

• 外部用户唯一标识；
• 外部组织唯一标识；
• 用户、组织的同步或实时查询模式；
• Token 由本系统签发还是外部身份系统签发；
• 用户停用、组织调整和 Token 失效机制；
• 外部角色与 ADMIN、AUDITOR、USER 的映射；
• allowedModules 的来源；
• 主案 ACL 主体 ID 的稳定性；
• 外部系统不可用时的容错策略；
• 审计日志保留外部主体标识和操作时快照；
• 管理员是否继续拥有全部管理能力；
• 审计员是否严格限制为只读审计。

建议保留当前英文 code 作为稳定协议值，中文仅作为展示字典。这样可以降低外部系统接入和项目迁移成本。

9.3 P1：独立全量集成验收

完成 P0 项后，由会话4执行一次固定基线验收：

• 全量后端测试；
• AI 回归；
• 全量前端测试；
• 类型检查和构建；
• Flask 与 OpenAPI 一致性；
• 三类真实账号；
• 31 条路径的认证和角色边界抽检；
• 上传、编辑、挂载、权限、下载、删除和恢复闭环；
• 主库 0002 恢复冒烟；
• 文件存在性、大小和 SHA-256；
• 审计和冗余计数；
• 浏览器控制台和 Network；
• 废止路径；
• 配置和敏感信息检查。

9.4 P2：前端遗留代码和构建优化

当前 App.tsx 仍有较多历史模拟数据和旧页面实现，构建存在大包警告。

建议在核心验收稳定后：

• 删除不可达模拟页面和重复映射；
• 将大型页面拆分为业务组件；
• 按路由或模块进行懒加载；
• 拆分文档、管理、审计、回收站等代码块；
• 检查重复依赖；
• 保持 DTO、状态和 UI 组件边界；
• 重新执行回归和包体分析。

9.5 P2：部署和运维能力

工业部门实际使用前建议补充：

• 应用进程托管；
• 反向代理和 HTTPS；
• MySQL 定期备份与恢复演练；
• 文件存储备份和数据库一致性校验；
• 日志轮转；
• 容量、错误率和健康监控；
• 审计留存周期；
• 文件防病毒或恶意内容扫描；
• 上传并发和磁盘容量告警；
• 密钥轮换；
• 安全基线和漏洞扫描；
• 部署升级、数据库迁移和回滚手册。

9.6 P2：补充真实文件样本

建议在固定测试环境补充：

• PDF 在线预览样本；
• DOC、DOCX、XLS、XLSX 下载样本；
• 中文名、长文件名和特殊字符样本；
• 损坏文件和伪造扩展名样本；
• 大文件和批量文件样本；
• Office 转 PDF 实施后的版式对比样本。

10. 推荐执行顺序

顺序	工作	建议负责会话	是否阻塞正式交付
1	备份并升级 dms 主库至 0002	会话3，统领授权	是
2	三类文档正式恢复冒烟	会话3 + 会话4	是
3	固化安全运行配置和部署说明	会话3	是
4	建立 Git 稳定基线	统领会话协调	是
5	Office 预览契约 1.3 设计	统领 + 会话3	否，当前暂缓
6	Office 预览前端接入	会话2	否，当前暂缓
7	清理模拟代码和前端分包	会话2	否
8	外部身份权限系统对接设计	统领会话	否，需外部条件
9	国产化适配验证	专项阶段	否，当前暂缓

11. 第一阶段最终验收条件

只有同时满足以下条件，才建议宣布第一阶段正式交付：

• 两份正式契约、OpenAPI 和实现一致；
• 三类标准账号通过真实密码登录；
• Q1 字典和分类层级通过真实浏览器补验；
• dms_test 全量测试通过；
• dms 正式主库升级至 0002；
• 主案、子方案、共享附件在正式主库恢复成功；
• 恢复失败具备事务原子性；
• 31 条正式路径不存在实质契约偏差；
• 前端测试、类型检查和构建通过；
• 后端测试、AI 回归和编译检查通过；
• 文件路径、大小和 SHA-256 一致；
• 权限、计数和审计一致；
• 生产运行配置已固化；
• 敏感配置未进入源码和 Git；
• 工作区形成可追溯 Git 基线；
• 部署、迁移、备份和恢复步骤可重复执行；
• 集成验证会话给出最终通过结论。

Office 文档在线预览、Milvus、审批、电子签章和国产化适配不属于当前第一阶段最终验收的必选条件，除非统领会话后续正式调整范围。

12. 当前阶段判断

综合判断：

• 业务需求主干已覆盖；
• 前后端核心闭环已实现；
• 数据库、文件、权限、审计和恢复设计已落地；
• 自动化测试基础较完整；
• 尚未达到可直接正式部署和交付的状态；
• 剩余阻塞主要集中在环境基线、正式数据库迁移、安全部署配置和 Git 交付基线，而不是大规模业务功能开发。

建议先关闭第 8 节的 P0 工作，再决定是否立即进入 Office 在线预览或外部统一身份权限系统对接。