Files
2026-04-19 14:05:40 +08:00

371 lines
20 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 科技成果转化管理系统 - 项目综合文档
本文档整合了系统设计、用户手册、权限矩阵、部署指南及安全策略,是项目的唯一核心文档。
---
## 目录
1. [项目概述](#1-项目概述)
2. [角色与权限体系(核心)](#2-角色与权限体系核心)
3. [业务流程与功能指南](#3-业务流程与功能指南)
4. [技术架构与开发规范](#4-技术架构与开发规范)
5. [运维部署与灾难恢复](#5-运维部署与灾难恢复)
6. [安全防御体系](#6-安全防御体系)
7. [API 接口规范](#7-api-接口规范)
8. [数据库设计](#8-数据库设计)
9. [常见问题 (FAQ)](#9-常见问题-faq)
---
## 1. 项目概述
本项目是一个现代化的科技成果转化管理系统,旨在解决企事业单位及科研机构在成果管理中的痛点。系统支持多种科技成果类型的全生命周期管理,包括录入、审核、统计分析及归档导出。
### 核心特性
- **全流程管理**:从成果提交、审核到归档的闭环管理。
- **多维度统计**:提供饼图、雷达图、堆叠柱状图、面积图等丰富的可视化分析。
- **严格权限控制**:基于角色的访问控制 (RBAC) + 细粒度的状态权限判断。
- **安全合规**:移动端拦截、HTTPS 加密、操作日志审计、敏感数据脱敏。
- **智能化处理**:自动归属部门、查重拦截、附件生命周期管理。
---
## 2. 角色与权限体系(核心)
系统设计了精细的权限模型,确保数据安全与业务流转的规范性。
### 2.1 角色定义
| 角色 | 代码 | 职责描述 |
| :--- | :--- | :--- |
| **普通用户** | `user` | 业务人员。负责成果数据的录入,查看自己参与的和自己所在科室的已通过成果。 |
| **中级用户** | `intermediate_user` | 科室主任。可查看本科室及本科室成员参与的所有已通过成果。 |
| **高级用户** | `senior_user` | 单位领导。可查看全单位所有已通过的成果,用于全局浏览和决策支持。 |
| **管理员** | `admin` | 管理员。负责审核成果。 |
| **系统维护员** | `maintainer` | 技术支持人员。负责字典、部门等基础数据维护,查看系统日志,重置用户密码。**无权访问任何成果数据**。 |
| **超级管理员** | `super_admin` | 系统管理。 |
### 2.2 全量权限操作矩阵
下表详细列出了不同角色在不同场景下的操作权限区别。
**图例**:✅ 允许 | ❌ 禁止 | ⚠️ 有限制
| 功能模块 | 操作行为 | 普通用户<br>(无关人员) | 普通用户<br>(提交人) | 普通用户<br>(完成人) | 中级用户 | 高级用户 | 管理员 | 超级管理员 | 系统维护员 | 权限说明 |
| :--- | :--- | :---: | :---: | :---: | :---: | :---: | :---: | :---: | :---: | :--- |
| **基础访问** | 登录/注册 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | |
| | 移动端访问 | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | 全局禁止非PC设备 |
| **成果查看** | 查看列表 | ⚠️ | ⚠️ | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ | 普通/中级/高级按范围过滤;管理员/超管可见全部状态 |
| | 查看详情 | ⚠️ | ⚠️ | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ | 详情权限与列表一致 |
| | **查看范围** | 本部门已通过 | 本人待审/驳回 + 本部门已通过 | 个人相关(任意状态) + 本部门已通过 | 本科室已通过(含本科室成员参与) + 个人相关 + 本人待审/驳回 | 全单位已通过 + 个人相关 + 本人待审/驳回 | 全量(含待审/驳回/已通过) | 全量(含待审/驳回/已通过) | 无 | 完成人通过 contributors.phone 精确匹配 |
| **成果录入** | 新增成果 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | 当前实现未限制维护员 |
| **成果修改** | 修改(待审核) | ❌ | ✅ | ❌ | ⚠️ | ⚠️ | ⚠️ | ✅ | ⚠️ | 仅提交人可改;超管可改任意成果 |
| | 修改(已驳回) | ❌ | ✅ | ❌ | ⚠️ | ⚠️ | ⚠️ | ✅ | ⚠️ | 仅提交人可改;超管可改任意成果 |
| | 修改(已通过) | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ | ❌ | 仅超管可修改 |
| **成果删除** | 删除(待审核) | ❌ | ✅ | ❌ | ⚠️ | ⚠️ | ⚠️ | ✅ | ⚠️ | 仅提交人可删;超管可删任意成果 |
| | 删除(已驳回) | ❌ | ✅ | ❌ | ⚠️ | ⚠️ | ⚠️ | ✅ | ⚠️ | 仅提交人可删;超管可删任意成果 |
| | 删除(已通过) | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ | ❌ | 仅超管可删 |
| **业务审核** | 审核通过/驳回 | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ | ✅ | ❌ | 管理员回避:不可审自己参与的成果 |
| **数据分析** | 查看统计图表 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | 统计图默认仅已通过;状态分布仅超管/维护员全量 |
| | 导出数据/附件 | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ | ❌ | 仅超管 |
| **成果附件** | 下载单个附件 | ❌ | ⚠️ | ✅ | ⚠️ | ⚠️ | ✅ | ✅ | ❌ | 完成人可下;提交人仅待审/驳回可下 |
| | 下载成果附件包 | ❌ | ⚠️ | ✅ | ⚠️ | ⚠️ | ✅ | ✅ | ❌ | 与单附件规则一致 |
| **系统管理** | 用户管理 | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ | ⚠️ | 超管全权;维护员仅列表/重置密码 |
| | 部门/字典维护 | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ | ✅ | 仅超管/维护员 |
| | 查看系统日志 | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ | ✅ | 仅超管/维护员 |
| | 发布系统公告 | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ | ✅ | 仅超管/维护员 |
| | 全量数据校验 | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ | ❌ | 仅超管 |
| **通知公告** | 查看公告列表/详情 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | 所有登录用户可看 |
| | 下载公告附件 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | 所有登录用户可下 |
| | 删除公告 | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ | ✅ | 仅超管/维护员可删 |
### 2.3 特殊场景说明
#### 场景 A:我是提交人,但不是完成人
> **例子**:管理员帮项目组录入成果。
- **待审核/已驳回**:拥有完全控制权(修改/删除)。
- **已通过**:权限降级为只读。
#### 场景 B:我是完成人,但不是提交人
> **例子**:项目负责人录入,我是成员。
- **待审核/已驳回**:**不可见**。为了隐私和准确性,草稿状态仅提交人可见。
- **已通过**:可见,但不可修改。
#### 场景 C:管理员的回避制度
- 如果管理员是某项成果的完成人之一,该成果在审核列表中对其**自动隐藏**。
- 必须由其他管理员或超级管理员进行审核。
---
## 3. 业务流程与功能指南
### 3.1 成果申报全流程
#### 3.1.1 成果类型详解
系统支持以下 10 种科技成果类型的申报:
1. **论文 (Paper)**: 已发表的学术论文 (SCI/EI/核心等)。
2. **专利 (Patent)**: 发明专利、实用新型、外观设计。
3. **项目 (Project)**: 纵向课题、横向课题、自选项目。
4. **奖励 (Award)**: 国家级、省部级、行业协会奖励。
5. **标准 (Standard)**: 国际标准、国家标准、行业标准、地方标准。
6. **专著 (Book)**: 出版发行的学术著作、译著。
7. **技术报告 (Report)**: 提交给政府或企业的咨询报告、技术方案。
8. **规划 (Plan)**: 发展规划、战略研究报告。
9. **成果转化 (Transfer)**: 技术转让、许可、作价入股。
10. **软著 (Software)**: 计算机软件著作权。
#### 3.1.2 智能表单填写指南
* **动态字段联动**: 不同类型的成果需要填写的字段不同(如论文需填“期刊名称”,专利需填“专利号”)。
* **完成人添加与排序**:
* 点击“添加完成人”按钮,输入姓名和手机号。
* 列表中的**第一位**默认为“主要完成人”(负责人)。
* 系统会自动根据**主要完成人**的手机号,查找其在系统中的注册信息,并将该成果自动归属到其所在部门。
* **附件上传规范**: 支持 PDF, Office, 图片, 压缩包。单个文件最大 **500MB**
#### 3.1.3 查重拦截机制
为了避免重复统计,系统内置了查重机制。当您点击提交时,系统会检查:
1. **唯一标识符**: 如专利号、论文DOI、软著登记号等是否已存在。
2. **名称+日期**: 如果同一天内提交了完全相同的成果名称。
如果检测到重复,系统将拦截提交。
### 3.2 审核与管理 (管理员视角)
#### 3.2.1 审核流程
1. **查看详情**: 点击成果名称,进入详情页。
2. **核对信息**: 检查填写的字段是否完整、准确,附件是否清晰、合规。
3. **给出结论**:
* **通过**: 成果状态变为“已通过”,正式计入统计数据。
* **驳回**: 需填写驳回理由。成果状态变为“已驳回”,提交人可修改后重新提交。
#### 3.2.2 附件清理
当成果被“驳回”或“删除”时,为了节省服务器空间,系统会自动清理关联的附件文件。
### 3.3 数据可视化与决策支持
进入“统计分析”页面,系统提供多维度的可视化报表。
* **部门贡献度分析**:
* **堆叠柱状图**: 展示各部门在不同年份的成果产出数量。
* **雷达图**: 展示各部门在不同成果类型上的分布,分析“偏科”现象。
* **历史趋势分析 (累计增长)**:
* **堆叠面积图**: 展示全单位及各部门的**累计**成果贡献趋势。
* **双轴组合图**: 左轴展示全单位总量,右轴展示各部门独立增长曲线。
#### 3.3.1 批量导出与表单生成
系统支持将成果数据以“电子档案”的形式批量导出,便于线下归档或上报。
* **批量生成表单**: 在用户管理或成果列表中,可选择多条成果,系统会自动将每条成果的详情页渲染为图片。
* **打包下载**: 系统将生成的表单图片及相关附件打包为 ZIP 文件,一键下载。
### 3.4 系统公告与通知
系统内置了全员通知系统,支持富文本编辑和附件分发。
* **发布公告**: 高级用户及以上角色可发布公告,支持置顶、富文本排版及多附件上传。
* **自动报警**: 系统集成了监控机制,当服务器磁盘空间不足(默认阈值 10GB)时,会自动以“系统监控”身份发布置顶报警公告,提醒管理员处理。
### 3.5 数据一致性校验
为了应对历史数据迁移或意外操作可能导致的数据脏读,系统提供了**全量数据校验工具**(仅超级管理员可用)。
* **校验范围**:
* **完成人结构**: 检查 JSONB 数据格式是否符合规范。
* **归属部门**: 检查成果归属部门是否存在于当前部门字典中。
* **字典约束**: 检查成果类型、等级等字段是否在合法值范围内。
* **一键修复**: 对于部分逻辑错误,系统提供指引或自动修复建议。
---
## 4. 技术架构与开发规范
### 4.1 总体架构
系统采用经典的 **前后端分离 (SPA)** 架构,通过 RESTful API 进行通信。
```mermaid
graph TD
Client[React 前端 SPA] -->|HTTPS/JSON| Nginx[Nginx 反向代理]
Nginx -->|Proxy Pass| Server[Node.js 后端 API]
Nginx -->|Static Files| Uploads[文件存储]
Server -->|SQL| DB[(PostgreSQL 17)]
```
### 4.2 目录结构
#### 后端 (`server/`)
* `index.js`: 应用入口,负责中间件装载、路由分发、HTTPS 启动。
* `routes/`: 路由定义层,按业务模块拆分 (auth, achievements, users...)。
* `middleware/`: 中间件层 (auth.js 鉴权, auditLogger.js 审计)。
* `utils/`: 工具库 (logger.js 日志, diskMonitor.js 监控)。
* `scripts/`: 运维脚本 (setup.js 初始化, seed_data.js 种子数据)。
#### 前端 (`client/src/`)
* `pages/`: 页面组件,对应路由 (Dashboard, Upload, Audit...)。
* `components/`: 通用业务组件 (MainLayout 布局, UserSearchSelect 用户搜索)。
* `constants/`: 常量定义 (achievements.js 定义了10种成果类型的元数据)。
### 4.3 后端核心机制实现
#### 4.3.1 安全防护中间件链
1. **CORS**: 跨域资源共享控制,严格限制 `origin` 来源,防止恶意跨域请求。
2. **RateLimit (限流)**: 全局 100 req/min,认证接口 10 req/min。
3. **MobileInterceptor (移动端拦截)**: 通过 User-Agent 识别并拦截移动设备。
4. **Morgan (日志脱敏)**: 正则替换 URL 中的 `token`, `password``***`
#### 4.3.2 审计日志系统 (AuditLogger)
* **机制**: 拦截所有非 GET 请求(修改性操作)。
* **语义翻译**: 内置映射表,将 `POST /api/achievements` 自动翻译为“上传成果”。
* **记录内容**: 操作人、IP、时间、耗时、操作结果。
#### 4.3.3 文件存储策略
* **写入**: 始终写入 `UPLOAD_DIR` (主目录)。
* **读取**: 先在 `UPLOAD_DIR` 查找,若未找到,遍历 `UPLOAD_FALLBACK_DIRS` (历史目录列表)。
* **安全增强**:
* **Magic Number 检查**: 引入 `file-type` 库,通过文件二进制头校验真实类型,防止伪装文件上传。
* **静态资源防护**: 强制设置 `Content-Disposition: attachment`,防止 HTML/JS 文件在浏览器中直接执行。
#### 4.3.4 稳定性保障机制
* **内存泄漏防护**: 针对验证码等临时数据,使用定时任务 (`setInterval`) 自动清理过期条目,防止内存溢出。
* **数据库连接保活**: 监听连接池 `error` 事件,在连接断开时安全处理,防止 Node.js 进程崩溃。
### 4.4 前端工程化实践
* **常量驱动开发**: 在 `client/src/constants/achievements.js` 中定义所有成果类型的元数据,新增类型无需改动业务逻辑。
* **组件复用**: 如 `UserSearchSelect` 组件,实现带有防抖的远程搜索下拉框。
---
## 5. 运维部署与灾难恢复
### 5.1 基础设施规划
* **操作系统**: Windows Server 2016+ / Ubuntu 20.04 LTS+ / CentOS 7.9+
* **运行环境**: Node.js v18.16.0+ (推荐 v20 LTS)。
* *兼容性说明*: 系统内置了对 `fs.promises.statfs` 的特性检测,确保在旧版 Node.js 上也能正常运行。
* **数据库**: PostgreSQL 17.x (必须支持 JSONB 类型)
* **Web 服务器**: Nginx 1.20+
### 5.2 Windows 环境部署实战
1. **安装依赖**: 使用 `配置包` 安装 Node.js 和 PostgreSQL。
2. **后端配置**:
* 复制 `.env.example``.env`
* 配置 `DB_PASSWORD`, `JWT_SECRET`, `UPLOAD_DIR`
* *环境变量支持*: 前端支持 `REACT_APP_API_URL` 环境变量,便于灵活配置 API 地址。
* 运行 `npm install``npm run init-db`
3. **前端构建**:
* 运行 `npm install``npm run build`
4. **Nginx 配置**:
* 配置 `client_max_body_size 500M` 支持大文件。
* 配置 `proxy_pass` 转发 API 请求。
* 配置 `alias` 托管上传文件。
5. **HTTPS 配置**: 使用 `mkcert` 生成自签名证书。
### 5.3 Linux 生产环境部署实战
1. **环境构建**: 安装 Node.js, PostgreSQL, Nginx。
2. **权限管理**: 创建专用用户 `stapp`,严禁使用 root 运行。
3. **进程守护**: 使用 PM2 (`pm2 start index.js --name "st-backend" --time`)。
4. **防火墙**: 仅开放 22, 80, 443 端口。
### 5.4 数据安全与灾难恢复
#### 5.4.1 自动备份策略
建议在 Linux 下使用 `crontab` 设置每日自动备份数据库。
#### 5.4.2 专用备份工具 (STBackupTool)
对于 Windows 用户,提供图形化工具:
* **一键备份**: 自动打包数据库 SQL 和上传文件为 ZIP 包。
* **一键恢复**: 自动解压、导入数据、修复序列、还原文件。
#### 5.4.3 灾难恢复演练
**场景:服务器硬盘彻底损坏,需迁移到新机器。**
1. **搭建新环境**: 安装 Node.js 和 PostgreSQL。
2. **创建空数据库**: **绝对不要运行 `npm run init-db`** 必须保持数据库为空。
3. **执行恢复**: 使用 `STBackupTool` 导入备份包。
---
## 6. 安全防御体系
### 6.1 网络层防御
* **反向代理隐藏**: Nginx 统一入口,隐藏后端端口。
* **全站 HTTPS**: 强制 SSL 加密,防止中间人攻击。
* **安全响应头**: 启用 `X-Frame-Options`, `X-XSS-Protection`
* **CORS 策略**: 严格限制跨域请求来源,防止 CSRF 攻击。
### 6.2 应用层防御
* **SQL 注入防御**: 全面使用参数化查询。
* **文件上传安全**:
* **白名单过滤**: 仅允许 PDF/Office/图片/压缩包。
* **Magic Number 校验**: 检查文件二进制头,防止伪装文件。
* **自动重命名**: 防止文件名冲突和路径注入。
* **Token 保护**: 附件下载使用 `Authorization` 头传递 Token,避免 URL 泄露。
* **防暴力破解**: 认证接口限流 (10次/分钟),验证码机制。
### 6.3 数据隐私保护
* **密码存储**: bcrypt 加盐哈希。
* **日志脱敏**: 自动替换日志中的敏感字段。
* **真实 IP 追踪**: 配置 Nginx 传递 `X-Forwarded-For`
### 6.4 权限安全
* **精确匹配**: 使用 PostgreSQL 的 JSONB 操作符进行权限判断,消除因重名导致的权限漏洞。
* **状态隔离**: 严格区分草稿、待审核、已通过状态下的操作权限。
---
## 7. API 接口规范
### 7.1 统一响应格式
```json
{
"success": true,
"data": { ... } // 业务数据
}
```
### 7.2 核心接口定义
* **成果上传**: `POST /api/achievements` (Multipart)
* **统计数据**: `GET /api/statistics`
* **认证**: `POST /api/auth/login`
* **日志**: `GET /api/logs`
---
## 8. 数据库设计
### 8.1 核心表结构
* **users**: 用户表 (id, username, password_hash, role, department...)
* **achievements**: 成果表 (id, type, status, contributors, assigned_departments...)
* *数据完整性*: 外键约束配置为 `ON DELETE SET NULL`,防止误删用户导致成果数据丢失。
* **audit_logs**: 审计日志表 (id, user_id, method, url, description, status...)
### 8.2 JSONB 的应用
为了应对灵活的“完成人”列表,使用 PostgreSQL 的 `JSONB` 类型存储 `contributors` 字段 `[{name, phone, is_main}]`,避免了复杂的关联表,且查询性能极佳。
---
## 9. 常见问题 (FAQ)
**Q: 为什么我提交了成果,但在列表里找不到?**
A: 默认列表只显示“我的成果”。请检查您是否是该成果的完成人。
**Q: 附件上传失败,提示“Network Error”?**
A: 可能是文件过大(超过500MB)或网络不稳定。建议在内网环境下操作。
**Q: 如何修改已通过审核的成果?**
A: 为了数据严谨性,已通过的成果不允许普通用户修改。请联系超级管理员进行“退回”或“修改”操作。
**Q: 手机无法访问系统?**
A: 系统开启了移动端拦截策略,仅允许 PC 浏览器访问,以确保数据安全。
## 10. 补充
### 10.1 系统相关账号和密码
| 类型 | 账号 | 密码 |
| :--- | :--- | :--- |
| 数据库 | postgre | 020416 |
| 服务器 | STsystem | STsystem |
| 超级管理员 | 18888888888 | admin123 |
| 系统维护员 | 19999999999 | maintainer123 |
### 10.2 运行服务器相关服务
PostgreSQL自启动服务
STsystem_local_backend 系统后端nssm注册服务
STsystem_network_nginx Nginx网络代理的nssm注册服务
### 10.3 阿里云短信认证服务
| 分类 | 配置项 | 详细信息 |
| :--- | :--- | :--- |
| 平台 | 网址 | https://dypns.console.aliyun.com/overview |
| 资源 | 使用情况 | 初级购入300条,现剩余超80% |
| 签名 | 名称 | 速通互联验证码 |
| 签名 | 使用场景 | 发送测试短信 |
| 模板 | 名称 | 登录/注册模板 |
| 模板 | Code | 100001 |
| 模板 | 内容 | 您的验证码为 ${code}。尊敬的客户,以上验证码 ${min}分钟内有效,请注意保密,切勿告知他人。 |