document-management

方案计划文档管理系统

面向方案、子方案和共享附件全生命周期管理的前后端业务系统。系统提供分类管理、文档上传与下载、共享附件挂载、文档权限、审计统计、回收站恢复和统一中文展示字典。

技术栈

• 前端：React 18、TypeScript、Vite、Material UI
• 后端：Python、Flask、SQLAlchemy、Alembic
• 数据库：MySQL 8
• 文件存储：本地文件系统，数据库仅保存安全相对路径
• 接口规范：OpenAPI 3.0.3

工程结构

.
├─ backend/                    后端应用、迁移、OpenAPI和自动化测试
│  ├─ dms/                    DMS业务模块
│  ├─ src/                    既有AI信息抽取模块
│  ├─ migrations/             Alembic迁移
│  ├─ openapi/                OpenAPI规格
│  ├─ tests/                  后端自动化测试
│  ├─ dms-storage/            正式运行文件存储（内容不提交Git）
│  └─ dms-test-storage/       本地测试文件存储（不提交Git）
├─ frontend/                   React前端
│  └─ src/features/           按业务领域划分的前端模块
├─ docs/                       计划、提示词和演示资料
├─ deliverables/               本地部署包和交付压缩包（不提交Git）
├─ DMS_FUNCTION_CONTRACT.md    正式功能契约
├─ DMS_API_CONTRACT.md         正式接口契约
└─ FUNCTION_AND_API_SPECIFICATION.md

详细文档索引见 docs/README.md。

本地运行

后端

cd backend
python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -r requirements.txt

.env.example 是配置模板，应用不会自动读取本地 .env。运行前应通过进程环境或服务管理器配置至少以下参数：

DMS_DATABASE_URL
DMS_JWT_SECRET
DMS_STORAGE_ROOT

开发启动：

python app.py

默认后端地址为 http://127.0.0.1:8754，健康检查为：

GET /api/v1/health

数据库迁移：

alembic -c migrations/alembic.ini upgrade head

前端

cd frontend
npm install
npm run dev

默认开发端口由 vite.config.ts 配置为 9345。生产接口基础路径通过 VITE_API_BASE_URL 配置。

验证

后端：

cd backend
python -m pytest

前端：

cd frontend
npm run typecheck
npm run test
npm run build

自动化测试源码属于正式工程质量资产，应保留在仓库中；缓存、覆盖率、运行日志和隔离测试存储不提交Git。

配置与数据边界

• 数据库连接、JWT密钥、存储根目录和AI密钥通过安全环境配置提供。
• UI中文展示字典默认位于 backend/dms/resources/ui-dictionaries.zh-CN.json。
• 业务文件保存在 DMS_STORAGE_ROOT，数据库只保存相对路径、大小和SHA-256。
• .env、运行日志、构建目录、部署包和存储文件均不提交Git。

当前基线

• 功能契约：1.2
• API契约：1.2
• OpenAPI：1.2.0
• 数据库迁移最新版本：0002_add_restore_audit_action
• Q1统一UI字典、分类层级和真实认证已通过独立验收