create-bubbles 0.1.26 → 0.1.27

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/restore-dump.ps1

@@ -0,0 +1,73 @@
+# 从本目录的 backup.dump 恢复数据到 vp-postgres 容器中的 postgres 库
+# 用法: pwsh ./restore-dump.ps1         （有确认提示）
+#       pwsh ./restore-dump.ps1 -Force  （跳过确认，用于自动化）
+param(
+  [switch]$Force
+)
+
+$ErrorActionPreference = 'Stop'
+
+$ContainerName = 'vp-postgres'
+$DbUser = 'postgres'
+$DbName = 'postgres'
+$DumpName = 'backup.dump'
+$ContainerPath = "/tmp/$DumpName"
+$HostPath = Join-Path $PSScriptRoot $DumpName
+
+# 1. 前置检查
+if (-not (Test-Path $HostPath)) {
+  throw "备份文件不存在: $HostPath"
+}
+
+$status = docker inspect -f '{{.State.Running}}' $ContainerName 2>$null
+if ($status -ne 'true') {
+  throw "容器 $ContainerName 未运行，请先执行: docker compose up -d postgres"
+}
+
+# 2. 恢复会删除并重建整个 postgres 库，要求显式确认
+if (-not $Force) {
+  $answer = Read-Host "将清空 $ContainerName/$DbName 的 public、drizzle schema（含备份之外的对象），并用 $DumpName 恢复，输入 YES 确认"
+  if ($answer -ne 'YES') {
+    Write-Host '已取消'
+    exit 1
+  }
+}
+
+# 3. 拷进容器（不用 stdin 重定向，避免跨环境文件损坏）
+docker cp "$HostPath" "${ContainerName}:$ContainerPath"
+if ($LASTEXITCODE -ne 0) {
+  throw 'docker cp 导入失败'
+}
+
+try {
+  # 4. 删除旧库之前先验证备份格式，避免无效文件造成数据丢失
+  docker exec $ContainerName pg_restore --list $ContainerPath | Out-Null
+  if ($LASTEXITCODE -ne 0) {
+    throw '备份文件无效，未删除目标数据库'
+  }
+
+  # 5. 从维护库 template1 连接，断开占用 postgres 的会话后完整重建数据库
+  docker exec $ContainerName dropdb -U $DbUser --maintenance-db=template1 --force --if-exists $DbName
+  if ($LASTEXITCODE -ne 0) {
+    throw '删除旧数据库失败，未执行恢复'
+  }
+
+  docker exec $ContainerName createdb -U $DbUser --maintenance-db=template1 $DbName
+  if ($LASTEXITCODE -ne 0) {
+    throw '创建空数据库失败，请修复后重新执行恢复'
+  }
+
+  # 6. --single-transaction 保证导入失败时不会留下部分备份对象；旧库已被删除
+  #    --no-owner 使恢复对象归属当前连接用户
+  docker exec $ContainerName pg_restore -U $DbUser -d $DbName `
+    --no-owner --single-transaction --exit-on-error $ContainerPath
+  if ($LASTEXITCODE -ne 0) {
+    throw 'pg_restore 执行失败，目标数据库为空，请修复后重新执行恢复'
+  }
+}
+finally {
+  # 7. 无论成功失败都清理容器内临时文件
+  docker exec $ContainerName rm -f $ContainerPath | Out-Null
+}
+
+Write-Host "恢复完成: $DumpName -> $ContainerName/$DbName"

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//346/223/215/344/275/234/346/214/207/345/215/227.md

@@ -0,0 +1,227 @@
+# 数据库迁移指南（Drizzle + PostgreSQL）
+
+> 状态：当前有效
+>
+> 适用目录：`packages/create-bubbles/template-vp-monorepo-react-nestjs`
+>
+> 适用技术栈：NestJS 11、Drizzle ORM、drizzle-kit、PostgreSQL 18、pnpm monorepo。
+>
+> 本文面向以前端开发为主、刚开始写 NestJS 的开发者。请按顺序操作，修改表结构后不要忘记生成并提交迁移文件。
+
+> **当前迁移阻断（2026-09-18）：** 仓库迁移链中的 `0003_cute_killmonger.sql` 仍包含已取消的企业父子层级，`0004_company-member-invitations.sql` 对应未获产品确认的邀请协议。清理两项偏差、同步正式契约并完成隔离环境复验前，不得对空库、开发库、共享库或生产库执行完整 `db:migrate`，也不得手工跳号、修改迁移历史或使用 `db:push` 绕过。本文中的迁移命令仅描述阻断解除后的标准流程，不是当前可执行指令。
+
+## 一、迁移体系一览
+
+本平台不使用 TypeORM，数据库表结构由 **Drizzle ORM** 的 schema 文件定义，再由 **drizzle-kit** 编译成有序的 SQL 迁移文件。
+
+| 项                         | 位置                                                                                                                                 | 说明                                                                                                     |
+| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------- |
+| 表结构定义（唯一事实来源） | `apps/server/src/database/schema.ts`、`apps/server/src/database/access.schema.ts`、`apps/server/src/database/organization.schema.ts` | 所有表、字段、枚举、索引都在这里声明                                                                     |
+| 迁移工具配置               | `apps/server/drizzle.config.ts`                                                                                                      | 指定 schema 路径、迁移输出目录、数据库方言（postgresql）和连接串                                         |
+| 已生成的迁移 SQL           | `apps/server/drizzle/`                                                                                                               | 形如 `0000_xxx.sql`、`0001_xxx.sql` 的版本文件                                                           |
+| 迁移快照与链路             | `apps/server/drizzle/meta/`                                                                                                          | `_journal.json` 和各版本 snapshot，记录迁移先后顺序，**必须随迁移文件一起提交**                          |
+| 应用侧连接配置             | `apps/server/src/config/database.config.ts`                                                                                          | NestJS 启动时读取 `DB_*` 环境变量创建连接池                                                              |
+| 环境变量                   | `apps/server/.env.development`（及 `.env.production`）                                                                               | `DATABASE_URL` 供 drizzle-kit 使用，`DB_*` 供运行时使用                                                  |
+| PostgreSQL 服务            | 根目录 `docker-compose.yml`                                                                                                          | `postgres:18-alpine`，容器名 `vp-postgres`，端口 5432，账号/密码/库名均为 `postgres` / `ml` / `postgres` |
+
+环境变量加载顺序见 `apps/server/src/utils/env-arr.ts`：`.env.${NODE_ENV}.local` → `.env.local` → `.env.${NODE_ENV}` → `.env`，本地覆盖文件不要提交。
+
+## 二、相关 npm 脚本
+
+脚本定义在 `apps/server/package.json`，均需在 `apps/server` 目录下执行：
+
+| 命令                                | 作用                                          | 使用场景                                 |
+| ----------------------------------- | --------------------------------------------- | ---------------------------------------- |
+| `pnpm db:generate`                  | 对比 schema 与最新快照，生成新的迁移 SQL 文件 | 修改 schema 之后                         |
+| `pnpm db:migrate`                   | 把 `drizzle/` 中尚未执行的迁移应用到数据库    | 仅在迁移链已审阅、无阻断并完成隔离验证后 |
+| `pnpm db:push`                      | 跳过迁移文件，直接把 schema 硬同步到数据库    | **仅限本地快速调试**，不留版本记录       |
+| `pnpm db:studio`                    | 启动 Drizzle Studio 网页端查看/编辑数据       | 本地排查数据                             |
+| `pnpm access:init --account <账号>` | 写入访问控制（角色、权限等）种子数据          | 迁移完成后的初始化                       |
+
+## 三、标准迁移流程
+
+### 1. 启动 PostgreSQL（在项目根目录）
+
+```powershell
+docker compose up -d postgres
+```
+
+如同时需要 Redis、MinIO，执行 `docker compose up -d` 启动全部服务。可用 `docker compose ps` 确认 `vp-postgres` 处于 running 状态。
+
+### 2. 应用已有迁移（仅限当前阻断解除后）
+
+以下命令在当前仓库状态下不得执行；完成 `0003`／`0004` 处置并更新本指南后，它才恢复为首次拉取代码或切换分支后的标准步骤。
+
+```powershell
+cd apps/server
+pnpm db:migrate
+```
+
+该命令会读取 `apps/server/.env.development` 中的 `DATABASE_URL`（当前为 `postgresql://postgres:ml@localhost:5432/postgres`），自动跳过已执行的迁移，只执行新增部分。
+
+### 3. 修改 schema
+
+在 `src/database/schema.ts`、`src/database/access.schema.ts` 或 `src/database/organization.schema.ts` 中新增表、字段、索引或枚举，并按现有领域边界选择对应文件。
+
+### 4. 生成迁移文件
+
+```powershell
+pnpm db:generate
+```
+
+执行后会在 `apps/server/drizzle/` 下生成新文件，例如 `0003_xxx.sql`，同时更新 `drizzle/meta/` 快照。
+
+**生成后必须打开 SQL 文件人工检查一遍**，重点确认：
+
+- 删列、改类型等操作是否会丢数据；
+- 新增非空列是否提供了默认值；
+- 索引、约束名称是否符合预期。
+
+### 5. 应用迁移（仅限迁移链无阻断时）
+
+执行前必须重新核对迁移清单；当前 `0003`／`0004` 阻断仍在，不能执行下面的标准命令。
+
+```powershell
+pnpm db:migrate
+```
+
+### 6. 提交到 Git
+
+迁移 SQL 与 `drizzle/meta/` 目录要**一起提交**。迁移链通过审阅和隔离验证后，其他同学或部署环境才能执行 `pnpm db:migrate` 得到一致表结构；当前阻断状态下不能据此操作。
+
+### 7.（可选）初始化权限种子数据
+
+```powershell
+pnpm access:init --account <已注册的完整账号>
+```
+
+该命令由 `src/access-init.ts` 驱动，为指定账号写入企业访问控制所需的角色、权限等基础数据。
+
+一句话总结工作流：
+
+```text
+改 schema.ts → pnpm db:generate → 检查 SQL → 连同 meta 一起提交 → 隔离验证且确认无阻断 → 各环境 pnpm db:migrate
+```
+
+## 四、generate 与 push 的区别
+
+- **`db:generate` + `db:migrate`**：迁移链无阻断时的正式流程。迁移有历史、可审查、可在各环境按顺序重放；当前 `0003`／`0004` 未处置，尚不能进入执行阶段。
+- **`db:push`**：直接比对 schema 后硬改数据库，速度快但不生成迁移文件，遇到删列等操作可能直接丢数据。仅允许在本地草稿/演示阶段使用，**不要对共享数据库或生产库使用**。
+
+## 五、注意事项
+
+1. **不要改名或删除已有迁移文件**。drizzle-kit 在数据库中维护迁移记录表，靠文件名和 `meta/_journal.json` 判定执行状态；改动历史文件会导致迁移链断裂，后续 `migrate` 报错。
+2. **迁移文件和 `meta/` 快照必须一起提交**，只提交 SQL 不提交快照会让其他人生成的下一个迁移与当前状态对不上。
+3. **一个迁移只做一件事**，避免在一个 SQL 文件里混合大量无关变更，方便审查和定位问题。
+4. **数据库连不上时先查基础设施**：Docker 是否启动（`docker compose ps`）、5432 端口是否被占用、`.env` 中账号密码是否与 `docker-compose.yml` 一致。
+5. 生产环境的连接串通过 `.env.production` 或部署平台的环境变量注入，不要把真实密码写进仓库。
+
+## 六、更换数据库 / 数据备份与搬迁
+
+迁移 SQL 只负责**表结构**，不负责搬运业务数据。
+
+### 1. 先看懂连接串
+
+`DATABASE_URL` 的格式固定如下，`@` 用于分隔"账号信息"和"服务器地址"：
+
+```text
+postgresql://用户名:密码@主机地址:端口/库名
+```
+
+本项目开发环境的实际值（见 `apps/server/.env.development`）：
+
+```text
+postgresql://postgres:ml@localhost:5432/postgres
+└── 协议          └用户  └密码 └主机     └端口 └库名
+```
+
+主机地址按部署位置填写：
+
+| 数据库位置                       | 主机地址填什么             | 示例                                                    |
+| -------------------------------- | -------------------------- | ------------------------------------------------------- |
+| 本机（含本机 Docker 映射的端口） | `localhost` 或 `127.0.0.1` | `postgresql://postgres:ml@localhost:5432/postgres`      |
+| 局域网内另一台服务器             | 那台机器的内网 IP          | `postgresql://postgres:ml@192.168.1.50:5432/postgres`   |
+| 云数据库 / 有域名                | 服务商提供的域名           | `postgresql://postgres:ml@db.example.com:5432/postgres` |
+
+### 2. 仅更换连接地址（目标库是空库）
+
+适用于"换一台数据库服务器，但不需要搬旧数据"的场景：
+
+1. 修改目标环境的 `DATABASE_URL` 与 `DB_HOST`、`DB_PORT`、`DB_DATABASE`、`DB_USERNAME`、`DB_PASSWORD`（本地调试可放到不提交的 `.env.development.local`）；
+2. 确保目标数据库**已被创建**（容器版默认只有 `postgres` 库；换库名需先建库）；
+3. 仅在迁移链通过审阅、隔离验证且没有阻断时，才在目标环境执行 `pnpm db:migrate` 建好全部表结构；当前仓库状态不满足该条件；
+4. 需要时执行 `pnpm access:init --account <账号>` 初始化种子数据。
+
+### 3. 备份与整体搬迁（表结构 + 业务数据）
+
+使用 PostgreSQL 原生的 `pg_dump` / `pg_restore` 最稳妥。
+
+> **敏感备份警告：** `.spaces/05.运行维护/数据库迁移/备份/backup.dump` 是数据库二进制快照，可能包含账号、成员关系和其他业务数据。仓库内只允许保留确认过的本地虚构或已脱敏开发数据；严禁把生产、客户或未经脱敏的备份提交到版本库。导出新备份后，应先核对数据来源和敏感性，再决定是否留存；本指南不授权删除当前快照。
+
+> ⚠️ 本项目的 PostgreSQL 跑在 Docker 容器 `vp-postgres` 中，**Windows 宿主机上通常没有安装 `pg_dump`**，直接在 PowerShell 执行会提示"不是内部或外部命令"。
+> 因此统一通过 `docker exec` 在容器内执行，并用 `docker cp` 把备份文件拷进/拷出容器。
+> 以下命令均在**项目根目录**（`docker-compose.yml` 所在目录）执行。
+
+**备份（导出）**：
+
+```powershell
+# 1. 在容器内把整个 postgres 库导出为压缩备份（容器内本地连接无需输密码）
+docker exec vp-postgres pg_dump -Fc -U postgres -d postgres -f /var/lib/postgresql/backup.dump
+
+# 2. 把备份文件从容器拷到当前目录
+docker cp vp-postgres:/var/lib/postgresql/backup.dump ./backup.dump
+```
+
+参数说明：`-Fc` 表示 custom 自定义压缩二进制格式，体积小、可选择性恢复，必须配合 `pg_restore` 使用；`-f` 指定输出文件路径。
+
+**恢复（导入）**：
+
+```powershell
+cd .spaces/05.运行维护/数据库迁移/备份
+./restore-dump.ps1
+# 自动化场景使用 ./restore-dump.ps1 -Force 跳过 YES 确认
+```
+
+脚本先验证本目录的 `backup.dump`，然后从 `template1` 连接并强制断开 `postgres` 库上的会话，删除、重建该库，再导入备份。旧库中备份未包含的表和外键也会被删除。导入失败会返回错误；由于删库和导入无法组成同一事务，此时目标库可能为空，需要修复错误并重新执行脚本。恢复要求 PostgreSQL 管理员权限；运行期间应停止使用目标库的应用。具体目标和验收要求见[数据库备份覆盖恢复需求](需求文档.md)。
+
+建议备份文件名带上日期，避免多次备份互相覆盖，例如 `backup-20260912.dump`。
+
+**搬迁到另一台服务器**时：在旧服务器按上面"备份"两步拿到 dump 文件，传送到新服务器后：
+
+- 若新服务器也是同样的 Docker 部署，按上面的恢复脚本操作即可；
+- 若新服务器是本机安装的 PostgreSQL 且已安装客户端工具，应先从维护库连接并重建目标库，再导入备份。例如：
+
+  ```powershell
+  dropdb -h 192.168.1.50 -U postgres --maintenance-db=template1 --force --if-exists postgres
+  createdb -h 192.168.1.50 -U postgres --maintenance-db=template1 postgres
+  pg_restore -h 192.168.1.50 -U postgres -d postgres --no-owner --single-transaction --exit-on-error backup.dump
+  ```
+
+搬迁完成后，把应用的环境变量指向新库并启动验证即可，**无需再跑 `db:migrate`**——表结构、数据以及 drizzle 的迁移记录表都已随 dump 一起恢复。
+
+> 版本提示：`pg_dump` 的大版本不应低于（最好等于）被导出的 PostgreSQL 版本。用容器内自带的工具天然与服务端版本一致，可避免版本不匹配的警告和兼容问题。
+
+## 七、常见问题排查
+
+| 现象                            | 可能原因                                                    | 处理                                                                            |
+| ------------------------------- | ----------------------------------------------------------- | ------------------------------------------------------------------------------- |
+| `DATABASE_URL 未配置`           | drizzle-kit 没读到 env 文件                                 | 确认在 `apps/server` 下执行，且 `.env.development` 存在；检查 `NODE_ENV`        |
+| `ECONNREFUSED 127.0.0.1:5432`   | PostgreSQL 容器未启动                                       | 根目录执行 `docker compose up -d postgres`                                      |
+| `database "xxx" does not exist` | 连接串中的库名与实际不符                                    | 以 `docker-compose.yml` 中的 `POSTGRES_DB` 为准，或手动 `CREATE DATABASE`       |
+| `pg_dump 不是内部或外部命令`    | 宿主机未安装 PostgreSQL 客户端工具                          | 用 `docker exec vp-postgres pg_dump ...` 在容器内执行（见第六节）               |
+| `pg_restore` 删除主键时报外键依赖 | 旧库含备份外的表或约束，按对象清理不完整                   | 使用本节的覆盖恢复脚本重建目标库，而非直接用 `--clean` 导入旧库                 |
+| migrate 报迁移历史不一致        | 历史迁移文件或 meta 被改动                                  | 恢复被删改的文件；必要时在开发库清理 drizzle 迁移记录表后重新迁移（仅限开发库） |
+| generate 生成了意料之外的 DROP  | 快照与 schema 差异过大（如重命名列会被识别成删旧列+加新列） | 放弃生成，改用手写迁移或先保留旧列做数据过渡                                    |
+
+## 八、涉及的后端知识点
+
+- **Schema 迁移（migration）的本质**：把"表结构长什么样"从代码编译成有序、可追溯、可在各环境重放的 SQL 版本文件，解决多人协作与多环境下表结构不一致的问题，作用类似前端的 lock 文件——人人按同一份脚本得到相同结果。
+- **迁移记录表**：`db:migrate` 会在库中维护一张迁移日志表，记录哪些迁移文件已执行，保证每个迁移只执行一次。这就是迁移文件不能随意改名或删除的原因。
+- **代码即结构（schema-as-code）**：Drizzle 的 schema 既是建表依据，也是 TypeScript 类型和查询 API 的来源，改结构 = 改代码，天然可走 Code Review 和版本管理流程。
+
+## 九、变更记录
+
+| 日期       | 变更摘要                                                                                                   | 影响范围                           | 原因 |
+| ---------- | ---------------------------------------------------------------------------------------------------------- | ---------------------------------- | --- |
+| 2026-09-18 | 明确 `0003` 企业层级残留和 `0004` 未确认邀请实现共同阻断当前完整迁移链，现有命令降级为解除阻断后的标准流程 | 新环境、现有环境、部署与数据库搬迁 | 完整迁移链仍有设计偏差 |
+| 2026-09-30 | 恢复方式改为验证备份后重建整个目标库，删除旧库额外对象 | 备份恢复与搬迁 | `--clean` 无法删除被旧库额外外键依赖的主键 |

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

@@ -0,0 +1,31 @@
+# 数据库备份覆盖恢复需求
+
+> 状态：当前有效
+
+## 目标与范围
+
+在本地 Docker 容器 `vp-postgres` 中，用备份目录的 `backup.dump` 完整替换 `postgres` 数据库。目标库原有表、约束和业务数据均可丢弃；备份中没有的对象也必须消失。仅作用于该容器和该数据库，不修改其他数据库或备份文件。
+
+## 规则与流程
+
+- 恢复前检查备份存在、容器运行，并验证转储文件可由 `pg_restore` 读取；未通过时不得删除目标库。
+- 默认要求操作人输入 `YES`；显式传入 `-Force` 时跳过交互确认。两种方式执行相同的完整覆盖流程。
+- 从维护数据库连接，强制断开目标库连接后删除目标库，再创建空的同名库并导入备份。恢复失败时必须返回错误，不能输出成功提示。
+- 数据约束：旧库全部丢弃；备份内容是恢复后的唯一来源。删库之后若创建或导入失败，目标库可能暂时不存在或为空，操作人应修复错误并重新执行恢复。
+- 权限边界：只有具备目标 Docker 容器和数据库管理员权限的操作者可以运行此脚本。
+
+## 验收标准
+
+1. 旧库含备份以外的外键或表时，恢复仍能成功，旧对象不再存在。
+2. 无效备份或容器不可用时，在删库之前失败。
+3. 默认确认与 `-Force` 两种入口均恢复为备份中的结构和数据，并在失败时返回非零退出码。
+
+## 待确认事项
+
+无。
+
+## 变更记录
+
+| 日期 | 变更摘要 | 影响范围 | 决策原因 |
+| --- | --- | --- | --- |
+| 2026-09-30 | 明确旧库可丢弃，恢复改为重建整个目标库 | 备份恢复脚本与操作指南 | 旧库额外外键阻止 `pg_restore --clean` 删除主键 |

package/template-vp-monorepo-react-nestjs/.spaces/06./350/256/244/350/257/201/344/270/216/344/274/232/350/257/235//344/274/232/350/257/235/347/256/241/347/220/206//346/212/200/346/234/257/345/245/221/347/272/246.md

@@ -0,0 +1,93 @@
+# 认证与会话技术契约
+
+## 1. 状态和范围
+
+- 状态：当前有效契约。
+- 本契约描述当前 Redis Session 实现，不定义尚未实施的 Refresh Token 接口。
+- 成功响应和失败响应的通用包装见 [API 与错误技术契约](../../07.API与错误/技术契约.md)。
+
+## 2. 共享类型
+
+```ts
+type SessionTerminalType = 'web' | 'desktop' | 'mobile'
+
+interface RegisterRequest {
+  name: string
+  account: string
+  password: string
+}
+
+interface LoginRequest {
+  account: string
+  password: string
+}
+
+interface LoginResult {
+  accessToken: string
+  tokenType: 'Bearer'
+  idleExpiresIn: number
+  absoluteExpiresAt: string
+}
+```
+
+`accessToken` 是随机不透明令牌，不是 JWT。客户端通过 `Authorization: Bearer <token>` 访问受保护接口；服务端将令牌摘要映射到 Redis 会话。
+
+## 3. 接口
+
+| 方法与路径 | 请求 | 成功响应 | 说明 |
+| --- | --- | --- | --- |
+| `POST /auth/register` | `RegisterRequest` | `{ id, name, account }` | 创建全局账号，不创建成员关系 |
+| `POST /auth/login` | `LoginRequest` | `LoginResult` | 识别终端并创建或替换对应槽位会话 |
+| `POST /auth/logout` | Bearer Token 可选 | `{ loggedOut: true }` | 幂等退出；无有效格式令牌也返回成功 |
+| `GET /auth/me` | Bearer Token | `{ id, name, account, terminal }` | 返回当前启用用户及终端 |
+
+当前没有 `/auth/refresh`，也没有 `refreshToken` 字段。
+
+当前基线仍没有本人改密或平台管理员重置他人密码的接口。[修改密码需求](../修改密码/需求文档.md)处于实施中，其新增路径、共享类型、权限和错误码已在[修改密码技术契约](../修改密码/技术契约.md)明确；实现与验收完成前不属于上表的现行接口。
+
+## 4. Redis 会话约束
+
+- 会话键前缀：`auth:v1:session:`；槽位键前缀：`auth:v1:slot:`。
+- 槽位唯一键由 `userId + terminal` 组成。
+- Redis 保存 Token 摘要、用户 ID、终端、有效期和受限长度的登录来源，不保存明文 Token。
+- 创建／替换、校验／续期、退出和全端撤销使用 Lua 原子执行。
+- Redis 不可用或脚本协议异常统一转换为认证服务不可用错误，不能退化为绕过认证。
+
+## 5. 并发和撤销
+
+- 登录在密码验证后锁定目标用户并再次确认账号有效，再创建会话。
+- 同终端并发登录以最后成功写入的槽位为准，旧 Token 因槽位不再匹配而失效。
+- 停用账号时撤销全部终端会话；撤销失败则停用事务不得声称成功。
+- 每次受保护请求都必须确认会话存在且用户仍处于 active 状态。
+- 待实施的本人改密和管理员重置成功后均撤销目标账号全部终端会话；撤销失败则密码事务回滚。登录须在用户行共享锁内复核最新密码摘要，防止旧密码并发登录在撤销后重新建立会话。详见[修改密码技术契约](../修改密码/技术契约.md)。
+
+## 6. Cookie 契约
+
+Web 端当前写入 `token` Cookie：
+
+```text
+Path=/; SameSite=Lax; Secure=<当前页面是否为 HTTPS>
+```
+
+删除时必须复用写入时的 Path、Domain、SameSite 和 Secure 语义。后续修改 Cookie 名称或前缀时，所有写入、读取、删除和请求拦截逻辑必须同批变更。
+
+## 7. Refresh Token 迁移门槛
+
+实施 Access Token + Refresh Token 前，必须先补齐并确认：
+
+- Token 格式、签名／摘要策略和存储位置；
+- Access／Refresh 有效期和轮换、复用检测、会话族撤销；
+- 刷新接口的并发幂等和错误码；
+- Cookie、CSRF、CORS 和多端策略；
+- 当前 Bearer Session 到新机制的兼容期和回滚路径；
+- 普通接口撤权延迟上限及高风险接口的实时 Auth State 清单。
+
+上述契约未确认前，不新增半成品 Refresh Token 字段或端点。
+
+## 8. 变更记录
+
+| 日期 | 摘要 | 影响范围 | 原因 |
+| --- | --- | --- | --- |
+| 2026-10-08 | 关联修改密码实施契约和全端撤销、并发登录约束，保持现行接口与待实施接口分界 | 认证、会话与登录 | 支持本期密码维护开发且不提前宣称接口可用 |
+| 2026-09-30 | 明确本人改密与管理员重置尚无现行接口，并链接待实施需求 | 认证接口、共享类型与会话 | 区分已确认业务需求和当前可用契约 |
+| 2026-09-17 | 固化当前 Redis Session 契约，并隔离尚未确认的 Refresh Token 迁移目标 | Server、Web、shared | 防止历史设计讨论被误认为现有接口 |

package/template-vp-monorepo-react-nestjs/.spaces/06./350/256/244/350/257/201/344/270/216/344/274/232/350/257/235//344/274/232/350/257/235/347/256/241/347/220/206//351/234/200/346/261/202/346/226/207/346/241/243.md

@@ -0,0 +1,87 @@
+# 认证与会话需求文档
+
+## 1. 文档状态
+
+- 状态：当前 Redis Session 基线有效；修改密码后的会话撤销规则实施中；令牌演进部分待单独确认实施契约。
+- 整理日期：2026-09-17。
+- 当前实现依据：`apps/server/src/modules/auth/`、`packages/shared/src/types/auth.ts`。
+- 技术边界见 [技术契约](./技术契约.md)。
+
+## 2. 目标
+
+1. 用户通过全局唯一账号和密码完成注册、登录、获取当前身份及退出。
+2. 同一用户在同一种终端只保留一个有效会话；新登录替换该终端的旧会话。
+3. Web、桌面端和移动端可以分别保持会话；iOS 与 Android 统一归类为 `mobile`，不引入厂商专用 User-Agent 标记。
+4. 账号停用、会话替换和主动退出能够撤销对应登录状态。
+5. 会话数据和日志不保存明文密码或明文令牌，公开错误不泄露账号是否存在等敏感事实。
+6. 为后续 Access Token + Refresh Token 轮换保留明确迁移边界，但在契约确认前不把目标方案写成当前实现。
+
+## 3. 当前有效业务规则
+
+### 3.1 账号与注册
+
+- `account` 全局唯一；姓名不唯一，用户关系使用稳定 `userId`。
+- 公开注册只创建全局账号，不自动加入企业、项目或授予角色。
+- 企业“直接注册成员”是企业成员接入流程：创建新全局账号并建立企业成员关系；它不等同于公开注册，也不能覆盖已有账号。
+
+### 3.2 终端分类
+
+| 终端 | 识别规则 | 会话槽位 |
+| --- | --- | --- |
+| `desktop` | User-Agent 含 Electron | 用户 + desktop |
+| `mobile` | Android、iPhone、iPad 或 iPod | 用户 + mobile |
+| `web` | 其他浏览器请求 | 用户 + web |
+
+同一槽位的新登录替换旧会话；不同槽位互不替换。
+
+### 3.3 会话有效性
+
+- 当前使用 Redis 保存服务端会话，客户端持有随机 Bearer Token；Redis 只使用令牌摘要定位会话。
+- 会话同时受闲置有效期和不可延长的绝对有效期约束。
+- 有效请求可以刷新闲置有效期，但不能突破绝对有效期。
+- 账号停用时撤销该用户全部终端会话；重新启用后必须重新登录。
+- 普通受保护请求至少校验会话和当前用户状态。权限敏感接口还必须读取当前作用域、成员和权限状态，不能只相信登录时快照。
+
+### 3.4 Cookie 使用边界
+
+- 当前 Web 端使用名为 `token` 的 Cookie 保存 Bearer Token，默认 `Path=/`、`SameSite=Lax`，HTTPS 下启用 `Secure`。
+- 删除 Cookie 时必须使用与写入相同的名称、Path 和 Domain，否则浏览器中的旧值不会被真正删除。
+- Cookie 名称若后续增加环境或应用前缀，写入、读取和删除必须共同使用同一前缀规则。
+- 当前 Cookie 可由前端 JavaScript 读取；若迁移到 HttpOnly Refresh Token，必须单独设计 CSRF、跨域和兼容策略。
+
+## 4. 后续令牌演进需求
+
+历史讨论提出将会话演进为短期 Access Token + 可轮换 Refresh Token。该目标需要保留，但当前代码没有 Refresh Token，也没有刷新端点，不能把下面内容当作已实施事实：
+
+1. Refresh Token 每次使用后轮换，旧 Token 失效；检测到复用时撤销对应会话族。
+2. 普通接口可以在明确的短时间窗口内接受撤权传播延迟；高风险接口必须读取共享 Auth State 做实时状态和撤销检查。
+3. 同一用户、同一终端类型仍只保留一个活动会话族。
+4. Access Token、Refresh Token 的载体、有效期、Cookie 属性、刷新接口、并发刷新、跨端退出和迁移兼容期必须先形成完整技术契约。
+
+## 5. 验收标准
+
+1. 同一用户在同一终端再次登录后，旧 Token 无法继续使用。
+2. Web、desktop、mobile 会话可以分别存在，iOS 与 Android 归入同一 mobile 槽位。
+3. 闲置超时、绝对超时、退出和账号停用均使相关会话失效。
+4. 登录、退出、会话校验和服务异常不会在响应或日志中暴露明文密码、Token、Cookie 或连接串。
+5. Cookie 删除使用与写入一致的 Path／Domain；退出后前端不再携带旧 Token。
+6. 在 Refresh Token 方案正式实施前，接口和文档均不得声称支持刷新或轮换。
+
+## 6. 待确认事项
+
+- 是否以及何时从 Redis opaque Session 迁移到 Access Token + Refresh Token。
+- Access Token 是否使用 JWT；若使用，签发者、受众、密钥轮换和撤销窗口如何定义。
+- Refresh Token 使用 HttpOnly Cookie 还是其他受控载体，以及 CSRF 防护方案。
+- 哪些接口属于必须实时读取共享 Auth State 的高风险接口。
+
+## 7. 实施中：修改密码后的会话规则
+
+[修改密码需求文档](../修改密码/需求文档.md)已确认本人改密及平台管理员重置他人密码的业务规则，实施契约见[修改密码技术契约](../修改密码/技术契约.md)。本人改密成功后撤销该用户全部终端会话，当前端返回登录页；管理员重置成功后撤销目标账号全部终端会话，操作者会话不受影响。会话撤销失败不得把密码操作报告为成功，密码保持原值。实施时还须防止旧密码并发登录在撤销后创建新会话。代码和验收完成前，上述能力不是当前有效基线。
+
+## 8. 变更记录
+
+| 日期 | 摘要 | 影响范围 | 原因 |
+| --- | --- | --- | --- |
+| 2026-10-08 | 关联修改密码实施契约，补充撤销失败回滚与并发登录约束 | 认证、会话与密码维护 | 使待实施会话规则与设计和接口契约一致 |
+| 2026-09-30 | 标明本人改密与管理员重置后的全端会话撤销为待实施需求 | 认证、会话与账号密码维护 | 与新增修改密码需求同步，避免将未实现的规则误写成当前基线 |
+| 2026-09-17 | 从本机 Codex 历史和当前实现整理认证、终端会话及令牌演进边界 | 认证与会话 | 避免把当前 Redis Session 与历史讨论的 Refresh Token 目标混为一套现行契约 |

package/template-vp-monorepo-react-nestjs/.spaces/06./350/256/244/350/257/201/344/270/216/344/274/232/350/257/235//344/277/256/346/224/271/345/257/206/347/240/201/PRD.md

@@ -0,0 +1,55 @@
+# 修改密码 PRD
+
+## 1. 状态与依据
+
+- 状态：待实施；页面与交互依据已确认需求编排，实际验收以实现和测试记录为准。
+- 需求来源：[修改密码需求文档](./需求文档.md)。现行会话规则见[会话管理需求文档](../会话管理/需求文档.md)。
+- 本文只描述用户可见流程；服务端权限、接口、错误和一致性以[技术契约](./技术契约.md)为准。
+
+## 2. 用户故事与入口
+
+| 用户 | 诉求 | 入口 |
+| --- | --- | --- |
+| 已登录的全局账号用户 | 验证旧密码后自行修改密码 | 工作空间选择页的账号操作；进入任一工作空间后的全局账号操作 |
+| 没有工作空间的已登录用户 | 仍能自行改密 | `/workspaces` 工作空间选择页的账号操作，不依赖工作空间权限 |
+| 平台管理员 | 为其他全局账号直接设定新密码 | `/platform/accounts` 目标账号的行操作；本人行不提供重置入口 |
+
+企业或项目管理员不会因其作用域身份获得平台重置入口。页面条件只是辅助；服务端仍须按[技术契约](./技术契约.md)鉴权。
+
+## 3. 页面与交互流程
+
+### 3.1 本人修改密码
+
+1. 用户从账号操作打开修改密码表单。表单提供旧密码、新密码、确认密码；三个输入框均不预填，也不在返回页面时保留输入。
+2. 前端检查三项必填、两次新密码一致、新密码为 8–16 位以及新旧密码不同。提交期间阻止重复提交；服务端再次执行完整校验。
+3. 成功时清理本地登录凭据和进行中的工作空间请求，跳转 `/login`；提示用户使用新密码重新登录。发起改密的当前会话和其他终端旧会话均应失效。
+4. 失败时停留在表单，显示可公开的字段或业务错误并允许修正重试；不得显示成功提示，不清理仍有效的本地会话。密码字段不写入 URL、持久存储或客户端日志。
+
+### 3.2 平台管理员重置
+
+1. 平台管理员在全局账号列表选择非本人账号，打开重置密码表单。显示目标账号的公开标识供核对，输入新密码与确认密码，不要求旧密码。
+2. 前端检查两次输入一致、新密码为 8–16 位；提交期间阻止重复提交。服务端独立校验平台管理员身份、目标存在且不是操作者本人。
+3. 成功时关闭表单并提示通过现有线下渠道告知用户；不展示、不复制、不发送或回显新密码。管理员当前登录保持有效，目标账号原有各终端会话失效。
+4. 失败时保留可修正的界面并显示公开错误，不提示成功。目标账号状态、角色与成员关系均不因重置变化。
+
+## 4. 验收映射
+
+| 场景 | 预期结果 | 需求对应 |
+| --- | --- | --- |
+| 无工作空间的已登录用户改密 | 可进入表单；成功后回登录页，旧密码与旧会话失效，新密码可登录 | 6.1 |
+| 旧密码错误、两次输入不一致、长度非法或新旧相同 | 无密码变更和成功提示；可修正重试 | 6.2 |
+| 平台管理员重置其他账号 | 目标全部旧会话失效；操作者会话有效；目标状态及关系不变；下次登录不强制再改密 | 6.3 |
+| 平台管理员重置自己、非平台管理员操作、目标不存在或撤销失败 | 服务端拒绝或报告失败，密码保持原值，不显示成功 | 6.4 |
+| 凭据和操作记录 | 响应、日志、审计、截图无密码明文或摘要；操作结果可追溯 | 6.5 |
+
+表中“需求对应”指[修改密码需求文档](./需求文档.md)第 6 节；实际执行证据应归档到本功能的测试报告，不以本文代替测试结果。
+
+## 5. 范围外事项
+
+未登录忘记密码找回、自动发送密码、自动生成临时密码和首次登录强制改密均不在本期范围；详见[需求文档](./需求文档.md)。
+
+## 6. 变更记录
+
+| 日期 | 摘要 | 影响范围 | 原因 |
+| --- | --- | --- | --- |
+| 2026-10-08 | 增补本人改密和平台重置的入口、页面流程与验收映射 | Web 账号操作、工作空间选择页、平台账号列表 | 为已确认需求提供实施和验收所需的交互依据 |