完善项目权限前置依赖保存校验

- 以接口权限定义中的 prerequisite_permissions 作为前置依赖单一事实源，生成运行时前置权限映射\n- 保存项目角色权限前预检缺失前置权限与受影响下游权限，未确认时返回 409 调整详情\n- 确认保存时自动合并补齐前置权限与取消下游权限，并提供有效权限矩阵读取接口\n- 前端角色权限编辑改为保存时执行依赖校验，弹窗展示需补充前置权限和受影响下游权限\n- 新增编辑权限取消按钮，清理权限选择即时确认弹窗残留\n- 补充后端接口测试、前端权限编辑测试与优化设计文档

frontend/src/api/projectPermissions.ts

@@ -2,6 +2,7 @@ import { apiGet, apiPut, apiPost, apiDelete, type ApiRequestConfig } from "./axi
 import type {
   ApiEndpointPermissionsResponse,
   ApiEndpointPermissionsUpdate,
+  ApiOperation,
   PermissionMetricsResponse,
   CacheStatsResponse,
   AlertsResponse,
@@ -21,11 +22,17 @@ export const fetchApiEndpointPermissions = (studyId: string, config?: ApiRequest
 export const fetchMyApiEndpointPermissions = (studyId: string, config?: ApiRequestConfig) =>
   apiGet<ApiEndpointPermissionsResponse>(`/api/v1/studies/${studyId}/api-permissions/me`, config);
 
-export const updateApiEndpointPermissions = (studyId: string, payload: ApiEndpointPermissionsUpdate) =>
-  apiPut<ApiEndpointPermissionsResponse>(`/api/v1/studies/${studyId}/api-permissions`, payload);
+export const updateApiEndpointPermissions = (
+  studyId: string,
+  payload: ApiEndpointPermissionsUpdate,
+  options?: { confirm_prerequisite_adjustments?: boolean },
+) =>
+  apiPut<ApiEndpointPermissionsResponse>(`/api/v1/studies/${studyId}/api-permissions`, payload, {
+    params: options?.confirm_prerequisite_adjustments ? { confirm_prerequisite_adjustments: true } : undefined,
+  });
 
 export const fetchApiOperations = () =>
-  apiGet<{ operations: Array<{ operation_key: string; module: string; action: string; description: string; default_roles: string[] }> }>(`/api/v1/api-permissions/operations`);
+  apiGet<{ operations: ApiOperation[] }>(`/api/v1/api-permissions/operations`);
 
 // 权限系统监控API
 export const fetchPermissionMetrics = () =>

frontend/src/components/ApiEndpointPermissions.test.ts

@@ -10,11 +10,11 @@ vi.mock("@/api/projectPermissions", () => ({
   fetchApiOperations: vi.fn().mockResolvedValue({ data: { operations: [] } }),
   fetchPermissionTemplates: vi.fn().mockResolvedValue({
     data: [
-      { category: "PM", name: "PM", description: "项目负责人，统筹项目全局，协调进度、资源与关键决策。" },
-      { category: "CRA", name: "CRA", description: "负责各中心临床监查执行，跟进现场质量、数据和问题闭环。" },
-      { category: "CTA", name: "CTA", description: "负责合同、药品及相关项目事务管理，保障执行支持与物资协同。" },
-      { category: "QA", name: "QA", description: "负责医学审核与稽查，关注质量风险、合规性和医学一致性。" },
       { category: "PV", name: "PV", description: "负责药物警戒相关工作，跟踪安全性事件并支持风险评估。" },
+      { category: "QA", name: "QA", description: "负责医学审核与稽查，关注质量风险、合规性和医学一致性。" },
+      { category: "CTA", name: "CTA", description: "负责合同、药品及相关项目事务管理，保障执行支持与物资协同。" },
+      { category: "CRA", name: "CRA", description: "负责各中心临床监查执行，跟进现场质量、数据和问题闭环。" },
+      { category: "PM", name: "PM", description: "项目负责人，统筹项目全局，协调进度、资源与关键决策。" },
     ],
   }),
 }));
@@ -96,7 +96,7 @@ describe("ApiEndpointPermissions.vue", () => {
     expect(source).not.toContain(':label="role"');
   });
 
-  it("sorts matrix role columns with the role list order", async () => {
+  it("pins PM first in matrix role columns even when templates return PM last", async () => {
     const wrapper = mount(ApiEndpointPermissions, {
       props: {
         project: { id: "test-id", name: "Test Project" },
@@ -117,7 +117,7 @@ describe("ApiEndpointPermissions.vue", () => {
     });
     await vi.dynamicImportSettled();
 
-    expect((wrapper.vm as any).roles).toEqual(["PM", "CRA", "CTA", "QA", "PV"]);
+    expect((wrapper.vm as any).roles).toEqual(["PM", "PV", "QA", "CTA", "CRA"]);
   });
 
   it("sorts project permission modules by sidebar menu order", async () => {

frontend/src/components/PermissionTemplateSelector.test.ts

@@ -20,6 +20,7 @@ describe("PermissionTemplateSelector", () => {
   it("reads current project permissions by role key, not by role label", () => {
     const source = readSource();
 
+    expect(source).toContain('v-for="template in sortedTemplates"');
     expect(source).toContain('<span class="card-name">{{ template.name }}</span>');
     expect(source).toContain("refreshKey?: number;");
     expect(source).toContain("watch(() => props.refreshKey, loadTemplates);");
@@ -32,6 +33,15 @@ describe("PermissionTemplateSelector", () => {
     expect(source).toContain("emit('edit-role', template.category!)");
   });
 
+  it("sorts role cards with the shared role template order", () => {
+    const source = readSource();
+
+    expect(source).toContain("useRoleTemplateMeta");
+    expect(source).toContain("compareRolesByTemplateOrder");
+    expect(source).toContain("const sortedTemplates = computed");
+    expect(source).toContain("compareRolesByTemplateOrder(a.category, b.category)");
+  });
+
   it("does not keep hard-coded preset role labels or icons", () => {
     const source = readSource();
 

frontend/src/components/PermissionTemplateSelector.vue

@@ -9,7 +9,7 @@
 
     <div class="template-grid">
       <div
-        v-for="template in templates"
+        v-for="template in sortedTemplates"
         :key="template.id"
         class="template-card"
         :class="{ inactive: template.category && !isRoleActive(template.category) }"
@@ -61,12 +61,13 @@
 </template>
 
 <script setup lang="ts">
-import { ref, onMounted, watch } from "vue";
+import { computed, ref, onMounted, watch } from "vue";
 import { ElMessage } from "element-plus";
 import {
   fetchPermissionTemplates,
   type PermissionTemplate,
 } from "@/api/projectPermissions";
+import { useRoleTemplateMeta } from "@/composables/useRoleTemplateMeta";
 
 const props = defineProps<{
   studyId: string;
@@ -80,6 +81,16 @@ const emit = defineEmits<{
 }>();
 
 const templates = ref<PermissionTemplate[]>([]);
+const { compareRolesByTemplateOrder } = useRoleTemplateMeta();
+
+const sortedTemplates = computed(() =>
+  [...templates.value].sort((a, b) => {
+    if (a.category && b.category) return compareRolesByTemplateOrder(a.category, b.category);
+    if (a.category) return -1;
+    if (b.category) return 1;
+    return 0;
+  })
+);
 
 const roleIcon = (category: string | null) => {
   const icons: Record<string, string> = {

frontend/src/types/api.ts

@@ -124,6 +124,7 @@ export interface Site {
   pi_name?: string | null;
   phone?: string | null;
   contact?: string | null;
+  contact_display?: string | null;
   contact_phone?: string | null;
   enrollment_target?: number | null;
   enrollment_plan_start_date?: string | null;
@@ -148,6 +149,15 @@ export interface ApiEndpointPermissionsUpdate {
   };
 }
 
+export interface ApiOperation {
+  operation_key: string;
+  module: string;
+  action: string;
+  description: string;
+  default_roles: string[];
+  prerequisite_permissions: string[];
+}
+
 // 监控指标
 export interface PermissionCheckMetrics {
   total_checks: number;

frontend/src/views/admin/PermissionManagement.test.ts

@@ -157,6 +157,28 @@ describe("permission management custom roles", () => {
     expect(source).toContain("compareRolesByTemplateOrder(a.key, b.key)");
   });
 
+  it("pins PM first in role list active role management and role permission editor", () => {
+    const source = readSource();
+    const listTabStart = source.indexOf("<!-- 标签页：角色列表 -->");
+    const listTabEnd = source.indexOf("<!-- 标签页：生效管理 -->", listTabStart);
+    const listTabSource = source.slice(listTabStart, listTabEnd);
+    const activeTabStart = source.indexOf("<!-- 标签页：生效管理 -->");
+    const activeTabEnd = source.indexOf("<!-- 标签页：编辑权限 -->", activeTabStart);
+    const activeTabSource = source.slice(activeTabStart, activeTabEnd);
+    const editTabStart = source.indexOf("<!-- 标签页：编辑权限 -->");
+    const editTabEnd = source.indexOf("</el-tab-pane>", editTabStart);
+    const editTabSource = source.slice(editTabStart, editTabEnd);
+
+    expect(source).toContain("const { roleLabel, roleDescription, roleIcon, compareRolesByTemplateOrder, loadRoleTemplates } = useRoleTemplateMeta();");
+    expect(source).toContain("const sortedTemplates = computed");
+    expect(source).toContain("compareRolesByTemplateOrder(a.category, b.category)");
+    expect(listTabSource).toContain(':data="sortedTemplates"');
+    expect(activeTabSource).toContain("v-for=\"role in roleOptions\"");
+    expect(editTabSource).toContain("v-for=\"role in roleOptions\"");
+    expect(source).toContain("options.sort((a, b) => compareRolesByTemplateOrder(a.key, b.key));");
+    expect(source).not.toContain("compareRoleManagementRoles");
+  });
+
   it("submits only the selected role from role editor saves", () => {
     const source = readSource();
 
@@ -165,6 +187,61 @@ describe("permission management custom roles", () => {
     expect(source).not.toContain("const payload = flattenMatrix(apiMatrix.value, { includePm: isAdmin.value });");
   });
 
+  it("provides a cancel action for unsaved role permission edits", () => {
+    const source = readSource();
+    const actionsStart = source.indexOf('<div class="drawer-tab-actions">');
+    const actionsEnd = source.indexOf("</div>", actionsStart);
+    const actionsSource = source.slice(actionsStart, actionsEnd);
+
+    expect(source).toContain("const cancelRoleEditor = () =>");
+    expect(actionsSource).toContain("@click=\"cancelRoleEditor\"");
+    expect(actionsSource).toContain("取消");
+    expect(source).toContain("roleEditorDirtyGuard.syncBaseline();");
+  });
+
+  it("checks prerequisite permission dependencies only when saving role permission edits", () => {
+    const source = readSource();
+
+    expect(source).toContain("previewRolePrerequisiteAdjustments");
+    expect(source).toContain("handleRolePermissionChange");
+    expect(source).toContain('@change="(v: boolean) => handleRolePermissionChange(op, v)"');
+    expect(source).toContain("roleEditorDraft.value = { ...roleEditorDraft.value, [op.operation_key]: allowed };");
+    expect(source).toContain("openPrereqCheck");
+    expect(source).toContain("const passed = await openPrereqCheck();");
+    expect(source).toContain("if (!passed) return;");
+    expect(source).toContain("prereqCheckVisible");
+    expect(source).toContain("prereqAdjustments");
+    expect(source).toContain("prereqMissingItems");
+    expect(source).toContain("prereqRemoveItems");
+    expect(source).toContain("confirmPrereqAndSave");
+    expect(source).toContain("updateApiEndpointPermissions(selectedStudyId.value, payload, { confirm_prerequisite_adjustments: true })");
+    expect(source).toContain("权限依赖校验");
+    expect(source).toContain("依赖关系");
+    expect(source).toContain("需补充前置权限");
+    expect(source).toContain("一键授权全部前置");
+    expect(source).toContain("确认调整并保存");
+    expect(source).toContain("roleOperationActionLabel");
+    expect(source).toContain("rolePermissionDisplayLabel");
+    expect(source).toContain("${roleOperationActionLabel(operationKey)}｜${roleOperationLabel(operationKey)}");
+    expect(source).not.toContain("renderPrerequisiteAdjustmentMessage");
+    expect(source).not.toContain("permission-prerequisite-dialog");
+    expect(source).not.toContain("permission-adjustment-row");
+    expect(source).not.toContain("permission-dependency-flow");
+    expect(source).not.toContain("permission-dependency-node--prerequisite");
+    expect(source).not.toContain("permission-dependency-node--dependent");
+    expect(source).not.toContain("prerequisiteAdjustmentMode");
+    expect(source).not.toContain("prerequisiteAdjustmentDialogCopy");
+    expect(source).not.toContain("roleEditorPrerequisiteConfirmed");
+    expect(source).not.toContain("同步授权依赖权限确认");
+    expect(source).not.toContain("取消权限影响确认");
+    expect(source).not.toContain("授权以下权限需要先授权其依赖权限");
+    expect(source).not.toContain("取消以下权限会影响依赖它的权限");
+    expect(source).not.toContain("确认后同步取消受影响权限。");
+    expect(source).not.toContain("permission-adjustment-summary");
+    expect(source).not.toContain("permission-adjustment-note");
+    expect(source).not.toContain("const confirmed = await confirmPrerequisiteAdjustmentsIfNeeded();");
+  });
+
   it("submits only editable metadata when saving an existing role template", () => {
     const source = readSource();
     const updateBuilderStart = source.indexOf("const buildTemplateUpdatePayload = () =>");

frontend/src/views/admin/PermissionManagement.vue

@@ -245,7 +245,7 @@
 
           <!-- 标签页：角色列表 -->
           <el-tab-pane label="角色列表" name="list">
-            <el-table :data="templates" v-loading="templatesLoading" stripe class="template-table">
+            <el-table :data="sortedTemplates" v-loading="templatesLoading" stripe class="template-table">
               <el-table-column prop="name" label="角色名称" min-width="140">
                 <template #default="{ row }">
                   <span class="template-name">{{ roleDisplayName(row) }}</span>
@@ -364,7 +364,7 @@
                               <el-checkbox
                                 :model-value="roleEditorDraft[op.operation_key] ?? false"
                                 :disabled="!canEditSelectedRole"
-                                @change="(v: boolean) => roleEditorDraft[op.operation_key] = v"
+                                @change="(v: boolean) => handleRolePermissionChange(op, v)"
                               />
                               <el-tag :type="opTagType(op)" size="small" class="op-action-tag" effect="light">{{ opActionLabel(op) }}</el-tag>
                               <span class="op-desc">{{ op.description || op.operation_key }}</span>
@@ -386,15 +386,17 @@
           <el-button v-else-if="templateDrawerTab === 'active'" type="primary" :loading="activeRolesSaving" @click="saveActiveRoles">
             保存
           </el-button>
-          <el-button
-            v-else-if="templateDrawerTab === 'edit-role' && editingRole"
-            type="primary"
-            :loading="roleEditorSaving"
-            :disabled="!canEditSelectedRole"
-            @click="saveRoleEditor"
-          >
-            保存 {{ roleLabel(editingRole) }} 权限
-          </el-button>
+          <template v-else-if="templateDrawerTab === 'edit-role' && editingRole">
+            <el-button @click="cancelRoleEditor">取消</el-button>
+            <el-button
+              type="primary"
+              :loading="roleEditorSaving"
+              :disabled="!canEditSelectedRole"
+              @click="saveRoleEditor"
+            >
+              保存 {{ roleLabel(editingRole) }} 权限
+            </el-button>
+          </template>
         </div>
       </div>
     </el-drawer>
@@ -447,12 +449,132 @@
       </template>
     </el-dialog>
 
+    <!-- 权限校验 Dialog -->
+    <el-dialog
+      v-model="prereqCheckVisible"
+      width="520px"
+      :close-on-click-modal="false"
+      :show-close="prereqCheckStep === 'failed'"
+      class="prereq-check-dialog"
+      title="权限依赖校验"
+      align-center
+    >
+      <!-- 校验步骤动画 -->
+      <div class="prereq-check-body">
+        <div class="prereq-check-steps">
+          <div
+            v-for="(item, i) in prereqCheckItems"
+            :key="i"
+            class="prereq-check-step"
+            :class="`prereq-check-step--${item.status}`"
+          >
+            <span class="prereq-step-icon">
+              <svg v-if="item.status === 'ok'" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.5"><polyline points="20 6 9 17 4 12"/></svg>
+              <svg v-else-if="item.status === 'fail'" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.5"><line x1="18" y1="6" x2="6" y2="18"/><line x1="6" y1="6" x2="18" y2="18"/></svg>
+              <svg v-else-if="item.status === 'warn'" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.5"><path d="M10.29 3.86L1.82 18a2 2 0 0 0 1.71 3h16.94a2 2 0 0 0 1.71-3L13.71 3.86a2 2 0 0 0-3.42 0z"/><line x1="12" y1="9" x2="12" y2="13"/><line x1="12" y1="17" x2="12.01" y2="17"/></svg>
+              <span v-else class="prereq-step-spinner" />
+            </span>
+            <span class="prereq-step-label">{{ item.label }}</span>
+          </div>
+        </div>
+
+        <!-- 通过状态 -->
+        <transition name="prereq-result">
+          <div v-if="prereqCheckStep === 'passed'" class="prereq-result prereq-result--pass">
+            <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M22 11.08V12a10 10 0 1 1-5.93-9.14"/><polyline points="22 4 12 14.01 9 11.01"/></svg>
+            <span>所有权限依赖校验通过</span>
+          </div>
+        </transition>
+
+        <!-- 失败：缺少前置权限 -->
+        <transition name="prereq-result">
+          <div v-if="prereqCheckStep === 'failed'" class="prereq-issues">
+            <div class="prereq-issues-header">
+              <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><circle cx="12" cy="12" r="10"/><line x1="12" y1="8" x2="12" y2="12"/><line x1="12" y1="16" x2="12.01" y2="16"/></svg>
+              <span>发现 {{ prereqMissingItems.length + prereqRemoveItems.length }} 项依赖冲突，需要处理后才能保存</span>
+            </div>
+
+            <!-- 缺少前置权限 -->
+            <div v-if="prereqMissingItems.length" class="prereq-section">
+              <div class="prereq-section-title">
+                <span class="prereq-section-badge prereq-section-badge--add">需补充前置权限</span>
+                <el-button size="small" type="primary" @click="grantAllPrereqs" class="prereq-grant-all-btn">
+                  一键授权全部前置
+                </el-button>
+              </div>
+              <div class="prereq-item-list">
+                <div v-for="(item, i) in prereqMissingItems" :key="i" class="prereq-item prereq-item--missing">
+                  <div class="prereq-item-info">
+                    <div class="prereq-item-row">
+                      <span class="prereq-item-chip prereq-item-chip--enabled">已启用</span>
+                      <span class="prereq-item-name">{{ rolePermissionDisplayLabel(item.dependentKey) }}</span>
+                    </div>
+                    <div class="prereq-item-arrow">依赖</div>
+                    <div class="prereq-item-row">
+                      <span class="prereq-item-chip prereq-item-chip--missing">缺少</span>
+                      <span class="prereq-item-name">{{ rolePermissionDisplayLabel(item.prereqKey) }}</span>
+                    </div>
+                  </div>
+                  <el-button
+                    size="small"
+                    type="success"
+                    :disabled="roleEditorDraft[item.prereqKey] === true"
+                    @click="grantSinglePrereq(item.prereqKey)"
+                  >授权</el-button>
+                </div>
+              </div>
+            </div>
+
+            <!-- 需取消的下游权限 -->
+            <div v-if="prereqRemoveItems.length" class="prereq-section">
+              <div class="prereq-section-title">
+                <span class="prereq-section-badge prereq-section-badge--remove">受影响的下游权限</span>
+              </div>
+              <div class="prereq-item-list">
+                <div v-for="(item, i) in prereqRemoveItems" :key="i" class="prereq-item prereq-item--remove">
+                  <div class="prereq-item-info">
+                    <div class="prereq-item-row">
+                      <span class="prereq-item-chip prereq-item-chip--disabled">已禁用</span>
+                      <span class="prereq-item-name">{{ rolePermissionDisplayLabel(item.prereqKey) }}</span>
+                    </div>
+                    <div class="prereq-item-arrow">影响</div>
+                    <div class="prereq-item-row">
+                      <span class="prereq-item-chip prereq-item-chip--will-remove">将同步取消</span>
+                      <span class="prereq-item-name">{{ rolePermissionDisplayLabel(item.dependentKey) }}</span>
+                    </div>
+                  </div>
+                </div>
+              </div>
+            </div>
+          </div>
+        </transition>
+      </div>
+
+      <template #footer>
+        <div v-if="prereqCheckStep === 'failed'" class="prereq-dialog-footer">
+          <el-button @click="prereqCheckVisible = false">取消保存</el-button>
+          <el-button
+            v-if="prereqRemoveItems.length && !prereqMissingItems.length"
+            type="primary"
+            :loading="prereqSaving"
+            @click="confirmPrereqAndSave"
+          >确认调整并保存</el-button>
+          <el-button
+            v-if="prereqMissingItems.length === 0 && prereqRemoveItems.length === 0"
+            type="primary"
+            :loading="prereqSaving"
+            @click="confirmPrereqAndSave"
+          >已处理，保存</el-button>
+        </div>
+      </template>
+    </el-dialog>
+
     <!-- 角色权限编辑抽屉已合并至角色管理抽屉 -->
   </div>
 </template>
 
 <script setup lang="ts">
-import { ref, computed, onMounted, watch, reactive } from "vue";
+import { ref, computed, onMounted, watch, reactive, nextTick } from "vue";
 import { useRoute, useRouter } from "vue-router";
 import { ElMessage, ElMessageBox } from "element-plus";
 import { Files, Search, ArrowRight } from "@element-plus/icons-vue";
@@ -798,6 +920,15 @@ const activeRolesLoading = ref(false);
 const activeRolesSaving = ref(false);
 const activeRolesDirtyGuard = useDrawerDirtyGuard(() => activeRolesDraft.value);
 
+const sortedTemplates = computed(() =>
+  [...templates.value].sort((a, b) => {
+    if (a.category && b.category) return compareRolesByTemplateOrder(a.category, b.category);
+    if (a.category) return -1;
+    if (b.category) return 1;
+    return 0;
+  })
+);
+
 const roleOptions = computed(() => {
   const options = templates.value.filter((template) => template.category).map((template) => ({
     key: template.category!,
@@ -1046,6 +1177,7 @@ interface RoleEditorOp {
   module: string;
   action: string;
   description: string;
+  prerequisite_permissions: string[];
 }
 
 interface RoleEditorSection {
@@ -1053,6 +1185,11 @@ interface RoleEditorSection {
   ops: RoleEditorOp[];
 }
 
+interface RolePrerequisiteAdjustments {
+  add: Record<string, string[]>;
+  remove: Record<string, string[]>;
+}
+
 const editingRole = ref("");
 const roleEditorSearch = ref("");
 const roleEditorDraft = ref<Record<string, boolean>>({});
@@ -1176,6 +1313,90 @@ const roleEditorModuleCount = (sections: RoleEditorSection[]): number =>
 const roleEditorEnabledCount = (ops: RoleEditorOp[]): number =>
   ops.filter((op) => roleEditorDraft.value[op.operation_key]).length;
 
+const operationByKey = computed(() => {
+  const map: Record<string, RoleEditorOp> = {};
+  for (const op of allOperations.value) map[op.operation_key] = op;
+  return map;
+});
+
+const roleOperationLabel = (operationKey: string): string =>
+  operationByKey.value[operationKey]?.description || operationKey;
+
+const roleOperationActionLabel = (operationKey: string): string => {
+  const op = operationByKey.value[operationKey];
+  if (!op) return "授权";
+  const verb = getOpVerb(op);
+  if (verb === "read") return "读取";
+  if (verb === "delete") return "删除";
+  return "写入";
+};
+
+const rolePermissionDisplayLabel = (operationKey: string): string =>
+  `${roleOperationActionLabel(operationKey)}｜${roleOperationLabel(operationKey)}`;
+
+const previewRolePrerequisiteAdjustments = (draft: Record<string, boolean>): RolePrerequisiteAdjustments => {
+  const add: Record<string, string[]> = {};
+  const remove: Record<string, string[]> = {};
+  const baseline: Record<string, boolean> = {};
+  const candidate = { ...draft };
+  const explicitlyDenied = new Set<string>();
+
+  const role = editingRole.value;
+  if (apiMatrix.value && apiMatrix.value[role]) {
+    for (const [key, val] of Object.entries(apiMatrix.value[role] as Record<string, any>)) {
+      baseline[key] = typeof val === "boolean" ? val : val.allowed;
+    }
+  }
+
+  for (const [key, allowed] of Object.entries(draft)) {
+    if (baseline[key] !== allowed && !allowed) explicitlyDenied.add(key);
+  }
+
+  // 先补充缺失的前置权限（add 优先）
+  let changed = true;
+  while (changed) {
+    changed = false;
+    for (const op of allOperations.value) {
+      if (!candidate[op.operation_key]) continue;
+      for (const prereq of op.prerequisite_permissions) {
+        if (candidate[prereq]) continue;
+        const prerequisites = add[op.operation_key] || [];
+        if (!prerequisites.includes(prereq)) prerequisites.push(prereq);
+        add[op.operation_key] = prerequisites;
+        candidate[prereq] = true;
+        explicitlyDenied.delete(prereq); // 补回来的前置不再是"明确禁用"
+        changed = true;
+      }
+    }
+  }
+
+  // 再级联禁用受影响的下游权限（remove）
+  changed = true;
+  while (changed) {
+    changed = false;
+    for (const op of allOperations.value) {
+      if (!candidate[op.operation_key] || explicitlyDenied.has(op.operation_key)) continue;
+      const deniedPrereq = op.prerequisite_permissions.find((key) => explicitlyDenied.has(key));
+      if (!deniedPrereq) continue;
+      const dependents = remove[deniedPrereq] || [];
+      if (!dependents.includes(op.operation_key)) dependents.push(op.operation_key);
+      remove[deniedPrereq] = dependents;
+      candidate[op.operation_key] = false;
+      explicitlyDenied.add(op.operation_key);
+      changed = true;
+    }
+  }
+
+  return { add, remove };
+};
+
+const hasPrerequisiteAdjustments = (adjustments: RolePrerequisiteAdjustments): boolean =>
+  Object.keys(adjustments.add).length > 0 || Object.keys(adjustments.remove).length > 0;
+
+const handleRolePermissionChange = (op: RoleEditorOp, allowed: boolean) => {
+  roleEditorDraft.value = { ...roleEditorDraft.value, [op.operation_key]: allowed };
+};
+
 const canEditSelectedRole = computed(() => {
   if (editingRole.value === "ADMIN") return false;
   if (isAdmin.value) return true;
@@ -1221,12 +1442,131 @@ const initRoleEditor = () => {
   roleEditorDirtyGuard.syncBaseline();
 };
 
+const cancelRoleEditor = () => {
+  editingRole.value = "";
+  roleEditorSearch.value = "";
+  roleEditorDraft.value = {};
+  roleEditorDirtyGuard.syncBaseline();
+};
+
+// ── 权限校验 Dialog ──
+const prereqCheckVisible = ref(false);
+const prereqCheckStep = ref<"checking" | "passed" | "failed">("checking");
+const prereqCheckItems = ref<Array<{ label: string; status: "checking" | "ok" | "fail" | "warn" }>>([]);
+const prereqAdjustments = ref<RolePrerequisiteAdjustments>({ add: {}, remove: {} });
+const prereqSaving = ref(false);
+
+const prereqCheckLabels = [
+  "分析已启用权限依赖关系",
+  "检查前置权限完整性",
+  "检查下游权限一致性",
+];
+
+const openPrereqCheck = async (): Promise<boolean> => {
+  prereqCheckVisible.value = true;
+  prereqCheckStep.value = "checking";
+  prereqCheckItems.value = prereqCheckLabels.map((label) => ({ label, status: "checking" }));
+  prereqAdjustments.value = { add: {}, remove: {} };
+
+  // 逐步动画显示校验过程
+  for (let i = 0; i < prereqCheckLabels.length; i++) {
+    await new Promise((r) => setTimeout(r, 320 + i * 180));
+    prereqCheckItems.value[i].status = "ok";
+  }
+
+  const adjustments = previewRolePrerequisiteAdjustments(roleEditorDraft.value);
+  prereqAdjustments.value = adjustments;
+
+  if (!hasPrerequisiteAdjustments(adjustments)) {
+    prereqCheckStep.value = "passed";
+    await new Promise((r) => setTimeout(r, 600));
+    prereqCheckVisible.value = false;
+    return true;
+  }
+
+  // 标记状态：有缺失前置 → 红叉；纯下游受影响 → 黄色警告
+  const hasAdd = Object.keys(adjustments.add).length > 0;
+  for (const item of prereqCheckItems.value) {
+    item.status = hasAdd ? "fail" : "warn";
+  }
+  prereqCheckStep.value = "failed";
+  return false;
+};
+
+const prereqMissingItems = computed(() => {
+  const items: Array<{ dependentKey: string; prereqKey: string }> = [];
+  for (const [dependentKey, prereqs] of Object.entries(prereqAdjustments.value.add)) {
+    for (const prereqKey of prereqs) {
+      items.push({ dependentKey, prereqKey });
+    }
+  }
+  return items;
+});
+
+const prereqRemoveItems = computed(() => {
+  const items: Array<{ prereqKey: string; dependentKey: string }> = [];
+  for (const [prereqKey, dependents] of Object.entries(prereqAdjustments.value.remove)) {
+    for (const dependentKey of dependents) {
+      items.push({ prereqKey, dependentKey });
+    }
+  }
+  return items;
+});
+
+const markAllStepsOk = () => {
+  prereqCheckItems.value = prereqCheckItems.value.map((item) => ({ ...item, status: "ok" as const }));
+};
+
+const grantSinglePrereq = (prereqKey: string) => {
+  roleEditorDraft.value = { ...roleEditorDraft.value, [prereqKey]: true };
+  prereqAdjustments.value = previewRolePrerequisiteAdjustments(roleEditorDraft.value);
+  if (!hasPrerequisiteAdjustments(prereqAdjustments.value)) {
+    markAllStepsOk();
+    prereqCheckStep.value = "passed";
+    setTimeout(() => confirmPrereqAndSave(), 800);
+  }
+};
+
+const grantAllPrereqs = () => {
+  const next = { ...roleEditorDraft.value };
+  for (const prereqs of Object.values(prereqAdjustments.value.add)) {
+    for (const p of prereqs) next[p] = true;
+  }
+  roleEditorDraft.value = next;
+  prereqAdjustments.value = previewRolePrerequisiteAdjustments(next);
+  markAllStepsOk();
+  prereqCheckStep.value = "passed";
+  setTimeout(() => confirmPrereqAndSave(), 800);
+};
+
+const confirmPrereqAndSave = async () => {
+  prereqSaving.value = true;
+  try {
+    const payload = flattenRolePermissions(editingRole.value, roleEditorDraft.value);
+    const res = await updateApiEndpointPermissions(selectedStudyId.value, payload, { confirm_prerequisite_adjustments: true });
+    apiMatrix.value = res.data;
+    const savedRole = editingRole.value;
+    prereqCheckVisible.value = false;
+    editingRole.value = "";
+    roleEditorDirtyGuard.syncBaseline();
+    ElMessage.success(`${roleLabel(savedRole)} 权限已保存`);
+  } catch (error: any) {
+    ElMessage.error(error?.response?.data?.detail?.message || "保存失败");
+  } finally {
+    prereqSaving.value = false;
+  }
+};
+
 const saveRoleEditor = async () => {
   if (!selectedStudyId.value || !apiMatrix.value) return;
   if (!canEditSelectedRole.value) {
     ElMessage.warning("当前角色权限不可修改");
     return;
   }
+  const passed = await openPrereqCheck();
+  if (!passed) return; // Dialog 保持打开，等用户操作
+
+  // 校验通过，直接保存
   roleEditorSaving.value = true;
   try {
     const payload = flattenRolePermissions(editingRole.value, roleEditorDraft.value);
@@ -1236,8 +1576,9 @@ const saveRoleEditor = async () => {
     editingRole.value = "";
     roleEditorDirtyGuard.syncBaseline();
     ElMessage.success(`${roleLabel(savedRole)} 权限已保存`);
-  } catch {
-    ElMessage.error("保存失败");
+  } catch (error: any) {
+    if (error === "cancel" || error === "close") return;
+    ElMessage.error(error?.response?.data?.detail?.message || "保存失败");
   } finally {
     roleEditorSaving.value = false;
   }
@@ -2020,3 +2361,252 @@ onMounted(async () => {
   color: #1e293b;
 }
 </style>
+
+<style>
+/* ══════════════════════════════════════
+   权限依赖校验 Dialog
+══════════════════════════════════════ */
+.prereq-check-body {
+  padding: 4px 0 8px;
+}
+
+.prereq-check-steps {
+  display: flex;
+  flex-direction: column;
+  gap: 10px;
+  margin-bottom: 20px;
+}
+
+.prereq-check-step {
+  display: flex;
+  align-items: center;
+  gap: 10px;
+  padding: 10px 14px;
+  border-radius: 8px;
+  background: #f8fafc;
+  border: 1px solid #e8edf3;
+  transition: all 0.3s ease;
+  font-size: 14px;
+  color: #64748b;
+}
+
+.prereq-check-step--ok {
+  background: #f0fdf4;
+  border-color: #bbf7d0;
+  color: #15803d;
+}
+
+.prereq-check-step--fail {
+  background: #fff7ed;
+  border-color: #fed7aa;
+  color: #c2410c;
+}
+
+.prereq-check-step--warn {
+  background: #fefce8;
+  border-color: #fde68a;
+  color: #92400e;
+}
+
+.prereq-step-icon {
+  width: 20px;
+  height: 20px;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  flex-shrink: 0;
+}
+
+.prereq-step-icon svg {
+  width: 16px;
+  height: 16px;
+}
+
+.prereq-check-step--ok .prereq-step-icon svg { stroke: #16a34a; }
+.prereq-check-step--fail .prereq-step-icon svg { stroke: #dc2626; }
+.prereq-check-step--warn .prereq-step-icon svg { stroke: #d97706; }
+
+.prereq-step-spinner {
+  display: block;
+  width: 14px;
+  height: 14px;
+  border: 2px solid #cbd5e1;
+  border-top-color: #6366f1;
+  border-radius: 50%;
+  animation: prereq-spin 0.7s linear infinite;
+}
+
+@keyframes prereq-spin {
+  to { transform: rotate(360deg); }
+}
+
+.prereq-step-label {
+  font-weight: 500;
+}
+
+/* 通过结果 */
+.prereq-result--pass {
+  display: flex;
+  align-items: center;
+  gap: 10px;
+  padding: 16px 18px;
+  background: linear-gradient(135deg, #f0fdf4 0%, #dcfce7 100%);
+  border: 1.5px solid #86efac;
+  border-radius: 10px;
+  color: #15803d;
+  font-weight: 600;
+  font-size: 15px;
+}
+
+.prereq-result--pass svg {
+  width: 22px;
+  height: 22px;
+  stroke: #16a34a;
+  flex-shrink: 0;
+}
+
+/* 失败：问题列表 */
+.prereq-issues {
+  display: flex;
+  flex-direction: column;
+  gap: 14px;
+}
+
+.prereq-issues-header {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  padding: 12px 14px;
+  background: #fff7ed;
+  border: 1px solid #fed7aa;
+  border-radius: 8px;
+  color: #9a3412;
+  font-size: 13px;
+  font-weight: 500;
+}
+
+.prereq-issues-header svg {
+  width: 16px;
+  height: 16px;
+  stroke: #ea580c;
+  flex-shrink: 0;
+}
+
+.prereq-section {
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+}
+
+.prereq-section-title {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+}
+
+.prereq-section-badge {
+  font-size: 11px;
+  font-weight: 600;
+  padding: 2px 8px;
+  border-radius: 20px;
+  letter-spacing: 0.02em;
+}
+
+.prereq-section-badge--add {
+  background: #eff6ff;
+  color: #1d4ed8;
+  border: 1px solid #bfdbfe;
+}
+
+.prereq-section-badge--remove {
+  background: #fef2f2;
+  color: #b91c1c;
+  border: 1px solid #fecaca;
+}
+
+.prereq-grant-all-btn {
+  margin-left: auto;
+  font-size: 12px;
+}
+
+.prereq-item-list {
+  display: flex;
+  flex-direction: column;
+  gap: 6px;
+}
+
+.prereq-item {
+  display: flex;
+  align-items: center;
+  gap: 10px;
+  padding: 10px 12px;
+  border-radius: 8px;
+  border: 1px solid;
+}
+
+.prereq-item--missing {
+  background: #f8faff;
+  border-color: #c7d7fe;
+}
+
+.prereq-item--remove {
+  background: #fff8f8;
+  border-color: #fecaca;
+}
+
+.prereq-item-info {
+  flex: 1;
+  display: flex;
+  align-items: center;
+  gap: 6px;
+  flex-wrap: wrap;
+  min-width: 0;
+}
+
+.prereq-item-row {
+  display: flex;
+  align-items: center;
+  gap: 5px;
+}
+
+.prereq-item-arrow {
+  font-size: 11px;
+  color: #94a3b8;
+  padding: 0 2px;
+}
+
+.prereq-item-chip {
+  font-size: 10px;
+  font-weight: 600;
+  padding: 1px 6px;
+  border-radius: 20px;
+  white-space: nowrap;
+}
+
+.prereq-item-chip--enabled { background: #dcfce7; color: #15803d; }
+.prereq-item-chip--missing { background: #fee2e2; color: #b91c1c; }
+.prereq-item-chip--disabled { background: #f1f5f9; color: #64748b; }
+.prereq-item-chip--will-remove { background: #fef9c3; color: #854d0e; }
+
+.prereq-item-name {
+  font-size: 12px;
+  color: #334155;
+  font-weight: 500;
+}
+
+.prereq-dialog-footer {
+  display: flex;
+  justify-content: flex-end;
+  gap: 8px;
+}
+
+/* 进入动画 */
+.prereq-result-enter-active {
+  transition: all 0.4s cubic-bezier(0.16, 1, 0.3, 1);
+}
+
+.prereq-result-enter-from {
+  opacity: 0;
+  transform: translateY(8px) scale(0.98);
+}
+</style>