--- title: minus80-freezer canonical_url: "https://www.modelscope.cn/studios/a2068589673/minus80-freezer" md_url: "https://www.modelscope.cn/studios/a2068589673/minus80-freezer.md" repository: a2068589673/minus80-freezer chinese_name: FrostTap last_updated: 2026-10-20 sdk_type: docker sdk_version: 6.29.1 downloads: 0 stars: 2 --- # minus80-freezer > minus80-freezer - a2068589673 在 ModelScope 创建的在线 Demo。实验室 -80℃ 冰箱菌种存取管理系统：NFC 手环定位、搜索、存取记录、数据导入导出 a2068589673/minus80-freezer 是 ModelScope 魔搭社区上的在线可交互 Demo（创空间），基于 docker 6.29.1 构建，中文名为「FrostTap」。 - **Repository**: a2068589673/minus80-freezer - **SDK**: docker - **SDK version**: 6.29.1 - **Downloads**: 0 - **Stars**: 2 - **Last updated**: 2026-10-20 Source: https://www.modelscope.cn/studios/a2068589673/minus80-freezer --- # FrostTap — -80 °C Freezer Sample Manager [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](./LICENSE) [![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue)](./requirements.txt) A cloud-based sample check-in/check-out system for wet-lab teams. An NFC card stuck on the freezer opens the right page with one tap; a 10×10 grid of every rack/box shows where each tube is, and every store/take action is timestamped to an operator and synced to everyone in the lab. **Who it is for:** small biology labs and iGEM teams that keep strain tubes in −80 °C freezers, currently tracking them on paper or in spreadsheets. No programming background is needed to use it — the only client is a phone browser. **What problem it solves:** opening the freezer to hunt for a tube means the door stays open, other samples undergo repeated freeze–thaw cycles, and nobody knows who stored what. FrostTap compresses the whole flow to one NFC tap: *store* shows only empty wells, *find* locates a tube by keyword/filter and registers its checkout in one tap. > 中文说明见文末 [Chinese section](#中文说明)。 --- ## Features - **Physical, zero-training entry** — five stateless URL views (`/`, `?view=store`, `?view=search`, `?view=tap`, `?view=write`); writing a URL onto an NTAG213/215 NFC card makes any fridge surface an entry point. Default is one card that opens a checkout/store chooser; two cards (direct-to-store, direct-to-find) can be selected in Settings. - **Rack → box → 10×10 well** model, custom tube types, 8 cap colors, occupancy/month/strain/plasmid/keeper/type/cap colorings, search highlight. - **Realtime collaboration without conflicts** — the whole lab database is a single JSON document with a revision number (`rev`). The client keeps a synced-snapshot/local/remote triple and performs entity-level three-way merges keyed on millisecond mtimes; a 3-second lightweight poll pulls only the revision number, so simultaneous edits by two people both survive. - **Multi-lab physical isolation** — a `registry.db` manages lab accounts, session tokens and NFC entry keys; each lab has its own `freezer.db` and can never see another lab's data. - **Passwordless NFC entry key** — the card stores a random 24-char entry key (not the lab password); keys can be revoked/rotated, which invalidates a lost card. - **Auditability** — per-tube and lab-wide activity logs (operator, second-level timestamp, location, field-level diff); last 200 JSON snapshots kept in `data/backups/`; JSON export/import in merge or overwrite mode. - **Batch onboarding** — multi-sheet `.xlsx` creates whole boxes (openpyxl, with a standard-library fallback parser); empty boxes/racks supported. - **Full Chinese/English UI** (runtime dictionary, one codebase), dark/light theme, mobile-first responsive layout, feedback form + engineer console. ## Architecture ``` Phone browser FastAPI backend (app.py) Persistent disk ───────────── ──────────────────────── ─────────────── NFC card tap ──URL──▶ /?view=store|search|tap|write PC / phone ────────▶ / (console, single-file SPA) static/index.html (one file, no build) 3 s poll ──GET /api/rev──▶ registry.db (labs, tokens, entry keys, full doc ──GET/PUT /api/db feedback) 409 conflict → client-side data/labs//freezer.db three-way merge, auto-retry data/labs//backups/*.json FREEZER_DATA env var ``` - **Backend:** one-file FastAPI app + SQLite. The server stays deliberately simple — it stores the whole-lab JSON document and one revision counter; merge intelligence lives in the client. - **Frontend:** one hand-written `static/index.html` (~700 i18n entries, no framework, no build step), served as a static file. Local-only state (operator profile, language, card mode) lives in `localStorage`; shared lab state lives in the cloud. - **Data portability:** every backup is plain UTF-8 JSON (standard open format), and taxonomic/operator text is free-form — no proprietary database or export step is needed to reuse the data. - **Auth:** custom header `X-Lab-Token` (some hosting gateways strip `Authorization: Bearer`); sessions also bind to the client IP, so a device on the same network re-enters its lab directly. ## Quick start (local / lab computer) Prerequisites: **Python 3.10+** (tested on 3.13) and a modern browser. ```bash pip install -r requirements.txt # exact tested versions, pinned python -m uvicorn app:app --host 0.0.0.0 --port 8000 # Windows users can instead double-click start.bat; Linux/macOS: ./start.sh ``` Open on the computer; connect a phone to the same Wi-Fi and open `http://:8000`. On first launch create a lab on the gate page (lab name + password ≥ 4 chars). **Verify the install:** ```bash curl http://127.0.0.1:8000/api/health # {"ok":true,"labs":0} ``` **Reproduce the main results** (the check-in/check-out loop): open the console → create a rack/box (or batch-import an `.xlsx`) → tap an empty well, fill strain/plasmid/keeper/date, save → use `?view=search` to find it by keyword → "Take this tube out"; the well flips to the temporary-out state, a checkout record appears, and a second browser session polling every 3 s shows both changes automatically. ## NFC cards 1. Open `http:///?view=write` in **Android Chrome/Edge (89+) over HTTPS** to write cards directly in the browser; on iPhone or desktops copy the URL into the NFC Tools app (NTAG213/215). 2. Default: write one `?view=tap` card. In Settings you may switch to two cards and write the direct store/find URLs instead. 3. Generate an **entry key** in Settings; the write URL then carries `?bk=…`, so tapping a card logs in without typing the lab password. Revoke or rotate the key to invalidate a lost card. When the write page is opened on `localhost`/a LAN address it automatically substitutes the configured public base URL, so a local address is never burned onto a card. ## Deployment The app is a plain ASGI app; set `FREEZER_DATA` to a persistent volume so SQLite survives container rebuilds. - **ModelScope Studio (current production, China-direct):** `https://a2068589673-minus80-freezer.ms.show/` — data volume `/mnt/workspace/freezer-data`. - **Railway (standby):** mount `/data`, set `FREEZER_DATA=/data`. - Self-hosting: any `uvicorn`/Docker target works; the repository contains `start.sh`, `start.bat`, and `requirements.txt` only needed to reproduce. Optional environment variables: `ENGINEER_PASS` (engineer-console password, default `daylab2026` — change it); `SMTP_USER` / `SMTP_PASS` (and optional `SMTP_HOST` / `SMTP_PORT` / `SMTP_FROM`) for the daily feedback-notification digest; SMTP absence never blocks feedback submission. ## Project layout ``` app.py # FastAPI app: labs/auth, /api/rev, /api/db, parse-excel, # search history, feedback/engineer API, backups static/index.html # entire frontend (views, i18n, merge engine, NFC page) requirements.txt # pinned dependency lockfile start.bat / start.sh # one-click local launchers (create venv + install + run) data/ # created at runtime: registry.db, labs//freezer.db + backups/ ``` Older standalone iterations are kept under `iterations/` (v1 desktop grid, v2 mobile single-device search, v3 this cloud + NFC codebase); the codebase has evolved inside the v3 directory through the current multi-lab/realtime generation. ## Documentation - User-facing changelog: Settings → "What's new" inside the app. - Full development history (Chinese): `修改记录.md` in the upstream working repository. ## License [MIT](./LICENSE) © 2026 Daylab iGEM Team. --- ## 中文说明 **FrostTap（-80℃ 冰箱菌种管理台）** 是面向湿实验团队的云端菌种存取登记系统： NFC 卡片贴在冰箱上，手机碰一下直达存菌或取菌页面；铁架 → 冻存盒 → 10×10 孔位的格子图记录每一管菌，每次存取都自动记录操作人和时间，全实验室 云端实时同步。 **安装运行**：Python 3.10+（在 3.13 上测试），`pip install -r requirements.txt` （依赖已按测试环境精确锁定）→ `python -m uvicorn app:app --host 0.0.0.0 --port 8000`（Windows 双击 `start.bat`，Linux/macOS 运行 `./start.sh`）→ 浏览器打开 `http://127.0.0.1:8000`，首次使用在门禁页创建实验室。 访问 `/api/health` 返回 `{"ok":true,...}` 即成功。 **核心能力**：碰卡片存取（默认一张卡片，可在设置切两张）；多实验室数据库 物理隔离；rev 乐观并发 + 客户端实体级三路自动合并（3 秒静默同步，两人同改 互不丢数据）；24 位进门码免密碰卡、可挂失；自动快照备份（最近 200 份 JSON）； 多 Sheet Excel 批量建盒；全库审计日志；问题反馈与工程师后台；中英双语界面、 深色模式、手机端适配。 **部署**：生产环境为 ModelScope 创空间（国内直连，数据盘 `/mnt/workspace/freezer-data`），Railway 为备用（挂载 `/data`）；任意平台 通过环境变量 `FREEZER_DATA` 指定持久化数据库目录即可。