tech-achievement-management-system/PROJECT_DOCUMENTATION.md

科技成果转化管理系统 - 项目综合文档

本文档整合了系统设计、用户手册、权限矩阵、部署指南及安全策略，是项目的唯一核心文档。

---

目录

1. 项目概述
2. 角色与权限体系（核心）
3. 业务流程与功能指南
4. 技术架构与开发规范
5. 运维部署与灾难恢复
6. 安全防御体系
7. API 接口规范
8. 数据库设计
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 进行通信。

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 统一响应格式

{
  "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}分钟内有效，请注意保密，切勿告知他人。