提交文件

2026-02-28 15:16:15 +08:00
parent 1a4e50e0a4
commit 44f250f58e
159 changed files with 61268 additions and 0 deletions
--- a/.qoder/repowiki/zh/content/数据库设计/数据字典/系统菜单字段.md
+++ b/.qoder/repowiki/zh/content/数据库设计/数据字典/系统菜单字段.md
@@ -0,0 +1,414 @@
+# 系统菜单字段
+
+<cite>
+**本文档引用的文件**
+- [models.py](file://backend/app/models/models.py)
+- [schemas.py](file://backend/app/schemas/schemas.py)
+- [menus.py](file://backend/app/api/v1/menus.py)
+- [menu_service.py](file://backend/app/services/menu_service.py)
+- [menu.js](file://frontend/src/api/menu.js)
+- [Menus.vue](file://frontend/src/views/system/Menus.vue)
+- [Layout.vue](file://frontend/src/views/Layout.vue)
+- [index.js](file://frontend/src/router/index.js)
+- [security.py](file://backend/app/core/security.py)
+- [create_menu_tables.py](file://backend/create_menu_tables.py)
+</cite>
+
+## 目录
+1. [简介](#简介)
+2. [项目结构](#项目结构)
+3. [核心组件](#核心组件)
+4. [架构概览](#架构概览)
+5. [详细组件分析](#详细组件分析)
+6. [依赖分析](#依赖分析)
+7. [性能考虑](#性能考虑)
+8. [故障排除指南](#故障排除指南)
+9. [结论](#结论)
+
+## 简介
+
+本文档提供了医院绩效系统中系统菜单相关字段的详细数据字典。涵盖了系统菜单表(Menu)、菜单类型枚举(MenuType)等字段定义，详细说明了菜单层级结构、权限控制、路由配置等相关字段。文档包含了菜单树形结构的父子关系和排序机制，提供了菜单权限验证和动态加载的字段设计说明，以及菜单可见性和激活状态的字段约束。同时说明了菜单与功能权限的关联关系。
+
+## 项目结构
+
+系统采用前后端分离架构，菜单管理功能分布在以下层次：
+
+```mermaid
+graph TB
+subgraph "前端层"
+FE_API[菜单API调用]
+FE_VIEW[菜单管理界面]
+FE_ROUTER[前端路由]
+end
+subgraph "后端层"
+API[菜单API路由]
+SERVICE[菜单业务逻辑]
+MODEL[菜单数据模型]
+SCHEMA[数据验证模式]
+end
+subgraph "数据库层"
+DB[(MySQL数据库)]
+end
+FE_API --> API
+FE_VIEW --> FE_API
+FE_ROUTER --> FE_VIEW
+API --> SERVICE
+SERVICE --> MODEL
+MODEL --> DB
+SCHEMA --> API
+```
+
+**图表来源**
+- [menus.py](file://backend/app/api/v1/menus.py#L1-L164)
+- [menu_service.py](file://backend/app/services/menu_service.py#L1-L137)
+- [models.py](file://backend/app/models/models.py#L347-L373)
+
+**章节来源**
+- [menus.py](file://backend/app/api/v1/menus.py#L1-L164)
+- [menu_service.py](file://backend/app/services/menu_service.py#L1-L137)
+- [models.py](file://backend/app/models/models.py#L347-L373)
+
+## 核心组件
+
+### 菜单数据模型
+
+系统菜单采用自引用的树形结构设计，支持无限层级的菜单组织。每个菜单项包含完整的元数据信息，用于前端渲染和权限控制。
+
+### 菜单类型枚举
+
+系统支持两种菜单类型：
+- **菜单(Menu)**: 用于页面导航的主要菜单项
+- **按钮(Button)**: 用于页面内功能按钮的权限控制
+
+### 菜单字段定义
+
+| 字段名 | 数据类型 | 是否可空 | 默认值 | 描述 |
+|--------|----------|----------|--------|------|
+| id | Integer | 否 | 自增 | 菜单唯一标识符 |
+| parent_id | Integer | 是 | NULL | 父菜单ID，自引用外键 |
+| menu_type | Enum | 否 | menu | 菜单类型(MENU/BUTTON) |
+| menu_name | String(100) | 否 | - | 菜单显示名称 |
+| menu_icon | String(50) | 是 | NULL | Element Plus图标名称 |
+| path | String(200) | 否 | - | Vue Router路由路径 |
+| component | String(200) | 是 | NULL | 页面组件路径 |
+| permission | String(100) | 是 | NULL | 权限标识符 |
+| sort_order | Integer | 否 | 0 | 排序权重 |
+| is_visible | Boolean | 否 | TRUE | 是否在菜单中显示 |
+| is_active | Boolean | 否 | TRUE | 菜单是否启用 |
+| created_at | DateTime | 否 | 当前时间 | 创建时间戳 |
+| updated_at | DateTime | 否 | 当前时间 | 更新时间戳 |
+
+**章节来源**
+- [models.py](file://backend/app/models/models.py#L347-L373)
+- [schemas.py](file://backend/app/schemas/schemas.py#L590-L638)
+
+## 架构概览
+
+系统菜单架构采用经典的三层架构模式，实现了完整的菜单生命周期管理：
+
+```mermaid
+sequenceDiagram
+participant Client as 前端客户端
+participant API as 菜单API
+participant Service as 菜单服务
+participant Model as 数据模型
+participant DB as 数据库
+Client->>API : GET /menus/tree?visible_only=true
+API->>Service : get_tree(visible_only)
+Service->>Model : 查询菜单树
+Model->>DB : SQL查询
+DB-->>Model : 菜单数据
+Model-->>Service : 菜单对象
+Service->>Service : 转换为字典结构
+Service-->>API : 菜单树数据
+API-->>Client : JSON响应
+Note over Client,DB : 菜单树形结构加载流程
+```
+
+**图表来源**
+- [menus.py](file://backend/app/api/v1/menus.py#L17-L29)
+- [menu_service.py](file://backend/app/services/menu_service.py#L16-L29)
+
+**章节来源**
+- [menus.py](file://backend/app/api/v1/menus.py#L17-L29)
+- [menu_service.py](file://backend/app/services/menu_service.py#L16-L29)
+
+## 详细组件分析
+
+### 菜单树形结构设计
+
+系统采用自引用关系实现菜单树形结构，支持无限层级嵌套：
+
+```mermaid
+classDiagram
+class Menu {
+Integer id
+Integer parent_id
+MenuType menu_type
+String menu_name
+String menu_icon
+String path
+String component
+String permission
+Integer sort_order
+Boolean is_visible
+Boolean is_active
+DateTime created_at
+DateTime updated_at
+children : Menu[]
+parent : Menu
+}
+class MenuType {
+<<enumeration>>
+MENU
+BUTTON
+}
+Menu --> Menu : "parent_id -> id"
+Menu --> Menu : "children"
+Menu --> MenuType : "uses"
+```
+
+**图表来源**
+- [models.py](file://backend/app/models/models.py#L347-L373)
+- [models.py](file://backend/app/models/models.py#L341-L345)
+
+### 菜单权限控制机制
+
+系统实现了多层次的权限控制体系：
+
+```mermaid
+flowchart TD
+Start([用户请求菜单]) --> CheckAuth["检查用户认证"]
+CheckAuth --> AuthOK{"认证通过?"}
+AuthOK --> |否| Deny["拒绝访问"]
+AuthOK --> |是| LoadTree["加载菜单树"]
+LoadTree --> FilterVisible["过滤可见菜单"]
+FilterVisible --> FilterActive["过滤启用菜单"]
+FilterActive --> SortOrder["按排序字段排序"]
+SortOrder --> BuildTree["构建菜单树"]
+BuildTree --> ReturnMenu["返回菜单数据"]
+Deny --> End([结束])
+ReturnMenu --> End
+style Start fill:#e1f5fe
+style End fill:#ffebee
+style Deny fill:#ffebee
+```
+
+**图表来源**
+- [menu_service.py](file://backend/app/services/menu_service.py#L16-L29)
+- [security.py](file://backend/app/core/security.py#L85-L91)
+
+### 菜单排序机制
+
+系统支持多维度排序控制：
+
+1. **主排序**: `sort_order` 字段，数值越小优先级越高
+2. **次排序**: `id` 字段，确保相同排序值的稳定性
+3. **层级排序**: 顶级菜单优先于子菜单
+
+**章节来源**
+- [menu_service.py](file://backend/app/services/menu_service.py#L24-L24)
+- [menu_service.py](file://backend/app/services/menu_service.py#L49-L49)
+
+### 菜单可见性控制
+
+系统通过两个独立字段控制菜单的显示状态：
+
+| 控制字段 | 类型 | 默认值 | 作用域 | 影响范围 |
+|----------|------|--------|--------|----------|
+| is_visible | Boolean | TRUE | 菜单树渲染 | 前端菜单树显示 |
+| is_active | Boolean | TRUE | 功能启用 | 菜单功能可用性 |
+
+**章节来源**
+- [menu_service.py](file://backend/app/services/menu_service.py#L20-L21)
+- [schemas.py](file://backend/app/schemas/schemas.py#L600-L601)
+
+### 菜单与功能权限关联
+
+系统通过 `permission` 字段实现菜单与功能权限的关联：
+
+```mermaid
+erDiagram
+MENUS {
+int id PK
+int parent_id FK
+enum menu_type
+string menu_name
+string menu_icon
+string path
+string component
+string permission
+int sort_order
+boolean is_visible
+boolean is_active
+datetime created_at
+datetime updated_at
+}
+USERS {
+int id PK
+string username UK
+string password_hash
+string role
+boolean is_active
+datetime last_login
+datetime created_at
+datetime updated_at
+}
+USER_PERMISSIONS {
+int user_id FK
+string permission
+boolean granted
+datetime granted_at
+}
+MENUS ||--o{ MENUS : "parent_id -> id"
+USERS ||--o{ USER_PERMISSIONS : "has"
+```
+
+**图表来源**
+- [models.py](file://backend/app/models/models.py#L347-L373)
+- [security.py](file://backend/app/core/security.py#L94-L109)
+
+**章节来源**
+- [models.py](file://backend/app/models/models.py#L358-L358)
+- [schemas.py](file://backend/app/schemas/schemas.py#L598-L598)
+
+### 前端菜单管理界面
+
+前端提供了完整的菜单管理功能：
+
+```mermaid
+sequenceDiagram
+participant Admin as 管理员
+participant View as 菜单管理界面
+participant API as 菜单API
+participant Service as 菜单服务
+participant DB as 数据库
+Admin->>View : 打开菜单管理页面
+View->>API : 加载菜单列表
+API->>Service : get_list()
+Service->>DB : 查询菜单
+DB-->>Service : 菜单数据
+Service-->>API : 菜单列表
+API-->>View : 返回数据
+View-->>Admin : 显示菜单表格
+Admin->>View : 新建菜单
+View->>API : create_menu()
+API->>Service : create()
+Service->>DB : 插入菜单
+DB-->>Service : 成功
+Service-->>API : 菜单对象
+API-->>View : 返回结果
+View-->>Admin : 显示成功消息
+```
+
+**图表来源**
+- [Menus.vue](file://frontend/src/views/system/Menus.vue#L144-L152)
+- [menu.js](file://frontend/src/api/menu.js#L18-L21)
+
+**章节来源**
+- [Menus.vue](file://frontend/src/views/system/Menus.vue#L1-L265)
+- [menu.js](file://frontend/src/api/menu.js#L1-L37)
+
+## 依赖分析
+
+系统菜单功能涉及多个组件间的复杂依赖关系：
+
+```mermaid
+graph TB
+subgraph "数据层"
+MenuModel[Menu模型]
+MenuType[MenuType枚举]
+end
+subgraph "业务层"
+MenuService[MenuService]
+Security[安全模块]
+end
+subgraph "接口层"
+MenuAPI[菜单API]
+Schema[数据模式]
+end
+subgraph "表现层"
+Frontend[前端界面]
+Router[Vue Router]
+end
+MenuAPI --> MenuService
+MenuService --> MenuModel
+MenuService --> Security
+MenuAPI --> Schema
+Frontend --> MenuAPI
+Router --> Frontend
+MenuModel --> MenuType
+```
+
+**图表来源**
+- [models.py](file://backend/app/models/models.py#L341-L345)
+- [models.py](file://backend/app/models/models.py#L347-L373)
+- [menu_service.py](file://backend/app/services/menu_service.py#L1-L137)
+- [menus.py](file://backend/app/api/v1/menus.py#L1-L164)
+
+**章节来源**
+- [models.py](file://backend/app/models/models.py#L341-L345)
+- [models.py](file://backend/app/models/models.py#L347-L373)
+- [menu_service.py](file://backend/app/services/menu_service.py#L1-L137)
+- [menus.py](file://backend/app/api/v1/menus.py#L1-L164)
+
+## 性能考虑
+
+### 数据库索引优化
+
+系统为菜单表建立了多个关键索引以提升查询性能：
+
+| 索引名称 | 字段组合 | 用途 | 性能影响 |
+|----------|----------|------|----------|
+| idx_menu_parent | parent_id | 父子关系查询 | 快速定位子菜单 |
+| idx_menu_type | menu_type | 类型过滤查询 | 快速筛选菜单类型 |
+| idx_menu_visible | is_visible | 可见性过滤 | 快速筛选显示菜单 |
+
+### 查询优化策略
+
+1. **延迟加载**: 使用 `selectinload` 优化N+1查询问题
+2. **条件过滤**: 在服务层统一处理查询条件
+3. **排序优化**: 利用复合索引支持排序查询
+
+### 前端性能优化
+
+1. **菜单树缓存**: 避免重复加载相同的菜单树
+2. **懒加载**: 路由组件按需加载
+3. **虚拟滚动**: 大数据量时使用虚拟滚动
+
+## 故障排除指南
+
+### 常见问题及解决方案
+
+| 问题类型 | 症状 | 可能原因 | 解决方案 |
+|----------|------|----------|----------|
+| 菜单不显示 | 菜单树为空 | is_visible=false 或 is_active=false | 检查菜单状态字段 |
+| 菜单排序异常 | 菜单顺序错误 | sort_order字段冲突 | 重新设置排序值 |
+| 子菜单无法删除 | 删除报错 | 存在子菜单依赖 | 先删除子菜单再删除父菜单 |
+| 权限控制失效 | 无权限访问 | permission字段缺失 | 添加正确的权限标识符 |
+
+### 调试工具
+
+1. **数据库查询**: 使用SQL查询验证菜单状态
+2. **API测试**: 使用Postman测试菜单接口
+3. **浏览器调试**: 检查前端控制台错误
+
+**章节来源**
+- [menu_service.py](file://backend/app/services/menu_service.py#L86-L98)
+- [security.py](file://backend/app/core/security.py#L94-L109)
+
+## 结论
+
+系统菜单字段设计体现了良好的软件工程实践，通过清晰的数据模型、完善的权限控制和高效的查询机制，实现了灵活的菜单管理功能。自引用的树形结构设计支持复杂的菜单层级，而权限标识符则为细粒度的权限控制提供了基础。
+
+系统的关键优势包括：
+- **灵活性**: 支持无限层级的菜单结构
+- **可扩展性**: 易于添加新的菜单类型和字段
+- **安全性**: 多层次的权限控制机制
+- **易用性**: 完整的前端管理界面
+
+未来可以考虑的改进方向：
+- 增加菜单访问日志功能
+- 实现菜单模板化管理
+- 添加菜单权限继承机制
+- 优化大数据量场景下的性能表现