create-bubbles 0.1.26 → 0.1.28

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//346/235/203/351/231/220/344/270/216/350/217/234/345/215/225/PRD.md

@@ -0,0 +1,121 @@
+# 企业、项目与菜单权限管理 PRD
+
+## 1. 文档状态与需求来源
+
+- 状态：主体业务范围已确认；企业成员只确认“直接注册或邀请”两个入口，邀请协议与验收尚待确认。
+- 业务依据：[已确认需求文档](./需求文档.md)。该文档及本节记录的用户后续确认是唯一业务来源；本 PRD 只负责拆分用户故事和映射验收，不新增业务政策。
+- 本会话最新确认：有效平台管理员即使没有企业成员身份，仍能进入平台空间开通企业；无企业不等同于没有平台管理权限。普通注册用户的具体邀请载体和加入流程尚未确认。
+- 若本 PRD 的摘要与需求原文存在表述差异，按已确认需求及用户后续确认核对修正，不由开发或测试自行扩展规则。
+- 本文不记录测试账号、密码、会话或其他凭据。验收状态将在后续测试报告中记录；本 PRD 的确认不表示功能或测试已经完成。
+
+## 2. 目标与首期范围
+
+在现有 React、NestJS、Drizzle、PostgreSQL 和 Redis 基础上，交付企业开通、项目管理、成员与角色、菜单授权、页面及接口鉴权、基础操作审计的完整管理流程。
+
+首期覆盖平台、企业、项目三类工作空间，以及注册与工作空间选择。平台维护全局资源和企业管理员恢复入口；企业管理员管理本企业及全部项目；项目管理员仅管理当前项目；普通成员按所在作用域的有效授权使用功能。各层级的具体权限、停启和管理员保护规则直接引用需求文档，不另建一套规则。
+
+## 3. 用户故事
+
+| 编号  | 用户故事与可观察结果                                                                                                                                                                         | 需求依据                                         |
+| ----- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------ |
+| US-01 | 作为普通用户，我可以公开注册并登录；注册不会自动开通企业或授予平台身份。尚未加入企业时，工作空间显示该状态，具体邀请载体和加入流程待确认。                                                   | 一、目标与业务边界；三、前端接入；本会话最新确认 |
+| US-02 | 作为有效平台管理员，我即使未加入任何企业，也可以进入平台空间开通企业、指定首位企业管理员、管理企业启停与全局账号；企业内部业务访问仍需要对应成员身份和授权。                                 | 一、身份边界；二、管理页面；本会话最新确认       |
+| US-03 | 作为企业管理员，我可以在“直接注册”和“邀请”两个企业成员入口之间选择。成员管理不会提供全平台账号枚举或按完整账号直接拉入既有账号；邀请的具体协议、操作和状态待确认。                           | 一、成员边界；二、管理页面                       |
+| US-04 | 作为有效内置企业管理员，我可以创建项目，并指定有效企业成员为首位项目管理员；创建结果和相关成员、角色、成功审计整体成功或整体回滚。                                                           | 一、目标与业务边界；二、菜单管理                 |
+| US-05 | 作为项目管理员，我可以从所属企业的有效成员中选择尚未加入当前项目的人，按稳定 `userId` 添加为项目成员，并管理当前项目资料、角色和审计；该身份不会提供企业管理、其他项目管理或创建项目的能力。 | 一、身份边界；二、管理页面                       |
+| US-06 | 作为有权管理角色的用户，我可以在授权边界内维护自定义角色并分配角色；内置角色由系统维护，身份委派、不可下放能力及最后管理员约束始终生效。                                                     | 二、内置角色规则；三、授权规则                   |
+| US-07 | 作为平台管理员，我可以维护三套菜单树，并从 React Web 的本地 SVG 图标库搜索、预览和选择任一图标；保存后在编辑表单、菜单列表和实际导航回显。用户看到的页面、按钮和接口访问遵循授权、隐藏与停用规则，受保护管理入口不能被破坏。 | 二、菜单管理 |
+| US-08 | 作为多企业、多项目成员，我可以选择和切换自己的工作空间，刷新后恢复目标空间；快速切换、退出换号时不会看到上一用户或上一作用域的数据和权限。                                                   | 三、共享契约与接口；三、前端接入                 |
+| US-09 | 作为上级管理员，我可以按既定入口停用和恢复企业、项目或成员；停用保留子级自身状态及授权，移除清理相应关系，恢复不会还原已撤销授权或已撤销会话。                                               | 二、停用、恢复与管理员设置                       |
+| US-10 | 作为平台管理员，我可以禁用企业唯一管理员的全局账号，并为启用或停用企业补任、更换管理员；更换事务失败时不留下部分结果，且平台自身最后有效管理员始终受保护。                                   | 二、停用、恢复与管理员设置；三、授权规则         |
+| US-11 | 作为相应作用域的审计查看者，我可以查看授权范围内的成功管理变更及对象、操作者、时间等信息；平台维护行为按平台事件记录，日志不包含敏感凭据。                                                   | 三、数据模型；三、后端鉴权                       |
+| US-12 | 作为使用者和维护者，我可以在功能发布期间继续使用旧前端已识别的功能；新版加载后显示符合授权的新功能，废弃权限由平台预览并在条件满足后安全清理。                                               | 二、功能发布与废弃权限清理                       |
+| US-13 | 作为维护者，我可以在空库和现有数据库执行迁移、初始化与升级，保留已有账号、用户授权和允许配置的菜单内容；现有上传继续按原所有者授权。                                                         | 四、实施阶段与数据兼容                           |
+| US-14 | 作为执行敏感管理操作的用户，我的操作与撤权按数据库提交顺序生效；撤权先完成时，先前在事务外通过的权限检查不能继续批准写入。                                                                   | 三、并发撤权与事务边界                           |
+
+## 4. 15 项验收映射
+
+AC 编号与需求文档“五、验收标准与后续范围”的原编号一一对应。下表是追踪摘要，详细条件仍以原文为准；后续测试报告必须逐项给出通过、失败或无法验证及证据，不以未执行或跳过代替通过。
+
+| 验收编号／原编号             | 对应用户故事                      | 必须验证的结果摘要                                                                                                                                                                                               | 验证证据类型                                    |
+| ---------------------------- | --------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------- |
+| AC-01／1 完整业务流程        | US-01、US-02、US-03、US-04、US-05 | 注册、开通企业、企业成员新增展示直接注册与邀请两个入口；当前完整流程只验收直接注册分支，邀请分支待协议确认后另补验收。创建项目、从所属企业候选添加项目成员、成员授权及功能访问串联成功，已确认事务失败整体回滚。 | Playwright 关键流程；数据库事务集成测试         |
+| AC-02／2 权限隔离            | US-02、US-05、US-06、US-08        | 同账号跨企业、项目分别授权；平台维护例外不变成企业业务访问权；企业管理员无显式项目成员记录仍可管理本企业项目。                                                                                                   | 权限规则测试；接口集成测试                      |
+| AC-03／3 菜单一致性          | US-06、US-07                      | 已注册功能的导航、页面、按钮与接口符合相同规则；隐藏可按授权直达，停用阻断功能及下级，管理员亦受约束。图标选择器自动覆盖本地 SVG 图标库，保存值在表单、列表及导航一致回显，未知值使用缺省图标。菜单管理保持树形父子关系，名称列不换行，只有存在真实子级的节点显示展开控件。 | 权限规则测试；前端组件与菜单映射测试；接口集成测试；Playwright |
+| AC-04／4 即时撤权            | US-06、US-09、US-10               | 角色撤销、成员停用或移除、企业或项目停用后，后续请求按最新授权拒绝相应访问。企业身份提供的项目管理能力按原文单独判断。                                                                                           | 接口集成测试；Playwright 权限刷新流程           |
+| AC-05／5 切换与缓存          | US-08                             | 快速切换作用域与退出换号时，旧数据、旧权限和迟到请求不会覆盖当前页面；菜单路由等待提交期间旧页面保持不可交互但视觉连续，目标页面提交后再替换。                                                                     | Playwright 切换及请求竞态验证                   |
+| AC-06／6 管理约束            | US-03、US-06、US-07、US-09、US-10 | 重复关系、越权授权、受约束菜单删除和循环关系被拒绝；最后有效管理员约束覆盖并发变化。邀请的有效期、状态、撤销／重发、接受／拒绝和幂等规则待确认，不纳入当前验收。                                                 | 权限规则测试；真实数据库并发集成测试            |
+| AC-07／7 数据与审计          | US-02、US-03、US-05、US-11        | 跨作用域查询符合统一边界，成功管理变更与审计一致；密码或完整敏感请求不进入列表、日志或审计。邀请是否审计及其字段待确认，不纳入当前验收。                                                                         | 接口与数据库集成测试；审计内容检查              |
+| AC-08／8 回归与迁移          | US-01、US-08、US-13               | Cookie、Storage、请求层、旧用户登录和上传兼容保持正确；空库、现有库迁移和重复初始化满足原文约束。                                                                                                                | 现有回归测试；迁移及初始化集成测试              |
+| AC-09／9 停用与恢复          | US-09                             | 企业恢复不启用原先单独停用的项目；成员恢复保留子级原状态，不还原已撤销角色；账号启用后重新登录。                                                                                                                 | 状态规则测试；接口集成测试；Playwright 恢复流程 |
+| AC-10／10 管理员补任与更换   | US-02、US-09、US-10               | 平台可为启用或停用企业补任管理员并建立或启用成员关系；更换整体提交，旧账号恢复不重获已撤销身份，范围恢复前校验有效管理员。                                                                                       | 权限规则测试；事务集成测试；Playwright          |
+| AC-11／11 创建项目身份限制   | US-04、US-05、US-06               | 仅有效内置企业管理员可创建项目；普通角色授权树和直接构造请求均不能下放或绕过该限制。                                                                                                                             | 权限规则测试；接口集成测试；Playwright          |
+| AC-12／12 内置角色与新增功能 | US-06、US-07、US-12、US-13        | 人工角色管理不能更改内置定义；新增功能只自动扩展对应内置管理员权限，用户角色分配和既有菜单配置不被初始化覆盖。                                                                                                   | 权限及种子升级测试；接口集成测试                |
+| AC-13／13 前端版本兼容       | US-07、US-12                      | 旧前端过滤未知页面、所属按钮和空目录，直达未知页面显示 404；实际加载新版后按当前授权和菜单状态显示，服务端配置不因过滤改变。                                                                                     | 前端菜单映射测试；Playwright 版本兼容验证       |
+| AC-14／14 废弃权限清理       | US-07、US-11、US-12、US-13        | 仅平台管理员可预览和执行符合条件的明确废弃项；重新校验预览后的变化，保护有效依赖，失败回滚、重复执行安全、审计及版本更新完整，初始化不复生。                                                                     | 权限规则测试；事务与初始化集成测试；Playwright  |
+| AC-15／15 在途写操作与撤权   | US-06、US-09、US-10、US-12、US-14 | 真实数据库验证写入先持锁与撤权先提交两种顺序；锁内重新鉴权，共同加锁，失败不提交业务变更或成功审计。                                                                                                             | 真实 PostgreSQL 并发集成测试                    |
+
+## 5. 已确认的关键边界
+
+- 工作空间入口按有效身份展示：普通账号未加入企业时显示该状态；邀请载体和加入流程待确认。平台管理员无企业仍保留平台入口，不能以企业列表为空作为整页阻断平台入口的条件。
+- 平台开通企业、设置或更换企业管理员使用全局账号选择器并提交 `userId`；企业新增普通成员只允许直接注册或邀请，不能复用平台账号枚举能力。
+- 企业邀请只确认作为企业成员新增入口存在。有效期、token、是否绑定账号、发送、状态、接受／拒绝、撤销／重发、幂等、数据表、DTO、端点和审计均待确认。
+- 项目新增成员只能查询所属企业有效成员，排除已加入当前项目者，提交 `userId` 后由服务端重新校验企业成员资格和重复关系。
+- 企业管理员的项目管理能力及项目有效管理员计数来自企业身份，不要求复制项目成员或角色记录；不新增项目必须长期保留专任管理员的要求。
+- 创建项目属于内置企业管理员专属能力，不能通过自定义角色下放；平台开通企业和设置企业管理员不等同于平台直接取得企业内部业务权限。
+- 停用、移除和恢复按源文档状态表执行；企业停用后先由平台恢复企业，再通过有效企业入口管理项目。平台在停用企业设置或更换管理员属于明确例外。
+- 平台禁用全局账号可以使企业暂时缺少有效管理员，但平台自身最后有效管理员不得失效；管理员更换和恢复校验按源文档事务规则执行。
+- 内置角色定义禁止人工修改，系统版本升级与合规的废弃权限清理可以维护系统定义；自定义角色不随新功能自动扩权。
+
+## 6. 接口草案与契约交接
+
+下表整理已确认需求中的接口范围。具体方法、请求和响应字段、业务错误、数据模型及锁规则由 [技术契约](./技术契约.md) 统一定义，前后端共同使用该契约。
+
+| 已确认接口范围                                | 业务用途                                                                                     | 对应用户故事                      |
+| --------------------------------------------- | -------------------------------------------------------------------------------------------- | --------------------------------- |
+| 现有认证体系下的注册与登录能力                | 公开注册、登录、全局账号状态及会话撤销兼容                                                   | US-01、US-02、US-10、US-13        |
+| `GET /workspaces`                             | 返回当前用户可进入的工作空间；平台入口与企业成员列表分别按有效身份判断                       | US-01、US-02、US-08               |
+| `/platform/*`                                 | 企业开通与启停、企业管理员设置与更换、账号、角色、菜单、废弃权限预览与清理、平台审计         | US-02、US-07、US-10、US-11、US-12 |
+| `/companies/:companyId/*`                     | 企业资料、成员直接注册、邀请入口（具体接口待确认）、角色、项目列表与创建、项目启停及企业审计 | US-03、US-04、US-06、US-09、US-11 |
+| `/companies/:companyId/projects/:projectId/*` | 当前项目资料、成员、角色及项目审计                                                           | US-05、US-06、US-09、US-11        |
+| 各作用域下的 `/access`                        | 返回当前已验证作用域的菜单与权限上下文                                                       | US-06、US-07、US-08、US-12        |
+
+契约应承接原文已有的共享类型与工具目录、三种作用域、权限上下文、分页上限、统一响应与异常、401／403／404 边界以及管理写入的事务鉴权要求。这里不重复定义实现类型，以免与后续统一契约产生双份口径。
+
+企业邀请尚未进入接口与验收契约。此前列出的列表／创建／撤销／重发／接受 5 个固定端点，以及关联 DTO、token、安全、状态、错误码、事务与审计规则全部撤回，待产品确认后重新设计并同步[技术契约](./技术契约.md)。
+
+## 7. 明确排除范围
+
+- 企业和项目物理删除、项目跨企业迁移。
+- 权限专项内另建“部门”模型或部门权限作用域；组织结构统一由组织架构专项的“组织单元”承载。字段级权限、审批流、SSO、外部协作者同样不在本专项范围。
+- 企业独立菜单副本、角色继承和显式拒绝规则。
+- 通过后台菜单配置创建未开发的页面、保存可执行组件路径，或让旧前端通过刷新权限获得不存在的页面代码。
+- 企业、项目上传归属改造及历史上传租户迁移；现有上传仍按 `ownerId` 授权，不将本期交付描述为已完成上传租户隔离。
+- 自动为注册用户创建或分配企业、自动提升首位注册用户、提供固定默认管理员密码。
+- 企业邀请的具体协议和功能闭环；在有效期、token、账号绑定、发送、状态、接受／拒绝、撤销／重发、幂等、数据表、DTO、端点及审计确认前，不纳入当前交付与验收。
+
+未在已确认需求中列出的企业功能，不因“企业级”名称自动纳入本期。验收和实现细节的必要澄清应回写统一契约并由主控协调，不能借此增加业务政策。
+
+## 8. 交付与验证要求
+
+实施阶段沿用源文档的契约与数据库、后端权限闭环、前端管理闭环、联调与交付四阶段。后续产物至少包括统一契约、可审阅迁移、接口及权限说明、联调记录和逐项测试报告。
+
+验证采用权限规则测试、真实 PostgreSQL／Redis 接口集成测试及 Playwright 关键流程测试；完成 `vp check`、相关测试与 shared、Web、Server 构建。真实环境测试跳过时须明确记录为未验证，不能记为通过。测试所需敏感值仅在运行期使用，不写入源码或交付文档。
+
+本 PRD 已完成 15／15 项验收追踪映射；尚未记录实现通过率，具体执行结果交由后续测试报告提供。需求输入和 PRD 确认沿用本会话授权，不重复向用户提问。
+
+## 9. 后续扩展事项
+
+- 邀请协议确认后，应直接更新本文及需求、技术契约和测试范围，不以当前仓库实现作为默认方案。
+- 当前仓库已有 `apps/server/drizzle/0004_company-member-invitations.sql` 以及相应后端、前端实现，属于未获产品确认的实现偏差。本轮不修改代码；这些实现和既有自动化结果不能倒推需求，也不能作为发布依据。
+- PRD 的规则确认不等于实现或验收完成；当前增量联调与测试状态以对应报告为准。
+
+## 10. 变更记录
+
+| 日期       | 变更摘要                                                                                                                                                   | 原因                                         | 影响范围                                                          |
+| ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------- | ----------------------------------------------------------------- |
+| 2026-09-19 | 菜单图标改用本地 SVG 资源自动发现和可视化选择；页面、目录、按钮／操作节点按语义分配默认图标，保存后在管理页与导航回显，未知 key 降级为缺省图标 | 让菜单图标配置可见、可扩展，并取消 Ant Design 图标名硬编码；避免操作节点空图标 | US-07、AC-03、AC-08、AC-12、AC-13、前端与迁移 |
+| 2026-09-18 | 菜单路由切换等待期间保留旧页面视觉内容并禁用交互，目标路由提交后再替换                                                                                         | 过早卸载 `RouteTransition` 会丢失旧页面视图快照，导致过渡动画消失 | AC-05、工作空间布局、导航等待态与测试                         |
+| 2026-09-18 | 纠正企业邀请口径：只保留“直接注册或邀请”两个已确认入口，撤回 7 天、固定 5 端点及其余未确认协议；将仓库 `0004` 与前后端邀请实现标记为实现偏差，本轮不改代码 | 先前将未经产品确认的方案写成了需求和验收事实 | 文档状态、US-01、US-03、AC-01、AC-06、AC-07、接口、迁移与发布判断 |
+| 2026-09-17 | 企业成员入口改为直接注册／邀请；项目成员入口改为从所属企业有效成员中选择并按 `userId` 提交                                                                 | 最新需求替代原“完整账号添加”规则             | US-03、US-05、AC-01、成员接口与测试                               |
+| 2026-09-17 | 明确平台管理员选择仍使用全局账号选择器                                                                                                                     | 平台与企业、项目的账号可见范围不同           | 企业开通、管理员设置和选择器权限                                  |

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//346/235/203/351/231/220/344/270/216/350/217/234/345/215/225//345/206/263/347/255/226/350/256/260/345/275/225.md

@@ -0,0 +1,29 @@
+# 企业、项目、账号选择与成员接入决策记录
+
+> 状态：当前决策索引。本文只记录跨轮次讨论形成的结论与状态，具体业务规则以同目录的现行需求、PRD 和技术契约为准。
+>
+> 整理日期：2026-09-18。
+
+## 决策
+
+| 日期       | 结论                                                                                                                                                                                                                                                           | 状态                             | 原因                                                                         | 影响范围                                               | 正式文档                                                                             |
+| ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------- | ---------------------------------------------------------------------------- | ------------------------------------------------------ | ------------------------------------------------------------------------------------ |
+| 2026-09-18 | 菜单路由切换等待期间保留旧页面视觉内容并隔离交互，加载层覆盖；目标路由提交后再替换页面，以维持 `RouteTransition` 的旧快照和滑动动画。                                                                                                                               | 当前有效                         | 等待态提前卸载过渡容器会使浏览器无法采集旧页面快照，菜单切换动画随之消失。     | 工作空间布局、导航等待态、前端回归测试与交付验证   | [需求文档](./需求文档.md)、[PRD](./PRD.md)、[技术契约](./技术契约.md)、[前端交接](./前端交接.md) |
+| 2026-09-17 | 平台账号使用全局唯一的 `userId` 作为人员关系值；`account` 全局唯一，姓名不要求唯一。                                                                                                                                                                           | 当前有效                         | 姓名不能稳定识别人，账号展示值也不应代替内部关系键。                         | 管理员选择、成员关系、搜索结果、同名辨识               | [需求文档](./需求文档.md)、[技术契约](./技术契约.md)                                 |
+| 2026-09-17 | 平台开通企业、设置或更换企业管理员时使用 `GlobalAccountSelect`，提交字段统一为 `administratorUserId`。                                                                                                                                                         | 当前有效                         | 平台具有全局账号可见范围，且管理员必须绑定稳定账号。                         | 企业开通、管理员补任与更换、共享 DTO、前后端接口       | [需求文档](./需求文档.md)、[PRD](./PRD.md)、[技术契约](./技术契约.md)                |
+| 2026-09-17 | 全局账号选择能力不开放给企业普通成员新增入口；企业不能借成员管理枚举全平台账号。                                                                                                                                                                               | 当前有效                         | 保持企业隔离并减少全局账号信息泄露。                                         | 企业成员页面、候选接口、权限校验                       | [需求文档](./需求文档.md)、[技术契约](./技术契约.md)                                 |
+| 2026-09-17 | 企业新增成员只保留“直接注册新账号并加入企业”和“邀请”两个产品入口。                                                                                                                                                                                             | 当前有效                         | 在不开放全局账号枚举的前提下，为企业成员接入保留两种产品路径。               | 企业成员页面与成员接入边界                             | [需求文档](./需求文档.md)、[PRD](./PRD.md)、[技术契约](./技术契约.md)                |
+| 2026-09-18 | 企业邀请有效期、token、是否绑定账号、发送、状态、接受／拒绝、撤销／重发、幂等、数据表、DTO、端点和审计均待产品确认；此前的 7 天、固定 5 端点等结论撤回。仓库现有 `0004` 及后端、前端邀请实现属于未获确认的实现偏差，本轮不改代码，不能倒推需求或作为发布依据。 | 当前有效，等待产品确认           | 先前把实现方案误写为用户已确认需求，需要恢复需求、PRD 和契约的真实确认边界。 | 邀请需求、迁移、共享 DTO、接口、前后端、测试与发布判断 | [需求文档](./需求文档.md)、[PRD](./PRD.md)、[技术契约](./技术契约.md)                |
+| 2026-09-17 | 项目新增成员只能从所属企业的有效成员中选择，候选排除已加入当前项目者，保存 `userId`，服务端写入时再次校验。                                                                                                                                                    | 当前有效，已实现并完成自动化复验 | 项目成员必须先具备所属企业成员资格，且前端候选不能代替服务端约束。           | 项目成员选择器、成员接口、事务校验、测试               | [需求文档](./需求文档.md)、[技术契约](./技术契约.md)                                 |
+| 2026-09-17 | 通用成员选择器按调用者权限提供企业／项目来源，并可按角色、组织单元和岗位辅助筛选；稳定选择值仍为 `userId`。                                                                                                                                                    | 当前有效，按场景裁剪             | 兼顾跨作用域定位、同名辨识和最小可见范围。                                   | `OrganizationMemberSelector`、流程选人、组织成员维护   | [组织架构需求](../组织架构/需求文档.md)、[组织架构技术契约](../组织架构/技术契约.md) |
+
+## 被替代或禁止的旧口径
+
+- 企业或项目成员通过“完整账号”直接拉入的旧入口不再是当前需求；历史联调和测试结果只能作为旧实现基线。
+- 不得把 7 天有效期、不绑定账号、链接发送、状态机、主动接受、撤销／重发、token 轮换、幂等、固定数据表／DTO／端点或审计规则继续表述为已确认需求。
+- `0004_company-member-invitations.sql` 及现有后端、前端邀请实现只能作为待处置的实现偏差，不能替代产品确认、倒推契约或作为发布依据。
+- 选择器返回的展示姓名、账号、角色、组织和岗位只用于识别与筛选，人员关系始终保存 `userId`。
+
+## 变更规则
+
+后续结论发生变化时，先修改对应的现行需求、PRD 和技术契约，再更新本记录的状态与替代关系；不得新建 `v2`、`最终版` 或聊天全文副本。

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//346/235/203/351/231/220/344/270/216/350/217/234/345/215/225//345/211/215/347/253/257/344/272/244/346/216/245.md

@@ -0,0 +1,74 @@
+# 前端实现与验证交接
+
+> 文档状态：历史基线＋当前证据边界。企业邀请只确认产品入口，固定协议仍待产品确认。
+
+历史交接日期：2026-09-10。前端实现以已确认需求及 [技术契约](./技术契约.md) 为准，业务代码修改范围仅为 `apps/web`。2026-09-17 成员接入契约已经变更，原交接与测试结果仅作为历史基线，不能证明当前成员入口已经实现或通过。
+
+## 2026-09-18 当前口径与待复验范围
+
+- 平台创建企业、设置或更换企业管理员统一使用 `GlobalAccountSelect`，表单保存 `userId` 并提交 `administratorUserId`，不再把账号字符串作为关系标识。
+- 企业成员页当前已确认的新增能力是“直接注册新账号并加入企业”，提交姓名、完整账号和密码；不能继续使用完整账号搜索并直接拉入既有平台账号。
+- 企业邀请只确认是企业新增成员的另一条产品入口；邀请对象、载体、有效期、状态、接受／拒绝、撤销／重发、安全与审计规则均待确认。
+- 当前前端已存在 7 天链接管理和 `/member-invitations/accept?token=...` 接受页，但这是未获产品确认的实现记录，不是现行交接要求，不得据此继续扩展或宣称产品可用。
+- 项目成员页使用 `OrganizationMemberSelector` 的 `purpose=addProjectMember`，只展示所属企业有效且未加入当前项目的成员，选择和提交均为 `userId`；不展示组织、岗位或角色标签。
+- 管理员选择、企业直接注册和项目成员候选已有组件／请求层自动化与构建证据，但当前真实浏览器全过程和正式环境仍未复验。邀请相关测试只能证明现有实现行为，不能替代产品确认或产品验收。
+
+## 实现范围
+
+- `src/pages/register`、`src/pages/login/index.tsx`：公开注册、登录、注册成功账号提示，以及登录后的工作空间入口。
+- `src/pages/workspaces`：按服务端有效身份展示企业、项目和平台工作空间。无企业普通账号不得被要求提供完整账号供管理员直接挂接；具体邀请引导文案应在协议确认后定稿。有效平台身份仍保留平台入口。
+- `src/pages/access`：工作台、企业开通与启停、项目创建与启停、管理员补任与更换、账号与成员管理、角色分配、自定义角色与权限树、资料、三套菜单编辑、废弃权限清理预览与执行、审计筛选与分页。当前邀请列表／创建／撤销／重发界面仅作为未确认实现登记。
+- `src/pages/member-invitations`：当前存在基于 URL token 的登录／注册和主动确认页面，仅作为未确认实现登记；产品协议确认前不把其路由、状态或交互当作稳定契约。
+- `src/pages/access/components`：通过 `show/hide` 暴露弹窗操作，所有写操作使用共享契约 DTO。内置角色定义只读；权限树保留页面和操作的依赖关系及全选、半选行为。
+- `src/router`：17 个静态管理页面注册，路由按功能拆入 `modules`，父级 scope middleware 获取作用域上下文，叶子 access middleware 校验页面权限；未知页面显示 404。页面 403 不会清空其他可用导航；空间首页无读权限时，优先进入可见菜单中的已授权静态页面。默认入口对无平台或额外企业职责的单项目成员直接进入项目，其余进入工作空间；明确选择的工作空间和页面不被分流覆盖。示例页面不出现在生产菜单。
+- `src/router/lazy-load`、`src/App.tsx`：使用 `lazyLoad('access', 'home')` 等相对 pages 的路径统一懒加载，并在 App 中只保留一个 `RouteTransition`。
+- `src/layouts/WorkspaceLayout/index.tsx`、`workspace.css`：三种作用域布局、具体企业／项目名称、导航和切换；菜单路由等待期间保留旧页面视觉内容并禁用交互，由加载层覆盖，目标路由提交后再替换以保持 `RouteTransition` 动画；进入新空间时重建业务子树；权限刷新时隐藏页面并保留表单输入。
+- `src/utils/request/workspace.ts`：沿用现有 alova 请求封装；管理请求禁止缓存，取消旧请求，使用用户、作用域和请求代次阻止迟到结果。旧 401 不得退出新账号，旧 403 不得刷新新空间。当前业务 403 刷新一次，access 403 不递归。
+- `test/workspace-requests.spec.ts`、`test/workspace-navigation.spec.ts`、`test/router`：权限导航、请求竞态、入口分流及真实 React Router memory 导航回归测试；原 loader 测试迁移至 middleware 测试。
+
+## 2026-09-10 middleware 简化历史验证
+
+- 移除根 `navigationMiddleware`、`router.subscribe` 和导航快照桥。具体 middleware 通过原生 Router context 交接校验数据；布局从 `pages/workspaces/state.ts` 按当前空间读取权限，再通过 `Outlet context` 传给页面。状态按登录会话隔离，每次导航仍请求最新权限。
+- Web 全量 `vp test`：9 个文件、81 项通过。原快照桥的 10 项实现测试替换为 6 项工作空间行为测试，入口及权限的 28 项测试继续保留；请求层的取消、换号和迟到响应测试不变。
+- 测试 TypeScript 检查、Web TypeScript／Vite 构建及本次 14 个代码文件的定向 `vp check` 通过。
+- 浏览器使用本机前端和拦截 API 响应验证：登录单项目直达、唯一过渡容器、叶子拒绝保留父布局、同位置刷新名称、页面撤权与恢复、整个空间撤权清除布局与重试恢复、慢速项目切换、手动选择及刷新为空列表。无页面运行时异常；本轮未连接真实后端。
+
+## 2026-09-10 middleware 重构历史验证（简化前）
+
+- Web 全量 `vp test`：9 个测试文件、85 项测试通过，其中 `test/router` 的 38 项覆盖默认入口、权限边界、导航取消、换号、刷新和 Fetcher 隔离。
+- `vp run --filter web build`：TypeScript 与 Vite 构建通过。
+- 浏览器使用本机前端和拦截 API 响应验证：登录后单项目直达、全局唯一过渡容器、手动选择工作空间、明确企业目标、Hash 导航、叶子 403 保留父布局、作用域撤权清除布局、重新加载恢复、再次撤权及返回空工作空间；无页面运行时异常。本轮未连接真实后端。
+- 仓库全量 `vp check` 仍被其他文件的格式问题阻挡；本次范围单独执行检查，不对全仓执行格式修复。
+
+## 2026-09-09 验证记录
+
+以下保留 2026-09-09 的实际验证记录，命令、文件名和数量反映当时实现；不作为后续 middleware 重构的验证结果：
+
+| 命令                                                                                                                                                                                                                                                                                                                            | 结果                                                                                                                                           |
+| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+| `vp run --filter web build`                                                                                                                                                                                                                                                                                                     | 通过。TypeScript 检查完成，Vite 构建 4494 个模块。现有 ProTable 相关产物存在大于 500 kB 的 chunk 提示，没有通过提高阈值隐藏提示。              |
+| `vp run --filter web test`                                                                                                                                                                                                                                                                                                      | 6 个测试文件、43 项测试全部通过：storage 14、request 11、draft-projects 4、workspace-requests 5、workspace-navigation 6、workspace-loaders 3。 |
+| `vp check apps/web/src/utils/request/workspace.ts apps/web/src/pages/access apps/web/src/pages/register apps/web/src/pages/workspaces apps/web/src/router apps/web/src/layouts/WorkspaceLayout.tsx apps/web/test/workspace-requests.spec.ts apps/web/test/workspace-navigation.spec.ts apps/web/test/workspace-loaders.spec.ts` | 31 个文件格式正确，无 lint 警告、错误或类型错误。                                                                                              |
+| `git diff --check -- apps/web`                                                                                                                                                                                                                                                                                                  | 无空白错误。Windows Git 的 LF／CRLF 提示不影响此结论。                                                                                         |
+
+14 项新增测试覆盖：切换取消与迟到成功；换号后的旧 401；旧作用域 403；当前 403 单次刷新与 access 防递归；Router AbortSignal；未知菜单、所属操作和空目录过滤且不改源数据；隐藏／停用导航与静态路由；未知／跨作用域 routeKey；服务端允许图标的完整前端映射；可见授权页面优先落点；没有受支持页面时无落点；叶子 403 保留父级上下文且可进入其他管理页；首页停用后自动重定向；整个作用域身份撤销后不保留旧上下文。
+
+最终检查前修复了菜单平铺后的父级选择问题：编辑器从原始树定位当前节点并排除自身及全部后代，防止平铺行的空 children 漏掉后代选项。
+
+联调复查发现并修复资料保存后的本地版本未递增问题：保存成功合并服务端返回的最新资料及 version，后续编辑使用最新版本；真正版本冲突仍保留输入。该修复已重新通过完整 TypeScript／Vite 构建及 31 文件检查，连续保存的真实浏览器验证交由 QA。
+
+## 联调边界
+
+- 页面直接调用真实 API，没有使用 mock 数据。共享类型与纯工具统一从 `shared/types`、`shared/utils` 导入。
+- 企业项目列表的管理员设置使用已同步契约的 `GET /companies/:companyId/projects/:projectId/administrators`，支持读取停用项目的显式项目管理员，避免将企业隐式管理员当作待替换的项目身份。
+- React Router 当前安装版本为 8.3.1，使用原生 Data Mode middleware。工作空间列表及各空间权限保存在 `pages/workspaces/state.ts`，页面随导航或重新校验完成后读取。布局通过 `Outlet context` 向子页面提供同一份权限；缺数据时显示加载态，避免撤权过渡中的旧页面读取空权限。不再订阅路由状态或维护导航快照。
+- 开发前端默认 API 前缀为 `/api`；隔离联调环境由主控启动，前端端口 5301，后端端口 3301。前端代理通过 `VITE_API_URL` 配置。
+- Playwright 真实页面、后端接口和数据库事务验收由主控及 QA 独立执行，结果应写入最终测试报告，不能用本交接中的静态检查替代。
+
+## 变更记录
+
+| 日期       | 变更摘要                                                                                                                                         | 影响范围                                 |
+| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------- |
+| 2026-09-18 | 修正菜单路由等待态：保留旧页面视觉内容并隔离交互，目标路由提交后再替换以恢复 `RouteTransition` 动画                                               | 工作空间布局、导航等待态与前端回归测试 |
+| 2026-09-17 | 增加平台全局账号选择、企业直接注册、邀请入口和项目企业成员候选的前端交接要求；当时写入的固定邀请协议未获产品确认                                 | API、成员页面、选择器、路由、i18n 与测试 |
+| 2026-09-18 | 纠偏邀请前端口径：7 天管理界面和接受页降级为未确认实现记录；保留直接注册和项目 `userId` 候选的自动化证据，并明确缺少当前真实浏览器／正式环境复验 | 成员页面、邀请页面、路由与验证状态       |

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//346/235/203/351/231/220/344/270/216/350/217/234/345/215/225//345/220/216/347/253/257/346/265/213/350/257/225/346/212/245/345/221/212.md

@@ -0,0 +1,115 @@
+# 企业级／项目级后端交接与测试报告
+
+> 文档状态：历史基线＋成员接入实现证据。企业邀请固定协议未获产品确认，相关测试不构成现行契约或产品验收。
+
+历史验收日期：2026-09-09。范围：`apps/server`。测试使用独立本机 PostgreSQL、Redis 与队列，不初始化或清理 QA 的 `enterprise_test` 数据库。2026-09-17 后曾执行成员接入自动化与真实 PostgreSQL／Redis 集成测试；原 33/33 结果仍只作为历史基线，新增结果按下述产品确认边界解释。
+
+## 2026-09-18 增量证据边界
+
+- 平台创建企业和设置企业管理员统一提交 `administratorUserId`；服务端按有效全局账号校验，前端 `GlobalAccountSelect` 负责搜索和回显。
+- 企业成员直接注册已覆盖账号、企业成员、默认 member 角色和审计同事务写入，密码不进入审计、日志或响应。
+- 企业邀请只确认产品入口，具体协议仍待确认。当前 7 天一次性 token、列表／创建／撤销／重发／接受 5 个端点及 `drizzle/0004_company-member-invitations.sql` 是未获产品确认的实现偏差；相应真实 PostgreSQL／Redis 结果只能证明这套代码的既有行为，不属于现行契约、联调通过或产品验收。
+- 项目成员写接口接收 `{ userId }`，已覆盖账号有效、所属企业成员有效、尚未加入当前项目三项事务内校验，以及跨企业、停用和重复关系拒绝。
+- 当前标准服务端测试 31 项通过，23 项因环境门控跳过；开启真实依赖的成员接入实现专项 22 项通过，构建通过。上述数量如实保留为技术执行记录；其中邀请断言不得计入现行产品验收，且本报告未执行当前成员入口的真实浏览器或正式环境验证。
+
+## 2026-09-09 历史交付范围
+
+- `src/modules/access/`：工作空间、平台企业与账号、企业项目、成员、角色、菜单、审计、管理员补任／替换、废弃权限预览与清理。
+- `src/database/access.schema.ts` 与增量迁移 `drizzle/0002_enterprise_access.sql`、对应 snapshot/journal；保留既有迁移。
+- 全局权限默认拒绝；公开、仅登录和业务范围策略均需明确声明。平台身份不自动获得企业访问权，企业管理员隐式管理本企业项目，创建项目要求内置企业管理员。
+- 写操作使用 PostgreSQL 事务级管理锁，取得锁后重新鉴权；数据库约束保护归属、唯一性、权限页面引用和版本。审计与业务写入同事务。
+- 停用保留子级自身状态；移除企业成员清理项目成员和授权；恢复或重新加入不会恢复已撤销角色。
+- 内置角色禁止编辑删除；新增目录权限自动补给内置管理员；菜单隐藏只影响导航，停用和祖先停用阻断对应接口权限。
+- 受控部署证明、证明摘要、废弃清单、菜单子项和在用版本依赖核验；清理带事务、版本递增与 tombstone，重复操作幂等、种子不复活。
+- `src/access-init.ts` 与 `access:init`：一次性指定已注册账号成为首位平台管理员，同账号重复执行安全，不会借重复初始化给其他账号提权。
+- 账号状态参与每次会话校验；登录创建会话持用户行共享锁，禁用持排他锁。禁止停用最后一位平台管理员时不撤会话；审计失败时保持账号状态和会话。
+
+## 2026-09-09 历史回归修复
+
+1. Redis validate 脚本缺少局部 `isValidDigest` 导致所有 Bearer 接口 503：已补定义，并通过真实 Redis 有效会话与失效会话验证。
+2. Redis revoke 脚本 `DO` 大写语法错误：改为 Lua `do`，真实账号禁用和测试清理通过。
+3. 最后管理员停用被拒绝仍注销：会话撤销移到数据库业务校验、审计和结果读取之后，并保持用户排他行锁。
+4. `UploadSessionParamsDto` 错用分片参数 schema：改为会话参数 schema，分片接口继续单独要求 `partNumber`。
+5. 企业、项目、成员列表原先接受账号专属 `locked` 状态：拆分 `entityListSchema`，在请求边界拒绝非法枚举，避免 SQL 500。
+6. 初始化脚本 ts-node 的 rootDir 问题：新增 `tsconfig.scripts.json` 并配置 `TS_NODE_PROJECT`；服务实际构建入口修正为 `dist/src/main.js`。
+
+## 2026-09-09 历史验证结果
+
+下列结果只覆盖 2026-09-09 当时实现与契约；管理员 `userId`、企业直接注册和项目成员企业候选的新增自动化证据由上一节单独记录，不与历史 33/33 重复计数。邀请自动化只证明未确认实现行为。
+
+| 检查                                                          | 结果                                                     |
+| ------------------------------------------------------------- | -------------------------------------------------------- |
+| 服务端当时全部测试，启用真实权限和队列集成                    | 6 个文件、33 项历史通过，0 跳过                          |
+| 新增权限真实 PostgreSQL／Redis 集成                           | 14 项通过                                                |
+| 新增权限策略／DTO 边界单测                                    | 5 项通过                                                 |
+| 既有错误目录、队列服务、处理器及真实 Redis 队列回归           | 14 项通过                                                |
+| 本轮文件定向 `vp check`                                       | 36 个文件格式通过；34 个文件无 lint 警告、错误或类型错误 |
+| AC-12 追加测试定向 `vp check test/access.integration.spec.ts` | 1 个文件格式、lint 和类型检查通过                        |
+| `vp exec tsc --noEmit`                                        | 通过                                                     |
+| `vp run build`                                                | SWC 成功编译 89 个文件                                   |
+| `vp run access:init` 缺少账号烟测                             | 输出明确用法并返回预期 exit 1，无 ts-node 配置异常       |
+
+真实权限集成每次新建随机 `access_it_<uuid>` 数据库，执行迁移两次验证幂等，使用随机用户会话键；finally 清理数据库、会话和临时证明文件。队列测试采用自身随机 prefix。未执行全库 Redis 清理。
+
+AC-12 追加后，由 QA 于 2026-09-09 23:19 使用下文相同命令复跑完整服务端测试，结果为 33/33 历史通过；后端随后完成新增测试文件的定向检查。此次仅增加测试证据，没有修改生产目录或产品逻辑。原测试中的跨企业项目成员约束不证明当前流程；后续 22 项专项只覆盖服务端及真实依赖边界，仍不能替代真实浏览器和正式环境复验。
+
+14 项集成测试覆盖：
+
+1. 一次初始化、同账号幂等、禁止其他账号提权、新账号无工作空间、初始化审计。
+2. 企业／成员／项目创建、平台不自动入企业、企业管理员隐式项目权限、普通成员不能创建项目。
+3. 项目创建审计失败时项目、角色、成员一起回滚。
+4. 重复成员、内置角色、非法管理员专属授权、跨企业项目成员数据库约束。
+5. 菜单隐藏保留权限、停用阻断管理员权限、受保护菜单不能停用。
+6. 企业停用保留项目自身状态、移除成员清理项目授权、重新加入不复活角色。
+7. 两种真实锁排队时序：业务写先持锁可提交；撤权先持锁时已入队业务写必须重新鉴权并拒绝。通过 `pg_locks` 确认等待状态，失败写没有成功审计。
+8. 两位企业管理员并发停用自己，只能成功一次。
+9. 账号禁用撤销真实 Redis 会话、平台补任替换、恢复不恢复旧管理员角色、最后平台管理员保护且会话保留。
+10. 账号禁用审计失败时账号状态回滚且现有会话有效。
+11. 登录共享行锁与禁用排他行锁真实协调，禁用完成后无残留登录会话。
+12. 清理非废弃子项、仍启用功能、过期证明、变更证明、旧服务依赖、未选子项均阻断；审计失败全回滚、成功幂等、tombstone 和种子不复活。
+13. 菜单乐观版本、数据库正版本约束、审计敏感字段检查。
+14. AC-12 真实目录升级：先初始化并创建自定义角色、成员分配和菜单定制，再向测试内存目录加入新页面与操作，使用真实 `getBuiltinPermissionKeys` 同步。仅企业范围内置管理员的权限和角色版本扩展；平台／项目角色、内置普通成员、自定义角色权限和用户角色分配保持不变；既有菜单名称、父级、图标、排序、隐藏和停用等全部字段保持；仅对应范围菜单版本递增，重复同步完全幂等。
+
+5 项策略／DTO 测试覆盖默认拒绝、明确公开和仅登录策略、公司／项目范围解析、列表状态枚举、上传会话与分片参数区分。
+
+## 历史基线复现命令
+
+以下命令用于复现 2026-09-09 测试基线，不自动覆盖 2026-09-17 待复验范围。临时配置由主控创建，仅存在本机临时目录，不写入仓库：
+
+```powershell
+$env:RUN_ACCESS_INTEGRATION='true'
+$env:RUN_QUEUE_INTEGRATION='true'
+node scripts/with-enterprise-test-env.mjs "$env:TEMP/codex-enterprise-01a085-runtime.json" apps/server C:/Users/Administrator/.vite-plus/bin/vp.exe test
+```
+
+在 `apps/server` 目录运行定向检查：
+
+```powershell
+vp check src/modules/access src/database/access.schema.ts src/database/schema.ts src/common/decorators/access-policy.decorator.ts src/modules/auth/auth.controller.ts src/modules/auth/auth.repository.ts src/modules/auth/auth.service.ts src/modules/auth/guards/session-auth.guard.ts src/modules/auth/session/session.script.ts src/modules/auth/session/session-store.service.ts src/modules/upload/upload.controller.ts src/modules/upload/dto/upload-params.dto.ts src/app.module.ts src/access-init.ts test/access.integration.spec.ts test/access-policy.spec.ts test/error-catalog.spec.ts package.json tsconfig.scripts.json
+vp exec tsc --noEmit
+vp run build
+```
+
+历史基线当时采用“数据库增量迁移 → 构建 shared 和 server → `node dist/src/access-init.js --account <已注册完整账号>` 初始化”的顺序，源码初始化方式为 `vp run access:init -- --account <已注册完整账号>`，运行入口为 `vp run build:preview`。这只是历史复现记录，不是当前部署指令；当前完整迁移链包含企业层级残留 `0003` 和未确认邀请 `0004`，两项阻断解除并重新验证前不得执行迁移或发布。
+
+## 范围与未测边界
+
+- HTTP、浏览器和真实 MinIO 上传验收由 QA 负责，具体计数和截图以 QA 报告为准；本报告不将服务层测试描述成浏览器测试。
+- 当前独立企业边界和成员入口尚未完成真实浏览器全过程或正式环境复验。`0003` 的企业层级实现仍需清理；邀请协议尚未确认，因此即使其 5 个端点和 `0004` 通过自动化，也不能据此给出发布、迁移或产品验收结论。
+- 清理成功路径使用测试模块扩展的废弃页面／操作目录。生产首版没有虚构的废弃功能，因此生产界面预览为空属于预期。
+- 管理写操作当前共用一把事务级 advisory lock，优先保证撤权与业务修改的顺序。本轮未进行大规模企业／项目的吞吐和性能压测。
+- PostgreSQL 和 Redis 没有共同的分布式事务。本轮覆盖业务检查失败、审计失败、真实行锁与正常会话撤销；没有注入数据库最终 COMMIT 与 Redis 连接同时故障的组合场景。
+- 全仓已有无关格式问题，由主控记录；本轮只修复和检查自身改动范围。
+
+## 后端知识点
+
+事务负责一组数据库写入共同提交或回滚；锁负责并发顺序。把鉴权放在取得写锁之后，才能防止排队请求使用已经撤销的权限。`expectedVersion` 则负责发现用户提交旧表单，两者解决不同问题。
+
+会话位于 Redis，账号状态和权限位于 PostgreSQL。用户行共享／排他锁协调登录与禁用：登录创建会话期间不能被禁用插入，禁用完成后登录会重新检查账号状态。最后管理员和审计检查必须先完成，才能避免被拒绝的操作产生会话副作用。
+
+## 变更记录
+
+| 日期       | 变更摘要                                                                                                           | 影响范围                                        |
+| ---------- | ------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------- |
+| 2026-09-17 | 完成全局管理员选择、企业直接注册、邀请实现及项目企业成员候选的后端实现与自动化；当时写入的固定邀请协议未获产品确认 | DTO、Schema、迁移、控制器、事务、审计和集成测试 |
+| 2026-09-18 | 纠偏邀请证据口径，并将历史部署顺序降级为复现记录；明确 `0003`／`0004` 阻断解除前不得迁移或发布                     | 成员接入契约、历史命令、迁移与测试结论          |