# QSDM

**Repository Path**: dovepan_git/qsdm

## Basic Information

- **Project Name**: QSDM
- **Description**: 这是一个基于 Next.js 16 + Python FastAPI + PostgreSQL 的企业级文件管理系统，支持四阶文件架构（手册、程序文件、管理规定、作业指导书、表单记录）的全生命周期管理。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-16
- **Last Updated**: 2026-04-22

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 企业级质量体系文件全生命周期管理平台

基于 [Next.js 16](https://nextjs.org) + [Python FastAPI](https://fastapi.tiangolo.com) + [PostgreSQL](https://www.postgresql.org) 的企业级文件管理系统，支持四阶文件架构的全生命周期管理。

## 技术栈

### 前端
- **框架**: Next.js 16 (App Router) + React 19
- **语言**: TypeScript 5
- **样式**: Tailwind CSS 4 + shadcn/ui
- **主题**: vintage-grey

### 后端
- **框架**: Python FastAPI + Uvicorn
- **数据验证**: Pydantic v2
- **ORM**: SQLAlchemy 2.0
- **数据库**: PostgreSQL 14+
- **文件处理**: PyMuPDF (水印、PDF转换)

### 存储
- **对象存储**: S3 兼容存储（MinIO / AWS S3）
- **包管理器**: pnpm（前端）、pip（后端）

## 功能特性

### 核心功能
- 四阶文件架构管理（手册、程序文件、管理规定、作业指导书、表单记录）
- 部门维度管理（公司-部门-分部三级结构）
- 文件编码自动生成与校验
- 文件状态跟踪（编制中、修订中、编制完成、已批准、已发布、已归档、已废止）
- 版本控制（A/0, A/1, ..., B/0 格式）
- 多维检索（按编号、名称、部门、状态、层级）
- 自动台账生成
- 文件分发与借阅管理
- 文件关联与废止管理
- 操作日志记录
- 水印模板管理（支持边框、文字、旋转）
- Word/Excel 转 PDF 发布
- PDF 水印预览

### 用户角色
- **系统管理员** (admin) - 系统配置和用户管理
- **部门管理员** (dept_admin) - 部门文件审批
- **编制人** (creator) - 创建和编辑文件
- **审核人** (reviewer) - 文件审核
- **批准人** (approver) - 文件批准
- **读者** (reader) - 只读访问

## 快速开始

### 前置要求
- Node.js 20+
- Python 3.11+
- PostgreSQL 14+
- pnpm 9.0+

### 1. 安装依赖

```bash
# 前端依赖
pnpm install

# 后端依赖
cd backend
pip install -r requirements.txt
cd ..
```

### 2. 配置环境变量

```bash
# 后端配置
cd backend
cp .env.example .env
# 编辑 .env 配置数据库和对象存储

# 前端配置（沙箱环境自动配置）
```

### 3. 启动服务

```bash
# 方式一：使用 Coze CLI（推荐）
coze dev

# 方式二：手动启动
# 终端1: 后端服务
cd backend
python -m uvicorn app.main:app --host 0.0.0.0 --port 8000

# 终端2: 前端服务
pnpm dev
```

### 4. 访问系统

| 服务 | 地址 |
|------|------|
| 前端应用 | http://localhost:5000 |
| 后端 API | http://localhost:8000 |
| API 文档 | http://localhost:8000/api/docs |

### 默认账户

```
用户名: admin
密码: admin123
角色: 系统管理员
```

**安全提示**: 生产环境请立即修改默认密码！

## 项目结构

```
.
├── src/                          # 前端源码
│   ├── app/                      # Next.js App Router
│   │   ├── (auth)/              # 认证页面
│   │   │   └── login/           # 登录页
│   │   ├── dashboard/            # 仪表盘页面
│   │   │   ├── departments/      # 部门管理
│   │   │   ├── documents/        # 文档管理
│   │   │   ├── watermarks/       # 水印模板
│   │   │   ├── settings/         # 系统设置
│   │   │   └── ...
│   │   └── globals.css          # 全局样式
│   ├── components/              # React 组件
│   │   └── ui/                  # shadcn/ui 组件
│   └── lib/                     # 工具库
│       └── api/                 # API 客户端
│
├── backend/                     # 后端源码
│   ├── app/
│   │   ├── api/                # API 路由
│   │   │   ├── documents.py    # 文档管理
│   │   │   ├── departments.py   # 部门管理
│   │   │   ├── users.py        # 用户管理
│   │   │   ├── document_publish.py  # 文档发布
│   │   │   ├── watermark_templates.py # 水印模板
│   │   │   ├── system_settings.py   # 系统设置
│   │   │   └── document_distributions.py # 分发管理
│   │   ├── core/               # 核心模块
│   │   │   ├── config.py       # 配置管理
│   │   │   ├── database.py     # 数据库连接
│   │   │   └── auth.py         # JWT 认证
│   │   ├── models/             # Pydantic 模型
│   │   └── services/           # 业务逻辑
│   │       └── document_converter.py  # 水印处理
│   └── requirements.txt        # Python 依赖
│
├── docker/                     # Docker 部署文件
│   ├── docker-compose.yml      # 容器编排
│   ├── deploy.sh               # 部署脚本
│   ├── nginx.conf              # Nginx 配置
│   ├── backend/Dockerfile     # 后端构建
│   └── frontend/Dockerfile     # 前端构建
│
├── scripts/                    # 管理脚本
│   ├── start-backend.sh       # 后端启动脚本
│   └── ...
│
└── .coze                      # Coze CLI 配置
```

## 数据库模型

| 表名 | 说明 |
|------|------|
| users | 用户表 |
| departments | 部门表（三级：公司/部门/分部） |
| document_types | 文档类型表 |
| documents | 文档主表 |
| document_versions | 文档版本表 |
| document_distributions | 文档分发记录表 |
| document_borrows | 文档借阅记录表 |
| watermark_templates | 水印模板表 |
| system_settings | 系统设置表 |

## 部署

### Docker Compose 部署（推荐）

```bash
cd docker

# 配置环境变量
cp .env.example .env
# 编辑 .env 配置密码和域名

# 一键部署
./deploy.sh deploy
```

### 手动部署

参考 [docker/README.md](docker/README.md) 了解详细的部署步骤。

## 文档

- [Docker 部署指南](docker/README.md) - Docker Compose 部署说明
- [项目规范文档](AGENTS.md) - 开发规范和接口文档

## 常见问题

### Q1: 后端服务启动失败
```bash
# 解决方案
cd backend
pip install --force-reinstall -r requirements.txt
bash ../scripts/start-backend.sh
```

### Q2: 文件上传失败
检查对象存储配置（MinIO 或 S3）是否正确。

### Q3: 水印边框不显示
确保水印模板中启用了边框功能，并设置了边框样式。

## 开发规范

### Git 提交规范
```
feat: 新功能
fix: 修复 Bug
docs: 更新文档
style: 代码格式调整
refactor: 重构代码
test: 测试相关
chore: 构建/工具链相关
```

### 代码规范
- 前端: TypeScript ESLint + Prettier
- 后端: Black + isort
- UI: shadcn/ui vintage-grey 主题

## 许可证

MIT License

---

**版本**: 1.0.0  
**最后更新**: 2026-04-11