create-bubbles 0.1.24 → 0.1.26

package/template-vp-monorepo-react-nestjs/.spaces/01./344/274/201/344/270/232/347/272/247/351/241/271/347/233/256/347/272/247//351/234/200/346/261/202/346/226/207/346/241/243.md

@@ -0,0 +1,177 @@
+# 企业、项目与菜单权限管理实施计划
+
+## 一、目标与业务边界
+
+在现有 React、NestJS、Drizzle、PostgreSQL 和 Redis 基础上，完成**企业管理 → 项目管理 → 成员与角色 → 菜单授权 → 页面、按钮与接口鉴权 → 操作审计**的完整闭环。
+
+采用已确认的业务规则：
+
+| 身份 | 默认管理范围 | 权限边界 |
+| --- | --- | --- |
+| 平台管理员 | 企业开通与启停、全局账号、平台角色、全局菜单、平台审计 | 进入企业内部仍需企业成员身份和相应授权 |
+| 企业管理员 | 企业资料、成员、角色、本企业全部项目及审计 | 自动拥有本企业所有项目的管理权限 |
+| 项目管理员 | 当前项目资料、成员、角色及审计 | 不获得企业管理权限或其他项目权限 |
+| 普通成员 | 当前企业、项目角色授予的功能 | 多个企业、项目之间分别授权 |
+
+- 一个账号可以加入多个企业、多个项目；项目成员必须先是所属企业成员。
+- 平台创建企业时指定首位企业管理员；企业管理员创建项目时指定项目管理员。
+- 保留公开注册，补齐注册页面。企业管理员通过**完整账号**添加已注册用户；新账号不会自动加入企业。
+- 企业、项目首期提供创建、编辑、启用和停用，不提供物理删除；项目不支持跨企业迁移。
+- 保留现有 Cookie token＋Bearer 请求方式。Cookie 工具负责 Cookie，Local/Session 工具负责浏览器存储。
+- 本期覆盖管理权限和基础审计；上传的企业、项目归属改造单列后续阶段。
+
+## 二、管理功能与菜单设计
+
+### 管理页面
+
+| 工作空间 | 首期页面与操作 |
+| --- | --- |
+| 平台 | 企业列表与开通、企业启停、账号查询与启停、平台角色及人员授权、菜单管理、平台操作日志 |
+| 企业 | 企业工作台、企业资料、成员管理、角色管理、项目列表与创建、项目启停、企业操作日志 |
+| 项目 | 项目工作台、项目资料、成员管理、角色管理、项目操作日志 |
+
+列表提供搜索、筛选和分页；成员支持添加、停用、启用、移除与分配角色。企业只能查询自己的成员，添加账号不开放全平台用户列表。
+
+企业、项目角色支持自定义。内置管理员角色负责完整管理，内置普通成员角色默认只提供工作台和必要的工作空间入口，其他操作通过角色授权。
+
+### 菜单管理
+
+平台统一维护适用于平台、企业、项目的三套菜单树，企业和项目不保存独立菜单副本。
+
+菜单节点分为：
+
+- **目录**：组织导航层级，不直接产生操作权限。
+- **页面**：绑定前端已注册的 `routeKey` 和页面访问权限。
+- **按钮／操作**：挂在页面下，绑定已实现的操作权限，例如添加成员、修改角色。
+
+支持新增、编辑、调整父级、排序、隐藏、启停及受约束的删除。名称、图标和排序可配置；组件、路径模板和权限标识来自代码中的功能目录。
+
+菜单编辑器只能选择已注册的页面和操作。新增业务页面仍需开发并发布对应代码，数据库不保存可执行组件路径。
+
+明确以下行为：
+
+| 设置 | 导航表现 | 页面、按钮与接口 |
+| --- | --- | --- |
+| 隐藏 | 不显示导航入口 | 已授权用户仍可访问 |
+| 停用 | 不显示入口 | 对应功能及下级功能均不可访问 |
+| 未授权 | 不显示入口或操作 | 页面拒绝访问，接口拒绝执行 |
+
+- 目录按可见子节点自动显示；按钮不进入导航。
+- 校验循环父子关系、跨层级移动、重复页面绑定和未知权限标识。
+- 有子节点或仍被角色授权引用的节点不能直接删除。
+- 平台菜单、平台角色等恢复管理所需的入口受到保护，不能通过自身或祖先节点的操作使其失效。
+- 角色授权树支持全选、半选；授予按钮权限时必须包含所属页面访问权限，取消页面权限时同步取消下级操作授权。
+
+## 三、数据、接口与权限实现
+
+### 数据模型
+
+新增以下数据组：
+
+| 数据组 | 主要实体与约束 |
+| --- | --- |
+| 企业与项目 | `companies`、`projects`；项目必须属于企业，项目编码在企业内唯一 |
+| 成员关系 | `company_members`、`project_members`；成员关系唯一，项目成员必须满足企业成员关系 |
+| 角色授权 | `roles`、`user_roles`、`role_permissions`；角色绑定明确的平台、企业或项目作用域 |
+| 功能与菜单 | `permissions`、`menus`；权限标识稳定且唯一，菜单和权限适用层级一致 |
+| 操作审计 | `audit_logs`；记录操作者、作用域、操作、对象、变更摘要、时间和 requestId |
+
+角色使用 `scopeType`、`companyId`、`projectId` 表示归属，通过数据库约束限制合法组合。不同企业、项目可以创建同名角色。
+
+授权规则统一为：
+
+- 同一作用域内，多角色权限取并集；首期不引入角色继承和显式拒绝规则。
+- 企业管理员跨本企业项目的管理能力由统一授权逻辑计算，不批量复制项目角色。
+- 普通角色不能授予操作者自身无权授予的权限；内置管理员身份只能由对应作用域的管理员委派。
+- 移除企业成员时，事务内清理其企业角色、下属项目成员关系和项目角色。
+- 不允许通过移除成员、停用账号或撤销角色，使仍启用的管理范围失去最后一名有效管理员；并发操作使用事务和锁保证这一点。
+- 角色授权和菜单结构更新使用版本校验，过期提交返回冲突，避免覆盖其他管理员的修改。
+
+### 共享契约与接口
+
+接口请求、返回类型通过 `shared/types` 共享，通用方法通过 `shared/utils` 共享。核心作用域采用明确的联合类型：
+
+```ts
+type AccessScope =
+  | { type: 'platform' }
+  | { type: 'company'; companyId: string }
+  | { type: 'project'; companyId: string; projectId: string }
+```
+
+新增 `AccessContext`，返回当前用户、已验证作用域、有效菜单树和权限标识集合。分页列表统一返回 `items、total、page、pageSize`，默认每页 20 条、最大 100 条。
+
+接口按作用域组织：
+
+| 接口范围 | 用途 |
+| --- | --- |
+| `GET /workspaces` | 当前用户和可进入的工作空间；仅返回本人可见内容 |
+| `/platform/*` | 平台企业管理、账号、角色、菜单、审计 |
+| `/companies/:companyId/*` | 企业资料、成员、角色、可见项目与审计 |
+| `/companies/:companyId/projects/:projectId/*` | 项目资料、成员、角色与审计 |
+| 各作用域下的 `/access` | 获取当前作用域的菜单和权限上下文 |
+
+普通企业成员只能看到自己加入的项目；企业管理员可以看到本企业全部项目。
+
+沿用当前成功响应和统一异常模型，不新增一套响应包装。新增业务错误加入错误目录校验。
+
+### 后端鉴权
+
+请求依次完成：
+
+**登录态校验 → 用户状态校验 → 作用域及成员校验 → 功能权限校验 → 资源归属校验。**
+
+- URL 中的企业、项目 ID 只是查询目标，后端必须验证归属，不能作为授权依据。
+- 管理接口声明作用域和所需权限；未声明访问策略的新接口默认拒绝。
+- Repository 查询同时约束资源 ID 与企业、项目归属，更新和删除也遵循这一规则。
+- 未登录或账号失效返回 401；作用域内权限不足返回 403；跨企业、跨项目资源与不存在资源统一返回 404。
+- 首期不缓存后端授权结果，后续请求读取当前成员、角色和功能状态；撤权无需等待重新登录。
+- 账号禁用同时接入已有的会话撤销能力。
+- 当前数据库、Redis 测试接口移出默认应用入口，避免通过测试接口绕过管理权限。
+
+管理变更与成功审计记录在同一数据库事务中提交。平台查看平台事件；企业查看本企业及下属项目事件；项目查看当前项目事件。日志不记录密码、token 或完整敏感请求。
+
+### 前端接入
+
+- 登录后进入工作空间入口，选择企业、项目或平台管理空间；没有企业的账号显示等待管理员添加的状态。
+- 企业、项目 ID 放在路由中，刷新后能够恢复当前工作空间。
+- 使用 React Router 的 loader 获取管理页面上下文，布局消费菜单，页面和按钮消费权限；不恢复已删除的 auth Provider／Guard 目录。
+- 前端保留静态页面注册表，将服务端菜单映射到已注册页面，并提供 403、404 和无权限空状态。
+- 页面 API 随页面存放，继续使用现有 alova 封装；弹窗遵循 `show/hide` 规范。
+- 权限上下文不持久化、不使用请求缓存。业务缓存区分用户、企业和项目；切换工作空间取消旧请求并阻止迟到结果覆盖新页面。
+- 路由切换、窗口重新激活、授权修改及收到 403 后刷新权限。退出、401 时清理 Cookie 和用户相关缓存。
+- Local/Session 只保存最近选择、筛选条件等界面状态，不能用于判定权限。
+
+## 四、实施阶段与数据兼容
+
+| 阶段 | 交付内容 | 阶段完成标准 |
+| --- | --- | --- |
+| 1. 契约与数据库 | 共享类型、权限目录、数据模型、迁移、内置角色和菜单种子 | 空库与现有数据库均可迁移，约束和重复初始化验证通过 |
+| 2. 后端权限闭环 | 企业、项目、成员、角色、菜单接口，统一鉴权和审计 | 不依赖前端隐藏，也能阻止越权与跨作用域访问 |
+| 3. 前端管理闭环 | 注册、工作空间切换、三级管理页面、菜单和角色授权 | 可完成“注册→加入企业→加入项目→角色授权→访问功能” |
+| 4. 联调与交付 | 浏览器验收、数据库集成测试、迁移说明、接口文档和权限说明 | 正常流程及撤权、切换、并发等异常场景通过 |
+
+初始化与兼容规则：
+
+- 首位平台管理员通过初始化命令指定一个已注册、有效的账号，不提供固定默认密码，也不自动提升第一个注册用户。
+- 初始化命令可重复执行，但不能借重复执行给其他账号提权；种子更新不覆盖管理员已经调整的菜单和授权。
+- 现有用户保持原账号和登录方式，不自动分配企业或项目。
+- 现有上传数据继续按 `ownerId` 授权，本期不猜测归属、不迁移到默认企业，也不宣称上传已完成租户隔离。
+- 使用可审阅的 Drizzle migration；上线顺序为备份、迁移、服务端、前端，并提供迁移失败处理说明。
+- 保留工作区已有修改，实施时只调整本计划涉及的代码。
+
+## 五、验收标准与后续范围
+
+必须覆盖以下场景：
+
+1. **完整业务流程**：平台开通企业，用户注册并加入企业，管理员创建项目、添加成员和分配角色。
+2. **权限隔离**：同一用户在不同企业、项目拥有不同权限；平台管理员未经成员授权不能进入企业内部。
+3. **菜单一致性**：导航、直达页面、按钮和接口权限一致；隐藏与停用表现符合定义。
+4. **即时撤权**：角色撤销、成员停用或移除、企业或项目停用后，后续请求立即失去相应访问权。
+5. **切换与缓存**：快速切换企业、项目以及退出后换号，不出现旧数据、旧权限或旧请求覆盖。
+6. **管理约束**：重复成员、越权授予角色、删除引用中的菜单、循环菜单、并发移除最后管理员均被拒绝。
+7. **数据与审计**：跨作用域查询返回一致结果，成功变更有对应审计，日志中不存在密码和 token。
+8. **回归与迁移**：保留 Cookie／Storage 和请求层回归测试，验证旧用户登录、上传兼容及迁移重复执行。
+
+验证采用权限规则测试、真实 PostgreSQL／Redis 接口集成测试及 Playwright 关键流程测试；完成 `vp check`、相关测试和 shared、Web、Server 构建。跳过的集成测试不能计为通过。
+
+首期默认采用应用层作用域隔离和 RBAC，不引入部门组织树、字段级权限、审批流、SSO、外部协作者或企业独立菜单。上传归属改造放在下一阶段，沿用本期确定的企业、项目与权限契约。