create-bubbles 0.1.26 → 0.1.28

package/template-vp-monorepo-react-nestjs/.spaces/01./344/274/201/344/270/232/347/272/247/351/241/271/347/233/256/347/272/247//346/235/203/351/231/220/344/270/216/350/217/234/345/215/225//346/212/200/346/234/257/345/245/221/347/272/246.md

@@ -0,0 +1,580 @@
+# 企业、项目与菜单权限实施契约
+
+状态：当前实现契约，2026-09-18 已统一管理员选择、企业成员直接注册及项目成员候选边界。企业邀请只确认产品入口，具体协议待确认，不属于本契约的现行实现范围。需求来源为[需求文档](./需求文档.md)；前后端共同遵循本文，发现缺失经统一更新后同步，不能各自发明字段或端点。
+
+## 1. 现有工程约定
+
+- 本期实现 `apps/web`（React）与 `apps/server`（NestJS），不改 `apps/web-vue`；保留既有上传的 `ownerId` 权限和 Cookie / Storage 职责。
+- 共享包已有源码目录为 `packages/shared/src/types`、`packages/shared/src/utils`，已有发布入口为 `shared/types`、`shared/utils`。需求中的共享目录按此现有结构落地，不另建重复目录。公共请求、返回、分页、权限目录字段均从共享包导出；服务端 Zod DTO 校验这些类型，不向前端泄漏 Drizzle 实体。
+- 以下路径不含环境中的 API 代理前缀。成功直接返回下述 JSON，不增加 `{code,data}` 包装；失败沿用 `ApiFailure = { code: string; message: string; details?: {path?: string; code: string; message: string}[] }`。请求追踪使用 `x-request-id`，审计使用同一个服务端 `request.id`。
+- 查询成功 200；创建企业、项目、成员、自定义角色、菜单节点成功 201；其他写操作成功 200。删除返回 `{deleted: true}`，不返回 204。已经不存在的普通删除目标返回 404；清理维护操作另有幂等约定。
+- 所有新管理端点声明访问策略，默认拒绝未声明策略的端点。现有公开根页、注册、登录、幂等退出保留 `@Public()`；`/auth/me` 明确为已登录策略；上传明确为已登录且 owner 策略。测试 DB / Redis 模块移出默认 AppModule，不能以“兼容旧接口”为由继续暴露。
+- 继续使用现有 alova 实例、页面旁 `api.ts`、React Router middleware、现有弹窗 `show/hide` 规范，不恢复已删除的 auth Provider / Guard 目录。Web 文件遵守其 AGENTS 与按需规则。
+
+## 2. 基础类型与字段
+
+```ts
+type ScopeType = 'platform' | 'company' | 'project'
+type AccessScope =
+  | { type: 'platform' }
+  | { type: 'company'; companyId: string }
+  | { type: 'project'; companyId: string; projectId: string }
+type EntityStatus = 'active' | 'disabled'
+type AccountStatus = 'active' | 'locked' | 'disabled' // 沿用 users.status
+type BuiltinRole = 'administrator' | 'member' | null
+interface PageQuery {
+  page?: number
+  pageSize?: number
+  query?: string
+}
+interface PageResult<T> {
+  items: T[]
+  total: number
+  page: number
+  pageSize: number
+}
+interface VersionRequest {
+  expectedVersion: number
+}
+interface StatusRequest extends VersionRequest {
+  status: EntityStatus
+}
+interface DeleteResult {
+  deleted: true
+}
+interface UserSummary {
+  id: string
+  account: string
+  name: string
+}
+interface AccountRecord extends UserSummary {
+  status: AccountStatus
+  createdAt: string
+  updatedAt: string
+  platformRoleIds: string[]
+}
+interface CompanyRecord {
+  id: string
+  name: string
+  code: string
+  description: string
+  status: EntityStatus
+  version: number
+  createdAt: string
+  updatedAt: string
+}
+interface ProjectRecord extends CompanyRecord {
+  companyId: string
+}
+interface AdministratorSummary extends UserSummary {
+  accountStatus: AccountStatus
+  memberStatus: EntityStatus
+  effective: boolean
+}
+interface CompanyDetail extends CompanyRecord {
+  administrators: AdministratorSummary[]
+}
+interface ProjectDetail extends ProjectRecord {
+  administrators: AdministratorSummary[]
+}
+interface MemberRecord {
+  id: string
+  userId: string
+  account: string
+  name: string
+  status: EntityStatus
+  accountStatus: AccountStatus
+  roleIds: string[]
+  roleNames: string[]
+  version: number
+  createdAt: string
+  updatedAt: string
+}
+interface RoleRecord {
+  id: string
+  scope: AccessScope
+  name: string
+  description: string
+  builtin: BuiltinRole
+  permissionKeys: string[]
+  version: number
+  memberCount: number
+  assignable: boolean
+  createdAt: string
+  updatedAt: string
+}
+```
+
+- 所有实体 ID 使用 UUID 字符串；`permissionKey`、`routeKey` 使用代码目录中的稳定字符串。日期均输出 ISO 8601 UTC 字符串。
+- `page` 默认 1，正整数；`pageSize` 默认 20，范围 1–100；超界返回 400，不静默改变用户值。`query` trim 后最多 100 字，空串等同不筛选。列表按 `createdAt DESC, id DESC` 稳定排序；菜单按 `sort ASC, id ASC`。搜索匹配名称／编码或名称／账号，不将 `%`、`_` 当用户输入的通配符。
+- 企业／项目 `name` trim 后 2–100 字；`code` trim 后 2–32 字，`^[A-Za-z0-9_-]+$`，规范化为小写。企业编码全平台唯一，项目编码在企业内唯一。`description` trim 后 0–500 字，省略创建时写空串；PATCH 省略字段表示不改。
+- 角色名称 2–100 字，同一作用域唯一；描述 0–500 字。内置角色名称由系统维护。首期自定义角色不另增启停状态，通过修改权限、撤销分配或删除未被使用的角色管理。
+- `status` 表示对象自身状态，不因父级停用而批量改写。新建企业、项目、成员、自定义角色默认可用。版本从 1 起，相关修改后递增；过期提交 409。账号状态操作沿用 users 表，没有请求版本字段。
+- 所有请求 DTO 拒绝未知字段。数组不允许重复项；角色／权限数组最多 500 项。所有返回均显式选择字段，不返回密码散列、token 或数据库内部对象。
+- 账号沿用 `normalizeAccount()`，完整账号 4–32 位字母、数字、下划线；注册 `name` 2–100，密码 8–128。注册不自动登录，也不加入任何工作空间。
+
+## 3. 工作空间与上下文
+
+```ts
+interface WorkspaceEntry {
+  scope: AccessScope
+  name: string
+  companyName?: string
+  administrator: ScopeType | null
+}
+interface WorkspacesResult {
+  user: UserSummary
+  workspaces: WorkspaceEntry[]
+}
+type MenuNodeType = 'directory' | 'page' | 'operation'
+interface MenuNode {
+  id: string
+  scopeType: ScopeType
+  parentId: string | null
+  type: MenuNodeType
+  name: string
+  icon: string
+  sort: number
+  hidden: boolean
+  status: EntityStatus
+  routeKey: string | null
+  permissionKey: string | null
+  protected: boolean
+  children: MenuNode[]
+}
+interface AccessContext {
+  user: UserSummary
+  scope: AccessScope
+  administrator: ScopeType | null
+  permissionKeys: string[]
+  menus: MenuNode[]
+  menuVersion: number
+  catalogVersion: string
+}
+interface MenuTreeResult {
+  scopeType: ScopeType
+  version: number
+  items: MenuNode[]
+}
+interface PermissionDefinition {
+  key: string
+  scopeType: ScopeType
+  kind: 'page' | 'operation'
+  title: string
+  routeKey: string
+  pagePermissionKey: string | null
+  adminOnly: boolean
+  deprecated: boolean
+}
+interface PermissionTreeResult {
+  catalogVersion: string
+  items: MenuNode[]
+  permissions: PermissionDefinition[]
+  grantablePermissionKeys: string[]
+}
+```
+
+| 方法与路径                                             | 返回               | 访问策略                                              |
+| ------------------------------------------------------ | ------------------ | ----------------------------------------------------- |
+| GET `/workspaces`                                      | `WorkspacesResult` | 有效登录用户；只列可进入的 active 范围                |
+| GET `/platform/access`                                 | `AccessContext`    | 有至少一个平台角色的有效用户                          |
+| GET `/companies/:companyId/access`                     | `AccessContext`    | 企业 active、账号及企业成员有效                       |
+| GET `/companies/:companyId/projects/:projectId/access` | `AccessContext`    | 所属企业及项目 active，且有效项目成员或所属企业管理员 |
+
+企业管理员不需要 `project_members` 记录即可列出并进入本企业所有 active 项目；在项目上下文中 `administrator: 'company'`。显式项目成员停用不屏蔽企业管理员能力。`/workspaces` 不接受任意用户 ID；无企业的新账号返回空列表，前端显示等待添加；拥有平台角色则仍显示平台空间。
+
+`AccessContext.permissionKeys` 是同作用域角色并集再扣除未注册、已下线及菜单自身／祖先停用的权限。按钮还须满足所属页面访问权限。内置管理员自动获得当前作用域的全部已注册功能权限，但仍受功能状态约束；项目上下文中的企业管理员按项目内置管理员权限计算。目录只用于导航。
+
+`menus` 只返回授权且可见的导航树；隐藏页及其导航子项不出现，但其有效权限仍出现在 `permissionKeys`，支持直达页面。按钮节点可包含在树中供消费，但布局不渲染为导航。`/access` 允许返回空树，不能因为用户没有某个页面权限就拒绝获取自己的上下文。
+
+同范围无权限或已停用返回 403；不存在／非成员企业、项目关系不匹配、非企业管理员且不是该项目成员，统一返回 404。无效账号与失效登录返回 401。资源 ID 的内部查询必须同时约束作用域；不能先加载其他租户完整资源再只做前端过滤。
+
+## 4. 页面、权限和 routeKey 目录
+
+页面权限固定为 `${routeKey}.read`。下表操作列为完整权限的最后一段，例如 `company.members.add`；每个操作绑定本行页面，必须同时拥有页面 `.read`。标记 `*` 的操作额外要求内置管理员身份，不能进入自定义角色授权集合。所有未标记操作可被自定义角色授予，但不能超过操作者有权授予的权限。
+
+| scope    | routeKey             | 前端路径                                            | 页面名称     | 操作后缀                                    |
+| -------- | -------------------- | --------------------------------------------------- | ------------ | ------------------------------------------- |
+| platform | `platform.home`      | `/platform`                                         | 平台工作台   | —                                           |
+| platform | `platform.companies` | `/platform/companies`                               | 企业管理     | `create*`, `status`, `administrator*`       |
+| platform | `platform.accounts`  | `/platform/accounts`                                | 全局账号     | `status`, `roles`, `reset-password*`        |
+| platform | `platform.roles`     | `/platform/roles`                                   | 平台角色     | `create`, `update`, `delete`, `permissions` |
+| platform | `platform.menus`     | `/platform/menus`                                   | 菜单管理     | `create`, `update`, `delete`, `cleanup*`    |
+| platform | `platform.audit`     | `/platform/audit`                                   | 平台操作日志 | —                                           |
+| company  | `company.home`       | `/companies/:companyId`                             | 企业工作台   | —                                           |
+| company  | `company.profile`    | `/companies/:companyId/profile`                     | 企业资料     | `update`                                    |
+| company  | `company.members`    | `/companies/:companyId/members`                     | 企业成员     | `add`, `status`, `remove`, `roles`          |
+| company  | `company.roles`      | `/companies/:companyId/roles`                       | 企业角色     | `create`, `update`, `delete`, `permissions` |
+| company  | `company.projects`   | `/companies/:companyId/projects`                    | 项目管理     | `create*`, `status`, `administrator*`       |
+| company  | `company.audit`      | `/companies/:companyId/audit`                       | 企业操作日志 | —                                           |
+| project  | `project.home`       | `/companies/:companyId/projects/:projectId`         | 项目工作台   | —                                           |
+| project  | `project.profile`    | `/companies/:companyId/projects/:projectId/profile` | 项目资料     | `update`                                    |
+| project  | `project.members`    | `/companies/:companyId/projects/:projectId/members` | 项目成员     | `add`, `status`, `remove`, `roles`          |
+| project  | `project.roles`      | `/companies/:companyId/projects/:projectId/roles`   | 项目角色     | `create`, `update`, `delete`, `permissions` |
+| project  | `project.audit`      | `/companies/:companyId/projects/:projectId/audit`   | 项目操作日志 | —                                           |
+
+`platform.companies.create` 涉及指定首位企业管理员，故仅平台管理员可用。`company.projects.create/administrator` 仅所属企业内置管理员可用。`platform.menus.cleanup` 仅内置平台管理员可用。企业内和项目内授予／撤销管理员角色时，在成员角色操作权限之外再验证对应管理员委派身份。
+
+普通成员内置角色：平台仅 `platform.home.read`；企业为 `company.home.read` 与 `company.projects.read`（仅列本人加入项目）；项目仅 `project.home.read`。新成员默认分配所在范围内置 member 角色，授予首位管理员同时分配 administrator 角色。普通 member 角色及管理员角色定义均不可人工编辑、停用、删除；可以在合法委派和最后管理员规则下修改用户的角色分配。自定义角色空权限合法。
+
+初始三棵菜单树以页面为根节点，operation 为页面子节点；平台可后续插入 directory。首期不需要虚构未实现的目录、按钮或页面。`icon` 保存 `apps/web/src/assets/svg/` 下相对文件名去掉 `.svg` 后的稳定 key，允许使用 `/` 表示子目录，例如 `navigation/dashboard`；空串或当前前端无法解析的 key 使用 `menu-item` 缺省图标。服务端只接受由小写字母、数字和连字符组成的路径段，拒绝路径穿越、SVG/HTML 内容和远程 URL。可选图标由 Web 在构建时自动发现，不由服务端维护第二份文件白名单。
+
+## 5. 企业、账号、项目端点
+
+```ts
+interface CreateCompanyRequest {
+  name: string
+  code: string
+  description?: string
+  administratorUserId: string
+}
+interface CreateProjectRequest {
+  name: string
+  code: string
+  description?: string
+  administratorUserId: string
+  organizationInitialization: ProjectOrganizationInitialization
+}
+interface UpdateProfileRequest extends VersionRequest {
+  name?: string
+  code?: string
+  description?: string
+}
+interface SetAdministratorRequest {
+  administratorUserId: string
+  replaceUserId?: string
+}
+interface SetAdministratorResult {
+  administrator: AdministratorSummary
+  replacedUserId: string | null
+}
+interface AccountStatusRequest {
+  status: 'active' | 'disabled'
+}
+interface AssignPlatformRolesRequest {
+  roleIds: string[]
+}
+```
+
+企业和项目搜索支持 `PageQuery & {status?: EntityStatus}`。账号搜索支持 `PageQuery & {status?: AccountStatus}`。资料 PATCH 至少提供一个待修改字段。
+
+| 方法与路径                                                     | 请求 / 返回                                                 | 权限与边界                                                                                                       |
+| -------------------------------------------------------------- | ----------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
+| GET `/platform/companies`                                      | 查询 → `PageResult<CompanyRecord>`                          | `platform.companies.read`，含停用企业                                                                            |
+| GET `/platform/companies/:companyId`                           | → `CompanyDetail`                                           | `platform.companies.read`，只提供平台管理资料                                                                    |
+| POST `/platform/companies`                                     | `CreateCompanyRequest` → `CompanyDetail`                    | `platform.companies.create` + 平台管理员                                                                         |
+| PATCH `/platform/companies/:companyId/status`                  | `StatusRequest` → `CompanyRecord`                           | `platform.companies.status`；恢复检查有效管理员                                                                  |
+| POST `/platform/companies/:companyId/administrator`            | `SetAdministratorRequest` → `SetAdministratorResult`        | `platform.companies.administrator` + 平台管理员；目标企业停用仍可执行                                            |
+| GET `/platform/accounts`                                       | 查询 → `PageResult<AccountRecord>`                          | `platform.accounts.read`                                                                                         |
+| PATCH `/platform/accounts/:userId/status`                      | `AccountStatusRequest` → `AccountRecord`                    | `platform.accounts.status`；禁用最后企业管理员必须是平台内置管理员，最后平台管理员不可禁用                       |
+| PUT `/platform/accounts/:userId/roles`                         | `AssignPlatformRolesRequest` → `AccountRecord`              | `platform.accounts.roles`；全量替换该用户平台角色，不触碰企业／项目角色                                          |
+| POST `/platform/accounts/:userId/reset-password`               | `ResetAccountPasswordRequest` → `ResetAccountPasswordResult` | `platform.accounts.reset-password` + 平台内置管理员；只能重置他人，成功撤销目标全部终端会话；详见[修改密码技术契约](../../06.认证与会话/修改密码/技术契约.md) |
+| GET `/companies/:companyId`                                    | → `CompanyDetail`                                           | `company.profile.read`                                                                                           |
+| PATCH `/companies/:companyId`                                  | `UpdateProfileRequest` → `CompanyRecord`                    | `company.profile.update`                                                                                         |
+| GET `/companies/:companyId/projects`                           | 查询 → `PageResult<ProjectRecord>`                          | `company.projects.read`；企业管理员所有项目，其他成员仅本人显式加入的项目，允许看到这些项目的停用状态            |
+| POST `/companies/:companyId/projects`                          | `CreateProjectRequest` → `ProjectDetail`                    | `company.projects.create` + 本企业内置管理员                                                                     |
+| PATCH `/companies/:companyId/projects/:projectId/status`       | `StatusRequest` → `ProjectRecord`                           | **按企业作用域** `company.projects.status`；普通企业成员只可操作本人已加入项目；项目本身停用不阻断此上级恢复接口 |
+| GET `/companies/:companyId/projects/:projectId/administrators` | → `ProjectAdministratorsResult`（`AdministratorSummary[]`） | **按企业作用域** `company.projects.administrator` + 企业内置管理员；目标项目停用仍可读取                         |
+| POST `/companies/:companyId/projects/:projectId/administrator` | `SetAdministratorRequest` → `SetAdministratorResult`        | **按企业作用域** `company.projects.administrator` + 企业管理员；允许对停用项目补任                               |
+| GET `/companies/:companyId/projects/:projectId`                | → `ProjectDetail`                                           | `project.profile.read`                                                                                           |
+| PATCH `/companies/:companyId/projects/:projectId`              | `UpdateProfileRequest` → `ProjectRecord`                    | `project.profile.update`                                                                                         |
+
+企业创建事务：按 `administratorUserId` 校验有效管理员账号 → 建企业和该范围内置角色 → 建立企业成员及 member / administrator 分配 → 审计 → 提交。项目创建同理，指定用户必须已经是有效企业成员；企业管理员创建者不强制生成项目成员记录。管理员选择器与组织初始化的详细约束见[组织架构技术契约](../组织架构/技术契约.md)。
+
+上级项目管理员列表仅列具有该项目**显式 administrator 角色**的账号，包含账号或项目成员已经停用的旧任，供补任／更换选择；`memberStatus` 是其项目成员自身状态，`effective` 同时考虑账号、企业成员及项目成员状态。隐式企业管理员不列为可替换项目管理员，企业管理能力不依赖项目角色。该只读维护接口不授予普通项目内部访问。
+
+设置管理员不传 `replaceUserId` 表示补充管理员，已具备身份时幂等；传入表示授予新任并撤销指定旧任的管理员角色。替换对象必须是该范围实际管理员，不得替换自己为自己。新任是有效账号；企业补任可以新增／启用企业成员，项目补任必须有效企业成员并新增／启用项目成员。已有其他角色不变；所有变化和审计在同一事务。此类接口不会启用企业或项目本身。全局账号禁用只改账号状态，不撤销任何角色。
+
+平台账号状态入口不是企业内部业务访问通行证。全局账号原 `locked` 仅保留读取兼容，界面提供启用／停用，平台可显式将其设置为 active 或 disabled。
+
+## 6. 成员与角色端点
+
+下面 `B` 取企业路径 `/companies/:companyId` 或项目路径 `/companies/:companyId/projects/:projectId`；`S` 取 `company` 或 `project`。角色端点还支持 `B=/platform`、`S=platform`。作用域从已验证 URL 推导，请求不能另传 `companyId/projectId/scope` 改变归属。
+
+```ts
+interface RegisterCompanyMemberRequest {
+  name: string
+  account: string
+  password: string
+}
+interface AddProjectMemberRequest {
+  userId: string
+}
+interface AssignMemberRolesRequest extends VersionRequest {
+  roleIds: string[]
+}
+interface CreateRoleRequest {
+  name: string
+  description?: string
+  permissionKeys?: string[]
+}
+interface UpdateRoleRequest extends VersionRequest {
+  name?: string
+  description?: string
+}
+interface SetRolePermissionsRequest extends VersionRequest {
+  permissionKeys: string[]
+}
+```
+
+| 方法与路径                                               | 请求 / 返回                                                        | 所需权限与边界                                                                                 |
+| -------------------------------------------------------- | ------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------- |
+| GET `B/members`                                          | `PageQuery & {status?: EntityStatus}` → `PageResult<MemberRecord>` | `S.members.read`                                                                               |
+| POST `/companies/:companyId/members`                     | `RegisterCompanyMemberRequest` → `MemberRecord`                    | `company.members.add`；直接创建全局账号并加入当前企业，不接收既有 `userId`                     |
+| POST `/companies/:companyId/projects/:projectId/members` | `AddProjectMemberRequest` → `MemberRecord`                         | `project.members.add`；只接收所属企业有效成员的稳定 `userId`                                   |
+| PATCH `B/members/:memberId/status`                       | `StatusRequest` → `MemberRecord`                                   | `S.members.status`                                                                             |
+| DELETE `B/members/:memberId?expectedVersion=n`           | → `DeleteResult`                                                   | `S.members.remove`                                                                             |
+| PUT `B/members/:memberId/roles`                          | `AssignMemberRolesRequest` → `MemberRecord`                        | `S.members.roles`；全量替换当前范围角色                                                        |
+| GET `B/roles`                                            | `PageQuery` → `PageResult<RoleRecord>`                             | `S.roles.read`                                                                                 |
+| GET `B/roles/:roleId`                                    | → `RoleRecord`                                                     | `S.roles.read`                                                                                 |
+| POST `B/roles`                                           | `CreateRoleRequest` → `RoleRecord`                                 | `S.roles.create`                                                                               |
+| PATCH `B/roles/:roleId`                                  | `UpdateRoleRequest` → `RoleRecord`                                 | `S.roles.update`                                                                               |
+| PUT `B/roles/:roleId/permissions`                        | `SetRolePermissionsRequest` → `RoleRecord`                         | `S.roles.permissions`                                                                          |
+| DELETE `B/roles/:roleId?expectedVersion=n`               | → `DeleteResult`                                                   | `S.roles.delete`；只能删除未被分配的自定义角色                                                 |
+| GET `B/permissions`                                      | → `PermissionTreeResult`                                           | `S.roles.read` 或 `S.members.roles`；平台为 `platform.roles.read` 或 `platform.accounts.roles` |
+
+成员分配角色弹窗需要角色选项，因此 GET `B/roles` 也允许持有 `S.members.roles`（平台 `platform.accounts.roles`）的用户读取当前范围角色；这不授予编辑角色权限。GET `B/permissions` 只展示当前作用域功能，不返回其他企业/项目授权。
+
+企业直接注册在同一事务中创建全局账号、当前企业成员关系和默认 member 角色；账号冲突或任一步失败不得留下部分数据。密码只参与散列写入，不能进入审计摘要、日志或响应。
+
+企业邀请只确认是新增企业成员的另一条产品入口。邀请对象、是否绑定账号、载体、有效期、状态、接受／拒绝、撤销／重发、发送渠道、DTO、端点、Token、安全、事务、审计和验收标准均待产品确认；确认前不得从现有代码、页面、迁移或测试反向补写本契约，也不得把它们计入现行端点、数据模型或交付范围。
+
+项目添加成员通过组织成员候选接口的 `purpose=addProjectMember` 查询，只返回当前项目所属企业中有效且尚未加入该项目的成员；前端保存并提交 `userId`。候选查询不要求项目管理员取得通用企业成员列表权限。写接口在事务内重新校验账号、企业、企业成员状态和当前项目重复关系，跨企业、停用或已存在关系返回相应业务错误，不能信任客户端曾经看到的候选结果。停用的既有项目成员应走启用而非重复新增。
+
+给用户新增一个角色时：角色作用域须一致，操作者可授予该角色的当前权限；普通角色不得携带管理员专属能力；内置 administrator 的分配与撤销必须验证委派者身份。保留已有未修改的角色不被误判成新增授予。内置 member 可按成员管理权限分配。
+
+修改自定义角色权限：新增权限必须属于 `grantablePermissionKeys`，不得新授予废弃项；已有废弃引用可原样保留，不通过种子或一次普通保存隐式丢失。授予 operation 必须同时包含其页面 read，否则返回 400；取消 page 时服务端同步从最终集合删除所属 operation。目录不写入 `role_permissions`。前端全选／半选仅是这份集合的展示。
+
+普通成员管理不能绕过最后管理员保护。移除企业成员在一个事务中删除其企业角色、全部下属项目角色／成员、最后企业成员记录；重新添加只获得默认 member，不还原已删除角色。停用只改当前关系状态，角色与子关系保留。
+
+## 7. 菜单管理与发布兼容
+
+```ts
+interface CreateMenuRequest {
+  expectedVersion: number
+  parentId: string | null
+  type: MenuNodeType
+  name: string
+  icon?: string
+  sort?: number
+  hidden?: boolean
+  status?: EntityStatus
+  routeKey?: string
+  permissionKey?: string
+}
+interface UpdateMenuRequest extends VersionRequest {
+  parentId?: string | null
+  name?: string
+  icon?: string
+  sort?: number
+  hidden?: boolean
+  status?: EntityStatus
+}
+interface FunctionCatalogResult {
+  catalogVersion: string
+  items: PermissionDefinition[]
+}
+```
+
+| 方法与路径                                         | 请求 / 返回                            | 权限                    |
+| -------------------------------------------------- | -------------------------------------- | ----------------------- |
+| GET `/platform/function-catalog?scopeType=S`       | → `FunctionCatalogResult`              | `platform.menus.read`   |
+| GET `/platform/menus?scopeType=S`                  | → `MenuTreeResult`                     | `platform.menus.read`   |
+| POST `/platform/menus?scopeType=S`                 | `CreateMenuRequest` → `MenuTreeResult` | `platform.menus.create` |
+| PATCH `/platform/menus/:menuId`                    | `UpdateMenuRequest` → `MenuTreeResult` | `platform.menus.update` |
+| DELETE `/platform/menus/:menuId?expectedVersion=n` | → `MenuTreeResult`                     | `platform.menus.delete` |
+
+版本是该 `scopeType` 整棵树的版本。菜单名称 1–100，icon 最多 64，必须为空串或匹配 `^[a-z0-9]+(?:-[a-z0-9]+)*(?:/[a-z0-9]+(?:-[a-z0-9]+)*)*$`；sort 是 0–100000 整数。新增 page 只传已注册 `routeKey`，permissionKey 由目录推导；operation 只传已注册 `permissionKey`，其 routeKey 和所属 page read 由目录推导；directory 二者均不传。创建后绑定和节点 type 不可通过 PATCH 改写，要换功能须通过合法的新建／移除处理，避免将已有授权悄悄变成另一功能。
+
+Web 使用 `import.meta.glob('/src/assets/svg/**/*.svg', { eager: true, query: '?react', import: 'default' })` 形成唯一图标注册表。图标选择器、菜单管理列表和导航必须消费同一注册表；SVG 组件统一通过 `SvgIcon` 渲染。单色菜单 SVG 使用 `currentColor`，源文件宽高为 `1em`，由外部字号控制尺寸。既有多色资源可以进入选择器并保留自身颜色。
+
+发布本变更时，数据迁移把旧 Ant Design 图标名映射为语义等价的 SVG key，并按 `routeKey` 为当前空图标页面补齐默认值；未知的合法自定义 key 不覆盖。种子只为新建页面菜单写入功能目录的默认图标，不覆盖迁移后的现有菜单配置。迁移更新受影响作用域的菜单版本。不同 Web 版本暂时不能识别新 key 时只能回退本地图标，不能修改服务端菜单或授权。
+
+directory 可包含 directory/page；page 只包含目录定义中属于它的 operation；operation 无子节点。只允许同 scope 树内合法移动，禁止循环、重复 page 绑定、重复 operation 绑定。停用祖先使后代权限全部不可用，恢复祖先不改后代自身状态；隐藏不撤权。页面移动不改变 operation 的固定所属页面。
+
+普通删除不能删除有子节点、被角色授权引用或受保护的节点。保护 `platform.companies`、`platform.accounts`、`platform.roles`、`platform.menus` 页面及其恢复／委派／启用／维护必需操作，保护其祖先：不得停用、隐藏、删除或移动到会失效的位置。首期可以保护上述四个页面的全部 operation，以保证规则清楚且容易验证。
+
+旧 Web 遇到未知 routeKey：过滤页面和全部 operation，然后移除空目录；直接访问未知路由 404。服务端权限和菜单不随旧前端过滤而变化。用户真正加载新前端代码并重新取得 `/access` 后才出现新页面。既有示例页面保留原有开发示例用途，不混入这三棵生产权限菜单，也不能借示例接口绕过新管理接口。
+
+## 8. 废弃权限清理与最小部署证明
+
+```ts
+interface CleanupPreviewItem {
+  permissionKey: string
+  title: string
+  menuIds: string[]
+  roleCount: number
+  blockedReasons: string[]
+}
+interface CleanupPreview {
+  catalogVersion: string
+  deploymentId: string | null
+  proofDigest: string | null
+  eligible: boolean
+  blockedReasons: string[]
+  items: CleanupPreviewItem[]
+  totals: { permissions: number; menus: number; roleAssignments: number }
+}
+interface CleanupRequest {
+  permissionKeys: string[]
+  proofDigest: string
+}
+interface CleanupResult {
+  removedPermissionKeys: string[]
+  alreadyCleanedPermissionKeys: string[]
+  removedMenuCount: number
+  removedRoleAssignmentCount: number
+}
+```
+
+| 方法与路径                                  | 请求 / 返回                        | 权限                                      |
+| ------------------------------------------- | ---------------------------------- | ----------------------------------------- |
+| GET `/platform/permissions/cleanup-preview` | → `CleanupPreview`                 | `platform.menus.cleanup` + 平台内置管理员 |
+| POST `/platform/permissions/cleanup`        | `CleanupRequest` → `CleanupResult` | 同上；所有候选重新检查，不信任预览结果    |
+
+系统功能目录保留明确的废弃定义（包含 `deprecated: true`），不会通过“本实例没有注册该 key”推断废弃。后端不再使用目标权限、目标功能已下线（对应菜单及有效入口不能访问），并满足部署证明后才可清理。当前第一版没有废弃功能时，预览返回空 items，不能伪造一批业务功能作为演示数据。
+
+首期不引入部署平台或服务发现系统，采用**由运维发布流程提供的受控部署证明文件**。服务端配置 `ACCESS_DEPLOYMENT_PROOF_FILE` 指向只读 JSON；文件不由普通 API 上传、修改，不接受客户端自报“全部升级完成”。它必须来自本系统实际部署清单，覆盖全部对外服务实例正在运行的版本；执行该文件生成／更新的人负责从实际部署环境核对清单，不能由当前进程自行猜测。
+
+```ts
+interface DeploymentProof {
+  deploymentId: string // 本次完成部署的唯一标识
+  completed: true
+  verifiedAt: string
+  expiresAt: string // 最长有效窗口 24 小时
+  serviceVersions: {
+    version: string
+    instanceIds: string[] // 此版本全部在用实例，至少一个
+    requiredPermissionKeys: string[] // 此版本发布产物中的完整权限依赖清单
+  }[]
+}
+```
+
+每个服务构建提供 `ACCESS_RELEASE_VERSION` 和相应权限依赖清单；证明中的版本不能重复、实例 ID 不能跨版本重复，执行清理的当前版本必须在清单中且依赖清单与本构建一致。未知／不完整依赖清单、未提供证明、未完成部署、过期、目标 key 仍在任一在用版本依赖中均拒绝清理。运维切换实例／回滚前必须撤销旧证明，部署完成重新生成；不能只改客户端预览。此约定是首期明确的运维边界，不能声称文件本身自动发现了实际实例。
+
+`proofDigest` 是服务端对验证后证明内容计算的 SHA-256，只用于防止预览与执行用到不同清单，不是客户端签名或可信来源。预览在无证明时仍可列出明确废弃项及阻断原因，`eligible=false`；无候选时不能执行空请求。执行时在管理锁内重新读文件、验证有效性与 digest、核对所有候选及当前角色/菜单引用。
+
+有有效子节点、受保护入口、活动功能或不满足部署条件时，整个请求失败，不部分删除。通过时按角色引用 → 可删除的菜单节点/绑定 → 权限记录顺序在同一事务清理，写入 `permission_cleanup_tombstones`（permissionKey 唯一）并记录审计、递增涉及角色与菜单版本。重复请求中已在 tombstone 的 key 计入 `alreadyCleanedPermissionKeys`，不重复变更；既不在明确废弃目录也不在 tombstone 的 key 拒绝。随后初始化不得重建 tombstone 指向的任何权限或引用。
+
+## 9. 审计端点与字段
+
+```ts
+interface AuditRecord {
+  id: string
+  actor: UserSummary
+  scope: AccessScope
+  action: string
+  objectType: string
+  objectId: string
+  summary: Record<string, string | number | boolean | null | string[]>
+  requestId: string
+  createdAt: string
+}
+interface AuditQuery extends PageQuery {
+  action?: string
+  actorId?: string
+  from?: string
+  to?: string
+}
+```
+
+GET `/platform/audit-logs`、`/companies/:companyId/audit-logs`、`/companies/:companyId/projects/:projectId/audit-logs` 返回 `PageResult<AuditRecord>`，分别要求 `platform.audit.read`、`company.audit.read`、`project.audit.read`。日期为 ISO 字符串，`from <= to`；默认不额外限制日期。平台只看 scopeType=platform，企业看本企业 company+project，项目只看本项目。query 搜索 action/objectType/objectId 的公开标识，不提供任意 JSON SQL 筛选。
+
+action 使用固定 `company.create/company.status/company.administrator.set/project.create/project.status/project.administrator.set/account.status/account.password.reset/member.add/member.status/member.remove/member.roles/role.create/role.update/role.permissions/role.delete/menu.create/menu.update/menu.delete/permission.cleanup`。同一 action 的实际范围从 scope 区分。平台侧企业创建、账号启停、企业管理员设置、管理员重置密码、菜单和清理写平台事件；内部公司/项目变更写自身事件，目标企业 ID 可以进入平台事件的 summary，但不能据此把该事件归入企业审计。`account.password.reset` 仅在成功时写入，`summary` 只含 `{ result: 'success' }`；两种密码操作的成功与失败安全事件见[修改密码技术契约](../../06.认证与会话/修改密码/技术契约.md)。企业邀请审计动作及字段待产品确认，不属于当前固定 action 集合。
+
+摘要只记录字段白名单，例如 `changedFields`, `fromStatus`, `toStatus`, `roleIds`, `permissionKeys`, `targetUserId`, `companyId`, `replacedUserId`；不记录完整请求体、密码或令牌。操作者姓名/账号保存当时快照，防止后续变化破坏审计可读性。本期记录成功管理变更，失败交由现有异常/服务日志处理，不增加失败审计产品。
+
+## 10. 数据模型与迁移
+
+继续导出到 `apps/server/src/database/schema.ts`，可拆分 access schema 后由该文件 re-export，保证既有 Drizzle schema 入口不变。不得改写已有 `0000/0001` 历史迁移；目标迁移及 journal/snapshot 必须可审阅，并在隔离的现有数据库和空库验证后才能执行。当前仓库完整迁移链尚未满足该条件。
+
+| 表                              | 关键字段与数据库约束                                                                                                                                                                                                  |
+| ------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `companies`                     | UUID PK；name/code/description；status enum active/disabled；version int > 0；timestamps；code 唯一                                                                                                                   |
+| `projects`                      | UUID PK；company_id NOT NULL FK companies RESTRICT；name/code/description/status/version/timestamps；UNIQUE(company_id,code)、UNIQUE(company_id,id)                                                                   |
+| `company_members`               | UUID PK；company_id/user_id NOT NULL FKs；status/version/timestamps；UNIQUE(company_id,user_id)                                                                                                                       |
+| `project_members`               | UUID PK；company_id/project_id/user_id NOT NULL；status/version/timestamps；FK(company_id,project_id)→projects(company_id,id)；FK(company_id,user_id)→company_members(company_id,user_id)；UNIQUE(project_id,user_id) |
+| `roles`                         | UUID PK；scope_type/company_id/project_id；name/description；builtin nullable enum administrator/member；version/timestamps；合法 scope CHECK；各作用域 name 唯一；各作用域 builtin 非空时唯一                        |
+| `user_roles`                    | user_id/role_id 复合 PK，FK users/roles；分配必须在锁内校验角色作用域与公司/项目成员关系；平台无成员表。成员移除事务先删其相应角色分配再删关系                                                                        |
+| `permissions`                   | key varchar(150) PK；scope_type/kind/title/route_key/page_permission_key/admin_only/deprecated；页面 page_permission_key=null，操作引用同 scope 的页面权限                                                            |
+| `role_permissions`              | role_id/permission_key 复合 PK，FK roles/permissions RESTRICT；服务层与集成测试保证同 scope，无目录授权                                                                                                               |
+| `menus`                         | UUID PK；scope_type/parent_id/type/name/icon/sort/hidden/status/route_key/permission_key/protected；父级 FK RESTRICT；UNIQUE(scope_type,route_key) 部分索引仅 page；UNIQUE(scope_type,permission_key) 非空唯一        |
+| `menu_versions`                 | scope_type PK，version > 0；为三棵菜单树提供稳定版本记录                                                                                                                                                              |
+| `audit_logs`                    | UUID PK；actor_user_id FK RESTRICT；actor_account/name 快照；scope_type/company_id/project_id；action/object_type/object_id/summary JSONB/request_id/created_at；scope 合法 CHECK                                     |
+| `permission_cleanup_tombstones` | permission_key PK；cleaned_at/deployment_id；不 FK 到已删除权限                                                                                                                                                       |
+| `access_bootstrap`              | singleton PK=1；initialized_admin_user_id FK users、initialized_at；用于一次性平台管理员初始化，不随指定新账号重复提权                                                                                                |
+
+scope CHECK 精确为：platform 两个 ID 均 NULL；company company_id 非 NULL 且 project_id NULL；project 两个 ID 均非 NULL，且复合 FK 指向所属 project。role 同名约束与内置角色唯一约束分别对 platform/company/project 使用 partial unique index，不能依赖 PostgreSQL 默认 NULL 相等语义。成员关系和角色引用的跨作用域服务层约束必须有真实数据库集成测试。
+
+新表 created_at/updated_at 为 timestamptz；审计只有 created_at。必要索引：projects(company_id,status)，成员(company_id/user_id)、项目成员(project_id/user_id)，user_roles(user_id)，role_permissions(permission_key)，menus(scope_type,parent_id)，audit(scope_type,company_id,project_id,created_at,id)。无企业/项目物理删除接口，不增加级联业务删除。现有 `0003_cute_killmonger.sql` 仍包含已取消的企业父子层级，清理并重新验证前不得执行；企业邀请的数据模型和索引待产品确认，不在当前迁移契约内，现有 `0004_company-member-invitations.sql` 同样不能作为迁移或发布依据。
+
+初始化命令约定为 server 脚本 `access:init --account <已注册完整账号>`，通过现有环境读取数据库/Redis配置，不写任何默认密码。经批准的数据库迁移与目录种子必须可重复；第一次在管理锁内确认 active 账号、创建平台内置角色和三棵全局菜单/权限种子、建立平台管理员并写 access_bootstrap。已有 bootstrap 时，重复同账号只校验/更新系统目录；不同账号拒绝，不能通过删改参数提权。后续种子更新不改变任何用户角色分配，管理员权限按代码目录补齐、member保留基础入口、自定义角色和菜单配置保留，清理 tombstone 必须先过滤。新企业/项目事务按范围创建两个内置角色。
+
+解除 `0003`／`0004` 阻断并完成隔离验证后，目标迁移顺序为备份 → Drizzle migration → 服务端和目录更新 → 前端。当前不得执行仓库完整迁移链，也不得手工跳号、修改迁移历史或用 `db:push` 绕过。未来迁移失败时停止后续发布，按迁移事务回滚或经审阅恢复备份。开发/测试部署证明由运行期临时文件注入，不能在仓库提交真实运维数据或账号密码。
+
+## 11. 事务、锁和会话一致性
+
+首期采用一个明确可验证的 PostgreSQL 管理事务 advisory lock：`pg_advisory_xact_lock(7421, 1)`，仅用于本系统 access 管理命名空间。**所有管理写操作**（资料、状态、成员、角色、授权、菜单、清理、初始化）首先取得该锁，再读取授权和数据，然后业务变更+审计在同一事务提交。锁覆盖本期整个权限依赖图，所以多实例也串行；首期接受管理写入串行的吞吐代价，未来优化为细锁必须维持相同验收，不提前引入另一套分布式锁。
+
+事务采用 PostgreSQL READ COMMITTED；获取 advisory lock 后的下一次查询读取最新已提交状态，再执行账号、上层作用域、成员、管理员身份、页面+操作、资源归属、expectedVersion 校验。不能在拿锁前计算一次权限后把结果带入事务，也不能把 Drizzle 事务中的查询误用外部 db 连接。失败回滚，无成功审计。读取接口不缓存授权，响应构建过程中使用同一事务快照/读取上下文，避免拼接不同用户或作用域数据。
+
+先取得管理锁的写请求允许先完成，撤权等待；撤权先提交则后续请求在锁内重新鉴权并失败。最后管理员数量在同一锁内按变更后的结果计算。企业/项目管理员保护覆盖成员移除/停用/撤角色，平台内置管理员禁用全局账号是企业/项目保护例外，永远不能突破至少一名 active 平台内置管理员。项目有效管理员包含有效企业管理员。
+
+账号登录和禁用还须处理 PostgreSQL 与 Redis 的并发：
+
+1. 每次受保护请求在 Redis Session 验证后查 users 当前状态，非 active 401；包括现有 upload，而不只新管理接口。
+2. 登录完成密码验证后，在数据库事务中对目标 users 行加共享锁，重新确认 active，再调用现有 SessionStoreService 创建会话，结束事务；密码散列计算在锁外完成。
+3. 账号状态管理按“管理 advisory lock → 目标 users 行排他锁”顺序，调用现有 `revokeAllForUser` 后写目标状态和审计，再提交。启用也撤销残存旧会话，确保用户必须重新登录。登录只获取用户行锁，不反向申请管理锁，避免死锁。
+4. Redis 撤销失败则账号状态事务不成功，返回既有 `AUTH.SERVICE_UNAVAILABLE`。若 Redis 已撤销而数据库提交失败，最多导致用户重新登录，不能导致旧权限恢复。这里不声称 Redis 与 PostgreSQL 组成分布式原子事务。
+
+管理接口之外不能新增绕开该用户行锁的 Session 创建路径；否则禁用与登录竞态会让恢复账号后出现旧会话复活。以上实现可复用现有 auth repository/SessionStoreService，不需重写 Cookie/Bearer 或引入 JWT。
+
+## 12. 错误码、前端和验收对照
+
+以下新错误集中在 access 模块 `*.errors.ts`，使用 `AppException`，并加入现有 error-catalog.spec.ts。未知数据库/程序错误按现有全局过滤器返回 500，不把整个流程 catch 成 503。
+
+| HTTP | code                                                  | 场景                                                                 |
+| ---- | ----------------------------------------------------- | -------------------------------------------------------------------- |
+| 400  | `COMMON.VALIDATION_FAILED`                            | DTO、分页、UUID、类型、未知字段校验                                  |
+| 400  | `ACCESS.INVALID_PERMISSION_SET`                       | 未注册/跨 scope/非法页面操作组合、重复授权                           |
+| 400  | `ACCESS.INVALID_MENU_STRUCTURE`                       | 循环、类型父子不合法、跨 scope、重复绑定、未知目录绑定               |
+| 401  | `AUTH.SESSION_TOKEN_MISSING` / `AUTH.SESSION_INVALID` | 沿用既有 token/账号失效；bearerChallenge=true                        |
+| 403  | `ACCESS.FORBIDDEN`                                    | 当前范围权限不足、管理员身份不足、无权授予、范围/成员/功能停用       |
+| 404  | `ACCESS.NOT_FOUND`                                    | 所有管理资源不存在与跨企业/项目/角色/成员目标统一文案                |
+| 409  | `ACCESS.VERSION_CONFLICT`                             | expectedVersion 过期                                                 |
+| 409  | `ACCESS.DUPLICATE_RESOURCE`                           | 同范围编码/角色名称/成员/绑定重复                                    |
+| 409  | `ACCESS.LAST_ADMINISTRATOR`                           | 最后有效管理员保护或恢复时没有管理员                                 |
+| 409  | `ACCESS.BUILTIN_ROLE_IMMUTABLE`                       | 人工修改/删除内置角色定义                                            |
+| 409  | `ACCESS.RESOURCE_IN_USE`                              | 自定义角色仍分配，菜单仍有引用/子节点，清理有有效依赖                |
+| 409  | `ACCESS.PROTECTED_MENU`                               | 破坏管理恢复入口                                                     |
+| 409  | `ACCESS.CLEANUP_BLOCKED`                              | 非废弃目标、功能未下线、证明缺失/过期/变更、仍有版本依赖             |
+| 409  | `ACCESS.ALREADY_INITIALIZED`                          | 初始化参数企图更换平台首位管理员                                     |
+| 422  | `ACCESS.INVALID_MEMBER_ACCOUNT`                       | 企业直接注册中的账号条件不符合                                       |
+| 422  | `ACCESS.INVALID_MEMBER_RELATION`                      | 管理员或项目成员 `userId` 不属于要求的有效企业成员，或成员关系不可用 |
+| 503  | `AUTH.SERVICE_UNAVAILABLE`                            | 复用 Session Redis 明确依赖失败语义                                  |
+| 500  | `COMMON.INTERNAL_SERVER_ERROR`                        | 未知服务错误；底层信息不公开                                         |
+
+前端路由 `/login`、`/register`、`/workspaces` 加三套管理布局。登录成功 Cookie 保存 token，跳 `/`，由入口 middleware 获取企业、项目和平台入口：仅有一个项目且没有平台或额外企业管理职责时，直接进入该项目的首个已授权页面；其余情况进入 `/workspaces`。普通企业成员的默认权限不阻止单项目直达；手动访问 `/workspaces` 和具体企业、项目链接不执行默认入口分流。注册成功跳登录并带账号 UI 状态，不保存密码。企业成员新增界面保留“直接注册”和“邀请”两个产品入口；直接注册按本契约实施，邀请入口之后的页面、字段、路由和交互待产品确认，现有邀请管理页与接受页不构成稳定契约。无企业工作空间空态应引导用户联系企业管理员，不预设邀请载体，也不要求提供完整账号供管理员直接挂接。项目成员新增使用 `OrganizationMemberSelector` 的 `purpose=addProjectMember`，选择值固定为 `userId`，不返回组织、岗位或角色标签。工作台只展示当前用户/作用域基本信息和可用入口，不虚构统计 API。权限上下文不持久化，管理 API 默认 `cacheFor:0, shareRequest:false`，可省去首期业务缓存隔离复杂度；仍须在切换/退出/换号取消旧请求并使用用户+scope+请求代次避免迟到响应写回。
+
+403 刷新当前 access 一次，避免递归刷新；401 清 Cookie/用户缓存并回登录；404 显示无资源页，不泄漏其他作用域存在性；409 保留用户输入并提示刷新，不能自动用旧输入覆盖新版本。路由切换、窗口 focus、成功授权变更刷新上下文。菜单路由等待提交期间必须保留旧页面视觉内容并隔离交互，加载层覆盖；目标路由提交后再替换页面，避免卸载 `RouteTransition` 导致视图过渡失去旧快照。父级 scope middleware 获取一次权限上下文，叶子 access middleware 校验页面读权限，布局和按钮消费同一次导航提交的数据，后端始终独立鉴权。middleware 统一位于 `router/middleware`，路由分模块位于 `router/modules`；页面通过 `lazyLoad` 加载，`App.tsx` 统一承载 `RouteTransition`。
+
+15 项需求验收对应：1 企业/项目创建事务；2 scope隔离及企业管理员隐式项目访问；3 目录/页面/操作及接口一致；4 最新授权与停用；5 请求取消/换号；6 唯一约束/最后管理员；7 事务审计；8 既有认证/上传/迁移；9 自身状态保留恢复；10 平台补任与替换；11 内置企业管理员专属创建；12 内置角色目录升级；13 未知routeKey兼容；14 受控证明和事务清理；15 双顺序真实数据库锁验证。
+
+契约/架构负责人独占 `packages/shared`，负责共享类型、纯工具和目录定义并先导出稳定接口；后端独占 `apps/server`，前端独占 `apps/web`，两端引用共享包，不能定义第二份传输 DTO。前端、后端各自测试本范围后由主控联调，验收报告区分通过/失败/环境无法验证，不把跳过数据库或 Playwright 测试记为通过。
+
+## 13. 后续扩展与变更记录
+
+- 企业邀请只保留已确认的入口定位；邀请对象、载体、流程、状态及技术协议全部待产品确认。当前代码、页面、自动化测试及 `0004_company-member-invitations.sql` 只能作为未确认实现记录，不能替代产品确认或进入现行交付。
+- 平台全局账号的管理员重置密码已在当前工作树实现，`platform.accounts.reset-password` 仅平台内置管理员可用，上文权限表、接口表和固定审计 action 清单已同步。业务错误、全端撤销和安全事件见[修改密码技术契约](../../06.认证与会话/修改密码/技术契约.md)，测试边界见[修改密码测试报告](../../06.认证与会话/修改密码/测试报告.md)。
+
+| 日期       | 变更摘要                                                                                                                                  | 原因                                              | 影响范围                                                               |
+| ---------- | ----------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------- | ---------------------------------------------------------------------- |
+| 2026-10-08 | 将管理员重置密码纳入当前平台账号操作、接口和固定审计清单，并链接测试边界 | 当前工作树已实现且完成自动化与隔离存储专项 | 平台账号权限、接口与审计清单 |
+| 2026-10-08 | 关联平台账号管理员重置密码的实施中增量，区分待实施权限与当前权限表 | 修改密码契约已确定新增平台管理员操作 | 平台账号权限、接口与审计清单 |
+| 2026-09-19 | 菜单图标契约由服务端图标名白名单调整为安全 SVG key；Web 自动发现本地图标并统一选择、解析和降级，补充旧图标及空值迁移和新菜单默认图标规则 | 前端资源不能由服务端重复维护清单，且需支持新增 SVG 自动进入选择器 | 共享类型、校验、种子、迁移、菜单管理、导航和兼容测试 |
+| 2026-09-18 | 菜单路由等待态保留旧页面视觉内容并隔离交互，目标路由提交后再替换                                                                                 | 过早卸载 `RouteTransition` 会丢失旧页面视图快照，导致过渡动画消失 | 前端布局、导航等待态、AC-05 与验证要求                                  |
+| 2026-09-18 | 明确当前完整迁移链受 `0003` 企业层级残留和 `0004` 未确认邀请实现共同阻断，解除前不得执行或绕过                                            | 目标迁移契约不能被误读为当前仓库已经可以安全迁移  | 数据模型、迁移顺序、初始化前提与发布判断                               |
+| 2026-09-18 | 邀请口径纠偏为“只确认产品入口，具体协议待确认”；撤回固定有效期、Token、状态、5 个端点、数据模型、错误码、事务、审计和接受流程等未确认契约 | 现有实现不能反向定义产品协议                      | 契约状态、共享 DTO、端点、数据模型、错误码、事务、审计、前端与发布判断 |
+| 2026-09-17 | 企业新增成员由完整账号添加改为直接注册／邀请                                                                                              | 最新成员边界                                      | 成员 DTO、POST 企业成员、前端入口、错误与测试                          |
+| 2026-09-17 | 项目新增成员改为从所属企业有效成员候选中按 `userId` 添加，并由服务端二次校验                                                              | 避免完整账号歧义、跨企业添加和候选状态竞态        | 候选查询、POST 项目成员、错误与测试                                    |
+| 2026-09-17 | 企业和项目管理员请求字段统一为 `administratorUserId`                                                                                      | 全局账号名称不唯一，关系必须使用平台唯一 `userId` | 企业／项目创建、管理员设置、选择器回显                                 |