create-bubbles 0.1.26 → 0.1.27

package/template-vp-monorepo-react-nestjs/.spaces/04./347/225/214/351/235/242/344/270/216/344/270/273/351/242/230//344/270/207/347/211/251/346/242/246/345/271/273//346/265/213/350/257/225/350/257/201/346/215/256/visual-report.json

@@ -0,0 +1,104 @@
+{
+  "baseUrl": "http://127.0.0.1:9999",
+  "browser": "145.0.7632.6",
+  "mockData": true,
+  "checks": [
+    {
+      "name": "companies-desktop-empty",
+      "viewport": {
+        "width": 1440,
+        "height": 960
+      },
+      "passed": true
+    },
+    {
+      "name": "companies-desktop-data",
+      "viewport": {
+        "width": 1440,
+        "height": 960
+      },
+      "passed": true
+    },
+    {
+      "name": "workspaces-1440",
+      "viewport": {
+        "width": 1440,
+        "height": 960
+      },
+      "passed": true
+    },
+    {
+      "name": "workspaces-390",
+      "viewport": {
+        "width": 390,
+        "height": 960
+      },
+      "passed": true
+    },
+    {
+      "name": "workspaces-empty",
+      "viewport": {
+        "width": 390,
+        "height": 844
+      },
+      "passed": true
+    },
+    {
+      "name": "login-1440",
+      "viewport": {
+        "width": 1440,
+        "height": 960
+      },
+      "passed": true
+    },
+    {
+      "name": "register-1440",
+      "viewport": {
+        "width": 1440,
+        "height": 960
+      },
+      "passed": true
+    },
+    {
+      "name": "login-390",
+      "viewport": {
+        "width": 390,
+        "height": 960
+      },
+      "passed": true
+    },
+    {
+      "name": "register-390",
+      "viewport": {
+        "width": 390,
+        "height": 960
+      },
+      "passed": true
+    },
+    {
+      "name": "companies-mobile-390",
+      "viewport": {
+        "width": 390,
+        "height": 844
+      },
+      "passed": true
+    },
+    {
+      "name": "companies-mobile-360",
+      "viewport": {
+        "width": 360,
+        "height": 844
+      },
+      "passed": true
+    },
+    {
+      "name": "companies-mobile-320",
+      "viewport": {
+        "width": 320,
+        "height": 844
+      },
+      "passed": true
+    }
+  ],
+  "failures": []
+}

package/template-vp-monorepo-react-nestjs/.spaces/04./347/225/214/351/235/242/344/270/216/344/270/273/351/242/230//344/270/207/347/211/251/346/242/246/345/271/273//351/252/214/350/257/201/350/257/264/346/230/216.md

@@ -0,0 +1,25 @@
+# 万物梦幻主题视觉验证
+
+使用当前本地 React 页面，通过独立 Playwright 浏览器上下文提供虚构数据。不会读取浏览器个人资料、真实凭据或现有登录态，不会写入后端数据。
+
+```powershell
+node ".spaces/04.界面与主题/万物梦幻/工具/visual-check.mjs" --base-url http://127.0.0.1:9999
+```
+
+- `--check-launch`：只验证本机 Chromium 可启动，不打开页面、不截图。
+- `--only companies-mobile-390`：只运行指定场景；`--only companies-mobile` 复验全部手机企业场景。定向运行会更新同一服务地址的已有报告，保留其他场景验证结果。
+- `PLAYWRIGHT_MODULE`：覆盖 Playwright 模块位置。
+- `PLAYWRIGHT_EXECUTABLE_PATH`：覆盖已有 Chromium 可执行文件位置。
+- 若受限沙箱阻止启动 Chromium（`spawn EPERM`），需使用获准的沙箱外执行权限运行同一脚本。
+
+`fixtures.mjs` 定义平台、企业、项目身份以及企业列表空/有数据状态。全部 `/api/` 请求由浏览器路由拦截：只允许已知 GET fixture，写入请求返回 405，未知请求返回 501 并导致验证失败。
+
+输出的 PNG 使用虚构名称“星屿科技”“月光计划”和 `example.invalid` 测试账号。`visual-report.json` 记录通过项和失败项。它们是本地 UI 验证证据，不能作为真实业务数据或服务端集成验证结果。
+
+## 验证记录（2026-09-10）
+
+- 本次前端修改文件的定向 `vp check` 通过；QA 脚本与 fixture 的定向检查通过。
+- 前端 6 个测试文件、43 个测试通过；最终前端构建通过。
+- 全仓 `vp check` 因已有的 164 个格式问题未通过，本次未扩大格式修改范围。
+- `vp install --frozen-lockfile` 因 pnpm 非 TTY 重建 modules 保护退出，验证沿用本地已安装依赖。
+- 视觉验证 12 个场景全部通过，0 失败。使用真实本地前端和独立浏览器的网络 mock，覆盖桌面 1440px、手机 320/360/390px，检查品牌、当前工作空间、表格、导航、空态及登录/注册字段。最终 PNG 已通过解码验证，主要交付截图已进行目视复核。

package/template-vp-monorepo-react-nestjs/.spaces/04./347/225/214/351/235/242/344/270/216/344/270/273/351/242/230//345/233/275/351/231/205/345/214/226//344/272/244/344/273/230/350/256/260/345/275/225.md

@@ -0,0 +1,12 @@
+# 前端国际化交付记录
+
+## 交付内容
+
+- 在 `apps/web/src/i18n/config.ts` 集中声明应用 locale 到组件库和日期库的标识映射。
+- 新增 `apps/web/src/i18n/ui-locale.ts`，统一返回 antd Locale、Pro Components `IntlType`、Day.js 和 `<html lang>` 配置。
+- `apps/web/src/App.tsx` 根据同一 locale 状态驱动 `ConfigProvider`、`ProConfigProvider` 和 Day.js。
+- 更新 Web README 与 `.spaces` 正式需求、设计、测试和索引文档。
+
+## 状态
+
+已实现并完成构建、测试和 i18n 词条检查。当前语言范围仍为 `zh_CN` 与 `en_US`。

package/template-vp-monorepo-react-nestjs/.spaces/04./347/225/214/351/235/242/344/270/216/344/270/273/351/242/230//345/233/275/351/231/205/345/214/226//346/265/213/350/257/225/346/212/245/345/221/212.md

@@ -0,0 +1,19 @@
+# 前端国际化测试报告
+
+## 验证范围
+
+- 应用 locale 到 antd `ConfigProvider` 的映射。
+- 应用 locale 到 Pro Components `IntlType` 的映射。
+- 应用 locale 到 Day.js 和 `<html lang>` 的同步。
+- 词条完整性、TypeScript 编译和 React Web 测试回归。
+
+## 验证结果（2026-09-19）
+
+| 命令 | 结果 |
+| --- | --- |
+| `pnpm --filter web build` | 通过，TypeScript 与 Vite 构建成功 |
+| `pnpm --filter web test --run` | 通过，17 个测试文件、112 个测试 |
+| `pnpm i18n:check` | 通过，1254 个词条无新增、废弃或未使用 |
+| `git diff --check` | 通过 |
+
+本次未改动后端接口、权限契约或 UI 截图；浏览器视觉回归仍沿用主题验证说明中的既有流程。

package/template-vp-monorepo-react-nestjs/.spaces/04./347/225/214/351/235/242/344/270/216/344/270/273/351/242/230//345/233/275/351/231/205/345/214/226//350/256/276/350/256/241/346/226/271/346/241/210.md

@@ -0,0 +1,18 @@
+# 前端国际化设计方案
+
+## 统一状态
+
+`@bubblesjs/i18n-core` store 是唯一语言状态源。`apps/web/src/i18n/config.ts` 集中维护应用 locale 及其适配标识，`ui-locale.ts` 将应用 locale 映射为：
+
+- antd 的 `Locale` 对象；
+- Pro Components 的 `IntlType`（`zhCNIntl` / `enUSIntl`）；
+- Day.js locale 标识（`zh-cn` / `en`）；
+- `<html lang>` 标识。
+
+## 渲染与副作用
+
+`App.tsx` 在渲染时将 antd locale 和 Pro `intl` 传入 Provider；在 locale 变化后的 effect 中设置 Day.js 全局 locale 和 `<html lang>`。这样静态组件配置会随 React 重新渲染，日期库的全局副作用也只在语言变化时执行。
+
+## 扩展约束
+
+新增语言时必须同时补充词条加载器、`APP_LOCALE_ADAPTERS`、antd locale 包、Pro Components intl 以及 Day.js locale 导入，并执行 `pnpm i18n:check` 与前端构建。

package/template-vp-monorepo-react-nestjs/.spaces/04./347/225/214/351/235/242/344/270/216/344/270/273/351/242/230//345/233/275/351/231/205/345/214/226//351/234/200/346/261/202/346/226/207/346/241/243.md

@@ -0,0 +1,24 @@
+# 前端国际化需求
+
+## 目标
+
+应用语言切换必须由同一份 locale 状态驱动，确保业务词条、Ant Design、Ant Design Pro Components、Day.js 以及文档语言属性同步变化。
+
+## 范围
+
+- 当前支持 `zh_CN`（简体中文）和 `en_US`（English）。
+- 切换结果继续由现有 i18n store 持久化。
+- Ant Design 组件文案、Pro Components 内置文案和 Day.js 日期/相对时间格式必须与当前语言一致。
+- 浏览器 `<html lang>` 必须同步更新。
+
+## 验收标准
+
+1. 初始语言、持久化语言和运行时切换均使用同一 locale 状态。
+2. 切换到英文后，antd、Pro Components、Day.js 和 `<html lang>` 均使用英文配置；切回中文后恢复中文配置。
+3. 新增语言时只需扩展集中式映射，并能明确补充对应组件库和 Day.js locale。
+
+## 变更记录
+
+| 日期 | 变更摘要 | 影响范围 | 原因 |
+| --- | --- | --- | --- |
+| 2026-09-19 | 明确应用 locale 必须同时驱动 antd、Pro Components、Day.js 与 `<html lang>` | React Web 全局入口与 locale 配置 | 补充国际化联动要求 |

package/template-vp-monorepo-react-nestjs/.spaces/05./350/277/220/350/241/214/347/273/264/346/212/244//345/271/263/345/217/260/346/223/215/344/275/234/346/211/213/345/206/214.md

@@ -0,0 +1,397 @@
+# 企业项目平台操作手册
+
+更新日期：2026-09-18。
+
+状态：本文已同步当前成员接入口径与迁移阻断。平台开通企业及设置企业管理员统一使用 `GlobalAccountSelect`，关系标识统一使用平台唯一 `userId`；企业邀请只确认产品入口。当前完整迁移链包含企业层级残留 `0003` 和未确认邀请 `0004`，两项阻断解除并重新验证前不得执行迁移或发布。
+
+本手册用于本地启动系统、初始化平台管理员，以及操作企业、项目、成员、角色和菜单。开发阶段优先使用源码脚本。除特别说明外，终端命令均在项目根目录执行。
+
+## 1 当前环境与入口
+
+### 1.1 当前初始化状态
+
+- 当前本地数据库已完成 `0000`、`0001`、`0002` 三次迁移。
+- 当前平台管理员账号为 `admin`，已完成首次初始化。
+- 登录密码沿用 `admin` 原有密码。系统没有另外生成管理员密码，手册不保存密码。
+- 当前环境直接启动并登录即可；首次管理员初始化步骤供新环境使用。
+- 本地开发操作按当前约定不额外创建数据库备份。
+
+上述状态是本次配置完成时的记录；更换数据库或后续修改角色后，以实际环境为准。
+
+### 1.2 访问地址
+
+| 用途         | 当前地址                         | 说明                             |
+| ------------ | -------------------------------- | -------------------------------- |
+| 前端登录     | http://localhost:9999/login      | 使用已注册账号登录               |
+| 注册账号     | http://localhost:9999/register   | 普通用户自行注册                 |
+| 工作空间     | http://localhost:9999/workspaces | 选择平台、企业或项目             |
+| 平台管理     | http://localhost:9999/platform   | 需要平台范围的相应权限           |
+| 后端接口文档 | http://localhost:13000/api-docs  | 查看接口定义                     |
+| MinIO 控制台 | http://localhost:9001            | 管理对象存储，不是业务平台登录页 |
+
+地址来自当前配置，服务启动后才可访问。端口被占用或配置调整时，以终端实际输出为准。后端端口由 `apps/server/.env` 中的 `PORT` 配置；前端端口由 `apps/web/.env` 中的 `VITE_PORT` 配置。
+
+前端开发请求使用 `/api` 前缀，由开发代理转发到 `http://localhost:13000` 并移除该前缀。后端接口文档使用上表中的地址。
+
+## 2 启动与停止
+
+### 2.1 准备依赖
+
+先启动 Docker Desktop，并确认本机可以使用 `vp`。首次获取项目或依赖清单变化后安装依赖：
+
+```powershell
+vp install
+```
+
+启动数据库、Redis 和对象存储：
+
+```powershell
+docker compose up -d postgres redis minio minio-init
+docker compose ps -a
+```
+
+| 容器            | 用途                              | 正常状态                          |
+| --------------- | --------------------------------- | --------------------------------- |
+| `vp-postgres`   | 保存账号、企业、项目和权限等数据  | 运行中                            |
+| `vp-redis`      | 保存会话等运行数据，支持任务队列  | 运行中                            |
+| `vp-minio`      | 保存上传文件                      | 运行中                            |
+| `vp-minio-init` | 创建 `uploads` 存储桶并设置为私有 | 执行成功后退出，显示 `Exited (0)` |
+
+`vp-minio-init` 是一次性初始化任务，完成后退出属于正常行为。上传和下载由持续运行的 `vp-minio` 提供服务。
+
+### 2.2 构建共享包与执行迁移
+
+首次启动前构建共享包：
+
+```powershell
+vp run --filter shared build
+```
+
+当前不得对新环境或现有环境执行完整迁移命令：`0003_cute_killmonger.sql` 仍包含已取消的企业父子层级，`0004_company-member-invitations.sql` 对应未确认的邀请协议。不得手工跳号、修改迁移历史或使用 `db:push` 绕过。完成代码与迁移清理、同步正式契约并在隔离环境重验后，再由本手册给出可执行命令。
+
+恢复迁移流程后，迁移工具使用的 `DATABASE_URL` 必须与运行中后端使用的 `DB_HOST`、`DB_PORT`、`DB_DATABASE`、`DB_USERNAME`、`DB_PASSWORD` 指向同一数据库。普通日常重启不需要重复初始化账号。
+
+服务端默认环境为 `development`，环境文件按以下优先级加载，进程已有的环境变量优先：
+
+1. `.env.<NODE_ENV>.local`
+2. `.env.local`
+3. `.env.<NODE_ENV>`
+4. `.env`
+
+后端文件位于 `apps/server`。本项目保留历史迁移，按顺序增量建表；不要将删除数据卷或重建数据库作为解决迁移错误的常规操作。
+
+### 2.3 启动前后端
+
+终端一启动后端，保持终端运行：
+
+```powershell
+vp run --filter server dev
+```
+
+终端二启动 React 前端：
+
+```powershell
+vp run --filter web dev
+```
+
+如果同时修改共享包，可另开终端运行共享包监听：
+
+```powershell
+vp run --filter shared dev
+```
+
+前端脚本使用 `dev` 模式，读取 `apps/web/.env.dev` 等对应配置；服务端的默认模式名称则是 `development`。
+
+验证启动结果：打开登录页，以及后端接口文档。登录后进入工作空间；平台管理员即使尚未开通企业，也有平台入口。
+
+### 2.4 停止服务
+
+在运行前后端的终端中按 `Ctrl+C`。需要停止本项目容器时执行：
+
+```powershell
+docker compose stop
+```
+
+停止容器会保留数据卷，下一次启动可继续使用现有数据。
+
+## 3 首位平台管理员初始化
+
+### 3.1 新环境的操作顺序
+
+1. 确认数据库使用已审阅的合规基线后启动前后端；当前完整迁移链不得执行，未来阻断解除并完成隔离验证后才恢复迁移步骤。
+2. 打开注册页，创建一个有效账号。
+3. 在终端执行初始化命令，指定该账号。
+4. 使用该账号重新登录，在工作空间进入平台管理。
+
+例如，在项目根目录将已注册的 `admin` 设为首位平台管理员：
+
+```powershell
+vp run --no-cache --filter server access:init -- --account admin
+```
+
+如果终端已位于 `apps/server`，可使用：
+
+```powershell
+vp run --no-cache access:init -- --account admin
+```
+
+在其他新环境执行时，将 `admin` 替换为实际已注册账号。源码脚本通过 `ts-node` 运行 `src/access-init.ts`，无需先构建后端；共享包仍需已有构建产物。
+
+成功输出类似：
+
+```json
+{ "initialized": true, "account": "admin", "alreadyInitialized": false }
+```
+
+当前本地的 `admin` 已初始化成功，不需要再次执行。
+
+### 3.2 初始化的规则
+
+- 账号必须已经注册且处于有效状态，账号格式为 4～32 位字母、数字或下划线。
+- 名称叫 `admin` 本身不会产生管理权限，身份取决于数据库里的角色分配。
+- 首次初始化给目标账号分配平台范围的内置管理员角色，并写初始化记录和审计日志。
+- 密码沿用注册账号的密码。
+- 对同一账号重复初始化会同步系统功能目录，但不会恢复后来被撤销的角色。
+- 已初始化后，再用该命令指定其他账号会被拒绝。后续管理员通过平台页面分配。
+
+### 3.3 源码脚本与 dist 的区别
+
+`src/access-init.ts` 是源码；`dist/src/access-init.js` 是后端构建后的 JavaScript。
+
+开发环境使用上面的 `access:init` 源码脚本。使用构建产物运行时，先构建共享包和后端，再在后端目录运行：
+
+```powershell
+node dist/src/access-init.js --account admin
+```
+
+修改源码后，旧 `dist` 不会自动反映新代码，需重新构建。两种启动方式执行的是同一套初始化业务。
+
+## 4 身份与工作空间
+
+| 身份                 | 主要操作范围                                                     | 创建项目             |
+| -------------------- | ---------------------------------------------------------------- | -------------------- |
+| 平台管理员           | 开通和启停企业、管理全局账号、设置企业管理员、配置菜单和维护权限 | 仅有平台身份时不可以 |
+| 企业管理员           | 管理本企业资料、成员、角色及全部项目                             | 可以                 |
+| 项目管理员           | 管理当前项目的资料、成员和角色                                   | 不可以               |
+| 普通成员或自定义角色 | 在所属企业或项目中使用已授权功能                                 | 不可以               |
+
+同一账号可以在不同范围拥有不同身份。角色选择框中的“内置管理员”取决于当前范围：在平台分配就是平台管理员，在企业分配就是企业管理员，在项目分配就是项目管理员。
+
+平台管理员身份本身不提供企业内部业务访问权。需要进入企业或项目时，该账号还需具备相应的企业或项目身份。企业管理员可以管理本企业全部项目，无需逐个建立项目成员关系。
+
+工作空间页面标题为“选择工作空间”，点击卡片中的“进入空间”进入目标范围。已进入管理页面时，可使用顶部“切换空间”返回选择。
+
+普通公开注册账号尚未加入企业时，页面显示等待加入企业的空态。企业“直接注册成员”用于创建新账号并同步加入企业；既有平台账号不能由企业管理员按完整账号直接拉入，后续如何通过邀请加入须等待邀请协议确认。成员关系建立后，点击“刷新工作空间”重新获取入口。公开注册不会自动创建企业或授予管理员身份。
+
+## 5 平台管理员日常操作
+
+### 5.1 开通企业
+
+1. 确保首位企业管理员已完成账号注册，且账号有效。
+2. 使用平台管理员账号登录，进入平台空间的企业管理页面。
+3. 点击“开通企业”。
+4. 填写企业名称、企业编码和可选说明，再通过 `GlobalAccountSelect` 搜索并选择首位企业管理员。
+5. 确认表单保存的是所选账号的平台唯一 `userId`，提交请求字段为 `administratorUserId`。
+6. 提交后检查企业列表，首位管理员重新进入工作空间即可看到企业入口。
+
+企业名称为 2～100 字；编码为 2～32 位字母、数字、下划线或短横线，保存时转为小写。企业编码全平台唯一。姓名不是唯一标识，必须以选择器返回的 `userId` 建立关系；系统会将首位管理员加入企业，并授予企业内置管理员角色。
+
+### 5.2 增加其他平台管理员
+
+1. 让目标用户先注册账号。
+2. 进入平台空间的账号管理页面，列表标题为“全局账号”。
+3. 搜索目标账号，点击“分配角色”。
+4. 选择平台范围的“内置管理员”，下拉选项会标注“内置”。
+5. 保留该用户需要继续拥有的其他角色，点击“保存角色”。
+6. 目标用户重新进入工作空间，确认可以访问平台管理。
+
+角色弹窗保存的是最终选中的角色集合，取消选择会撤销对应角色。系统会保护最后一个有效平台管理员。
+
+### 5.3 设置或更换企业管理员
+
+1. 在平台企业列表找到目标企业，点击“设置管理员”。
+2. 通过 `GlobalAccountSelect` 搜索并选择新管理员；选择值为平台唯一 `userId`。
+3. 补充管理员时，“被替换的管理员”留空。
+4. 更换管理员时，选择需要撤销管理员身份的旧任。
+5. 点击“保存管理员”，确认请求以 `administratorUserId` 提交新管理员，并核对结果。
+
+新管理员必须是有效的已注册账号。系统按需要建立或启用其企业成员关系。更换会撤销选定旧任的企业管理员角色，保留其成员关系和其他角色。
+
+停用中的企业也可以设置管理员，设置操作不会自动启用企业。平台停用了企业最后一位管理员的全局账号后，由平台在这里补任或更换；旧账号恢复启用也不会恢复已被撤销的管理员角色。
+
+### 5.4 停用与恢复
+
+| 操作             | 影响                                         | 恢复后的结果                             |
+| ---------------- | -------------------------------------------- | ---------------------------------------- |
+| 平台停用全局账号 | 该账号所有工作空间均不可访问                 | 重新启用后需要重新登录                   |
+| 平台停用企业     | 企业及下属项目的访问被阻断                   | 仅恢复企业本身；原本单独停用的项目仍停用 |
+| 停用企业成员     | 阻断该企业成员身份提供的访问，保留关系和角色 | 不自动启用原本停用的项目成员关系         |
+| 移除企业成员     | 清理企业角色以及下属项目关系和角色           | 重新加入不恢复旧授权                     |
+
+企业和项目内部的成员、角色操作受最后有效管理员约束。平台可以停用企业最后一位管理员的全局账号，但不能使平台自身失去最后一位有效管理员。
+
+## 6 企业与项目操作
+
+### 6.1 添加企业成员
+
+企业管理员进入企业空间的成员管理页面，通过“直接注册”填写新成员姓名、完整账号和初始密码。提交后系统在同一事务中创建全局账号、当前企业成员关系和默认 member 角色；账号已存在或任一步失败时，不得留下部分数据。需要其他能力时再分配企业角色。
+
+“邀请成员”是已经确认的另一条产品入口，但邀请对象范围、是否绑定账号、载体与发送渠道、有效期、状态、接受或拒绝、撤销、重发、安全和审计规则仍待确认。当前仓库虽已有固定 7 天链接、邀请管理和接受页实现，这些内容属于待处置的实现偏差，不是现行运行契约；在协议确认并同步需求、契约、迁移和验收前，不应把该页面用于正式操作或发布说明。
+
+2026-09-17 之前“输入已注册完整账号并直接添加企业成员”的页面和接口属于历史实现，不是现行操作流程，也不能作为当前验收依据。企业侧不得通过成员入口枚举全平台账号或把既有平台账号直接拉入企业。
+
+### 6.2 创建项目
+
+1. 使用有效的企业内置管理员身份进入企业空间。
+2. 在项目管理页面点击“创建项目”。
+3. 填写项目名称、编码和说明，再从所属企业的有效成员候选中选择首位项目管理员。
+4. 表单保存候选的稳定 `userId`，创建请求以 `administratorUserId` 提交；服务端仍须重新校验账号与企业成员状态。
+5. 创建成功后进入项目空间，添加项目成员并分配角色。
+
+项目编码在所属企业内唯一。创建项目的能力不能通过自定义角色下放；仅有项目管理员身份也不能创建项目。
+
+### 6.3 添加项目成员与更换项目管理员
+
+项目管理员从项目成员页面添加成员时，只能查询所属企业当前有效成员。候选列表排除已经属于当前项目的成员，选择值和提交值均为稳定 `userId`；服务端写入时再次校验账号、企业成员资格、状态和重复关系。项目成员的角色只作用于当前项目。
+
+企业管理员可在企业项目列表中设置或更换项目管理员。新管理员从所属企业有效成员候选中按 `userId` 选择，请求字段为 `administratorUserId`；补任与更换的区别和企业管理员设置一致。已经是项目成员的企业成员也可以被授予项目管理员角色，因此“排除已加入当前项目者”只适用于新增普通项目成员，不适用于管理员晋升。企业管理员本身对本企业项目的管理能力不依赖项目成员列表中的显式记录。
+
+## 7 角色与授权
+
+### 7.1 创建自定义角色
+
+1. 进入目标平台、企业或项目空间的角色管理页面。
+2. 点击“创建角色”，填写名称和说明。
+3. 点击“配置权限”，选择所需页面和操作，点击“保存权限”。
+4. 回到账号或成员页面，通过“分配角色”授予目标用户。
+5. 让目标用户重新进入工作空间，检查页面和按钮。
+
+只能分配当前管理范围内允许授予的权限。选择操作权限时会包含所属页面权限，取消页面访问也会取消该页面的操作权限。平台、企业和项目角色相互独立；页面能够显示，还需要该功能已启用、前端已支持并满足其他访问条件。
+
+内置角色可通过“查看权限”了解授权范围。自定义角色只有在未分配给用户时才能删除。
+
+### 7.2 内置角色规则
+
+- 内置管理员与内置普通成员由系统维护，不能人工编辑、停用、删除或修改权限集合。
+- 给用户分配、撤销某个内置角色，与编辑这个角色本身是两件事；角色分配仍受管理约束。
+- 新功能发布后，自动补齐对应范围内置管理员的权限。
+- 内置普通成员、自定义角色和已有用户角色分配不会因此自动扩权。
+- 授权被撤销后，后续请求重新检查权限；前端隐藏按钮不能代替后端鉴权。
+
+## 8 菜单与功能维护
+
+### 8.1 调整菜单
+
+进入平台“菜单管理”页面，选择“平台菜单”“企业菜单”或“项目菜单”页签，再按需要调整名称、图标、排序、隐藏状态、启停状态和合法父级，点击“保存菜单”。
+
+新增时点击“新增节点”，选择目录、页面或按钮类型。页面与操作只能绑定代码目录中尚未绑定的已发布功能，已有节点不能更换所绑定的功能。
+
+企业和项目菜单按范围统一配置，当前版本不为每个企业提供独立菜单树。页面编号 `routeKey` 和操作权限来自代码功能目录；添加菜单记录不会自动开发出一个新页面。
+
+### 8.2 隐藏与停用
+
+| 设置 | 导航菜单           | 直接访问页面和接口                             |
+| ---- | ------------------ | ---------------------------------------------- |
+| 隐藏 | 不显示对应导航入口 | 具备权限且满足其他条件时仍可访问               |
+| 停用 | 对应功能不可用     | 页面、操作和接口均受阻断，内置管理员也不能绕过 |
+
+停用父级会影响下级功能。平台关键恢复入口及其祖先受到保护，避免无法重新恢复管理功能。
+
+旧前端遇到不认识的 `routeKey` 时，会过滤对应菜单、按钮及因此变空的目录，其他已支持功能继续使用。用户实际加载新版前端并重新取得权限上下文后，才会显示符合条件的新页面。
+
+### 8.3 废弃权限清理
+
+平台菜单管理提供“清理废弃权限”按钮。点击后打开“废弃权限清理预览”，核对权限、菜单节点、角色授权引用和阻断原因。条件满足时，勾选“已核对权限、菜单和角色授权引用的清理范围”，再点击“确认清理废弃权限”。
+
+执行前需要开发或部署人员完成以下准备：
+
+1. 在代码功能目录中明确标记目标权限已废弃，并完成对应功能下线。
+2. 确认所有在用服务版本已解除相关依赖。
+3. 提供受控部署证明 JSON 文件，通过 `ACCESS_DEPLOYMENT_PROOF_FILE` 配置给服务端。
+
+预览为空表示当前没有可清理项。菜单被隐藏、功能被停用或旧前端不认识页面，都不等于权限已经废弃。
+
+存在受保护节点、有效子节点或在用服务依赖等阻断项时，整次清理会被拒绝。成功清理会同步处理引用、版本和审计；再次初始化也不会重建已经清理的权限。
+
+## 9 审计与异常处理
+
+平台、企业和项目分别通过“平台操作日志”“企业操作日志”“项目操作日志”查看允许访问的管理记录，可按操作类型和时间范围筛选。平台查看平台事件，企业查看本企业及下属项目事件，项目查看当前项目事件。
+
+成功的管理变更和成功审计记录在同一数据库事务中提交。平台管理员补任、全局账号停用和废弃权限清理记录为平台操作事件。
+
+| 现象                                          | 排查与处理                                                                                                                   |
+| --------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
+| `vp-minio-init` 显示 `Exited (0)`             | 初始化已成功完成，确认 `vp-minio` 正在运行即可                                                                               |
+| MinIO 初始化日志出现 `connection refused`     | 启动初期 MinIO 可能尚未就绪；检查后续是否重试成功，不能只看一条旧错误                                                        |
+| 启动查询 `permission_cleanup_tombstones` 失败 | 检查底层数据库错误、迁移记录和目标库配置；当前不得因缺表直接执行完整迁移，先处理 `0003`／`0004` 阻断并按审阅后的迁移流程修复 |
+| 迁移提示旧类型或旧表已存在                    | 可能是旧库结构与迁移记录不一致；核对结构和历史记录后处理，不要直接重复建表或手改记录跳过迁移                                 |
+| `admin` 登录后没有平台入口                    | 检查首次初始化、账号状态和平台角色分配；账号名称本身不代表身份                                                               |
+| 普通公开注册账号登录后没有企业                | 公开注册不会自动加入企业；由企业管理员直接注册新账号，既有账号的邀请加入方式待产品协议确认                                   |
+| 没有“创建项目”按钮                            | 确认当前处于企业空间，并且具有有效的企业内置管理员身份                                                                       |
+| 403                                           | 检查当前空间、角色、成员状态及功能启停情况，再重新获取权限                                                                   |
+| 404                                           | 地址可能不存在、前端未注册页面，或资源不属于当前允许访问范围；从工作空间重新进入                                             |
+| 409 或版本冲突提示                            | 刷新当前数据，核对他人修改后重新提交                                                                                         |
+| 账号恢复启用后仍不能访问                      | 退出并重新登录，再检查企业、项目、成员和角色状态                                                                             |
+| 授权后仍看不到菜单                            | 检查页面权限、菜单隐藏或停用、父节点状态及前端版本                                                                           |
+
+查看本机容器日志可使用：
+
+```powershell
+docker logs --tail 100 vp-minio-init
+docker logs --tail 100 vp-minio
+docker logs --tail 100 vp-postgres
+docker logs --tail 100 vp-redis
+```
+
+## 10 开发知识说明
+
+### 10.1 初始化脚本为什么创建 Nest 上下文
+
+`NestFactory.createApplicationContext()` 启动 Nest 的依赖注入容器，让命令行脚本复用配置、数据库和 `AccessSeedService`。它不监听 HTTP 端口。
+
+脚本从 `--account` 参数读取账号，通过服务执行初始化，输出结果后关闭上下文并退出。退出码 `0` 表示成功，`1` 表示失败。
+
+### 10.2 lockAccess 是什么
+
+当前实现：
+
+```ts
+export const lockAccess = (tx: AccessTx) => tx.execute(sql`select pg_advisory_xact_lock(7421, 1)`)
+```
+
+这是向 PostgreSQL 申请一把事务级的独占咨询锁，用来协调权限相关管理操作的先后顺序。
+
+- `tx` 是当前数据库事务，调用时应写 `await lockAccess(tx)`。
+- `pg_advisory_xact_lock` 会等待，直到当前事务取得指定的锁。
+- `(7421, 1)` 是代码约定的锁标识，不是企业 ID、项目 ID 或数据库表编号。
+- 同一个数据库里，使用相同锁标识的不同事务会相互等待；不同服务进程也能通过这把数据库锁协调。
+- 事务提交或回滚时自动释放锁，无需手动解锁。
+- 咨询锁依赖相关代码共同遵守；没有申请这把锁的 SQL 不会因此自动被阻止。
+
+例如，管理员正在授权，另一个请求同时撤销该管理员的权限：先取得锁的事务先处理，后取得锁的事务必须在锁内重新读取并校验最新权限，不能继续沿用锁外的旧鉴权结果。
+
+当前固定锁标识会让使用它的权限管理写操作排队执行，包括不同企业或项目的相关写操作；它不是为每个企业单独设置的锁。以后如果写入量增大，需要按授权依赖设计更细的锁范围，并保持一致的加锁顺序。
+
+### 10.3 事务锁与版本号的区别
+
+事务锁用于协调并发操作的执行顺序，配合锁内重新鉴权处理撤权与在途请求。版本号用于发现用户提交的是旧数据，避免旧表单覆盖他人的更新。两者解决的问题不同，需要同时保留。
+
+## 11 相关文档与代码
+
+- [企业项目权限与菜单需求文档](../01.企业级项目级/权限与菜单/需求文档.md)
+- [权限与菜单技术契约](../01.企业级项目级/权限与菜单/技术契约.md)
+- [权限与菜单测试报告](../01.企业级项目级/权限与菜单/测试报告.md)
+- [管理员初始化脚本](../../apps/server/src/access-init.ts)
+- [角色与权限初始化服务](../../apps/server/src/modules/access/seed/access-seed.service.ts)
+- [事务锁与访问数据工具](../../apps/server/src/modules/access/access.store.ts)
+- [Docker 服务配置](../../docker-compose.yml)
+
+验收报告中的隔离测试端口和临时账号属于测试记录；本地使用入口以本手册和当前环境配置为准。
+
+## 12 变更记录
+
+| 日期       | 变更摘要                                                                                           | 原因                                                    | 影响范围                           |
+| ---------- | -------------------------------------------------------------------------------------------------- | ------------------------------------------------------- | ---------------------------------- |
+| 2026-09-17 | 企业开通和企业管理员设置改用 `GlobalAccountSelect`，统一以 `administratorUserId` 提交              | 账号全局唯一但姓名不唯一，人员关系必须使用稳定 `userId` | 平台开通企业、管理员补任与更换     |
+| 2026-09-18 | 撤回未经确认的固定邀请操作说明，并明确 `0003`／`0004` 阻断当前完整迁移链；删除可直接执行的迁移命令 | 对话只确认邀请入口，且当前企业层级实现违反独立企业边界  | 企业成员操作、启动、迁移与发布边界 |
+| 2026-09-17 | 项目管理员和项目成员从所属企业有效成员中按 `userId` 选择，新增普通项目成员排除已加入者             | 统一稳定标识并由服务端复核成员资格                      | 项目创建、管理员设置、项目成员新增 |

package/template-vp-monorepo-react-nestjs/.spaces/05./350/277/220/350/241/214/347/273/264/346/212/244//346/225/260/346/215/256/345/272/223/350/277/201/347/247/273//345/244/207/344/273/275/export-dump.ps1

@@ -0,0 +1,34 @@
+# 导出 vp-postgres 容器中的 postgres 库到本目录的 backup.dump
+# 用法: pwsh ./export-dump.ps1
+$ErrorActionPreference = 'Stop'
+
+$ContainerName = 'vp-postgres'
+$DbUser = 'postgres'
+$DbName = 'postgres'
+$DumpName = 'backup.dump'
+$ContainerPath = "/tmp/$DumpName"
+$HostPath = Join-Path $PSScriptRoot $DumpName
+
+# 1. 确认容器正在运行
+$status = docker inspect -f '{{.State.Running}}' $ContainerName 2>$null
+if ($status -ne 'true') {
+  throw "容器 $ContainerName 未运行，请先执行: docker compose up -d postgres"
+}
+
+# 2. 容器内用 pg_dump 生成 custom 格式备份（不用 stdout 重定向，避免跨环境产生空文件/编码损坏）
+docker exec $ContainerName pg_dump -U $DbUser -d $DbName -Fc -f $ContainerPath
+if ($LASTEXITCODE -ne 0) {
+  throw 'pg_dump 执行失败'
+}
+
+# 3. 从容器拷出到脚本所在目录（覆盖旧备份）
+docker cp "${ContainerName}:$ContainerPath" "$HostPath"
+if ($LASTEXITCODE -ne 0) {
+  throw 'docker cp 导出失败'
+}
+
+# 4. 清理容器内临时文件
+docker exec $ContainerName rm -f $ContainerPath | Out-Null
+
+$sizeKb = [math]::Round((Get-Item $HostPath).Length / 1KB, 1)
+Write-Host "导出完成: $HostPath ($sizeKb KB)"