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
24 KiB
运营管理端架构设计
文档版本: v1.0
创建日期: 2025-11-06
最后更新: 2025-11-06
文档状态: 架构设计中
作者: 技术架构师
📋 文档说明
本文档详细设计运营管理端(Admin/Operations Platform)的完整架构,包括:
- 运营管理端的层次定位
- 完整的功能清单
- 对系统总体设计的影响
- 技术实现方案
🎯 核心问题解答
1. 运营管理端是应用层吗?
答案:运营管理端是"横跨多层"的特殊系统
运营管理端的定位:
┌─────────────────────────────────────────────────────────┐
│ 运营管理端(Admin Platform) │
│ 独立的前端应用 + 独立的后端API │
│ │
│ 管理范围: │
│ ├─ 平台基础层配置(用户、权限、租户) │
│ ├─ 通用能力层配置(LLM模型、Feature Flag) │
│ ├─ 业务模块配置(智能体提示词、模块开关) │
│ └─ 运营数据分析(统计、监控、成本分析) │
└─────────────────────────────────────────────────────────┘
↓ 管理
┌─────────────────────────────────────────────────────────┐
│ 业务模块层 │
│ AIA | ASL | PKB | DC | SSA | ST | RVW │
└─────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────┐
│ 通用能力层 │
│ LLM网关 | 文档处理 | RAG | ETL | NLP │
└─────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────┐
│ 平台基础层 │
│ 用户权限 | 存储 | 通知 | 监控 | 配置 │
└─────────────────────────────────────────────────────────┘
准确定位:
- ✅ 运营管理端是一个独立的应用系统
- ✅ 它管理和配置所有三层(平台层、能力层、业务层)
- ✅ 它有自己的前端应用、后端API、权限体系
- ✅ 它是"平台的管理者",而不是"应用层"
类比:
- 业务前端(用户端):给医生、研究者使用
- 运营管理端:给公司内部运营人员、管理员使用
2. 运营管理端的完整功能清单
基于7个业务模块,我为您补充了完整的功能清单:
📊 功能模块设计
模块1:用户管理 ✅ 已提到
核心功能:
-
用户列表与搜索
- 列表展示(邮箱、姓名、注册时间、状态、版本)
- 搜索和筛选(按邮箱、姓名、状态、版本、注册时间)
- 批量操作(批量禁用、批量删除)
-
用户详情与编辑
- 基本信息(邮箱、姓名、头像、手机号)
- 账户状态(激活、禁用、锁定)
- 用户版本(基础版、高级版、旗舰版)
- 配额管理(知识库配额、文档配额、月度AI配额)
- 试用期管理(是否试用、试用到期时间)
-
用户权限管理
- 模块权限(可访问哪些模块:AIA、ASL、PKB等)
- 功能权限(批处理、全文模式、模型切换等)
- 角色分配(普通用户、高级用户、VIP用户、管理员)
-
用户操作日志
- 登录日志(登录时间、IP地址、设备)
- 操作日志(上传文档、创建对话、批处理任务等)
- API调用日志(LLM调用次数、Token使用量)
-
用户数据统计
- 知识库数量、文档数量
- 对话数量、消息数量
- AI调用次数、Token使用量
- 存储空间使用量
模块2:智能体提示词管理 ✅ 已提到
核心功能:
-
智能体列表
- 10个智能体(选题评价、PICO梳理、样本量计算等)
- 每个智能体的基本信息(名称、描述、图标)
- 启用/禁用状态
-
提示词编辑
- System Prompt(系统提示词)
- User Prompt Template(用户提示词模板)
- 支持变量(如
{研究背景}、{研究目标}) - 实时预览
-
提示词版本管理
- 版本历史记录
- 版本对比
- 版本回滚
- 版本发布(灰度发布、全量发布)
-
测试与验证
- 提示词测试工具
- 输入测试数据,查看AI输出
- A/B测试(对比不同提示词效果)
模块3:版本功能设置(Feature Flag) ✅ 已提到
核心功能:
-
版本定义
- 基础版(Basic)
- 高级版(Advanced)
- 旗舰版(Flagship)
- 企业版(Enterprise)
-
模块权限配置
- 7个业务模块的访问权限矩阵
版本 | AIA | ASL | PKB | DC | SSA | ST | RVW -----|-----|-----|-----|----|----|----|----| 基础 | ✓ | ✗ | ✓ | ✗ | ✗ | ✗ | ✗ | 高级 | ✓ | ✓ | ✓ | ✗ | ✗ | ✓ | ✗ | 旗舰 | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | -
功能权限配置
- AI模型选择权限(DeepSeek、Qwen3、Claude等)
- 批处理功能
- 全文阅读模式
- 知识库配额(3个、10个、无限)
- 文档配额(100个、1000个、无限)
- 月度AI配额(100次、500次、2000次、无限)
-
动态配置
- 实时生效(无需重启)
- 配置预览(修改前预览效果)
- 配置回滚
模块4:用户权限和版本设置 ✅ 已提到
核心功能:
-
批量版本调整
- 选择多个用户批量升级/降级版本
- 批量延长试用期
- 批量调整配额
-
自动化规则
- 新用户默认版本(基础版)
- 新用户默认试用期(14天)
- 试用期到期自动降级
- 配额超出自动限流
-
特殊权限
- 内部员工账号(所有权限)
- 测试账号(无限配额)
- 合作伙伴账号(特殊权限)
模块5:租户管理 🆕 新增
适用场景: 私有化部署、企业版
核心功能:
-
租户列表
- 租户名称、Logo、域名
- 租户状态(试用、正式、过期、禁用)
- 租户类型(标准版、企业版、定制版)
-
租户配置
- 品牌定制(Logo、主题色、名称)
- 独立域名(如
hospital-a.yizhengxun.com) - 数据隔离(独立Schema)
- 模块开关(可选模块)
-
租户统计
- 用户数量、活跃用户
- 存储使用量
- API调用量
- 成本分析
模块6:LLM模型管理 🆕 新增(关键)
核心功能:
-
模型配置
- 支持的模型列表(DeepSeek-V3、Qwen3、Qwen-Long、Claude等)
- 每个模型的API Key
- 模型基础URL
- 模型参数(Temperature、Max Tokens等)
-
模型与版本绑定
基础版:只能用DeepSeek-V3 高级版:可用DeepSeek-V3、Qwen3 旗舰版:可用DeepSeek-V3、Qwen3、Qwen-Long、Claude -
模型成本配置
- 每个模型的成本(¥/百万tokens)
- DeepSeek-V3:¥1/百万tokens
- Qwen3:¥5/百万tokens
- Claude 3:¥50/百万tokens(估算)
-
模型切换策略
- 默认模型(如DeepSeek-V3)
- 降级策略(模型不可用时自动降级)
- 限流策略(超出配额时禁用高成本模型)
模块7:系统配置管理 🆕 新增
核心功能:
-
全局配置
- 系统名称、Logo、Favicon
- 默认语言(中文、英文)
- 时区设置
- 文件上传限制(单文件大小、总大小)
-
安全配置
- JWT Token过期时间
- 密码强度要求
- 登录失败锁定策略
- CORS配置
-
邮件配置
- SMTP服务器
- 邮件模板(注册、密码重置、通知等)
-
存储配置
- 对象存储类型(本地、MinIO、阿里云OSS、S3)
- 存储配额限制
模块8:监控与日志 🆕 新增(关键)
核心功能:
-
系统监控
- 实时在线用户数
- 实时API调用量(TPS/QPS)
- 系统资源使用(CPU、内存、磁盘)
- 数据库连接数
-
错误监控
- 错误日志列表(时间、用户、错误类型、错误信息)
- 错误统计(按类型、按模块、按时间)
- 错误告警(邮件、短信)
-
性能监控
- API响应时间统计
- 慢查询日志
- LLM调用延迟
-
审计日志
- 管理员操作日志(登录、修改配置、修改用户等)
- 敏感操作记录(删除用户、修改权限、修改提示词等)
模块9:数据统计与报表 🆕 新增(关键)
核心功能:
-
用户统计
- 注册用户趋势(日/周/月)
- 活跃用户趋势(DAU/WAU/MAU)
- 用户留存率
- 用户版本分布
-
业务统计
- 各模块使用情况(AIA、ASL、PKB等)
- 智能体使用排行
- 知识库数量趋势
- 文档上传量趋势
-
AI调用统计
- LLM调用次数趋势
- Token使用量趋势
- 各模型使用占比
- 成本分析(按模型、按模块、按用户)
-
存储统计
- 总存储使用量
- 各模块存储占比
- 用户存储排行
-
导出报表
- Excel导出
- PDF导出
- 定期自动生成报表(周报、月报)
模块10:成本分析与计费 🆕 新增(商业关键)
核心功能:
-
成本统计
- LLM API总成本(按日/周/月)
- 各模块成本占比
- 各用户成本排行
- 各模型成本占比
-
计费管理
- 用户账单生成
- 欠费用户列表
- 自动扣费
- 发票管理
-
成本预警
- 成本超出预算告警
- 单用户成本异常告警
- 免费用户滥用检测
-
利润分析
- 收入 vs 成本
- ROI分析
- 各版本利润率
模块11:公告与通知管理 🆕 新增
核心功能:
-
系统公告
- 创建公告(标题、内容、优先级)
- 公告展示位置(首页横幅、弹窗、消息中心)
- 公告定时发布
- 公告过期时间
-
站内消息
- 给所有用户发消息
- 给特定版本用户发消息
- 给特定用户发消息
- 消息模板
-
邮件群发
- 邮件内容编辑(富文本)
- 邮件预览
- 定时发送
- 发送记录
模块12:帮助文档管理 🆕 新增
核心功能:
-
文档库
- 文档分类(快速入门、功能介绍、常见问题等)
- 文档列表(标题、状态、更新时间)
- 文档编辑(Markdown富文本)
- 文档预览
-
视频教程
- 视频上传
- 视频分类
- 视频播放统计
-
常见问题(FAQ)
- 问题分类
- 问题编辑
- 搜索优化
模块13:反馈与工单管理 🆕 新增
核心功能:
-
用户反馈
- 反馈列表(用户、内容、类型、状态)
- 反馈分类(功能建议、Bug报告、咨询)
- 反馈回复
- 反馈状态(待处理、处理中、已完成、已忽略)
-
工单系统
- 工单创建
- 工单分配(分配给客服、技术团队)
- 工单跟进
- 工单关闭
-
满意度调查
- 问题解决后发送满意度调查
- 满意度统计
模块14:系统健康检查 🆕 新增
核心功能:
-
健康检查
- 数据库连接检查
- Redis连接检查
- Dify API连接检查
- Python微服务连接检查
- LLM API连接检查
-
自动化测试
- API可用性测试
- 端到端测试(注册、登录、上传文档、AI对话)
-
告警通知
- 服务异常告警
- 邮件/短信通知管理员
模块15:数据库备份与恢复 🆕 新增
核心功能:
-
备份管理
- 手动备份
- 定时自动备份(每日、每周)
- 备份列表(时间、大小、状态)
- 备份下载
-
恢复管理
- 选择备份恢复
- 恢复预览(确认恢复内容)
- 恢复进度
📊 功能优先级分类
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(普通用户)
- vip(VIP用户,高级功能)
管理员角色:⭐ 新增
- 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个月
实现内容:
- ✅ 管理端前端(React + Ant Design Pro)
- ✅ 管理端后端API(Node.js + Fastify)
- ✅ 管理员认证与权限
- ✅ 用户管理(P0)
- ✅ Feature Flag管理(P0)
- ✅ LLM模型管理(P0)
- ✅ 基础监控(错误日志、审计日志)
阶段二:运营功能
时间:1-2个月
实现内容:
- ✅ 智能体提示词管理
- ✅ 数据统计与报表
- ✅ 成本分析与计费
- ✅ 公告与通知管理
阶段三:高级功能
时间:1-2个月
实现内容:
- ✅ 租户管理(私有化部署需要)
- ✅ 反馈与工单系统
- ✅ 帮助文档管理
- ✅ 系统健康检查
- ✅ 数据库备份与恢复
📊 技术选型
前端技术栈
推荐: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个功能:
- ✅ 用户管理
- ✅ 智能体提示词设置
- ✅ 版本功能设置(Feature Flag)
- ✅ 用户权限和版本设置
我补充的11个功能: 5. 🆕 租户管理(私有化部署) 6. 🆕 LLM模型管理(关键) 7. 🆕 系统配置管理 8. 🆕 监控与日志(关键) 9. 🆕 数据统计与报表(关键) 10. 🆕 成本分析与计费(商业关键) 11. 🆕 公告与通知管理 12. 🆕 帮助文档管理 13. 🆕 反馈与工单管理 14. 🆕 系统健康检查 15. 🆕 数据库备份与恢复
总计:15个功能模块
对系统总体设计的影响
- ✅ 新增独立前端应用(admin-frontend/)
- ✅ 新增独立后端API(/api/admin/*)
- ✅ 扩展权限体系(管理员角色、管理员权限)
- ✅ 扩展数据库Schema(admin_schema)
- ✅ 增强LLM Gateway(使用量统计、成本分析)
- ✅ 新增监控服务(实时监控、错误监控、性能监控)
实施建议
阶段一(P0): 1-2个月
- 用户管理、Feature Flag、LLM模型管理、基础监控
阶段二(P1): 1-2个月
- 智能体管理、数据统计、成本分析、公告管理
阶段三(P2): 1-2个月
- 租户管理、反馈工单、帮助文档、健康检查、备份恢复
下一步建议:
- 确认运营管理端的功能优先级
- 设计管理端的UI原型
- 设计管理端的数据库表结构
- 设计管理端的API接口