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. 租户品牌定制

```typescript
// 从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. 科室树组件（医院端）

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

**支持：**
- 多级展开/折叠
- 拖拽排序
- 配额可视化

### 3. 配额分配器

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

**特性：**
- 可视化进度条
- 实时计算剩余配额
- 超额预警

---

## 🗄️ 数据模型

### 医院端

```typescript
// 科室
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;
}
```

### 药企端

```typescript
// 项目（关联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. 多租户隔离

```typescript
// 中间件：确保只能访问自己租户的数据
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. 科室权限检查

```typescript
// 科室管理员只能管理自己科室
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. 配额计算

```typescript
// 计算可分配配额
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接口

---

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

---

**🚀 敬请期待！**