create-bubbles 0.1.25 → 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//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 账号操作、工作空间选择页、平台账号列表 | 为已确认需求提供实施和验收所需的交互依据 |

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//346/212/200/346/234/257/345/245/221/347/272/246.md

@@ -0,0 +1,92 @@
+# 修改密码技术契约
+
+## 1. 状态与依赖
+
+- 状态：待实施；以下是本期前后端实施与联调契约，接口在实现和验收完成前不得标为现行可用。
+- 业务规则以[需求文档](./需求文档.md)为准；交互流程见[PRD](./PRD.md)，事务与并发取舍见[设计方案](./设计方案.md)。
+- 认证沿用[会话管理技术契约](../会话管理/技术契约.md)的 Redis Session；HTTP 成功正文、统一失败结构与 `x-request-id` 遵循[API 与错误技术契约](../../07.API与错误/技术契约.md)。
+
+## 2. 共享请求与响应类型
+
+前后端在 `packages/shared/src/types` 共享下列类型；Server DTO 与 Web 请求方法引用该处定义，不在两端复制平行接口。
+
+```ts
+interface ChangePasswordRequest {
+  oldPassword: string
+  newPassword: string
+  confirmPassword: string
+}
+
+interface ChangePasswordResult {
+  passwordChanged: true
+}
+
+interface ResetAccountPasswordRequest {
+  newPassword: string
+  confirmPassword: string
+}
+
+interface ResetAccountPasswordResult {
+  passwordReset: true
+}
+```
+
+- 三个密码字段仅用于本次请求；均不做 `trim` 或其他隐式改写。旧密码必填；新密码按当前注册规则为 8–16 位；确认密码必须与新密码完全相同。本人改密时，新旧密码必须不同。
+- 管理员重置不要求旧密码，也不以目标账号当前密码为输入；`userId` 为路径中的 UUID，不进入请求体。成功结果不包含目标资料、明文密码或摘要。
+- 服务端必须重新校验所有约束；输入校验失败时密码与会话不变。前端校验只用于及时反馈。
+
+## 3. 接口与权限
+
+| 方法与路径 | 请求 | 200 正文 | 权限与作用对象 |
+| --- | --- | --- | --- |
+| `POST /auth/change-password` | `ChangePasswordRequest`，Bearer Session | `ChangePasswordResult` | `@Authenticated()`；目标固定为当前会话 `userId`，不依赖工作空间 |
+| `POST /platform/accounts/:userId/reset-password` | `ResetAccountPasswordRequest`，Bearer Session | `ResetAccountPasswordResult` | 平台作用域 `platform.accounts.reset-password` 且 `adminOnly: true`；目标必须存在且不能等于操作者 `userId` |
+
+- `platform.accounts.reset-password` 是绑定 `platform.accounts` 页面的新操作权限，加入共享权限目录；仅平台内置管理员可实际使用，不可授予自定义角色。守卫和服务层写事务均须复核平台管理员身份，避免授权状态变化与直接调用服务绕过。
+- 平台账号列表按钮只在平台内置管理员且目标非本人时展示；任何已存在账号均可被重置，原状态保持不变。当前账号模型包含 `active`、`locked`、`disabled`；未来扩展状态亦遵循保留规则。角色或成员关系不变。本人改密对无工作空间但会话有效的用户开放。
+- 成功后撤销**目标**在 `web`、`desktop`、`mobile` 全部终端的旧会话；本人改密包含当前会话，Web 删除本地令牌并转 `/login`。管理员自己的会话不受目标撤销影响。重置后用户下次登录不强制改密。
+- 重置接口不发送密码；管理员按现有线下渠道告知用户。两个接口不接收幂等键，本期同一目标并发操作由用户行锁串行化。
+
+## 4. 公开错误与失败行为
+
+失败按统一 `ApiFailure` 返回，不回显请求字段值、密码摘要或原始异常。下表中的错误码为本期拟新增或复用的稳定码；`COMMON.VALIDATION_FAILED` 可包含安全清洗后的字段详情。
+
+| 场景 | HTTP | 公开码 | 密码与会话 |
+| --- | --- | --- | --- |
+| 缺少或无效会话 | 401 | `AUTH.SESSION_TOKEN_MISSING` / `AUTH.SESSION_INVALID` | 不变 |
+| 旧密码错误 | 422 | `AUTH.OLD_PASSWORD_INCORRECT` | 不变 |
+| 新旧密码相同 | 422 | `AUTH.PASSWORD_REUSE_NOT_ALLOWED` | 不变 |
+| 必填、长度、确认密码或目标 UUID 格式不合法 | 400 | `COMMON.VALIDATION_FAILED` | 不变 |
+| 非平台管理员、无操作权限或重置自己 | 403 | `ACCESS.FORBIDDEN` | 不变 |
+| 目标账号不存在 | 404 | `ACCESS.NOT_FOUND` | 不变 |
+| Redis 撤销失败、脚本协议异常或必要认证依赖不可用 | 503 | `AUTH.SERVICE_UNAVAILABLE` | 密码更新回滚；撤销失败时不能报告成功 |
+
+- 目标不存在与越权场景不泄露目标密码、角色或内部查询结果；错误码仍须保留可诊断的授权与资源语义。
+- 任一失败不得向客户端显示“修改／重置成功”。会话撤销已成功但随后 PostgreSQL 提交失败时，密码事务回滚，旧会话可能已失效；接口返回失败，用户按原密码重新登录。此情况不可伪装为成功或恢复已撤销的会话。
+
+## 5. 写入顺序与并发一致性
+
+1. 本人改密在 PostgreSQL 事务中以目标用户 `FOR UPDATE` 行锁读取最新摘要并验证旧密码；管理员重置在平台权限写事务中复核管理员身份、锁定目标行并排除本人。
+2. 用现有 Argon2id 规则生成新摘要，只更新 `users.password_hash` 和必要的更新时间；管理员成功的现有 `audit_logs` 记录随业务事务写入，摘要只含动作结果等白名单字段。
+3. 在事务提交前执行 `SessionStoreService.revokeAllForUser(targetUserId)`；Redis Lua 脚本原子撤销三个终端槽位。撤销异常抛出并回滚 PostgreSQL 密码更新和事务内成功审计，然后返回 503。
+4. Redis 成功后提交 PostgreSQL。数据库提交失败时不能返回成功；Redis 撤销不逆转。事务成功提交后才向客户端返回 200。
+5. 登录流程必须与密码写入按同一用户行锁串行化：在获得共享行锁后重新验证最新密码摘要，或确认摘要没有从加锁前验证的值变化。禁止沿用加锁前对旧摘要的验证结果直接创建新会话，否则可能在改密撤销后生成有效的旧密码会话。
+
+## 6. 安全事件与审计
+
+- 两种操作的成功与失败均输出固定字段结构化安全事件：`event`（`account.password.change` 或 `account.password.reset`）、`actorUserId`（认证前未知时为 `null`）、`targetUserId`（目标未解析或路径不合法时为 `null`）、`requestId`、`result`（`success` / `failure`）、`reasonCode`（成功为 `null`，失败为稳定错误码）、`occurredAt`（UTC 时间）。只允许这些字段，禁止记录请求体、密码、摘要、Token、Cookie、账号资料快照或原始异常对象。
+- 接口入口、认证守卫与平台权限守卫中的拒绝同样属于失败事件，不能仅在业务方法 `catch` 中记录；每个请求只记录一次最终结果。失败事件在业务事务外输出，避免回滚吞掉记录。未能解析的目标不伪造目标身份。
+- 管理员重置成功另外按现有平台管理审计口径写入 `audit_logs`：`action='account.password.reset'`、`objectType='account'`、`objectId=targetUserId`，`summary` 只含 `{ result: 'success' }`；该行与密码更新同事务提交。失败不写入既有成功变更审计。本人改密的成功／失败由上述安全事件覆盖，不强行写入要求平台作用域的管理审计。
+- 安全事件使用现有应用结构化日志采集链路，应用侧不新增单独的清理任务；访问范围沿用该链路的运维／安全权限。当前仓库没有可核验的统一保留期限配置，实际保留周期和检索能力须在交付时依据部署环境确认并记录，不能写成已落实。功能验收先检查事件固定字段、成功与失败覆盖，以及凭据不进入日志。
+
+## 7. 兼容与验收
+
+- 现有注册、登录、退出、`/auth/me` 的路径和返回类型保持不变；无需数据迁移或新增用户字段。新权限加入共享目录后同步种子数据与平台账号页操作授权。
+- 已登录但无工作空间、跨终端撤销、管理员自身会话保留、锁定／停用目标状态不变、权限与自重置拒绝、Redis 故障回滚，以及“旧密码登录与改密并发”均须验证。
+- 响应、结构化安全事件、平台审计、应用日志与测试证据均不得出现明文密码或密码摘要。验证结果须写入本功能测试报告；仅代码阅读不能标为通过。
+
+## 8. 变更记录
+
+| 日期 | 摘要 | 影响范围 | 原因 |
+| --- | --- | --- | --- |
+| 2026-10-08 | 确定双接口、共享类型、权限、错误、全端撤销一致性与安全事件契约 | Server、Web、shared、Redis Session、平台审计 | 将待实施业务需求转为可联调且可验收的技术边界 |

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//346/265/213/350/257/225/346/212/245/345/221/212.md

@@ -0,0 +1,38 @@
+# 修改密码测试报告
+
+## 1. 状态与范围
+
+- 状态：验证记录（2026-10-08，验证进行中）；本报告尚未形成完整验收结论。
+- 依据：[需求文档](./需求文档.md)、[PRD](./PRD.md)、[技术契约](./技术契约.md)。
+- 验证对象为当前工作树中的 Shared、Server 与 React Web 增量；基线提交为 `c7f2bc6`。工作树未提交，后续代码变化须复测受影响项。
+
+## 2. 已执行的自动化
+
+| 范围与命令 | 实际结果 | 证据边界 |
+| --- | --- | --- |
+| Server：`vp test test/auth/password-operations.spec.ts` | 12 项通过 | 使用服务替身验证事务失败路径、权限、安全事件和登录并发判定；包含 Fastify inject 的路由响应钩子测试，不等同于真实数据库／Redis 联调 |
+| Server：`vp test` | 8 套件、45 项通过；2 套件、23 项因环境门控跳过 | 跳过项不得计为通过；真实依赖专项另记 |
+| Server：`pnpm exec tsc --noEmit -p tsconfig.json`、`vp run build` | 均执行成功 | 类型检查与构建不能替代运行态验证 |
+| Web：定向运行 `password-actions.spec.ts`、`password-reset-action.spec.ts`、`workspaces-password-entry.spec.tsx` | 共 5 项通过 | 覆盖成功后清理本地会话、失败时保留会话、入口显示与空工作空间实际页面渲染；未覆盖真实浏览器全过程 |
+| Web：`pnpm --filter web build` | 执行成功 | 类型检查与构建不能替代运行态验证 |
+
+Web 全量 `pnpm --filter web test` 的 20 个套件中，14 个套件运行通过，62 项测试通过；另 6 个套件在导入既有 `apps/web/src/i18n/instance.ts` 时因 Node 测试环境缺少 `localStorage` 而未进入用例。加临时 `NODE_OPTIONS=--localstorage-file` 后仍复现。改用 `pnpm --filter web exec vp test --environment happy-dom`，19 个套件运行，106 项通过；既有 `test/request.spec.ts` 的 11 项因 happy-dom 的 CORS 限制拒绝本地测试 HTTP 服务而失败。这些运行不能记为 Web 全量通过。
+
+## 3. 验收场景与未覆盖项
+
+| 场景 | 当前证据 | 待补验证 |
+| --- | --- | --- |
+| 无工作空间用户进入本人改密、成功后回登录页 | Web 页面与会话清理定向自动化 | 真实浏览器和后端联动 |
+| 旧密码错误、密码复用、输入不合法时无密码变更 | Server 定向自动化 | 真实 PostgreSQL 写入前后比对 |
+| 平台管理员重置他人、自重置拒绝、越权拒绝、目标不存在 | Server 定向自动化及 Web 入口定向自动化 | 真实权限数据和 HTTP 联动 |
+| 撤销目标 Web、桌面端、移动端会话，管理员自身会话保持 | 服务替身验证撤销调用边界 | 真实 Redis 三终端会话验证 |
+| Redis 撤销失败时密码和成功审计回滚，旧密码并发登录不能重新建会话 | Server 定向自动化 | 真实 PostgreSQL／Redis 故障与并发验证 |
+| 响应、安全事件、管理审计和普通日志无密码明文或摘要 | Server 定向自动化覆盖固定安全事件与错误日志，代码审查已发现并修复两处问题 | 运行态日志、响应与审计数据抽检；部署日志保留期限与检索能力确认 |
+
+真实 PostgreSQL／Redis 专项、浏览器端到端场景及运行态日志／审计抽检尚待记录，不能据当前自动化结果认定需求第 6 节全部通过。相关前后端核对见[联调记录](./联调记录.md)。
+
+## 4. 变更记录
+
+| 日期 | 摘要 | 影响范围 | 原因 |
+| --- | --- | --- | --- |
+| 2026-10-08 | 建立自动化与未覆盖场景记录，区分测试环境加载失败和真实依赖验证 | Shared、Server、Web、认证与会话 | 避免将代码级测试或构建结果误记为完整业务验收 |