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

@@ -0,0 +1,744 @@
+# 企业／项目组织架构、岗位与成员选择器实施契约
+
+契约状态：独立企业与组织架构主体已确认，进入实施同步阶段；企业邀请只确认产品入口，具体协议不属于现行契约。PRD 状态：部分确认。日期：2026-09-18。
+
+本文件是 [PRD](./需求文档.md) 已确认部分的前后端、共享类型、数据库和迁移单一真相源。用户于 2026-09-16 确认初版契约，并于 2026-09-17 明确平台下企业彼此独立及新的成员入口边界；最新决定覆盖初版中的企业间父子关系和完整账号添加成员设计。企业邀请当前只确认入口存在，任何业务或技术细节均须产品确认后才能写入本契约。实现发现会改变已确认业务语义的缺口时，必须先更新本契约并重新确认；前后端不得各自发明字段、端点或权限 key。
+
+## 1. 工程基线与实施边界
+
+- 继续使用现有 `platform | company | project` 三种 `AccessScope`。平台下企业彼此独立，不新增企业类型或企业间父子关系；集团、事业群、分公司、部门等层级名称由单个企业内部的组织单元表达，不新增 group、organization 或 department 作用域。
+- 共享 DTO、返回类型、枚举、权限目录和纯规范化方法统一放在 `packages/shared/src/types`、`packages/shared/src/utils` 并从既有入口导出；前端和后端不得复制第二份传输类型。
+- 成功响应直接返回约定 JSON，不增加 `{ code, data }` 包装。失败沿用 `ApiFailure = { code, message, details? }`，并使用服务端 `request.id`／`x-request-id` 关联审计。
+- GET 成功为 200，创建资源的 POST 成功为 201，其余写操作成功为 200。稳定资源没有 DELETE 端点；批量替换关系直接返回替换后的关系集合。
+- Controller 接收 `unknown`，使用 Zod `strictObject` 拒绝未知字段；URL UUID 使用现有路由校验；作用域只从 URL 和登录上下文推导，不能相信请求体自报的 companyId、projectId 或 scope。
+- 所有新增 Controller 显式声明 `@AccessPolicy`，未声明策略继续默认拒绝。鉴权顺序固定为登录与账号状态 → 作用域与成员资格 → 页面及操作权限 → 资源归属。
+- 跨企业、跨项目、跨组织树 ID 与不存在 ID 统一返回 404；已确认处于当前作用域但缺少权限返回 403。
+- 前端继续使用现有 alova 实例、页面旁 `api.ts`、React Router middleware、工作空间取消控制和 `cacheFor: 0, shareRequest: false` 的管理请求约定。
+- 本期实现范围只包含 React Web、NestJS Server 和 shared；不改 `apps/web-vue`，不实现完整工作流。
+
+## 2. 共享类型与字段规范
+
+### 2.1 基础枚举与引用
+
+```ts
+type OrganizationScope = Extract<AccessScope, { type: 'company' | 'project' }>
+type OrganizationDuty = 'member' | 'leader' | 'deputy'
+type ProjectOrganizationInitialization =
+  { mode: 'blank' } | { mode: 'template'; templateId: string; templateVersion: number }
+
+interface OrganizationRelationInput {
+  organizationUnitId: string
+  duty: OrganizationDuty
+}
+```
+
+- 所有实体 ID 和 userId 均为 UUID 字符串；日期输出 ISO 8601 UTC 字符串。
+- `sort` 是 `0～999999999` 的单个整数，不拆分主排序／细分排序，不接受小数。
+- 所有稳定可编辑资源的 `version` 从 1 开始；写请求携带 `expectedVersion`，成功后版本加一。
+- 名称等展示文本保存前只 `trim` 并保留大小写；需要唯一校验的名称和编码统一使用 `lower(NFKC(trim(value)))` 作为规范值，内部空白不折叠。所有公开 code DTO 先 trim 并按 ASCII 大小写字母／数字／下划线／短横线校验，再执行 `toLowerCase` 保存；因此新建或更新写入的 code 及其响应固定为小写，未被编辑的存量记录仍按原值展示，迁移不静默重写。新增表的 key 列由共享纯方法计算并写入，数据库再以 `lower(normalize(btrim(value), NFKC))` CHECK 校验原值与 key 一致；没有 key 列的既有 code 使用同一表达式函数索引，不能假设 PostgreSQL `lower()` 自动完成 NFKC。
+- 公共规范化方法、树深度计算、作用域 URL 构造等非显然方法必须写 JSDoc；超过 3 个参数的方法使用对象参数。
+
+### 2.2 字段长度、格式与分页基线
+
+| 字段          | 共享 DTO 规则                                             | 新表数据库规则                              |
+| ------------- | --------------------------------------------------------- | ------------------------------------------- |
+| `name`        | `trim` 后 2～100 个字符                                   | `varchar(100)`，并以 CHECK 保证长度下限     |
+| `code`        | trim 后 2～32 个字符，先接受 `^[A-Za-z0-9_-]+$`，再转小写 | `varchar(32)`，CHECK 保证长度、字符集和小写 |
+| `description` | 可省略；`trim` 后 0～500 个字符，省略时保存为空字符串     | `varchar(500)`，默认空字符串                |
+| `query`       | 可省略；`trim` 后最多 100 个字符                          | 不持久化                                    |
+| `page`        | 正整数，默认 1                                            | 不持久化                                    |
+| `pageSize`    | 1～100 的整数，默认 20                                    | 不持久化                                    |
+
+- 上表的 `name`、`code`、`description` 统一适用于企业、项目、组织单元、岗位、组织模板及模板子项；shared 导出唯一一套基础 schema，各 Controller 组合复用，不得在前后端或模块内复制不同上限。
+- 新增业务表的物理列宽与公开 DTO 上限一致。既有 `companies.name varchar(100)` 保持不变；既有 `companies.description/projects.description` 可继续使用 `text`，但公开写接口仍严格执行 500 字上限。
+- 既有 `companies.code` 与 `projects.code` 当前为 `varchar(64)`，本期不缩短物理列，避免无意义重写和失败回滚；所有新旧公开写接口仍统一执行 32 字上限，不得因物理容量为 64 而放宽 API。
+- migration 在任何 DDL 前预检存量企业和项目 code。只要 trim 后长度不在 2～32、字符不符合大小写 ASCII 字母／数字／下划线／短横线规则，或新规范键产生冲突，就立即停止迁移并输出记录 ID 供人工修复；禁止自动截断、改名、拼接后缀或静默转小写。存量 code 保留原展示值但参与不区分大小写的规范唯一校验；后续公开写入统一保存小写。企业 code 继续保持既有全局唯一，项目 code 继续保持企业内唯一。
+- 所有数组筛选字段和 resolve 的 `userIds` 每类最多 100 个 UUID；字段一旦出现就必须至少 1 个且去重，空数组和重复项按请求校验失败处理。
+
+### 2.3 独立企业边界与企业创建
+
+```ts
+interface CreateCompanyRequest {
+  name: string
+  code: string
+  description?: string
+  administratorUserId: string
+}
+```
+
+- 既有 `CompanyRecord`、`CompanyDetail`、`ProjectRecord extends CompanyRecord` 以及企业列表／详情／资料／状态响应保持原契约；本期不向企业模型新增父级、类型、排序或企业名称规范键字段。
+- 平台继续使用既有企业列表管理彼此独立的企业，不新增企业树查询、父级选择、企业移动或层级摘要端点。
+- 项目始终直接保存一个 `companyId`；组织树、岗位、成员、模板及权限校验均以该直接所属企业为边界，不产生跨企业继承或隐式归属。
+- 创建企业仍以 `CompanyDetail` 返回；请求只把管理员标识从 `administratorAccount` 破坏性切换为 `administratorUserId`，不接受任何企业层级字段。
+
+### 2.4 组织树与组织单元
+
+```ts
+interface OrganizationTreeRecord {
+  id: string
+  scope: OrganizationScope
+  parentId: string | null
+  units: OrganizationUnitNode[]
+}
+
+interface OrganizationTreeQuery {
+  parentId?: string
+}
+
+interface OrganizationUnitRecord {
+  id: string
+  treeId: string
+  parentId: string | null
+  name: string
+  code: string
+  description: string
+  sort: number
+  status: EntityStatus
+  version: number
+  depth: number
+  fullPath: string
+  createdAt: string
+  updatedAt: string
+}
+
+interface OrganizationUnitNode extends OrganizationUnitRecord {
+  effective: boolean
+  hasChildren: boolean
+}
+
+interface CreateOrganizationUnitRequest {
+  parentId?: string | null
+  name: string
+  code: string
+  description?: string
+  sort?: number
+}
+
+interface UpdateOrganizationUnitRequest extends VersionRequest {
+  name?: string
+  code?: string
+  description?: string
+  sort?: number
+}
+
+interface MoveOrganizationUnitRequest extends VersionRequest {
+  parentId: string | null
+  sort?: number
+}
+```
+
+- 企业／项目本身只作为 UI 虚拟根，不持久化根节点；真实顶级节点 `parentId = null` 且深度为 1。
+- 树接口按父节点懒加载：查询省略 `parentId` 时返回顶级节点并在响应中写 `parentId = null`；传入 `parentId` 时只返回其直接子节点。每个节点以 `hasChildren` 表示是否还有可见直接子节点，不递归返回 `children`。
+- 每棵树最多 10 层。创建、移动和模板复制都在事务锁内校验目标节点及完整子树深度。
+- `code` 在单棵树内规范化唯一；`name` 在同一父级下规范化唯一，不同分支允许同名。
+- `fullPath`、`depth`、`effective` 是查询派生字段，不落库。`effective` 仅在自身及全部祖先都 active 时为 true。
+- 停用节点不改写后代状态，也不删除成员关系；停用父节点下不能新建节点，有无效祖先的节点不能成为有效节点的移动目标。
+- 移动保持组织单元 ID 不变，禁止移动到自身或后代。未传 sort 时取目标同级下一个可用整数。
+
+### 2.5 组织成员关系
+
+```ts
+interface OrganizationMembershipRecord {
+  id: string
+  organizationUnit: Pick<OrganizationUnitRecord, 'id' | 'name' | 'code' | 'fullPath' | 'status'>
+  duty: OrganizationDuty
+  createdAt: string
+  updatedAt: string
+}
+
+interface ReplaceMemberOrganizationUnitsRequest {
+  relations: OrganizationRelationInput[]
+}
+
+interface ReplaceMemberOrganizationUnitsResult {
+  userId: string
+  relations: OrganizationMembershipRecord[]
+}
+
+interface OrganizationUnitMemberInput {
+  userId: string
+  duty: OrganizationDuty
+}
+
+interface OrganizationUnitMemberRecord {
+  membershipId: string
+  member: Pick<MemberRecord, 'id' | 'userId' | 'account' | 'name' | 'status' | 'accountStatus'>
+  duty: OrganizationDuty
+  createdAt: string
+  updatedAt: string
+}
+
+interface ReplaceOrganizationUnitMembersRequest {
+  members: OrganizationUnitMemberInput[]
+}
+
+interface ReplaceOrganizationUnitMembersResult {
+  organizationUnitId: string
+  members: OrganizationUnitMemberRecord[]
+}
+```
+
+- 企业关系绑定既有 company member，项目关系绑定既有 project member。一次请求中的 `userId` 与所有组织单元必须属于 URL 指定的同一作用域。
+- 同一成员可加入多个组织单元；`(成员, 组织单元)` 唯一。全部关系同等，不存在主归属、默认组织或数组第一项的特殊语义。
+- 每条关系只有一个 duty；每个组织单元最多一个 leader、可有多个 deputy。同一个人可以领导多个组织单元。
+- 按成员替换时，`relations` 是该成员在当前 URL 作用域内的完整组织关系集合；按组织单元替换时，`members` 是该单元的完整成员集合，只替换该单元关系并保留每名成员在其他组织单元的关系。两种方向都在锁内原子完成，重复组织单元／userId、跨作用域、非法新增／升级或负责人冲突使整批失败，不能留下部分写入。
+- 两种替换请求的空数组都允许：按成员空数组解除该成员全部组织关系，按组织单元空数组清空该单元全部成员。按组织单元提交时同样比较该单元的持久化旧集合与新集合；停用成员或停用／无效组织单元的旧关系只可原样保留、移除或降级，不可新增或升级，且最终最多一名 leader。
+- 关系返回固定按 leader、deputy、member，再按关系 ID 升序。不存在成员排序字段。
+- “未归属组织”由候选查询的 `unassigned = true` 派生，数据库不创建对应节点。
+- active 成员只可向 effective 组织单元新增关系或升级职责。停用成员以及指向停用／无效组织单元的既有关系可原样保留、移除，或按 `leader → deputy → member` 的方向降级；不得新增关系或反向升级职责。服务端比较持久化旧集合与请求新集合后判定，而不是把含停用 ID 的请求一律拒绝。
+
+### 2.6 岗位与任职
+
+```ts
+interface PositionRecord {
+  id: string
+  scope: OrganizationScope
+  name: string
+  code: string
+  description: string
+  status: EntityStatus
+  version: number
+  memberCount: number
+  createdAt: string
+  updatedAt: string
+}
+
+interface CreatePositionRequest {
+  name: string
+  code: string
+  description?: string
+}
+
+interface UpdatePositionRequest extends VersionRequest {
+  name?: string
+  code?: string
+  description?: string
+}
+
+interface ReplaceMemberPositionsRequest {
+  positionIds: string[]
+}
+
+interface ReplaceMemberPositionsResult {
+  userId: string
+  positions: PositionRecord[]
+}
+
+interface PositionMemberRecord {
+  assignmentId: string
+  member: Pick<MemberRecord, 'id' | 'userId' | 'account' | 'name' | 'status' | 'accountStatus'>
+  createdAt: string
+}
+
+interface ReplacePositionMembersRequest {
+  userIds: string[]
+}
+
+interface ReplacePositionMembersResult {
+  positionId: string
+  members: PositionMemberRecord[]
+}
+```
+
+- 岗位是企业或项目作用域内的平面列表，不是树，不属于组织单元。
+- 岗位、岗位任职和模板岗位的请求、响应、表结构均不包含 organizationUnitId、treeId 或 templateUnitId；Zod strict DTO 会拒绝这些未知字段。
+- 同一作用域的岗位 name 和 code 分别按规范键唯一；一人可多岗，一岗可多人，成员与岗位组合唯一。
+- 组织关系、岗位任职和 RBAC 角色分别维护、分别审计，任一方变化不得联动另外两方。
+- 按成员替换时，`positionIds` 是该成员在当前 URL 作用域内的完整岗位集合；按岗位替换时，`userIds` 是该岗位的完整成员集合，只替换该岗位任职并保留每名成员的其他岗位。两种方向均在锁内原子完成，重复 ID、跨作用域或非法新增使整批失败。
+- 两种岗位替换请求的空数组都允许，分别表示解除该成员全部任职或清空该岗位全部任职。停用成员或停用岗位的既有任职可原样保留或移除，但不得新增；服务端必须比较旧集合和新集合，不能因目标停用而阻止清理，也不能借全量替换新增停用关系。
+
+### 2.7 项目组织模板与项目创建
+
+```ts
+interface OrganizationTemplateUnitInput {
+  clientKey: string
+  parentClientKey: string | null
+  name: string
+  code: string
+  description?: string
+  sort: number
+}
+
+interface OrganizationTemplatePositionInput {
+  name: string
+  code: string
+  description?: string
+  status: EntityStatus
+}
+
+interface OrganizationTemplateUnitRecord extends Omit<
+  OrganizationTemplateUnitInput,
+  'clientKey' | 'parentClientKey'
+> {
+  id: string
+  parentId: string | null
+  templateVersion: number
+}
+
+interface OrganizationTemplatePositionRecord extends OrganizationTemplatePositionInput {
+  id: string
+  templateVersion: number
+}
+
+interface OrganizationTemplateRecord {
+  id: string
+  companyId: string
+  name: string
+  description: string
+  status: EntityStatus
+  isDefault: boolean
+  version: number
+  units: OrganizationTemplateUnitRecord[]
+  positions: OrganizationTemplatePositionRecord[]
+  createdAt: string
+  updatedAt: string
+}
+
+interface OrganizationTemplateSummary extends Omit<
+  OrganizationTemplateRecord,
+  'units' | 'positions'
+> {
+  unitCount: number
+  positionCount: number
+}
+
+interface CreateOrganizationTemplateRequest {
+  name: string
+  description?: string
+  isDefault?: boolean
+  units: OrganizationTemplateUnitInput[]
+  positions: OrganizationTemplatePositionInput[]
+}
+
+interface ReplaceOrganizationTemplateRequest extends VersionRequest {
+  name: string
+  description?: string
+  isDefault: boolean
+  units: OrganizationTemplateUnitInput[]
+  positions: OrganizationTemplatePositionInput[]
+}
+
+interface UpdateOrganizationTemplateStatusRequest extends VersionRequest {
+  status?: EntityStatus
+  isDefault?: boolean
+}
+
+interface CreateProjectRequest {
+  name: string
+  code: string
+  description?: string
+  administratorUserId: string
+  organizationInitialization: ProjectOrganizationInitialization
+}
+```
+
+- `clientKey` 只用于一次请求内表达模板树父子关系，不持久化，不作为跨请求稳定 ID；同一请求内唯一且 `parentClientKey` 必须引用本请求节点。缺失父节点、自引用或任意环按 400 `COMMON.VALIDATION_FAILED` 拒绝；形成的森林超过 10 层按 409 `ACCESS.ORGANIZATION_DEPTH_EXCEEDED` 拒绝。
+- 模板 `version` 同时是乐观锁版本和当前组织单元／岗位子项快照版本，不代表可重建整个模板聚合的历史。创建时 `isDefault` 省略即为 false；模板 PUT 必须显式提交 `isDefault` 与完整定义，更新模板主表当前值并生成下一份完整子项版本快照；状态 PATCH 的 `status/isDefault` 至少提交一项，省略的字段保持原值，也必须生成下一版本，并把上一版本的全部组织单元和岗位原样复制到新版本后再变更状态／默认标记，不能产生没有子项的当前版本。旧版本子项永久保留供来源追踪和审计，不作为新项目可选版本；旧的 name、description、status、isDefault 只由审计记录表达，不承诺从模板表重建历史主表状态。
+- 每个企业最多一个 active 且 `isDefault = true` 的模板。设为默认时目标最终状态必须为 active；同一事务锁定目标和旧默认模板。若存在另一旧默认模板，旧模板也递增 version、把自身当前完整子项复制到下一版本、仅把 `isDefault` 改为 false，并写独立审计；不能旁路 UPDATE 绕过乐观锁或生成空版本。停用默认模板时目标新版本强制 `isDefault = false`，不自动挑选替代默认模板。
+- 项目创建必须显式提交 `organizationInitialization`。blank 不允许模板字段；template 必须提交 templateId 和 templateVersion，且模板属于项目直接企业、active、版本等于当前版本。
+- 模板查询先以项目直接 `companyId + templateId` 约束资源归属；跨企业或不存在统一 404。只有已经确认属于当前企业后，停用、不能作为默认或其他当前作用域内不可用状态才返回 422 `ACCESS.TEMPLATE_UNAVAILABLE`，版本不等于当前版本返回 409 `ACCESS.TEMPLATE_VERSION_CONFLICT`。
+- template 初始化在写锁内先比较 `organization_templates.version`，再只读取 `organization_template_units/positions` 中该 `template_id + template_version` 的完整子项版本快照；不能读取“最新子项”或跨版本拼接。状态变更生成的新版本因已复制完整子项，可被后续项目正常初始化。
+- 模板组织单元输入和表有意不含 status：模板中存在的结构节点都可用，初始化后的项目组织单元统一为 active，避免在模板树中再引入无效祖先语义。模板岗位是平面定义，保留显式 status；初始化时按原状态复制，disabled 岗位在项目中仍为 disabled，项目可随后独立启用。因此 97 个新增字段统计不变，此差异不是漏字段。
+- 模板复制只生成项目组织单元和项目岗位，保留各自来源模板子项 ID；不复制成员、负责人、组织关系、岗位任职或 RBAC 角色。
+- 项目创建后组织和岗位完全独立；模板修改、停用、恢复均不自动同步既有项目。
+
+### 2.8 账号与组织成员候选
+
+```ts
+type GlobalAccountCandidatePurpose = 'createCompanyAdministrator' | 'setCompanyAdministrator'
+type OrganizationMemberCandidatePurpose =
+  | 'browseOrganization'
+  | 'assignPositionMembers'
+  | 'createProjectAdministrator'
+  | 'setProjectAdministrator'
+  | 'addProjectMember'
+type CandidateDisabledReason =
+  | 'accountInactive'
+  | 'memberInactive'
+  | 'scopeInactive'
+  | 'organizationInactive'
+  | 'positionInactive'
+  | null
+
+interface GlobalAccountCandidateQuery extends PageQuery {
+  purpose: GlobalAccountCandidatePurpose
+}
+
+interface GlobalAccountCandidate {
+  userId: string
+  account: string
+  name: string
+  status: AccountStatus
+  disabled: boolean
+  disabledReason: CandidateDisabledReason
+}
+
+interface OrganizationMemberCandidateQuery extends PageQuery {
+  purpose?: OrganizationMemberCandidatePurpose
+  organizationUnitIds?: string[]
+  positionIds?: string[]
+  roleIds?: string[]
+  projectIds?: string[]
+  unassigned?: boolean
+  includeDisabled?: boolean
+}
+
+interface OrganizationUnitCandidateTag {
+  id: string
+  membershipId: string
+  name: string
+  fullPath: string
+  status: EntityStatus
+  effective: boolean
+  duty: OrganizationDuty
+}
+
+interface PositionCandidateTag {
+  id: string
+  name: string
+  status: EntityStatus
+}
+
+interface OrganizationMemberIdentity {
+  scope: OrganizationScope
+  scopeName: string
+  memberId: string
+  memberStatus: EntityStatus
+  scopeStatus: EntityStatus
+  organizationUnits: OrganizationUnitCandidateTag[]
+  positions: PositionCandidateTag[]
+  roles: Array<{ id: string; name: string }>
+}
+
+interface OrganizationMemberCandidate {
+  userId: string
+  account: string
+  name: string
+  accountStatus: AccountStatus
+  identities: OrganizationMemberIdentity[]
+  disabled: boolean
+  disabledReason: CandidateDisabledReason
+}
+
+interface ResolveCandidatesRequest {
+  userIds: string[]
+}
+
+interface ResolveGlobalAccountCandidatesRequest extends ResolveCandidatesRequest {
+  purpose: GlobalAccountCandidatePurpose
+}
+
+interface ResolveOrganizationMemberCandidatesRequest extends ResolveCandidatesRequest {
+  purpose?: OrganizationMemberCandidatePurpose
+}
+
+interface SetAdministratorRequest {
+  administratorUserId: string
+  replaceUserId?: string
+}
+```
+
+- 候选查询和回显均按 userId 去重。搜索支持姓名或完整账号，服务端分页，默认按规范化姓名、完整账号、userId 升序；返回完整账号、`scopeName`、组织完整路径、组织／岗位状态、必要角色及身份状态。
+- `OrganizationMemberSelector` 的稳定选择值固定为 `userId`。当前企业／项目由调用候选及保存动作的 URL `AccessScope` 解释；候选中的项目 identity 只用于权限裁剪后的展示、筛选与辨识，不进入持久化选择值。需要修改某个项目的关系时，业务必须在该项目 URL 下提交，不能让客户端在请求体中自报 scope。
+- `organizationUnits` 中每个标签对应一条真实成员关系，必须返回稳定的 `membershipId` 与 `duty`。`browseOrganization` 的 `organizationUnitIds` 恰好包含一个 ID 时，改按该匹配关系的 duty 优先级 `leader → deputy → member`、`membershipId ASC`、`userId ASC` 排序，使组织成员表可直接分页编辑；其他候选查询仍按规范化姓名、完整账号、userId 排序。
+- `purpose` 省略时固定为 `browseOrganization`。`includeDisabled` 省略时固定为 `true`，停用候选仍返回并带禁选原因；显式为 `false` 时只返回当前 purpose 下可提交的候选。resolve 不丢弃已选的停用候选，以便稳定回显，但仍标记禁选。
+- 普通浏览时，企业端点聚合当前企业身份及调用者在该企业内获准查看的项目身份；项目端点只返回当前项目身份。企业端只有具备 `company.projects.read` 时才可读取任何项目 identity，并继续按现有项目可见性逐项目裁剪；仅有 `company.projects.read` 不代表可以读取项目组织、岗位或角色标签。企业端未传 `projectIds` 时，身份筛选域是当前企业身份；传入时筛选域是所列可见项目身份，`projectIds` 内部为 OR，且当前企业身份不参与本次筛选。项目端不接受 `projectIds`。
+- 企业端返回的每个项目 identity 都按该项目实际权限裁剪：组织标签要求该项目的 `project.organization.read`，岗位标签要求 `project.positions.read`，角色标签要求既有 `project.roles.read`；缺少某类权限时不返回该类标签，不能用其他项目或企业权限替代。`organizationUnitIds`、`positionIds`、`roleIds` 用于项目身份筛选时，也必须对每个目标项目分别具备上述对应权限；可见项目内权限不足返回 403，不可见、跨企业或不存在的项目／资源返回 404。
+- `organizationUnitIds`、`positionIds`、`roleIds` 各自数组内部为 OR，不同类别之间与 `query`、`unassigned` 之间为 AND；必须由同一个筛选域 identity 同时满足全部身份类条件，不能用企业身份的角色与项目身份的组织标签拼成一次命中。候选只要存在一个这样的 identity 即命中。
+- `unassigned` 省略或为 `false` 时不参与过滤；为 `true` 时要求上述同一个 identity 没有任何持久化组织关系，包含指向停用组织单元的关系也仍算“已归属”。因此企业端无 `projectIds` 时判断企业组织关系，有 `projectIds` 时分别在所选项目身份中判断；项目端只判断当前项目。
+- 所有筛选 ID 必须属于本次筛选域且对调用者可见；跨域或不存在返回 404，筛选能力所需权限不足返回 403。响应中的 identities 及各类标签仍按当前企业或逐项目权限返回，不能借筛选参数扩张可见范围。
+- 同一候选存在多个命中 identity 时，只要至少一个 identity 在当前 purpose 下可提交，候选整体 `disabled=false`；全部不可提交时，才按 `accountInactive → scopeInactive → memberInactive → organizationInactive → positionInactive` 取第一个禁选原因。后两项只在本次命中依赖对应无效标签时生效；某人存在其他无效组织或岗位标签，不会使其有效身份无条件禁选。提交业务动作时服务端按该动作重新校验，不能信任查询时状态。
+- `assignPositionMembers` 只返回 URL 当前企业或项目的成员身份，要求对应 `*.positions.read` 与 `*.positions.assign`，不要求 `*.organization.read`。该 purpose 只接受 `page/pageSize/query/positionIds/includeDisabled`；响应保留当前身份的岗位标签，并清空组织与角色标签，既满足岗位成员回显和筛选，也不借岗位维护权限暴露组织信息。
+- `createProjectAdministrator` 与 `setProjectAdministrator` 只允许调用企业端候选接口，分别要求既有 `company.projects.create` 与 `company.projects.administrator`，不额外要求 `company.organization.read` 或 `company.members.read`。这两个 purpose 只允许 `page/pageSize/query/includeDisabled`，其他身份筛选字段出现即 400；只搜索当前企业成员，并把 identities 裁成一个企业身份且清空组织、岗位、角色标签，避免为选管理员扩大信息暴露。
+- `addProjectMember` 只允许调用项目端候选接口，要求 `project.members.add`，不额外要求企业成员列表、组织、岗位或角色读取权限。该 purpose 只接受 `page/pageSize/query/includeDisabled`；只返回项目所属企业中账号和企业成员关系均有效、且尚无当前项目成员关系的用户，identity 只保留所属企业成员摘要并清空组织、岗位、角色标签。resolve 对已经加入项目或状态失效的既有选择仍返回禁选原因，保存接口仍须二次校验。
+- 除 `addProjectMember` 这一明确业务动作外，`OrganizationMemberSelector` 只负责选择既有成员，不创建成员、组织关系、岗位任职或角色。
+- 企业新增成员只确认直接注册新账号并加入企业、发起邀请两个产品入口；不能通过候选接口枚举平台账号，也不能继续用旧 `{ account }` 精确匹配方式直接拉入既有账号。邀请对象、是否绑定账号、载体、有效期、状态、接受／拒绝、撤销／重发、发送渠道、DTO、端点、Token、安全、事务、审计和验收标准均待确认，其他专项或现有实现中的邀请细节不得被本契约引用为默认规则。
+- 项目普通成员新增提交 `{ userId }`。后端在写事务中重新验证账号 active、目标是当前项目所属企业的 active company member、当前项目不存在该成员关系；不满足时返回 `ACCESS.INVALID_MEMBER_RELATION`，重复关系按 `ACCESS.DUPLICATE_RESOURCE` 处理。候选结果不构成写入授权。
+- 平台创建企业、设置企业管理员统一改用 `administratorUserId`；项目创建、设置项目管理员也统一提交 `administratorUserId`，目标必须是有效企业成员。新旧 account/userId 字段不同时接受，Web 与 Server 同版本发布。
+- 创建企业或由平台设置企业管理员时，目标可为尚未加入该企业的 active 全局账号；事务内按既有规则创建或恢复 company member 并授予管理员角色。项目管理员只能从项目直接企业的 active company member 中选择，事务内创建或恢复 project member 后授予管理员角色；直接提交未通过候选查询的 userId 仍执行相同资格校验并以 `ACCESS.INVALID_MEMBER_RELATION` 拒绝。
+
+## 3. 数据模型与数据库约束
+
+### 3.1 表与字段清单
+
+本期新增 10 张表，共 **97 个新增字段**；不向 `companies` 或其他既有表新增企业间父子关系专属字段。既有 `companies.code`、`projects.code` 的规范唯一索引调整不计入字段数；索引、外键、CHECK 和 enum 同样不计入字段数。
+
+| 表                                  | 字段                                                                                                                                                                                  | 核心约束                                                                                                                          |
+| ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
+| `organization_trees`                | `id`, `scope_type`, `company_id`, `project_id`, `backfill_batch_key`, `created_at`                                                                                                    | company 行要求 company_id 非空、project_id 为空；project 行两者非空并组合 FK 到 projects；分别保留企业／项目组合引用键            |
+| `organization_units`                | `id`, `tree_id`, `parent_id`, `name`, `name_key`, `code`, `code_key`, `description`, `sort`, `status`, `version`, `source_template_unit_id`, `created_at`, `updated_at`               | `(tree_id,id)` 唯一；组合自 FK `(tree_id,parent_id)`；单树 code_key 唯一；根／非根分别做同父 name_key 唯一；sort/version CHECK    |
+| `company_organization_unit_members` | `id`, `scope_type`, `company_id`, `tree_id`, `organization_unit_id`, `user_id`, `duty`, `created_at`, `updated_at`                                                                    | scope_type 固定 company；组合 FK 同时约束企业树、单元和 company member；成员-单元唯一；leader 部分唯一                            |
+| `project_organization_unit_members` | `id`, `scope_type`, `company_id`, `project_id`, `tree_id`, `organization_unit_id`, `user_id`, `duty`, `created_at`, `updated_at`                                                      | scope_type 固定 project；组合 FK 同时约束项目树、单元和 project member；成员-单元唯一；leader 部分唯一                            |
+| `positions`                         | `id`, `scope_type`, `company_id`, `project_id`, `name`, `name_key`, `code`, `code_key`, `description`, `status`, `version`, `source_template_position_id`, `created_at`, `updated_at` | scope CHECK；保留 `(id,scope_type,company_id)` 与 `(id,scope_type,company_id,project_id)` 唯一键；分 scope 唯一索引；不含组织字段 |
+| `company_position_members`          | `id`, `scope_type`, `company_id`, `position_id`, `user_id`, `created_at`                                                                                                              | scope_type 固定 company；组合 FK 约束岗位和 company member；成员-岗位唯一                                                         |
+| `project_position_members`          | `id`, `scope_type`, `company_id`, `project_id`, `position_id`, `user_id`, `created_at`                                                                                                | scope_type 固定 project；组合 FK 约束岗位和 project member；成员-岗位唯一                                                         |
+| `organization_templates`            | `id`, `company_id`, `name`, `name_key`, `description`, `status`, `is_default`, `version`, `created_at`, `updated_at`                                                                  | 企业内 name_key 唯一；active 默认模板部分唯一；version CHECK                                                                      |
+| `organization_template_units`       | `id`, `template_id`, `template_version`, `parent_id`, `name`, `name_key`, `code`, `code_key`, `description`, `sort`, `created_at`                                                     | 同版本组合父 FK、code_key 唯一；根节点与非根节点分别建立 name_key 唯一索引；sort CHECK；服务层限制 10 层                          |
+| `organization_template_positions`   | `id`, `template_id`, `template_version`, `name`, `name_key`, `code`, `code_key`, `description`, `status`, `created_at`                                                                | 同模板版本 name_key、code_key 分别唯一；不含模板组织节点字段                                                                      |
+
+### 3.2 关系完整性与生命周期
+
+- `organization_trees`、`organization_units`、`positions`、`organization_templates` 及模板版本子项使用 RESTRICT，不通过级联物理删除稳定资源。
+- 成员关系表对现有 company/project member 使用 `ON DELETE CASCADE` 仅作数据库兜底；正式成员移除必须先在同一业务事务显式删除组织关系、负责人关系和岗位任职并写审计，再删除成员，不能依赖静默级联代替审计。
+- 每张关系表复制必要 scope 键并使用组合 FK。禁止只分别 FK `memberId` 与 `unitId/positionId`，否则数据库会允许跨企业或跨项目组合。
+- `organization_trees` 的 CHECK 精确固定两种行形状：company 行为 `scope_type='company' AND company_id IS NOT NULL AND project_id IS NULL`；project 行为 `scope_type='project' AND company_id IS NOT NULL AND project_id IS NOT NULL`。project 行另以 `(company_id,project_id)` 引用既有 `projects(company_id,id)`。
+- `organization_trees` 同时建立 `UNIQUE(id,scope_type,company_id)` 与 `UNIQUE(id,scope_type,company_id,project_id)`；前者只供企业关系引用，后者只供 project_id 非空的项目关系引用。每企业一棵树使用 company 条件唯一索引，每项目一棵树使用 project 条件唯一索引。
+- 企业组织关系表不包含 nullable `project_id`，且 `scope_type/company_id/tree_id/organization_unit_id/user_id` 全部 NOT NULL；分别以 `(tree_id,scope_type,company_id)`、`(tree_id,organization_unit_id)`、`(company_id,user_id)` 引用企业树、组织单元和 company member。
+- 项目组织关系表的 `scope_type/company_id/project_id/tree_id/organization_unit_id/user_id` 全部 NOT NULL；分别以 `(tree_id,scope_type,company_id,project_id)`、`(tree_id,organization_unit_id)`、`(project_id,user_id)` 引用项目树、组织单元和 project member。
+- `positions` 使用与树相同的 company/project 行形状 CHECK，company_id 始终 NOT NULL；project 行以 `(company_id,project_id)` 引用 `projects(company_id,id)`，并明确建立 `UNIQUE(id,scope_type,company_id)` 与 `UNIQUE(id,scope_type,company_id,project_id)`。
+- 企业岗位任职表不携带 `project_id`，所有 scope 键 NOT NULL，以 `(position_id,scope_type,company_id)` 和 `(company_id,user_id)` 组合 FK；项目岗位任职表的 project_id NOT NULL，以 `(position_id,scope_type,company_id,project_id)` 和 `(project_id,user_id)` 组合 FK。关系表拆分及非空约束用于避免 PostgreSQL `MATCH SIMPLE` 因任一列为 NULL 而跳过组合 FK。
+- `organization_units` 的同父名称唯一使用两个索引：根节点 `UNIQUE(tree_id,name_key) WHERE parent_id IS NULL`，非根节点 `UNIQUE(tree_id,parent_id,name_key) WHERE parent_id IS NOT NULL`。模板节点同理，根节点使用 `UNIQUE(template_id,template_version,name_key) WHERE parent_id IS NULL`，非根节点增加 parent_id；普通含 NULL 的 UNIQUE 不能代替这两个约束。
+- 所有新增表中的 `name_key/code_key` 均以 CHECK 校验其等于 `lower(normalize(btrim(原值), NFKC))`；迁移使用同一 PostgreSQL 表达式写入，shared 规范化方法必须用包含全角、组合字符和大小写的固定语料验证与数据库结果一致。`companies` 不新增 `name_key`。
+- 既有 `companies.code` 不新增字段，改用上述规范表达式的全局唯一函数索引；既有 `projects.code` 使用 `company_id + 规范表达式` 的企业内唯一函数索引。新索引建立前必须先通过第 2.2 节预检，建立后才能移除被其覆盖的旧大小写敏感唯一约束。
+- leader 唯一使用 `WHERE duty = 'leader'` 的部分唯一索引；deputy 和 member 不受人数限制。
+- `organization_units.source_template_unit_id` 与 `positions.source_template_position_id` 可空且 RESTRICT，只有项目模板复制生成的数据填写；它们只表示来源，不建立同步关系。
+- 组织、岗位、模板均无 DELETE Controller。关系替换可以删除不再存在的关系行，历史由审计保留。
+
+### 3.3 迁移与回滚
+
+1. 数据库 `0003` 尚未应用；当前 Schema、Shared、Server、Web、测试及 `0003_cute_killmonger.sql` 仍残留企业间父子关系实现。直接同步修正该 Drizzle migration、journal、snapshot 和各实现层，删除企业间父子关系专属内容，不再追加一个先创建错误结构再回滚的修复迁移，并继续由 `apps/server/src/database/schema.ts` 导出最终 Schema。
+2. migration 的第一条事务性检查执行第 2.2 节企业／项目 code 长度、字符和规范键冲突预检；任一失败时在 DDL 与数据写入前终止，不截断、不改名、不静默转小写。
+3. 预检通过后只创建组织、岗位和模板领域所需 enum、表、规范键、约束及索引，并调整既有企业／项目 code 规范唯一索引；不得向 `companies` 添加企业父级、类型、排序或名称规范键字段。
+4. 为每个缺少树的企业和项目插入一条空 `organization_trees`，写同一迁移批次 `backfill_batch_key`。依赖作用域唯一索引使重复执行不产生第二棵树。
+5. 不推断存量成员组织关系、负责人、岗位或模板，不创建虚拟“未归属”节点。
+6. 回滚只删除当前批次创建、仍为空且没有任何引用的树；一旦出现组织单元或业务引用就拒绝自动回滚并要求人工审阅。已经存在或后续业务创建的树绝不删除。
+7. `0004_company-member-invitations.sql` 及其对应邀请代码、页面和测试是未获产品确认的实现偏差；邀请协议确认并正式写入契约前，不得把该迁移纳入组织专项迁移链、执行或作为验收证据。
+
+## 4. REST 端点
+
+第 4.1～4.5 节固定 26 个方法／路径行，其中 11 行为固定 URL，带 `{scopeBase}` 的 15 行各展开为企业和项目两条实际 URL，因此契约表共有 **41 个实际端点**：37 个新增端点、4 个修改请求 DTO 的现有端点。第 4.6 节另列 4 个不新增路由但行为随本期变化的既有端点；合计 **45 个实际受影响端点**。企业邀请端点尚未获得产品确认，不进入本组织专项或其他现行端点统计；代码中已经存在的邀请端点仅记为实现偏差。
+
+`{scopeBase}` 仅是本文简写，实际 Controller 必须显式注册：
+
+- 企业：`/companies/:companyId`
+- 项目：`/companies/:companyId/projects/:projectId`
+
+### 4.1 账号与既有创建端点
+
+| 方法与路径                                                     | 请求／返回                                                           | 权限与规则                                                                                                 |
+| -------------------------------------------------------------- | -------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
+| GET `/platform/account-candidates`                             | `GlobalAccountCandidateQuery` → `PageResult<GlobalAccountCandidate>` | purpose 只允许两种固定值；服务端据 purpose 分别要求 create 或 administrator 权限，不信任客户端自报权限 key |
+| POST `/platform/account-candidates/resolve`                    | `ResolveGlobalAccountCandidatesRequest` → `GlobalAccountCandidate[]` | 与搜索相同鉴权；最多 100 个去重 userId，按请求顺序回显                                                     |
+| POST `/platform/companies`                                     | `CreateCompanyRequest` → `CompanyDetail`                             | 修改既有请求；不再接受 `administratorAccount` 或企业层级字段；创建企业、树、成员、管理员角色与审计同事务   |
+| POST `/platform/companies/:companyId/administrator`            | `SetAdministratorRequest` → `SetAdministratorResult`                 | 修改既有请求；不再接受 account                                                                             |
+| POST `/companies/:companyId/projects`                          | `CreateProjectRequest` → `ProjectDetail`                             | 修改既有请求；不再接受 `administratorAccount`；显式 blank/template 初始化同事务                            |
+| POST `/companies/:companyId/projects/:projectId/administrator` | `SetAdministratorRequest` → `SetAdministratorResult`                 | 修改既有请求；目标必须是当前企业有效成员，不再接受 account                                                 |
+
+### 4.2 组织单元与成员关系
+
+| 方法与路径                                            | 请求／返回                                                                       | 权限与规则                                                                                                                 |
+| ----------------------------------------------------- | -------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
+| GET `{scopeBase}/organization/tree`                   | `OrganizationTreeQuery` → `OrganizationTreeRecord`                               | 对应 `*.organization.read`；按 parentId 懒加载一层，含停用节点、fullPath、effective、hasChildren，按同父 `sort ASC,id ASC` |
+| POST `{scopeBase}/organization/units`                 | `CreateOrganizationUnitRequest` → `OrganizationUnitRecord`                       | `*.organization.create`；父级省略/null 表示顶级                                                                            |
+| PATCH `{scopeBase}/organization/units/:unitId`        | `UpdateOrganizationUnitRequest` → `OrganizationUnitRecord`                       | `*.organization.update`；至少一个业务字段，sort 也走此端点                                                                 |
+| POST `{scopeBase}/organization/units/:unitId/move`    | `MoveOrganizationUnitRequest` → `OrganizationUnitRecord`                         | `*.organization.move`；同树移动，完整子树深度校验                                                                          |
+| PATCH `{scopeBase}/organization/units/:unitId/status` | `StatusRequest` → `OrganizationUnitRecord`                                       | `*.organization.update`；停用保留关系，恢复不改后代自身状态                                                                |
+| PUT `{scopeBase}/organization/members/:userId/units`  | `ReplaceMemberOrganizationUnitsRequest` → `ReplaceMemberOrganizationUnitsResult` | `*.organization.assign`；按成员全量原子替换，空数组解除该成员全部组织关系                                                  |
+| PUT `{scopeBase}/organization/units/:unitId/members`  | `ReplaceOrganizationUnitMembersRequest` → `ReplaceOrganizationUnitMembersResult` | `*.organization.assign`；按单元全量原子替换，只影响该单元，空数组清空该单元全部成员                                        |
+
+### 4.3 岗位与任职
+
+| 方法与路径                                               | 请求／返回                                                       | 权限与规则                                                                       |
+| -------------------------------------------------------- | ---------------------------------------------------------------- | -------------------------------------------------------------------------------- |
+| GET `{scopeBase}/positions`                              | `PageQuery & { status? }` → `PageResult<PositionRecord>`         | 对应 `*.positions.read`；支持名称／编码搜索，稳定按 `createdAt DESC,id DESC`     |
+| POST `{scopeBase}/positions`                             | `CreatePositionRequest` → `PositionRecord`                       | `*.positions.create`                                                             |
+| PATCH `{scopeBase}/positions/:positionId`                | `UpdatePositionRequest` → `PositionRecord`                       | `*.positions.update`；至少一个业务字段                                           |
+| PATCH `{scopeBase}/positions/:positionId/status`         | `StatusRequest` → `PositionRecord`                               | `*.positions.update`；停用保留任职关系                                           |
+| PUT `{scopeBase}/organization/members/:userId/positions` | `ReplaceMemberPositionsRequest` → `ReplaceMemberPositionsResult` | `*.positions.assign`；按成员全量原子替换，空数组解除该成员全部任职               |
+| PUT `{scopeBase}/positions/:positionId/members`          | `ReplacePositionMembersRequest` → `ReplacePositionMembersResult` | `*.positions.assign`；按岗位全量原子替换，只影响该岗位，空数组清空该岗位全部任职 |
+
+### 4.4 组织成员候选
+
+| 方法与路径                                                | 请求／返回                                                                     | 权限与规则                                                                                        |
+| --------------------------------------------------------- | ------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------- |
+| GET `{scopeBase}/organization/member-candidates`          | `OrganizationMemberCandidateQuery` → `PageResult<OrganizationMemberCandidate>` | 按 purpose 鉴权并裁剪身份；组织、岗位和项目管理员 purpose 分别使用对应最小权限                    |
+| POST `{scopeBase}/organization/member-candidates/resolve` | `ResolveOrganizationMemberCandidatesRequest` → `OrganizationMemberCandidate[]` | 与相同 purpose 的搜索使用同一鉴权和字段裁剪；最多 100 个去重 userId；未知或越权 ID 不返回占位数据 |
+
+候选端点通过 `organizationUnitIds`、`positionIds`、`roleIds`、`projectIds` 和 `unassigned` 覆盖按组织、岗位、角色、项目及未归属筛选。单组织查询通过 membershipId、duty 和固定关系排序形成可编辑成员视图；岗位 purpose 形成岗位成员视图，因此不再增加重复的只读“组织成员列表”“岗位成员列表”“未归属列表”端点。保存则分别使用第 4.2、4.3 节按成员或按资源全量替换的写端点。
+
+- `purpose=browseOrganization` 要求对应 `*.organization.read`；`positionIds` 及岗位标签另要求 `*.positions.read`，`roleIds` 及角色标签另要求既有 `*.roles.read`。
+- `purpose=assignPositionMembers` 要求对应 `*.positions.read` 与 `*.positions.assign`，不要求 `*.organization.read`；身份字段和允许筛选按第 2.8 节最小化。
+- 企业 browse 的 `projectIds` 及任何项目 identity 首先要求既有 `company.projects.read`，并继续按调用者实际可见项目裁剪；每个项目的组织、岗位、角色标签及相应筛选再分别要求该项目的 `project.organization.read`、`project.positions.read`、`project.roles.read`。项目端不接受 `projectIds`。
+- 两个项目管理员 purpose 与 `addProjectMember` 的搜索、resolve 均直接复用本端点，不新增通用“企业成员枚举”接口；其最小权限、允许字段和脱敏响应固定按第 2.8 节执行。
+
+企业直接注册与项目成员写入端点沿用既有成员接口，不计入本组织专项契约表；候选端点仍只增加本契约已统计的两条路由。企业邀请协议及端点待产品确认，现有邀请端点不得计入组织专项或其他现行契约统计。
+
+### 4.5 企业项目组织模板
+
+| 方法与路径                                                              | 请求／返回                                                               | 权限与规则                                                                                |
+| ----------------------------------------------------------------------- | ------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------- |
+| GET `/companies/:companyId/organization/templates`                      | `PageQuery & { status? }` → `PageResult<OrganizationTemplateSummary>`    | `company.organization.templates.read`；列表只返回 unitCount/positionCount，不返回完整定义 |
+| GET `/companies/:companyId/organization/templates/:templateId`          | → `OrganizationTemplateRecord`                                           | 同上；返回当前版本完整定义                                                                |
+| POST `/companies/:companyId/organization/templates`                     | `CreateOrganizationTemplateRequest` → `OrganizationTemplateRecord`       | `company.organization.templates.create`；整个模板聚合创建                                 |
+| PUT `/companies/:companyId/organization/templates/:templateId`          | `ReplaceOrganizationTemplateRequest` → `OrganizationTemplateRecord`      | `company.organization.templates.update`；显式 isDefault、完整替换并新增不可变子项版本快照 |
+| PATCH `/companies/:companyId/organization/templates/:templateId/status` | `UpdateOrganizationTemplateStatusRequest` → `OrganizationTemplateRecord` | `company.organization.templates.update`；复制完整子项快照到下一版本，再变更状态／默认标记 |
+
+### 4.6 既有行为变更端点
+
+以下 4 个端点不新增路由，也不计入第 4.1～4.5 节的 26 个方法／路径行，但实现与测试必须纳入本期总计 45 个实际受影响端点：
+
+- `POST /companies/:companyId/members`：请求只允许直接注册新账号，不接受既有 `userId` 或旧 `{ account }` 精确挂接；账号、企业成员、默认角色与审计同事务。
+- `POST /companies/:companyId/projects/:projectId/members`：请求固定为 `{ userId }`；目标必须是直属企业有效成员且尚未加入当前项目，写事务内重新校验。
+- `DELETE /companies/:companyId/members/:memberId`：沿用现有请求 DTO，增加第 9 节企业成员关联清理及审计数量。
+- `DELETE /companies/:companyId/projects/:projectId/members/:memberId`：沿用现有请求 DTO，增加第 9 节项目成员关联清理及审计数量。
+
+## 5. 权限目录与页面
+
+本期新增 **21 个权限 key**。页面 `.read` 及其操作必须同时进入 `ACCESS_PAGE_CATALOG`、`ACCESS_PERMISSION_CATALOG`、菜单种子、Web page registry 和路由模块，并提升 `ACCESS_CATALOG_VERSION`。操作权限仍依赖所属页面 `.read`。
+
+| scope   | routeKey／既有页面               | Web 路径                                                 | 新增权限 key                                      |
+| ------- | -------------------------------- | -------------------------------------------------------- | ------------------------------------------------- |
+| company | `company.organization`           | `/companies/:companyId/organization`                     | `.read`, `.create`, `.update`, `.move`, `.assign` |
+| company | `company.positions`              | `/companies/:companyId/positions`                        | `.read`, `.create`, `.update`, `.assign`          |
+| company | `company.organization.templates` | `/companies/:companyId/organization/templates`           | `.read`, `.create`, `.update`                     |
+| project | `project.organization`           | `/companies/:companyId/projects/:projectId/organization` | `.read`, `.create`, `.update`, `.move`, `.assign` |
+| project | `project.positions`              | `/companies/:companyId/projects/:projectId/positions`    | `.read`, `.create`, `.update`, `.assign`          |
+
+表中以点开头的后缀须与 routeKey 拼接，例如 `company.organization.assign`。新增数量为 5 + 4 + 3 + 5 + 4 = 21。平台企业管理沿用既有权限，不新增企业层级权限。
+
+- 平台账号候选不新增通用“搜索所有账号”权限。`purpose=createCompanyAdministrator` 要求 `platform.companies.create` 且为平台内置管理员；`purpose=setCompanyAdministrator` 要求 `platform.companies.administrator` 且为平台内置管理员。
+- 项目管理员候选不新增权限 key。`purpose=createProjectAdministrator` 只复用 `company.projects.create`，`purpose=setProjectAdministrator` 只复用 `company.projects.administrator`；两者沿用既有 adminOnly 规则，但均不隐式要求组织或成员页面 read。
+- 项目模板初始化同时要求既有 `company.projects.create` 与 `company.organization.templates.read`；blank 创建不要求模板读取权限。
+- 候选接口不能因为用户有页面 read 就泄露所有角色或项目标签；只返回其在当前端点策略下可见的身份摘要。
+- 组织负责人、组织归属和岗位不会自动生成任何权限 key，也不会授予 RBAC 角色。
+- 不新增 `company.organization.publish`、`project.workflow.*`、企业目标或任务级授权权限。
+
+## 6. 事务、并发、查询与审计
+
+### 6.1 写事务
+
+- 所有本期管理写操作继续使用 PostgreSQL `pg_advisory_xact_lock(7421, 1)`。取得锁后必须重新执行登录状态、作用域成员资格、管理员身份、页面+操作权限、资源归属和 expectedVersion 校验。
+- 写事务沿用现有 READ COMMITTED；组织默认 sort、组织循环／深度、leader 唯一、模板版本与默认模板唯一都在锁内基于最新已提交状态计算。
+- 企业创建、项目创建／模板复制、按成员或按组织单元／岗位的批量关系替换、成员移除清理、模板定义／状态快照和对应成功审计必须在同一事务提交。任何步骤失败全部回滚，且没有成功审计。
+- 数据库唯一索引是并发兜底，服务层应把已知约束映射为约定业务错误；未知数据库或程序异常交全局过滤器，不做大范围 catch 后伪装成 503。
+
+### 6.2 只读查询
+
+- 组织树、模板详情和候选聚合等多查询读取继续使用 REPEATABLE READ + READ ONLY，确保树、路径、成员标签和分页总数来自同一快照。
+- Repository 查询必须在 SQL 条件中同时约束 companyId/projectId/treeId；禁止先按裸 ID 读取其他租户资源再在 Controller 过滤。
+- 候选搜索 trim 后最多 100 字，分页沿用默认 20、最大 100；数组筛选每类最多 100 个去重 UUID。
+
+### 6.3 审计动作
+
+新增固定 action：
+
+```text
+organization.unit.create
+organization.unit.update
+organization.unit.move
+organization.unit.status
+organization.members.replace
+position.create
+position.update
+position.status
+position.members.replace
+organization_template.create
+organization_template.replace
+organization_template.status
+project.organization.initialize
+```
+
+- action 的企业／项目范围由 `AuditRecord.scope` 区分，不复制两套 action 名。
+- 摘要只保存对象 ID、changedFields、from/to、数量、目标 userId、模板 ID／版本等白名单；不得记录密码、token、完整请求体或不必要的成员信息。
+- `organization.members.replace` 与 `position.members.replace` 同时复用于按成员和按资源替换；摘要必须记录替换方向、目标 userId／organizationUnitId／positionId、变更前后数量及新增／移除／职责变化数量，不能只记录入口名称。
+- 设置新默认模板时，目标模板按入口写 `organization_template.create`、`organization_template.replace` 或 `organization_template.status`；被自动取消默认的旧模板另写一条 `organization_template.status`，摘要记录旧／新 version 与 `isDefault: true → false`。相关审计与完整子项版本快照在同一事务提交。
+- 企业／项目成员移除的既有审计摘要增加 `removedOrganizationRelationCount`、`removedPositionAssignmentCount`，但仍保持原 action。
+
+## 7. 错误码与状态语义
+
+本期复用既有通用错误目录，并新增 **7 个领域错误码**。
+
+| HTTP | code                                  | 场景                                                                                                                           |
+| ---- | ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
+| 400  | `COMMON.VALIDATION_FAILED`            | strict DTO、UUID、未知字段、非法枚举、请求内重复、筛选／resolve 等明确要求非空的数组为空、分页和 sort 范围；关系替换空数组合法 |
+| 401  | 既有 `AUTH.*`                         | 会话或账号失效                                                                                                                 |
+| 403  | `ACCESS.FORBIDDEN`                    | 当前作用域已识别但缺少页面／操作权限或内置管理员资格                                                                           |
+| 404  | `ACCESS.NOT_FOUND`                    | 目标账号、成员或资源不存在，或其属于其他企业、项目、组织树时统一返回；不得用该响应暴露跨作用域存在性                           |
+| 409  | `ACCESS.VERSION_CONFLICT`             | 组织、岗位、模板 PUT／状态 PATCH 等 expectedVersion 过期                                                                       |
+| 409  | `ACCESS.DUPLICATE_RESOURCE`           | 已持久化的组织名称／编码、岗位名称／编码、模板名称或企业／项目 code 规范唯一冲突                                               |
+| 409  | `ACCESS.RESOURCE_IN_USE`              | 数据库 RESTRICT 保护的稳定引用仍被使用                                                                                         |
+| 409  | `ACCESS.ORGANIZATION_CYCLE`           | 组织单元移动形成自身／后代循环                                                                                                 |
+| 409  | `ACCESS.ORGANIZATION_DEPTH_EXCEEDED`  | 创建、移动或模板复制后超过 10 层                                                                                               |
+| 409  | `ACCESS.ORGANIZATION_LEADER_CONFLICT` | 同一组织单元出现第二名 leader                                                                                                  |
+| 409  | `ACCESS.ORGANIZATION_SORT_EXHAUSTED`  | 省略 sort 时同级最大值已经达到上限                                                                                             |
+| 422  | `ACCESS.INVALID_MEMBER_RELATION`      | 已确认属于当前作用域，但账号／成员状态无效、负责人资格无效或候选状态不可用于新增、升级关系                                     |
+| 409  | `ACCESS.TEMPLATE_VERSION_CONFLICT`    | 项目 template 初始化提交的 templateVersion 不是模板当前版本                                                                    |
+| 422  | `ACCESS.TEMPLATE_UNAVAILABLE`         | 已确认属于项目直接企业，但模板已停用、目标默认状态非法或不能用于新项目                                                         |
+| 500  | `COMMON.INTERNAL_SERVER_ERROR`        | 未知错误，底层信息不公开                                                                                                       |
+
+新增 7 个错误码为：`ORGANIZATION_CYCLE`、`ORGANIZATION_DEPTH_EXCEEDED`、`ORGANIZATION_LEADER_CONFLICT`、`ORGANIZATION_SORT_EXHAUSTED`、`INVALID_MEMBER_RELATION`、`TEMPLATE_VERSION_CONFLICT`、`TEMPLATE_UNAVAILABLE`。
+
+## 8. 前端组件与状态契约
+
+- `Selector/src/Selector.tsx` 继续只做出口归类；`BasicTableSelector`、`GlobalAccountSelect`、`OrganizationMemberSelector` 分别作为独立功能目录，不增加一个庞大 mode 组件。
+- `GlobalAccountSelect` 是平台账号远程搜索单选，稳定值为 userId，由业务注入 search/resolve request；编辑回显使用候选快照，不从名称反查。
+- `OrganizationMemberSelector` 是 Select 风格表单字段 + 弹窗组织浏览器。左侧为当前可见作用域／组织／岗位／角色筛选，右侧为分页人员和已选区；组织节点只做筛选值，已选值统一为 userId，不持久化候选 identity 的 scope。
+- 组织树按层懒加载，节点缓存键必须包含完整 AccessScope 与 parentId；`hasChildren=false` 时不得继续请求子节点。由于节点缓存包含 fullPath、depth、effective，重命名、移动或状态变更必须失效受影响节点及所有后代，同时失效会改变 `hasChildren` 的原／新父级列表；如果前端没有可靠的后代依赖索引，必须直接清空当前 AccessScope 的整棵树缓存，不能只失效父级或祖先。
+- 企业页面和项目页面各自从现有 workspace 路由进入，页面内部不再提供第二套企业／项目切换器。请求、树、筛选、分页、已选缓存键必须包含完整 AccessScope；切换工作空间时取消旧请求并清空旧状态。
+- 同名人员显示姓名、完整账号和来源作用域；同名组织显示企业／项目名称及 fullPath；组织标签与岗位标签分栏，不暗示关联。
+- 401 清登录状态，403 刷新一次 access context，404 显示统一不可见，409 保留表单并提示刷新，422 展示可修正业务原因。前端禁用只是体验，服务端始终二次校验 userId 与作用域。
+
+## 9. 成员移除与状态清理
+
+- 移除项目成员：锁内删除该项目的组织关系（包含 leader/deputy）、岗位任职和项目 user_roles，再删除 project member，写一条既有成员移除审计及清理数量。
+- 移除企业成员：锁内先按现有规则处理该企业直接项目中的项目成员及其组织／岗位／角色关系，再清本企业组织关系、岗位任职和 company user_roles，最后删除 company member。
+- 停用成员不删除组织或岗位关系，但不再作为新增关系的有效候选；恢复后按当前保存关系重新可见。停用期间允许全量替换请求原样保留或移除既有关系，并允许组织职责降级；禁止新增关系或职责升级。停用组织单元／岗位遵循同一“可保留、可解除、不可新增”规则。
+- 任何企业清理不得触碰该 userId 在其他企业中的独立成员、组织、岗位或角色关系。
+
+## 10. 验收追踪矩阵
+
+| PRD 验收项                | 契约保障                                                       | 必测证据                                              |
+| ------------------------- | -------------------------------------------------------------- | ----------------------------------------------------- |
+| AC-01～AC-02 身份与作用域 | userId 稳定值；AccessScope 不扩枚举                            | 同名账号、三作用域回归                                |
+| AC-03～AC-06 独立企业边界 | companies 模型保持不变；无企业树端点／权限；项目直接 companyId | 禁止字段／端点全仓扫描、跨企业隔离、项目直接归属      |
+| AC-07～AC-12 组织树与排序 | 独立 tree、组合 FK、10 层、单整数 sort、移动端点               | 跨树 404、深度、默认和显式排序、移动保持 ID           |
+| AC-13～AC-18 组织成员     | 两类关系表、集合替换、duty、leader 唯一、未归属查询            | 多组织、无主归属、冲突整批回滚、默认顺序              |
+| AC-19～AC-21 岗位         | 平面 positions、两类任职表、strict DTO、无组织字段             | 多岗多人、规范唯一、组织／角色无联动                  |
+| AC-22～AC-25 模板与迁移   | 显式 union、子项版本快照、来源 ID、创建事务、backfill 批次     | blank/template 非法组合、复制边界、独立演进、幂等回滚 |
+| AC-26～AC-31 页面与选择器 | workspace 路由隔离、两类选择器、候选与保存契约                 | 快切无旧数据、分页去重、同名展示、禁选、账号边界      |
+| AC-32～AC-35 权限与安全   | 21 key、SQL 作用域、稳定资源仅状态、同事务审计                 | 前后端权限一致、跨域 404、清理范围、失败无成功审计    |
+| AC-36 排除范围            | 第 11 节禁止清单                                               | schema/types/routes 全仓扫描无禁用概念                |
+
+后续 QA 必须逐条回填 AC-01～AC-36 的自动化或人工证据；上表归组不表示可以省略任一条验收标准。
+
+## 11. 明确排除与禁止字段
+
+本期不得新增以下表、字段、DTO、端点、权限或 UI：
+
+- 项目小组或第四种组织／访问作用域。
+- 企业间父子关系，以及企业级父级、企业类型、企业名称规范键、企业排序同义字段、企业树查询／移动端点、企业层级权限或审计动作。
+- 主归属、默认组织、primaryOrganization、isPrimary 等同义字段。
+- 任何成员手工排序字段或双框排序交互。
+- 岗位到组织单元、组织树、模板组织节点的持久关联。
+- 企业目标发布、WorkflowTargetSelector、运行时接收人解析、任务参与者、任务级资源／附件授权、流程转交机制或可执行工作流引擎。
+
+“项目 → 直接所属企业”仅是后续工作流专项的首个推荐方向，本期不建表、不加接口、不加权限、不计入验收完成。
+
+## 12. 前后端并行边界与确认门
+
+契约确认后的实施顺序固定为：
+
+1. 契约／架构负责人先独占 `packages/shared`、数据库 schema 与 migration，完成共享导出、权限／错误目录、空库和存量库迁移验证。
+2. 共享契约稳定后，后端负责 `apps/server` 的 Controller、Service、Repository、事务、审计与集成测试；前端负责 `apps/web` 的路由、页面、选择器和组件测试，两边并行但只消费 shared 类型。
+3. 集成阶段验证全部 45 个实际受影响端点（41 个契约表端点及 4 个既有行为变更端点）、21 个权限 key、7 个组织领域新增错误码、成员移除清理和 AC-01～AC-36；企业邀请细节确认后另行进入成员接入契约和验证范围，现有邀请实现不得提前计入。
+4. QA 默认使用真实 PostgreSQL 集成测试和 Playwright 覆盖关键 Web 流程；环境无法验证必须明确标记，不能算通过。
+
+### 变更与确认记录
+
+用户于 2026-09-16 明确回复“确认，继续”，并于 2026-09-17 明确取消企业间父子关系；2026-09-18 进一步澄清企业邀请只确认入口，具体协议尚未确认。企业独立决定覆盖初版契约中所有企业层级字段、端点、权限、审计与验收语义；当前实施基线为：
+
+1. 账号管理员接口按同版本破坏性迁移，从 `administratorAccount` 一次切换到 `administratorUserId`，不提供双字段兼容期。
+2. 数据层按 10 张新表、97 个新增字段落地；不向 `companies` 增加企业父级、类型、排序或名称规范键字段；模板定义采用保留历史子项的版本快照。
+3. 接口和授权按 41 个契约表实际端点（37 个新增、4 个修改请求 DTO）及另 4 个既有行为变更端点实施，总计 45 个实际受影响端点；同时固定 21 个新增权限 key、7 个组织领域新增错误码，不由实现阶段删并端点或改名。企业邀请端点尚未确认，不计入任何现行契约统计。
+4. 写事务使用 READ COMMITTED + 全局管理锁，聚合只读使用 REPEATABLE READ + READ ONLY；业务变更和成功审计保持同事务。
+5. 平台企业继续按独立列表管理；企业与企业之间不存在父子关系，每个企业和每个项目只维护各自的一棵组织树。
+6. 企业普通成员新增只确认直接注册和邀请两个产品入口；邀请入口之后的对象、流程、状态与技术协议全部待确认。项目普通成员从所属企业有效成员中按 `userId` 选择，候选排除已加入者，写入时由服务端重新校验。
+
+除明确列为待确认的企业邀请协议外，本契约不把架构空白留给前端或后端自行决定。现有邀请代码、页面、自动化测试及 `0004` 不能代替产品确认；后续形成完整邀请规则时，须先更新需求、设计和契约并重新确认。
+
+| 日期       | 变更摘要                                                                                               | 原因                         | 影响范围                                     |
+| ---------- | ------------------------------------------------------------------------------------------------------ | ---------------------------- | -------------------------------------------- |
+| 2026-09-18 | 邀请口径纠偏为“只确认入口，具体协议待确认”；撤回既有端点数量、固定有效期、Token 和接受流程等未确认契约 | 现有实现不能反向定义产品协议 | 成员边界、迁移、端点统计、确认门、联调与测试 |
+| 2026-09-18 | 明确 Schema、Shared、Server、Web、测试及 `0003` 当前仍残留企业层级                                     | 区分目标契约和实际实现状态   | 迁移、发布阻断与复验                         |
+| 2026-09-17 | 取消企业之间的父子层级                                                                                 | 最新企业边界确认             | 字段、表、端点、权限、审计、迁移与验收       |
+| 2026-09-17 | 企业成员改为直接注册／邀请；项目成员改为企业有效成员候选 `userId` 选择                                 | 最新成员边界确认             | 候选 purpose、成员写接口约束、错误与测试     |