danyang-match/docs/superpowers/plans/2026-10-25-v12-permission-scope-dashboard-remediation.md

# V1.2 权限基线与范围看板收口实施计划

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:executing-plans or superpowers:subagent-driven-development. Steps use checkbox syntax.

**目标：** 按 V1.2 需求、实施计划和决策登记表，修复角色权限、后端数据范围、工作台统计和前端入口不一致问题。

**架构：** 保留模块化单体和 PostgreSQL Source of Truth。权限继续由 role_permissions 与后端门禁控制；数据范围由认证主体、角色、组织和有效分配关系服务端推导。聚合查询与详情查询共用同一 scope builder 和状态谓词。

**技术栈：** Java 21、Spring Boot 3、MyBatis-Plus、PostgreSQL、Flyway、Vue 3、TypeScript、微信原生小程序、Maven、pnpm。

**规范：**
- C:/Users/13070/.codex/attachments/155243ba-d394-45a0-b100-8c44baf9094d/已粘贴的文本.txt
- E:/develop/公益婚恋服务平台/docs/superpowers/plans/2026-10-23-v12-account-lifecycle-matchmaker-dashboard.md
- E:/develop/公益婚恋服务平台/docs/governance/decision-register.md

## 全局约束

- 普通红娘只访问本人有效分配对象；红娘组长只访问本人所属组织；管理员才可查看全平台。
- 后端不信任请求体中的 userId、matchmakerId、teamId 或角色字段。
- 无权限、真实空数据、查询失败必须分别返回和展示。
- 六项卡片必须与对应详情列表使用相同范围和状态口径。
- 未审核的新资料版本不得进入展示、推荐、匹配、红娘服务或统计。
- 不删除历史数据，不重写 V001-V061，不引入新第三方依赖。

---

### Task 1：冻结角色权限矩阵与冲突决策

**文件：**
- 新建 docs/v12/V1.2-角色权限与前端入口矩阵.md
- 修改 docs/governance/decision-register.md（仅在冲突裁决确认后）
- 新建 backend/src/test/java/com/danyang/match/platform/deployment/PermissionBaselineContractTest.java

**步骤：**
- [ ] 查询活跃 PostgreSQL 的 Flyway 版本、角色权限、操作员角色和组织归属。
- [ ] 对照 V070/V071 与 V1.2 要求，记录“红娘是否拥有五类业务操作权限”的正式裁决，不得默默覆盖历史迁移。
- [ ] 为 user、matchmaker、matchmaker_leader、platform_admin、super_admin、reviewer、activity_manager、risk_operator、organization_admin、counselor、counseling_manager、service_station_operator、content_editor、data_viewer 建立权限、范围、菜单和禁止操作矩阵。
- [ ] 添加矩阵契约测试，确保普通红娘不能通过参数修改读取其他人员或组织的数据。
- [ ] 运行后端契约测试并记录基线结果。

**验收：** Task 2-5 均以同一矩阵为准，V070/V071 冲突已被明确记录。

### Task 2：修复工作台权限可用性与组织范围

**文件：**
- 修改 backend/src/main/java/com/danyang/match/platform/matchmaker/dashboard/MatchmakerWorkbenchService.java
- 修改 backend/src/main/java/com/danyang/match/platform/matchmaker/dashboard/MatchmakerDashboardScope.java
- 新建 backend/src/test/java/com/danyang/match/platform/matchmaker/MatchmakerWorkbenchAuthorizationTest.java
- 新建 backend/src/test/java/com/danyang/match/platform/matchmaker/MatchmakerWorkbenchScopeTest.java
- 如需数据约束，经批准后新建 backend/src/main/resources/db/migration/V072__validate_matchmaker_organization_scope.sql

**步骤：**
- [ ] 为普通红娘、同组织组长、跨组织组长、平台管理员和组织为空的组长编写失败测试。
- [ ] 每个指标先检查对应 detailPermission；无权限时不得返回统计值，返回 available=false 和稳定权限标识。
- [ ] 授权但无数据时返回真实 0，不与无权限混淆。
- [ ] 组织为空的组长必须被拒绝或进入明确异常状态，不能把所有 NULL 组织当成一个团队。
- [ ] 对用户资料相关指标增加 published revision 条件。
- [ ] 运行范围和授权测试。

**验收：** 未授权指标不返回数据；授权空数据返回 0；组长不能看到其他组织或所有未分组数据。

### Task 3：统一六项详情接口的数据范围

**文件：**
- 新建或修改 backend/src/main/java/com/danyang/match/platform/matchmaker/dashboard/MatchmakerDashboardMapper.java
- 修改 review、counseling、service_appointment、analytics、activity 相关 Service/Controller
- 新建 backend/src/test/java/com/danyang/match/platform/matchmaker/MatchmakerDashboardDetailScopeTest.java

**步骤：**
- [ ] 详情接口只接受分页和时间筛选，不接受替代 operator/team scope。
- [ ] 为普通红娘、同组织组长、跨组织组长和管理员添加越权失败测试。
- [ ] 在数据库查询层应用 SELF、TEAM、ALL 条件，不在 Vue 过滤全量数据。
- [ ] 统一各指标纳入和排除状态，并排除未发布资料版本。
- [ ] 验证聚合数字等于允许访问的详情列表数量。
- [ ] 敏感佐证和咨询备注继续独立授权并留痕。

**验收：** 卡片与详情一致；修改请求参数不能扩大范围；跨组织记录不可探测。

### Task 4：修复管理端卡片、导航和角色显示

**文件：**
- 修改 admin-web/src/services/dashboard.ts
- 修改 admin-web/src/types/dashboard.ts
- 修改 admin-web/src/views/DashboardView.vue
- 修改 admin-web/src/router/index.ts
- 修改 admin-web/src/layouts/MainLayout.vue
- 修改 admin-web/src/stores/auth.ts
- 新建 admin-web/tests/dashboard-permission-contract.test.ts

**步骤：**
- [ ] 为普通红娘、组长、管理员、审核员、咨询人员和服务站人员添加前端权限契约测试。
- [ ] 区分 forbidden、真实 0 和 error；无权限卡片不可显示误导性数值，也不可导航到无权限页面。
- [ ] 保留授权角色的六张卡片和真实 0。
- [ ] 角色名称改为使用服务端角色信息，消除“红娘组长被显示为资料审核人员”的权限顺序冲突。
- [ ] 管理员继续隐藏独立“公益红娘/红娘服务”菜单，只在工作台展示统计。
- [ ] 运行 admin type-check、build 和前端契约测试。

**验收：** 前端入口与后端权限矩阵一致，禁止把无权限显示成空数据或可操作入口。

### Task 5：补齐其他运营角色的最小权限

**文件：**
- 新建 backend/src/main/resources/db/migration/V073__align_operator_role_permissions.sql
- 修改 admin-web/src/layouts/MainLayout.vue
- 修改 admin-web/src/stores/auth.ts
- 新建 backend/src/test/java/com/danyang/match/platform/deployment/OperatorRolePermissionContractTest.java

**步骤：**
- [ ] 为 reviewer、activity_manager、risk_operator、organization_admin 编写最小权限契约测试。
- [ ] 仅按已确认矩阵写幂等迁移，禁止给非管理员授予全部权限。
- [ ] 让前端菜单与实际权限一致。
- [ ] 校验操作员创建/编辑只能分配当前管理员可授予的角色；组长必须有组织。
- [ ] 在干净数据库执行迁移验证。

**验收：** 每个正式运营角色都有可用的最小权限集合，且没有无关的全平台数据权限。

### Task 6：活栈端到端验收与文档收口

**文件：**
- 新建 tests/e2e/v12_permission_scope_dashboard_test.py
- 修改 tests/e2e/conftest.py
- 修改 docs/STATUS.md
- 新建 docs/Phase-V12-Permission-Scope-Completion-Report.md
- 修改 docs/api/API_INVENTORY.md
- 修改 docs/v12/V1.2-角色权限与前端入口矩阵.md

**步骤：**
- [ ] 使用干净 PostgreSQL/Redis 栈和真实迁移，不删除现有项目数据。
- [ ] 为普通用户、普通红娘、同组织组长、跨组织组长、平台管理员、审核员、咨询人员、服务站人员、活动管理员建立 fixture。
- [ ] 验证登录权限、菜单、六项卡片、详情列表、禁止状态、空数据和失败状态。
- [ ] 尝试跨组织和替代 operator/team 参数，断言拒绝且不泄露数据。
- [ ] 运行：
  - mvn -B -f backend/pom.xml -s backend/maven-settings.xml test
  - pnpm --dir admin-web type-check
  - pnpm --dir admin-web build
  - npm --prefix miniapp run type-check
  - python -m pytest tests/e2e/v12_permission_scope_dashboard_test.py -q
- [ ] 生成 Completion Report，使用 PASS、PARTIAL、FAIL、NOT_VERIFIED，并停止等待用户验收。

**验收：** 当前代码、数据库、接口、前端入口和六项看板均通过同一权限矩阵；没有使用历史测试结果替代当前证据。

## 依赖顺序

Task 1 权限矩阵与冲突裁决
→ Task 2 聚合门禁与组织范围
→ Task 3 详情接口范围
→ Task 4 管理端展示
→ Task 5 其他运营角色
→ Task 6 活栈 E2E 和发布门禁

## 明确不做

- 不重新设计自动分配算法。
- 不新增支付、会员、社区、微服务或 Kubernetes。
- 不把身份证原件和咨询备注全文权限隐式授予红娘。
- 不直接修改生产数据库，不以隐藏前端按钮替代后端权限。

## 发布门禁

只有当 Task 1-6 均有当前运行证据，且 SELF、TEAM、ALL 三种范围的聚合数字与详情列表一致、未授权数据不返回、前端入口与后端矩阵一致时，才可判定本阶段完成。否则结论为 CONDITIONAL GO 或 NO-GO。