danyang-match/docs/superpowers/plans/2026-10-24-workbench-role-scope-management.md

工作台数据范围与运营角色管理实施计划

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: 让普通红娘查看本人工作台数据、红娘组长查看本组数据、管理员查看全平台统计，并在管理员端支持创建/分配红娘角色与组长角色；管理员不展示红娘业务明细页面。

Architecture: 后端从当前操作员角色和组织推导 SELF、TEAM、ALL 数据范围；前端只消费统一工作台聚合接口。角色使用现有 roles、permissions、operator_roles、role_permissions 表，管理员只能分配预置角色，不能直接给单个账号勾选任意权限。

Tech Stack: Java 21 / Spring Boot 3 / PostgreSQL / Flyway / MyBatis-Plus / Vue 3 / TypeScript / Vite。

Spec: docs/superpowers/plans/2026-10-23-v12-account-lifecycle-matchmaker-dashboard.md Task 5/6；backend/src/main/resources/db/migration/V054__add_matchmaker_leader_role.sql。

Global Constraints

• PostgreSQL 是权限和数据范围 Source of Truth；前端隐藏菜单不是安全边界。
• 普通红娘只能读取本人有效分配/本人关联数据；组长只能读取同组织数据；管理员读取全平台聚合数据。
• 咨询正文、身份证、手机号等敏感数据继续遵守既有最小权限规则。
• 不新增第三方依赖，不重写 V1.1 业务模块，不删除现有数据。
• 普通 matchmaker 不拥有 matchmaker.assign；组长使用 matchmaker.team.assign。

---

Task 1: 角色管理权限与接口契约

Files:

• Create: backend/src/main/resources/db/migration/V067__add_workbench_view_and_role_management.sql
• Modify: backend/src/main/java/com/danyang/match/platform/operator/controller/OperatorController.java
• Modify: backend/src/main/java/com/danyang/match/platform/operator/service/OperatorManagementService.java
• Create: backend/src/main/java/com/danyang/match/platform/operator/dto/OperatorRoleUpdateRequest.java
• Create: backend/src/test/java/com/danyang/match/platform/operator/OperatorRoleManagementTest.java

Interfaces:

• GET /api/v1/operator/operators/roles returns caller-allowed role templates and inherited permissions.

• GET /api/v1/operator/operators/{id} returns roles, organization and derived scope.

• POST /api/v1/operator/operators accepts roleCodes and binds roles transactionally.

• PUT /api/v1/operator/operators/{id}/roles replaces role bindings transactionally.

• Only permission.manage callers may use these endpoints; server validates role assignability, organization scope, last-super-admin protection and self-demotion protection.

• Write failing tests for role binding, invalid role, missing organization for team leader, and unauthorized role escalation.

• Run targeted tests and verify expected failures.

• Add workbench.view; grant it to matchmaker, matchmaker_leader, platform_admin, super_admin.

• Remove matchmaker.assign from ordinary matchmaker role while preserving administrator assignment capability.

• Implement role catalog, transactional create/update, audit events, and effective permission response.

• Run operator and migration tests.

Task 2: Scoped workbench aggregation

Files:

• Create: backend/src/main/java/com/danyang/match/platform/matchmaker/dashboard/MatchmakerDashboardScope.java
• Create: backend/src/main/java/com/danyang/match/platform/matchmaker/dashboard/MatchmakerWorkbenchService.java
• Create: backend/src/main/java/com/danyang/match/platform/matchmaker/dashboard/MatchmakerWorkbenchController.java
• Create: backend/src/main/java/com/danyang/match/platform/matchmaker/dashboard/MatchmakerWorkbenchMapper.java
• Create: backend/src/test/java/com/danyang/match/platform/matchmaker/MatchmakerWorkbenchScopeTest.java
• Create: backend/src/test/java/com/danyang/match/platform/matchmaker/MatchmakerDashboardAuthorizationTest.java

Interfaces:

• GET /api/v1/operator/workbench/dashboard returns scope, scopeLabel, five card metrics, and each card's detail permission.

• Scope resolver: ordinary matchmaker = SELF; leader = same organization_id with NULL=NULL platform-team semantics; platform/super admin = ALL.

• Queries filter review tasks, matchmaker assignments/services, counseling assignments, service appointments, matchmaker-linked matches, and matchmaker-linked activity registrations using server-derived operator/team predicates.

• Aggregates never return counseling正文 or sensitive user fields.

• Write failing scope-isolation tests for self/team/all and cross-organization denial.

• Implement scope resolver and aggregate queries.

• Add tests proving request parameters cannot widen scope.

• Run targeted backend tests.

Task 3: Admin operator and role management UI

Files:

• Modify: admin-web/src/modules/operator/OperatorManagementView.vue

• Create: admin-web/src/components/operator/RolePermissionPreview.vue

• Modify: admin-web/src/api/client.ts only if typed helper is needed

• Create/Modify: admin-web/src/types/operator.ts

• Add role, scope, and organization columns.

• Add role selection and inherited-permission preview to create dialog.

• Add role edit dialog with organization validation and confirmation.

• Show audit-safe error messages; do not expose password hashes or raw permissions from local storage.

• Run admin type-check and build.

Task 4: Workbench frontend and administrator route policy

Files:

• Modify: admin-web/src/services/dashboard.ts

• Modify: admin-web/src/types/dashboard.ts

• Modify: admin-web/src/views/DashboardView.vue

• Modify: admin-web/src/layouts/MainLayout.vue

• Modify: admin-web/src/router/index.ts

• Create: admin-web/tests/workbench-role-scope.cjs

• Use the unified workbench endpoint for the six workbench metrics while retaining detail requests for secondary panels.

• Render the server-derived scope label and values in the workbench cards.

• Hide /referral and /matchmaker navigation for administrators.

• Keep those pages for ordinary matchmakers and leaders.

• Redirect administrator direct navigation to those routes back to /dashboard.

• Show aggregate cards even without detail permissions; detail buttons remain permission-gated.

• Run UI type-check and build.

Task 5: Verification and handoff

• Run Flyway migration validation and backend targeted tests.
• Log in as ordinary matchmaker, group leader, and administrator.
• Verify self/team/all counts with cross-organization negative cases.
• Verify administrator has no red娘 detail navigation and can see statistics on dashboard.
• Update docs/STATUS.md and provide a Completion Report with evidence and residual risks.