chore: initial import

2026-04-19 14:05:40 +08:00
commit 89e9eae36e
81 changed files with 37363 additions and 0 deletions
@@ -0,0 +1,370 @@
+# 科技成果转化管理系统 - 项目综合文档
+
+本文档整合了系统设计、用户手册、权限矩阵、部署指南及安全策略，是项目的唯一核心文档。
+
+---
+
+## 目录
+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}分钟内有效，请注意保密，切勿告知他人。 |
+