# 科技成果转化管理系统 - 项目综合文档
本文档整合了系统设计、用户手册、权限矩阵、部署指南及安全策略，是项目的唯一核心文档。
---
## 目录
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 全量权限操作矩阵
下表详细列出了不同角色在不同场景下的操作权限区别。
**图例**：✅ 允许 | ❌ 禁止 | ⚠️ 有限制
| 功能模块 | 操作行为 | 普通用户
(无关人员) | 普通用户
(提交人) | 普通用户
(完成人) | 中级用户 | 高级用户 | 管理员 | 超级管理员 | 系统维护员 | 权限说明 |
| :--- | :--- | :---: | :---: | :---: | :---: | :---: | :---: | :---: | :---: | :--- |
| **基础访问** | 登录/注册 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | |
| | 移动端访问 | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | 全局禁止非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}分钟内有效，请注意保密，切勿告知他人。 |