Files
AIclinicalresearch/docs/00-系统总体设计/04-运营管理端架构设计.md
HaHafeng 66255368b7 feat(admin): Add user management and upgrade to module permission system
Features - User Management (Phase 4.1):
- Database: Add user_modules table for fine-grained module permissions
- Database: Add 4 user permissions (view/create/edit/delete) to role_permissions
- Backend: UserService (780 lines) - CRUD with tenant isolation
- Backend: UserController + UserRoutes (648 lines) - 13 API endpoints
- Backend: Batch import users from Excel
- Frontend: UserListPage (412 lines) - list/filter/search/pagination
- Frontend: UserFormPage (341 lines) - create/edit with module config
- Frontend: UserDetailPage (393 lines) - details/tenant/module management
- Frontend: 3 modal components (592 lines) - import/assign/configure
- API: GET/POST/PUT/DELETE /api/admin/users/* endpoints

Architecture Upgrade - Module Permission System:
- Backend: Add getUserModules() method in auth.service
- Backend: Login API returns modules array in user object
- Frontend: AuthContext adds hasModule() method
- Frontend: Navigation filters modules based on user.modules
- Frontend: RouteGuard checks requiredModule instead of requiredVersion
- Frontend: Remove deprecated version-based permission system
- UX: Only show accessible modules in navigation (clean UI)
- UX: Smart redirect after login (avoid 403 for regular users)

Fixes:
- Fix UTF-8 encoding corruption in ~100 docs files
- Fix pageSize type conversion in userService (String to Number)
- Fix authUser undefined error in TopNavigation
- Fix login redirect logic with role-based access check
- Update Git commit guidelines v1.2 with UTF-8 safety rules

Database Changes:
- CREATE TABLE user_modules (user_id, tenant_id, module_code, is_enabled)
- ADD UNIQUE CONSTRAINT (user_id, tenant_id, module_code)
- INSERT 4 permissions + role assignments
- UPDATE PUBLIC tenant with 8 module subscriptions

Technical:
- Backend: 5 new files (~2400 lines)
- Frontend: 10 new files (~2500 lines)
- Docs: 1 development record + 2 status updates + 1 guideline update
- Total: ~4900 lines of code

Status: User management 100% complete, module permission system operational
2026-01-16 13:42:10 +08:00

24 KiB
Raw Permalink Blame History

运营管理端架构设计

文档版本: v1.0
创建日期: 2025-11-06
最后更新: 2025-11-06
文档状态: 架构设计中
作者: 技术架构师


📋 文档说明

本文档详细设计运营管理端Admin/Operations Platform的完整架构包括

  1. 运营管理端的层次定位
  2. 完整的功能清单
  3. 对系统总体设计的影响
  4. 技术实现方案

🎯 核心问题解答

1. 运营管理端是应用层吗?

答案:运营管理端是"横跨多层"的特殊系统

运营管理端的定位:

┌─────────────────────────────────────────────────────────┐
│              运营管理端Admin Platform                  │
│         独立的前端应用 + 独立的后端API                      │
│                                                           │
│  管理范围:                                                │
│  ├─ 平台基础层配置(用户、权限、租户)                      │
│  ├─ 通用能力层配置LLM模型、Feature Flag                │
│  ├─ 业务模块配置(智能体提示词、模块开关)                  │
│  └─ 运营数据分析(统计、监控、成本分析)                    │
└─────────────────────────────────────────────────────────┘
                          ↓ 管理
┌─────────────────────────────────────────────────────────┐
│                   业务模块层                              │
│  AIA | ASL | PKB | DC | SSA | ST | RVW                  │
└─────────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────────┐
│                   通用能力层                              │
│  LLM网关 | 文档处理 | RAG | ETL | NLP                    │
└─────────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────────┐
│                   平台基础层                              │
│  用户权限 | 存储 | 通知 | 监控 | 配置                     │
└─────────────────────────────────────────────────────────┘

准确定位:

  • 运营管理端是一个独立的应用系统
  • 它管理和配置所有三层(平台层、能力层、业务层)
  • 它有自己的前端应用、后端API、权限体系
  • 它是"平台的管理者",而不是"应用层"

类比:

  • 业务前端(用户端):给医生、研究者使用
  • 运营管理端:给公司内部运营人员、管理员使用

2. 运营管理端的完整功能清单

基于7个业务模块我为您补充了完整的功能清单


📊 功能模块设计

模块1用户管理 已提到

核心功能:

  1. 用户列表与搜索

    • 列表展示(邮箱、姓名、注册时间、状态、版本)
    • 搜索和筛选(按邮箱、姓名、状态、版本、注册时间)
    • 批量操作(批量禁用、批量删除)
  2. 用户详情与编辑

    • 基本信息(邮箱、姓名、头像、手机号)
    • 账户状态(激活、禁用、锁定)
    • 用户版本(基础版、高级版、旗舰版)
    • 配额管理知识库配额、文档配额、月度AI配额
    • 试用期管理(是否试用、试用到期时间)
  3. 用户权限管理

    • 模块权限可访问哪些模块AIA、ASL、PKB等
    • 功能权限(批处理、全文模式、模型切换等)
    • 角色分配普通用户、高级用户、VIP用户、管理员
  4. 用户操作日志

    • 登录日志登录时间、IP地址、设备
    • 操作日志(上传文档、创建对话、批处理任务等)
    • API调用日志LLM调用次数、Token使用量
  5. 用户数据统计

    • 知识库数量、文档数量
    • 对话数量、消息数量
    • AI调用次数、Token使用量
    • 存储空间使用量

模块2智能体提示词管理 已提到

核心功能:

  1. 智能体列表

    • 10个智能体选题评价、PICO梳理、样本量计算等
    • 每个智能体的基本信息(名称、描述、图标)
    • 启用/禁用状态
  2. 提示词编辑

    • System Prompt系统提示词
    • User Prompt Template用户提示词模板
    • 支持变量(如{研究背景}{研究目标}
    • 实时预览
  3. 提示词版本管理

    • 版本历史记录
    • 版本对比
    • 版本回滚
    • 版本发布(灰度发布、全量发布)
  4. 测试与验证

    • 提示词测试工具
    • 输入测试数据查看AI输出
    • A/B测试对比不同提示词效果

模块3版本功能设置Feature Flag 已提到

核心功能:

  1. 版本定义

    • 基础版Basic
    • 高级版Advanced
    • 旗舰版Flagship
    • 企业版Enterprise
  2. 模块权限配置

    • 7个业务模块的访问权限矩阵
    版本 | AIA | ASL | PKB | DC | SSA | ST | RVW
    -----|-----|-----|-----|----|----|----|----|
    基础 |  ✓  |  ✗  |  ✓  | ✗  | ✗  | ✗  | ✗  |
    高级 |  ✓  |  ✓  |  ✓  | ✗  | ✗  | ✓  | ✗  |
    旗舰 |  ✓  |  ✓  |  ✓  | ✓  | ✓  | ✓  | ✓  |
    
  3. 功能权限配置

    • AI模型选择权限DeepSeek、Qwen3、Claude等
    • 批处理功能
    • 全文阅读模式
    • 知识库配额3个、10个、无限
    • 文档配额100个、1000个、无限
    • 月度AI配额100次、500次、2000次、无限
  4. 动态配置

    • 实时生效(无需重启)
    • 配置预览(修改前预览效果)
    • 配置回滚

模块4用户权限和版本设置 已提到

核心功能:

  1. 批量版本调整

    • 选择多个用户批量升级/降级版本
    • 批量延长试用期
    • 批量调整配额
  2. 自动化规则

    • 新用户默认版本(基础版)
    • 新用户默认试用期14天
    • 试用期到期自动降级
    • 配额超出自动限流
  3. 特殊权限

    • 内部员工账号(所有权限)
    • 测试账号(无限配额)
    • 合作伙伴账号(特殊权限)

模块5租户管理 🆕 新增

适用场景: 私有化部署、企业版

核心功能:

  1. 租户列表

    • 租户名称、Logo、域名
    • 租户状态(试用、正式、过期、禁用)
    • 租户类型(标准版、企业版、定制版)
  2. 租户配置

    • 品牌定制Logo、主题色、名称
    • 独立域名(如hospital-a.yizhengxun.com
    • 数据隔离独立Schema
    • 模块开关(可选模块)
  3. 租户统计

    • 用户数量、活跃用户
    • 存储使用量
    • API调用量
    • 成本分析

模块6LLM模型管理 🆕 新增(关键)

核心功能:

  1. 模型配置

    • 支持的模型列表DeepSeek-V3、Qwen3、Qwen-Long、Claude等
    • 每个模型的API Key
    • 模型基础URL
    • 模型参数Temperature、Max Tokens等
  2. 模型与版本绑定

    基础版只能用DeepSeek-V3
    高级版可用DeepSeek-V3、Qwen3
    旗舰版可用DeepSeek-V3、Qwen3、Qwen-Long、Claude
    
  3. 模型成本配置

    • 每个模型的成本(¥/百万tokens
    • DeepSeek-V3¥1/百万tokens
    • Qwen3¥5/百万tokens
    • Claude 3¥50/百万tokens估算
  4. 模型切换策略

    • 默认模型如DeepSeek-V3
    • 降级策略(模型不可用时自动降级)
    • 限流策略(超出配额时禁用高成本模型)

模块7系统配置管理 🆕 新增

核心功能:

  1. 全局配置

    • 系统名称、Logo、Favicon
    • 默认语言(中文、英文)
    • 时区设置
    • 文件上传限制(单文件大小、总大小)
  2. 安全配置

    • JWT Token过期时间
    • 密码强度要求
    • 登录失败锁定策略
    • CORS配置
  3. 邮件配置

    • SMTP服务器
    • 邮件模板(注册、密码重置、通知等)
  4. 存储配置

    • 对象存储类型本地、MinIO、阿里云OSS、S3
    • 存储配额限制

模块8监控与日志 🆕 新增(关键)

核心功能:

  1. 系统监控

    • 实时在线用户数
    • 实时API调用量TPS/QPS
    • 系统资源使用CPU、内存、磁盘
    • 数据库连接数
  2. 错误监控

    • 错误日志列表(时间、用户、错误类型、错误信息)
    • 错误统计(按类型、按模块、按时间)
    • 错误告警(邮件、短信)
  3. 性能监控

    • API响应时间统计
    • 慢查询日志
    • LLM调用延迟
  4. 审计日志

    • 管理员操作日志(登录、修改配置、修改用户等)
    • 敏感操作记录(删除用户、修改权限、修改提示词等)

模块9数据统计与报表 🆕 新增(关键)

核心功能:

  1. 用户统计

    • 注册用户趋势(日/周/月)
    • 活跃用户趋势DAU/WAU/MAU
    • 用户留存率
    • 用户版本分布
  2. 业务统计

    • 各模块使用情况AIA、ASL、PKB等
    • 智能体使用排行
    • 知识库数量趋势
    • 文档上传量趋势
  3. AI调用统计

    • LLM调用次数趋势
    • Token使用量趋势
    • 各模型使用占比
    • 成本分析(按模型、按模块、按用户)
  4. 存储统计

    • 总存储使用量
    • 各模块存储占比
    • 用户存储排行
  5. 导出报表

    • Excel导出
    • PDF导出
    • 定期自动生成报表(周报、月报)

模块10成本分析与计费 🆕 新增(商业关键)

核心功能:

  1. 成本统计

    • LLM API总成本按日/周/月)
    • 各模块成本占比
    • 各用户成本排行
    • 各模型成本占比
  2. 计费管理

    • 用户账单生成
    • 欠费用户列表
    • 自动扣费
    • 发票管理
  3. 成本预警

    • 成本超出预算告警
    • 单用户成本异常告警
    • 免费用户滥用检测
  4. 利润分析

    • 收入 vs 成本
    • ROI分析
    • 各版本利润率

模块11公告与通知管理 🆕 新增

核心功能:

  1. 系统公告

    • 创建公告(标题、内容、优先级)
    • 公告展示位置(首页横幅、弹窗、消息中心)
    • 公告定时发布
    • 公告过期时间
  2. 站内消息

    • 给所有用户发消息
    • 给特定版本用户发消息
    • 给特定用户发消息
    • 消息模板
  3. 邮件群发

    • 邮件内容编辑(富文本)
    • 邮件预览
    • 定时发送
    • 发送记录

模块12帮助文档管理 🆕 新增

核心功能:

  1. 文档库

    • 文档分类(快速入门、功能介绍、常见问题等)
    • 文档列表(标题、状态、更新时间)
    • 文档编辑Markdown富文本
    • 文档预览
  2. 视频教程

    • 视频上传
    • 视频分类
    • 视频播放统计
  3. 常见问题FAQ

    • 问题分类
    • 问题编辑
    • 搜索优化

模块13反馈与工单管理 🆕 新增

核心功能:

  1. 用户反馈

    • 反馈列表(用户、内容、类型、状态)
    • 反馈分类功能建议、Bug报告、咨询
    • 反馈回复
    • 反馈状态(待处理、处理中、已完成、已忽略)
  2. 工单系统

    • 工单创建
    • 工单分配(分配给客服、技术团队)
    • 工单跟进
    • 工单关闭
  3. 满意度调查

    • 问题解决后发送满意度调查
    • 满意度统计

模块14系统健康检查 🆕 新增

核心功能:

  1. 健康检查

    • 数据库连接检查
    • Redis连接检查
    • Dify API连接检查
    • Python微服务连接检查
    • LLM API连接检查
  2. 自动化测试

    • API可用性测试
    • 端到端测试注册、登录、上传文档、AI对话
  3. 告警通知

    • 服务异常告警
    • 邮件/短信通知管理员

模块15数据库备份与恢复 🆕 新增

核心功能:

  1. 备份管理

    • 手动备份
    • 定时自动备份(每日、每周)
    • 备份列表(时间、大小、状态)
    • 备份下载
  2. 恢复管理

    • 选择备份恢复
    • 恢复预览(确认恢复内容)
    • 恢复进度

📊 功能优先级分类

P0必须阶段一

模块 功能 原因
用户管理 用户列表、编辑、禁用 基础功能
版本功能设置 Feature Flag配置 商业模式基础
LLM模型管理 模型配置、成本配置 成本控制
系统配置 全局配置、安全配置 系统运行基础

P1重要阶段一或阶段二

模块 功能 原因
智能体提示词管理 提示词编辑、版本管理 产品优化
监控与日志 错误监控、审计日志 稳定性
数据统计与报表 用户统计、AI调用统计 运营决策
成本分析与计费 成本统计、计费管理 商业运营

P2有用阶段二或阶段三

模块 功能 原因
租户管理 租户配置、数据隔离 私有化部署需要
公告与通知 系统公告、站内消息 用户运营
帮助文档 文档管理、视频教程 用户支持
反馈与工单 用户反馈、工单系统 客户服务
系统健康检查 健康检查、自动化测试 运维自动化
数据库备份 备份管理、恢复管理 数据安全

🏗️ 对系统总体设计的影响

影响1独立的前端应用

当前架构:

frontend/              # 用户端前端React
  ├── src/
  │   ├── pages/
  │   │   ├── login/
  │   │   ├── dashboard/
  │   │   └── ...
  └── ...

新架构(需要增加运营管理端):

frontend/              # 用户端前端React
  └── ...

admin-frontend/        # 运营管理端前端React⭐ 新增
  ├── src/
  │   ├── pages/
  │   │   ├── login/             # 管理员登录
  │   │   ├── dashboard/         # 运营仪表盘
  │   │   ├── users/             # 用户管理
  │   │   ├── agents/            # 智能体管理
  │   │   ├── feature-flags/     # Feature Flag管理
  │   │   ├── llm-models/        # LLM模型管理
  │   │   ├── monitoring/        # 监控与日志
  │   │   ├── statistics/        # 数据统计
  │   │   ├── cost-analysis/     # 成本分析
  │   │   └── ...
  │   └── ...
  └── ...

部署方式:

  • 用户端:https://app.yizhengxun.com
  • 运营管理端:https://admin.yizhengxun.com

影响2独立的后端API

当前后端API

/api/auth/*          # 用户认证
/api/users/*         # 用户相关
/api/projects/*      # 项目管理
/api/conversations/* # AI对话
/api/kb/*            # 知识库
...

新增管理端API

/api/admin/auth/*              # 管理员认证 ⭐
/api/admin/users/*             # 用户管理 ⭐
/api/admin/agents/*            # 智能体管理 ⭐
/api/admin/feature-flags/*     # Feature Flag管理 ⭐
/api/admin/llm-models/*        # LLM模型管理 ⭐
/api/admin/tenants/*           # 租户管理 ⭐
/api/admin/monitoring/*        # 监控与日志 ⭐
/api/admin/statistics/*        # 数据统计 ⭐
/api/admin/cost-analysis/*     # 成本分析 ⭐
/api/admin/announcements/*     # 公告管理 ⭐
/api/admin/feedback/*          # 反馈管理 ⭐
...

影响3权限体系扩展

当前权限:

用户角色:
- user普通用户
- admin管理员但功能有限

新权限体系:

用户角色:
- user普通用户
- vipVIP用户高级功能

管理员角色:⭐ 新增
- super_admin超级管理员所有权限
- admin管理员部分权限
- operator运营人员用户管理、数据统计
- customer_service客服反馈管理、工单管理
- auditor审计员只读权限查看日志和报表

管理员权限:⭐ 新增
- user_management        # 用户管理
- agent_management       # 智能体管理
- feature_flag_management # Feature Flag管理
- llm_model_management   # LLM模型管理
- tenant_management      # 租户管理
- monitoring_access      # 监控与日志访问
- statistics_access      # 数据统计访问
- cost_analysis_access   # 成本分析访问
- system_config_management # 系统配置管理
- announcement_management # 公告管理
- feedback_management    # 反馈管理

影响4数据库Schema扩展

当前Schema逻辑隔离

-- 平台层
platform_schema.users
platform_schema.admin_logs

-- 业务模块
aia_schema.projects
pkb_schema.knowledge_bases
...

新增管理端Schema

-- 管理端Schema ⭐ 新增
CREATE SCHEMA admin_schema;

-- 管理员相关
admin_schema.admin_users          # 管理员账号
admin_schema.admin_roles          # 管理员角色
admin_schema.admin_permissions    # 管理员权限

-- Feature Flag
admin_schema.feature_flags        # Feature Flag配置
admin_schema.feature_flag_history # Feature Flag变更历史

-- 智能体配置
admin_schema.agent_configs        # 智能体配置
admin_schema.agent_prompt_history # 提示词版本历史

-- LLM模型配置
admin_schema.llm_models           # LLM模型配置
admin_schema.llm_cost_config      # 模型成本配置

-- 租户管理
admin_schema.tenants              # 租户表
admin_schema.tenant_configs       # 租户配置

-- 公告与通知
admin_schema.announcements        # 系统公告
admin_schema.notifications        # 站内通知

-- 反馈与工单
admin_schema.feedback             # 用户反馈
admin_schema.tickets              # 工单

-- 系统配置
admin_schema.system_configs       # 系统配置

-- 审计日志
admin_schema.audit_logs           # 审计日志
admin_schema.operation_logs       # 操作日志

影响5新增通用能力

LLM Gateway需要增强

// 原有功能
interface LLMGateway {
  chat(...): Promise<ChatResponse>;
}

// 新增功能(支持运营管理端)⭐
interface LLMGateway {
  chat(...): Promise<ChatResponse>;
  
  // 管理端功能
  getUsageStats(startDate, endDate): Promise<UsageStats>;      // 使用量统计
  getCostStats(startDate, endDate): Promise<CostStats>;        // 成本统计
  getUserUsage(userId): Promise<UserUsage>;                    // 单用户使用量
  getModelConfig(): Promise<ModelConfig[]>;                    // 模型配置
  updateModelConfig(config): Promise<void>;                    // 更新模型配置
  checkQuota(userId): Promise<QuotaInfo>;                      // 配额检查
  resetQuota(userId): Promise<void>;                           // 重置配额
}

影响6监控与日志增强

新增监控能力:

// 监控服务 ⭐ 新增
interface MonitoringService {
  // 实时监控
  getSystemStatus(): Promise<SystemStatus>;           // 系统状态
  getOnlineUsers(): Promise<number>;                  // 在线用户数
  getApiMetrics(): Promise<ApiMetrics>;               // API指标TPS/QPS
  
  // 错误监控
  getErrorLogs(filter): Promise<ErrorLog[]>;          // 错误日志
  getErrorStats(): Promise<ErrorStats>;               // 错误统计
  
  // 性能监控
  getSlowQueries(): Promise<SlowQuery[]>;             // 慢查询
  getApiLatency(): Promise<LatencyStats>;             // API延迟
  
  // 审计日志
  getAuditLogs(filter): Promise<AuditLog[]>;          // 审计日志
  logAdminOperation(operation): Promise<void>;        // 记录管理员操作
}

🎯 实施方案

阶段一核心功能MVP

时间1-2个月

实现内容:

  1. 管理端前端React + Ant Design Pro
  2. 管理端后端APINode.js + Fastify
  3. 管理员认证与权限
  4. 用户管理P0
  5. Feature Flag管理P0
  6. LLM模型管理P0
  7. 基础监控(错误日志、审计日志)

阶段二:运营功能

时间1-2个月

实现内容:

  1. 智能体提示词管理
  2. 数据统计与报表
  3. 成本分析与计费
  4. 公告与通知管理

阶段三:高级功能

时间1-2个月

实现内容:

  1. 租户管理(私有化部署需要)
  2. 反馈与工单系统
  3. 帮助文档管理
  4. 系统健康检查
  5. 数据库备份与恢复

📊 技术选型

前端技术栈

推荐Ant Design Pro

admin-frontend/
  ├── React 18
  ├── TypeScript
  ├── Ant Design Pro (开箱即用的中台前端解决方案)
  ├── Ant Design Charts (数据可视化)
  ├── ProComponents (高级组件)
  └── UmiJS (路由和构建)

优势:

  • 专为中台/管理系统设计
  • 开箱即用的布局、菜单、权限、表格、表单
  • 丰富的数据可视化组件
  • 与Ant Design生态完美集成

后端技术栈

继续使用现有技术栈:

backend/
  ├── Node.js + TypeScript
  ├── Fastify
  ├── Prisma
  └── PostgreSQL

新增模块:

backend/src/admin/
  ├── controllers/       # 管理端控制器
  ├── services/          # 管理端服务
  ├── middleware/        # 管理员认证中间件
  └── routes/            # 管理端路由

🎯 总结

运营管理端的定位

运营管理端是:

  • 一个独立的应用系统(独立前端 + 独立API
  • 横跨所有层次的管理者(管理平台层、能力层、业务层)
  • 商业运营的核心Feature Flag、成本控制、计费管理
  • 系统健康的保障(监控、日志、健康检查)

完整功能清单

您提到的4个功能

  1. 用户管理
  2. 智能体提示词设置
  3. 版本功能设置Feature Flag
  4. 用户权限和版本设置

我补充的11个功能 5. 🆕 租户管理(私有化部署) 6. 🆕 LLM模型管理关键 7. 🆕 系统配置管理 8. 🆕 监控与日志(关键) 9. 🆕 数据统计与报表(关键) 10. 🆕 成本分析与计费(商业关键) 11. 🆕 公告与通知管理 12. 🆕 帮助文档管理 13. 🆕 反馈与工单管理 14. 🆕 系统健康检查 15. 🆕 数据库备份与恢复

总计15个功能模块

对系统总体设计的影响

  1. 新增独立前端应用admin-frontend/
  2. 新增独立后端API/api/admin/*
  3. 扩展权限体系(管理员角色、管理员权限)
  4. 扩展数据库Schemaadmin_schema
  5. 增强LLM Gateway(使用量统计、成本分析)
  6. 新增监控服务(实时监控、错误监控、性能监控)

实施建议

阶段一P0 1-2个月

  • 用户管理、Feature Flag、LLM模型管理、基础监控

阶段二P1 1-2个月

  • 智能体管理、数据统计、成本分析、公告管理

阶段三P2 1-2个月

  • 租户管理、反馈工单、帮助文档、健康检查、备份恢复

下一步建议:

  1. 确认运营管理端的功能优先级
  2. 设计管理端的UI原型
  3. 设计管理端的数据库表结构
  4. 设计管理端的API接口