璇玑云库  ·  TalosArk

生物样本储存管理系统 — 树形节点 · 试剂位置追踪 · 多组织协作

---

璇玑云库（TalosArk） 是一套面向实验室场景的生物样本储存管理系统，用于管理冰箱、储存柜、样本盒等层级结构，追踪试剂在具体位置槽的存入/取出记录，并支持多组织协作与权限隔离。

项目以 pnpm monorepo 组织，包含后端服务、客户端和文档站三个工作区。

Warning

当前处于积极开发阶段（0.x）

所有接口契约、数据模型和目录结构在版本间可能发生较大变动，不保证向后兼容。

仓库结构

Talos-Ark/
├── apps/
│   ├── backend/     # NestJS 后端服务（API + 数据库）
│   ├── frontend/    # Tauri 桌面客户端（Vue 3 + Rust 壳层）
│   └── docsite/     # VitePress 文档站
└── docs/            # Monorepo 级规划文档

工作区概览

工作区	技术栈	职责
apps/backend	NestJS · Prisma · PostgreSQL · Zod	REST API、认证、业务逻辑、数据持久化
apps/frontend	Tauri · Vue 3 · Pinia · Alova · shadcn-vue · Tailwind	跨平台桌面客户端（Tauri 壳层 + Vue 3 渲染器）
apps/docsite	VitePress · Nginx	项目文档站、OpenAPI 参考文档

核心功能

功能	说明
🌲 树形节点管理	ROOT → CONTAINER → BOX → BOX_SLOT 四级层次，支持任意深度嵌套
📍 网格位置系统	为 BOX 节点配置行列网格，每个槽位（BOX_SLOT）精确追踪试剂位置
🧪 试剂全生命周期	存入、取出、移动、更新记录，附带操作日志与责任人归属
🏷️ 试剂类型管理	可配置试剂类别（颜色、单位、描述），关联至具体试剂
🏢 多组织协作	组织级数据隔离，支持成员角色（OWNER / ADMIN / MEMBER）与资源共享
✉️ 邮箱验证	注册与安全操作的邮箱验证码流程

快速开始

前置要求

• Node.js ≥ 22
• pnpm ≥ 11
• PostgreSQL ≥ 18

安装与启动

# 安装依赖
pnpm install -r

pnpm --filter @talos-ark/backend db:gen-client

# 后端（热重载，:3000）
pnpm --filter @talos-ark/backend start:dev

# 前端（:8081）
pnpm --filter @talos-ark/frontend vite

常用命令

# 格式化（全工作区）
pnpm format

# 数据库迁移 / 重新生成 Prisma Client
pnpm --filter @talos-ark/backend db:migrate
pnpm --filter @talos-ark/backend db:gen-client

# 类型检查 & 单元测试
pnpm --filter @talos-ark/frontend type-check
pnpm --filter @talos-ark/backend test
pnpm --filter @talos-ark/frontend test

# E2E 测试
pnpm --filter @talos-ark/frontend test:e2e

文档

• 后端文档 — 架构设计、API 规范、开发指南
• 后端 AGENTS.md — AI 协作操作手册
• 前端 AGENTS.md — 前端 AI 协作操作手册

License

本项目基于 GNU Affero General Public License v3.0 开源。