AIclinicalresearch/docs/03-业务模块/INST-机构管理端/00-模块当前状态与开发指南.md

INST-机构管理端 - 模块当前状态与开发指南

最后更新： 2026-01-11
状态： 🔴 未开始（等待运营管理端完成）
版本： v0.0 (Planning)

---

🎯 一句话总结

机构管理端为医院和药企客户提供自服务管理界面，让机构管理员能够独立管理用户、配额、科室/项目等资源。

---

📊 当前开发状态

✅ 已完成

• 无（尚未开始）

🚧 进行中

• 无

⏳ 待开发（依赖运营管理端）

前置条件（必须先完成）：

• 运营管理端基础架构（Phase 0-2）
• 租户管理功能
• 租户专属登录页
• 品牌定制配置

机构管理端开发计划（预计Week 5+）：

P1 - 医院管理端（Week 5-6）

• 用户管理（CRUD + 科室分配）
• 科室管理（支持多级结构）
• 配额分配（科室/个人）
• 审计日志查询

P1 - 药企管理端（Week 7-8）

• 用户管理（CRUD + 角色分配）
• 项目管理（IIT项目关联）
• 配额分配（项目/个人）
• 审计日志查询（FDA合规）

---

🏗️ 架构概览

┌─────────────────────────────────────────────────┐
│         机构管理端（INST Portal）                  │
├──────────────────────┬──────────────────────────┤
│   🏥 医院管理端       │   💊 药企管理端           │
├──────────────────────┼──────────────────────────┤
│ · 用户管理           │  · 用户管理               │
│ · 科室管理           │  · 项目管理               │
│ · 配额分配（科室/人） │  · 配额分配（项目/人）     │
│ · 审计日志           │  · 审计日志（合规）        │
└──────────────────────┴──────────────────────────┘
                      ↓
         继承运营管理端的基础设施
                      ↓
┌─────────────────────────────────────────────────┐
│              Platform Layer                     │
│  认证中心 │ 权限中心 │ 多租户隔离 │ 审计日志      │
└─────────────────────────────────────────────────┘

---

🔐 权限矩阵

功能	HOSPITAL_ADMIN	DEPARTMENT_ADMIN	PHARMA_ADMIN	PROJECT_MANAGER	USER
用户管理（租户内）	✅ 全部	✅ 本科室	✅ 全部	✅ 项目成员	❌
科室管理	✅	❌	N/A	N/A	❌
项目管理	N/A	N/A	✅ 查看	✅ 管理	❌
配额分配	✅	✅ 本科室	✅	✅ 项目内	❌
审计日志	✅ 租户内	✅ 本科室	✅ 租户内	✅ 项目内	❌
业务模块使用	✅	✅	✅	✅	✅

---

📁 代码结构（规划）

后端

backend/src/
├── modules/
│   └── institution/                    # 机构管理端模块
│       ├── controllers/
│       │   ├── hospital/
│       │   │   ├── user.controller.ts
│       │   │   ├── department.controller.ts
│       │   │   └── quota.controller.ts
│       │   │
│       │   └── pharma/
│       │       ├── user.controller.ts
│       │       ├── project.controller.ts
│       │       └── quota.controller.ts
│       │
│       ├── services/
│       │   ├── hospital.service.ts
│       │   └── pharma.service.ts
│       │
│       └── routes/
│           ├── hospital.routes.ts
│           └── pharma.routes.ts
│
└── common/
    └── middleware/
        ├── tenant.middleware.ts        # 租户隔离（复用）
        └── department.middleware.ts    # 科室权限检查

前端

frontend-v2/src/
├── modules/
│   └── institution/                    # 机构管理端模块
│       ├── pages/
│       │   ├── hospital/
│       │   │   ├── UserManagement/
│       │   │   ├── DepartmentManagement/
│       │   │   ├── QuotaAllocation/
│       │   │   └── AuditLog/
│       │   │
│       │   └── pharma/
│       │       ├── UserManagement/
│       │       ├── ProjectManagement/
│       │       ├── QuotaAllocation/
│       │       └── AuditLog/
│       │
│       └── components/
│           ├── UserForm/
│           ├── DepartmentTree/
│           ├── QuotaAllocator/
│           └── AuditLogViewer/
│
└── layouts/
    └── TenantLayout/                   # 租户专属布局（品牌定制）

---

🎨 UI/UX 特性

1. 租户品牌定制

// 从API获取租户配置
const tenantConfig = await api.get('/api/public/tenant-config/:tenantCode');

// 应用品牌样式
document.documentElement.style.setProperty('--primary-color', config.primaryColor);
document.title = config.systemName;

效果：

• 协和医院看到的是协和Logo和"协和临床研究平台"
• 辉瑞药业看到的是辉瑞Logo和"辉瑞IIT管理平台"

2. 科室树组件（医院端）

<DepartmentTree
  departments={departments}
  onSelect={(dept) => loadDeptUsers(dept)}
  showQuota={true}                    // 显示科室配额
  allowEdit={hasPermission('dept:edit')}
/>

支持：

• 多级展开/折叠
• 拖拽排序
• 配额可视化

3. 配额分配器

<QuotaAllocator
  totalQuota={1000000}
  allocations={[
    { target: '心内科', allocated: 500000, used: 300000 },
    { target: '神内科', allocated: 300000, used: 150000 }
  ]}
  onAllocate={(target, amount) => handleAllocate(target, amount)}
/>

特性：

• 可视化进度条
• 实时计算剩余配额
• 超额预警

---

🗄️ 数据模型

医院端

// 科室
interface Department {
  id: string;
  tenantId: string;
  name: string;
  parentId?: string;                  // 支持多级
  description?: string;
  members: User[];
  quota?: QuotaAllocation;
}

// 配额分配
interface QuotaAllocation {
  id: string;
  tenantId: string;
  targetType: 'DEPARTMENT' | 'USER';
  targetKey: string;                  // DepartmentID 或 UserID
  limitAmount: bigint;
  usedAmount: bigint;
}

药企端

// 项目（关联IIT）
interface Project {
  id: string;
  tenantId: string;
  iitProjectId?: string;              // 关联IIT项目
  name: string;
  description?: string;
  members: User[];
  quota?: QuotaAllocation;
}

// 项目成员
interface ProjectMember {
  id: string;
  projectId: string;
  userId: string;
  role: 'PROJECT_MANAGER' | 'DATA_ANALYST' | 'MEMBER';
}

---

🚀 开发流程

Step 1: 设计阶段（当前）

• 详细需求文档（PRD）
• API接口设计
• 数据库表设计
• UI原型设计

Step 2: 后端开发（依赖运营端完成）

1. 医院端API

   • 用户管理API
   • 科室管理API
   • 配额分配API
   • 审计日志API

2. 药企端API

   • 用户管理API
   • 项目管理API
   • 配额分配API
   • 审计日志API（合规）

Step 3: 前端开发

1. 公共组件

   • TenantLayout（品牌定制布局）
   • QuotaAllocator（配额分配器）
   • AuditLogViewer（审计日志查看器）

2. 医院端页面

   • 用户管理
   • 科室管理（DepartmentTree）
   • 配额分配

3. 药企端页面

   • 用户管理
   • 项目管理
   • 配额分配

---

📚 核心文档导航

当前可阅读

1. 整体架构
   ../ADMIN-运营管理端/00-系统设计/00-权限与角色体系梳理报告_v1.0.md

2. 需求文档（包含机构端）
   ../ADMIN-运营管理端/01-需求分析/02-通用能力层_07-运营与机构管理端PRD_v2.1.md

3. 运营端状态
   ../ADMIN-运营管理端/00-模块当前状态与开发指南.md

待创建文档

00-系统设计/

• 01-机构管理端架构设计.md
• 02-多租户隔离设计.md
• 03-配额管理设计.md

01-需求分析/

• 01-医院管理端PRD.md
• 02-药企管理端PRD.md
• 03-用户故事与验收标准.md

02-技术设计/

• 01-API设计文档.md
• 02-数据库设计文档.md
• 03-科室树实现方案.md
• 04-配额计算算法.md

03-UI设计/

• 01-医院端原型设计.html
• 02-药企端原型设计.html
• 03-品牌定制指南.md

---

⚠️ 技术要点

1. 多租户隔离

// 中间件：确保只能访问自己租户的数据
export const requireTenantAccess = async (request: FastifyRequest) => {
  const { tenantId } = request.user;
  const { id } = request.params;
  
  const resource = await prisma.resource.findUnique({
    where: { id }
  });
  
  if (resource.tenantId !== tenantId) {
    throw new ForbiddenError('无权访问其他租户资源');
  }
};

2. 科室权限检查

// 科室管理员只能管理自己科室
export const requireDepartmentAccess = async (request: FastifyRequest) => {
  const { role, departmentId } = request.user;
  const { deptId } = request.params;
  
  if (role === 'DEPARTMENT_ADMIN' && departmentId !== deptId) {
    throw new ForbiddenError('无权访问其他科室');
  }
};

3. 配额计算

// 计算可分配配额
export const calculateAvailableQuota = async (tenantId: string) => {
  // 1. 获取租户总配额
  const tenantQuota = await getTenantQuota(tenantId);
  
  // 2. 计算已分配配额
  const allocated = await prisma.tenantQuotaAllocation.aggregate({
    where: { tenantId },
    _sum: { limitAmount: true }
  });
  
  // 3. 返回可用配额
  return tenantQuota.totalAmount - (allocated._sum.limitAmount || 0);
};

---

🔍 与运营管理端的对比

特性	运营管理端（ADMIN）	机构管理端（INST）
用户	公司内部运营人员	医院/药企管理员
权限	全局管理权限	租户级管理权限
租户管理	✅ 创建/管理所有租户	❌ 只能看到自己租户
用户管理	✅ 全局用户管理	✅ 租户内用户管理
配额管理	✅ 分配租户总配额	✅ 分配科室/项目配额
Prompt管理	✅ 生产环境调试	❌ 无权限
审计日志	✅ 全局日志	✅ 租户内日志
品牌定制	✅ 配置所有租户品牌	❌ 只能查看

---

📅 预计开发时间

前提： 运营管理端基础架构完成（Week 4）

• Week 5-6： 医院管理端（8人天）
• Week 7-8： 药企管理端（8人天）
• Week 9： 测试与优化（3人天）

总计： 约19人天（~4周）

---

📞 需要帮助？

1. 架构问题：参考运营管理端实现
2. 权限问题：查看00-权限与角色体系梳理报告_v1.0.md
3. UI问题：参考DC/ASL等已有模块

---

🎯 下一步行动

• 等待运营管理端完成基础架构
• 开始编写详细PRD
• 设计UI原型
• 设计API接口

---

机构管理端虽然尚未开始开发，但设计思路已明确。待运营管理端完成后，可快速启动开发。

---

🚀 敬请期待！