开发说明 · 赵齐实验室管理

📄 开发说明与界面规范赵齐实验室管理 · 中山大学肿瘤防治中心 · v2.0

本文档为「赵齐实验室管理」系统的开发说明，包含系统架构、目录结构、界面风格规范（lab-ui.css 设计系统）、模块开发流程，以及数据存储与移植方式。开发新模块前请先通读本文档，确保界面风格与数据规范统一。

1️⃣ 系统概况

系统名称：赵齐实验室管理（中山大学肿瘤防治中心 · 实验室信息管理平台）。
架构：两种运行模式。① 后端模式（多用户）：运行 server.py 后通过 http://127.0.0.1:8000 访问，支持登录与三级角色（管理员/PI/学生），数据统一存于 data/ JSON 文件；② 单机模式（离线）：直接双击 index.html 打开，无需后端，数据存浏览器 localStorage（后端不可达时自动降级）。两种模式数据格式兼容。
页面组成：index.html（系统首页） + login.html（登录页） + server.py（可选轻量后端） + modules/（各功能模块页面，含用户管理） + assets/（共享样式与外壳） + data/（数据文件） + 本文档。

2️⃣ 目录结构

lab-manager/
├── index.html                   系统首页（模块导航卡片）
├── login.html                   登录页（后端模式）
├── server.py                    轻量后端（可选；多用户/权限/集中数据）
├── start.sh                     Linux/macOS 一键启动脚本（bash start.sh）
├── 开发说明.html                 本文档
├── assets/
│   ├── lab-ui.css               统一设计系统（--lm-* 变量 + lm-* 组件类）
│   └── lab-shell.js             共享外壳与工具函数（LAB 命名空间 + MODULES 导航 + 认证/数据层）
├── modules/                     所有模块页面（模块名.html）
│   ├── 组学原始数据管理.html / 人员管理.html / 成果管理.html
│   ├── 科研项目管理.html（含在研看板）/ 代码管理.html
│   ├── 服务器电脑管理.html / 设备管理.html / 公共文件下载.html
│   └── 用户管理.html（管理员专用）
└── data/                        数据文件（后端模式实时读写；单机模式备份用）
    ├── omicsManagerData_v1.json / labPersonnel_v1.json / labAchievements_v1.json
    ├── labProjects_v1.json / labCodes_v1.json / labServers_v1.json
    ├── labEquipment_v1.json / labDownloads_v1.json
    ├── users.json               用户账号（密码为加盐哈希，不外传）
    └── README.txt

3️⃣ 界面风格规范（lab-ui.css 设计系统）

3.1 必须遵守的硬性规则

所有颜色、圆角、阴影必须使用 CSS 变量（--lm-*），禁止硬编码颜色值（如 #fff、rgb()、内联 color:）。
组件类名统一使用 lm- 前缀（lm-card / lm-btn / lm-table / lm-field / lm-modal 等）。
图标统一使用 Emoji，不引入外部图标库；不加载任何网络资源（字体/CDN/图片），可离线运行。
所有动态输出必须经 LAB.esc() 转义，防止 XSS；超链接 href 同样必须转义。
localStorage 读写必须 try/catch，不可用时在页面顶部显示 lm-banner 提示。
删除/清空操作必须 window.confirm 确认；保存后 LAB.toast(msg, 'success') 提示。

3.2 设计变量（--lm-*）

变量	用途
`--lm-primary`	主色（科技蓝），用于主按钮、激活态、强调文字
`--lm-accent`	强调/成功色（绿）
`--lm-warn`	警示色（橙）
`--lm-danger`	危险色（红），用于删除
`--lm-bg / --lm-card / --lm-border / --lm-text-1 / --lm-text-2`	背景、卡片、边框、主/次文字色
`--lm-radius / --lm-shadow / --lm-mono`	圆角、阴影、等宽字体

3.3 组件速查

卡片：lm-card + lm-card-title；页签：lm-tabs + lm-tab active
按钮：lm-btn（primary / accent / danger / mini）；输入：lm-input / lm-select / lm-textarea
表单容器：lm-field + label；按钮行：lm-actions
表格：lm-twrap + lm-table；小型统计表：lm-stat-table；徽标：lm-badge
统计卡：lm-stats + lm-scard；图表卡：lm-charts + lm-chart-card + lm-cb-row/lm-cb-label/lm-cb-track/lm-cb-bar/lm-cb-val
弹窗：lm-mask open + lm-modal；提示：LAB.toast(msg, 'success'|'error'|'warn')
工具栏：lm-toolbar；搜索框：lm-input lm-search；计数标签：lm-note；横幅：lm-banner；预览区：lm-preview-box

4️⃣ 模块开发流程

4.1 页面模板

新模块页面统一放在 lab-manager/modules/ 子文件夹，文件命名 模块名.html；资源引用使用 ../assets/ 相对路径。

<!DOCTYPE html>
<html lang="zh-CN">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>模块名（如 组学原始数据管理）</title>
  <link rel="stylesheet" href="../assets/lab-ui.css?v=v2.0">   <!-- 必须 -->
</head>
<body>
  <div id="lmHeader"></div>
  <nav id="lmNav" class="lm-nav"></nav>
  <main id="lmMain" class="lm-main">
    <!-- 模块内容 -->
  </main>
  <div id="lmFooter" class="lm-footer"></div>
  <script src="../assets/lab-shell.js?v=v2.0"></script>    <!-- 必须 -->
  <script>
    LAB.renderShell('模块id', '模块名');   <!-- 渲染统一外壳 -->
    // …模块逻辑（CRUD + 搜索 + 筛选 + 统计 + 导入导出）…
  </script>
</body>
</html>

4.2 开发步骤

在 modules/ 下创建 模块名.html，按上方模板搭建页面。
调用 LAB.renderShell('模块id', '模块名') 渲染统一头部/导航/页脚（id 需唯一、全小写英文）。
实现功能：增删改查 + 即时搜索 + 筛选 + 统计卡（lm-stats/lm-scard）+ 导出 CSV/备份 JSON + 批量导入（📥 导入数据，支持 .json/.csv/.tsv 与粘贴文本、表头别名映射、替换/追加）+ 示例数据按钮。
数据持久化：localStorage 键命名 lab模块名_v1（如 labPersonnel_v1）；读写 try/catch；同时确保「备份 JSON」可存入 data/ 文件夹、「📂 恢复数据」可整体恢复。
在 assets/lab-shell.js 的 MODULES 表中登记：{ id: '模块id', name: '模块名', href: 'modules/模块名.html', icon: '🌱', group: 'data' }（href 用根相对路径，导航会自动适配子文件夹前缀；group 取 data / share / system 之一，决定导航分组）。
在 data/ 文件夹创建对应的 JSON 数据文件（文件名为 localStorage 键名，内容 []），并在 data/README.txt 补充说明。
语法验证：提取页面内联 <script> 后执行 node --check，确认 exit code 0。

4.3 命名与登记规则

模块名简洁、不带「实验室管理」前缀（如组学原始数据管理、人员管理）。
模块 id 全小写英文唯一（如 omics / personnel / achievements / projects / codes / servers / equipment / downloads / docs）。
共享数据：科研项目管理（labProjects_v1）内含「在研看板」页签，看板与项目管理共用同一份数据；新模块如需读取其他模块数据，直接使用对应键名并在文档中说明。

5️⃣ 数据存储与移植

5.1 数据键 ↔ 数据文件对照表

模块	localStorage 键	data/ 数据文件
组学原始数据管理	`omicsManagerData_v1`	`omicsManagerData_v1.json`
人员管理	`labPersonnel_v1`	`labPersonnel_v1.json`
成果管理	`labAchievements_v1`	`labAchievements_v1.json`
科研项目管理（含在研看板）	`labProjects_v1`	`labProjects_v1.json`
代码管理	`labCodes_v1`	`labCodes_v1.json`
服务器电脑管理	`labServers_v1`	`labServers_v1.json`
设备管理	`labEquipment_v1`	`labEquipment_v1.json`
公共文件下载	`labDownloads_v1`	`labDownloads_v1.json`

5.2 备份与恢复（移植流程）

备份：在每个管理模块中点「💾 备份 JSON」，把下载的 JSON 文件保存到 data/ 文件夹并覆盖对应文件（或点「导出 CSV」备份为表格）。
恢复：在模块中点「📂 恢复数据」，选择 data/ 中对应的 .json 文件，确认后整体替换当前数据；也可用「📥 导入数据」（勾选"替换全部现有数据"）导入 JSON/CSV/TSV。
整体移植：将整个 lab-manager/ 文件夹拷贝到其他电脑即可，数据文件随系统迁移；首次打开新电脑时按第 2 步恢复即可。

5.3 导入格式说明

支持 .json（数组或 {"records":[...]}）、.csv / .tsv（首行为表头，自动识别分隔符与引号转义）、以及直接粘贴文本。
表头支持中文别名与字段名映射（如姓名/name/人员姓名 → name）；必填字段缺失的行自动跳过并计数。
各模块「导出 CSV」表头与导入映射闭环，导出的文件可原样导回。

6️⃣ 多用户与后端模式（v1.6）

6.1 启动后端

cd lab-manager
python server.py                       # 本机访问 http://127.0.0.1:8000
python server.py --host 0.0.0.0 --port 8000   # 局域网内多台电脑访问

Linux / macOS 一键启动：bash start.sh（本机访问）；局域网访问用 HOST=0.0.0.0 bash start.sh；自定义端口 PORT=9000 bash start.sh。脚本自动定位 python3/python，启动后端并尝试打开浏览器，Ctrl+C 停止。

仅依赖 Python 标准库（3.7+），无需安装任何包。首次启动自动在 data/users.json 创建初始账号（固定初始口令，便于记忆）：admin/admin123（管理员）、pi/pi123（PI）、student/student123（学生）。请管理员登录后在「用户管理」中管理账号；如需重置所有账号，删除 data/users.json 后重启即可。

6.2 角色 × 模块权限矩阵（v1.6 可配置）

权限按「角色 × 模块」的读写矩阵控制，矩阵存于 data/permissions.json，管理员可在「用户管理 → 权限设置」中勾选修改，保存后即时生效。默认矩阵：

模块	管理员	PI	学生
组学原始数据管理 / 人员管理 / 成果管理 / 科研项目管理 / 代码管理 / 服务器电脑管理 / 设备管理	读写	读写	只读
公共文件下载（共享文件上传）	读写	读写	读写（可上传）
用户管理 / 权限设置 / 审计日志	全部	无	无

6.3 认证与数据流

前端 lab-shell.js 提供认证层与权限层：LAB.checkAuth()（检测后端并校验登录，未登录跳转 login.html）、LAB.login/logout、LAB.canWrite(模块key) / LAB.canRead(模块key)（按角色×模块矩阵判断，key 省略时按当前页面模块自动派生）、LAB.refreshPerms()（拉取并缓存权限矩阵）、LAB.loadData/saveData（后端数据读写，checkAuth 未完成时自动入队补拉）。
前端按权限自动调整界面：无写权限的模块隐藏「新增/编辑/删除/导入/恢复/清空/示例」按钮；无读权限的模块从导航隐藏；写操作入口仍保留 if (!LAB.canWrite()) {...return;} 守卫（体验层）。
后端强制鉴权（安全由后端保证）：未登录 401；GET /api/data/<key> 校验该角色对 key 的读权限，PUT 校验写权限；/api/users、PUT /api/permissions、GET /api/audit 仅管理员。
API 一览：POST /api/login、POST /api/logout、GET /api/me、GET /api/health、POST /api/password（自助改密）；GET/POST /api/users、PUT/DELETE /api/users/<id>（管理员）；GET/PUT /api/permissions（PUT 管理员）；GET /api/audit（管理员）；GET/PUT /api/data/<key>（按矩阵；key 白名单）。
审计日志：写操作（数据写入、用户增删改、改密、权限变更）自动追加到 data/audit.log（上限 1MB 自动截断），管理员在「用户管理 → 审计日志」查看最近 300 条。

6.4 账号安全（v1.7）

密码修改为自愿操作：登录后直接进入系统；任一登录用户可点击页头「修改密码」自助改密（需验证原密码，页面提供"显示密码"便于核对）。
改密/重置即失效旧会话：自助改密或管理员在「用户管理」中重置密码后，该用户全部会话立即失效，需用新密码重新登录（登录页会显示"密码修改成功，请使用新密码登录"提示）。
管理员重置：管理员可在「用户管理」中重置他人密码（密码至少 6 位）；修改角色后该用户旧会话同样立即失效。
一键启动：Windows 双击 启动实验室系统.bat；Linux/macOS 用 bash start.sh（局域网访问 HOST=0.0.0.0 bash start.sh）；均自动启动后端并打开浏览器。

6.5 安全特性（v1.8）

初始口令：首次启动创建固定初始账号 admin/admin123、pi/pi123、student/student123（内网工具，便于记忆；建议登录后尽快修改）。
登录防暴力破解：同一用户名连续失败 5 次锁定 15 分钟（滑动窗口 10 分钟自动衰减计数），返回 429。
数据文件不提供静态下载：serve_static 对 data/ 目录一律 403，数据只走鉴权 API；server.py 同样禁止下载。
请求体大小上限：超过 8MB 拒绝（防 DoS）。
XSS 双重转义：记录 id 拼进 onclick 时使用 LAB.escJs()（HTML 属性→JS 字符串双重上下文）。
其他：用户名白名单字符校验（防审计日志伪造）；PBKDF2-SHA256 迭代 300000；用户表/权限矩阵按文件 mtime 内存缓存；过期会话守护线程定期清理；数据/权限解析失败与控制台告警而非静默。

7️⃣ 版本记录

v1.0：创建 lab-ui.css 设计系统与 lab-shell.js 共享外壳；上线首模块组学原始数据存储管理。
v1.1：模块化重组——8 个功能模块（含在研项目情况看板）；模块名精简；模块页面统一移入 modules/ 子文件夹；导航支持根相对路径与动态前缀。
v1.2：所有管理模块新增批量导入；新增公共文件下载模块；新增 data/ 数据文件夹与各模块 JSON 数据文件；系统更名为「赵齐实验室管理 · 中山大学肿瘤防治中心」；新增本文档。
v1.3：新增轻量后端 server.py 与登录页 login.html，实现多级用户访问（管理员/PI/学生）；新增用户管理模块（管理员专用）；lab-shell.js 增加认证层与后端数据层（checkAuth/login/logout/loadData/saveData/canWrite）；所有模块接入后端数据同步并支持学生只读守卫；单机离线模式自动降级保留。
v1.4：账号安全——任意用户自助修改密码（change-password.html + POST /api/password）、改密/重置后旧会话立即失效、页头「修改密码」入口；新增一键启动脚本 启动实验室系统.bat；登录页改为多彩渐变背景。
v1.5：移除强制改密环节（登录后直接进入系统，改密为自愿操作），避免浏览器自动填充导致的"新密码无法登录"问题；登录页与改密页新增"显示密码"开关，改密成功提示更清晰。
v1.6：角色权限细分——角色 × 模块读写权限矩阵（管理员可在「用户管理 → 权限设置」勾选配置，存于 data/permissions.json，即时生效）；后端按矩阵精确鉴权（读/写分别校验）；学生默认全部只读、允许在「公共文件下载」上传共享文件；前端按权限隐藏写操作按钮与不可读模块导航；新增审计日志（data/audit.log，写操作自动记录，管理员可查看最近 300 条）。
v1.7：安全与可靠性加固——/data/ 静态下载一律 403；登录失败限流锁定（5 次/15 分钟）；请求体 8MB 上限；用户名白名单校验；PBKDF2 迭代上调至 300000；用户/权限矩阵内存缓存；过期会话定期清理；数据损坏与控制台告警；前端写按钮改用 data-write 属性精确隐藏；记录 id 拼接 onclick 统一 LAB.escJs() 双重转义（XSS 修复）。
v1.8：应使用需求，初始口令恢复为固定值（admin/admin123、pi/pi123、student/student123），便于记忆与日常使用；其余安全加固全部保留。
v1.9：UI 信息架构优化——导航移至右侧边栏（左内容 + 右导航的 Grid 布局，模块按登记顺序平铺，与早期布局一致），窄屏自动折叠为 ☰ 抽屉菜单；头部右侧收敛为用户下拉菜单（头像 + 用户名 ▾ → 个人信息 / 修改密码 / 退出），新增「个人信息」弹窗（含我的模块权限一览）；新增亮/暗主题切换（头部按钮，localStorage 记忆）；首页模块卡片按类别分区展示。
v2.0：按反馈全面重做为极简风格——白色简约头部（品牌居左，右上角仅保留主题切换与用户下拉菜单，去掉与导航重复的模块标签）；顶部横条导航（激活项下划线高亮，窄屏横向滚动）；主内容区铺满（不再限宽居中）；间距与配色全面梳理，消除元素交叠与文字不清问题；首页模块卡片去分类、平铺铺满，顺序按用户指定：人员管理 → 科研项目管理 → 成果管理 → 在研项目情况 → 组学原始数据管理 → 代码管理 → 服务器电脑管理 → 设备管理 → 公共文件下载 → 用户管理；深色模式同步适配。
v2.1：合并「科研项目管理」与「在研项目情况」——独立看板模块移除，看板作为「在研看板」页签并入科研项目管理（页签：在研看板 / 项目管理），看板只读特性（来源分布图、距结束天数、90 天结题预警）与管理 CRUD 在同一页面共存；导航与首页卡片同步移除「在研项目情况」入口；modules/在研项目情况.html 保留为自动跳转页，兼容旧链接。
v2.2：按轻量级建议落地若干小优化——深色模式下「即将到期/过保」高亮行改用 CSS 变量 --lm-warn-bg（原硬编码 #fff3cd），并抽为共享类 lm-row-soon；科研项目、设备表单增加日期联动校验；设备管理新增「保修截止日期」字段与 90 天过保提醒（复用 parseDate 思路）；人员邮箱/电话、服务器 IP 增加格式校验（IP 含重复检测）；成果来源列的 DOI / URL 渲染为可点击链接；系统首页新增「一键备份全部数据」。
v2.3：新增 start.sh Linux/macOS 一键启动脚本（自动定位 python3/python、支持 HOST/PORT 环境变量、启动后尝试打开浏览器），开发说明补充 Linux 启动方式。
v2.4：成果管理增强——支持列排序（年份/标题/期刊/录入顺序）；新增「主要作者」字段（第一/通讯/共同第一作者，含筛选、统计卡、表单、导入导出）；新增「🔍 DOI/PMID 添加」：输入 DOI（Crossref API）或 PMID（NCBI E-utilities）自动拉取标题/作者/年份/期刊并保存；首批 75 篇论文（含 22 篇主要作者）已导入。
v2.5：成果管理调整——移除「示例数据」按钮；新增「影响因子」独立列（数据由 IF2022 提取，68/75 篇有值，平均 13.79，支持表单编辑与导入导出）；列表「备注」列隐藏（数据保留，编辑表单与 CSV 导出仍含备注）。
v2.6：成果管理作者角色化——「主要作者」布尔字段升级为「作者角色」（第一作者/共同第一/通讯作者/共同通讯，可多选组合）；筛选器改为按角色筛选（含"非主要作者"），修复年份/排序对非数字年份的边界问题；数据按作者列表位置 + 源表角色列重新推导（38 篇有角色：第一 6 / 共同第一 16 / 共同通讯 16），导入导出新增「作者角色」列（兼容旧"主要作者=是/否"格式）。
v2.7：论文自动检索——通过 Crossref/OpenAlex API 检索 Qi Zhao（中山大学肿瘤防治中心）2025–2026 年论文，按作者+机构匹配、标题去重后并入成果管理（新增 9 篇，累计 84 篇）；作者角色按作者列表位置推断（首位=第一作者、末位=通讯作者）。
v2.8：成果管理标题按 DOI 渲染为超链接（https://doi.org/）；解析个人简历（docx）中的发表论文列表与成果数据对比查漏补缺——简历 39 篇中 37 篇已在库，补录 2 篇 Cancer Cell（2025 共同通讯 / 2026 共同第一），累计 86 篇。
v2.9：简历中的 6 项授权发明专利录入成果管理（类型=专利，发明人→作者，专利号→来源，授权日期/国别→备注），累计 92 条（86 论文 + 6 专利）。
v2.10：录入获奖（中华医学科技奖一等奖，2024），累计 93 条；后端静态响应增加 Cache-Control: no-cache，解决浏览器缓存旧页面导致前端改动不生效的问题。
v2.11：简历中的 11 项基金项目录入科研项目管理（国家科技重大专项、国自然面上/青年/重点/国际合、广东省自然科学基金、博士后基金、校内培育、人才项目等；含编号、起止时间、经费、状态、角色）。
v2.12：对比实验室官网 seqworld.com 补充数据——人员管理新增 11 名成员（赵齐教授 + 博士后 2 名 + 博士/硕士生 8 名）；代码管理新增 9 个生物信息学工具（VSOLassoBag、MPTevol、MesKit、LncPipe、GPS-SUMO、CrossICC、CaMutQC、BioTreasury、AutoRPA）及 GitHub/官网链接；成果管理新增 17 篇文献（含 PMID/DOI，累计 111 条）。
v2.13：成果模块增加影响因子自动查询功能——后端新增 /api/if-lookup?journal=xxx 接口（内置 80+ 生物医学期刊 2024 JCR 影响因子字典）；前端新增「查询IF」按钮（表单/DOI添加弹窗）、「批量更新IF」按钮；添加 DOI/PMID 时自动查询 IF；104 篇论文全部更新为最新影响因子。