Hab-bah/VitalisX

# 🏥 VitalisX — Stellar 上的去中心化患者健康记录 [](LICENSE) [](https://stellar.org) [](https://soroban.stellar.org) [](https://pnpm.io/workspaces) ## 📌 目录 - [概述](#overview) - [问题陈述](#problem-statement) - [为何选择 Stellar](#why-stellar) - [功能特性](#features) - [Monorepo 结构](#monorepo-structure) - [架构](#architecture) - [智能合约 (Soroban)](#smart-contracts-soroban) - [应用](#apps) - [Web 应用 (前端)](#web-app-frontend) - [API / 后端](#api--backend) - [移动应用](#mobile-app) - [包 (Packages)](#packages) - [快速入门](#getting-started) - [环境变量](#environment-variables) - [数据库 Schema](#database-schema) - [同意与隐私模型](#consent--privacy-model) - [代币经济学与激励](#tokenomics--incentives) - [路线图](#roadmap) - [贡献指南](#contributing) - [许可证](#license) ## 概述 **VitalisX** 是一个建立在 **Stellar 区块链**之上、使用 **Soroban 智能合约**的去中心化、隐私优先的电子健康记录 (EHR) 平台。它使医疗专业人员——医生、护士、药剂师和医院——能够以安全、防篡改和可审计的方式记录、检索和共享患者病史。 与传统上局限于单个医院的 EHR 系统不同，VitalisX 创建了一个**统一的、以患者为中心的健康图谱**，患者拥有自己的数据，并授予医疗提供者时间范围和角色范围的访问权限——所有这一切都在链上强制执行。 该项目是面向全球卫生部门的开源公共产品。 ## 问题陈述 全球医疗系统面临以下问题： - **记录碎片化**——患者病史分散在多家医院，无法互操作 - **患者无数据主权**——患者无法控制谁访问其记录 - **篡改风险**——存储在中心化数据库中的记录可以在没有审计跟踪的情况下被更改 - **紧急情况下访问延迟**——转院的患者没有可用记录 - **重复用药**——没有统一的处方历史，危险的药物相互作用难以被发现 - **账单不透明**——患者无法核实哪些操作被计费 VitalisX 利用 Stellar 快速、低成本、可编程的区块链基础设施解决了上述每一个问题。 ## 为何选择 Stellar VitalisX 特别选择 **Stellar 区块链**，原因如下： - **交易吞吐量**——5秒终局性，约4,000 TPS，非常适合高频医疗记录条目 - **低费用**——低于1美分的交易成本，使得微交互（例如，记录生命体征检查）在经济上可行 - **Soroban 智能合约**——基于 Rust、可审计、确定性的合约执行，用于同意和访问控制 - **USDC / 稳定币支持**——可在同一条链上原生实现医疗支付结算 - **Stellar Quest 生态系统**——成熟的开发者工具和资助基础设施 - **能源效率**——SCP 共识（非工作量证明），对公共产品应用环境友好 ## 功能特性 ### 🔐 核心医疗功能 - **患者健康记录 (PHR)** — 创建和维护结构化的病史、诊断、治疗和结果 - **多方访问** — 医生、护士、药剂师、实验室和专家各自拥有适合其角色的视图 - **紧急访问模式** — 患者可以为昏迷/紧急情况生成时间限制的紧急二维码 - **用药史与相互作用检查器** — 完整的处方账本，带有链上药物相互作用标记 - **实验室结果与影像链接** — 通过 IPFS 链接的诊断结果，附加到链上记录哈希 - **过敏注册表** — 跨提供者的不可变过敏和不良反应记录 - **疫苗接种账本** — 可验证的疫苗接种历史，可用于旅行、学校和就业核实 - **转诊管理** — 链上专家转诊请求及状态跟踪 ### 🔑 同意与隐私 - **患者控制的同意** — 患者通过链上交易授予/撤销对特定提供者的访问权限 - **精细的同意范围** — 同意可以限于特定记录类别（例如，“这位心脏病专家只能查看心脏记录”） - **有时间限制的访问** — 所有同意授予都有由 Soroban 合约强制执行的过期时间戳 - **同意审计跟踪** — 每个访问事件都记录在链上，提供患者可以审查的完整审计日志 - **数据加密** — 所有链下记录内容都使用患者派生的密钥加密；仅将哈希/元数据上链 ### 💊 临床决策支持 - **药物相互作用警报** — 使用嵌入式药物数据库进行实时药物交叉检查 - **慢性病标志** — 在录入期间自动高亮显示患有慢性病的患者 - **重复处方检测** — 防止不同提供者开具重复处方 - **AI驱动的症状摘要器** — 将患者多年病史总结为简明的临床快照，供新提供者使用 ### 💳 医疗财务 (链上) - **医疗账单账本** — 透明、逐项列示的账单记录，链接到治疗条目 - **保险理赔锚定** — 账单哈希锚定在 Stellar 上，用于争议解决 - **微支付结算** — 患者与提供者之间的直接稳定币 (USDC) 用于支付咨询费用 - **药品供应链** — 从制造商到配药事件的药物来源追踪 ### 🏥 机构功能 - **多设施网络** — 医院、诊所和实验室加入一个具有链上证明的许可网络 - **员工资质认证** — 医疗专业人员执照作为可验证的凭证存储在 Stellar 上 - **分析仪表板** — 按地区、疾病和人口统计聚合（匿名）的公共健康趋势 - **预约调度** — 链上预约预订，使用代币化时段 NFT（通过 Soroban 强制执行失约惩罚） ## Monorepo 结构 ``` vitalisx/ ├── apps/ │ ├── web/ # Next.js 14 web application (healthcare professionals + patients) │ ├── api/ # NestJS REST & GraphQL API server │ ├── mobile/ # React Native patient-facing mobile app │ └── admin/ # Internal admin dashboard (facility onboarding, analytics) │ ├── contracts/ │ ├── patient-registry/ # Soroban: Patient identity and record root registration │ ├── consent-manager/ # Soroban: Consent grants, revocations, access control │ ├── record-anchor/ # Soroban: Record hash anchoring and integrity verification │ ├── credential-vault/ # Soroban: Healthcare professional credential attestation │ ├── billing-ledger/ # Soroban: Transparent medical billing and claim anchoring │ └── appointment-token/ # Soroban: Tokenized appointment slots │ ├── packages/ │ ├── ui/ # Shared component library (Radix UI + Tailwind) │ ├── stellar-sdk-utils/ # Stellar/Soroban client abstractions and helpers │ ├── crypto/ # Patient key derivation, encryption/decryption utilities │ ├── drug-db/ # Embedded drug interaction database (RxNorm-compatible) │ ├── types/ # Shared TypeScript types across apps │ ├── config/ # Shared ESLint, Prettier, TypeScript configs │ └── validators/ # Zod schemas for clinical data structures │ ├── docs/ # Architecture docs, ADRs, API reference ├── scripts/ # Deployment scripts, contract migration tools ├── docker-compose.yml # Local development environment ├── pnpm-workspace.yaml ├── turbo.json └── README.md ``` ## 架构 ``` ┌──────────────────────────────────────────────────────────────────┐ │ CLIENT LAYER │ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────────────┐ │ │ │ Web App │ │ Mobile App │ │ Admin Dashboard │ │ │ │ (Next.js 14) │ │(React Native)│ │ (Next.js 14) │ │ │ └──────┬───────┘ └──────┬───────┘ └──────────┬───────────┘ │ └──────────┼─────────────────┼─────────────────────┼──────────────┘ │ │ │ └────────────────►│◄──────────────────────┘ ▼ ┌──────────────────────────────────────────────────────────────────┐ │ API LAYER │ │ NestJS — REST + GraphQL + WebSocket │ │ Auth (Stellar wallet), RBAC, Rate limiting │ │ Supabase (PostgreSQL) ── IPFS/Filebase (encrypted files) │ └──────────────────────┬───────────────────────────────────────────┘ │ ┌────────────┼────────────┐ ▼ ▼ ▼ ┌─────────────────────────────────────────────────────────────────┐ │ STELLAR BLOCKCHAIN LAYER │ │ │ │ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │ │ │ patient-registry│ │ consent-manager │ │ record-anchor │ │ │ │ (Soroban) │ │ (Soroban) │ │ (Soroban) │ │ │ └─────────────────┘ └─────────────────┘ └─────────────────┘ │ │ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │ │ │credential-vault │ │ billing-ledger │ │ appt-token │ │ │ │ (Soroban) │ │ (Soroban) │ │ (Soroban) │ │ │ └─────────────────┘ └─────────────────┘ └─────────────────┘ │ └─────────────────────────────────────────────────────────────────┘ ``` **记录创建的数据流：** 1. 医疗专业人员通过其 Stellar 钱包 (Freighter / Lobstr) 进行身份验证 2. API 通过 `credential-vault` 合约验证其凭证 3. 记录在客户端使用患者派生的对称密钥进行加密 4. 加密后的数据块上传到 IPFS；返回内容哈希 5. API 调用 `record-anchor` 合约，将 `(patient_id, provider_id, ipfs_hash, record_type, timestamp)` 存储在链上 6. 在任何读取操作之前，`consent-manager` 中会执行同意检查 ## 智能合约 (Soroban) 所有合约均使用 **Rust** 编写，面向 Soroban (Stellar 的智能合约平台)。 ### `patient-registry` 管理患者身份注册及其记录根。 ``` pub trait PatientRegistry { fn register_patient(env: Env, patient_stellar_id: Address, metadata_hash: BytesN<32>) -> Result; fn get_patient(env: Env, patient_id: u64) -> Result; fn update_metadata(env: Env, patient_id: u64, new_hash: BytesN<32>) -> Result<(), Error>; fn deactivate_patient(env: Env, patient_id: u64) -> Result<(), Error>; } ``` ### `consent-manager` 核心隐私执行——每次记录读取都通过此合约。 ``` pub trait ConsentManager { fn grant_consent(env: Env, patient_id: u64, provider_address: Address, scope: ConsentScope, expires_at: u64) -> Result; fn revoke_consent(env: Env, patient_id: u64, consent_id: ConsentId) -> Result<(), Error>; fn check_access(env: Env, patient_id: u64, provider_address: Address, record_type: RecordType) -> Result; fn list_active_consents(env: Env, patient_id: u64) -> Vec; fn list_access_log(env: Env, patient_id: u64, limit: u32) -> Vec; } ``` ### `record-anchor` 记录哈希的不可变锚定——记录完整性的唯一事实来源。 ``` pub trait RecordAnchor { fn anchor_record(env: Env, patient_id: u64, provider_id: u64, ipfs_hash: String, record_type: RecordType) -> Result; fn verify_record(env: Env, record_id: RecordId, ipfs_hash: String) -> bool; fn get_record_chain(env: Env, patient_id: u64, record_type: Option) -> Vec; fn flag_record(env: Env, record_id: RecordId, reason: String) -> Result<(), Error>; } ``` ### `credential-vault` 医疗专业人员的可验证凭证。 ``` pub trait CredentialVault { fn issue_credential(env: Env, professional_address: Address, credential_type: CredentialType, issuer: Address, expiry: u64) -> Result; fn verify_credential(env: Env, professional_address: Address, required_type: CredentialType) -> bool; fn revoke_credential(env: Env, credential_id: CredentialId) -> Result<(), Error>; } ``` ### `billing-ledger` 透明的链上医疗计费。 ``` pub trait BillingLedger { fn create_bill(env: Env, patient_id: u64, provider_id: u64, line_items: Vec) -> Result; fn anchor_claim(env: Env, bill_id: BillId, insurer_address: Address) -> Result; fn settle_payment(env: Env, bill_id: BillId, amount: i128, token: Address) -> Result<(), Error>; fn dispute_bill(env: Env, bill_id: BillId, reason: String) -> Result; } ``` ## 应用 ### Web 应用 (前端) **路径:** `apps/web` **技术栈:** Next.js 14, TypeScript, Tailwind CSS, Radix UI, SWR, Stellar Freighter 钱包 **关键界面:** - `/dashboard` — 提供者主页，显示近期患者和待处理任务 - `/patients` — 患者搜索和注册 - `/patients/[id]` — 完整的患者健康时间线 - `/patients/[id]/records/new` — 结构化记录录入表单（诊断、治疗、处方） - `/consent` — 患者同意管理门户 - `/prescriptions` — 处方签，附带药物相互作用检查器 - `/labs` — 实验室结果上传和 IPFS 链接 - `/billing` — 账单创建和理赔锚定 - `/credentials` — 提供者执照管理 ``` cd apps/web pnpm dev # http://localhost:3000 pnpm build pnpm lint ``` ### API / 后端 **路径:** `apps/api` **技术栈:** NestJS, TypeScript, Prisma ORM, PostgreSQL (Supabase), GraphQL (Apollo), Stellar SDK **模块概述:** ``` src/ ├── auth/ # Stellar wallet authentication (SEP-10) ├── patients/ # Patient CRUD and record management ├── records/ # Record encryption, IPFS upload, on-chain anchoring ├── consent/ # Consent grant/revoke + access checking middleware ├── prescriptions/ # Medication management + drug interaction checks ├── billing/ # Bill creation and on-chain claim anchoring ├── labs/ # Lab result management and IPFS linking ├── appointments/ # Appointment scheduling + Soroban token management ├── credentials/ # Healthcare professional credential verification ├── analytics/ # Aggregate anonymized public health data └── stellar/ # Soroban contract interaction services ``` ``` cd apps/api pnpm dev # http://localhost:4000 pnpm db:migrate pnpm db:seed ``` ### 移动应用 **路径:** `apps/mobile` **技术栈:** React Native (Expo), TypeScript **目标用户:** 患者 **关键功能:** - 查看个人健康时间线 - 管理同意授权（授予/撤销提供者访问权限） - 查看处方和疫苗接种记录 - 生成紧急二维码 - 接收预约提醒 - 通过二维码扫描安全地将记录共享给新提供者 ``` cd apps/mobile pnpm start # Expo dev server pnpm android pnpm ios ``` ## 包 (Packages) ### `packages/ui` 所有应用共享的组件库。 ``` pnpm --filter @vitalisx/ui build ``` 关键组件: ``, ``, ``, ``, ``, ``, ``, `` ### `packages/stellar-sdk-utils` 对 Stellar JS SDK 和 Soroban 合约调用的抽象。 ``` import { invokeContract, signAndSubmit, buildConsentGrant } from '@vitalisx/stellar-sdk-utils'; const result = await invokeContract({ contractId: CONSENT_MANAGER_CONTRACT_ID, method: 'grant_consent', args: [patientId, providerAddress, scope, expiresAt], wallet: freighterWallet, }); ``` ### `packages/crypto` 患者派生的密钥管理和记录加密/解密。 ``` import { derivePatientKey, encryptRecord, decryptRecord } from '@vitalisx/crypto'; // Derive a symmetric key from the patient's Stellar keypair const key = await derivePatientKey(patientStellarPublicKey); // Encrypt before IPFS upload const { ciphertext, iv } = await encryptRecord(key, recordPayload); // Decrypt after retrieval const plaintext = await decryptRecord(key, ciphertext, iv); ``` ### `packages/drug-db` 嵌入式、支持离线的药物相互作用数据库（兼容 RxNorm）。 ``` import { checkInteractions, getDrugInfo } from '@vitalisx/drug-db'; const interactions = await checkInteractions(['warfarin', 'aspirin', 'ibuprofen']); // Returns: [{ drugs: ['warfarin', 'ibuprofen'], severity: 'HIGH', description: '...' }] ``` ### `packages/validators` 所有临床数据结构的 Zod schema，在前端和后端共享。 ``` import { DiagnosisSchema, PrescriptionSchema, PatientRegistrationSchema } from '@vitalisx/validators'; const parsed = DiagnosisSchema.parse(formData); // throws on invalid clinical data ``` ## 快速入门 ### 前置条件 - Node.js >= 20 - pnpm >= 9 - Docker & Docker Compose - Rust (用于 Soroban 合约开发) - Stellar CLI: `cargo install --locked stellar-cli` - 一个 [Freighter 钱包](https://www.freighter.app/) 用于本地测试 ### 安装 ``` # 克隆仓库 git clone https://github.com/your-org/vitalisx.git cd vitalisx # 安装所有依赖 pnpm install # 启动本地基础设施（PostgreSQL, Redis） docker-compose up -d # 复制环境文件 cp apps/api/.env.example apps/api/.env cp apps/web/.env.example apps/web/.env ``` ### 构建并部署 Soroban 合约 ``` # 构建所有合约 cd contracts/patient-registry cargo build --target wasm32-unknown-unknown --release # 部署到 Stellar 测试网 stellar contract deploy \ --wasm target/wasm32-unknown-unknown/release/patient_registry.wasm \ --source-account your-secret-key \ --network testnet # 初始化合约 stellar contract invoke \ --id \ --source-account your-secret-key \ --network testnet \ -- initialize \ --admin your-public-key ``` 对 `contracts/` 目录中的所有合约重复此步骤。将生成的合约 ID 存储在你的 `.env` 文件中。 ### 运行完整技术栈 ``` # 从 monorepo 根目录 pnpm dev # Starts all apps in parallel via Turborepo # 或单独操作 pnpm --filter @vitalisx/web dev pnpm --filter @vitalisx/api dev ``` ### 运行测试 ``` pnpm test # All packages and apps pnpm --filter @vitalisx/api test # API tests only # Soroban 合约测试 cd contracts/consent-manager cargo test ``` ## 环境变量 ### `apps/api/.env` ``` # 数据库 DATABASE_URL=postgresql://vitalisx:password@localhost:5432/vitalisx # Stellar STELLAR_NETWORK=testnet STELLAR_HORIZON_URL=https://horizon-testnet.stellar.org STELLAR_RPC_URL=https://soroban-testnet.stellar.org # 合约 ID（来自部署） PATIENT_REGISTRY_CONTRACT_ID=C... CONSENT_MANAGER_CONTRACT_ID=C... RECORD_ANCHOR_CONTRACT_ID=C... CREDENTIAL_VAULT_CONTRACT_ID=C... BILLING_LEDGER_CONTRACT_ID=C... APPOINTMENT_TOKEN_CONTRACT_ID=C... # IPFS（Filebase 或 Pinata） IPFS_GATEWAY=https://ipfs.filebase.io/ipfs IPFS_API_KEY=your_api_key IPFS_SECRET=your_secret # 应用程序 JWT_SECRET=your_jwt_secret API_PORT=4000 ``` ### `apps/web/.env.local` ``` NEXT_PUBLIC_API_URL=http://localhost:4000 NEXT_PUBLIC_STELLAR_NETWORK=testnet NEXT_PUBLIC_PATIENT_REGISTRY_CONTRACT_ID=C... NEXT_PUBLIC_CONSENT_MANAGER_CONTRACT_ID=C... NEXT_PUBLIC_RECORD_ANCHOR_CONTRACT_ID=C... ``` ## 数据库 Schema 链下 PostgreSQL 数据库（通过 Prisma 管理）镜像并索引链上状态，以实现快速查询。 ``` model Patient { id String @id @default(cuid()) stellarAddress String @unique patientChainId BigInt @unique // on-chain patient_id dateOfBirth DateTime bloodType String? createdAt DateTime @default(now()) records HealthRecord[] consents ConsentGrant[] prescriptions Prescription[] appointments Appointment[] bills Bill[] } model HealthRecord { id String @id @default(cuid()) patientId String providerId String recordType RecordType ipfsHash String chainRecordId BigInt // on-chain record_id for verification anchoredAt DateTime metadata Json? patient Patient @relation(fields: [patientId], references: [id]) provider Provider @relation(fields: [providerId], references: [id]) } model ConsentGrant { id String @id @default(cuid()) patientId String providerAddress String scope ConsentScope[] expiresAt DateTime chainConsentId BigInt revokedAt DateTime? patient Patient @relation(fields: [patientId], references: [id]) } model Provider { id String @id @default(cuid()) stellarAddress String @unique name String role ProviderRole facility String licenseHash String? // on-chain credential hash licenseExpiry DateTime? records HealthRecord[] } model Prescription { id String @id @default(cuid()) patientId String providerId String drugName String dosage String frequency String startDate DateTime endDate DateTime? status PrescriptionStatus patient Patient @relation(fields: [patientId], references: [id]) } ``` ## 同意与隐私模型 VitalisX 实施**零信任访问控制**模型，其中**没有患者的链上明确同意，任何数据访问都是不可能的**。 ### 同意范围 | 范围 | 描述 | |---|---| | `FULL` | 访问所有记录类别 | | `DIAGNOSIS` | 仅限诊断和病史 | | `MEDICATIONS` | 仅限处方历史 | | `LABS` | 仅限实验室结果和影像 | | `VITALS` | 仅限生命体征历史 | | `BILLING` | 仅限账单记录 | | `EMERGENCY` | 紧急访问（由患者二维码自动授予） | ### 访问流程 ``` Provider requests record │ ▼ consent-manager.check_access() │ ┌─────┴──────┐ │ │ GRANTED DENIED │ │ ▼ ▼ Decrypt & Return 403 return data │ │ Log attempt ▼ on-chain Log access on-chain ``` ### 紧急访问 患者可以生成一个时间有限（例如 2 小时）的紧急访问令牌，任何提供者都可以扫描它。这会在链上创建一个临时的 `EMERGENCY` 同意，并带有硬性到期时间，之后访问权限将被合约自动撤销。 ## 代币经济学与激励 VitalisX 使用 Stellar 的原生资产功能来实现激励对齐： - **VITX 代币（自定义 Stellar 资产）** — 颁发给提供者以奖励高质量数据录入，用于平台治理 - **USDC 支付** — 患者与提供者之间的直接微支付用于支付咨询费用，在 Stellar 上结算 - **数据质量质押** — 提供者质押 VITX 代币；不准确或欺诈的记录会削减其质押 - **研究数据赏金** — 匿名、聚合的健康数据可以（在患者同意下）贡献给研究机构，以换取支付给参与患者的 USDC 奖励 ## 路线图 ### 第一阶段 — 基础 (当前) - [x] Monorepo 结构和工具 - [x] Soroban 合约脚手架 (patient-registry, consent-manager, record-anchor) - [ ] 核心 API (患者、记录、同意) - [ ] Web 应用：提供者仪表板和记录录入 - [ ] 测试网部署 ### 第二阶段 — 临床功能 - [ ] 药物相互作用检查器集成 - [ ] 实验室结果 + IPFS 链接 - [ ] 处方管理 - [ ] 移动应用（面向患者） - [ ] 紧急二维码系统 ### 第三阶段 — 财务与资质 - [ ] 账单账本合约 - [ ] USDC 支付结算 - [ ] 用于提供者执照的凭证保管库 - [ ] 预约代币化 ### 第四阶段 — 网络与分析 - [ ] 多设施网络（医院加入） - [ ] 匿名公共健康分析仪表板 - [ ] VITX 代币发行和治理 - [ ] 研究数据赏金市场 - [ ] 主网部署 ## 贡献指南 我们欢迎医疗专业人员、区块链开发者以及任何关心健康数据主权的人士的贡献。 1. Fork 仓库 2. 创建一个功能分支：`git checkout -b feat/your-feature` 3. 按照[贡献指南](docs/CONTRIBUTING.md)进行更改 4. 确保所有测试通过：`pnpm test` 5. 提交拉取请求 查看标记为 `good first issue` 的开放议题作为入门点。 ### 开发指南 - 所有 Soroban 合约必须有 90% 以上的测试覆盖率 - 所有 API 端点必须包含 OpenAPI 文档 - 患者数据在代码库中的任何地方都不得以明文记录 - 所有涉及同意逻辑的 PR 都需要进行安全审查 ## 许可证 MIT — 完整条款请参见 [LICENSE](LICENSE)。 ## 致谢 作为全球医疗基础设施的开源公共产品，构建在 Stellar 区块链之上。 *VitalisX — 因为您的健康历史应属于您自己。*

标签：DNS解析, Soroban, Stellar, 健康记录系统, 全球健康, 区块链, 区块链技术, 医疗专业工具, 医疗信息化, 医疗健康, 去中心化, 去中心化应用, 可审计, 开源项目, 患者数据管理, 数据共享, 智能合约, 测试用例, 电子健康记录, 网络安全, 隐私优先, 隐私保护