肿瘤微环境可视化分析系统

---

一、项目概述

本系统是一个面向肿瘤微环境（Tumor MicroEnvironment, TME）研究的可视化分析平台，整合单细胞转录组与空间转录组数据，提供从数据导入、解卷积计算到交互式空间可视化的全链路分析能力。系统采用 Flask + SQLite 后端、原生 JavaScript + deck.gl (WebGL) 前端架构，支持多项目隔离、角色权限管理与科研验证闭环。

---

二、目录结构说明

flask/
├── backend/                    # Flask 应用层
│   ├── app.py                  # 应用工厂，注册蓝图与路由
│   ├── http_util.py            # 请求/响应工具函数
│   ├── scripts_init_db.py      # 数据库初始化入口
│   └── blueprints/             # API 蓝图（按领域拆分）
│       ├── auth_bp.py          #   认证与项目管理
│       ├── datasets_bp.py      #   数据集管理
│       ├── tasks_bp.py         #   解卷积任务
│       ├── visualization_bp.py #   可视化数据
│       ├── reports_bp.py       #   报告生成
│       ├── validation_bp.py    #   验证基准
│       └── ops_bp.py           #   审计与导入日志
│
├── core/                       # 核心业务逻辑层
│   ├── config.py               # 全局配置（路径、开关、超时）
│   ├── constants.py            # 细胞类型色板、必填列、阈值常量
│   ├── db.py                   # SQLite 连接与初始化
│   ├── errors.py               # 统一错误类型
│   ├── schemas.py              # Pydantic 请求校验模型
│   ├── security.py             # 鉴权、角色判断、项目权限
│   ├── path_utils.py           # 存储路径安全解析
│   ├── processing.py           # 解卷积计算主流程
│   ├── geo_import.py           # GEO 原始数据自动转换
│   ├── public_import.py        # 公开/远程数据导入
│   ├── quality.py              # 数据质量评分
│   └── services/               # 各领域的服务函数
│       ├── datasets.py         #   数据集增删查与导入
│       ├── tasks.py            #   任务队列管理
│       ├── visualization.py    #   可视化查询与导出
│       ├── reports.py          #   报告生成（PDF/JSON）
│       ├── validation.py       #   验证基准评估
│       └── ops.py              #   审计/导入日志查询
│
├── frontend/                   # 前端页面与静态资源
│   ├── login.html              # 登录/注册页
│   ├── workspace.html          # 工作台主页（核心交互页）
│   ├── index.html              # 入口跳转页
│   └── static/
│       ├── css/
│       │   └── styles.css      # 全局样式（深色主题）
│       └── js/
│           ├── api.js          # 后端 API 封装
│           ├── auth.js         # 登录/注册/鉴权逻辑
│           ├── workspace.js    # 工作台主控逻辑
│           ├── workspace-helpers.js  # 辅助工具（颜色、区域计算）
│           ├── workspace-charts.js   # ECharts 图表构建
│           ├── echart-panel.js       # ECharts 面板封装
│           ├── echarts-setup.js      # ECharts 全局配置
│           ├── echarts.min.js        # ECharts 库
│           ├── spatial-deck.js       # deck.gl WebGL 空间渲染引擎
│           └── toast.js              # 消息通知组件
│
├── worker/                     # 后台任务 Worker
│   └── worker.py               # 轮询 SQLite 队列，执行解卷积
│
├── scripts/                    # 辅助脚本
│   ├── init_db.py              # 数据库建表与默认用户
│   ├── prepare_geo_input.py    # GEO 原始数据打包为可导入 ZIP
│   └── verify_graduation.py    # 计算机设计自动化验收脚本
│
├── sql/                        # 数据库 DDL
│   └── schema_sqlite.sql       # 全部表结构定义
│
├── GEO/                        # GEO 原始数据集（5 套）
│   ├── 01_lung_GSE268049_GSE131907/
│   ├── 02_breast_GSE240212_scRef_GSE131907/
│   ├── 03_hepatoblastoma_GSE249965_scRef_GSE131907/
│   ├── 04_PDAC_GSE274103_scRef_GSE131907/
│   ├── 05_CRC_GSE267401_scRef_GSE131907/
│   └── README.md               # GEO 数据集说明
│
├── data/                       # 运行时数据
│   ├── app.db                  # SQLite 数据库文件
│   ├── output/                 # 解卷积计算结果（按数据集 ID 分目录）
│   └── raw/                    # 导入的原始数据
│       ├── imported/           #   用户上传/GEO 自动导入的数据
│       ├── public_demo/        #   内置演示数据（基础样例）
│       ├── public_tumor_core/  #   内置演示数据（肿瘤核心）
│       ├── public_immune_ring/ #   内置演示数据（免疫环）
│       ├── public_myeloid_bands/ # 内置演示数据（髓系条带）
│       ├── public_balanced_mix/  # 内置演示数据（混合均衡）
│       └── public_quadrants/     # 内置演示数据（四象限）
│
├── input/                      # 待导入 ZIP 包（GEO 转换后的输出）
│
├── reports/                    # 生成的报告文件
│   └── validation/             #   验证基准报告
│
├── 运行步骤必看/                # 运行说明文档
├── mac_run.sh                  # macOS 日常启动脚本
├── mac_setup_run.sh            # macOS 首次安装脚本
├── window_run.bat              # Windows 启动脚本
├── requirements.txt            # Python 依赖清单
└── 项目说明.md                  # 本文件

---

三、功能清单

3.1 用户与认证

功能	说明
用户登录	用户名 + 密码登录，返回 Bearer Token，有效期 24 小时
用户注册	注册新账号，密码至少 6 位，角色可选 editor / viewer
修改密码	验证原密码后修改，支持向后兼容历史哈希
Token 鉴权	所有 API 请求携带 Bearer Token，自动校验有效期与撤销状态
角色权限	editor 可执行写操作（导入、删除、运行任务）；viewer 只读
项目隔离	每个用户绑定项目，viewer 只能访问自己项目的数据

3.2 项目管理

功能	说明
创建项目	editor 角色可创建项目（名称 + 描述）
删除项目	editor 角色可删除项目及其关联数据
项目列表	按角色过滤：editor 查看全部，viewer 仅看所属项目

3.3 数据集管理

功能	说明
ZIP 批量导入	上传包含四份标准 CSV 的 ZIP，系统自动解压入库
多文件分项上传	分别上传单细胞表达、单细胞元数据、空间表达、空间坐标、组织切片图
GEO 自动导入	从本地 GEO 目录自动解析 Visium/10x 数据，转换为标准格式后入库
公开数据导入	通过 URL 下载公开数据（支持 HTTP/本地 file://），自动解析归档
内置演示数据导入	系统自带 6 套模拟数据（肿瘤核心、免疫环、髓系条带等），一键导入
数据集列表	按项目过滤，显示名称、来源、版本、状态
数据集详情	查看数据集元信息、输入资产清单、质量报告
删除数据集	editor 角色可删除数据集及其输出文件
版本管理	同一数据集支持多版本，可查看历史版本

3.4 数据质量检查

功能	说明
空间数据校验	检查坐标有效性、丰度值合法性、细胞类型数量
参考数据校验	检查标记基因完整性、细胞类型标注完整性
质量评分	百分制评分，按错误比例扣分（坐标 30 分、丰度 20 分、空细胞类型 20 分等）
通过/警告判定	可用点位 ≥ 20、细胞类型 ≥ 2 且错误率 < 10% 为通过

3.5 解卷积任务

功能	说明
提交任务	对指定数据集提交解卷积任务（integration_deconvolution）
任务队列	SQLite 生产者-消费者模型，Flask 入队，Worker 出队执行
任务轮询	前端定时轮询任务状态，支持进度显示
30 分钟硬超时	任务运行超过 30 分钟直接标记为 failed
任务删除	editor 可删除失败或已完成的任务
任务指标	汇总项目内任务成功率、平均耗时等指标

3.6 解卷积计算（Worker）

功能	说明
签名投影模型	基于单细胞参考构建细胞类型签名矩阵，投影到空间表达
NNLS 空间平滑	非负最小二乘拟合 + 空间邻居平滑，优化丰度估计
UMAP 降维	对空间点位表达谱进行 UMAP 嵌入，用于聚类可视化
桥接模式	当仅有 spatial_spots + sc_reference 时，自动生成合成单细胞参考与空间表达
基因筛选	按空间表达量与标记基因特异性排序，选择高区分度基因
置信度评估	计算每个点位的解卷积置信度与不确定性比例
拟合质量	报告 R²、ΔR²、告警等级（高/中/提示/无）
基准评估	对比不同平滑参数组合，选择最优 alpha 和 k

3.7 可视化 — WebGL 空间图

功能	说明
deck.gl 渲染	基于 WebGL 的 ScatterplotLayer，高性能渲染数万空间点位
组织切片叠加	在点位下方叠加组织切片图像（BitmapLayer）
深色主题	深色背景 + 高饱和度色板，确保点位醒目
丰度映射	点位大小与亮度随丰度值动态变化
细胞类型筛选	按细胞类型显示/隐藏点位，未选中类型半透明
缩放平移	支持 0.001x ~ 12x 缩放范围，首次加载自动适配全量区域
框选 ROI	在空间图上框选感兴趣区域，自动计算区域统计
预设保存	保存当前可视化参数（点大小、透明度、丰度阈值等）

3.8 可视化 — ECharts 图表

功能	说明
ROI 细胞比例堆叠图	展示左半区/右半区各细胞类型比例的堆叠柱状图
ROI 指标对比图	对比两个区域的关键指标（平均丰度、主导细胞类型等）
UMAP 聚类图	基于空间表达 UMAP 嵌入的散点图，按细胞类型着色
四象限热力矩阵	将空间图分为四象限，展示各象限细胞组成
数据集对比	跨数据集的统计对比

3.9 可视化 — 数据查询

功能	说明
空间点位查询	分页获取点位坐标、细胞类型、丰度（支持区域/类型/丰度过滤）
细胞类型图例	获取数据集的细胞类型列表及对应颜色
统计概览	点位总数、平均丰度、细胞类型分布
解卷积结果	获取完整解卷积输出（模型名称、版本、各点位比例）
区域统计	按空间范围聚合统计
空间点位导出	导出点位数据为 JSON 或 CSV
组织切片图	获取组织切片图像

3.10 报告生成

功能	说明
数据集报告	生成包含空间分析、模型评估、数据质量的解读报告（PDF/JSON）
空间形态解读	自动计算四象限分布、主导细胞类型、空间拉伸方向
模型评估解读	置信度、R²、告警等级、平滑参数等
建议动作	根据结果质量给出后续分析建议

3.11 科研验证闭环

功能	说明
准确性评估	解卷积预测 vs 地面真值的 MAE 与主导类型一致率
稳定性评估	平均置信度、不确定点位比例、变异系数稳定性
重复性评估	两次独立运行的一致性（MAE、主导类型一致率）
综合评分	准确性 45% + 稳定性 35% + 重复性 20% 加权综合分
按癌种汇总	按癌种分组汇总各指标
按样本汇总	按样本分组汇总各指标
验证报告	生成验证基准报告（PDF/JSON）
告警机制	根据综合分自动评定告警等级

3.12 运维与审计

功能	说明
审计日志	记录所有 API 请求的用户、方法、路径、状态码
导入日志	记录每次数据导入的类型、来源、质量、错误信息
健康检查	/health 端点快速检测服务可用性
内联 Worker	可配置 BACKEND_INLINE_WORKER 使 Flask 同步执行任务（调试用）
演示数据禁用	/api/demo-datasets/profiles 返回 410，防止虚假数据误用

3.13 数据准备脚本

功能	说明
GEO 数据转换	prepare_geo_input.py 将 GEO 原始归档（Visium RAW.tar + 单细胞矩阵）转换为标准四 CSV 打包 ZIP
Visium HDF5 支持	自动检测并转换 10x HDF5 表达矩阵 + spatial.tar.gz
标记基因评分	对单细胞矩阵进行细胞类型特异性评分，优先选择高区分度基因
细胞过滤	排除 doublet/ambiguous/unknown 等低质量细胞类型
基因过滤	排除管家基因、核糖体蛋白、血红蛋白、免疫球蛋白等
计算机设计验收	verify_graduation.py 自动化测试全链路（登录→导入→解卷积→可视化→WebGL 检测）
数据库初始化	init_db.py 建表并创建默认 admin 账号

---

四、细胞类型色板

细胞类型	颜色	说明
Tumor	#ff3b4f	红色，肿瘤细胞
T-cell	#3b8bff	蓝色，T 细胞
B-cell	#22d3a7	绿色，B 细胞
Myeloid	#ffb020	橙色，髓系细胞

系统同时支持 20+ 种扩展细胞类型（如 Fibroblasts、Endothelial cells、Macrophages 等），每种均有独立高饱和度配色，并在超出预设范围时自动使用 20 色回退色板。

---

五、技术栈

层级	选型
后端框架	Flask 3.0
数据库	SQLite（本地单文件）
任务队列	SQLite 轮询（生产者-消费者模型）
数据校验	Pydantic 2.9
降维	UMAP-learn 0.5
机器学习	scikit-learn 1.5（NNLS 拟合）
HDF5 读取	h5py 3.11
PDF 生成	ReportLab 4.2
空间渲染	deck.gl 9.2（WebGL 2）
图表	ECharts 5
前端	原生 HTML + CSS + JavaScript（ES Module）
默认端口	8100

---

六、运行方式

脚本	用途
mac_setup_run.sh	macOS 首次安装：创建虚拟环境、安装依赖、初始化数据库、启动服务
mac_run.sh	macOS 日常启动：Flask 后端 + Worker 后台运行
window_run.bat	Windows 启动脚本
python scripts/init_db.py	单独初始化数据库
python scripts/prepare_geo_input.py	从 GEO 数据生成可导入 ZIP
python scripts/verify_graduation.py	计算机设计自动化验收
python worker/worker.py	单独启动 Worker（支持 --once 单次执行）

默认账号：admin / admin123