create-bubbles 0.1.26 → 0.1.27

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、认证与会话 | 避免将代码级测试或构建结果误记为完整业务验收 |

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//350/201/224/350/260/203/350/256/260/345/275/225.md

@@ -0,0 +1,26 @@
+# 修改密码联调记录
+
+## 1. 状态与依据
+
+- 状态：验证记录（2026-10-08，联调进行中）；目前记录前后端契约核对，尚未形成运行态完整联调结论。
+- 需求与用户流程见[需求文档](./需求文档.md)和[PRD](./PRD.md)；请求、响应、权限及失败语义见[技术契约](./技术契约.md)。执行结果见[测试报告](./测试报告.md)。
+
+## 2. 已核对的接口衔接
+
+| 场景 | 当前代码衔接 | 验证边界 |
+| --- | --- | --- |
+| 本人改密 | Web `changePassword` 提交共享 `ChangePasswordRequest` 到 `POST /auth/change-password`；Server 使用当前会话 `userId` 处理并返回 `ChangePasswordResult` | 已完成源码与类型路径核对，运行态 HTTP 联动待记录 |
+| 平台管理员重置 | Web 平台账号管理提交共享 `ResetAccountPasswordRequest` 到 `POST /platform/accounts/:userId/reset-password`；Server 路由要求平台操作权限与内置管理员身份 | 已完成源码与类型路径核对，真实权限数据的 HTTP 联动待记录 |
+| 成功与失败界面 | 本人成功后删除本地令牌并跳转登录页，重置成功后仅提示线下告知；失败保留仍有效的会话且不显示成功 | 定向 Web 自动化已执行，真实浏览器全过程待记录 |
+
+## 3. 联调发现与待确认
+
+- 安全审查发现管理员重置请求的未知字段名可能进入 400 响应，以及重置时认证存储／审计故障可能返回与契约不符的 500。Server 已针对这两项修改，并在定向自动化中复测；真实依赖故障路径仍待验证。
+- Web 全量测试受既有 Node `localStorage` 加载条件和 happy-dom 本地 HTTP CORS 限制影响；具体运行数字和边界见[测试报告](./测试报告.md)。
+- 当前尚无真实浏览器端到端证据；部署日志的实际保留期限和检索能力也尚未核验。
+
+## 4. 变更记录
+
+| 日期 | 摘要 | 影响范围 | 原因 |
+| --- | --- | --- | --- |
+| 2026-10-08 | 建立共享类型、Web 请求与 Server 路由的衔接核对及待联调边界 | Shared、Web、Server | 区分源码契约核对和真实运行态联调 |

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//350/256/276/350/256/241/346/226/271/346/241/210.md

@@ -0,0 +1,53 @@
+# 修改密码设计方案
+
+## 1. 状态与来源
+
+- 状态：待实施；本文描述 2026-10-08 确定的实施设计，不表示当前接口已经上线。
+- 业务边界以[需求文档](./需求文档.md)为准，用户流程以[PRD](./PRD.md)为准，字段与错误以[技术契约](./技术契约.md)为准。
+- 沿用当前全局 `users` 账号、Argon2id 密码摘要和 Redis Session；不引入工作空间级密码、临时密码或 Refresh Token。
+
+## 2. 交互与权限设计
+
+- 本人改密由全局账号操作承载，在 `/workspaces` 与已进入工作空间的布局中均提供入口；即使用户没有任何工作空间，仍可使用已登录会话操作。表单为旧密码、新密码、确认密码，提交后成功即清除客户端凭据和待处理请求，再转 `/login`。
+- 平台管理员重置位于 `/platform/accounts` 的目标账号行操作。仅当当前访问上下文为平台内置管理员且目标不是自己时显示入口；服务端独立要求平台内置管理员，禁止用前端隐藏代替授权。
+- 管理员输入目标的新密码与确认密码；只展示目标公开资料作为核对信息。成功后保留管理员会话，并提示通过现有线下渠道交付；系统不回显或自动发送密码。
+
+## 3. 服务端领域流程
+
+### 3.1 本人改密
+
+1. 认证守卫校验当前 Bearer 会话，使用会话中的 `userId` 作为唯一目标，不接受请求体指定目标账号。
+2. 校验新密码与确认密码、8–16 位长度及新旧不同；在目标用户行排他锁内读取最新摘要并验证旧密码，避免并发密码操作以旧快照覆盖新值。
+3. 使用现有 `PasswordService` 生成 Argon2id 摘要；在 PostgreSQL 事务内更新 `users.password_hash`，提交前调用 Redis 全端撤销脚本。撤销失败则抛错回滚数据库密码，不返回成功。成功和失败的安全事件使用固定字段结构化日志记录。
+4. 事务提交后返回无凭据的成功正文；客户端删除本地令牌并转登录页。任何失败均不返回成功。
+
+### 3.2 管理员重置
+
+1. 会话和平台访问守卫校验平台作用域，再由写事务重新确认操作者仍为平台内置管理员。不能仅凭 `platform.accounts.read` 或普通账号管理权限授权。
+2. 在写事务内锁定目标用户行，确认目标存在且不是操作者；任何已存在账号均可重置，状态原样保留。当前模型包含 `active`、`locked`、`disabled`，未来新增状态也遵循保留规则；角色及成员关系不变。
+3. 校验新密码与确认密码及长度，生成 Argon2id 摘要，更新目标 `password_hash`。在同一事务内写入平台成功管理审计，并在提交前撤销目标全部终端会话；失败则回滚密码更新及成功审计。操作者的会话不参与撤销。
+
+### 3.3 并发与一致性
+
+- Redis 撤销采用现有 `SessionStoreService.revokeAllForUser` 的单脚本原子操作，覆盖 `web`、`desktop`、`mobile` 槽位。数据库与 Redis 不能共用分布式事务；以“数据库事务中更新密码 → Redis 撤销 → 提交事务”的顺序，保证**撤销失败时密码保持原值**。若 Redis 已撤销而数据库提交失败，密码仍为旧值，但会话已失效，客户端须重新登录；这是安全侧的可接受保守结果，不能提示改密成功。
+- 改密或重置持有目标用户 `FOR UPDATE` 行锁，登录创建会话持有该用户共享行锁，两类操作必须串行化。现有登录在加锁前校验密码；实施时必须在共享锁内比对当前摘要与先前验证的摘要，或在锁内重新校验密码。如果摘要已变化，旧密码登录必须失败，不得在撤销后创建新会话。
+- 并发本人改密、管理员重置、账号停用以目标用户行锁排序；实际成功结果以事务提交为准。失败不改变密码；已执行的 Redis 撤销不做会话恢复。
+
+## 4. 安全记录与数据边界
+
+- 两种操作的成功和失败使用固定字段结构化安全日志记录 `event`、`actorUserId`、可确定时的 `targetUserId`、`result`、`reasonCode`、`requestId` 和时间；不序列化请求体、密码字段、密码摘要、Cookie、Token、Redis/SQL 原始异常或错误对象。
+- 管理员重置的成功平台管理审计与密码写入同事务提交；失败事件在业务事务外记录，避免回滚丢失。具体记录载体、可查范围和保留边界以[技术契约](./技术契约.md)为准。
+- 公开错误沿用[API 与错误技术契约](../../07.API与错误/技术契约.md)包装；后端参数校验不可仅依赖前端。失败时不暴露目标摘要或内部依赖信息。
+- 密码明文只在请求处理内用于验证和加密，不在服务端响应或任何日志、审计摘要、测试证据及截图中出现。目标密码摘要仅写入 `users.password_hash`。
+
+## 5. 实施与验证边界
+
+- 前后端接口类型与返回类型集中在 `packages/shared/src/types`；服务端 DTO 校验按共享类型建立，前端请求使用同一类型，不复制平行声明。
+- 验证至少覆盖：无工作空间的本人入口、跨终端旧会话失效、旧密码或权限失败时密码原值、目标不存在、自重置拒绝、Redis 撤销故障回滚、并发旧密码登录、管理员自身会话保留、凭据不进入响应和记录。
+- 本功能不修改账号状态、角色或成员关系，也不处理未登录找回；后续 Token 机制迁移应重新评估会话撤销实现。
+
+## 6. 变更记录
+
+| 日期 | 摘要 | 影响范围 | 原因 |
+| --- | --- | --- | --- |
+| 2026-10-08 | 确定入口、权限、事务内全端撤销、登录并发校验及安全记录边界 | Auth、平台账号、Web、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//351/234/200/346/261/202/346/226/207/346/241/243.md

@@ -0,0 +1,63 @@
+# 修改密码需求文档
+
+## 1. 文档状态
+
+- 状态：实施中；以下业务规则已确认，本功能尚待代码实现与验收完成。
+- 整理日期：2026-09-30。
+- 当前认证与会话基线见[会话管理需求文档](../会话管理/需求文档.md)和[会话管理技术契约](../会话管理/技术契约.md)。本功能的实施依据另见[PRD](./PRD.md)、[设计方案](./设计方案.md)和[技术契约](./技术契约.md)；拟新增能力在验收完成前不是现行接口。
+
+## 2. 背景与目标
+
+当前用户注册后无法自行修改密码，管理员也无法为忘记密码的用户重置密码。账号是跨工作空间使用的全局身份；密码变更必须作用于全局账号，并及时使旧登录状态失效。
+
+本功能让已登录用户验证旧密码后修改自己的密码，让平台管理员为其他全局账号设定新密码，同时保护密码内容与各终端会话。
+
+## 3. 范围与入口
+
+- 本人改密属于账号级功能，不依赖企业、项目成员身份或工作空间权限；已登录但没有任何工作空间的用户也必须能从工作空间选择页进入。进入工作空间的用户可从全局账号入口进入。
+- 管理员重置入口位于平台账号管理，仅平台管理员可操作；企业管理员和项目管理员不能重置全局账号密码。平台管理员不能通过此入口重置自己的密码，应使用本人改密流程。
+- 管理员可重置其他已存在的全局账号。重置不改变账号的启用、锁定或停用状态，也不改变角色、成员关系；不能登录的账号不会因重置密码而自动恢复登录资格。
+- 本期不包含未登录用户的忘记密码找回、邮件或短信发送、自动生成临时密码，也不要求管理员重置后的首次登录强制改密。
+
+## 4. 业务流程与规则
+
+### 4.1 本人修改密码
+
+1. 已登录用户输入旧密码、新密码和确认密码；密码输入不预填，确认密码必须与新密码一致。
+2. 服务端验证当前会话、旧密码以及新密码。新密码沿用当前注册校验的 8–16 位长度规则，且不得与旧密码相同；仅前端校验不能代替服务端校验。
+3. 验证通过后更新该全局账号的密码摘要，并撤销该用户在 Web、桌面端和移动端的全部会话，包括发起改密的当前会话。前端清除本地登录凭据并跳转登录页；用户须使用新密码重新登录。
+4. 旧密码错误、输入不合法或处理失败时，不更新密码，也不提示修改成功；允许用户修正输入后重试。
+
+### 4.2 平台管理员重置他人密码
+
+1. 平台管理员在平台账号管理中选择其他全局账号，输入新密码和确认密码；无须提供目标账号的旧密码。
+2. 新密码同样遵循 8–16 位长度规则，确认密码必须一致。成功后更新目标账号的密码摘要，撤销目标账号全部终端会话；管理员自己的会话保持有效。
+3. 管理员通过现有线下渠道把自己设定的新密码交给用户。系统不发送密码，也不在成功响应或操作记录中回显密码。用户下次使用新密码登录后可直接使用原有权限，不强制再次改密。
+4. 目标账号不存在、操作者无权或处理失败时，不更新密码，也不提示重置成功。
+
+## 5. 权限、安全与数据约束
+
+- 本人改密只允许作用于当前会话对应的 `userId`；管理员重置须同时满足有效登录和平台管理员身份，并由服务端校验操作者与目标不是同一账号。页面隐藏操作入口不能代替服务端鉴权。
+- 明文密码仅用于本次校验与生成密码摘要；数据库只保存摘要。明文密码及摘要不得写入接口响应、日志、审计摘要、测试证据或截图。密码摘要算法沿用当前认证实现。
+- 为本人改密和管理员重置记录可追溯的安全操作结果，包括操作人、目标账号、操作类型、时间与成功或失败结果；目标未解析时不伪造目标身份。失败记录的载体和字段在实施契约中确定，不改变现行管理审计只记录成功变更的既有口径。
+- 密码更新和目标全部终端会话撤销共同构成成功条件。会话撤销失败时不得返回成功，密码应保持原值；实现方案须处理数据库与会话存储之间的一致性，并避免暴露底层错误或凭据。
+
+## 6. 验收标准
+
+1. 已登录用户在没有工作空间时仍可进入本人改密；旧密码正确、两次新密码一致且符合规则时可改密，随后当前及其他终端旧会话均失效，旧密码不能再登录，新密码可以登录。
+2. 旧密码错误、新旧密码相同、新密码长度不符或确认密码不一致时，密码保持原值，不显示成功结果。
+3. 平台管理员可重置其他已有账号；目标账号全部旧会话失效，管理员会话不受影响，目标账号状态、角色和成员关系保持原样，首次使用新密码登录不被强制再次改密。
+4. 平台管理员不能从重置入口重置自己；企业或项目管理员、未登录用户不能重置全局账号密码。目标不存在或会话撤销失败时，密码保持原值，不显示成功结果。
+5. 响应、日志、审计和归档证据均不含明文密码或密码摘要；安全操作记录能够区分操作人、目标账号和结果。
+
+## 7. 实施契约与交付待确认事项
+
+- 接口路径、共享请求与返回类型、错误码及权限标识已在[技术契约](./技术契约.md)中确定；密码更新与会话撤销的一致性取舍见[设计方案](./设计方案.md)。
+- 失败操作结果采用固定字段结构化安全事件，管理员成功另写既有平台管理审计。事件载体与字段见[技术契约](./技术契约.md)；部署日志链路的实际保留期限与检索能力在当前仓库不可核验，须在交付时确认记录，不能把待确认的部署事实写成已落实。
+
+## 8. 变更记录
+
+| 日期 | 摘要 | 影响范围 | 原因 |
+| --- | --- | --- | --- |
+| 2026-10-08 | 形成 PRD、设计与技术契约，明确接口和安全事件；保留周期作为交付待确认项 | 全局账号、认证、平台账号管理、Web 与会话 | 为已确认需求建立实施和联调依据，避免把部署状态写成已验证事实 |
+| 2026-09-30 | 确认本人改密与平台管理员重置、密码规则及全端会话撤销，建立待实施需求 | 全局账号、认证、平台账号管理与会话 | 补齐现有账号密码维护能力，并明确凭据与会话的安全边界 |

package/template-vp-monorepo-react-nestjs/.spaces/07.API/344/270/216/351/224/231/350/257/257//346/212/200/346/234/257/345/245/221/347/272/246.md

@@ -0,0 +1,95 @@
+# API 与统一错误技术契约
+
+## 1. 状态和范围
+
+- 状态：当前有效。
+- 适用范围：Server HTTP API。
+- 本契约不规定前端组件如何展示错误，也不把 OpenTelemetry Trace ID 作为当前请求关联标识。
+
+## 2. 成功响应
+
+Server 成功响应直接返回业务正文，不增加通用 `{ code, data, message }` 外壳。
+
+```json
+{
+  "id": "示例资源 ID",
+  "name": "示例名称"
+}
+```
+
+状态码按 HTTP 语义选择；调用方不得依赖成功正文中存在统一 `code` 字段。
+
+## 3. 失败响应
+
+所有可公开的 Server 失败响应统一为：
+
+```ts
+interface ApiErrorDetail {
+  path?: string
+  code: string
+  message: string
+}
+
+interface ApiFailure {
+  code: string
+  message: string
+  details?: ApiErrorDetail[]
+}
+```
+
+示例：
+
+```json
+{
+  "code": "COMMON.VALIDATION_FAILED",
+  "message": "请求参数校验失败",
+  "details": [
+    {
+      "path": "account",
+      "code": "too_small",
+      "message": "账号长度不符合要求"
+    }
+  ]
+}
+```
+
+### 3.1 `details` 语义
+
+- `details` 是通用业务错误详情，不限定为 Zod 校验格式。
+- 每一项必须提供稳定 `code` 和可公开 `message`；`path` 仅在能够定位输入或业务字段时提供。
+- 没有安全、有效详情时省略整个字段，不返回空数组占位。
+- 详情数量、路径、错误码和公开文案必须限制长度并清理控制字符。
+
+### 3.2 安全边界
+
+- 5xx 不返回原始异常、堆栈、SQL、Redis／对象存储错误或内部连接信息。
+- 业务异常只暴露登记过的公开文案；未知异常统一为内部错误。
+- 日志中的 Authorization、Cookie、密码、Token、密钥、连接串和 URL 凭据必须脱敏。
+- 401 是否返回 `WWW-Authenticate: Bearer` 由具体错误定义决定，不能仅凭 HTTP 状态盲目添加。
+
+## 4. 请求关联 ID
+
+- 每个 HTTP 响应通过响应头 `x-request-id` 返回当前请求关联 ID，包括成功和失败响应。
+- 客户端反馈故障时应携带该响应头值，服务端日志使用同一 ID 定位请求。
+- 当前 `x-request-id` 是应用请求 ID，不承诺等同于 OpenTelemetry Trace ID；以后接入链路追踪时可以建立映射，但不得静默改变现有字段语义。
+
+## 5. 实现约束
+
+- 业务错误使用统一错误定义和 `AppException`，不能在各控制器随意返回不同 JSON 形状。
+- DTO／Zod 校验错误转换为 `COMMON.VALIDATION_FAILED`，详情按统一规则规范化。
+- Nest 遗留 `HttpException` 只映射固定公开文案，不直接透传异常消息。
+- shared 只定义可供前后端复用的 `ApiFailure`／`ApiErrorDetail` 类型；Server 负责状态码、日志和安全清洗。
+
+## 6. 验收标准
+
+1. 任一成功接口直接返回业务正文。
+2. 400～599 失败响应均符合 `{ code, message, details? }`。
+3. `details` 可表达校验错误和其他业务错误，不绑定具体校验库。
+4. 成功和失败响应都包含 `x-request-id`。
+5. 未知 5xx 响应不泄露内部异常，服务端日志保留脱敏后的定位信息。
+
+## 7. 变更记录
+
+| 日期 | 摘要 | 影响范围 | 原因 |
+| --- | --- | --- | --- |
+| 2026-09-17 | 从历史讨论和当前实现整理成功正文、统一失败结构、通用 details 与请求 ID 规则 | Server API、shared 类型 | 形成单一可引用契约，避免把前端展示或 Trace ID 混入 Server 错误规范 |

package/template-vp-monorepo-react-nestjs/.spaces/README.md

@@ -0,0 +1,85 @@
+# 项目空间文档索引
+
+首次整理日期：2026-09-17；最后核对日期：2026-10-08。
+
+`.spaces/` 是本项目需求、PRD、设计、技术契约、UI 产物、测试证据与交付记录的唯一正式来源。聊天记录只用于提炼决策，不保存为正文副本；代码实现与文档不一致时，必须在对应文档中标明差异和后续动作。
+
+完整的新增、变更、归档和敏感信息规则见 [文档规范](./文档规范.md)。
+
+## 目录索引
+
+| 目录                                  | 内容                                           | 当前状态                                                                                                                 |
+| ------------------------------------- | ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
+| [01.企业级项目级](./01.企业级项目级/) | 企业、项目、权限、菜单、组织、岗位、成员选择器 | 核心组织边界已确认；企业层级残留必须清理；企业邀请只确认产品入口，现有邀请实现属于待处置偏差；组织迁移与整体验收尚未收口 |
+| [02.上传与文件](./02.上传与文件/)     | 分片上传、文件模型改造、过期上传清理           | 分片上传已有实现教程；文件模型改造和定时清理按各文档状态执行                                                             |
+| [03.任务队列](./03.任务队列/)         | BullMQ 公共队列                                | 公共队列基础能力已实现；具体业务任务另行接入                                                                             |
+| [04.界面与主题](./04.界面与主题/)     | 主题说明、UI 截图、视觉验证证据与工具、前端国际化 | 已归档验证产物；国际化已统一联动 antd、Pro Components 与 Day.js，不等同于业务验收                         |
+| [05.运行维护](./05.运行维护/)         | 平台操作、数据库迁移、备份与恢复工具           | 随当前实现维护；备份文件按敏感数据处理                                                                                   |
+| [06.认证与会话](./06.认证与会话/)     | 登录、终端会话、修改密码、令牌演进与实时撤权边界 | 当前 Redis Session 基线已记录；修改密码实施中，后续令牌演进必须先确认迁移契约                                             |
+| [07.API与错误](./07.API与错误/)       | Server 成功响应、失败响应、请求关联 ID         | 当前有效契约                                                                                                             |
+
+## 主要功能与产物导航
+
+| 主题／功能             | 正式文档                                                                                                                                                                                                       | 配套产物                                                                                                                                                                                                                                                                                                                                                                              |
+| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 企业、项目、权限与菜单 | [需求文档](./01.企业级项目级/权限与菜单/需求文档.md)、[PRD](./01.企业级项目级/权限与菜单/PRD.md)、[技术契约](./01.企业级项目级/权限与菜单/技术契约.md)、[决策记录](./01.企业级项目级/权限与菜单/决策记录.md)   | [前端交接](./01.企业级项目级/权限与菜单/前端交接.md)、[后端测试报告](./01.企业级项目级/权限与菜单/后端测试报告.md)、[联调记录](./01.企业级项目级/权限与菜单/联调记录.md)、[测试报告](./01.企业级项目级/权限与菜单/测试报告.md)、[运行说明](./01.企业级项目级/权限与菜单/运行说明.md)、[UI 截图](./01.企业级项目级/权限与菜单/ui/)、[测试证据](./01.企业级项目级/权限与菜单/测试证据/) |
+| 企业／项目组织架构     | [需求文档](./01.企业级项目级/组织架构/需求文档.md)、[设计方案](./01.企业级项目级/组织架构/设计方案.md)、[技术契约](./01.企业级项目级/组织架构/技术契约.md)、[决策记录](./01.企业级项目级/组织架构/决策记录.md) | [联调记录](./01.企业级项目级/组织架构/联调记录.md)、[测试报告](./01.企业级项目级/组织架构/测试报告.md)                                                                                                                                                                                                                                                                                |
+| 分片上传               | [实施教程](./02.上传与文件/分片上传/实施教程.md)                                                                                                                                                               | 当前上传实现说明                                                                                                                                                                                                                                                                                                                                                                      |
+| 文件模型改造           | [设计方案](./02.上传与文件/上传改造/设计方案.md)                                                                                                                                                               | 待按文档状态实施                                                                                                                                                                                                                                                                                                                                                                      |
+| 过期上传清理           | [设计方案](./02.上传与文件/上传清理/设计方案.md)                                                                                                                                                               | BullMQ 与 MinIO 清理教程及验收清单                                                                                                                                                                                                                                                                                                                                                    |
+| 公共任务队列           | [设计方案](./03.任务队列/公共队列/设计方案.md)                                                                                                                                                                 | BullMQ 公共能力说明                                                                                                                                                                                                                                                                                                                                                                   |
+| 万物梦幻主题           | [验证说明](./04.界面与主题/万物梦幻/验证说明.md)                                                                                                                                                               | [UI 截图](./04.界面与主题/万物梦幻/ui/)、[测试证据](./04.界面与主题/万物梦幻/测试证据/)、[验证工具](./04.界面与主题/万物梦幻/工具/)                                                                                                                                                                                                                                                   |
+| 前端国际化             | [需求文档](./04.界面与主题/国际化/需求文档.md)、[设计方案](./04.界面与主题/国际化/设计方案.md)、[测试报告](./04.界面与主题/国际化/测试报告.md)、[交付记录](./04.界面与主题/国际化/交付记录.md) | 语言切换统一驱动应用词条、antd、Pro Components、Day.js 与 `<html lang>`                                                                                                                                                                                                                                             |
+| 平台运行维护           | [平台操作手册](./05.运行维护/平台操作手册.md)、[数据库迁移指南](./05.运行维护/数据库迁移/操作指南.md)                                                                                                          | [备份与恢复材料](./05.运行维护/数据库迁移/备份/)；其中数据库转储按敏感数据管理                                                                                                                                                                                                                                                                                                        |
+| 认证与会话             | [需求文档](./06.认证与会话/会话管理/需求文档.md)、[技术契约](./06.认证与会话/会话管理/技术契约.md)                                                                                                             | 当前 Session 基线与后续演进边界                                                                                                                                                                                                                                                                                                                                                       |
+| 修改密码               | [需求文档](./06.认证与会话/修改密码/需求文档.md)、[PRD](./06.认证与会话/修改密码/PRD.md)、[设计方案](./06.认证与会话/修改密码/设计方案.md)、[技术契约](./06.认证与会话/修改密码/技术契约.md) | 实施中：本人改密、平台管理员重置及全端会话撤销；保留期限待交付核验 |
+| API 与错误             | [技术契约](./07.API与错误/技术契约.md)                                                                                                                                                                         | 成功响应、失败响应与请求关联 ID                                                                                                                                                                                                                                                                                                                                                       |
+
+## 从 Codex 历史提炼的当前决策
+
+以下结论按 2026-09-17 前本机该项目的 Codex 会话整理，已分别同步到所属正式文档：
+
+1. 平台下企业彼此独立，不建设集团／子企业父子层级；集团、事业群、分公司等层次由单个企业内部的组织单元表达。
+2. 企业与项目分别维护自己的组织树；成员可加入同一作用域的多个组织单元，不设置主归属。
+3. 保留企业岗位和项目岗位，但岗位是作用域内的平面列表，不关联组织单元；不建设项目小组。
+4. 组织单元排序只保存一个非负整数 `sort`。
+5. `account` 全局唯一，姓名不唯一，所有人员关系最终使用稳定 `userId`。
+6. 企业新增成员只确认“直接注册”和“邀请”两个产品入口；邀请对象、账号绑定、载体、有效期、状态、接受／拒绝、撤销／重发、发送渠道和技术协议均待确认。项目只能从所属企业的有效成员中按 `userId` 选择，且候选排除已经加入当前项目的成员。
+7. `GlobalAccountSelect` 只用于平台有权搜索全局账号的场景；企业／项目业务选人使用受作用域和权限保护的成员选择器。
+8. 单项目且没有平台或额外企业管理职责的成员，默认直接进入项目。
+9. 项目流程流转到企业财务、董事抄送等需求合理，但属于后续工作流目标解析和任务授权能力，不纳入当前组织架构交付。
+
+跨轮次决策索引：
+
+- [账号选择、成员接入与权限决策](./01.企业级项目级/权限与菜单/决策记录.md)
+- [企业／项目组织架构决策](./01.企业级项目级/组织架构/决策记录.md)
+
+## 尚未确认的设计
+
+- 权限树、导航菜单、功能开关和独立业务逻辑权限是否彻底解耦，仍属于待确认设计，不能当作已实施事实。
+- 企业邀请的对象范围、是否绑定账号、载体、有效期、状态、接受／拒绝、撤销／重发、发送渠道、DTO、端点、Token、安全、事务、审计和验收标准均待产品确认。
+- 认证令牌是否从当前 Redis Session 迁移为 Access Token + Refresh Token，以及迁移兼容期、存储位置和刷新接口细节，需要在实施前单独确认技术契约。
+
+## 当前实现偏差
+
+- 现有 Schema、Shared、Server、Web、测试和 `0003` 迁移仍残留已明确取消的企业父子层级。完成全链路清理并在隔离环境重验前，不得对当前数据库执行 `0003`，也不得把旧层级方案的测试结果视为现行验收。
+- 现有固定邀请代码、页面、自动化测试和 `0004_company-member-invitations.sql` 先于产品协议确认产生，只能作为待处置的实现偏差；协议确认并同步正式契约前，不得执行该迁移、发布相关功能或把既有测试结果计入产品验收。
+
+## 成员接入状态
+
+- 企业直接注册新账号、项目从所属企业有效成员中按 `userId` 选人是已确认边界，已有自动化与真实数据库集成记录可作为技术回归参考，新增真实浏览器证据仍待补。
+- 企业邀请当前只确认产品入口。现有邀请自动化只证明代码行为曾被实现，不能证明邀请协议已确认，也不能作为现行契约、迁移、发布或验收依据。
+
+## 历史整理边界
+
+- 不把原始聊天、Cookie、Token、密钥、请求头或真实账号资料复制进仓库。
+- 历史会话与当前决策冲突时，以最新明确决定为准，并直接修改原文档的现行正文。
+- 已被新需求影响的联调或测试报告只能标记为历史证据或待重验，不能仅改文案后继续声称通过。
+
+## 变更记录
+
+| 日期       | 摘要                                                                                           | 影响范围                               | 原因                                                                          |
+| ---------- | ---------------------------------------------------------------------------------------------- | -------------------------------------- | ----------------------------------------------------------------------------- |
+| 2026-10-08 | 补充修改密码 PRD、设计和技术契约导航，标明实施中及日志保留待核验 | 认证与会话目录索引 | 在开发前固定正式实施依据并保持状态真实 |
+| 2026-09-30 | 新增修改密码待实施需求导航，同步认证与会话主题状态 | 认证与会话目录索引 | 区分已确认的密码维护需求与当前尚未实现的接口 |
+| 2026-09-18 | 清理原始未完会话正文，记录企业层级实现偏差，并将企业邀请纠偏为“只确认产品入口、具体协议待确认” | 企业／项目正式文档索引、迁移与交付状态 | 现有邀请实现不能反向定义产品协议；消除索引与现行需求、PRD、技术契约之间的冲突 |

package/template-vp-monorepo-react-nestjs/.spaces//346/226/207/346/241/243/350/247/204/350/214/203.md

@@ -0,0 +1,97 @@
+# `.spaces` 文档规范
+
+## 1. 目的和适用范围
+
+本规范适用于项目中的需求、澄清、PRD、设计、技术契约、UI 原型与截图、测试证据、联调记录、交付说明和运行文档。`.spaces/` 是上述内容的唯一正式来源，`artifacts/` 不再作为产物目录使用。
+
+## 2. 目录组织
+
+```text
+.spaces/
+├── README.md
+├── 文档规范.md
+└── <序号>.<业务主题>/
+    └── <功能>/
+        ├── 需求文档.md
+        ├── PRD.md
+        ├── 设计方案.md
+        ├── 技术契约.md
+        ├── 决策记录.md
+        ├── 联调记录.md
+        ├── 测试报告.md
+        ├── ui/
+        ├── 测试证据/
+        └── 工具/
+```
+
+- 一级目录使用 `<两位序号>.<主题>`，序号只用于稳定排序，不表达优先级。
+- 新增、移动、合并或重命名一级主题与主要功能目录时，必须同步更新根目录 `README.md` 的索引、状态和相关决策链接。
+- 一个功能只有一个文件时，可以直接放在主题目录；同一功能出现两个或以上文件或产物时，必须建立功能子目录。
+- 同一功能不得同时散落在多个主题。跨主题只使用相对链接引用，不复制正文。
+- 不建立含义模糊的 `todo/`、`temp/`、`new/`、`final/` 目录。待确认事项写入所属需求或设计文档。
+
+## 3. 文档职责
+
+| 文档 | 负责内容 | 不应包含 |
+| --- | --- | --- |
+| `需求文档.md` | 背景、目标、范围、业务规则、权限边界、数据约束、验收标准、待确认项 | 未确认的接口和数据库细节 |
+| `PRD.md` | 用户故事、页面／流程、验收映射 | 与需求文档冲突的第二套业务规则 |
+| `设计方案.md` | 领域模型、交互、架构取舍、替代方案和边界 | 冒充当前实现的历史设想 |
+| `技术契约.md` | DTO、接口、错误、权限、数据约束、兼容与迁移规则 | 前后端各自维护的重复类型 |
+| `决策记录.md` | 跨轮次重要结论的日期、状态、原因、影响范围和正式文档链接 | 原始聊天全文或另一套需求正文 |
+| `联调记录.md` | 实际联调范围、发现、修复和遗留项 | 未执行却声称通过的结论 |
+| `测试报告.md` | 环境、版本、执行证据、结果、未覆盖风险 | 仅依据代码阅读得出的“已通过” |
+
+文档应尽量引用权威来源。需要摘要时标明“摘要”，并附相对链接。
+
+## 4. 新需求和需求变更
+
+1. 收到新需求、需求澄清或变更时，先定位所属主题和功能；没有目录时先建立目录，再开始实现。
+2. 新需求至少记录目标、范围、业务规则、权限边界、数据约束、验收标准和待确认项。
+3. 需求变更直接修改原文档中的现行结论，并同步所有受影响的 PRD、设计、契约、UI、测试和运行说明。
+4. 原文档维护“变更记录”，至少写日期、摘要、影响范围和决策原因。版本历史交给 Git，不创建 `v2`、`最终版`、`最新版` 等正文副本。
+5. 新结论推翻旧结论时，删除旧的现行表述，或明确标为“已废弃／历史基线”；不得在同一文档中保留两套互相矛盾的当前规则。
+6. 尚未确认或尚未实现的内容必须标注状态。未经用户确认的讨论方向不得写成有效需求。
+
+## 5. 产物归档
+
+- UI 原型、截图和标注图放在所属功能的 `ui/`。
+- 自动化测试结果、JSON 报告和不可读性较强的原始证据放在 `测试证据/`，并由测试报告解释其含义。
+- 为生成或验证产物保留的脚本放在 `工具/`，输出路径必须指向同一功能目录，不得重新生成 `artifacts/`。
+- 运行说明、联调记录和测试报告放在产生它们的功能目录；全局运维文档放在 `05.运行维护/`。
+- 二进制备份、数据库转储等材料即使位于 `.spaces/`，也必须按敏感数据管理，不得默认视为可公开文档。
+
+## 6. 状态和证据
+
+文档开头应明确状态，推荐使用以下值：
+
+- `当前有效`：已确认，且作为当前实现或实施依据。
+- `待实施`：需求或方案已确认，但实现尚未完成。
+- `待确认`：仍有会改变结果的产品或技术选择。
+- `历史基线`：只用于追溯，不能作为当前实现依据。
+- `验证记录`：记录某一时间点和版本的执行结果，不自动覆盖后续变更。
+
+需求变化使既有测试失效时，必须把受影响项目标为“待重验”或“历史证据”。只有重新执行后才能恢复“通过”。
+
+## 7. 从会话和临时资料整理文档
+
+- 只提炼稳定决策、业务规则、设计取舍、接口约束和待确认项，不保存原始聊天流水。
+- 同一主题存在多次讨论时，按最新明确决定覆盖旧结论；无法判断是否确认时写入“待确认事项”。
+- 跨轮次且容易反复影响范围的结论可以维护 `决策记录.md`，但只作为索引；现行规则仍必须落入需求、设计或技术契约。
+- 对话中的示例账号、请求头、Cookie、Token、密钥、连接串和生产数据必须丢弃或脱敏。
+- 已在正式文档存在的内容只更新原文档，不另建“对话总结”副本。
+- 整理完成后检查代码、契约、测试报告和运行说明是否仍引用旧结论。
+
+## 8. 链接、命名和提交检查
+
+- 仓库内 Markdown 使用相对链接；移动文件后同步修复全部引用。
+- `.spaces/README.md` 维护主题与主要功能的导航；目录结构变化后必须同步更新，避免出现只有文件归档、没有入口索引的孤立产物。
+- 文件名使用稳定业务含义，不包含日期、人员名或阶段后缀。
+- 提交前至少检查：旧路径、失效链接、重复正文、`artifacts/` 残留、敏感信息、过时状态、未同步契约和测试结论。
+- 需求或契约涉及代码实现时，按项目 `AGENTS.md` 的按需规则继续读取代码设计和共享代码规则。
+
+## 9. 变更记录
+
+| 日期 | 摘要 | 影响范围 | 原因 |
+| --- | --- | --- | --- |
+| 2026-09-17 | 建立 `.spaces` 唯一来源、原文档变更、功能归档与产物目录规范 | 全项目需求、设计、契约和交付资料 | 统一散落的 `.spaces`、`artifacts` 与 Codex 会话结论，避免重复和口径漂移 |

package/template-vp-monorepo-react-nestjs/AGENTS.md

@@ -1,6 +1,17 @@
+## 方法注释
+
+- 前端、后端及共享代码中的每个函数或方法都必须编写 JSDoc（`/** ... */`），只有通过名称和实现一眼就能看出用途的简单方法可以省略。
+- 注释应说明实际用途；按需补充关键参数、返回值、异常和副作用，避免只重复方法名或 TypeScript 类型。修改方法行为时同步更新注释。
+
 ## 目录说明
 
 - 修改文件前，须从文件所在目录逐级向上查找并阅读相关的 `AGENTS.md`（如存在），并遵循其中的说明。
+- 当一个目录下存在多个同级文件，其中两个或以上文件属于同一功能时，必须建立对应的功能子目录，将这些文件统一放入该目录，避免不同功能的文件平铺混放。
+
+## 需求与产物归档
+
+- 当出现新需求、需求澄清或需求变更时，必须先在 `.spaces/` 中定位或创建对应的主题与功能目录，更新现行需求文档并同步受影响的设计、PRD、契约、UI、测试和交付说明，再开始实现；变更直接修改原文档并记录变更，不创建 `v2`、`final`、`最新版` 等平行正文。
+- `.spaces/` 是需求与项目产物的唯一正式来源。UI 截图放入对应功能的 `ui/`，测试证据和工具按功能分类归档；不得再使用或重新生成 `artifacts/` 目录。
 
 ## 按需规则
 
@@ -10,3 +21,4 @@
 | -------------------------------------------------------------- | ------------------------------------- |
 | 新增、修改或重构前后端代码                                     | [代码设计](.agents/rules/代码设计.md) |
 | 定义或调整前后端接口类型、返回类型，或新增、修改、抽取公用方法 | [共享代码](.agents/rules/共享代码.md) |
+| 出现任何新需求、需求澄清或需求变更，或新增／更新需求、设计、PRD、契约、UI、测试与交付产物 | [需求与设计文档](.agents/rules/需求与设计文档.md) |