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

> 更新日期：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` 乐观锁；
- 废止旧恢复路径。

对应数据库迁移为：

```text
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 是正式契约规定的当前行为。

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

```text
原始 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. 第一阶段最终验收条件

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

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

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

## 12. 当前阶段判断

综合判断：

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

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