root/Neo-ZQYY
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity
Files
b44096600dd6668738057b809f05e42f63f83513
Neo-ZQYY/docs/audit/changes/2026-03-27__miniprogram-permission-unification.md
Neo 14a12342b5 chore(audit): 补追 96 份未入仓审计孤本 — 覆盖 2026-02-26 ~ 2026-04-08 
这些审计记录原本堆积在 docs/audit/changes/changes/ 嵌套误产物目录下（由开发机迁移
79d3c2e 前后的不明批量操作产生）。由于同期 .gitignore 屏蔽了 docs/audit/ 全目录，
它们从未入过 git 任何分支 history。删除即永久丢失。

按 docs/specs/audit-gap-recovery/tasks.md 阶段 1 执行，将全部 96 份 D 类孤本
（主目录无同名、git history 亦无记录）复制到 docs/audit/changes/ 主目录入仓。

涵盖主题: P1-P18 全栈集成 / 多模块累积变更 / ETL bug 修复 / 业务日切 /
   召回与任务引擎改造 / 租户管理与审批 / 董事会财务 / 客户与助教详情 /
   DDL 基线合并 / Kiro 到 Claude Code 迁移

阶段 2（B 类内容漂移 1 份）和阶段 4（嵌套目录删除）独立推进。

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-04-20 06:35:42 +08:00

11 KiB
Raw Blame History

变更审计记录：小程序权限体系统一改造（W1-W5）

字段 值
日期 2026-03-27 09:55:17
Prompt-ID P20260327-083929
Session-ID 0ecf5499
Session 路径 docs/audit/session_logs/2026-03/27/11_476da926_075522

操作摘要

小程序权限体系统一改造——后端为权限唯一真相源，前端根据权限码动态控制页面/tab/按钮可见性。涵盖 5 个工作项（W1-W5）：refresh_token 有效期延长、/api/xcx/me 返回 permissions 列表、角色-权限码映射修正、后端端点从 require_approved 迁移到 require_permission("xxx")、前端权限守卫重写为权限码驱动。

变更范围

  • W1 — Token 有效期：apps/backend/app/config.py — refresh_token 有效期从 7 天延长至 30 天
  • W2 — 权限下发：apps/backend/app/schemas/xcx_auth.py UserStatusResponse 新增 permissions: list[str] 字段；apps/backend/app/routers/xcx_auth.py /api/xcx/me 返回当前用户的 permissions 列表
  • W3 — 角色权限映射：db/zqyy_app/migrations/2026-03-27__fix_role_permissions.sql 修正角色-权限码映射关系
  • W4 — 后端端点权限化：
    • xcx_tasks.py：7 个端点从 require_approved → require_permission("view_tasks")
    • xcx_performance.py：2 个端点 → require_permission("view_tasks")
    • xcx_customers.py：2 个端点 → require_permission("view_board_customer")
    • xcx_coaches.py：1 个端点 → require_permission("view_board_coach")
  • W5 — 前端权限守卫重写：
    • auth-guard.ts：重写为权限码驱动（不再基于角色硬编码）
    • app.ts：改用 syncPermissions 同步权限
    • typings/index.d.ts：globalData 新增 permissions 字段
    • 看板页面（board-finance/board-customer/board-coach）：.ts + .wxml 改为动态二级 tab，根据权限码控制可见性

风险与回滚

  • 风险点：
    • 权限码不匹配：若数据库 auth.role_permissions 映射遗漏某权限码，对应角色用户将被 403 拒绝
    • 前后端权限一致性：前端 tab 可见性依赖 permissions 数组，后端 API 依赖 require_permission，两者必须使用相同的权限码字符串
    • refresh_token 延长至 30 天：已签发的旧 token（7 天有效期）不受影响，新 token 才生效
    • 迁移脚本依赖 auth.roles 和 auth.permissions 表已存在且包含正确的角色/权限记录
  • 回滚要点：
    • 数据库：回滚 2026-03-27__fix_role_permissions.sql 中的映射变更
    • 后端：将 12 个端点的 require_permission(...) 改回 require_approved；移除 UserStatusResponse 的 permissions 字段；恢复 config.py 的 7 天有效期
    • 前端：恢复 auth-guard.ts 为角色驱动版本；恢复 app.ts 的 syncVisibleTabs；恢复看板页面的静态 tab 逻辑

改动注解

apps/backend/app/config.py

  • 变更类型：修改
  • 原始原因：W1 要求延长 refresh_token 有效期，减少用户频繁重新登录
  • 思路分析：将 REFRESH_TOKEN_EXPIRE_DAYS 从 7 改为 30，属于配置级变更，不影响 token 签发/验证逻辑
  • 修改结果：新签发的 refresh_token 有效期 30 天，已签发的旧 token 不受影响

apps/backend/app/schemas/xcx_auth.py

  • 变更类型：修改
  • 原始原因：W2 需要在 /api/xcx/me 响应中携带权限码列表，供前端做动态可见性控制
  • 思路分析：在 UserStatusResponse Pydantic model 中新增 permissions: list[str] 字段，默认空列表
  • 修改结果：前端可通过 me.permissions 获取当前用户的全部权限码

apps/backend/app/routers/xcx_auth.py

  • 变更类型：修改
  • 原始原因：W2 配合 schema 变更，在 /api/xcx/me 路由中查询并填充 permissions
  • 思路分析：从 auth.role_permissions + auth.permissions 表 JOIN 查询当前用户角色对应的权限码列表
  • 修改结果：approved 用户调用 /api/xcx/me 时，响应中包含完整的 permissions 数组

apps/backend/app/routers/xcx_tasks.py

  • 变更类型：修改
  • 原始原因：W4 将端点级鉴权从"已审核即可访问"升级为"需持有特定权限码"
  • 思路分析：7 个端点的依赖注入从 require_approved 替换为 require_permission("view_tasks")，实现细粒度权限控制
  • 修改结果：仅持有 view_tasks 权限码的角色可访问任务相关端点

apps/backend/app/routers/xcx_performance.py

  • 变更类型：修改
  • 原始原因：W4 绩效端点同样需要权限码控制
  • 思路分析：2 个端点改为 require_permission("view_tasks")，与任务模块共享同一权限码（绩效是任务的子功能）
  • 修改结果：绩效端点与任务端点权限一致

apps/backend/app/routers/xcx_customers.py

  • 变更类型：修改
  • 原始原因：W4 客户看板端点需要独立权限码
  • 思路分析：2 个端点改为 require_permission("view_board_customer")
  • 修改结果：仅持有 view_board_customer 权限码的角色可访问客户看板

apps/backend/app/routers/xcx_coaches.py

  • 变更类型：修改
  • 原始原因：W4 助教看板端点需要独立权限码
  • 思路分析：1 个端点改为 require_permission("view_board_coach")
  • 修改结果：仅持有 view_board_coach 权限码的角色可访问助教看板

db/zqyy_app/migrations/2026-03-27__fix_role_permissions.sql

  • 变更类型：新增
  • 原始原因：W3 需要修正角色-权限码映射，确保各角色拥有正确的权限集合
  • 思路分析：迁移脚本操作 auth.role_permissions 表，建立角色与权限码的多对多映射
  • 修改结果：数据库中角色权限映射与 W4/W5 的权限码使用保持一致

apps/miniprogram/miniprogram/utils/auth-guard.ts

  • 变更类型：修改
  • 原始原因：W5 将前端权限守卫从角色硬编码改为权限码驱动
  • 思路分析：重写核心逻辑——不再维护 PAGE_ROLES 角色→页面映射，改为从 globalData.permissions 读取权限码，页面/tab 可见性由权限码决定
  • 修改结果：前端权限判断与后端权限码完全对齐，新增权限码时只需更新数据库映射，无需改前端代码

apps/miniprogram/miniprogram/app.ts

  • 变更类型：修改
  • 原始原因：W5 全局入口需要同步权限码到 globalData
  • 思路分析：将 syncVisibleTabs 替换为 syncPermissions，在 /api/xcx/me 返回后将 permissions 存入 globalData
  • 修改结果：小程序启动时自动同步权限码，后续页面/组件可直接读取

apps/miniprogram/typings/index.d.ts

  • 变更类型：修改
  • 原始原因：W5 TypeScript 类型定义需要同步新增 permissions 字段
  • 思路分析：在 IAppOption.globalData 接口中新增 permissions: string[]
  • 修改结果：全局类型安全，IDE 自动补全支持

apps/miniprogram/miniprogram/pages/board-finance/board-finance.ts

  • 变更类型：修改
  • 原始原因：W5 财务看板二级 tab 需要根据权限码动态显示
  • 思路分析：从 globalData.permissions 过滤出当前用户可见的二级 tab，动态渲染
  • 修改结果：不同角色看到不同的二级 tab 组合

apps/miniprogram/miniprogram/pages/board-finance/board-finance.wxml

  • 变更类型：修改
  • 原始原因：W5 配合 .ts 的动态 tab 逻辑，模板需要支持动态渲染
  • 思路分析：tab 列表改为 wx:for 遍历动态数组
  • 修改结果：模板与逻辑层联动，tab 可见性由权限码控制

apps/miniprogram/miniprogram/pages/board-customer/board-customer.ts

  • 变更类型：修改
  • 原始原因：W5 客户看板同上
  • 思路分析：同 board-finance 的动态 tab 方案
  • 修改结果：客户看板二级 tab 权限码驱动

apps/miniprogram/miniprogram/pages/board-customer/board-customer.wxml

  • 变更类型：修改
  • 原始原因：W5 配合动态 tab
  • 思路分析：同 board-finance.wxml
  • 修改结果：模板支持动态 tab 渲染

apps/miniprogram/miniprogram/pages/board-coach/board-coach.ts

  • 变更类型：修改
  • 原始原因：W5 助教看板同上
  • 思路分析：同 board-finance 的动态 tab 方案
  • 修改结果：助教看板二级 tab 权限码驱动

apps/miniprogram/miniprogram/pages/board-coach/board-coach.wxml

  • 变更类型：修改
  • 原始原因：W5 配合动态 tab
  • 思路分析：同 board-finance.wxml
  • 修改结果：模板支持动态 tab 渲染

本次对话文件变更

新增文件

  • docs/audit/prompt_logs/prompt_log_20260327_083929.md
  • docs/audit/session_logs/2026-03/27/11_476da926_075522/main_01_db3ab14f.md
  • docs/audit/session_logs/2026-03/27/11_476da926_075522/sub_01_db3ab14f.md

删除文件

  • docs/audit/session_logs/2026-03/27/11_476da926_075522/main_01_77123f5a.md

验证

  1. 数据库验证：执行迁移后 SELECT r.code, p.code FROM auth.role_permissions rp JOIN auth.roles r ON r.id=rp.role_id JOIN auth.permissions p ON p.id=rp.permission_id ORDER BY r.code, p.code; 确认映射正确
  2. 后端验证：GET /api/xcx/me 返回的 permissions 数组包含当前角色对应的全部权限码
  3. 前端验证：
    • coach 登录 → 看到任务 tab，看不到客户/助教看板 tab
    • staff 登录 → 看到看板 tab，看不到任务 tab
    • head_coach/manager 登录 → 看到全部 tab
    • 无权限用户访问受保护端点 → 返回 403
  4. 迁移状态：⚠️ 2026-03-27__fix_role_permissions.sql 需确认已在测试库执行

文件清单

文件 操作 工作项
apps/backend/app/config.py 修改 W1
apps/backend/app/schemas/xcx_auth.py 修改 W2
apps/backend/app/routers/xcx_auth.py 修改 W2
apps/backend/app/routers/xcx_tasks.py 修改 W4
apps/backend/app/routers/xcx_performance.py 修改 W4
apps/backend/app/routers/xcx_customers.py 修改 W4
apps/backend/app/routers/xcx_coaches.py 修改 W4
db/zqyy_app/migrations/2026-03-27__fix_role_permissions.sql 新增 W3
apps/miniprogram/miniprogram/utils/auth-guard.ts 修改 W5
apps/miniprogram/miniprogram/app.ts 修改 W5
apps/miniprogram/typings/index.d.ts 修改 W5
apps/miniprogram/miniprogram/pages/board-finance/board-finance.ts 修改 W5
apps/miniprogram/miniprogram/pages/board-finance/board-finance.wxml 修改 W5
apps/miniprogram/miniprogram/pages/board-customer/board-customer.ts 修改 W5
apps/miniprogram/miniprogram/pages/board-customer/board-customer.wxml 修改 W5
apps/miniprogram/miniprogram/pages/board-coach/board-coach.ts 修改 W5
apps/miniprogram/miniprogram/pages/board-coach/board-coach.wxml 修改 W5
Reference in New Issue View Git Blame Copy Permalink