create-bubbles 0.1.26 → 0.1.27

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//351/234/200/346/261/202/346/226/207/346/241/243.md

@@ -0,0 +1,275 @@
+# 企业、项目与菜单权限管理实施计划
+
+## 一、目标与业务边界
+
+在现有 React、NestJS、Drizzle、PostgreSQL 和 Redis 基础上，完成**企业管理 → 项目管理 → 成员与角色 → 菜单授权 → 页面、按钮与接口鉴权 → 操作审计**的完整闭环。
+
+采用已确认的业务规则：
+
+| 身份       | 默认管理范围                                                                               | 权限边界                                                                           |
+| ---------- | ------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------- |
+| 平台管理员 | 企业开通与启停、企业管理员设置与更换、全局账号、平台角色、全局菜单、废弃权限清理、平台审计 | 在平台侧设置企业管理员无需加入企业；进入企业内部操作业务仍需企业成员身份和相应授权 |
+| 企业管理员 | 企业资料、成员、角色、项目创建、本企业全部项目及审计                                       | 自动拥有本企业所有项目的管理权限；项目创建仅限本企业有效的内置企业管理员           |
+| 项目管理员 | 当前项目资料、成员、角色及审计                                                             | 不获得企业管理权限或其他项目权限                                                   |
+| 普通成员   | 当前企业、项目角色授予的功能                                                               | 多个企业、项目之间分别授权                                                         |
+
+- 一个账号可以加入多个企业、多个项目；项目成员必须先是所属企业成员。
+- 平台创建企业时指定首位企业管理员，也负责企业管理员被禁用后的重新设置；企业停用期间仍可在平台侧设置或更换企业管理员。
+- 只有本企业有效的内置企业管理员可以创建项目，创建能力不下放给自定义角色。创建时指定一名有效企业成员为首位项目管理员，项目、首位管理员的项目成员关系、角色授权及成功审计在同一事务中提交。
+- 保留公开注册，补齐注册页面。企业管理员新增企业成员只能使用“直接注册新账号并加入企业”或“邀请”两种产品入口，不再通过完整账号搜索并直接拉入既有平台账号。
+- 用户目前只确认了上述两个入口。邀请有效期、token、是否绑定账号、发送方式、状态、接受／拒绝、撤销／重发、幂等、数据表、DTO、端点和审计均待产品确认；确认前不得写成现行需求、契约或验收标准。
+- 当前仓库已经存在 `apps/server/drizzle/0004_company-member-invitations.sql` 及相应后端、前端实现，这些内容属于未获产品确认的实现偏差。本轮只纠正文档，不修改代码；现有实现不能倒推需求，也不能作为发布依据。
+- 项目新增成员只能从所属企业当前有效成员中选择，候选排除已经属于该项目的成员；前端提交稳定的 `userId`，后端在写入事务中再次校验账号、企业成员资格、状态和重复关系，不能信任选择器结果。
+- 企业、项目首期提供创建、编辑、启用和停用，不提供物理删除；项目不支持跨企业迁移。停用仅阻断相应访问，保留子级自身状态和授权，恢复按当前保存的状态与授权生效。
+- 保留现有 Cookie token＋Bearer 请求方式。Cookie 工具负责 Cookie，Local/Session 工具负责浏览器存储。
+- 本期覆盖管理权限和基础审计；上传的企业、项目归属改造单列后续阶段。
+
+## 二、管理功能与菜单设计
+
+### 管理页面
+
+| 工作空间 | 首期页面与操作                                                                                                               |
+| -------- | ---------------------------------------------------------------------------------------------------------------------------- |
+| 平台     | 企业列表与开通、企业启停、企业管理员设置与更换、账号查询与启停、平台角色及人员授权、菜单管理、废弃权限清理按钮、平台操作日志 |
+| 企业     | 企业工作台、企业资料、成员直接注册、邀请入口（具体协议待确认）、成员管理、角色管理、项目列表与创建、项目启停、企业操作日志   |
+| 项目     | 项目工作台、从所属企业成员中添加项目成员、成员管理、角色管理、项目操作日志                                                   |
+
+列表提供搜索、筛选和分页；成员支持按所属作用域允许的入口新增、停用、启用、移除与分配角色。企业不能通过成员管理入口枚举全平台账号；项目成员候选只来自所属企业，并排除已经存在的项目成员关系。
+
+平台开通企业、设置或更换企业管理员时使用全局账号选择器，按稳定 `userId` 选择有权查看的全局账号。该平台级能力不下放为企业新增普通成员的账号搜索入口。
+
+企业、项目角色支持自定义。内置管理员角色负责相应作用域的完整管理，内置普通成员角色默认只提供工作台和必要的工作空间入口，其他可下放操作通过自定义角色授权。
+
+### 内置角色规则
+
+- 内置角色定义由系统维护，管理页面和普通角色管理接口均不允许人工编辑、停用、删除内置角色或修改其权限集合。向成员分配、撤销内置角色仍按管理员委派和最后有效管理员保护规则执行。
+- 新增功能自动授予对应作用域的内置管理员，并继续受账号、成员、企业、项目及功能启停状态约束；内置管理员不能绕过功能停用。
+- 内置普通成员继续保留基础入口，自定义角色不因新增功能自动扩权。普通成员需要额外功能时，通过分配自定义角色授权。
+- 系统可以通过版本化的功能目录和初始化更新维护内置角色权限；系统升级与废弃权限清理不属于人工编辑内置角色。
+
+### 停用、恢复与管理员设置
+
+停用与移除的处理不同，状态变化统一遵循：
+
+| 对象     | 停用效果                                                                 | 恢复规则                                                               |
+| -------- | ------------------------------------------------------------------------ | ---------------------------------------------------------------------- |
+| 全局账号 | 阻断登录及全部作用域访问，撤销已有会话；保留成员关系与角色               | 启用后重新登录，按当前成员、角色及各作用域状态访问，不恢复已撤销的会话 |
+| 企业     | 阻断企业内部及下属项目访问；保留项目、成员自身状态和授权                 | 恢复企业自身状态，不自动启用原本单独停用的项目或成员                   |
+| 项目     | 阻断项目内部访问；保留成员自身状态和角色                                 | 恢复项目自身状态，仍须满足企业及成员状态要求                           |
+| 企业成员 | 阻断该成员在企业及下属项目的访问；保留下属项目成员关系、角色及其自身状态 | 按当前保存的企业、项目成员状态和授权恢复，不还原停用期间已被撤销的角色 |
+| 项目成员 | 阻断该项目成员身份提供的访问与授权；保留角色                             | 按当前企业、项目及企业成员状态恢复，不还原已撤销的角色                 |
+
+- 企业管理员的项目管理能力来自企业身份，不依赖独立的项目成员记录；停用其某个项目成员关系，不会撤销其企业管理员身份提供的管理能力。
+- 移除企业成员时，按后文事务规则清理企业角色、下属项目成员关系及项目角色；重新添加成员不会自动恢复已经清理的授权。
+- 企业、项目的启停管理分别通过平台、所属企业管理入口执行。目标对象停用不妨碍具有相应权限的管理员在有效的上级作用域执行恢复；企业停用时，先由平台恢复企业，再通过企业入口管理项目。平台在企业停用期间设置或更换企业管理员，按下述例外规则执行。
+- 平台管理员可以为启用或停用的企业设置、更换企业管理员，无需加入目标企业。新管理员必须是有效账号；未加入企业时同步建立企业成员关系，已有成员关系被停用时同步启用该关系。
+- “更换管理员”在同一事务内授予新任企业管理员身份、撤销指定被替换者的企业管理员角色并写入审计，保留被替换者的成员关系及其他角色。单纯停用账号不撤销角色；已被更换的旧账号重新启用后，不自动恢复原管理员身份。
+- 企业、项目恢复启用前，按恢复后的状态检查是否存在有效管理员；缺失时先由平台设置企业管理员，或由所属企业管理员补任项目管理员，再执行恢复。停用期间的补任不自动启用企业或项目。
+
+### 菜单管理
+
+平台统一维护适用于平台、企业、项目的三套菜单树，企业和项目不保存独立菜单副本。
+
+菜单节点分为：
+
+- **目录**：组织导航层级，不直接产生操作权限。
+- **页面**：绑定前端已注册的 `routeKey` 和页面访问权限。
+- **按钮／操作**：挂在页面下，绑定已实现的操作权限，例如添加成员、修改角色。
+
+支持新增、编辑、调整父级、排序、隐藏、启停及受约束的删除。名称、图标和排序可配置；组件、路径模板和权限标识来自代码中的功能目录。
+
+菜单图标统一来自 React Web 的 `apps/web/src/assets/svg/`，菜单编辑器以“图标选择器”展示该目录及其子目录中的全部 SVG，并在当前选择、菜单管理列表和实际导航中回显。目录、页面和按钮／操作节点均必须有可回显图标；按钮／操作不进入导航，只在管理界面回显。现有菜单按页面或操作语义分配默认图标，已有自定义图标不得被种子覆盖；新增或调整菜单页面、操作时应优先复用语义匹配的现有 SVG，没有合适图标时补充符合项目 SVG 规范的新图标。
+
+新生成的单色菜单图标必须保留 `viewBox`，使用 `currentColor` 继承外部颜色，并以 `1em` 接受外部字号控制；不得把 SVG、HTML 或远程 URL 本身写入菜单数据。数据库只保存稳定的相对图标 key。空值、旧版本暂不认识或文件已不存在的 key 使用本地缺省菜单图标，不影响其他导航和权限；多色既有 SVG 可以保留自身颜色。
+
+菜单编辑器只能选择已注册的页面和操作。新增业务页面仍需开发并发布对应代码，数据库不保存可执行组件路径。
+
+明确以下行为：
+
+| 设置   | 导航表现         | 页面、按钮与接口             |
+| ------ | ---------------- | ---------------------------- |
+| 隐藏   | 不显示导航入口   | 已授权用户仍可访问           |
+| 停用   | 不显示入口       | 对应功能及下级功能均不可访问 |
+| 未授权 | 不显示入口或操作 | 页面拒绝访问，接口拒绝执行   |
+
+- 目录按可见子节点自动显示；按钮不进入导航。
+- 校验循环父子关系、跨层级移动、重复页面绑定和未知权限标识。
+- 有子节点或仍被角色授权引用的节点不能直接删除。
+- 平台菜单、平台角色等恢复管理所需的入口受到保护，不能通过自身或祖先节点的操作使其失效。
+- 角色授权树支持全选、半选；授予按钮权限时必须包含所属页面访问权限，取消页面权限时同步取消下级操作授权。
+- 创建项目属于内置企业管理员专属能力，自定义角色授权树不提供该操作；修改前端或直接调用接口也不能绕过身份限制。
+
+### 功能发布与废弃权限清理
+
+- 新功能随代码发布并注册到功能目录，内置管理员按对应作用域自动获得权限；既有普通成员和自定义角色不自动获得新增权限。
+- 旧前端收到不认识的 `routeKey` 时，过滤该页面菜单及所属按钮，过滤后没有可见子节点的目录一并隐藏，其他已识别功能正常使用。过滤仅影响当前前端，不修改服务端菜单与角色授权。
+- 新版前端发布后，用户刷新并加载包含该页面的新版本，重新获取当前权限上下文后显示符合授权与菜单状态要求的入口；旧版本前端不会仅因重新获取菜单就获得未发布的页面代码。
+- 废弃权限由系统功能目录明确标记。当前服务版本找不到某个标识、功能暂时停用或代码尚未完整发布，都不能作为删除权限的依据。
+- 首期在平台管理侧提供废弃权限清理按钮及维护接口，仅平台管理员可用。执行前展示待清理权限、关联菜单及角色授权的影响范围和数量；真正执行时重新检查候选项、引用和部署条件，不直接沿用过期预览结果。
+- 清理前必须下线目标功能，并确认所有在用服务版本均不再依赖待清理权限；多实例发布未完成或无法确认依赖已解除时拒绝清理。旧前端隐藏未知页面不构成清理依据。
+- 清理接口仅处理满足条件的明确废弃项，不能通过传入任意权限 ID 删除有效权限。在同一事务内清理对应角色授权引用、菜单绑定及符合删除条件的废弃菜单节点，最后清理权限记录并写入审计；不得破坏仍有效的子节点或受保护管理入口，存在此类依赖时拒绝清理。
+- 清理可重复执行，已经清理的内容不重复产生变更；清理后更新受影响的授权与菜单版本。后续初始化不得重新生成已清理的废弃权限及引用。
+
+## 三、数据、接口与权限实现
+
+### 数据模型
+
+新增以下数据组：
+
+| 数据组     | 主要实体与约束                                                                                                                   |
+| ---------- | -------------------------------------------------------------------------------------------------------------------------------- |
+| 企业与项目 | `companies`、`projects`；项目必须属于企业，项目编码在企业内唯一                                                                  |
+| 成员关系   | `company_members`、`project_members`；成员关系唯一，项目成员必须满足企业成员关系                                                 |
+| 企业邀请   | 只确认企业成员新增存在“邀请”入口；是否需要独立数据表及其字段、约束和生命周期均待确认，仓库现有 `0004` 与相关表结构不构成需求依据 |
+| 角色授权   | `roles`、`user_roles`、`role_permissions`；角色绑定明确的平台、企业或项目作用域，并区分系统维护的内置角色与自定义角色            |
+| 功能与菜单 | `permissions`、`menus`；权限标识稳定且唯一，菜单和权限适用层级一致，支持与系统功能目录一致的废弃标记                             |
+| 操作审计   | `audit_logs`；记录操作者、作用域、操作、对象、变更摘要、时间和 requestId                                                         |
+
+角色使用 `scopeType`、`companyId`、`projectId` 表示归属，通过数据库约束限制合法组合。不同企业、项目可以创建同名角色。
+
+企业邀请尚未形成数据模型。有效期、token、账号绑定、发送、状态流转、接受／拒绝、撤销／重发、幂等和审计等设计全部留待产品确认，不能使用当前代码或迁移内容补写本节。
+
+授权规则统一为：
+
+- 同一作用域内，多角色权限取并集；首期不引入角色继承和显式拒绝规则。
+- 企业管理员跨本企业项目的管理能力由统一授权逻辑计算，不批量复制项目角色。
+- 普通角色不能授予操作者自身无权授予的权限，也不能获得内置管理员专属能力。平台管理员身份由平台管理员委派；企业管理员身份由本企业管理员委派，或由平台管理员通过平台侧企业管理员设置入口委派；项目管理员身份由所属企业管理员或当前项目管理员委派。
+- 有效管理员须账号有效、相关成员关系启用且具有对应内置管理员身份；平台身份不要求企业成员关系。项目的有效管理员包括有效项目管理员及所属企业的有效企业管理员，企业管理员无需显式加入项目即可计入，也不因此生成项目成员或角色记录。
+- 移除企业成员时，事务内清理其企业角色、下属项目成员关系和项目角色。
+- 企业、项目内部不允许通过移除成员、停用成员或撤销角色，使仍启用的管理范围失去最后一名有效管理员；并发操作使用事务和锁保证这一点，恢复启用也须检查恢复后的有效管理员。
+- 平台管理员禁用全局账号是上述企业及项目管理员保护的例外，即使该账号是企业最后一名有效管理员，也允许禁用，由平台负责重新设置企业管理员。账号禁用对其全部企业、项目身份生效，相关管理变更写入审计。
+- 平台初始化后始终至少保留一名有效平台管理员。停用账号、撤销平台管理员角色等任何操作均不得破坏该约束，平台执行禁用账号时也不能绕过；并发操作采用相同的事务与锁保护。
+- 自定义角色授权和菜单结构更新使用版本校验，过期提交返回冲突，避免覆盖其他管理员的修改。系统更新内置权限或清理废弃权限时，同样更新受影响版本。
+
+### 共享契约与接口
+
+接口请求、返回类型通过 `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`                        | 获取当前作用域的菜单和权限上下文                                               |
+
+普通企业成员只能看到自己加入的项目；企业管理员可以看到本企业全部项目。
+
+企业邀请尚未进入接口契约。此前写入的列表／创建／撤销／重发／接受 5 个固定端点及其 DTO、状态、错误码和事务语义全部撤回，后续必须在产品确认邀请协议后重新设计并同步[技术契约](./技术契约.md)。
+
+沿用当前成功响应和统一异常模型，不新增一套响应包装。新增业务错误加入错误目录校验。
+
+### 后端鉴权
+
+请求依次完成：
+
+**登录态校验 → 用户状态校验 → 作用域及成员校验 → 功能权限校验 → 资源归属校验。**
+
+- URL 中的企业、项目 ID 只是查询目标，后端必须验证归属，不能作为授权依据。
+- 管理接口声明作用域和所需权限；未声明访问策略的新接口默认拒绝。
+- 平台侧企业管理员设置与更换、废弃权限清理使用明确的平台作用域策略，校验有效平台管理员身份；设置目标企业管理员不要求操作者加入该企业，也不授予其企业内部业务权限。
+- 创建项目接口除校验企业及成员状态、功能状态外，必须验证操作者具有本企业内置企业管理员身份；仅持有普通角色或伪造权限参数不能通过。
+- 项目添加成员接口必须按请求中的 `userId` 重新校验目标属于当前项目所属企业且企业成员有效，并检查未加入当前项目；跨企业、停用或重复成员不能因前端候选缓存而写入。
+- 企业邀请的鉴权、事务、并发、幂等和审计边界均待确认，当前不作为管理事务的现行验收规则。
+- Repository 查询同时约束资源 ID 与企业、项目归属，更新和删除也遵循这一规则。
+- 未登录或账号失效返回 401；作用域内权限不足返回 403；跨企业、跨项目资源与不存在资源统一返回 404。
+- 首期不缓存后端授权结果，后续请求读取当前成员、角色和功能状态；撤权无需等待重新登录。
+- 账号禁用同时接入已有的会话撤销能力。
+- 当前数据库、Redis 测试接口移出默认应用入口，避免通过测试接口绕过管理权限。
+
+管理变更与成功审计记录在同一数据库事务中提交。平台查看平台事件；企业查看本企业及下属项目事件；项目查看当前项目事件。日志不记录密码、token 或完整敏感请求。
+
+平台侧禁用账号、设置或更换企业管理员、清理废弃权限均记录为平台操作事件，包含目标账号、企业或权限及实际变更摘要；这些维护操作不改变平台与企业内部业务审计的访问边界。
+
+### 并发撤权与事务边界
+
+- 角色授权、管理员委派、成员状态变更、废弃权限清理等敏感管理写操作，与账号禁用、成员停用或移除、角色撤销、企业或项目停用、菜单或功能停用等影响其授权的操作，必须遵守同一套数据库事务与锁规则。
+- 根据本次授权依赖选择稳定的锁对象，覆盖账号、成员、角色、作用域及功能状态的相关变化；采用固定的加锁顺序。不能只锁业务数据或可能被删除的授权关系，也不能只给撤权一方加锁。
+- 敏感管理写操作获取相关锁后，在事务内读取当前已提交的授权状态，重新完成账号、作用域、成员、身份、功能权限及资源归属校验，不能沿用事务外已通过的旧鉴权结果。业务变更与成功审计提交或回滚后才释放锁。
+- 管理写操作先获得相关锁时，允许其先完成，撤权操作等待后再提交；撤权操作先完成时，管理写操作取得锁后必须重新鉴权，权限已失效则拒绝写入。
+- 后续请求读取最新授权的规则保持不变。角色、菜单版本校验继续处理过期编辑提交，不能替代上述事务内鉴权与共同加锁约束。
+
+### 前端接入
+
+- 登录后进入工作空间入口，选择企业、项目或平台管理空间；没有企业的普通账号显示尚未加入企业，并可提示联系企业管理员了解成员接入方式。邀请的载体和加入流程待确认。
+- 企业、项目 ID 放在路由中，刷新后能够恢复当前工作空间。
+- 使用 React Router 的 loader 获取管理页面上下文，布局消费菜单，页面和按钮消费权限；不恢复已删除的 auth Provider／Guard 目录。
+- 前端保留静态页面注册表，将服务端菜单映射到已注册页面，并提供 403、404 和无权限空状态。
+- 按功能发布兼容规则过滤未知 `routeKey` 的页面、所属按钮及空目录；旧前端直接访问未注册页面时显示 404，不影响已注册功能。加载新版前端并重新获取权限上下文后，再展示已支持且符合授权与菜单状态要求的页面。
+- 页面 API 随页面存放，继续使用现有 alova 封装；弹窗遵循 `show/hide` 规范。
+- 企业成员页面提供“直接注册”和“邀请”两个入口；邀请入口后续展示的表单、列表、状态和操作均待确认。项目成员页面使用企业成员候选选择器，保存值为 `userId`，展示姓名、完整账号及必要的企业身份信息用于同名辨识。
+- 权限上下文不持久化、不使用请求缓存。业务缓存区分用户、企业和项目；切换工作空间取消旧请求并阻止迟到结果覆盖新页面。
+- 路由切换、窗口重新激活、授权修改及收到 403 后刷新权限。退出、401 时清理 Cookie 和用户相关缓存。
+- 菜单路由切换等待数据提交期间保留旧页面的视觉内容并禁止交互，由加载层覆盖；目标路由提交后再替换页面，保证页面过渡动画连续且不暴露旧页面操作。
+- Local/Session 只保存最近选择、筛选条件等界面状态，不能用于判定权限。
+
+## 四、实施阶段与数据兼容
+
+| 阶段            | 交付内容                                                                                     | 阶段完成标准                                                                 |
+| --------------- | -------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
+| 1. 契约与数据库 | 共享类型、权限目录与废弃标记、数据模型、迁移、内置角色和菜单种子                             | 空库与现有数据库均可迁移，内置角色升级、约束和重复初始化验证通过             |
+| 2. 后端权限闭环 | 企业、项目、成员、角色、菜单接口，平台企业管理员设置与更换、废弃权限维护接口，统一鉴权和审计 | 不依赖前端隐藏，也能阻止越权与跨作用域访问；补任、清理和并发撤权规则通过     |
+| 3. 前端管理闭环 | 注册、工作空间切换、三级管理页面、菜单和角色授权、管理员设置及废弃权限清理入口               | 可完成“注册→加入企业→加入项目→角色授权→访问功能”，旧前端未知页面兼容规则通过 |
+| 4. 联调与交付   | 浏览器验收、数据库集成测试、迁移说明、接口文档、权限及清理操作说明                           | 正常流程及停启恢复、管理员更换、版本兼容、清理、撤权、切换和并发等场景通过   |
+
+初始化与兼容规则：
+
+- 首位平台管理员通过初始化命令指定一个已注册、有效的账号，不提供固定默认密码，也不自动提升第一个注册用户。
+- 初始化命令可重复执行，但不能借重复执行给其他账号授予平台管理员身份或修改已有用户的角色分配。内置角色定义由系统按功能目录更新，新增功能自动授予对应作用域内置管理员；内置普通成员保持基础入口，自定义角色不自动扩权。
+- 种子更新保留用户角色分配、自定义角色授权，以及管理员已经调整的菜单名称、图标、排序、隐藏、启停和合法层级等配置；废弃权限引用仅通过规定的清理流程处理。重复初始化不恢复已清理的废弃权限与引用。
+- 现有用户保持原账号和登录方式，不自动分配企业或项目。
+- 现有上传数据继续按 `ownerId` 授权，本期不猜测归属、不迁移到默认企业，也不宣称上传已完成租户隔离。
+- 使用可审阅的 Drizzle migration；上线顺序为备份、迁移、服务端、前端，并提供迁移失败处理说明。新旧前端共存时执行未知页面过滤规则，废弃权限清理须等待所有在用服务版本解除依赖后，由平台维护入口执行。
+- 保留工作区已有修改，实施时只调整本计划涉及的代码。
+
+## 五、验收标准与后续范围
+
+必须覆盖以下场景：
+
+1. **完整业务流程**：平台开通企业并选择首位管理员；企业成员新增明确提供“直接注册”和“邀请”两个入口，当前只验收已确认的直接注册分支，邀请分支待协议确认后补充专项验收；随后创建项目、指定首位项目管理员，项目管理员从所属企业有效成员中按 `userId` 添加成员并分配角色。已确认事务失败时，成员关系、角色授权及成功审计不留下部分结果。
+2. **权限隔离**：同一用户在不同企业、项目拥有不同权限；平台管理员可以通过平台入口设置企业管理员，但未经成员授权不能进入企业内部操作业务；企业管理员没有显式项目成员记录时仍可管理本企业项目。
+3. **菜单一致性**：对当前前端已注册的功能，导航、直达页面、按钮和接口权限一致；隐藏与停用表现符合定义，内置管理员也不能绕过功能停用。图标选择器覆盖 SVG 目录中的全部图标，选择结果可保存并在表单、管理列表和导航回显；空值或未知图标安全降级。未知页面按版本兼容规则处理。
+4. **即时撤权**：角色撤销、成员停用或移除、企业或项目停用后，后续请求立即失去相应访问权。
+5. **切换与缓存**：快速切换企业、项目以及退出后换号，不出现旧数据、旧权限或旧请求覆盖。
+6. **管理约束**：重复成员、越权授予角色、通过普通菜单管理删除引用中的节点、循环菜单均被拒绝；企业与项目内部并发移除或停用成员、撤销角色不能导致启用范围失去最后有效管理员。平台禁用企业最后管理员账号按例外规则允许，但任何操作均不得导致平台自身失去最后有效管理员。邀请相关约束待确认，不纳入本项验收。
+7. **数据与审计**：跨作用域查询返回一致结果，成功变更有对应审计；日志、审计和列表响应中不存在密码或完整敏感请求。邀请是否产生审计以及审计字段待确认，不纳入本项验收。
+8. **回归与迁移**：保留 Cookie／Storage 和请求层回归测试，验证旧用户登录、上传兼容及迁移重复执行。
+9. **停用与恢复**：企业下项目 A 启用、项目 B 单独停用，企业停用再恢复后 A 可按授权访问、B 仍停用；企业成员停用保留下属关系和角色，恢复时不自动启用原本停用的项目成员关系，也不恢复停用期间已撤销的角色。全局账号恢复后必须重新登录。
+10. **管理员补任与更换**：平台禁用企业唯一管理员账号后，可为启用或停用的企业设置有效新管理员；新管理员未加入企业或成员关系被停用时，正确建立或启用关系。更换事务同时撤销指定旧管理员的对应角色，旧账号重新启用不恢复该身份；补任失败时全部回滚。企业、项目恢复启用时按恢复后的状态校验有效管理员。
+11. **创建项目身份限制**：有效企业管理员可创建项目；普通成员、自定义角色及仅具备项目管理员身份的用户，即使直接构造请求也不能创建。授权树不提供向自定义角色授予创建项目能力的入口。
+12. **内置角色与新增功能**：管理页面和角色接口均拒绝人工编辑、停用、删除内置角色及修改其权限；发布新增功能后，对应作用域内置管理员自动获得权限，内置普通成员与自定义角色不扩权，已有用户角色分配及菜单配置不被初始化覆盖。
+13. **前端版本兼容**：旧前端收到未知页面编号时，隐藏该页面及按钮，隐藏因此变空的目录，其他功能正常；直接访问未知页面显示 404。用户刷新并实际加载新版前端后，已注册且符合授权与菜单状态要求的新页面正常显示，服务端菜单和授权不因旧版过滤被修改。
+14. **废弃权限清理**：平台可预览明确废弃项及引用范围，普通用户不能调用维护接口；未标记废弃项、有效子节点、受保护入口、仍被在用服务版本依赖的权限均不能被清理。执行时重新校验预览后的变化；事务失败不留下部分删除，重复执行安全，变更有审计且更新相关版本，随后初始化不重新生成废弃项。
+15. **在途写操作与撤权**：使用真实数据库并发验证两种顺序：管理写操作先持有相关锁则先完成、随后撤权生效；撤权先提交则管理写操作在锁内重新鉴权并拒绝。失败写操作不提交业务变更或成功审计，不能仅依赖前端隐藏、锁外鉴权或单方加锁通过验收。
+
+验证采用权限规则测试、真实 PostgreSQL／Redis 接口集成测试及 Playwright 关键流程测试；完成 `vp check`、相关测试和 shared、Web、Server 构建。跳过的集成测试不能计为通过。
+
+首期默认采用应用层作用域隔离和 RBAC；组织树、岗位和组织成员选择器由同主题下的[组织架构需求](../组织架构/需求文档.md)独立定义，本文件不重复建立第二套规则。字段级权限、审批流、SSO、外部协作者和企业独立菜单仍不在本期。上传归属改造放在下一阶段，沿用本期确定的企业、项目与权限契约。
+
+## 六、后续扩展项
+
+- 企业邀请协议整体待确认，包括有效期、token、是否绑定账号、发送、状态、接受／拒绝、撤销／重发、幂等、数据表、DTO、端点和审计；确认前不进入实现或发布验收。
+- 当前规则确认仅表示产品与技术契约已固定；实现、联调和验收状态以联调记录与测试报告中的增量证据为准。
+
+## 七、变更记录
+
+| 日期       | 变更摘要                                                                                                                                                                                                                                         | 原因                                                         | 影响范围                                           |
+| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------ | -------------------------------------------------- |
+| 2026-09-19 | 菜单图标改为从 React Web SVG 目录自动发现；增加可搜索、可预览、可回显的图标选择器，为现行菜单补充 `currentColor` 图标，并规定路由新增时的图标复用／生成规则                                                                                       | 消除 Ant Design 图标硬编码和前后端重复白名单，使菜单图标成为可维护的本地资源 | 菜单管理、导航、共享契约、种子、迁移、前端规则与测试 |
+| 2026-09-19 | 菜单管理表格保留菜单树层级，名称列保持单行显示并按列宽省略；只有真实存在子级的节点显示展开控件，叶子节点不显示展开加号                                                                                       | 避免名称换行破坏行高，同时保留父子菜单的树形管理关系 | 菜单管理列表 UI、前端回归测试 |
+| 2026-09-19 | 为页面、目录和按钮／操作节点统一分配语义图标；新增操作图标 SVG，种子和增量迁移只补空值或旧值，不覆盖已有自定义图标                                                               | 消除操作节点空图标，保证菜单管理中每个节点都能识别并回显 | 共享目录、菜单种子、迁移、SVG 资源、图标选择器与测试 |
+| 2026-09-18 | 修正菜单路由切换等待态：旧页面保留为不可交互的视觉快照，目标路由提交后再替换，恢复页面过渡动画                                                                                                                                                | 等待态提前卸载 `RouteTransition` 会使浏览器无法采集旧页面快照                                                   | 工作空间布局、导航等待态、前端测试与交付验证       |
+| 2026-09-18 | 纠正企业邀请口径：只确认“直接注册或邀请”两个入口；撤回 7 天、固定 5 端点及 token、账号绑定、发送、状态、接受／拒绝、撤销／重发、幂等、数据表、DTO 和审计等未确认细节。仓库现有 `0004` 与前后端实现标记为实现偏差，本轮不改代码，不能作为发布依据 | 先前把未经用户确认的实现方案误写成现行需求                   | 企业成员需求、接口与数据契约、验收、迁移和发布判断 |
+| 2026-09-17 | 企业新增成员改为“直接注册或邀请”；项目新增成员改为从所属企业有效成员中选择，排除已加入项目者并提交 `userId`                                                                                                                                      | 最新成员边界确认，避免企业枚举平台账号并强化项目成员资格校验 | 成员页面、候选选择器、成员接口、后端校验、测试     |
+| 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//347/273/204/347/273/207/346/236/266/346/236/204//345/206/263/347/255/226/350/256/260/345/275/225.md

@@ -0,0 +1,35 @@
+# 企业／项目组织架构决策记录
+
+> 状态：当前决策索引。本文只记录跨轮次讨论形成的结论与状态，详细规则以同目录的现行需求、设计方案和技术契约为准。
+>
+> 整理日期：2026-09-18。
+
+## 决策
+
+| 日期       | 结论                                                                                                                                                                           | 状态                           | 原因                                                                           | 影响范围                                         | 正式文档                                                                        |
+| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------ | ------------------------------------------------------------------------------ | ------------------------------------------------ | ------------------------------------------------------------------------------- |
+| 2026-09-18 | 企业成员新增保留“直接注册”和“邀请”两个产品入口；邀请对象、账号绑定、载体、有效期、状态、接受／拒绝、撤销／重发、渠道、DTO、端点、Token、安全、事务、审计和验收标准全部待确认。 | 入口当前有效；邀请协议待确认   | 产品只确认了入口选择，不能由先行实现反向固化完整邀请方案。                     | 成员入口、数据库、接口、UI、测试与验收           | [需求文档](./需求文档.md)、[设计方案](./设计方案.md)、[技术契约](./技术契约.md) |
+| 2026-09-17 | 平台下企业彼此独立，不建立企业之间的父子层级；集团、事业群、分公司等内部层次由单个企业的组织单元表达。                                                                         | 当前有效，替代初版企业层级方案 | 独立企业需要各自的成员、权限、数据和项目边界，内部管理层次不应改变租户边界。   | 企业模型、项目归属、数据库、接口、权限、UI、测试 | [需求文档](./需求文档.md)、[设计方案](./设计方案.md)、[技术契约](./技术契约.md) |
+| 2026-09-17 | 每个企业维护一棵企业组织树，每个项目维护一棵项目组织树，两棵树分别管理且不能跨树建立父子关系。                                                                                 | 当前有效                       | 企业组织表达治理与共享职能，项目组织表达具体执行结构。                         | 组织树、页面作用域、关系校验、模板               | [需求文档](./需求文档.md)、[设计方案](./设计方案.md)                            |
+| 2026-09-17 | 树节点统一称为“组织单元”，允许客户按自身业务把节点命名和使用为集团、分公司、部门、中心、科室或班组。                                                                           | 当前有效                       | “部门”不足以覆盖多层和多种组织结构。                                           | 产品文案、数据模型、组织页面                     | [需求文档](./需求文档.md)、[设计方案](./设计方案.md)                            |
+| 2026-09-17 | 企业成员和项目成员都可以加入同一作用域内的多个组织单元，不设置主归属、默认归属或唯一归属。                                                                                     | 当前有效                       | 多部门／多职责归属是真实业务需求，主归属没有明确业务价值。                     | 成员组织关系、选择器、接口、验收                 | [需求文档](./需求文档.md)、[技术契约](./技术契约.md)                            |
+| 2026-09-17 | 企业和项目都保留岗位；岗位是各自作用域内的平面列表，不是树，也不与组织单元建立持久关联；一人可多岗，一岗可多人。                                                               | 当前有效                       | 岗位表达职责名称，组织单元表达结构，两者独立可避免组织调整隐式改变职责或权限。 | 岗位库、任职关系、模板、成员筛选                 | [需求文档](./需求文档.md)、[设计方案](./设计方案.md)、[技术契约](./技术契约.md) |
+| 2026-09-17 | 不建设独立“项目小组”概念；稳定协作结构使用项目组织单元，临时协作由具体业务选择成员。                                                                                           | 当前有效                       | 独立小组会与项目组织单元重叠，当前没有额外的生命周期或权限价值。               | 领域模型、页面、接口、数据库                     | [需求文档](./需求文档.md)、[设计方案](./设计方案.md)                            |
+| 2026-09-17 | 组织单元排序只保存和填写一个非负整数 `sort`，不拆成多个输入框，也不使用小数。                                                                                                  | 当前有效，替代拆分排序方案     | 降低用户心智负担并保持数据库和接口简单稳定。                                   | 组织编辑、接口字段、数据库排序                   | [需求文档](./需求文档.md)、[技术契约](./技术契约.md)                            |
+| 2026-09-17 | 项目流程流转到所属企业的财务、董事等目标是合理的后续方向，但不纳入当前组织架构交付。                                                                                           | 后续专项                       | 组织资源可以被流程引用，但目标解析、任务参与者和任务级授权需要独立完整设计。   | 工作流、通知、任务授权、跨作用域选人             | [需求文档](./需求文档.md)、[设计方案](./设计方案.md)                            |
+
+## 被替代或禁止的旧口径
+
+- 初版企业父子层级、企业类型、企业树查询／移动和企业层级排序全部失效；不得作为当前实现或验收依据。
+- “主归属组织单元”“岗位挂组织”“项目小组”和拆分式排序均不属于当前模型。
+- 企业组织树和项目组织树可以在选择器中聚合浏览，但数据库中仍是两棵独立树。
+- 任何固定邀请有效期、账号绑定方式、Token、状态机、接受／拒绝、撤销／重发、发送渠道、DTO、端点、安全、事务或审计规则均未确认，不得作为当前产品结论。
+
+## 当前实现偏差
+
+- 当前 Schema、Shared、Server、Web、测试及 `0003_cute_killmonger.sql` 仍残留已取消的企业父子层级实现；迁移或发布前必须完成清理并重新验证，历史通过结果不能替代复验。
+- 当前邀请代码、前端页面、自动化测试及 `0004_company-member-invitations.sql` 先于产品确认产生，只能记录为实现偏差；它们不能进入组织专项现行契约、联调完成结论或验收证据。
+
+## 变更规则
+
+后续结论发生变化时，先修改对应的现行需求、设计和技术契约，再更新本记录的状态与替代关系；历史追溯依赖 Git，不创建并行正文副本。