# 方案计划文档管理系统

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

## 技术栈

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

## 工程结构

```text
.
├─ 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](docs/README.md)。

## 本地运行

### 后端

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

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

```text
DMS_DATABASE_URL
DMS_JWT_SECRET
DMS_STORAGE_ROOT
```

开发启动：

```powershell
python app.py
```

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

```text
GET /api/v1/health
```

数据库迁移：

```powershell
alembic -c migrations/alembic.ini upgrade head
```

### 前端

```powershell
cd frontend
npm install
npm run dev
```

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

## 验证

后端：

```powershell
cd backend
python -m pytest
```

前端：

```powershell
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字典、分类层级和真实认证已通过独立验收