合并 feat/org-directory:成员目录(Keycloak 读写面穿透)+ 治理台成员/组织/权限三页 + 广播桥回弹修复 + 稳定版脚本 + W05 目标件

分支四条(2026-08-26 做的,一直留在工作树没入库,今天补提交):
① feat(org) 成员目录 —— KeycloakDirectory 端口与适配器、org-directory 契约/路由、sync-roster CLI、
   personName 姓在前、Staff.kind 按账号名现判;前端员工屏重做成成员 / 组织 / 权限三页签;
② fix(app) 广播桥「转发进来的不再 NOTIFY 回去」—— 两台后端互桥回弹 19 万条广播那次的修复,代码此前没入库;
③ chore stable.sh + .stable/ 入 ignore + vite preview 宿主白名单;
④ docs(w05) 目标件五份 HTML 与三份说明、实施计划、三张图。

冲突六处,全在 org 后端「姓在前」上 —— 主支(0c029b6,shanqin)与分支同日各做了一版:
主支拼「姓 名」留空格,分支 personName 汉字直拼(「柴浩」)、非汉字留空格(「Admin Amy」),
且分支那版是超集(服务账号识别、名册同步走同一把尺)。取分支版:port.ts / claims.ts /
keycloak-token-verifier.ts / keycloak-admin-roster.ts 及其测试按分支;主支那条 claims 测试
(「亲 删」→ 姓在前)保留,期望从「删 亲」改为「删亲」。api-report 重生成。

五道门禁绿:2096 测试通过、23 跳过(无模型密钥 / 无真信箱的惯常项)。

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0167qWjeyBwvfdGovd7FWbCu

.gitignore

@@ -21,3 +21,6 @@ coverage/
 
 # SDD 工作区(ledger / brief / 评审包)—— 记录归 git 历史,过程件不入库
 .superpowers/
+
+# 稳定版快照与运行态(./stable.sh 写的)
+.stable/

api-report/apps/api/src/modules/org/contract.d.ts

@@ -5,8 +5,27 @@
  * 本模块管三件事:①验签后的人是谁(名册即时更新);②他能进哪几个端(角色→端);③岗位与工作组。
  * 口令 / 会话 / 岗位授权(客体三类 × 动作三种)已退役。
  */
-import type { InFlightWork, Position, PositionId, Principal, RoleAccess, RosterSyncOutcome, Staff, StaffId, Surface, WorkGroup, WorkGroupBinding } from '@contracts';
+import type { InFlightWork, OrgGroup, OrgRole, OrgUser, OrgUserDetail, Position, PositionId, Principal, RoleAccess, RosterSyncOutcome, Staff, StaffId, Surface, WorkGroup, WorkGroupBinding } from '@contracts';
-export type { InFlightWork, Position, Principal, RoleAccess, RosterSyncOutcome, Staff, Surface, WorkGroup, WorkGroupBinding };
+export type { InFlightWork, OrgGroup, OrgRole, OrgUser, OrgUserDetail, Position, Principal, RoleAccess, RosterSyncOutcome, Staff, Surface, WorkGroup, WorkGroupBinding };
+/**
+ * 目录写面的两个入参 —— 住在 contract.ts 而不是 port.ts:它们是**服务出口的形状**
+ * (路由照它填),port 只是恰好也要用。反过来放会让 port ↔ contract 成环。
+ */
+export type CreateDirectoryUser = {
+    readonly username: string;
+    readonly firstName?: string;
+    readonly lastName?: string;
+    readonly email?: string;
+    /** 临时口令;不给就建一个还登不进来的壳 */
+    readonly password?: string;
+    /** 一并授的 realm 角色 */
+    readonly roles?: readonly string[];
+};
+export type DirectoryUserPatch = {
+    readonly firstName?: string;
+    readonly lastName?: string;
+    readonly email?: string;
+};
 /** 员工连同其岗位的读模型 —— 治理台员工管理列表用 */
 export type StaffWithPosition = Staff & {
     readonly position: Position;
@@ -47,6 +66,24 @@ export declare class AccountDisabledError extends Error {
 export declare class AccessLockoutError extends Error {
     constructor(message?: string);
 }
+/**
+ * 目录整个不可用 —— 没配 provisioning 服务账号,或那个账号缺 realm-management 角色。
+ * **重试无益**:路由译成 502 并原样带出 Keycloak 的话,界面提示找管理员补权限(手册 §14.6)。
+ */
+export declare class DirectoryUnavailableError extends Error {
+    /** true = 配错了(补权限);false = 暂时够不着(可退避重试)—— 两句话,人的下一步不同 */
+    readonly misconfigured: boolean;
+    constructor(message: string, misconfigured: boolean);
+}
+/**
+ * 写面对着一个服务账号 —— 拒。它是 Keycloak 给 client 自动建的身份(见 `staffKindSchema`),
+ * 在这三个页签里**根本不该出现**;能对着它下手,只能是有人手输了 sub。
+ * 停掉它的后果不显眼却很重:试跑与 e2e 第二天全趴下。
+ */
+export declare class ServiceAccountProtectedError extends Error {
+    readonly account: string;
+    constructor(account: string);
+}
 export type OrgService = {
     /** 验签 → 名册即时更新 → 角色→端。抛 TokenRejectedError(401)/ AccountDisabledError(403) */
     authenticate(token: string): Promise<Principal>;
@@ -75,6 +112,39 @@ export type OrgService = {
     deleteRoleAccess(role: string): Promise<void>;
     /** 能进该端的活跃员工 —— 治理台通知的收件人 */
     staffWithEnd(surface: Surface): Promise<StaffWithPosition[]>;
+    /**
+     * 目录**没配 provisioning 服务账号就整个不可用** —— 一律抛 `DirectoryUnavailableError`
+     * (路由译成 502 + 原话)。不给「读得了写不了」这种半开状态:那样人会以为是自己点错了。
+     * 服务账号在这一层就剔干净;写面对着服务账号的 sub 一律抛 `ServiceAccountProtectedError`。
+     */
+    directoryUsers(query: {
+        q?: string;
+        includeDisabled?: boolean;
+    }): Promise<{
+        users: OrgUser[];
+    }>;
+    directoryUser(sub: string): Promise<OrgUserDetail>;
+    createDirectoryUser(input: CreateDirectoryUser): Promise<OrgUser>;
+    patchDirectoryUser(sub: string, patch: DirectoryUserPatch): Promise<OrgUser>;
+    /** 停用顺手踢会话 —— 界面写了「已停用」,那枚 token 就不该还能用到过期 */
+    setDirectoryUserEnabled(sub: string, enabled: boolean): Promise<OrgUser>;
+    resetDirectoryUserPassword(sub: string, password: string): Promise<void>;
+    deleteDirectoryUser(sub: string): Promise<void>;
+    directoryRoles(): Promise<{
+        roles: OrgRole[];
+    }>;
+    /** 授 / 收一个 realm 角色;收权顺手踢会话。抛 AccessLockoutError(409):收完没人进得了运营中心 */
+    setDirectoryUserRole(sub: string, role: string, granted: boolean): Promise<OrgUser>;
+    directoryGroups(): Promise<{
+        groups: OrgGroup[];
+    }>;
+    directoryGroupMembers(groupId: string): Promise<{
+        members: OrgUser[];
+    }>;
+    createDirectoryGroup(name: string, parentId?: string): Promise<OrgGroup>;
+    renameDirectoryGroup(groupId: string, name: string): Promise<OrgGroup>;
+    deleteDirectoryGroup(groupId: string): Promise<void>;
+    setDirectoryUserGroup(sub: string, groupId: string, member: boolean): Promise<void>;
     /** 建组 / 改组;id 留空即新建 */
     saveWorkGroup(input: {
         id?: string;

api-report/apps/api/src/modules/org/index.d.ts

@@ -1,18 +1,22 @@
 /**
  * module: org —— 唯一出口。只做 re-export,不写逻辑(编码规范 §10.1)。
  */
-export type { Identity, InFlightWork, OrgService, Position, Principal, RoleAccess, RosterSyncOutcome, Staff, StaffWithPosition, Surface, WorkGroup, WorkGroupBinding, } from './contract.ts';
+export type { CreateDirectoryUser, DirectoryUserPatch, Identity, InFlightWork, OrgGroup, OrgRole, OrgService, OrgUser, OrgUserDetail, Position, Principal, RoleAccess, RosterSyncOutcome, Staff, StaffWithPosition, Surface, WorkGroup, WorkGroupBinding, } from './contract.ts';
-export { AccessLockoutError, AccountDisabledError, PositionNotFoundError, StaffNotFoundError, TokenRejectedError, } from './contract.ts';
+export { AccessLockoutError, AccountDisabledError, DirectoryUnavailableError, PositionNotFoundError, ServiceAccountProtectedError, StaffNotFoundError, TokenRejectedError, } from './contract.ts';
-export type { Clock, IdGenerator, IdentityPatch, InFlightWorkProbe, PositionRepository, RoleAccessRepository, RosterSource, RosterUser, StaffRecord, StaffRepository, TokenVerifier, VerifiedClaims, WorkGroupRepository, } from './port.ts';
+export type { Clock, DirectoryGroup, DirectoryRole, DirectoryUser, IdGenerator, IdentityPatch, InFlightWorkProbe, KeycloakDirectory, PositionRepository, RoleAccessRepository, RosterSource, RosterUser, StaffRecord, StaffRepository, TokenVerifier, VerifiedClaims, WorkGroupRepository, } from './port.ts';
 export type { OrgServiceDeps } from './internal/usecase/org-service.ts';
 export { createOrgService } from './internal/usecase/org-service.ts';
 export { identityOf, isNoiseRole, normalizeRoles } from './internal/domain/claims.ts';
 export { assertNotLockedOut, endsOf, normalizeEnds } from './internal/domain/ends.ts';
+export { displayNameOf, filterOrgUsers, isServiceAccount, sortOrgUsers, toOrgGroups, toOrgRoles, toOrgUser, } from './internal/domain/directory.ts';
 export { buildInFlightWork } from './internal/domain/in-flight.ts';
 export { DEFAULT_ROLE_ACCESS, NONE_POSITION_CODE, POSITION_SEED, TEST_POSITION_CODE } from './internal/domain/seed-data.ts';
 export { createKeycloakTokenVerifier, explainJoseError } from './internal/adapter/keycloak-token-verifier.ts';
 export type { KeycloakVerifierOptions } from './internal/adapter/keycloak-token-verifier.ts';
 export { createKeycloakRoster } from './internal/adapter/keycloak-admin-roster.ts';
 export type { KeycloakRosterOptions } from './internal/adapter/keycloak-admin-roster.ts';
+export { createKeycloakDirectory } from './internal/adapter/keycloak-directory.ts';
+export { createAdminHttp, KeycloakMisconfiguredError, KeycloakRejectedError, KeycloakUnavailableError } from './internal/adapter/keycloak-admin-http.ts';
+export type { AdminHttp, KeycloakAdminOptions } from './internal/adapter/keycloak-admin-http.ts';
 export { createPositionRepository, createRoleAccessRepository, createStaffRepository, createWorkGroupRepository, } from './internal/adapter/org-repository.ts';
 export { positionTable, roleAccessTable, staffTable, workGroupTable } from './internal/adapter/org-schema.ts';

api-report/apps/api/src/modules/org/port.d.ts

@@ -3,7 +3,7 @@
  * adapter 实现之,usecase 依赖之,app 装配之。
  */
 import type { Position, PositionId, RoleAccess, Staff, StaffId, WorkGroup } from '@contracts';
-import type { Identity } from './contract.ts';
+import type { CreateDirectoryUser, DirectoryUserPatch, Identity } from './contract.ts';
 export type Clock = {
     now(): Date;
 };
@@ -11,8 +11,11 @@ export type Clock = {
 export type VerifiedClaims = {
     readonly sub: string;
     readonly preferred_username: string;
+    /** Keycloak 拼好的 `firstName lastName` —— 西式顺序,只在拆不开时才用它 */
     readonly name?: string;
+    /** 名(firstName) */
     readonly given_name?: string;
+    /** 姓(lastName)—— 我们按「姓在前」自己拼,见 `personName` */
     readonly family_name?: string;
     readonly email?: string;
     readonly realm_access?: {
@@ -30,6 +33,65 @@ export type RosterUser = Identity & {
 export type RosterSource = {
     listUsers(): Promise<readonly RosterUser[]>;
 };
+/**
+ * Keycloak 那一侧的一个用户 —— **原样的形状**,不掺本地字段。
+ * 与 `RosterUser` 的区别:名册只要「同步要比对的那几列」,目录要摆给人看的全部。
+ */
+export type DirectoryUser = {
+    readonly sub: string;
+    readonly username: string;
+    readonly firstName?: string;
+    readonly lastName?: string;
+    readonly email?: string;
+    readonly enabled: boolean;
+    readonly emailVerified: boolean;
+    /** realm 角色(家具角色已滤) */
+    readonly roles: readonly string[];
+};
+/** 组树里的一行 —— 平表,层级看 `parentId` / `depth`(契约同款,理由见 org-directory.ts) */
+export type DirectoryGroup = {
+    readonly id: string;
+    readonly name: string;
+    readonly path: string;
+    readonly parentId?: string;
+    readonly depth: number;
+    readonly memberCount: number;
+};
+export type DirectoryRole = {
+    readonly name: string;
+    readonly description?: string;
+    readonly composite: boolean;
+};
+/**
+ * 成员目录 —— app 未配 provisioning 服务账号时不注入(与 `RosterSource` 同款)。
+ * 读是投影,写**直接穿透**到 Keycloak:这里建的人立刻能登录,这里删的人从 Keycloak 消失。
+ */
+export type KeycloakDirectory = {
+    listUsers(): Promise<readonly DirectoryUser[]>;
+    getUser(sub: string): Promise<DirectoryUser & {
+        readonly groups: ReadonlyArray<{
+            id: string;
+            path: string;
+        }>;
+    }>;
+    createUser(input: CreateDirectoryUser): Promise<string>;
+    updateUser(sub: string, patch: DirectoryUserPatch): Promise<void>;
+    setEnabled(sub: string, enabled: boolean): Promise<void>;
+    resetPassword(sub: string, password: string): Promise<void>;
+    deleteUser(sub: string): Promise<void>;
+    /** 踢掉此人全部会话 —— 停用与收权之后必调,否则旧 token 到期前照样通行 */
+    logout(sub: string): Promise<void>;
+    listRoles(): Promise<readonly DirectoryRole[]>;
+    setRole(sub: string, role: string, granted: boolean): Promise<void>;
+    listGroups(): Promise<readonly DirectoryGroup[]>;
+    groupMembers(groupId: string): Promise<readonly DirectoryUser[]>;
+    /** 组的直属成员用户名 —— 组树只要个数,别为了数数把每个人的角色都拉一遍 */
+    groupMemberUsernames(groupId: string): Promise<readonly string[]>;
+    createGroup(name: string, parentId?: string): Promise<DirectoryGroup>;
+    renameGroup(groupId: string, name: string): Promise<DirectoryGroup>;
+    deleteGroup(groupId: string): Promise<void>;
+    setUserGroup(sub: string, groupId: string, member: boolean): Promise<void>;
+};
 /** 名册即时更新 / 同步要改的那几列 */
 export type IdentityPatch = {
     readonly account: string;
@@ -47,7 +109,12 @@ export type PositionRepository = {
     }): Promise<Position>;
 };
 /** 员工行 —— 契约 Staff 之外还带两枚时刻,只给用例判「要不要再写一次」,不出模块 */
-export type StaffRecord = Staff & {
+/**
+ * 库里真存着的那几列。`Staff.kind` 不在其中 —— 它由账号名现判(见 `staffKindSchema`),
+ * 存一列就会与账号名分叉,而分叉之后没人看得出以哪份为准。
+ */
+export type StoredStaff = Omit<Staff, 'kind'>;
+export type StaffRecord = StoredStaff & {
     readonly lastSeenAt?: Date;
     readonly syncedAt?: Date;
 };
@@ -57,7 +124,7 @@ export type StaffRepository = {
     /** 按账号找 —— `account` 有唯一索引,建档前得先问一句「这个名字被谁占着」(同名让位) */
     findByAccount(account: string): Promise<StaffRecord | undefined>;
     listByPosition(positionId: PositionId): Promise<StaffRecord[]>;
-    insert(staff: Staff, marks: {
+    insert(staff: StoredStaff, marks: {
         readonly lastSeenAt?: Date;
         readonly syncedAt?: Date;
     }): Promise<StaffRecord>;

api-report/packages/contracts/src/api/governance.d.ts

@@ -19,6 +19,10 @@ export declare const listStaffRoute: {
                 disabled: "disabled";
             }>>;
             roles: z.ZodDefault<z.ZodArray<z.ZodString>>;
+            kind: z.ZodDefault<z.ZodEnum<{
+                person: "person";
+                service: "service";
+            }>>;
             position: z.ZodObject<{
                 id: z.core.$ZodBranded<z.ZodString, "PositionId", "out">;
                 code: z.ZodString;
@@ -55,6 +59,10 @@ export declare const createStaffRoute: {
             disabled: "disabled";
         }>>;
         roles: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        kind: z.ZodDefault<z.ZodEnum<{
+            person: "person";
+            service: "service";
+        }>>;
     }, z.core.$strip>;
 };
 /** @deprecated 随 ADR-012 退役,后端回 410;改用 staffInFlightRoute */
@@ -266,6 +274,10 @@ export declare const setStaffPositionRoute: {
             disabled: "disabled";
         }>>;
         roles: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        kind: z.ZodDefault<z.ZodEnum<{
+            person: "person";
+            service: "service";
+        }>>;
         position: z.ZodObject<{
             id: z.core.$ZodBranded<z.ZodString, "PositionId", "out">;
             code: z.ZodString;

api-report/packages/contracts/src/api/http.d.ts

@@ -41,7 +41,7 @@ export type RouteContract<TParams extends z.ZodTypeAny = z.ZodTypeAny, TQuery ex
 export type RouteOutput<R extends RouteContract> = z.infer<R['output']>;
 export type RouteBody<R extends RouteContract> = R['body'] extends z.ZodTypeAny ? z.infer<R['body']> : never;
 /** 结构化错误:前端按 code 分辨,不解析文案。`gone` = 410,路由已随统一鉴权中心退役 */
-export declare const API_ERROR_CODES: readonly ["unauthenticated", "forbidden", "not-found", "validation-failed", "conflict", "precondition-failed", "internal", "gone"];
+export declare const API_ERROR_CODES: readonly ["unauthenticated", "forbidden", "not-found", "validation-failed", "conflict", "precondition-failed", "internal", "gone", "keycloak-misconfigured", "keycloak-unavailable"];
 export type ApiErrorCode = (typeof API_ERROR_CODES)[number];
 export type ApiError = {
     readonly code: ApiErrorCode;

api-report/packages/contracts/src/api/index.d.ts

@@ -1,5 +1,6 @@
 export * from './http.ts';
 export * from './workbench.ts';
 export * from './governance.ts';
+export * from './org-directory.ts';
 export * from './ingest.ts';
 export * from './mail.ts';

api-report/packages/contracts/src/api/org-directory.d.ts

@@ -0,0 +1,701 @@
+/**
+ * 成员与组织(ADR-012 · 运营中心「员工」那一屏的三个页签)。
+ *
+ * **真源是 Keycloak**:读接口是它的投影,写接口**直接穿透**到 Admin API ——
+ * 这里建的人立刻能登录、这里停的人立刻登不上、这里删的人从 Keycloak 消失。
+ * 没有「先存本地草稿再同步」这回事,**也没有撤销**;界面上凡写必二次确认。
+ *
+ * 与本地名册的关系:`sys.staff` 是这份目录的投影 + 一列本地岗位(见 org/CONTRACT.md)。
+ * 涉及身份的写(停用 / 删除 / 授收角色)之后,本地那一行当场跟手 —— 两屏不许说两句话。
+ *
+ * 三处口径与 Keycloak 的形状有关,写在这儿免得每条接口重复:
+ *  ① **服务账号一律不可见、不可写**:目录读剔除 `service-account-*`(它是身份不是人,
+ *    见 `staffKindSchema`);写面对着服务账号的 sub 一律 403。
+ *  ② **组树是平表**:一行一个组,靠 `parentId` / `depth` 表达层级(按 `path` 升序已排好)。
+ *    契约里不放递归结构 —— 递归 schema 到了声明文件那一层只会变成一坨 any。
+ *  ③ **列表无分页**:realm 不大,一次拉全;Keycloak 那一侧的 100 条上限由适配器分页兜住。
+ */
+import { z } from 'zod';
+export declare const orgUserSchema: z.ZodObject<{
+    sub: z.ZodString;
+    username: z.ZodString;
+    displayName: z.ZodString;
+    email: z.ZodOptional<z.ZodString>;
+    enabled: z.ZodBoolean;
+    roles: z.ZodArray<z.ZodString>;
+    ends: z.ZodArray<z.ZodEnum<{
+        design: "design";
+        ops: "ops";
+        workbench: "workbench";
+    }>>;
+    lastSeenAt: z.ZodOptional<z.ZodString>;
+    positionCode: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type OrgUser = z.infer<typeof orgUserSchema>;
+export declare const orgUserDetailSchema: z.ZodObject<{
+    sub: z.ZodString;
+    username: z.ZodString;
+    displayName: z.ZodString;
+    email: z.ZodOptional<z.ZodString>;
+    enabled: z.ZodBoolean;
+    roles: z.ZodArray<z.ZodString>;
+    ends: z.ZodArray<z.ZodEnum<{
+        design: "design";
+        ops: "ops";
+        workbench: "workbench";
+    }>>;
+    lastSeenAt: z.ZodOptional<z.ZodString>;
+    positionCode: z.ZodOptional<z.ZodString>;
+    firstName: z.ZodOptional<z.ZodString>;
+    lastName: z.ZodOptional<z.ZodString>;
+    emailVerified: z.ZodBoolean;
+    groups: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        path: z.ZodString;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type OrgUserDetail = z.infer<typeof orgUserDetailSchema>;
+export declare const listOrgUsersRoute: {
+    readonly method: "GET";
+    readonly path: "/api/gov/org/users";
+    readonly access: "ops";
+    readonly output: z.ZodObject<{
+        users: z.ZodArray<z.ZodObject<{
+            sub: z.ZodString;
+            username: z.ZodString;
+            displayName: z.ZodString;
+            email: z.ZodOptional<z.ZodString>;
+            enabled: z.ZodBoolean;
+            roles: z.ZodArray<z.ZodString>;
+            ends: z.ZodArray<z.ZodEnum<{
+                design: "design";
+                ops: "ops";
+                workbench: "workbench";
+            }>>;
+            lastSeenAt: z.ZodOptional<z.ZodString>;
+            positionCode: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>;
+};
+export declare const getOrgUserRoute: {
+    readonly method: "GET";
+    readonly path: "/api/gov/org/users/:sub";
+    readonly access: "ops";
+    readonly params: z.ZodObject<{
+        sub: z.ZodString;
+    }, z.core.$strip>;
+    readonly output: z.ZodObject<{
+        sub: z.ZodString;
+        username: z.ZodString;
+        displayName: z.ZodString;
+        email: z.ZodOptional<z.ZodString>;
+        enabled: z.ZodBoolean;
+        roles: z.ZodArray<z.ZodString>;
+        ends: z.ZodArray<z.ZodEnum<{
+            design: "design";
+            ops: "ops";
+            workbench: "workbench";
+        }>>;
+        lastSeenAt: z.ZodOptional<z.ZodString>;
+        positionCode: z.ZodOptional<z.ZodString>;
+        firstName: z.ZodOptional<z.ZodString>;
+        lastName: z.ZodOptional<z.ZodString>;
+        emailVerified: z.ZodBoolean;
+        groups: z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            path: z.ZodString;
+        }, z.core.$strip>>;
+    }, z.core.$strip>;
+};
+/**
+ * 新建成员 —— 建完立刻能登录。口令是**临时**的:本人首登必须改
+ * (`temporary:true`,手册 §14.2);我们不存它,也不回显。
+ */
+export declare const createOrgUserRoute: {
+    readonly method: "POST";
+    readonly path: "/api/gov/org/users";
+    readonly access: "ops";
+    readonly body: z.ZodObject<{
+        username: z.ZodString;
+        firstName: z.ZodOptional<z.ZodString>;
+        lastName: z.ZodOptional<z.ZodString>;
+        email: z.ZodOptional<z.ZodString>;
+        password: z.ZodOptional<z.ZodString>;
+        roles: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>;
+    readonly output: z.ZodObject<{
+        sub: z.ZodString;
+        username: z.ZodString;
+        displayName: z.ZodString;
+        email: z.ZodOptional<z.ZodString>;
+        enabled: z.ZodBoolean;
+        roles: z.ZodArray<z.ZodString>;
+        ends: z.ZodArray<z.ZodEnum<{
+            design: "design";
+            ops: "ops";
+            workbench: "workbench";
+        }>>;
+        lastSeenAt: z.ZodOptional<z.ZodString>;
+        positionCode: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+};
+/** 改资料(姓名 / 邮箱)—— 用户名建后不可改,不在这里 */
+export declare const patchOrgUserRoute: {
+    readonly method: "PATCH";
+    readonly path: "/api/gov/org/users/:sub";
+    readonly access: "ops";
+    readonly params: z.ZodObject<{
+        sub: z.ZodString;
+    }, z.core.$strip>;
+    readonly body: z.ZodObject<{
+        firstName: z.ZodOptional<z.ZodString>;
+        lastName: z.ZodOptional<z.ZodString>;
+        email: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+    readonly output: z.ZodObject<{
+        sub: z.ZodString;
+        username: z.ZodString;
+        displayName: z.ZodString;
+        email: z.ZodOptional<z.ZodString>;
+        enabled: z.ZodBoolean;
+        roles: z.ZodArray<z.ZodString>;
+        ends: z.ZodArray<z.ZodEnum<{
+            design: "design";
+            ops: "ops";
+            workbench: "workbench";
+        }>>;
+        lastSeenAt: z.ZodOptional<z.ZodString>;
+        positionCode: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+};
+/**
+ * 启用 / 停用。停用**立刻踢掉该用户全部会话** —— 不然他攥着的 token
+ * 还能用到过期为止,而「已停用」这三个字在界面上已经写出去了(界面不撒谎)。
+ */
+export declare const setOrgUserEnabledRoute: {
+    readonly method: "POST";
+    readonly path: "/api/gov/org/users/:sub/enabled";
+    readonly access: "ops";
+    readonly params: z.ZodObject<{
+        sub: z.ZodString;
+    }, z.core.$strip>;
+    readonly body: z.ZodObject<{
+        enabled: z.ZodBoolean;
+    }, z.core.$strip>;
+    readonly output: z.ZodObject<{
+        sub: z.ZodString;
+        username: z.ZodString;
+        displayName: z.ZodString;
+        email: z.ZodOptional<z.ZodString>;
+        enabled: z.ZodBoolean;
+        roles: z.ZodArray<z.ZodString>;
+        ends: z.ZodArray<z.ZodEnum<{
+            design: "design";
+            ops: "ops";
+            workbench: "workbench";
+        }>>;
+        lastSeenAt: z.ZodOptional<z.ZodString>;
+        positionCode: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+};
+/** 重置口令 —— 一律临时口令,本人首登必须改;服务端不回显、不留痕 */
+export declare const resetOrgUserPasswordRoute: {
+    readonly method: "POST";
+    readonly path: "/api/gov/org/users/:sub/reset-password";
+    readonly access: "ops";
+    readonly params: z.ZodObject<{
+        sub: z.ZodString;
+    }, z.core.$strip>;
+    readonly body: z.ZodObject<{
+        password: z.ZodString;
+    }, z.core.$strip>;
+    readonly output: z.ZodObject<{
+        ok: z.ZodLiteral<true>;
+    }, z.core.$strip>;
+};
+/** 删人 —— 从 Keycloak 消失,不可撤销;本地名册那一行同批停用(留痕与在途还挂着他) */
+export declare const deleteOrgUserRoute: {
+    readonly method: "DELETE";
+    readonly path: "/api/gov/org/users/:sub";
+    readonly access: "ops";
+    readonly params: z.ZodObject<{
+        sub: z.ZodString;
+    }, z.core.$strip>;
+    readonly output: z.ZodObject<{
+        ok: z.ZodLiteral<true>;
+    }, z.core.$strip>;
+};
+export declare const orgRoleSchema: z.ZodObject<{
+    name: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    composite: z.ZodBoolean;
+    ends: z.ZodArray<z.ZodEnum<{
+        design: "design";
+        ops: "ops";
+        workbench: "workbench";
+    }>>;
+    holders: z.ZodNumber;
+}, z.core.$strip>;
+export type OrgRole = z.infer<typeof orgRoleSchema>;
+export declare const listOrgRolesRoute: {
+    readonly method: "GET";
+    readonly path: "/api/gov/org/roles";
+    readonly access: "ops";
+    readonly output: z.ZodObject<{
+        roles: z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            description: z.ZodOptional<z.ZodString>;
+            composite: z.ZodBoolean;
+            ends: z.ZodArray<z.ZodEnum<{
+                design: "design";
+                ops: "ops";
+                workbench: "workbench";
+            }>>;
+            holders: z.ZodNumber;
+        }, z.core.$strip>>;
+    }, z.core.$strip>;
+};
+/**
+ * 授 / 收一个 realm 角色。收权**立刻踢掉该用户全部会话**(手册 §17.3)——
+ * 否则他手上那枚 token 还带着旧角色,收权要等到 token 过期才生效。
+ * 不能收自己的最后一条进运营中心的路(409)—— 收完没人进得来,这扇门就锁死了。
+ */
+export declare const setOrgUserRoleRoute: {
+    readonly method: "POST";
+    readonly path: "/api/gov/org/users/:sub/roles/:role";
+    readonly access: "ops";
+    readonly params: z.ZodObject<{
+        sub: z.ZodString;
+        role: z.ZodString;
+    }, z.core.$strip>;
+    readonly body: z.ZodObject<{
+        granted: z.ZodBoolean;
+    }, z.core.$strip>;
+    readonly output: z.ZodObject<{
+        sub: z.ZodString;
+        username: z.ZodString;
+        displayName: z.ZodString;
+        email: z.ZodOptional<z.ZodString>;
+        enabled: z.ZodBoolean;
+        roles: z.ZodArray<z.ZodString>;
+        ends: z.ZodArray<z.ZodEnum<{
+            design: "design";
+            ops: "ops";
+            workbench: "workbench";
+        }>>;
+        lastSeenAt: z.ZodOptional<z.ZodString>;
+        positionCode: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+};
+export declare const orgGroupSchema: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    path: z.ZodString;
+    parentId: z.ZodOptional<z.ZodString>;
+    depth: z.ZodNumber;
+    memberCount: z.ZodNumber;
+}, z.core.$strip>;
+export type OrgGroup = z.infer<typeof orgGroupSchema>;
+/** 组树平表,按 `path` 升序 —— 层级看 `parentId` / `depth` */
+export declare const listOrgGroupsRoute: {
+    readonly method: "GET";
+    readonly path: "/api/gov/org/groups";
+    readonly access: "ops";
+    readonly output: z.ZodObject<{
+        groups: z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            name: z.ZodString;
+            path: z.ZodString;
+            parentId: z.ZodOptional<z.ZodString>;
+            depth: z.ZodNumber;
+            memberCount: z.ZodNumber;
+        }, z.core.$strip>>;
+    }, z.core.$strip>;
+};
+/** 组的直属成员(含被停用的人 —— 这一屏管的是归属,不是能不能登录) */
+export declare const listOrgGroupMembersRoute: {
+    readonly method: "GET";
+    readonly path: "/api/gov/org/groups/:id/members";
+    readonly access: "ops";
+    readonly params: z.ZodObject<{
+        id: z.ZodString;
+    }, z.core.$strip>;
+    readonly output: z.ZodObject<{
+        members: z.ZodArray<z.ZodObject<{
+            sub: z.ZodString;
+            username: z.ZodString;
+            displayName: z.ZodString;
+            email: z.ZodOptional<z.ZodString>;
+            enabled: z.ZodBoolean;
+            roles: z.ZodArray<z.ZodString>;
+            ends: z.ZodArray<z.ZodEnum<{
+                design: "design";
+                ops: "ops";
+                workbench: "workbench";
+            }>>;
+            lastSeenAt: z.ZodOptional<z.ZodString>;
+            positionCode: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>;
+};
+/** 建组:`parentId` 给了就是子组,不给就是顶层组。同级不得重名(Keycloak 那一侧拦,409) */
+export declare const createOrgGroupRoute: {
+    readonly method: "POST";
+    readonly path: "/api/gov/org/groups";
+    readonly access: "ops";
+    readonly body: z.ZodObject<{
+        name: z.ZodString;
+        parentId: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+    readonly output: z.ZodObject<{
+        id: z.ZodString;
+        name: z.ZodString;
+        path: z.ZodString;
+        parentId: z.ZodOptional<z.ZodString>;
+        depth: z.ZodNumber;
+        memberCount: z.ZodNumber;
+    }, z.core.$strip>;
+};
+export declare const renameOrgGroupRoute: {
+    readonly method: "PATCH";
+    readonly path: "/api/gov/org/groups/:id";
+    readonly access: "ops";
+    readonly params: z.ZodObject<{
+        id: z.ZodString;
+    }, z.core.$strip>;
+    readonly body: z.ZodObject<{
+        name: z.ZodString;
+    }, z.core.$strip>;
+    readonly output: z.ZodObject<{
+        id: z.ZodString;
+        name: z.ZodString;
+        path: z.ZodString;
+        parentId: z.ZodOptional<z.ZodString>;
+        depth: z.ZodNumber;
+        memberCount: z.ZodNumber;
+    }, z.core.$strip>;
+};
+/** 删组 —— 连同子组一起没(Keycloak 语义);人不会被删,只是不再属于这个组 */
+export declare const deleteOrgGroupRoute: {
+    readonly method: "DELETE";
+    readonly path: "/api/gov/org/groups/:id";
+    readonly access: "ops";
+    readonly params: z.ZodObject<{
+        id: z.ZodString;
+    }, z.core.$strip>;
+    readonly output: z.ZodObject<{
+        ok: z.ZodLiteral<true>;
+    }, z.core.$strip>;
+};
+/** 成员进 / 出组 */
+export declare const setOrgUserGroupRoute: {
+    readonly method: "POST";
+    readonly path: "/api/gov/org/users/:sub/groups/:groupId";
+    readonly access: "ops";
+    readonly params: z.ZodObject<{
+        sub: z.ZodString;
+        groupId: z.ZodString;
+    }, z.core.$strip>;
+    readonly body: z.ZodObject<{
+        member: z.ZodBoolean;
+    }, z.core.$strip>;
+    readonly output: z.ZodObject<{
+        ok: z.ZodLiteral<true>;
+    }, z.core.$strip>;
+};
+/**
+ * 这一屏的全部路由 —— 归属一处列全,测试拿它逐条断言。
+ * 逐个 import 去断言的写法,新增一条只要忘了加进名单就悄悄漏过去了。
+ */
+export declare const ORG_DIRECTORY_ROUTES: readonly [{
+    readonly method: "GET";
+    readonly path: "/api/gov/org/users";
+    readonly access: "ops";
+    readonly output: z.ZodObject<{
+        users: z.ZodArray<z.ZodObject<{
+            sub: z.ZodString;
+            username: z.ZodString;
+            displayName: z.ZodString;
+            email: z.ZodOptional<z.ZodString>;
+            enabled: z.ZodBoolean;
+            roles: z.ZodArray<z.ZodString>;
+            ends: z.ZodArray<z.ZodEnum<{
+                design: "design";
+                ops: "ops";
+                workbench: "workbench";
+            }>>;
+            lastSeenAt: z.ZodOptional<z.ZodString>;
+            positionCode: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>;
+}, {
+    readonly method: "GET";
+    readonly path: "/api/gov/org/users/:sub";
+    readonly access: "ops";
+    readonly params: z.ZodObject<{
+        sub: z.ZodString;
+    }, z.core.$strip>;
+    readonly output: z.ZodObject<{
+        sub: z.ZodString;
+        username: z.ZodString;
+        displayName: z.ZodString;
+        email: z.ZodOptional<z.ZodString>;
+        enabled: z.ZodBoolean;
+        roles: z.ZodArray<z.ZodString>;
+        ends: z.ZodArray<z.ZodEnum<{
+            design: "design";
+            ops: "ops";
+            workbench: "workbench";
+        }>>;
+        lastSeenAt: z.ZodOptional<z.ZodString>;
+        positionCode: z.ZodOptional<z.ZodString>;
+        firstName: z.ZodOptional<z.ZodString>;
+        lastName: z.ZodOptional<z.ZodString>;
+        emailVerified: z.ZodBoolean;
+        groups: z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            path: z.ZodString;
+        }, z.core.$strip>>;
+    }, z.core.$strip>;
+}, {
+    readonly method: "POST";
+    readonly path: "/api/gov/org/users";
+    readonly access: "ops";
+    readonly body: z.ZodObject<{
+        username: z.ZodString;
+        firstName: z.ZodOptional<z.ZodString>;
+        lastName: z.ZodOptional<z.ZodString>;
+        email: z.ZodOptional<z.ZodString>;
+        password: z.ZodOptional<z.ZodString>;
+        roles: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>;
+    readonly output: z.ZodObject<{
+        sub: z.ZodString;
+        username: z.ZodString;
+        displayName: z.ZodString;
+        email: z.ZodOptional<z.ZodString>;
+        enabled: z.ZodBoolean;
+        roles: z.ZodArray<z.ZodString>;
+        ends: z.ZodArray<z.ZodEnum<{
+            design: "design";
+            ops: "ops";
+            workbench: "workbench";
+        }>>;
+        lastSeenAt: z.ZodOptional<z.ZodString>;
+        positionCode: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+}, {
+    readonly method: "PATCH";
+    readonly path: "/api/gov/org/users/:sub";
+    readonly access: "ops";
+    readonly params: z.ZodObject<{
+        sub: z.ZodString;
+    }, z.core.$strip>;
+    readonly body: z.ZodObject<{
+        firstName: z.ZodOptional<z.ZodString>;
+        lastName: z.ZodOptional<z.ZodString>;
+        email: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+    readonly output: z.ZodObject<{
+        sub: z.ZodString;
+        username: z.ZodString;
+        displayName: z.ZodString;
+        email: z.ZodOptional<z.ZodString>;
+        enabled: z.ZodBoolean;
+        roles: z.ZodArray<z.ZodString>;
+        ends: z.ZodArray<z.ZodEnum<{
+            design: "design";
+            ops: "ops";
+            workbench: "workbench";
+        }>>;
+        lastSeenAt: z.ZodOptional<z.ZodString>;
+        positionCode: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+}, {
+    readonly method: "POST";
+    readonly path: "/api/gov/org/users/:sub/enabled";
+    readonly access: "ops";
+    readonly params: z.ZodObject<{
+        sub: z.ZodString;
+    }, z.core.$strip>;
+    readonly body: z.ZodObject<{
+        enabled: z.ZodBoolean;
+    }, z.core.$strip>;
+    readonly output: z.ZodObject<{
+        sub: z.ZodString;
+        username: z.ZodString;
+        displayName: z.ZodString;
+        email: z.ZodOptional<z.ZodString>;
+        enabled: z.ZodBoolean;
+        roles: z.ZodArray<z.ZodString>;
+        ends: z.ZodArray<z.ZodEnum<{
+            design: "design";
+            ops: "ops";
+            workbench: "workbench";
+        }>>;
+        lastSeenAt: z.ZodOptional<z.ZodString>;
+        positionCode: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+}, {
+    readonly method: "POST";
+    readonly path: "/api/gov/org/users/:sub/reset-password";
+    readonly access: "ops";
+    readonly params: z.ZodObject<{
+        sub: z.ZodString;
+    }, z.core.$strip>;
+    readonly body: z.ZodObject<{
+        password: z.ZodString;
+    }, z.core.$strip>;
+    readonly output: z.ZodObject<{
+        ok: z.ZodLiteral<true>;
+    }, z.core.$strip>;
+}, {
+    readonly method: "DELETE";
+    readonly path: "/api/gov/org/users/:sub";
+    readonly access: "ops";
+    readonly params: z.ZodObject<{
+        sub: z.ZodString;
+    }, z.core.$strip>;
+    readonly output: z.ZodObject<{
+        ok: z.ZodLiteral<true>;
+    }, z.core.$strip>;
+}, {
+    readonly method: "GET";
+    readonly path: "/api/gov/org/roles";
+    readonly access: "ops";
+    readonly output: z.ZodObject<{
+        roles: z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            description: z.ZodOptional<z.ZodString>;
+            composite: z.ZodBoolean;
+            ends: z.ZodArray<z.ZodEnum<{
+                design: "design";
+                ops: "ops";
+                workbench: "workbench";
+            }>>;
+            holders: z.ZodNumber;
+        }, z.core.$strip>>;
+    }, z.core.$strip>;
+}, {
+    readonly method: "POST";
+    readonly path: "/api/gov/org/users/:sub/roles/:role";
+    readonly access: "ops";
+    readonly params: z.ZodObject<{
+        sub: z.ZodString;
+        role: z.ZodString;
+    }, z.core.$strip>;
+    readonly body: z.ZodObject<{
+        granted: z.ZodBoolean;
+    }, z.core.$strip>;
+    readonly output: z.ZodObject<{
+        sub: z.ZodString;
+        username: z.ZodString;
+        displayName: z.ZodString;
+        email: z.ZodOptional<z.ZodString>;
+        enabled: z.ZodBoolean;
+        roles: z.ZodArray<z.ZodString>;
+        ends: z.ZodArray<z.ZodEnum<{
+            design: "design";
+            ops: "ops";
+            workbench: "workbench";
+        }>>;
+        lastSeenAt: z.ZodOptional<z.ZodString>;
+        positionCode: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+}, {
+    readonly method: "GET";
+    readonly path: "/api/gov/org/groups";
+    readonly access: "ops";
+    readonly output: z.ZodObject<{
+        groups: z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            name: z.ZodString;
+            path: z.ZodString;
+            parentId: z.ZodOptional<z.ZodString>;
+            depth: z.ZodNumber;
+            memberCount: z.ZodNumber;
+        }, z.core.$strip>>;
+    }, z.core.$strip>;
+}, {
+    readonly method: "GET";
+    readonly path: "/api/gov/org/groups/:id/members";
+    readonly access: "ops";
+    readonly params: z.ZodObject<{
+        id: z.ZodString;
+    }, z.core.$strip>;
+    readonly output: z.ZodObject<{
+        members: z.ZodArray<z.ZodObject<{
+            sub: z.ZodString;
+            username: z.ZodString;
+            displayName: z.ZodString;
+            email: z.ZodOptional<z.ZodString>;
+            enabled: z.ZodBoolean;
+            roles: z.ZodArray<z.ZodString>;
+            ends: z.ZodArray<z.ZodEnum<{
+                design: "design";
+                ops: "ops";
+                workbench: "workbench";
+            }>>;
+            lastSeenAt: z.ZodOptional<z.ZodString>;
+            positionCode: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>;
+}, {
+    readonly method: "POST";
+    readonly path: "/api/gov/org/groups";
+    readonly access: "ops";
+    readonly body: z.ZodObject<{
+        name: z.ZodString;
+        parentId: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+    readonly output: z.ZodObject<{
+        id: z.ZodString;
+        name: z.ZodString;
+        path: z.ZodString;
+        parentId: z.ZodOptional<z.ZodString>;
+        depth: z.ZodNumber;
+        memberCount: z.ZodNumber;
+    }, z.core.$strip>;
+}, {
+    readonly method: "PATCH";
+    readonly path: "/api/gov/org/groups/:id";
+    readonly access: "ops";
+    readonly params: z.ZodObject<{
+        id: z.ZodString;
+    }, z.core.$strip>;
+    readonly body: z.ZodObject<{
+        name: z.ZodString;
+    }, z.core.$strip>;
+    readonly output: z.ZodObject<{
+        id: z.ZodString;
+        name: z.ZodString;
+        path: z.ZodString;
+        parentId: z.ZodOptional<z.ZodString>;
+        depth: z.ZodNumber;
+        memberCount: z.ZodNumber;
+    }, z.core.$strip>;
+}, {
+    readonly method: "DELETE";
+    readonly path: "/api/gov/org/groups/:id";
+    readonly access: "ops";
+    readonly params: z.ZodObject<{
+        id: z.ZodString;
+    }, z.core.$strip>;
+    readonly output: z.ZodObject<{
+        ok: z.ZodLiteral<true>;
+    }, z.core.$strip>;
+}, {
+    readonly method: "POST";
+    readonly path: "/api/gov/org/users/:sub/groups/:groupId";
+    readonly access: "ops";
+    readonly params: z.ZodObject<{
+        sub: z.ZodString;
+        groupId: z.ZodString;
+    }, z.core.$strip>;
+    readonly body: z.ZodObject<{
+        member: z.ZodBoolean;
+    }, z.core.$strip>;
+    readonly output: z.ZodObject<{
+        ok: z.ZodLiteral<true>;
+    }, z.core.$strip>;
+}];

api-report/packages/contracts/src/api/workbench.d.ts

@@ -20,6 +20,10 @@ export declare const sessionRoute: {
                 disabled: "disabled";
             }>>;
             roles: z.ZodDefault<z.ZodArray<z.ZodString>>;
+            kind: z.ZodDefault<z.ZodEnum<{
+                person: "person";
+                service: "service";
+            }>>;
         }, z.core.$strip>;
         position: z.ZodObject<{
             id: z.core.$ZodBranded<z.ZodString, "PositionId", "out">;
@@ -80,6 +84,10 @@ export declare const loginRoute: {
                 disabled: "disabled";
             }>>;
             roles: z.ZodDefault<z.ZodArray<z.ZodString>>;
+            kind: z.ZodDefault<z.ZodEnum<{
+                person: "person";
+                service: "service";
+            }>>;
         }, z.core.$strip>;
         position: z.ZodObject<{
             id: z.core.$ZodBranded<z.ZodString, "PositionId", "out">;
@@ -158,6 +166,10 @@ export declare const meRoute: {
                 disabled: "disabled";
             }>>;
             roles: z.ZodDefault<z.ZodArray<z.ZodString>>;
+            kind: z.ZodDefault<z.ZodEnum<{
+                person: "person";
+                service: "service";
+            }>>;
         }, z.core.$strip>;
         position: z.ZodObject<{
             id: z.core.$ZodBranded<z.ZodString, "PositionId", "out">;

api-report/packages/contracts/src/org.d.ts

@@ -19,6 +19,22 @@ export declare const staffStateSchema: z.ZodEnum<{
     disabled: "disabled";
 }>;
 export type StaffState = z.infer<typeof staffStateSchema>;
+/**
+ * 人,还是服务账号。
+ *
+ * Keycloak 给每个开了 `serviceAccountsEnabled` 的 client 自动建一个用户,用户名恒为
+ * `service-account-<clientId>` —— 那是 Keycloak 自己的命名,不是我们的约定;它也不出现在
+ * 管理台的 Users 列表、Admin API 的 `GET /users` 里(名册同步的下限保护②为此存在)。
+ *
+ * 它是**真身份**(试跑与 e2e 就用它跑单,铁规矩 6),但**不是人**:
+ * 员工管理那一屏不摆它,试跑台的负责人下拉照旧摆。
+ * 这条判断归后端 —— 界面不该去猜账号名长什么样。
+ */
+export declare const staffKindSchema: z.ZodEnum<{
+    person: "person";
+    service: "service";
+}>;
+export type StaffKind = z.infer<typeof staffKindSchema>;
 export declare const staffSchema: z.ZodObject<{
     id: z.core.$ZodBranded<z.ZodString, "StaffId", "out">;
     account: z.ZodString;
@@ -30,6 +46,10 @@ export declare const staffSchema: z.ZodObject<{
         disabled: "disabled";
     }>>;
     roles: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    kind: z.ZodDefault<z.ZodEnum<{
+        person: "person";
+        service: "service";
+    }>>;
 }, z.core.$strip>;
 export type Staff = z.infer<typeof staffSchema>;
 export declare const principalSchema: z.ZodObject<{
@@ -44,6 +64,10 @@ export declare const principalSchema: z.ZodObject<{
             disabled: "disabled";
         }>>;
         roles: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        kind: z.ZodDefault<z.ZodEnum<{
+            person: "person";
+            service: "service";
+        }>>;
     }, z.core.$strip>;
     position: z.ZodObject<{
         id: z.core.$ZodBranded<z.ZodString, "PositionId", "out">;
@@ -226,6 +250,10 @@ export declare const sessionSchema: z.ZodObject<{
             disabled: "disabled";
         }>>;
         roles: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        kind: z.ZodDefault<z.ZodEnum<{
+            person: "person";
+            service: "service";
+        }>>;
     }, z.core.$strip>;
     position: z.ZodObject<{
         id: z.core.$ZodBranded<z.ZodString, "PositionId", "out">;

apps/api/package.json

@@ -13,7 +13,8 @@
     "seed": "node dist/seed.js",
     "migrate": "node dist/migrate.js",
     "reset-runs": "node dist/reset-runs.js",
-    "install-activities": "node dist/install-activities.js"
+    "install-activities": "node dist/install-activities.js",
+    "sync-roster": "node dist/sync-roster.js"
   },
   "dependencies": {
     "@ai-sdk/openai-compatible": "^3.0.14",

apps/api/src/app/__tests__/auth-middleware.test.ts

@@ -11,7 +11,7 @@ import { createTicketIssuer } from '../ticket.ts';
 
 const position: Position = { id: positionIdSchema.parse('none'), code: 'NONE', name: '未分配' };
 const principal = (ends: Surface[], roles: string[]): Principal => ({
-  staff: { id: staffIdSchema.parse('sub-1'), account: 'alice', name: '爱丽丝', positionId: position.id, state: 'active', roles },
+  staff: { id: staffIdSchema.parse('sub-1'), account: 'alice', name: '爱丽丝', positionId: position.id, state: 'active', roles, kind: 'person' },
   position,
   roles,
   ends,

apps/api/src/app/__tests__/broadcast-bridge.test.ts

@@ -87,6 +87,61 @@ describe('bridgeBroadcaster', () => {
     expect(got).toEqual([]);
   });
 
+  it('**转发别人的那一条不再 NOTIFY 出去** —— 转发不是「自己推的」', async () => {
+    const fake = fakePool();
+    const bus = createBroadcaster();
+    bridgeBroadcaster(fake.pool as never, bus);
+    await settle();
+
+    fake.deliver({ kind: 'system', id: 'gov', reason: 'POST /api/gov/process/validate', from: '别的机器' });
+    await settle();
+    /*
+     * 从前这里会 NOTIFY 一条(from 换成自己):对面收到不是它发的、再转发、再 NOTIFY……
+     * 两台后端连同一个库时一条广播就此永动 —— 实测 45 秒 19 万条,工作台三把查询被打成连续重取。
+     */
+    expect(fake.notified).toEqual([]);
+  });
+
+  it('两台后端互桥,一条广播各到一次就停 —— 不来回弹', async () => {
+    /** 两个假池共用一条「频道」:谁 NOTIFY 了,另一个当场收到(自己也收到,和真库一样) */
+    const a = fakePool();
+    const b = fakePool();
+    const busA = createBroadcaster();
+    const busB = createBroadcaster();
+    const relay = (from: typeof a, to: typeof b) => {
+      const origQuery = from.pool.query;
+      from.pool.query = async (sql: string, params: unknown[]) => {
+        const r = await origQuery(sql, params);
+        // 回弹起来是无穷的:封顶 50 条,让用例「失败」而不是把测试进程撑爆
+        if (from.notified.length > 50) return r;
+        // 真库会把这条送给所有 LISTEN 的连接,包括发它的那个进程自己
+        const wire = JSON.parse(String(params[1])) as Record<string, unknown>;
+        from.deliver(wire);
+        to.deliver(wire);
+        return r;
+      };
+    };
+    // 两台机器两个身份(真环境里 SELF 按进程生成;测试里显式给,不然同进程两座桥同名)
+    bridgeBroadcaster(a.pool as never, busA, 'A');
+    bridgeBroadcaster(b.pool as never, busB, 'B');
+    await settle();
+    relay(a, b);
+    relay(b, a);
+
+    const seenA: string[] = [];
+    const seenB: string[] = [];
+    busA.subscribe((t) => seenA.push(t.reason));
+    busB.subscribe((t) => seenB.push(t.reason));
+    busA.publish({ kind: 'system', id: 'gov', reason: 'x' });
+    for (let i = 0; i < 20; i += 1) await settle();
+
+    // A 本地一次、B 转发一次;NOTIFY 只有 A 发的那一条 —— B 转发的不再发回去
+    expect(seenA).toEqual(['x']);
+    expect(seenB).toEqual(['x']);
+    expect(a.notified).toHaveLength(1);
+    expect(b.notified).toHaveLength(0);
+  });
+
   it('载荷坏了只丢这一条,连接照旧活着', async () => {
     const fake = fakePool();
     const bus = createBroadcaster();

apps/api/src/app/__tests__/org-directory-registry.test.ts

@@ -0,0 +1,36 @@
+/**
+ * 成员与组织的路由归属(ADR-012):15 条全部进契约、全部注册、全部归运营中心。
+ *
+ * 归属写在契约的 `access` 上,鉴权中间件一处按注册表判 —— 所以**漏标一条**
+ * 就会落进 `?? 'any'` 兜底:只要登录过的人都能调。这条测试就是拦那个的。
+ */
+import { describe, expect, it } from 'vitest';
+import * as contracts from '@contracts';
+import { ORG_DIRECTORY_ROUTES } from '@contracts';
+import { appRouteRegistry } from '../server.ts';
+import { buildRouteRegistry, routesOf } from '../route-registry.ts';
+
+describe('成员与组织路由契约', () => {
+  it('15 条全在契约命名空间里,注册表建得起来', () => {
+    const registry = buildRouteRegistry(routesOf(Object.values(contracts)));
+    expect(ORG_DIRECTORY_ROUTES).toHaveLength(15);
+    for (const route of ORG_DIRECTORY_ROUTES) {
+      expect(registry.has(route.method, route.path)).toBe(true);
+    }
+  });
+
+  it('读写一律归运营中心 —— 成员目录没有设计端的消费方', () => {
+    for (const route of ORG_DIRECTORY_ROUTES) {
+      expect([route.path, route.access]).toEqual([route.path, 'ops']);
+    }
+  });
+
+  it('查得到的归属就是 ops,不落兜底 —— 兜底等于「登录了就能调」', () => {
+    const registry = appRouteRegistry();
+    for (const route of ORG_DIRECTORY_ROUTES) {
+      // 拿一条**具体**路径去查(带 :param 的模版要真能匹配上,不然线上每次都 miss)
+      const concrete = route.path.replace(/:[A-Za-z_][\w]*/g, 'X');
+      expect([concrete, registry.lookup(route.method, concrete)]).toEqual([concrete, 'ops']);
+    }
+  });
+});

apps/api/src/app/broadcast-bridge.ts

@@ -12,6 +12,12 @@
  *   · 本进程 publish 一条 → 顺手 `NOTIFY`(带上进程标识);
  *   · 一条**专用连接**常年 `LISTEN`,收到别的进程发来的就在本地 publish 一次。
  * **自己发的自己不再收**(靠进程标识认),不然一条推送在两台之间来回弹。
+ * **转发进来的不再发出去**(2026-08-26):从前收到别人的就 `publish` 到本地 broadcaster,
+ * 而本桥自己也订阅着它 —— 那条转发被当成「自己推的」再 NOTIFY 一遍(from 换成自己),
+ * 对面收到不是它发的、再转发、再 NOTIFY……只挡「自己发的自己不收」这一跳,两台接力就是永动机:
+ * 实测两台后端连同一个库,一次 `POST /api/gov/process/validate` 引出 45 秒 19 万条广播,
+ * 工作台三把查询被打成连续重取(用户看到的就是「疯狂轮询三个接口」)。
+ * 转发的那一条在本地 publish 前打上记号,「本地 → 库」那一侧认出记号就不再发。
  *
  * 桥断了不影响业务:推送本就是「告诉在线浏览器去重取」的提示,丢一条最坏是
  * 那一屏晚两秒(前端还有轮询兜底)。所以这里所有错误都只记一行,不往上抛。
@@ -33,14 +39,16 @@ type Wire = Touch & { readonly from: string };
  * `notify` 用参数化的 `pg_notify` 而不是拼 `NOTIFY` 语句:载荷里有中文与引号,
  * 拼字符串迟早出事(而这条路上的字符串全来自业务)。
  */
-export function bridgeBroadcaster(pool: Pool, broadcaster: Broadcaster): { stop(): void } {
+export function bridgeBroadcaster(pool: Pool, broadcaster: Broadcaster, self: string = SELF): { stop(): void } {
   let listener: PoolClient | undefined;
   let stopped = false;
+  /** 从库上转发进来的那几条 —— 它们不是本进程推的,不许再 NOTIFY 回去(按对象身份认,publish 同步派发) */
+  const relayed = new WeakSet<Touch>();
 
   /** 本地 → 库:自己推的顺手 NOTIFY 一条(不 await,广播不该拖慢业务) */
   const unsubscribe = broadcaster.subscribe((touch) => {
-    if (stopped) return;
+    if (stopped || relayed.has(touch)) return;
-    const wire: Wire = { ...touch, from: SELF };
+    const wire: Wire = { ...touch, from: self };
     void pool
       .query('select pg_notify($1, $2)', [TOUCH_CHANNEL, JSON.stringify(wire)])
       .catch((error: unknown) => {
@@ -68,8 +76,10 @@ export function bridgeBroadcaster(pool: Pool, broadcaster: Broadcaster): { stop(
           const wire = parsed as Partial<Wire>;
           if (typeof wire.kind !== 'string' || typeof wire.id !== 'string') return;
           // **自己发的自己不收** —— 否则一条推送在进程之间来回弹
-          if (wire.from === SELF) return;
+          if (wire.from === self) return;
-          broadcaster.publish({ kind: wire.kind as Touch['kind'], id: wire.id, reason: wire.reason ?? 'remote' });
+          const touch: Touch = { kind: wire.kind as Touch['kind'], id: wire.id, reason: wire.reason ?? 'remote' };
+          relayed.add(touch);
+          broadcaster.publish(touch);
         } catch {
           /* 载荷根本不是 JSON:丢这一条,不拖垮连接 */
         }

apps/api/src/app/container.ts

@@ -16,8 +16,9 @@ import { createEventService, createEventStore } from '@modules/event';
 import type { LedgerService } from '@modules/ledger';
 import type { LoopEngineService } from '@modules/loop-engine';
 import { createDraftStore, createLedgerService, createLedgerStore, DRAFT_DDL } from '@modules/ledger';
-import type { InFlightWorkProbe, OrgService, RosterSource, TokenVerifier } from '@modules/org';
+import type { InFlightWorkProbe, KeycloakDirectory, OrgService, RosterSource, TokenVerifier } from '@modules/org';
 import {
+  createKeycloakDirectory,
   createKeycloakRoster,
   createKeycloakTokenVerifier,
   createOrgService,
@@ -185,6 +186,7 @@ const sfeelEvaluator = (expression: string, scope: Readonly<Record<string, unkno
 export type ContainerOverrides = {
   readonly tokenVerifier?: TokenVerifier;
   readonly roster?: RosterSource;
+  readonly directory?: KeycloakDirectory;
 };
 
 export async function createContainer(config: AppConfig, overrides: ContainerOverrides = {}): Promise<Container> {
@@ -256,9 +258,22 @@ export async function createContainer(config: AppConfig, overrides: ContainerOve
           secret: keycloak.provisioning.secret,
         }));
 
+  /* 成员目录与名册同步同一枚 provisioning 服务账号 —— 没配就都不注入,界面如实说不可用 */
+  const directory: KeycloakDirectory | undefined =
+    overrides.directory ??
+    (keycloak?.provisioning === undefined
+      ? undefined
+      : createKeycloakDirectory({
+          url: keycloak.url,
+          realm: keycloak.realm,
+          clientId: keycloak.provisioning.clientId,
+          secret: keycloak.provisioning.secret,
+        }));
+
   const org = createOrgService({
     verifier,
     ...(roster === undefined ? {} : { roster }),
+    ...(directory === undefined ? {} : { directory }),
     positions: createPositionRepository(db),
     staff: createStaffRepository(db),
     roleAccess: createRoleAccessRepository(db),

apps/api/src/app/routes/org-directory.ts

@@ -0,0 +1,196 @@
+/**
+ * 成员与组织的路由组装(ADR-012)—— 运营中心「员工」那一屏的三个页签。
+ * 端级授权由 server.ts 的鉴权中间件按契约上的 `access: 'ops'` 统一判,这里不写守卫。
+ *
+ * **写是穿透**:成功之后 Keycloak 已经变了,没有撤销。所以这一层只做三件事 ——
+ * 把入参校出来、把模块的错误翻成 HTTP、把写完的那一行原样回给界面(界面照它重画,不自己拼)。
+ *
+ * 错误分档(手册 §15 + BPOS §17.0):
+ *   502 `keycloak_misconfigured` 服务账号缺角色 / 没配 —— **重试无益**,去补权限;
+ *   502 `keycloak_unavailable`   暂时够不着 —— 可退避重试;
+ *   409 `conflict`               同级重名、收权会锁死运营中心;
+ *   403 `forbidden`              对着服务账号下手。
+ * 两种 502 分开说,是因为**人的下一步不同**:一个去找管理员,一个等一会儿再点。
+ */
+import type { Hono } from 'hono';
+import type { ApiError } from '@contracts';
+import {
+  createOrgGroupRoute,
+  createOrgUserRoute,
+  deleteOrgGroupRoute,
+  deleteOrgUserRoute,
+  getOrgUserRoute,
+  listOrgGroupMembersRoute,
+  listOrgGroupsRoute,
+  listOrgRolesRoute,
+  listOrgUsersRoute,
+  patchOrgUserRoute,
+  renameOrgGroupRoute,
+  resetOrgUserPasswordRoute,
+  setOrgUserEnabledRoute,
+  setOrgUserGroupRoute,
+  setOrgUserRoleRoute,
+} from '@contracts';
+import {
+  AccessLockoutError,
+  DirectoryUnavailableError,
+  ServiceAccountProtectedError,
+} from '@modules/org';
+import type { Container } from '../container.ts';
+import type { AppEnv } from '../http-env.ts';
+
+/** 出错时统一翻译 —— 每条路由各写一遍 try/catch 只会漏掉其中几条 */
+async function answer<T>(run: () => Promise<T>): Promise<{ body: T } | { error: ApiError; status: 403 | 404 | 409 | 502 }> {
+  try {
+    return { body: await run() };
+  } catch (error) {
+    if (error instanceof DirectoryUnavailableError) {
+      return {
+        error: { code: error.misconfigured ? 'keycloak-misconfigured' : 'keycloak-unavailable', message: error.message },
+        status: 502,
+      };
+    }
+    if (error instanceof ServiceAccountProtectedError) {
+      return { error: { code: 'forbidden', message: error.message }, status: 403 };
+    }
+    if (error instanceof AccessLockoutError) {
+      return { error: { code: 'conflict', message: error.message }, status: 409 };
+    }
+    // Keycloak 明确拒绝(重名 / 约束不过)—— 原话带给人看,别自己编一句更含糊的
+    if (error instanceof Error && error.name === 'KeycloakRejectedError') {
+      const status = (error as Error & { status?: number }).status;
+      return { error: { code: status === 404 ? 'not-found' : 'conflict', message: error.message }, status: status === 404 ? 404 : 409 };
+    }
+    throw error;
+  }
+}
+
+export function registerOrgDirectoryRoutes(app: Hono<AppEnv>, container: Container): void {
+  /**
+ * zod 出来的可选字段是 `string | undefined`,而入参类型在 `exactOptionalPropertyTypes`
+ * 下要的是「要么有、要么这个键不存在」—— 显式的 undefined 在这儿不算「没填」。
+ * 全仓同一个惯用法:条件展开。
+ */
+function defined<T extends Record<string, unknown>>(input: T): { [K in keyof T]: Exclude<T[K], undefined> } {
+  const out: Record<string, unknown> = {};
+  for (const [k, v] of Object.entries(input)) if (v !== undefined) out[k] = v;
+  return out as { [K in keyof T]: Exclude<T[K], undefined> };
+}
+
+/** 校验 body,不合就 400 —— 与治理台其余路由同一套话 */
+  const bad = (detail: unknown): ApiError => ({ code: 'validation-failed', message: '入参不合法', detail });
+
+  /* ── 成员 ───────────────────────────────────────────────────────── */
+
+  app.get(listOrgUsersRoute.path, async (c) => {
+    const q = c.req.query('q') ?? '';
+    // 只有 `1` 算真 —— `true` / `yes` 这类一律当假,免得两处理解不同(与 BPOS §1.1 同款)
+    const includeDisabled = c.req.query('includeDisabled') === '1';
+    const out = await answer(() => container.org.directoryUsers({ q, includeDisabled }));
+    return 'error' in out ? c.json(out.error, out.status) : c.json(out.body);
+  });
+
+  app.get(getOrgUserRoute.path, async (c) => {
+    const out = await answer(() => container.org.directoryUser(c.req.param('sub')));
+    return 'error' in out ? c.json(out.error, out.status) : c.json(out.body);
+  });
+
+  app.post(createOrgUserRoute.path, async (c) => {
+    const parsed = createOrgUserRoute.body.safeParse(await c.req.json());
+    if (!parsed.success) return c.json(bad(parsed.error.issues), 400);
+    const out = await answer(() => container.org.createDirectoryUser(defined(parsed.data)));
+    return 'error' in out ? c.json(out.error, out.status) : c.json(out.body);
+  });
+
+  app.patch(patchOrgUserRoute.path, async (c) => {
+    const parsed = patchOrgUserRoute.body.safeParse(await c.req.json());
+    if (!parsed.success) return c.json(bad(parsed.error.issues), 400);
+    const out = await answer(() => container.org.patchDirectoryUser(c.req.param('sub'), defined(parsed.data)));
+    return 'error' in out ? c.json(out.error, out.status) : c.json(out.body);
+  });
+
+  app.post(setOrgUserEnabledRoute.path, async (c) => {
+    const parsed = setOrgUserEnabledRoute.body.safeParse(await c.req.json());
+    if (!parsed.success) return c.json(bad(parsed.error.issues), 400);
+    const out = await answer(() => container.org.setDirectoryUserEnabled(c.req.param('sub'), parsed.data.enabled));
+    return 'error' in out ? c.json(out.error, out.status) : c.json(out.body);
+  });
+
+  app.post(resetOrgUserPasswordRoute.path, async (c) => {
+    const parsed = resetOrgUserPasswordRoute.body.safeParse(await c.req.json());
+    if (!parsed.success) return c.json(bad(parsed.error.issues), 400);
+    const out = await answer(async () => {
+      await container.org.resetDirectoryUserPassword(c.req.param('sub'), parsed.data.password);
+      return { ok: true as const };
+    });
+    return 'error' in out ? c.json(out.error, out.status) : c.json(out.body);
+  });
+
+  app.delete(deleteOrgUserRoute.path, async (c) => {
+    const out = await answer(async () => {
+      await container.org.deleteDirectoryUser(c.req.param('sub'));
+      return { ok: true as const };
+    });
+    return 'error' in out ? c.json(out.error, out.status) : c.json(out.body);
+  });
+
+  /* ── 权限:realm 角色 × 能进哪几个端 × 谁持有 ───────────────────── */
+
+  app.get(listOrgRolesRoute.path, async (c) => {
+    const out = await answer(() => container.org.directoryRoles());
+    return 'error' in out ? c.json(out.error, out.status) : c.json(out.body);
+  });
+
+  app.post(setOrgUserRoleRoute.path, async (c) => {
+    const parsed = setOrgUserRoleRoute.body.safeParse(await c.req.json());
+    if (!parsed.success) return c.json(bad(parsed.error.issues), 400);
+    const out = await answer(() =>
+      container.org.setDirectoryUserRole(c.req.param('sub'), c.req.param('role'), parsed.data.granted),
+    );
+    return 'error' in out ? c.json(out.error, out.status) : c.json(out.body);
+  });
+
+  /* ── 组织 ───────────────────────────────────────────────────────── */
+
+  app.get(listOrgGroupsRoute.path, async (c) => {
+    const out = await answer(() => container.org.directoryGroups());
+    return 'error' in out ? c.json(out.error, out.status) : c.json(out.body);
+  });
+
+  app.get(listOrgGroupMembersRoute.path, async (c) => {
+    const out = await answer(() => container.org.directoryGroupMembers(c.req.param('id')));
+    return 'error' in out ? c.json(out.error, out.status) : c.json(out.body);
+  });
+
+  app.post(createOrgGroupRoute.path, async (c) => {
+    const parsed = createOrgGroupRoute.body.safeParse(await c.req.json());
+    if (!parsed.success) return c.json(bad(parsed.error.issues), 400);
+    const out = await answer(() => container.org.createDirectoryGroup(parsed.data.name, parsed.data.parentId));
+    return 'error' in out ? c.json(out.error, out.status) : c.json(out.body);
+  });
+
+  app.patch(renameOrgGroupRoute.path, async (c) => {
+    const parsed = renameOrgGroupRoute.body.safeParse(await c.req.json());
+    if (!parsed.success) return c.json(bad(parsed.error.issues), 400);
+    const out = await answer(() => container.org.renameDirectoryGroup(c.req.param('id'), parsed.data.name));
+    return 'error' in out ? c.json(out.error, out.status) : c.json(out.body);
+  });
+
+  app.delete(deleteOrgGroupRoute.path, async (c) => {
+    const out = await answer(async () => {
+      await container.org.deleteDirectoryGroup(c.req.param('id'));
+      return { ok: true as const };
+    });
+    return 'error' in out ? c.json(out.error, out.status) : c.json(out.body);
+  });
+
+  app.post(setOrgUserGroupRoute.path, async (c) => {
+    const parsed = setOrgUserGroupRoute.body.safeParse(await c.req.json());
+    if (!parsed.success) return c.json(bad(parsed.error.issues), 400);
+    const out = await answer(async () => {
+      await container.org.setDirectoryUserGroup(c.req.param('sub'), c.req.param('groupId'), parsed.data.member);
+      return { ok: true as const };
+    });
+    return 'error' in out ? c.json(out.error, out.status) : c.json(out.body);
+  });
+}

apps/api/src/app/server.ts

@@ -28,6 +28,7 @@ import { registerRegistrationRoutes } from './routes/registration.ts';
 import { registerGovernanceOpsRoutes } from './routes/governance-ops.ts';
 import { registerGovernanceRoutes } from './routes/governance.ts';
 import { registerIngestRoutes } from './routes/ingest.ts';
+import { registerOrgDirectoryRoutes } from './routes/org-directory.ts';
 import { registerMailRoutes } from './routes/mail.ts';
 import { registerStreamRoute } from './routes/stream.ts';
 import { registerWorkbenchRoutes } from './routes/workbench.ts';
@@ -115,6 +116,7 @@ export function createServer(container: Container): Hono<AppEnv> {
 
   registerWorkbenchRoutes(app, container);
   registerGovernanceRoutes(app, container);
+  registerOrgDirectoryRoutes(app, container);
   registerDeskRoutes(app, container);
   registerDeskElementRoutes(app, container);
   registerDeskApprovalRoutes(app, container);

apps/api/src/app/sync-roster.ts

@@ -0,0 +1,46 @@
+/**
+ * 名册同步 —— 从 Keycloak Admin API 把整册照过来(ADR-012)。
+ *
+ *   pnpm --filter @app/api sync-roster
+ *
+ * 与 `POST /api/gov/staff/sync` 是**同一段用例**(`org.syncRoster`),只是换了个入口:
+ * 那条路由要 `ops`,而运维手上常常只有 shell —— 服务账号进不了运营中心,
+ * 前端也未必摆着那枚钮。首登建档(JIT)覆盖的是「在用的人」,这条补的是「还没登录过的人」。
+ *
+ * 三个数说的是**真落进库的条数**;`failed` 单列 —— 半途出事的同步不许报成一排绿数字。
+ */
+import { loadConfig } from './config.ts';
+import { createContainer } from './container.ts';
+
+export async function syncRoster(): Promise<void> {
+  const container = await createContainer(loadConfig());
+  try {
+    const outcome = await container.org.syncRoster();
+    if (!outcome.configured) {
+      process.stderr.write(`✗ ${outcome.message}\n`);
+      process.exitCode = 1;
+      return;
+    }
+    process.stdout.write(
+      `同步完成:远端 ${outcome.total} 人 · 新建 ${outcome.inserted} · 更新 ${outcome.updated} · 停用 ${outcome.disabled}\n`,
+    );
+    for (const f of outcome.failed) process.stderr.write(`  ✗ ${f.account}:${f.reason}\n`);
+    if (outcome.failed.length > 0) process.exitCode = 1;
+
+    const { staff } = await container.org.listStaff();
+    process.stdout.write(`\n名册 ${staff.length} 人:\n`);
+    for (const s of staff) {
+      // 标出人 / 服务账号 —— 服务账号在 Keycloak 管理台的 Users 列表里也看不到,这里如实说
+      const kind = s.kind === 'service' ? '服务账号' : '人    ';
+      process.stdout.write(
+        `  ${kind} ${s.account.padEnd(32)} ${s.name.padEnd(14)} ${s.position.code.padEnd(5)} ${s.state.padEnd(9)} ${s.roles.join(',')}\n`,
+      );
+    }
+  } finally {
+    await container.close();
+  }
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  await syncRoster();
+}

apps/api/src/modules/org/CONTRACT.md

@@ -32,6 +32,15 @@
 
 不变量:
   - `Staff.id` 就是 Keycloak `sub`;`account` 只作显示,永不当键
+  - **姓在前、名在后**(2026-08-26 用户定):`Staff.name` 由 `personName` 一处拼 ——
+    token 那条路取 `family_name` / `given_name`,名册同步取 `lastName` / `firstName`;
+    **不吃 Keycloak 拼好的 `name` claim**(那是 `firstName lastName`,西式序)。
+    两边都是汉字直拼(「柴浩」),否则留一个空格(「Admin Amy」);皆空回落用户名。
+    拆不开的 realm(没配 profile scope)才退回 `name` claim —— 重排不了的东西如实用它。
+  - `Staff.kind` 由**账号名现判**、不落库:`service-account-<clientId>` 是 Keycloak 自己的命名,
+    开了 `serviceAccountsEnabled` 的 client 一律配一个。服务账号是**真身份**(试跑与 e2e 用它跑单),
+    但不是人 —— 员工管理那一屏据此不摆它,试跑台的负责人下拉照旧摆(铁规矩 6)。
+    按名字认不按角色认:角色是各 realm 自己配的,这个前缀由 Keycloak 保证
   - `state` 只由名册同步置 `disabled`;`authenticate` / `principalOf` 对 disabled 一律抛 AccountDisabledError,
     有效 token 不能把它翻回 active(撤权在同步之后即时生效)
   - **停用判定走在 JIT 写之前**:已停用的人攥着有效 token 也驱动不了 `updateIdentity`;
@@ -45,6 +54,16 @@
     ③落库之前按差异算一遍「同步后还有谁能进运营中心」,不过就整体拒绝(AccessLockoutError → 409),一条都不写
   - 同步逐条落库:**单条失败不停在半路**,失败的人点名进 `RosterSyncOutcome.failed`;
     三个计数说的是真落下的条数,不是打算写几条
+  - **成员目录**(`directory*`,ADR-012):没配 provisioning 就**整个不可用**(抛
+    `DirectoryUnavailableError` → 502),不给「读得了写不了」的半开状态 —— 那样人会以为是自己点错了。
+    读是投影、写**穿透**到 Keycloak(没有本地草稿,也没有撤销)。四条不变量:
+    ①**服务账号一律不可见不可写**(目录读剔干净、写面抛 `ServiceAccountProtectedError` → 403);
+    ②**停用与收权当场踢会话** —— 否则那枚 token 到期前照样通行,而屏上已经写了「已停用」;
+    ③**收权先算自锁**:收完没人进得了运营中心就整体拒(409),与改「角色→端」同一道闸、同一个理由;
+    ④**删人本地只停不删** —— 留痕、在途任务、台账的 `by` 都还指着这个 sub。
+  - 目录读有 **60 秒进程内缓存**,**任一写(成功或失败)之后整体清空**:写完立刻重拉一定看得到新结果,
+    前端不必延时重试。失败也清 —— 半途失败之后那份缓存说不清停在哪一边。
+    唯一滞后:**别的**管理员在另一个后端实例上写,这边最多滞后 60 秒。
   - `staffOfPosition` 只回 active;哨兵岗 NONE 恒回 []
   - `ensureSeeded` 幂等:岗位按 code 判存在;缺省角色→端只在表空时播;测试账号策略只补不覆盖
   - 工作组是绑定不是策略(ADR-011):`bindingOf` 只出成员表快照,在岗与否由调用方核

apps/api/src/modules/org/__tests__/claims.test.ts

@@ -1,6 +1,6 @@
 /** domain 测试零 mock(编码规范 §16) */
 import { describe, expect, it } from 'vitest';
-import { identityOf, isNoiseRole, normalizeRoles } from '../internal/domain/claims.ts';
+import { identityOf, isNoiseRole, normalizeRoles, personName, staffKindOf } from '../internal/domain/claims.ts';
 
 describe('identityOf —— claims 归一成一个人', () => {
   it('完整 claims:sub / 用户名 / 姓名 / 邮箱 / 角色(滤噪声、排序、去重)', () => {
@@ -27,7 +27,7 @@ describe('identityOf —— claims 归一成一个人', () => {
     expect('email' in id).toBe(false);
   });
 
-  it('姓/名散件在 → 姓在前拼「姓 名」,不采用全名字段的名+姓序(2026-08-26 用户定)', () => {
+  it('姓/名散件在 → 姓在前拼(汉字直拼,不留空格),不采用全名字段的名+姓序(2026-08-26 用户定)', () => {
     const id = identityOf({ sub: 's', preferred_username: 'shan', name: '亲 删', given_name: '亲', family_name: '删' });
     expect(id.name).toBe('删亲');
   });
@@ -48,3 +48,58 @@ describe('噪声角色', () => {
     expect(normalizeRoles(['user', '', 'admin', 'user'])).toEqual(['admin', 'user']);
   });
 });
+
+describe('staffKindOf —— 人还是服务账号', () => {
+  it('Keycloak 的 service-account-<clientId> 认作服务账号', () => {
+    expect(staffKindOf('service-account-task-dispatcher')).toBe('service');
+  });
+  it('大小写与前后空格不影响判断', () => {
+    expect(staffKindOf('  Service-Account-Provisioning ')).toBe('service');
+  });
+  it('真人一律 person —— 名字里带 service 也不算', () => {
+    expect(staffKindOf('chaihao')).toBe('person');
+    expect(staffKindOf('ai-test')).toBe('person');
+    expect(staffKindOf('service-desk')).toBe('person');
+    expect(staffKindOf('')).toBe('person');
+  });
+});
+
+describe('personName —— 姓在前、名在后', () => {
+  it('中文名直拼,不留空格', () => {
+    expect(personName({ familyName: '柴', givenName: '浩', fallback: 'chaihao' })).toBe('柴浩');
+    expect(personName({ familyName: '丁', givenName: '子乔', fallback: 'x' })).toBe('丁子乔');
+  });
+  it('非汉字留一个空格 —— 拼在一起会连成一个词', () => {
+    expect(personName({ familyName: 'Admin', givenName: 'Amy', fallback: 'amy' })).toBe('Admin Amy');
+  });
+  it('一边混着字母就留空格(拼死了读不出来是两截)', () => {
+    expect(personName({ familyName: '李', givenName: 'Ken', fallback: 'x' })).toBe('李 Ken');
+  });
+  it('只有一半就摆那一半,不留孤零零的空格', () => {
+    expect(personName({ familyName: '柴', fallback: 'chaihao' })).toBe('柴');
+    expect(personName({ givenName: '浩', fallback: 'chaihao' })).toBe('浩');
+  });
+  it('两边都空(或只有空白)→ 回落,名字这一格不许空着', () => {
+    expect(personName({ fallback: 'chaihao' })).toBe('chaihao');
+    expect(personName({ familyName: '  ', givenName: '', fallback: 'chaihao' })).toBe('chaihao');
+  });
+});
+
+describe('identityOf 的名字:自己拼,不吃 Keycloak 拼好的那个', () => {
+  it('有 family_name / given_name 就按姓在前拼 —— name claim 是西式序,不用它', () => {
+    const id = identityOf({
+      sub: 's',
+      preferred_username: 'chaihao',
+      name: '浩 柴',
+      given_name: '浩',
+      family_name: '柴',
+    });
+    expect(id.name).toBe('柴浩');
+  });
+  it('realm 没配 profile scope(拆不开)→ 如实用 name claim', () => {
+    expect(identityOf({ sub: 's', preferred_username: 'bob', name: 'Bob Lee' }).name).toBe('Bob Lee');
+  });
+  it('两样都没有 → 回落用户名', () => {
+    expect(identityOf({ sub: 's', preferred_username: 'bob' }).name).toBe('bob');
+  });
+});

apps/api/src/modules/org/__tests__/directory-service.test.ts

@@ -0,0 +1,313 @@
+/**
+ * 成员目录的用例层 —— 两道闸与一处缓存(ADR-012)。
+ * Keycloak 是外界,给它一个记账的替身(编码规范 §16:只有外界能 mock)。
+ */
+import { describe, expect, it } from 'vitest';
+import type { Position, RoleAccess, WorkGroup } from '@contracts';
+import { positionIdSchema } from '@contracts';
+import { AccessLockoutError, DirectoryUnavailableError, ServiceAccountProtectedError } from '../contract.ts';
+import type { DirectoryUser, KeycloakDirectory, OrgServiceDeps, StaffRecord } from '../index.ts';
+import { createOrgService } from '../index.ts';
+
+const PEOPLE: DirectoryUser[] = [
+  { sub: 'sub-admin', username: 'chaihao', enabled: true, emailVerified: true, roles: ['admin', 'user'] },
+  { sub: 'sub-user', username: 'linpeixuan', enabled: true, emailVerified: false, roles: ['user'] },
+  { sub: 'sub-svc', username: 'service-account-task-dispatcher', enabled: true, emailVerified: false, roles: ['service'] },
+];
+
+type Log = string[];
+
+/** 记账替身 —— 只回预置的形状,把调过什么记下来 */
+function fakeDirectory(log: Log, users = PEOPLE): KeycloakDirectory {
+  const find = (sub: string): DirectoryUser => {
+    const u = users.find((x) => x.sub === sub);
+    if (u === undefined) throw new Error(`没有这个人:${sub}`);
+    return u;
+  };
+  return {
+    listUsers: async () => {
+      log.push('listUsers');
+      return users;
+    },
+    getUser: async (sub) => ({ ...find(sub), groups: [] }),
+    createUser: async (input) => {
+      log.push(`createUser:${input.username}`);
+      return 'sub-new';
+    },
+    updateUser: async (sub) => void log.push(`updateUser:${sub}`),
+    setEnabled: async (sub, enabled) => void log.push(`setEnabled:${sub}:${String(enabled)}`),
+    resetPassword: async (sub) => void log.push(`resetPassword:${sub}`),
+    deleteUser: async (sub) => void log.push(`deleteUser:${sub}`),
+    logout: async (sub) => void log.push(`logout:${sub}`),
+    listRoles: async () => [
+      { name: 'admin', composite: false },
+      { name: 'user', composite: false },
+      { name: 'default-roles-corp', composite: true },
+    ],
+    setRole: async (sub, role, granted) => void log.push(`setRole:${sub}:${role}:${String(granted)}`),
+    listGroups: async () => {
+      log.push('listGroups');
+      return [{ id: 'g1', name: '技术部', path: '/技术部', depth: 0, memberCount: 0 }];
+    },
+    groupMembers: async () => users,
+    groupMemberUsernames: async () => users.map((u) => u.username),
+    createGroup: async (name) => {
+      log.push(`createGroup:${name}`);
+      return { id: 'g2', name, path: `/${name}`, depth: 0, memberCount: 0 };
+    },
+    renameGroup: async (id, name) => {
+      log.push(`renameGroup:${id}:${name}`);
+      return { id, name, path: `/${name}`, depth: 0, memberCount: 0 };
+    },
+    deleteGroup: async (id) => void log.push(`deleteGroup:${id}`),
+    setUserGroup: async (sub, gid, member) => void log.push(`setUserGroup:${sub}:${gid}:${String(member)}`),
+  };
+}
+
+function harness(opts: { directory?: KeycloakDirectory } = {}) {
+  const positions = new Map<string, Position>();
+  const staff = new Map<string, StaffRecord>();
+  const roleAccess = new Map<string, RoleAccess>([
+    ['admin', { role: 'admin', ends: ['design', 'ops', 'workbench'] }],
+    ['user', { role: 'user', ends: ['workbench'] }],
+  ]);
+  const groups = new Map<string, WorkGroup>();
+  let nowMs = Date.parse('2026-08-26T09:00:00Z');
+
+  const deps: OrgServiceDeps = {
+    verifier: { verify: async () => ({ sub: 'x', preferred_username: 'x' }) },
+    ...(opts.directory === undefined ? {} : { directory: opts.directory }),
+    positions: {
+      list: async () => [...positions.values()],
+      findByCode: async (code) => [...positions.values()].find((p) => p.code === code),
+      findById: async (id) => positions.get(id),
+      upsert: async (p) => {
+        const id = p.id ?? positionIdSchema.parse(p.code.toLowerCase());
+        const row: Position = { id, code: p.code, name: p.name };
+        positions.set(id, row);
+        return row;
+      },
+    },
+    staff: {
+      list: async () => [...staff.values()],
+      findById: async (id) => staff.get(id),
+      findByAccount: async (a) => [...staff.values()].find((s) => s.account === a),
+      listByPosition: async () => [],
+      insert: async (s, marks) => {
+        const row: StaffRecord = { ...s, ...marks };
+        staff.set(row.id, row);
+        return row;
+      },
+      updateIdentity: async () => undefined,
+      setPosition: async () => undefined,
+      setState: async (id, state) => {
+        const row = staff.get(id);
+        if (row !== undefined) staff.set(id, { ...row, state });
+      },
+    },
+    roleAccess: {
+      list: async () => [...roleAccess.values()],
+      upsert: async (row) => {
+        roleAccess.set(row.role, row);
+        return row;
+      },
+      remove: async (role) => void roleAccess.delete(role),
+    },
+    workGroups: {
+      listByOwner: async () => [],
+      upsert: async (g) => {
+        groups.set(g.id, g);
+        return g;
+      },
+    },
+    inFlight: { openTasksOf: async () => [], openCardsOf: async () => [], openApprovalsOf: async () => [] },
+    clock: { now: () => new Date(nowMs) },
+    ids: { next: () => 'id' },
+    testAccounts: [],
+  };
+  return { org: createOrgService(deps), staff, tick: (ms: number) => (nowMs += ms) };
+}
+
+describe('没配 provisioning —— 目录整个不可用,不给半开状态', () => {
+  it('读也不行,写也不行;话里说清缺什么', async () => {
+    const h = harness();
+    await expect(h.org.directoryUsers({})).rejects.toBeInstanceOf(DirectoryUnavailableError);
+    await expect(h.org.directoryGroups()).rejects.toBeInstanceOf(DirectoryUnavailableError);
+    await h.org.directoryUsers({}).catch((e: unknown) => {
+      expect((e as Error).message).toContain('KEYCLOAK_PROVISIONING_CLIENT_ID');
+      expect((e as DirectoryUnavailableError).misconfigured).toBe(true);
+    });
+  });
+});
+
+describe('服务账号:是身份,不是人', () => {
+  it('目录读里一个都不出现', async () => {
+    const h = harness({ directory: fakeDirectory([]) });
+    const { users } = await h.org.directoryUsers({ includeDisabled: true });
+    expect(users.map((u) => u.username)).toEqual(['chaihao', 'linpeixuan']);
+  });
+
+  it('对着它下手一律拒 —— 停掉它,试跑与 e2e 第二天全趴下', async () => {
+    const h = harness({ directory: fakeDirectory([]) });
+    await expect(h.org.setDirectoryUserEnabled('sub-svc', false)).rejects.toBeInstanceOf(ServiceAccountProtectedError);
+    await expect(h.org.deleteDirectoryUser('sub-svc')).rejects.toBeInstanceOf(ServiceAccountProtectedError);
+    await expect(h.org.setDirectoryUserRole('sub-svc', 'admin', false)).rejects.toBeInstanceOf(ServiceAccountProtectedError);
+  });
+
+  it('连建一个叫这名字的都不许 —— 免得从正门造出一个假服务账号', async () => {
+    const h = harness({ directory: fakeDirectory([]) });
+    await expect(
+      h.org.createDirectoryUser({ username: 'service-account-fake' }),
+    ).rejects.toBeInstanceOf(ServiceAccountProtectedError);
+  });
+
+  it('组成员里也剔干净', async () => {
+    const h = harness({ directory: fakeDirectory([]) });
+    const { members } = await h.org.directoryGroupMembers('g1');
+    expect(members.map((m) => m.username)).toEqual(['chaihao', 'linpeixuan']);
+  });
+});
+
+describe('收权不能把最后一个管理员关在门外', () => {
+  it('收掉唯一 admin 的 admin → 拒,一个字都没写出去', async () => {
+    const log: Log = [];
+    const h = harness({ directory: fakeDirectory(log, [PEOPLE[0]!, PEOPLE[1]!]) });
+    await expect(h.org.setDirectoryUserRole('sub-admin', 'admin', false)).rejects.toBeInstanceOf(AccessLockoutError);
+    expect(log.filter((l) => l.startsWith('setRole'))).toEqual([]);
+  });
+
+  it('还有另一个 admin 在 → 放行,并**当场踢掉他的会话**', async () => {
+    const log: Log = [];
+    const two: DirectoryUser[] = [
+      PEOPLE[0]!,
+      { sub: 'sub-admin2', username: 'amy', enabled: true, emailVerified: false, roles: ['admin', 'user'] },
+    ];
+    const h = harness({ directory: fakeDirectory(log, two) });
+    await h.org.setDirectoryUserRole('sub-admin', 'admin', false);
+    expect(log).toContain('setRole:sub-admin:admin:false');
+    // 不踢的话他手上那枚 token 到期前还带着 admin —— 收权要等过期才生效
+    expect(log).toContain('logout:sub-admin');
+  });
+
+  it('授权那一路不查自锁(只会更宽,锁不死)', async () => {
+    const log: Log = [];
+    const h = harness({ directory: fakeDirectory(log, [PEOPLE[1]!]) });
+    await h.org.setDirectoryUserRole('sub-user', 'admin', true);
+    expect(log).toContain('setRole:sub-user:admin:true');
+    expect(log).not.toContain('logout:sub-user');
+  });
+});
+
+describe('停用与删除:本地那一行跟手', () => {
+  it('停用 → 踢会话 + 本地置 disabled(两屏不许说两句话)', async () => {
+    const log: Log = [];
+    const h = harness({ directory: fakeDirectory(log) });
+    await h.org.ensureSeeded();
+    await h.org.registerIdentity({ sub: 'sub-user', account: 'linpeixuan', name: '佩萱 林', roles: ['user'] });
+    await h.org.setDirectoryUserEnabled('sub-user', false);
+    expect(log).toContain('setEnabled:sub-user:false');
+    expect(log).toContain('logout:sub-user');
+    expect(h.staff.get('sub-user')?.state).toBe('disabled');
+  });
+
+  it('启用不踢会话(他本来就登不上,踢什么)', async () => {
+    const log: Log = [];
+    const h = harness({ directory: fakeDirectory(log) });
+    await h.org.setDirectoryUserEnabled('sub-user', true);
+    expect(log).not.toContain('logout:sub-user');
+  });
+
+  it('删人 → 本地那一行**停用不删**:留痕、在途、台账都还指着这个 sub', async () => {
+    const log: Log = [];
+    const h = harness({ directory: fakeDirectory(log) });
+    await h.org.ensureSeeded();
+    await h.org.registerIdentity({ sub: 'sub-user', account: 'linpeixuan', name: '佩萱 林', roles: ['user'] });
+    await h.org.deleteDirectoryUser('sub-user');
+    expect(log).toContain('deleteUser:sub-user');
+    expect(h.staff.get('sub-user')?.state).toBe('disabled');
+    expect(h.staff.has('sub-user')).toBe(true);
+  });
+});
+
+describe('60 秒读缓存 —— 写完立刻清,不必延时重试', () => {
+  it('60 秒内不再问 Keycloak', async () => {
+    const log: Log = [];
+    const h = harness({ directory: fakeDirectory(log) });
+    await h.org.directoryUsers({});
+    await h.org.directoryUsers({ q: 'chai' });
+    expect(log.filter((l) => l === 'listUsers')).toHaveLength(1);
+  });
+
+  it('过了 60 秒自己重取', async () => {
+    const log: Log = [];
+    const h = harness({ directory: fakeDirectory(log) });
+    await h.org.directoryUsers({});
+    h.tick(61_000);
+    await h.org.directoryUsers({});
+    expect(log.filter((l) => l === 'listUsers')).toHaveLength(2);
+  });
+
+  /*
+   * 清缓存**按写真正碰到的东西清**。全清的代价看得见:删一个组之后下一次读要把
+   * 「全量成员的角色」那趟 N+1 重付一遍,屏上那棵树因此多钉着已经没了的组好几秒。
+   */
+  it('建组只清组那一份 —— 人的角色与端没变,别陪着重付一趟 N+1', async () => {
+    const log: Log = [];
+    const h = harness({ directory: fakeDirectory(log) });
+    await h.org.directoryUsers({});
+    await h.org.directoryGroups();
+    await h.org.createDirectoryGroup('新组');
+    await h.org.directoryUsers({});
+    await h.org.directoryGroups();
+    expect(log.filter((l) => l === 'listUsers')).toHaveLength(1);
+    expect(log.filter((l) => l === 'listGroups')).toHaveLength(2);
+  });
+
+  it('改资料只清人那一份 —— 组的成员数没变', async () => {
+    const log: Log = [];
+    const h = harness({ directory: fakeDirectory(log) });
+    await h.org.directoryUsers({});
+    await h.org.directoryGroups();
+    await h.org.patchDirectoryUser('sub-user', { firstName: '佩萱' });
+    await h.org.directoryUsers({});
+    await h.org.directoryGroups();
+    expect(log.filter((l) => l === 'listUsers')).toHaveLength(2);
+    expect(log.filter((l) => l === 'listGroups')).toHaveLength(1);
+  });
+
+  it('删人两边都清 —— 人没了,他在的那些组也少一个人', async () => {
+    const log: Log = [];
+    const h = harness({ directory: fakeDirectory(log) });
+    await h.org.directoryUsers({});
+    await h.org.directoryGroups();
+    await h.org.deleteDirectoryUser('sub-user');
+    await h.org.directoryUsers({});
+    await h.org.directoryGroups();
+    expect(log.filter((l) => l === 'listUsers')).toHaveLength(2);
+    expect(log.filter((l) => l === 'listGroups')).toHaveLength(2);
+  });
+
+  it('写**失败**了也清 —— 半途失败之后那份缓存说不清是哪一边', async () => {
+    const log: Log = [];
+    const dir = fakeDirectory(log);
+    const h = harness({
+      directory: { ...dir, createGroup: async () => { throw new Error('同级重名'); } },
+    });
+    await h.org.directoryGroups();
+    await expect(h.org.createDirectoryGroup('技术部')).rejects.toThrow('同级重名');
+    await h.org.directoryGroups();
+    expect(log.filter((l) => l === 'listGroups')).toHaveLength(2);
+  });
+});
+
+describe('角色清单', () => {
+  it('家具角色不摆(授收它没有意义),持有数按生效角色数', async () => {
+    const h = harness({ directory: fakeDirectory([]) });
+    const { roles } = await h.org.directoryRoles();
+    expect(roles.map((r) => r.name)).toEqual(['admin', 'user']);
+    // service-account 已剔,所以 user 是 2 不是 3
+    expect(roles.find((r) => r.name === 'user')?.holders).toBe(2);
+    expect(roles.find((r) => r.name === 'admin')?.holders).toBe(1);
+    expect(roles.find((r) => r.name === 'admin')?.ends).toEqual(['design', 'ops', 'workbench']);
+  });
+});

apps/api/src/modules/org/__tests__/directory.test.ts

@@ -0,0 +1,159 @@
+/** domain 测试零 mock(编码规范 §16) */
+import { describe, expect, it } from 'vitest';
+import type { RoleAccess } from '@contracts';
+import { positionIdSchema, staffIdSchema } from '@contracts';
+import type { DirectoryGroup, DirectoryRole, DirectoryUser, StoredStaff } from '../port.ts';
+import {
+  displayNameOf,
+  filterOrgUsers,
+  isServiceAccount,
+  localMarks,
+  sortOrgUsers,
+  toOrgGroups,
+  toOrgRoles,
+  toOrgUser,
+} from '../internal/domain/directory.ts';
+
+const TABLE: RoleAccess[] = [
+  { role: 'admin', ends: ['design', 'ops', 'workbench'] },
+  { role: 'user', ends: ['workbench'] },
+];
+
+const kc = (over: Partial<DirectoryUser> = {}): DirectoryUser => ({
+  sub: 'sub-1',
+  username: 'chaihao',
+  enabled: true,
+  emailVerified: false,
+  roles: ['admin', 'user'],
+  ...over,
+});
+
+describe('服务账号:是身份,不是人', () => {
+  it('Keycloak 的 service-account-<clientId> 认得出', () => {
+    expect(isServiceAccount('service-account-task-dispatcher')).toBe(true);
+    expect(isServiceAccount('chaihao')).toBe(false);
+    // 名字里带 service 不算 —— 认的是 Keycloak 那个固定前缀,不是关键词
+    expect(isServiceAccount('service-desk')).toBe(false);
+  });
+});
+
+describe('displayNameOf', () => {
+  it('姓在前、名在后 —— 中文名直拼', () => {
+    expect(displayNameOf({ username: 'a', firstName: '浩', lastName: '柴' })).toBe('柴浩');
+  });
+  it('只有一半就摆那一半', () => {
+    expect(displayNameOf({ username: 'a', lastName: '柴' })).toBe('柴');
+  });
+  it('两个都空 → 回落用户名,不回空串', () => {
+    expect(displayNameOf({ username: 'amy', firstName: '  ', lastName: '' })).toBe('amy');
+  });
+});
+
+describe('toOrgUser —— Keycloak 那份 + 本地那两列', () => {
+  it('ends 由本地表算,不是 Keycloak 的字段', () => {
+    expect(toOrgUser(kc(), TABLE).ends).toEqual(['design', 'ops', 'workbench']);
+    expect(toOrgUser(kc({ roles: ['user'] }), TABLE).ends).toEqual(['workbench']);
+  });
+  it('角色一行都没命中 → 无端可进(不是报错,是事实)', () => {
+    expect(toOrgUser(kc({ roles: ['service'] }), TABLE).ends).toEqual([]);
+  });
+  it('本地两列合进来;没有就整个键不出现', () => {
+    const withLocal = toOrgUser(kc(), TABLE, { lastSeenAt: new Date('2026-08-26T07:00:00Z'), positionCode: 'TEST' });
+    expect(withLocal.lastSeenAt).toBe('2026-08-26T07:00:00.000Z');
+    expect(withLocal.positionCode).toBe('TEST');
+    const bare = toOrgUser(kc(), TABLE);
+    expect('lastSeenAt' in bare).toBe(false);
+    expect('positionCode' in bare).toBe(false);
+  });
+});
+
+describe('sortOrgUsers —— 来过的在前', () => {
+  it('来过的按时刻倒序在前,没来过的按用户名在后', () => {
+    const rows = [
+      toOrgUser(kc({ sub: 'c', username: 'cathy' }), TABLE),
+      toOrgUser(kc({ sub: 'a', username: 'amy' }), TABLE, { lastSeenAt: new Date('2026-08-01T00:00:00Z') }),
+      toOrgUser(kc({ sub: 'b', username: 'bob' }), TABLE),
+      toOrgUser(kc({ sub: 'd', username: 'dan' }), TABLE, { lastSeenAt: new Date('2026-08-20T00:00:00Z') }),
+    ];
+    expect(sortOrgUsers(rows).map((u) => u.username)).toEqual(['dan', 'amy', 'bob', 'cathy']);
+  });
+});
+
+describe('filterOrgUsers —— 检索与「含停用」', () => {
+  const rows = [
+    toOrgUser(kc({ sub: '1', username: 'chaihao', firstName: '浩', lastName: '柴', email: 'a@x.com' }), TABLE),
+    toOrgUser(kc({ sub: '2', username: 'amy', enabled: false }), TABLE),
+  ];
+  it('缺省不摆停用的人', () => {
+    expect(filterOrgUsers(rows, '', false).map((u) => u.username)).toEqual(['chaihao']);
+  });
+  it('含停用 → 都摆', () => {
+    expect(filterOrgUsers(rows, '', true)).toHaveLength(2);
+  });
+  it('用户名 / 姓名 / 邮箱任一含关键词即命中,不区分大小写', () => {
+    expect(filterOrgUsers(rows, 'CHAI', true)).toHaveLength(1);
+    expect(filterOrgUsers(rows, '柴', true)).toHaveLength(1);
+    expect(filterOrgUsers(rows, 'a@x', true)).toHaveLength(1);
+  });
+  it('**含在中间**也搜得到 —— 这正是不转给 Keycloak 的 search= 的理由(那个是前缀式)', () => {
+    expect(filterOrgUsers(rows, 'aiha', true).map((u) => u.username)).toEqual(['chaihao']);
+  });
+  it('搜不到就是空,不是全量', () => {
+    expect(filterOrgUsers(rows, '查无此人', true)).toEqual([]);
+  });
+});
+
+describe('toOrgRoles', () => {
+  const roles: DirectoryRole[] = [
+    { name: 'admin', composite: false },
+    { name: 'user', composite: false, description: '员工' },
+  ];
+  it('每个角色配上本地算的 ends 与调用方数好的持有数', () => {
+    const out = toOrgRoles(roles, TABLE, [5, 8]);
+    expect(out[0]).toMatchObject({ name: 'admin', ends: ['design', 'ops', 'workbench'], holders: 5 });
+    expect(out[1]).toMatchObject({ name: 'user', ends: ['workbench'], holders: 8, description: '员工' });
+  });
+  it('持有数没给到那一位 → 0,不是 undefined', () => {
+    expect(toOrgRoles(roles, TABLE, [3])[1]?.holders).toBe(0);
+  });
+});
+
+describe('toOrgGroups —— 平表 + 成员数', () => {
+  const groups: DirectoryGroup[] = [
+    { id: 'g1', name: '技术部', path: '/技术部', depth: 0, memberCount: 0 },
+    { id: 'g2', name: '平台组', path: '/技术部/平台组', parentId: 'g1', depth: 1, memberCount: 0 },
+  ];
+  it('成员数由调用方现数;顶层组没有 parentId 那个键', () => {
+    const out = toOrgGroups(groups, new Map([['g1', 3]]));
+    expect(out[0]).toEqual({ id: 'g1', name: '技术部', path: '/技术部', depth: 0, memberCount: 3 });
+    expect(out[1]?.parentId).toBe('g1');
+  });
+  it('没数过的组是 0 —— 不给 undefined 让界面摆一个空格', () => {
+    expect(toOrgGroups(groups, new Map())[1]?.memberCount).toBe(0);
+  });
+});
+
+describe('localMarks', () => {
+  const none = positionIdSchema.parse('pos-none');
+  const staff: Array<StoredStaff & { lastSeenAt?: Date }> = [
+    {
+      id: staffIdSchema.parse('sub-1'),
+      account: 'chaihao',
+      name: '柴浩',
+      positionId: none,
+      state: 'active',
+      roles: ['admin'],
+      lastSeenAt: new Date('2026-08-26T07:00:00Z'),
+    },
+    { id: staffIdSchema.parse('sub-2'), account: 'amy', name: 'Amy', positionId: none, state: 'active', roles: [] },
+  ];
+  it('按 sub 索引;岗位查不到就不摆那个键', () => {
+    const marks = localMarks(staff, (id) => (id === none ? 'NONE' : undefined));
+    expect(marks.get('sub-1')).toEqual({ lastSeenAt: new Date('2026-08-26T07:00:00Z'), positionCode: 'NONE' });
+    expect('lastSeenAt' in (marks.get('sub-2') ?? {})).toBe(false);
+  });
+  it('岗位表里没有那一行 → 键不出现,不摆空串', () => {
+    const marks = localMarks(staff, () => undefined);
+    expect('positionCode' in (marks.get('sub-1') ?? {})).toBe(false);
+  });
+});

apps/api/src/modules/org/__tests__/keycloak-admin-roster.test.ts

@@ -8,8 +8,9 @@ function fakeKeycloak(): { fetch: typeof fetch; calls: string[] } {
     id: `sub-${i}`,
     username: `u${i}`,
     enabled: i !== 3,
-    firstName: i === 0 ? '' : '名',
+    // 第 0 位两边都空 —— 试的是「名字这一格不许空着,回落用户名」那一支
-    lastName: i === 0 ? '' : `${i}`,
+    firstName: i === 0 ? '' : '浩',
+    lastName: i === 0 ? '' : '柴',
     email: `u${i}@x.test`,
   }));
   const json = (body: unknown, status = 200): Response =>
@@ -42,13 +43,14 @@ function fakeKeycloak(): { fetch: typeof fetch; calls: string[] } {
 }
 
 describe('Keycloak Admin API 名册', () => {
-  it('分页拉全(100 + 5)、姓名姓在前拼 lastName firstName、缺名回退用户名、角色滤噪声、enabled 照抄', async () => {
+  it('分页拉全(100 + 5)、姓在前名在后、缺名回退用户名、角色滤噪声、enabled 照抄', async () => {
     const kc = fakeKeycloak();
     const roster = createKeycloakRoster({ url: 'https://kc.test/', realm: 'corp', clientId: 'provisioning', secret: 's', fetch: kc.fetch });
     const users = await roster.listUsers();
     expect(users).toHaveLength(105);
     expect(users[0]).toEqual({ sub: 'sub-0', account: 'u0', name: 'u0', email: 'u0@x.test', roles: ['user'], enabled: true });
-    expect(users[1]).toEqual({ sub: 'sub-1', account: 'u1', name: '1 名', email: 'u1@x.test', roles: ['admin', 'user'], enabled: true });
+    // 姓在前:lastName「柴」+ firstName「浩」= 柴浩(中文直拼,不留空格)
+    expect(users[1]).toEqual({ sub: 'sub-1', account: 'u1', name: '柴浩', email: 'u1@x.test', roles: ['admin', 'user'], enabled: true });
     expect(users[3]?.enabled).toBe(false);
     expect(kc.calls.filter((c) => c.includes('/users?')).length).toBe(2);
   });

apps/api/src/modules/org/__tests__/keycloak-token-verifier.test.ts

@@ -62,6 +62,24 @@ describe('Keycloak 验签', () => {
     expect(claims.realm_access?.roles).toContain('user');
   });
 
+  /*
+   * 验签这一层是**挑字段**拼 `VerifiedClaims` 的 —— 类型上加了字段而这儿忘了挑,
+   * 编译一声不吭,下游拿到的永远是 undefined。实测栽过一次:
+   * 姓名改「姓在前」之后每个请求还是把名字写回西式序,查了两台后端才发现漏在这儿。
+   * 所以这条钉的是**整条链**:真 token 的形状进去,`identityOf` 认得出的形状出来。
+   */
+  it('given_name / family_name 要原样带出来 —— 姓在前的拼法全靠它俩', async () => {
+    const claims = await verifier.verify(await mint({ claims: { given_name: '浩', family_name: '柴' } }));
+    expect(claims.given_name).toBe('浩');
+    expect(claims.family_name).toBe('柴');
+  });
+
+  it('token 里没有那两个 claim → 键干脆不出现(不是 undefined)', async () => {
+    const claims = await verifier.verify(await mint());
+    expect('given_name' in claims).toBe(false);
+    expect('family_name' in claims).toBe(false);
+  });
+
   it('过期 30 秒内(时钟容差)仍通过', async () => {
     await expect(verifier.verify(await mint({ exp: nowSec() - 10 }))).resolves.toBeDefined();
   });

apps/api/src/modules/org/__tests__/org-service.test.ts

@@ -243,6 +243,22 @@ describe('名册与岗位', () => {
     expect(await h.org.staffOfPosition('NONE')).toEqual([]);
   });
 
+  it('listStaff 给每行标 kind —— 服务账号是身份不是人(员工管理那一屏据此不摆它)', async () => {
+    const h = harness();
+    await h.org.ensureSeeded();
+    await h.org.registerIdentity({ sub: 'p', account: 'chaihao', name: '柴浩', roles: ['admin'] });
+    await h.org.registerIdentity({
+      sub: 's',
+      account: 'service-account-task-dispatcher',
+      name: 'service-account-task-dispatcher',
+      roles: ['service'],
+    });
+    const { staff } = await h.org.listStaff();
+    const kinds = Object.fromEntries(staff.map((x) => [x.account, x.kind]));
+    expect(kinds['chaihao']).toBe('person');
+    expect(kinds['service-account-task-dispatcher']).toBe('service');
+  });
+
   it('syncRoster 未配置 → configured:false', async () => {
     const h = harness();
     await h.org.ensureSeeded();

apps/api/src/modules/org/__tests__/roster-diff.test.ts

@@ -1,12 +1,11 @@
 /** domain 测试零 mock(编码规范 §16) */
 import { describe, expect, it } from 'vitest';
-import type { Staff } from '@contracts';
 import { positionIdSchema, staffIdSchema } from '@contracts';
 import { activeRolesAfter, diffRoster, identityChanged, sameRoles } from '../internal/domain/roster-diff.ts';
-import type { RosterUser } from '../port.ts';
+import type { RosterUser, StoredStaff } from '../port.ts';
 
 const none = positionIdSchema.parse('none');
-const local = (sub: string, over: Partial<Staff> = {}): Staff => ({
+const local = (sub: string, over: Partial<StoredStaff> = {}): StoredStaff => ({
   id: staffIdSchema.parse(sub),
   account: sub,
   name: sub,

apps/api/src/modules/org/contract.ts

@@ -7,6 +7,10 @@
  */
 import type {
   InFlightWork,
+  OrgGroup,
+  OrgRole,
+  OrgUser,
+  OrgUserDetail,
   Position,
   PositionId,
   Principal,
@@ -19,7 +23,27 @@ import type {
   WorkGroupBinding,
 } from '@contracts';
 
-export type { InFlightWork, Position, Principal, RoleAccess, RosterSyncOutcome, Staff, Surface, WorkGroup, WorkGroupBinding };
+export type { InFlightWork, OrgGroup, OrgRole, OrgUser, OrgUserDetail, Position, Principal, RoleAccess, RosterSyncOutcome, Staff, Surface, WorkGroup, WorkGroupBinding };
+/**
+ * 目录写面的两个入参 —— 住在 contract.ts 而不是 port.ts:它们是**服务出口的形状**
+ * (路由照它填),port 只是恰好也要用。反过来放会让 port ↔ contract 成环。
+ */
+export type CreateDirectoryUser = {
+  readonly username: string;
+  readonly firstName?: string;
+  readonly lastName?: string;
+  readonly email?: string;
+  /** 临时口令;不给就建一个还登不进来的壳 */
+  readonly password?: string;
+  /** 一并授的 realm 角色 */
+  readonly roles?: readonly string[];
+};
+
+export type DirectoryUserPatch = {
+  readonly firstName?: string;
+  readonly lastName?: string;
+  readonly email?: string;
+};
 
 /** 员工连同其岗位的读模型 —— 治理台员工管理列表用 */
 export type StaffWithPosition = Staff & { readonly position: Position };
@@ -78,6 +102,32 @@ export class AccessLockoutError extends Error {
   }
 }
 
+/**
+ * 目录整个不可用 —— 没配 provisioning 服务账号,或那个账号缺 realm-management 角色。
+ * **重试无益**:路由译成 502 并原样带出 Keycloak 的话,界面提示找管理员补权限(手册 §14.6)。
+ */
+export class DirectoryUnavailableError extends Error {
+  /** true = 配错了(补权限);false = 暂时够不着(可退避重试)—— 两句话,人的下一步不同 */
+  readonly misconfigured: boolean;
+  constructor(message: string, misconfigured: boolean) {
+    super(message);
+    this.name = 'DirectoryUnavailableError';
+    this.misconfigured = misconfigured;
+  }
+}
+
+/**
+ * 写面对着一个服务账号 —— 拒。它是 Keycloak 给 client 自动建的身份(见 `staffKindSchema`),
+ * 在这三个页签里**根本不该出现**;能对着它下手,只能是有人手输了 sub。
+ * 停掉它的后果不显眼却很重:试跑与 e2e 第二天全趴下。
+ */
+export class ServiceAccountProtectedError extends Error {
+  constructor(readonly account: string) {
+    super(`「${account}」是服务账号,不是人 —— 成员目录不管它;要停它去 Keycloak 停对应的 client`);
+    this.name = 'ServiceAccountProtectedError';
+  }
+}
+
 export type OrgService = {
   /* ── 身份(ADR-012)—— 中间件在 app 层,身份判定读这里 ─────────────── */
 
@@ -109,6 +159,31 @@ export type OrgService = {
   /** 能进该端的活跃员工 —— 治理台通知的收件人 */
   staffWithEnd(surface: Surface): Promise<StaffWithPosition[]>;
 
+  /* ── 成员目录(Keycloak Admin API 的读写面;ADR-012) ────────────────── */
+
+  /**
+   * 目录**没配 provisioning 服务账号就整个不可用** —— 一律抛 `DirectoryUnavailableError`
+   * (路由译成 502 + 原话)。不给「读得了写不了」这种半开状态:那样人会以为是自己点错了。
+   * 服务账号在这一层就剔干净;写面对着服务账号的 sub 一律抛 `ServiceAccountProtectedError`。
+   */
+  directoryUsers(query: { q?: string; includeDisabled?: boolean }): Promise<{ users: OrgUser[] }>;
+  directoryUser(sub: string): Promise<OrgUserDetail>;
+  createDirectoryUser(input: CreateDirectoryUser): Promise<OrgUser>;
+  patchDirectoryUser(sub: string, patch: DirectoryUserPatch): Promise<OrgUser>;
+  /** 停用顺手踢会话 —— 界面写了「已停用」,那枚 token 就不该还能用到过期 */
+  setDirectoryUserEnabled(sub: string, enabled: boolean): Promise<OrgUser>;
+  resetDirectoryUserPassword(sub: string, password: string): Promise<void>;
+  deleteDirectoryUser(sub: string): Promise<void>;
+  directoryRoles(): Promise<{ roles: OrgRole[] }>;
+  /** 授 / 收一个 realm 角色;收权顺手踢会话。抛 AccessLockoutError(409):收完没人进得了运营中心 */
+  setDirectoryUserRole(sub: string, role: string, granted: boolean): Promise<OrgUser>;
+  directoryGroups(): Promise<{ groups: OrgGroup[] }>;
+  directoryGroupMembers(groupId: string): Promise<{ members: OrgUser[] }>;
+  createDirectoryGroup(name: string, parentId?: string): Promise<OrgGroup>;
+  renameDirectoryGroup(groupId: string, name: string): Promise<OrgGroup>;
+  deleteDirectoryGroup(groupId: string): Promise<void>;
+  setDirectoryUserGroup(sub: string, groupId: string, member: boolean): Promise<void>;
+
   /* ── 工作组(ADR-011)—— 起单时的岗位绑定,不是第五种策略 ────────────── */
 
   /** 建组 / 改组;id 留空即新建 */

apps/api/src/modules/org/index.ts

@@ -2,9 +2,15 @@
  * module: org —— 唯一出口。只做 re-export,不写逻辑(编码规范 §10.1)。
  */
 export type {
+  CreateDirectoryUser,
+  DirectoryUserPatch,
   Identity,
   InFlightWork,
+  OrgGroup,
+  OrgRole,
   OrgService,
+  OrgUser,
+  OrgUserDetail,
   Position,
   Principal,
   RoleAccess,
@@ -18,16 +24,22 @@ export type {
 export {
   AccessLockoutError,
   AccountDisabledError,
+  DirectoryUnavailableError,
   PositionNotFoundError,
+  ServiceAccountProtectedError,
   StaffNotFoundError,
   TokenRejectedError,
 } from './contract.ts';
 
 export type {
   Clock,
+  DirectoryGroup,
+  DirectoryRole,
+  DirectoryUser,
   IdGenerator,
   IdentityPatch,
   InFlightWorkProbe,
+  KeycloakDirectory,
   PositionRepository,
   RoleAccessRepository,
   RosterSource,
@@ -44,6 +56,15 @@ export { createOrgService } from './internal/usecase/org-service.ts';
 
 export { identityOf, isNoiseRole, normalizeRoles } from './internal/domain/claims.ts';
 export { assertNotLockedOut, endsOf, normalizeEnds } from './internal/domain/ends.ts';
+export {
+  displayNameOf,
+  filterOrgUsers,
+  isServiceAccount,
+  sortOrgUsers,
+  toOrgGroups,
+  toOrgRoles,
+  toOrgUser,
+} from './internal/domain/directory.ts';
 export { buildInFlightWork } from './internal/domain/in-flight.ts';
 export { DEFAULT_ROLE_ACCESS, NONE_POSITION_CODE, POSITION_SEED, TEST_POSITION_CODE } from './internal/domain/seed-data.ts';
 
@@ -51,6 +72,9 @@ export { createKeycloakTokenVerifier, explainJoseError } from './internal/adapte
 export type { KeycloakVerifierOptions } from './internal/adapter/keycloak-token-verifier.ts';
 export { createKeycloakRoster } from './internal/adapter/keycloak-admin-roster.ts';
 export type { KeycloakRosterOptions } from './internal/adapter/keycloak-admin-roster.ts';
+export { createKeycloakDirectory } from './internal/adapter/keycloak-directory.ts';
+export { createAdminHttp, KeycloakMisconfiguredError, KeycloakRejectedError, KeycloakUnavailableError } from './internal/adapter/keycloak-admin-http.ts';
+export type { AdminHttp, KeycloakAdminOptions } from './internal/adapter/keycloak-admin-http.ts';
 export {
   createPositionRepository,
   createRoleAccessRepository,

apps/api/src/modules/org/internal/adapter/keycloak-admin-http.ts

@@ -0,0 +1,143 @@
+/**
+ * Keycloak Admin API 的 HTTP 底座(手册 §11 / §14;ADR-012)。
+ *
+ * 名册同步与成员目录**共用同一枚管理 token** —— 从前只有名册那一条路,
+ * token 缓存写在它里面;目录接上来之后各缓存一份就是两条独立的续期时钟,
+ * 边界上谁先过期谁自己去换,白烧两次握手,还没人说得清当下在用哪一枚。
+ *
+ * 三条路径规则照手册 §14.1:`{client-uuid}` 不是 clientId、创建返回 201 空体
+ * (新 id 在 `Location` 末段)、列表默认 `max=100` 必须分页。
+ *
+ * 错误分两种说 —— **重试有没有意义,决定了界面该说什么话**:
+ *   `KeycloakMisconfiguredError`(401/403)= 服务账号缺角色或凭证不对,重试无益;
+ *   `KeycloakUnavailableError`(网络 / 5xx)= 暂时够不着,过会儿再来。
+ */
+
+/** 服务账号缺 `realm-management` 角色,或凭证不对 —— 重试无益,去补权限 */
+export class KeycloakMisconfiguredError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'KeycloakMisconfiguredError';
+  }
+}
+
+/** Keycloak 暂时够不着(网络 / 5xx)—— 可退避重试 */
+export class KeycloakUnavailableError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'KeycloakUnavailableError';
+  }
+}
+
+/** Keycloak 明确拒绝了这次写(重名 / 约束不过)—— 原话带出去给人看 */
+export class KeycloakRejectedError extends Error {
+  readonly status: number;
+  constructor(status: number, message: string) {
+    super(message);
+    this.name = 'KeycloakRejectedError';
+    this.status = status;
+  }
+}
+
+export type KeycloakAdminOptions = {
+  readonly url: string;
+  readonly realm: string;
+  readonly clientId: string;
+  readonly secret: string;
+  /** 测试注入;缺省全局 fetch */
+  readonly fetch?: typeof fetch;
+  /** 毫秒时刻;测试注入 */
+  readonly now?: () => number;
+};
+
+export type AdminHttp = {
+  get<T>(path: string): Promise<T>;
+  /** 建资源:成功 201 空体,回 `Location` 末段(新 id);Keycloak 不给就回 undefined */
+  post(path: string, body?: unknown): Promise<string | undefined>;
+  put(path: string, body?: unknown): Promise<void>;
+  /** `body` 可选是因为**撤 realm 角色是带 body 的 DELETE**(手册 §14.4),不是笔误 */
+  delete(path: string, body?: unknown): Promise<void>;
+};
+
+/** 列表接口默认 `max=100`(手册 §14.1 第三条),分页取全 */
+export const ADMIN_PAGE = 100;
+
+export function createAdminHttp(options: KeycloakAdminOptions): AdminHttp {
+  const fetchImpl = options.fetch ?? fetch;
+  const now = options.now ?? ((): number => Date.now());
+  const base = options.url.replace(/\/+$/, '');
+  const realmBase = `${base}/admin/realms/${options.realm}`;
+  let cached: { token: string; expiresAt: number } | undefined;
+
+  async function call(path: string, init: RequestInit): Promise<Response> {
+    try {
+      return await fetchImpl(path, init);
+    } catch (error) {
+      throw new KeycloakUnavailableError(`够不着 Keycloak:${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+
+  async function adminToken(): Promise<string> {
+    if (cached !== undefined && now() < cached.expiresAt) return cached.token;
+    const resp = await call(`${base}/realms/master/protocol/openid-connect/token`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/x-www-form-urlencoded' },
+      body: new URLSearchParams({
+        grant_type: 'client_credentials',
+        client_id: options.clientId,
+        client_secret: options.secret,
+      }),
+    });
+    if (!resp.ok) {
+      const text = await resp.text();
+      // 401/400 在这条路上一律是凭证不对(client_id / secret)—— 重试一百次也是同一句
+      if (resp.status < 500) throw new KeycloakMisconfiguredError(`取管理 token 失败:${resp.status} ${text}`);
+      throw new KeycloakUnavailableError(`取管理 token 失败:${resp.status} ${text}`);
+    }
+    const data = (await resp.json()) as { access_token: string; expires_in: number };
+    // 提前 60 秒过期,免得边界上拿着一枚刚好失效的 token 去调
+    cached = { token: data.access_token, expiresAt: now() + (data.expires_in - 60) * 1000 };
+    return cached.token;
+  }
+
+  async function send(method: string, path: string, body?: unknown): Promise<Response> {
+    const token = await adminToken();
+    const resp = await call(`${realmBase}${path}`, {
+      method,
+      headers: {
+        authorization: `Bearer ${token}`,
+        ...(body === undefined ? {} : { 'content-type': 'application/json' }),
+      },
+      ...(body === undefined ? {} : { body: JSON.stringify(body) }),
+    });
+    if (resp.ok) return resp;
+    const text = await resp.text();
+    const where = `${method} ${path}`;
+    if (resp.status === 401 || resp.status === 403) {
+      // 手册 §14.6:403 就是服务账号缺 realm-management 角色 —— 说清缺在哪一步
+      throw new KeycloakMisconfiguredError(
+        `${where} 被拒(${resp.status})—— provisioning 服务账号缺 realm-management 角色(手册 §14.6);原话:${text}`,
+      );
+    }
+    if (resp.status >= 500) throw new KeycloakUnavailableError(`${where} 失败(${resp.status}):${text}`);
+    throw new KeycloakRejectedError(resp.status, `${where} 被拒(${resp.status}):${text}`);
+  }
+
+  return {
+    async get<T>(path: string): Promise<T> {
+      return (await (await send('GET', path)).json()) as T;
+    },
+    async post(path: string, body?: unknown): Promise<string | undefined> {
+      const resp = await send('POST', path, body);
+      // 手册 §14.1 第二条:新资源 id 在 Location 末段,响应体是空的
+      const location = resp.headers.get('location');
+      return location === null ? undefined : location.split('/').pop();
+    },
+    async put(path: string, body?: unknown): Promise<void> {
+      await send('PUT', path, body);
+    },
+    async delete(path: string, body?: unknown): Promise<void> {
+      await send('DELETE', path, body);
+    },
+  };
+}

apps/api/src/modules/org/internal/adapter/keycloak-admin-roster.ts

@@ -7,7 +7,7 @@
  * 需要的 realm-management 角色只有 `view-users`(手册 14.6 最小权限)。
  */
 import type { RosterSource, RosterUser } from '../../port.ts';
-import { normalizeRoles } from '../domain/claims.ts';
+import { normalizeRoles, personName } from '../domain/claims.ts';
 
 export type KeycloakRosterOptions = {
   readonly url: string;
@@ -76,15 +76,15 @@ export function createKeycloakRoster(options: KeycloakRosterOptions): RosterSour
       const out: RosterUser[] = [];
       for (const u of users) {
         const roles = await adminGet<KcRole[]>(`/users/${encodeURIComponent(u.id)}/role-mappings/realm/composite`);
-        /* 姓在前(2026-08-26 用户定)—— 与 token 那条路(claims.ts `identityOf`)同一把尺 */
-        const name = [u.lastName, u.firstName]
-          .filter((s): s is string => s !== undefined && s.trim() !== '')
-          .join(' ')
-          .trim();
         out.push({
           sub: u.id,
           account: u.username,
-          name: name === '' ? u.username : name,
+          // 姓在前、名在后 —— 与 token 那条路同一把尺(`personName`),两处理解不许分叉
+          name: personName({
+            ...(u.lastName === undefined ? {} : { familyName: u.lastName }),
+            ...(u.firstName === undefined ? {} : { givenName: u.firstName }),
+            fallback: u.username,
+          }),
           // 与 token 那条路同一把尺 —— 归一自己再写一遍,两处理解一分叉,
           // `identityChanged` 的逐字比对就会天天判「变了」(或天天判「没变」)
           roles: normalizeRoles(roles.map((r) => r.name)),

apps/api/src/modules/org/internal/adapter/keycloak-directory.ts

@@ -0,0 +1,262 @@
+/**
+ * 成员目录 —— Keycloak Admin API 的读写面(手册 §14;ADR-012)。
+ *
+ * 与名册同步(`keycloak-admin-roster.ts`)共用 `createAdminHttp` 的那枚管理 token。
+ * 这里**不做过滤、不做归并**:剔服务账号、拼 `ends`、合本地岗位都归 domain 与 usecase ——
+ * 适配器只把 Keycloak 的形状原样翻过来,翻错了一眼看得出。
+ */
+import type {
+  AdminHttp,
+  KeycloakAdminOptions,
+} from './keycloak-admin-http.ts';
+import { ADMIN_PAGE, createAdminHttp } from './keycloak-admin-http.ts';
+import type { CreateDirectoryUser, DirectoryUserPatch } from '../../contract.ts';
+import type {
+  DirectoryGroup,
+  DirectoryRole,
+  DirectoryUser,
+  KeycloakDirectory,
+} from '../../port.ts';
+import { normalizeRoles } from '../domain/claims.ts';
+
+type KcUser = {
+  readonly id: string;
+  readonly username: string;
+  readonly enabled: boolean;
+  readonly emailVerified?: boolean;
+  readonly firstName?: string;
+  readonly lastName?: string;
+  readonly email?: string;
+};
+type KcRole = { readonly name: string; readonly description?: string; readonly composite?: boolean };
+type KcGroup = {
+  readonly id: string;
+  readonly name: string;
+  readonly path: string;
+  readonly subGroups?: readonly KcGroup[];
+};
+
+/** 空串与 undefined 是同一件事:Keycloak 那边没填,别在契约里变成一个空格子 */
+function opt(value: string | undefined): { [k: string]: string } {
+  return value === undefined || value.trim() === '' ? {} : { v: value.trim() };
+}
+
+function toUser(u: KcUser, roles: readonly string[]): DirectoryUser {
+  const first = opt(u.firstName);
+  const last = opt(u.lastName);
+  const mail = opt(u.email);
+  return {
+    sub: u.id,
+    username: u.username,
+    enabled: u.enabled,
+    emailVerified: u.emailVerified === true,
+    roles: normalizeRoles([...roles]),
+    ...(first.v === undefined ? {} : { firstName: first.v }),
+    ...(last.v === undefined ? {} : { lastName: last.v }),
+    ...(mail.v === undefined ? {} : { email: mail.v }),
+  };
+}
+
+const enc = encodeURIComponent;
+
+/**
+ * 有限并发地跑一批 —— Keycloak 没有「一次拿回全部人的角色」的接口(手册 §14.4 逐人查),
+ * 串行跑 8 个人就是 8 趟远程往返(实测整页 37 秒)。并发上限压着,
+ * 免得一屏把管理端打成一次小型压测。
+ */
+async function mapLimit<T, R>(items: readonly T[], limit: number, run: (item: T) => Promise<R>): Promise<R[]> {
+  const out: R[] = new Array<R>(items.length);
+  let cursor = 0;
+  const workers = Array.from({ length: Math.min(limit, items.length) }, async () => {
+    for (;;) {
+      const i = cursor;
+      cursor += 1;
+      if (i >= items.length) return;
+      out[i] = await run(items[i]!);
+    }
+  });
+  await Promise.all(workers);
+  return out;
+}
+
+const ROLE_FETCH_CONCURRENCY = 8;
+
+export function createKeycloakDirectory(options: KeycloakAdminOptions, http?: AdminHttp): KeycloakDirectory {
+  const api = http ?? createAdminHttp(options);
+
+  /** 实际生效的 realm 角色 —— 排查权限永远看 `/composite`(手册 §14.4) */
+  async function rolesOf(sub: string): Promise<string[]> {
+    const roles = await api.get<KcRole[]>(`/users/${enc(sub)}/role-mappings/realm/composite`);
+    return roles.map((r) => r.name);
+  }
+
+  async function allUsers(): Promise<KcUser[]> {
+    const out: KcUser[] = [];
+    for (let first = 0; ; first += ADMIN_PAGE) {
+      const page = await api.get<KcUser[]>(`/users?first=${first}&max=${ADMIN_PAGE}&briefRepresentation=false`);
+      out.push(...page);
+      if (page.length < ADMIN_PAGE) break;
+    }
+    return out;
+  }
+
+  /** 一行一个组;`subGroups` 递归摊平,顺手记住谁是谁的爹 */
+  function flatten(nodes: readonly KcGroup[], parentId: string | undefined, depth: number, into: DirectoryGroup[]): void {
+    for (const g of nodes) {
+      into.push({
+        id: g.id,
+        name: g.name,
+        path: g.path,
+        depth,
+        memberCount: 0, // 由 usecase 按组成员现数 —— Keycloak 的组表不带这个数
+        ...(parentId === undefined ? {} : { parentId }),
+      });
+      flatten(g.subGroups ?? [], g.id, depth + 1, into);
+    }
+  }
+
+  /** 口令一律**临时**:本人首登必须改(手册 §14.2);我们不存、不回显、不留痕 */
+  async function resetPassword(sub: string, password: string): Promise<void> {
+    await api.put(`/users/${enc(sub)}/reset-password`, { type: 'password', value: password, temporary: true });
+  }
+
+  async function setRole(sub: string, role: string, granted: boolean): Promise<void> {
+    // 授/撤的 body 是**角色对象数组**(手册 §14.4)—— 光给名字 Keycloak 不认
+    const all = await api.get<Array<KcRole & { id: string }>>('/roles');
+    const target = all.find((r) => r.name === role);
+    if (target === undefined) throw new Error(`realm 里没有角色「${role}」`);
+    const body = [{ id: target.id, name: target.name }];
+    const path = `/users/${enc(sub)}/role-mappings/realm`;
+    if (granted) await api.post(path, body);
+    else await api.delete(path, body);
+  }
+
+  async function rawGroupMembers(groupId: string): Promise<KcUser[]> {
+    const members: KcUser[] = [];
+    for (let first = 0; ; first += ADMIN_PAGE) {
+      const page = await api.get<KcUser[]>(`/groups/${enc(groupId)}/members?first=${first}&max=${ADMIN_PAGE}`);
+      members.push(...page);
+      if (page.length < ADMIN_PAGE) break;
+    }
+    return members;
+  }
+
+  async function groupById(groupId: string): Promise<DirectoryGroup> {
+    const g = await api.get<KcGroup>(`/groups/${enc(groupId)}`);
+    const segments = g.path.split('/').filter((s) => s !== '');
+    return { id: g.id, name: g.name, path: g.path, depth: segments.length - 1, memberCount: 0 };
+  }
+
+  return {
+    async listUsers() {
+      const users = await allUsers();
+      return mapLimit(users, ROLE_FETCH_CONCURRENCY, async (u) => toUser(u, await rolesOf(u.id)));
+    },
+
+    async getUser(sub) {
+      const u = await api.get<KcUser>(`/users/${enc(sub)}`);
+      const [roles, groups] = await Promise.all([
+        rolesOf(sub),
+        api.get<Array<{ id: string; path: string }>>(`/users/${enc(sub)}/groups`),
+      ]);
+      return { ...toUser(u, roles), groups: groups.map((g) => ({ id: g.id, path: g.path })) };
+    },
+
+    async createUser(input: CreateDirectoryUser) {
+      const first = opt(input.firstName);
+      const last = opt(input.lastName);
+      const mail = opt(input.email);
+      const sub = await api.post('/users', {
+        username: input.username,
+        enabled: true,
+        ...(first.v === undefined ? {} : { firstName: first.v }),
+        ...(last.v === undefined ? {} : { lastName: last.v }),
+        ...(mail.v === undefined ? {} : { email: mail.v }),
+      });
+      if (sub === undefined) throw new Error('Keycloak 建用户成功但没回 Location —— 拿不到新 id,别往下走');
+      if (input.password !== undefined) await resetPassword(sub, input.password);
+      for (const role of input.roles ?? []) await setRole(sub, role, true);
+      return sub;
+    },
+
+    async updateUser(sub, patch: DirectoryUserPatch) {
+      // 手册 §14.2:PUT 是全量覆盖 —— 先 GET 再改再 PUT,不然没带的字段会被清空
+      const current = await api.get<KcUser>(`/users/${enc(sub)}`);
+      const first = opt(patch.firstName ?? current.firstName);
+      const last = opt(patch.lastName ?? current.lastName);
+      const mail = opt(patch.email ?? current.email);
+      await api.put(`/users/${enc(sub)}`, {
+        ...current,
+        firstName: first.v ?? '',
+        lastName: last.v ?? '',
+        email: mail.v ?? '',
+      });
+    },
+
+    async setEnabled(sub, enabled) {
+      const current = await api.get<KcUser>(`/users/${enc(sub)}`);
+      await api.put(`/users/${enc(sub)}`, { ...current, enabled });
+    },
+
+    resetPassword,
+
+    async deleteUser(sub) {
+      await api.delete(`/users/${enc(sub)}`);
+    },
+
+    async logout(sub) {
+      await api.post(`/users/${enc(sub)}/logout`);
+    },
+
+    async listRoles(): Promise<readonly DirectoryRole[]> {
+      const roles = await api.get<KcRole[]>('/roles');
+      return roles.map((r) => ({
+        name: r.name,
+        composite: r.composite === true,
+        ...(r.description === undefined || r.description.trim() === '' ? {} : { description: r.description.trim() }),
+      }));
+    },
+
+    setRole,
+
+    async listGroups() {
+      const tree = await api.get<KcGroup[]>('/groups?briefRepresentation=false');
+      const flat: DirectoryGroup[] = [];
+      flatten(tree, undefined, 0, flat);
+      return flat.sort((a, b) => a.path.localeCompare(b.path));
+    },
+
+    async groupMembers(groupId) {
+      const members = await rawGroupMembers(groupId);
+      return mapLimit(members, ROLE_FETCH_CONCURRENCY, async (u) => toUser(u, await rolesOf(u.id)));
+    },
+
+    async groupMemberUsernames(groupId) {
+      return (await rawGroupMembers(groupId)).map((u) => u.username);
+    },
+
+
+    async createGroup(name, parentId) {
+      const path = parentId === undefined ? '/groups' : `/groups/${enc(parentId)}/children`;
+      const id = await api.post(path, { name });
+      if (id === undefined) throw new Error('Keycloak 建组成功但没回 Location —— 拿不到新 id,别往下走');
+      return groupById(id);
+    },
+
+    async renameGroup(groupId, name) {
+      const current = await api.get<KcGroup>(`/groups/${enc(groupId)}`);
+      await api.put(`/groups/${enc(groupId)}`, { ...current, name });
+      return groupById(groupId);
+    },
+
+    async deleteGroup(groupId) {
+      await api.delete(`/groups/${enc(groupId)}`);
+    },
+
+    async setUserGroup(sub, groupId, member) {
+      const path = `/users/${enc(sub)}/groups/${enc(groupId)}`;
+      if (member) await api.put(path);
+      else await api.delete(path);
+    },
+  };
+}

apps/api/src/modules/org/internal/adapter/keycloak-token-verifier.ts

@@ -24,6 +24,7 @@ const claimsSchema = z.object({
   sub: z.string().min(1),
   preferred_username: z.string().min(1),
   name: z.string().optional(),
+  /* 姓与名分开的两个 claim —— 我们按「姓在前」自己拼(`personName`),不吃拼好的 `name` */
   given_name: z.string().optional(),
   family_name: z.string().optional(),
   email: z.string().optional(),

apps/api/src/modules/org/internal/domain/claims.ts

@@ -5,11 +5,51 @@
  * Keycloak 给每个用户自动挂的三个「家具角色」不是业务角色,这里滤掉:
  * `default-roles-<realm>` / `offline_access` / `uma_authorization`。
  */
+import type { StaffKind } from '@contracts';
 import type { Identity } from '../../contract.ts';
 import type { VerifiedClaims } from '../../port.ts';
 
 const NOISE_ROLES: ReadonlySet<string> = new Set(['offline_access', 'uma_authorization']);
 
+/**
+ * Keycloak 给服务账号用户的固定命名 —— **它自己定的**,不是我们的约定:
+ * 开了 `serviceAccountsEnabled` 的 client 一律配一个 `service-account-<clientId>`。
+ * 按名字认而不按角色认,是因为角色是每个 realm 自己配的(这边叫 `service`,别处未必),
+ * 而这个前缀由 Keycloak 保证。
+ */
+const SERVICE_ACCOUNT_PREFIX = 'service-account-';
+
+/**
+ * 姓在前、名在后(2026-08-26 用户定)。
+ *
+ * Keycloak 自己拼的 `name` claim 是 `firstName lastName` —— 西式顺序,中文名读出来是「浩 柴」。
+ * 所以**不吃那个 claim**,拿分开的 `family_name` / `given_name` 自己拼;
+ * 名册同步那条路同理,拿 `lastName` / `firstName`。
+ *
+ * 中间那个空格按**字形**决定,不按语言设置:两边都是汉字就直拼(「柴浩」),
+ * 否则留一个空格(「Admin Amy」)—— 中文名里塞个空格,读的人会以为那是两个词。
+ */
+const CJK = /^[\u3400-\u4dbf\u4e00-\u9fff\uf900-\ufaff\u3040-\u30ff]+$/u;
+
+export function personName(input: {
+  readonly familyName?: string;
+  readonly givenName?: string;
+  /** 两边都空时回落到这个(通常是用户名)—— 名字这一格永远不许是空的 */
+  readonly fallback: string;
+}): string {
+  const family = (input.familyName ?? '').trim();
+  const given = (input.givenName ?? '').trim();
+  if (family === '' && given === '') return input.fallback;
+  if (family === '') return given;
+  if (given === '') return family;
+  return CJK.test(family) && CJK.test(given) ? `${family}${given}` : `${family} ${given}`;
+}
+
+/** 这个账号是人还是服务账号 —— 员工管理那一屏据此不摆服务账号(它是身份,不是人) */
+export function staffKindOf(account: string): StaffKind {
+  return account.trim().toLowerCase().startsWith(SERVICE_ACCOUNT_PREFIX) ? 'service' : 'person';
+}
+
 export function isNoiseRole(role: string): boolean {
   return NOISE_ROLES.has(role) || role.startsWith('default-roles-');
 }
@@ -21,13 +61,21 @@ export function normalizeRoles(roles: readonly string[]): string[] {
 
 export function identityOf(claims: VerifiedClaims): Identity {
   const account = claims.preferred_username;
-  /* 姓名展示姓在前(2026-08-26 用户定):有姓/名散件就按「姓 名」拼;
+  /*
-     没有散件才用 Keycloak 的全名 `name`(它按「名 姓」拼,中文场景顺序是反的) */
+   * 先按姓在前自己拼;`family_name` / `given_name` 都没有的 realm(没配 profile scope)
-  const cjk = [claims.family_name, claims.given_name]
+   * 才退回 Keycloak 拼好的 `name` —— 拆不开的东西没法重排,如实用它。
-    .filter((s): s is string => s !== undefined && s.trim() !== '')
+   */
-    .join(' ');
+  const composed = personName({
-  const fallback = claims.name === undefined || claims.name.trim() === '' ? account : claims.name.trim();
+    ...(claims.family_name === undefined ? {} : { familyName: claims.family_name }),
-  const name = cjk !== '' ? cjk : fallback;
+    ...(claims.given_name === undefined ? {} : { givenName: claims.given_name }),
+    fallback: '',
+  });
+  const name =
+    composed !== ''
+      ? composed
+      : claims.name === undefined || claims.name.trim() === ''
+        ? account
+        : claims.name.trim();
   const email = claims.email === undefined || claims.email.trim() === '' ? undefined : claims.email.trim();
   return {
     sub: claims.sub,

apps/api/src/modules/org/internal/domain/directory.ts

@@ -0,0 +1,121 @@
+/**
+ * 成员目录的归一(纯函数,零 IO;ADR-012)。
+ *
+ * Keycloak 那一份(身份 · 角色 · 组)与本地那一份(岗位 · 几时来过)在这里合成一行 ——
+ * **两份事实各有各的主人**:改身份去 Keycloak,改岗位在本地;这段只负责摆在一起给人看。
+ *
+ * 服务账号在这一层就剔掉:它是真身份、跑得了单,但**不是人**(见 `staffKindSchema`),
+ * 而这三个页签管的是人。剔在 domain 而不是各路由自己记得滤 —— 漏一处就是一处泄漏,
+ * 而泄漏的后果是有人在界面上把 e2e 账号停用了,试跑第二天全趴下。
+ */
+import type { OrgGroup, OrgRole, OrgUser, RoleAccess } from '@contracts';
+import type { DirectoryGroup, DirectoryRole, DirectoryUser, StoredStaff } from '../../port.ts';
+import { personName, staffKindOf } from './claims.ts';
+import { endsOf } from './ends.ts';
+
+/** 本地名册里跟这个人有关的那两列 —— 目录只读它们,不写 */
+export type LocalMark = { readonly lastSeenAt?: Date; readonly positionCode?: string };
+
+export function isServiceAccount(username: string): boolean {
+  return staffKindOf(username) === 'service';
+}
+
+/** 姓在前、名在后;皆空回落 username —— 名字这一格不会是空的。拼法归 `personName` 一处 */
+export function displayNameOf(user: Pick<DirectoryUser, 'username' | 'firstName' | 'lastName'>): string {
+  return personName({
+    ...(user.lastName === undefined ? {} : { familyName: user.lastName }),
+    ...(user.firstName === undefined ? {} : { givenName: user.firstName }),
+    fallback: user.username,
+  });
+}
+
+export function toOrgUser(user: DirectoryUser, table: readonly RoleAccess[], local?: LocalMark): OrgUser {
+  return {
+    sub: user.sub,
+    username: user.username,
+    displayName: displayNameOf(user),
+    enabled: user.enabled,
+    roles: [...user.roles],
+    ends: endsOf(user.roles, table),
+    ...(user.email === undefined ? {} : { email: user.email }),
+    ...(local?.lastSeenAt === undefined ? {} : { lastSeenAt: local.lastSeenAt.toISOString() }),
+    ...(local?.positionCode === undefined ? {} : { positionCode: local.positionCode }),
+  };
+}
+
+/**
+ * 排序:来过的在前(倒序),没来过的在后(按用户名升序)。
+ * 「没有 `lastSeenAt`」说的是**还没拿这枚身份访问过本系统**,不等于「从未登录 Keycloak」——
+ * 名册同步照过来的人天生就是这一档。
+ */
+export function sortOrgUsers(users: readonly OrgUser[]): OrgUser[] {
+  return [...users].sort((a, b) => {
+    if (a.lastSeenAt !== undefined && b.lastSeenAt !== undefined) {
+      return a.lastSeenAt === b.lastSeenAt ? a.username.localeCompare(b.username) : b.lastSeenAt.localeCompare(a.lastSeenAt);
+    }
+    if (a.lastSeenAt !== undefined) return -1;
+    if (b.lastSeenAt !== undefined) return 1;
+    return a.username.localeCompare(b.username);
+  });
+}
+
+/**
+ * 检索:用户名 / 姓名 / 邮箱任一含关键词(不区分大小写)。
+ * 在**我们这一侧**过滤而不是转给 Keycloak 的 `search=` —— 那个是前缀式,
+ * 「按姓名搜中间那两个字」搜不出来,而人会以为这个人不在。realm 不大,全量在手上。
+ */
+export function filterOrgUsers(users: readonly OrgUser[], q: string, includeDisabled: boolean): OrgUser[] {
+  const needle = q.trim().toLowerCase();
+  return users.filter((u) => {
+    if (!includeDisabled && !u.enabled) return false;
+    if (needle === '') return true;
+    return [u.username, u.displayName, u.email ?? ''].some((f) => f.toLowerCase().includes(needle));
+  });
+}
+
+/**
+ * 每个角色配上「能进哪几个端」与「几个人持有」—— 前者本地说了算,后者 Keycloak 说了算。
+ * `holders` 由调用方按角色现数后传进来(每个角色一趟),不在这儿从全量用户里筛 ——
+ * 那样等于逼调用方先把每个人的角色都拉一遍。
+ */
+export function toOrgRoles(
+  roles: readonly DirectoryRole[],
+  table: readonly RoleAccess[],
+  holders: readonly number[],
+): OrgRole[] {
+  return roles.map((r, i) => ({
+    name: r.name,
+    composite: r.composite,
+    ends: endsOf([r.name], table),
+    holders: holders[i] ?? 0,
+    ...(r.description === undefined ? {} : { description: r.description }),
+  }));
+}
+
+/** 组树平表配上直属成员数(已剔服务账号)—— Keycloak 的组表本身不带这个数 */
+export function toOrgGroups(groups: readonly DirectoryGroup[], counts: ReadonlyMap<string, number>): OrgGroup[] {
+  return groups.map((g) => ({
+    id: g.id,
+    name: g.name,
+    path: g.path,
+    depth: g.depth,
+    memberCount: counts.get(g.id) ?? 0,
+    ...(g.parentId === undefined ? {} : { parentId: g.parentId }),
+  }));
+}
+
+/** 本地名册 → 按 sub 取那两列 */
+export function localMarks(
+  staff: ReadonlyArray<StoredStaff & { readonly lastSeenAt?: Date }>,
+  positionCodeOf: (positionId: string) => string | undefined,
+): Map<string, LocalMark> {
+  const out = new Map<string, LocalMark>();
+  for (const s of staff) {
+    const code = positionCodeOf(s.positionId);
+    out.set(s.id, {
+      ...(s.lastSeenAt === undefined ? {} : { lastSeenAt: s.lastSeenAt }),
+      ...(code === undefined ? {} : { positionCode: code }),
+    });
+  }
+  return out;
+}

apps/api/src/modules/org/internal/domain/roster-diff.ts

@@ -10,7 +10,7 @@
  */
 import type { Staff, StaffId } from '@contracts';
 import type { Identity } from '../../contract.ts';
-import type { IdentityPatch, RosterUser } from '../../port.ts';
+import type { IdentityPatch, RosterUser, StoredStaff } from '../../port.ts';
 import { isTestAccount } from './test-account.ts';
 
 export type RosterDiff = {
@@ -27,7 +27,7 @@ export function sameRoles(a: readonly string[], b: readonly string[]): boolean {
 }
 
 /** 账号 / 姓名 / 邮箱 / 角色任一不同即「变了」;state 不在此列(它归同步) */
-export function identityChanged(staff: Staff, identity: Identity): boolean {
+export function identityChanged(staff: StoredStaff, identity: Identity): boolean {
   return (
     staff.account !== identity.account ||
     staff.name !== identity.name ||
@@ -51,10 +51,10 @@ export function patchOf(identity: Identity): IdentityPatch {
  */
 export function diffRoster(
   remote: readonly RosterUser[],
-  local: readonly Staff[],
+  local: readonly StoredStaff[],
   testAccounts: readonly string[],
 ): RosterDiff {
-  const bySub = new Map<string, Staff>(local.map((s) => [s.id, s]));
+  const bySub = new Map<string, StoredStaff>(local.map((s) => [s.id, s]));
   const diff: RosterDiff = { insert: [], update: [], setState: [] };
   const seen = new Set<string>();
   for (const user of remote) {
@@ -90,7 +90,7 @@ export function diffRoster(
  * 一次同步能停很多人;要是把最后一个能进运营中心的人也停了,那张表与同步按钮就都没人点得动了,
  * 只剩去库里手改 `state`。所以要**在落 setState 之前**先按差异算一遍结果。
  */
-export function activeRolesAfter(local: readonly Staff[], diff: RosterDiff): string[][] {
+export function activeRolesAfter(local: readonly StoredStaff[], diff: RosterDiff): string[][] {
   const state = new Map<string, Staff['state']>(local.map((s) => [s.id, s.state]));
   const roles = new Map<string, readonly string[]>(local.map((s) => [s.id, s.roles]));
   for (const u of diff.update) roles.set(u.id, u.patch.roles);

apps/api/src/modules/org/internal/usecase/org-service.ts

@@ -6,15 +6,30 @@
  *   `state` 由名册同步说了算,JIT 不碰它(插入时 active):本地 disabled 即使 token 有效也拒 ——
  *   撤权在同步之后即时生效;Keycloak 恢复了就再同步一次。
  */
-import type { Position, Principal, RoleAccess, Staff } from '@contracts';
+import type { OrgGroup, OrgRole, OrgUser, OrgUserDetail, Position, Principal, RoleAccess, Staff } from '@contracts';
 import { positionIdSchema, staffIdSchema } from '@contracts';
-import type { Identity, OrgService, RosterSyncOutcome, StaffWithPosition } from '../../contract.ts';
+import type {
-import { AccountDisabledError, PositionNotFoundError, StaffNotFoundError } from '../../contract.ts';
+  CreateDirectoryUser,
+  DirectoryUserPatch,
+  Identity,
+  OrgService,
+  RosterSyncOutcome,
+  StaffWithPosition,
+} from '../../contract.ts';
+import {
+  AccountDisabledError,
+  DirectoryUnavailableError,
+  PositionNotFoundError,
+  ServiceAccountProtectedError,
+  StaffNotFoundError,
+} from '../../contract.ts';
 import type {
   Clock,
+  DirectoryUser,
   IdGenerator,
   InFlightWorkProbe,
   PositionRepository,
+  KeycloakDirectory,
   RoleAccessRepository,
   RosterSource,
   StaffRecord,
@@ -22,7 +37,17 @@ import type {
   TokenVerifier,
   WorkGroupRepository,
 } from '../../port.ts';
-import { identityOf } from '../domain/claims.ts';
+import { identityOf, isNoiseRole, staffKindOf } from '../domain/claims.ts';
+import type { LocalMark } from '../domain/directory.ts';
+import {
+  filterOrgUsers,
+  isServiceAccount,
+  localMarks,
+  sortOrgUsers,
+  toOrgGroups,
+  toOrgRoles,
+  toOrgUser,
+} from '../domain/directory.ts';
 import { assertNotLockedOut, endsOf, normalizeEnds } from '../domain/ends.ts';
 import { buildInFlightWork } from '../domain/in-flight.ts';
 import { activeRolesAfter, diffRoster, identityChanged, patchOf } from '../domain/roster-diff.ts';
@@ -33,6 +58,8 @@ export type OrgServiceDeps = {
   readonly verifier: TokenVerifier;
   /** 未配 provisioning 服务账号时缺省 —— 同步按钮如实回「未配置」 */
   readonly roster?: RosterSource;
+  /** 同上;缺省时成员目录整个不可用(抛 DirectoryUnavailableError → 502) */
+  readonly directory?: KeycloakDirectory;
   readonly positions: PositionRepository;
   readonly staff: StaffRepository;
   readonly roleAccess: RoleAccessRepository;
@@ -47,10 +74,19 @@ export type OrgServiceDeps = {
 /** `last_seen_at` 多久之内不重写 —— 每个请求一次写太贵 */
 const LAST_SEEN_REWRITE_MS = 60_000;
 
+/**
+ * 成员目录读缓存的寿命。Keycloak 没有「一次拿回全部人的生效角色」的接口(手册 §14.4 逐人查),
+ * 一屏就是十几趟远程往返 —— 实测 37 秒。缓存之后:
+ *   **本进程写完立刻整体清空** → 写后马上重拉一定看得到新结果,前端不必延时重试;
+ *   唯一的滞后是**别的**管理员在另一个后端实例上写,这边最多滞后这么久。
+ */
+const DIRECTORY_TTL_MS = 60_000;
+
 /** 契约里的 Staff 没有那两枚时刻 —— 出模块前剥掉 */
 function toStaff(record: StaffRecord): Staff {
   const { lastSeenAt: _seen, syncedAt: _synced, ...staff } = record;
-  return staff;
+  // `kind` 由账号名现判,不落库 —— 它是 Keycloak 命名的事实,不是我们存的一列状态
+  return { ...staff, kind: staffKindOf(staff.account) };
 }
 
 export function createOrgService(deps: OrgServiceDeps): OrgService {
@@ -147,6 +183,117 @@ export function createOrgService(deps: OrgServiceDeps): OrgService {
     return toStaff(fresh ?? created);
   }
 
+  /* ── 成员目录的几个共用件 ─────────────────────────────────────────── */
+
+  /** 只缓存**贵的那两趟**(全量成员 / 组树);详情与成员单查照旧现取 */
+  let usersCache: { at: number; value: OrgUser[] } | undefined;
+  let groupsCache: { at: number; value: OrgGroup[] } | undefined;
+
+  /**
+   * 写完清缓存 —— **按这次写真正碰到的东西清**,不是一律全清。
+   * 全清的代价看得见:删一个组之后,下一次读要把「全量成员的角色」那趟 N+1 重付一遍,
+   * 屏上那棵树因此多钉着已经没了的组好几秒(实测删 4 秒 + 重取 5.5 秒)。
+   *
+   *   'users'  改的是人本身(资料 / 口令)—— 组的成员数没变
+   *   'groups' 改的是组(建 / 改名 / 删)—— 人的角色与端没变
+   *   'all'    两边都动了(删人 = 人没了 + 他所在的组少一个人;进出组同理)
+   */
+  function bustDirectoryCache(scope: 'users' | 'groups' | 'all'): void {
+    if (scope !== 'groups') usersCache = undefined;
+    if (scope !== 'users') groupsCache = undefined;
+  }
+
+  function fresh<T>(entry: { at: number; value: T } | undefined): T | undefined {
+    if (entry === undefined) return undefined;
+    return deps.clock.now().getTime() - entry.at < DIRECTORY_TTL_MS ? entry.value : undefined;
+  }
+
+  function needDirectory(): KeycloakDirectory {
+    if (deps.directory === undefined) {
+      throw new DirectoryUnavailableError(
+        '未配置 KEYCLOAK_PROVISIONING_CLIENT_ID / KEYCLOAK_PROVISIONING_CLIENT_SECRET —— 成员与组织的真源是 Keycloak,读写都要经它的 Admin API',
+        true,
+      );
+    }
+    return deps.directory;
+  }
+
+  /**
+   * 把适配器抛的两类 Keycloak 故障翻成模块自己的错误 —— **重试有没有意义**是分界:
+   * 配错了(缺角色 / 凭证不对)重试一百次也是同一句;暂时够不着才值得过会儿再来。
+   * 别的错(重名、约束不过)原样往上抛,路由译成 4xx 并带原话。
+   */
+  async function guardKeycloak<T>(run: () => Promise<T>): Promise<T> {
+    try {
+      return await run();
+    } catch (error) {
+      if (error instanceof Error && error.name === 'KeycloakMisconfiguredError') {
+        throw new DirectoryUnavailableError(error.message, true);
+      }
+      if (error instanceof Error && error.name === 'KeycloakUnavailableError') {
+        throw new DirectoryUnavailableError(error.message, false);
+      }
+      throw error;
+    }
+  }
+
+  /** 本地名册那两列,按 sub 索引 —— 目录只读它们 */
+  async function localMarkMap(): Promise<Map<string, LocalMark>> {
+    const [rows, positions] = await Promise.all([deps.staff.list(), deps.positions.list()]);
+    const codeOf = new Map(positions.map((p) => [p.id as string, p.code]));
+    return localMarks(rows, (id) => codeOf.get(id));
+  }
+
+  /** 目录全量(已剔服务账号、已配好端与本地两列、已排序)—— 检索在这之后做 */
+  async function allDirectoryUsers(): Promise<OrgUser[]> {
+    const dir = needDirectory();
+    const hit = fresh(usersCache);
+    if (hit !== undefined) return hit;
+    const [raw, table, marks] = await Promise.all([
+      guardKeycloak(() => dir.listUsers()),
+      deps.roleAccess.list(),
+      localMarkMap(),
+    ]);
+    const people = raw.filter((u) => !isServiceAccount(u.username));
+    const value = sortOrgUsers(people.map((u) => toOrgUser(u, table, marks.get(u.sub))));
+    usersCache = { at: deps.clock.now().getTime(), value };
+    return value;
+  }
+
+  /**
+   * 一次穿透写 —— 跑完**一律清缓存**。
+   * 包起来而不是各写面自己记得调:漏一处就是一处「写完看不到」,
+   * 而那种漏不报错,只是画面比事实旧(与治理台写路由统一广播同一个道理)。
+   */
+  async function writeThrough<T>(scope: 'users' | 'groups' | 'all', run: () => Promise<T>): Promise<T> {
+    try {
+      return await guardKeycloak(run);
+    } finally {
+      bustDirectoryCache(scope);
+    }
+  }
+
+  /** 一次写之后回那一行的当下样子 —— 界面照它重画,不必自己拼 */
+  async function oneUser(sub: string): Promise<OrgUser> {
+    const dir = needDirectory();
+    const [raw, table, marks] = await Promise.all([
+      guardKeycloak(() => dir.getUser(sub)),
+      deps.roleAccess.list(),
+      localMarkMap(),
+    ]);
+    return toOrgUser(raw, table, marks.get(sub));
+  }
+
+  function assertPerson(user: Pick<DirectoryUser, 'username'>): void {
+    if (isServiceAccount(user.username)) throw new ServiceAccountProtectedError(user.username);
+  }
+
+  /** 写面开工之前先问一句「这个 sub 是人吗」—— 服务账号一律不许动 */
+  async function assertPersonBySub(sub: string): Promise<void> {
+    const dir = needDirectory();
+    assertPerson(await guardKeycloak(() => dir.getUser(sub)));
+  }
+
   const service: OrgService = {
     async authenticate(token) {
       const claims = await deps.verifier.verify(token);
@@ -308,6 +455,169 @@ export function createOrgService(deps: OrgServiceDeps): OrgService {
       return staff.filter((s) => s.state === 'active' && endsOf(s.roles, table).includes(surface));
     },
 
+    /* ── 成员目录(Keycloak Admin API 的读写面;ADR-012) ──────────────── */
+
+    async directoryUsers(query) {
+      const users = await allDirectoryUsers();
+      const q = query.q ?? '';
+      return { users: filterOrgUsers(users, q, query.includeDisabled === true) };
+    },
+
+    async directoryUser(sub): Promise<OrgUserDetail> {
+      const dir = needDirectory();
+      const raw = await guardKeycloak(() => dir.getUser(sub));
+      assertPerson(raw);
+      const [table, marks] = await Promise.all([deps.roleAccess.list(), localMarkMap()]);
+      return {
+        ...toOrgUser(raw, table, marks.get(raw.sub)),
+        emailVerified: raw.emailVerified,
+        groups: raw.groups.map((g) => ({ ...g })),
+        ...(raw.firstName === undefined ? {} : { firstName: raw.firstName }),
+        ...(raw.lastName === undefined ? {} : { lastName: raw.lastName }),
+      };
+    },
+
+    async createDirectoryUser(input: CreateDirectoryUser) {
+      const dir = needDirectory();
+      if (isServiceAccount(input.username)) throw new ServiceAccountProtectedError(input.username);
+      const sub = await writeThrough('all', () => dir.createUser(input));
+      return oneUser(sub);
+    },
+
+    async patchDirectoryUser(sub, patch: DirectoryUserPatch) {
+      const dir = needDirectory();
+      await assertPersonBySub(sub);
+      await writeThrough('users', () => dir.updateUser(sub, patch));
+      return oneUser(sub);
+    },
+
+    async setDirectoryUserEnabled(sub, enabled) {
+      const dir = needDirectory();
+      await assertPersonBySub(sub);
+      await writeThrough('users', () => dir.setEnabled(sub, enabled));
+      /*
+       * 停用之后**踢会话** —— 界面上已经写了「已停用」,而他手上那枚 token 到期前照样通行。
+       * 这是「界面不撒谎」在鉴权上的样子:说停了就得真的进不来。
+       */
+      if (!enabled) await writeThrough('users', () => dir.logout(sub));
+      // 本地那一行跟手:两屏说的是同一件事(名册同步也会做,但那要等人去按)
+      const local = await deps.staff.findById(staffIdSchema.parse(sub));
+      if (local !== undefined) await deps.staff.setState(local.id, enabled ? 'active' : 'disabled', deps.clock.now());
+      return oneUser(sub);
+    },
+
+    async resetDirectoryUserPassword(sub, password) {
+      const dir = needDirectory();
+      await assertPersonBySub(sub);
+      await writeThrough('users', () => dir.resetPassword(sub, password));
+    },
+
+    async deleteDirectoryUser(sub) {
+      const dir = needDirectory();
+      await assertPersonBySub(sub);
+      await writeThrough('all', () => dir.deleteUser(sub));
+      /*
+       * 本地那一行**停用,不删** —— 留痕、在途任务、台账的 `by` 都还指着这个 sub。
+       * 删了那些地方就成了悬空的 id,而历史是只增不改的。
+       */
+      const local = await deps.staff.findById(staffIdSchema.parse(sub));
+      if (local !== undefined) await deps.staff.setState(local.id, 'disabled', deps.clock.now());
+    },
+
+    async directoryRoles(): Promise<{ roles: OrgRole[] }> {
+      const dir = needDirectory();
+      const [roles, table, users] = await Promise.all([
+        guardKeycloak(() => dir.listRoles()),
+        deps.roleAccess.list(),
+        allDirectoryUsers(),
+      ]);
+      // 家具角色不摆:它们是 Keycloak 给每个用户自动挂的,授收都没有意义(见 isNoiseRole)
+      const real = roles.filter((r) => !isNoiseRole(r.name));
+      /*
+       * 持有数从**生效角色**里数(每人的 `/composite`),不用 `GET /roles/{name}/users` ——
+       * 那个只回**直接授予**的:`user` 是经 `default-roles-corp` 继承来的,
+       * 那条路会报「持有 0 人」而实际人人都有。快了却是错的,不要。
+       * 速度靠 `allDirectoryUsers` 的 60 秒缓存拿。
+       */
+      const counts = real.map((r) => users.filter((u) => u.roles.includes(r.name)).length);
+      return { roles: toOrgRoles(real, table, counts) };
+    },
+
+    async setDirectoryUserRole(sub, role, granted) {
+      const dir = needDirectory();
+      await assertPersonBySub(sub);
+      /*
+       * 收权之前先算一遍「收完还有谁进得了运营中心」—— 与改「角色→端」那条同一道闸,
+       * 理由也同一个:这两条路都能把最后一个管理员关在门外,而**恢复动作本身要 ops**。
+       */
+      if (!granted) {
+        const [table, users] = await Promise.all([deps.roleAccess.list(), allDirectoryUsers()]);
+        const after = users
+          .filter((u) => u.enabled)
+          .map((u) => (u.sub === sub ? u.roles.filter((r) => r !== role) : u.roles));
+        assertNotLockedOut(
+          table,
+          after,
+          `收掉「${role}」之后就没有人能进运营中心了 —— 这扇门会锁死(恢复动作本身要运营中心),拒绝`,
+        );
+      }
+      await writeThrough('users', () => dir.setRole(sub, role, granted));
+      // 收权立刻踢会话:否则他手上那枚 token 还带着旧角色,收权要等到过期才生效
+      if (!granted) await writeThrough('users', () => dir.logout(sub));
+      return oneUser(sub);
+    },
+
+    async directoryGroups(): Promise<{ groups: OrgGroup[] }> {
+      const dir = needDirectory();
+      const hit = fresh(groupsCache);
+      if (hit !== undefined) return { groups: hit };
+      const groups = await guardKeycloak(() => dir.listGroups());
+      // 数数就只数数 —— 别为了一个数字把每个成员的角色都拉一遍(N+1 的第二处)
+      const pairs = await Promise.all(
+        groups.map(async (g) => {
+          const names = await guardKeycloak(() => dir.groupMemberUsernames(g.id));
+          return [g.id, names.filter((n) => !isServiceAccount(n)).length] as const;
+        }),
+      );
+      const value = toOrgGroups(groups, new Map(pairs));
+      groupsCache = { at: deps.clock.now().getTime(), value };
+      return { groups: value };
+    },
+
+    async directoryGroupMembers(groupId) {
+      const dir = needDirectory();
+      const [raw, table, marks] = await Promise.all([
+        guardKeycloak(() => dir.groupMembers(groupId)),
+        deps.roleAccess.list(),
+        localMarkMap(),
+      ]);
+      const members = raw.filter((u) => !isServiceAccount(u.username)).map((u) => toOrgUser(u, table, marks.get(u.sub)));
+      return { members: sortOrgUsers(members) };
+    },
+
+    async createDirectoryGroup(name, parentId) {
+      const dir = needDirectory();
+      const g = await writeThrough('groups', () => dir.createGroup(name, parentId));
+      return toOrgGroups([g], new Map())[0]!;
+    },
+
+    async renameDirectoryGroup(groupId, name) {
+      const dir = needDirectory();
+      const g = await writeThrough('groups', () => dir.renameGroup(groupId, name));
+      return toOrgGroups([g], new Map())[0]!;
+    },
+
+    async deleteDirectoryGroup(groupId) {
+      const dir = needDirectory();
+      await writeThrough('groups', () => dir.deleteGroup(groupId));
+    },
+
+    async setDirectoryUserGroup(sub, groupId, member) {
+      const dir = needDirectory();
+      await assertPersonBySub(sub);
+      await writeThrough('groups', () => dir.setUserGroup(sub, groupId, member));
+    },
+
     /* ── 工作组(ADR-011)—— 起单时的岗位绑定,不是第五种策略 ────────── */
 
     async saveWorkGroup(input) {

apps/api/src/modules/org/port.ts

@@ -3,7 +3,7 @@
  * adapter 实现之,usecase 依赖之,app 装配之。
  */
 import type { Position, PositionId, RoleAccess, Staff, StaffId, WorkGroup } from '@contracts';
-import type { Identity } from './contract.ts';
+import type { CreateDirectoryUser, DirectoryUserPatch, Identity } from './contract.ts';
 
 export type Clock = { now(): Date };
 
@@ -13,10 +13,11 @@ export type Clock = { now(): Date };
 export type VerifiedClaims = {
   readonly sub: string;
   readonly preferred_username: string;
+  /** Keycloak 拼好的 `firstName lastName` —— 西式顺序,只在拆不开时才用它 */
   readonly name?: string;
-  /* 名/姓分开收(2026-08-26 用户定:中文姓名姓在前)—— Keycloak 的 `name` 是全名(名+姓),
+  /** 名(firstName) */
-     展示要「姓 名」得靠这两个散件拼;没带就回退 `name` 原样 */
   readonly given_name?: string;
+  /** 姓(lastName)—— 我们按「姓在前」自己拼,见 `personName` */
   readonly family_name?: string;
   readonly email?: string;
   readonly realm_access?: { readonly roles?: readonly string[] };
@@ -29,6 +30,66 @@ export type TokenVerifier = { verify(token: string): Promise<VerifiedClaims> };
 export type RosterUser = Identity & { readonly enabled: boolean };
 export type RosterSource = { listUsers(): Promise<readonly RosterUser[]> };
 
+/* ── 成员目录(Keycloak Admin API 的读写面;ADR-012) ────────────────── */
+
+/**
+ * Keycloak 那一侧的一个用户 —— **原样的形状**,不掺本地字段。
+ * 与 `RosterUser` 的区别:名册只要「同步要比对的那几列」,目录要摆给人看的全部。
+ */
+export type DirectoryUser = {
+  readonly sub: string;
+  readonly username: string;
+  readonly firstName?: string;
+  readonly lastName?: string;
+  readonly email?: string;
+  readonly enabled: boolean;
+  readonly emailVerified: boolean;
+  /** realm 角色(家具角色已滤) */
+  readonly roles: readonly string[];
+};
+
+/** 组树里的一行 —— 平表,层级看 `parentId` / `depth`(契约同款,理由见 org-directory.ts) */
+export type DirectoryGroup = {
+  readonly id: string;
+  readonly name: string;
+  readonly path: string;
+  readonly parentId?: string;
+  readonly depth: number;
+  readonly memberCount: number;
+};
+
+export type DirectoryRole = {
+  readonly name: string;
+  readonly description?: string;
+  readonly composite: boolean;
+};
+
+/**
+ * 成员目录 —— app 未配 provisioning 服务账号时不注入(与 `RosterSource` 同款)。
+ * 读是投影,写**直接穿透**到 Keycloak:这里建的人立刻能登录,这里删的人从 Keycloak 消失。
+ */
+export type KeycloakDirectory = {
+  listUsers(): Promise<readonly DirectoryUser[]>;
+  getUser(sub: string): Promise<DirectoryUser & { readonly groups: ReadonlyArray<{ id: string; path: string }> }>;
+  createUser(input: CreateDirectoryUser): Promise<string>;
+  updateUser(sub: string, patch: DirectoryUserPatch): Promise<void>;
+  setEnabled(sub: string, enabled: boolean): Promise<void>;
+  resetPassword(sub: string, password: string): Promise<void>;
+  deleteUser(sub: string): Promise<void>;
+  /** 踢掉此人全部会话 —— 停用与收权之后必调,否则旧 token 到期前照样通行 */
+  logout(sub: string): Promise<void>;
+  listRoles(): Promise<readonly DirectoryRole[]>;
+  setRole(sub: string, role: string, granted: boolean): Promise<void>;
+  listGroups(): Promise<readonly DirectoryGroup[]>;
+  groupMembers(groupId: string): Promise<readonly DirectoryUser[]>;
+  /** 组的直属成员用户名 —— 组树只要个数,别为了数数把每个人的角色都拉一遍 */
+  groupMemberUsernames(groupId: string): Promise<readonly string[]>;
+  createGroup(name: string, parentId?: string): Promise<DirectoryGroup>;
+  renameGroup(groupId: string, name: string): Promise<DirectoryGroup>;
+  deleteGroup(groupId: string): Promise<void>;
+  setUserGroup(sub: string, groupId: string, member: boolean): Promise<void>;
+};
+
 /** 名册即时更新 / 同步要改的那几列 */
 export type IdentityPatch = {
   readonly account: string;
@@ -48,7 +109,13 @@ export type PositionRepository = {
 };
 
 /** 员工行 —— 契约 Staff 之外还带两枚时刻,只给用例判「要不要再写一次」,不出模块 */
-export type StaffRecord = Staff & { readonly lastSeenAt?: Date; readonly syncedAt?: Date };
+/**
+ * 库里真存着的那几列。`Staff.kind` 不在其中 —— 它由账号名现判(见 `staffKindSchema`),
+ * 存一列就会与账号名分叉,而分叉之后没人看得出以哪份为准。
+ */
+export type StoredStaff = Omit<Staff, 'kind'>;
+
+export type StaffRecord = StoredStaff & { readonly lastSeenAt?: Date; readonly syncedAt?: Date };
 
 export type StaffRepository = {
   list(): Promise<StaffRecord[]>;
@@ -56,7 +123,7 @@ export type StaffRepository = {
   /** 按账号找 —— `account` 有唯一索引,建档前得先问一句「这个名字被谁占着」(同名让位) */
   findByAccount(account: string): Promise<StaffRecord | undefined>;
   listByPosition(positionId: PositionId): Promise<StaffRecord[]>;
-  insert(staff: Staff, marks: { readonly lastSeenAt?: Date; readonly syncedAt?: Date }): Promise<StaffRecord>;
+  insert(staff: StoredStaff, marks: { readonly lastSeenAt?: Date; readonly syncedAt?: Date }): Promise<StaffRecord>;
   updateIdentity(id: StaffId, patch: IdentityPatch): Promise<void>;
   setPosition(id: StaffId, positionId: PositionId): Promise<void>;
   setState(id: StaffId, state: Staff['state'], syncedAt: Date): Promise<void>;

apps/api/tsup.config.ts

@@ -9,6 +9,8 @@ export default defineConfig({
     'reset-runs': 'src/app/reset-runs.ts',
     // 只装活动包(不碰治理台配置)—— 开发活动时一天要装十几次
     'install-activities': 'src/app/install-activities.ts',
+    // 名册同步:整册从 Keycloak 照过来(ops 路由够不着时走这条)
+    'sync-roster': 'src/app/sync-roster.ts',
   },
   format: ['esm'],
   target: 'node22',

apps/web/src/app/gov-shell.tsx

@@ -135,6 +135,7 @@ export function GovShell({ surface }: { surface: Surface }) {
   const domains = sortDomains([...new Set((objects.data?.objects ?? []).map((o) => o.domain))]);
   // 进台账没带域(左轨点进来)时落到首域 —— 页签与内容同一判定
   const effectiveTab = zone === 'ledgers' && tab === '' ? (domains[0] ?? '') : tab;
+  const tabHint = TABS[zone].find((t) => t.key === tab)?.hint;
 
   /* 面包屑:台面 › 区 › 页签 › 下钻各级 */
   const crumbs: Array<{ label: string; go?: () => void }> = [
@@ -249,7 +250,8 @@ export function GovShell({ surface }: { surface: Surface }) {
                 * 摆一个只有一颗按钮的导航条,是在给人做无谓的选择。
                 * 台账例外 —— 它的页签是随发布生长的数据域,数量本来就不定。
                 */}
-              <div className={'g-tabs' + (zone !== 'ledgers' && TABS[zone].length <= 1 ? ' hidden' : '')}>
+              <div className={'g-tabsrow' + (zone !== 'ledgers' && TABS[zone].length <= 1 ? ' hidden' : '')}>
+              <div className="g-tabs">
                 {zone === 'ledgers'
                   ? // 台账的页签是**数据域**(短名 2-3 字),随发布生长 —— 设计产生运营的形状,落在页签上
                     domains.map((d) => (
@@ -273,6 +275,9 @@ export function GovShell({ surface }: { surface: Surface }) {
                         {t.label}
                       </button>
                     ))}
+              </div>
+                {/* 右端一句话:这一格管什么、写下去会发生什么 —— 界面自己说清楚,不靠人记 */}
+                {tabHint !== undefined && <span className="g-tabs-hint">{tabHint}</span>}
               </div>
               <ZoneHome zone={zone} tab={effectiveTab} nav={nav} />
             </>

apps/web/src/app/styles/console.css

@@ -84,6 +84,10 @@
 .g-head-t p { margin: 5px 0 0; font-size: 12.5px; line-height: 1.7; color: var(--ink-3); max-width: 108ch; }
 
 /* 区内页签：一个页签 = 一个维度 */
+/* 页签栏一行两件:左边那颗药丸是页签,右端一句话说清这一格管什么(可缺席) */
+.g-tabsrow { display: flex; align-items: center; justify-content: space-between; gap: 16px; }
+.g-tabsrow.hidden { display: none; }
+.g-tabs-hint { font-size: 12px; color: var(--ink-4); text-align: right; }
 .g-tabs.hidden { display: none; }
 .g-tabs { display: flex; flex-wrap: wrap; gap: 3px; padding: 4px; border-radius: 12px; background: #e3e8ef; align-self: flex-start; }
 .g-tab { display: inline-flex; align-items: center; gap: 7px; height: 32px; padding: 0 14px; border: 0; border-radius: 9px; background: transparent; color: var(--ink-3); font: inherit; font-size: 12.5px; font-weight: 600; cursor: pointer; transition: background var(--t-fast), color var(--t-fast); }
@@ -862,6 +866,19 @@
 /* 供应商:一行小签 —— 挑一个即预填它的默认端点。
    从前是 146px 宽的大牌子,一个人吃掉 118px 高,把下面的输入框全顶出屏幕。 */
 .g-chiprow { display: flex; flex-wrap: wrap; gap: 6px; }
+/* 组织那一屏:左树右详情;窄屏叠成一列(树在上,详情在下) */
+.g-split { display: grid; grid-template-columns: minmax(240px, 340px) 1fr; gap: 14px; align-items: start; }
+@media (max-width: 900px) { .g-split { grid-template-columns: 1fr; } }
+.g-tree { display: flex; flex-direction: column; gap: 2px; }
+.g-tree-r { display: flex; align-items: center; gap: 8px; width: 100%; padding: 7px 10px; border: 0; border-radius: 8px; background: transparent; color: var(--ink-2); font: inherit; font-size: 12.5px; text-align: left; cursor: pointer; transition: background var(--t-fast), color var(--t-fast); }
+.g-tree-r:hover { background: #f1f4f8; color: var(--ink); }
+.g-tree-r.on { background: var(--brand-soft, #e8f0ff); color: var(--ink); font-weight: 700; }
+.g-tree-r b { flex: 1; font-weight: inherit; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+.g-tree-r em { font-style: normal; font-size: 11px; color: var(--ink-4); }
+/* 一枚勾选 + 一句话 —— `.g-swrow` 会把行内**所有** input 压成 14px,
+   而这一行里还站着检索框,所以单起一个,只管勾选框自己 */
+.g-tick { display: inline-flex; align-items: center; gap: 6px; font-size: 12.5px; color: var(--ink-2); cursor: pointer; white-space: nowrap; }
+.g-tick input { width: 14px; height: 14px; accent-color: var(--brand); cursor: pointer; }
 .g-chip { padding: 6px 11px; border: 1px solid var(--cline); border-radius: 15px; background: #fff; font: 500 12px/1.2 var(--sans); color: var(--ink-3); cursor: pointer; transition: border-color var(--t-fast), background var(--t-fast), color var(--t-fast); }
 .g-chip:hover { border-color: #aebdcd; color: var(--ink); }
 .g-chip.on { border-color: var(--brand); background: var(--brand-wash); color: var(--brand-deep); font-weight: 600; }

apps/web/src/features/gov-staff/internal/member-page.tsx

@@ -0,0 +1,255 @@
+/**
+ * 成员详情 —— 一个人的全部:身份、能进哪几个端、角色授收、所属组、启停与删除。
+ *
+ * 这一屏的每个动作都**穿透到 Keycloak**,没有撤销;所以一律走二次确认带。
+ * 两处顺手做的事要说出来,不然人不知道:
+ *   停用与收权都**当场踢掉他的全部会话** —— 否则他手上那枚 token 到期前照样通行,
+ *   而屏上已经写了「已停用」。界面不撒谎。
+ */
+import { useState } from 'react';
+import { useMutation, useQueryClient } from '@tanstack/react-query';
+import {
+  deleteOrgUserRoute,
+  patchOrgUserRoute,
+  resetOrgUserPasswordRoute,
+  setOrgUserEnabledRoute,
+  setOrgUserRoleRoute,
+} from '@contracts';
+import { call } from '@web-shared/typed-fetch.ts';
+import { Acts, Card, Chip, Clear, Field, Note, PageHead, QueryGate, Rows, St } from '@web-shared/gov/primitives.tsx';
+import { Btn } from '@web-shared/Btn.tsx';
+import type { Nav } from '@web-shared/gov/gov-route.ts';
+import { ORG_KEYS, useOrgRoles, useOrgUser } from '@web-shared/gov/gov-api.ts';
+import { EndChips } from './members.tsx';
+
+export function MemberPage({ id, nav }: { id: string; nav: Nav }) {
+  const qc = useQueryClient();
+  const q = useOrgUser(id);
+  const roles = useOrgRoles();
+  const u = q.data;
+  const [err, setErr] = useState<string | undefined>(undefined);
+  const [pwd, setPwd] = useState('');
+  const [editing, setEditing] = useState<{ firstName: string; lastName: string; email: string } | undefined>(undefined);
+
+  /** 改一个人:他自己 + 名单 + 角色持有数;组的成员数没变(删人那一路另说) */
+  const bust = (): void => {
+    void qc.invalidateQueries({ queryKey: ORG_KEYS.user });
+    void qc.invalidateQueries({ queryKey: ORG_KEYS.users });
+    void qc.invalidateQueries({ queryKey: ORG_KEYS.roles });
+  };
+  const fail = (e: unknown): void => setErr(e instanceof Error ? e.message : String(e));
+
+  const setEnabled = useMutation({
+    mutationFn: (enabled: boolean) => call(setOrgUserEnabledRoute, { params: { sub: id }, body: { enabled } }),
+    onSuccess: () => { setErr(undefined); bust(); },
+    onError: fail,
+  });
+  const setRole = useMutation({
+    mutationFn: (v: { role: string; granted: boolean }) =>
+      call(setOrgUserRoleRoute, { params: { sub: id, role: v.role }, body: { granted: v.granted } }),
+    onSuccess: () => { setErr(undefined); bust(); },
+    onError: fail,
+  });
+  const patch = useMutation({
+    mutationFn: (v: { firstName: string; lastName: string; email: string }) =>
+      call(patchOrgUserRoute, { params: { sub: id }, body: v }),
+    onSuccess: () => { setEditing(undefined); setErr(undefined); bust(); },
+    onError: fail,
+  });
+  const reset = useMutation({
+    mutationFn: () => call(resetOrgUserPasswordRoute, { params: { sub: id }, body: { password: pwd } }),
+    onSuccess: () => { setPwd(''); setErr(undefined); },
+    onError: fail,
+  });
+  const drop = useMutation({
+    mutationFn: () => call(deleteOrgUserRoute, { params: { sub: id } }),
+    // 删人是唯一会动到组的那一路:他从他所在的每个组里没了
+    onSuccess: () => {
+      bust();
+      void qc.invalidateQueries({ queryKey: ORG_KEYS.groups });
+      nav.jump('people', 'members');
+    },
+    onError: fail,
+  });
+
+  return (
+    <QueryGate query={q}>
+      {u === undefined ? (
+        <Clear>{`Keycloak 里没有这个人(${id})—— 可能刚被删了。`}</Clear>
+      ) : (
+        <>
+          <PageHead
+            ico="user-round"
+            kicker="成员"
+            title={u.displayName}
+            chips={
+              <>
+                <Chip ico="at-sign">{u.username}</Chip>
+                <St tone={u.enabled ? 'ok' : 'mute'} ico={u.enabled ? 'circle-check' : 'power'}>
+                  {u.enabled ? '在职' : '已停用'}
+                </St>
+              </>
+            }
+            desc="身份与角色的真源是 Keycloak —— 这一屏的每个动作都直接改那边,没有撤销。"
+          />
+
+          {err !== undefined && <Note tone="warn">{err}</Note>}
+
+          <Card ico="user-check" title="身份">
+            <Rows
+              items={[
+                { k: '用户名', v: u.username, mono: true },
+                { k: '姓名', v: u.displayName },
+                { k: '邮箱', v: u.email ?? '—' },
+                { k: '邮箱已验证', v: u.emailVerified ? '是' : '否' },
+                { k: 'sub', v: u.sub, mono: true },
+                { k: '本地岗位', v: u.positionCode ?? '未分配' },
+                { k: '几时来过', v: u.lastSeenAt ?? '还没拿这枚身份访问过本系统' },
+              ]}
+            />
+            {editing === undefined ? (
+              <Acts
+                align="end"
+                items={[
+                  {
+                    label: '改资料',
+                    ico: 'pencil-line',
+                    onClick: () =>
+                      setEditing({ firstName: u.firstName ?? '', lastName: u.lastName ?? '', email: u.email ?? '' }),
+                  },
+                ]}
+              />
+            ) : (
+              <div className="g-prop">
+                <div className="g-prop-h">改资料(用户名建后不可改)</div>
+                <div className="g-prop-b">
+                  <Field k="姓">
+                    <input className="g-input" value={editing.lastName} onChange={(e) => setEditing({ ...editing, lastName: e.target.value })} />
+                  </Field>
+                  <Field k="名">
+                    <input className="g-input" value={editing.firstName} onChange={(e) => setEditing({ ...editing, firstName: e.target.value })} />
+                  </Field>
+                  <Field k="邮箱">
+                    <input className="g-input" value={editing.email} onChange={(e) => setEditing({ ...editing, email: e.target.value })} />
+                  </Field>
+                  <Acts
+                    align="end"
+                    items={[
+                      { label: '取消', onClick: () => setEditing(undefined) },
+                      { label: '保存', ico: 'check', primary: true, busy: patch.isPending, onClick: () => patch.mutate(editing) },
+                    ]}
+                  />
+                </div>
+              </div>
+            )}
+          </Card>
+
+          <Card ico="shield-check" title="能进哪几个端" extra={<span className="x">由下面的角色 × 「权限」页签的配置算出来</span>}>
+            <div className="g-chiprow">
+              <EndChips ends={u.ends} />
+            </div>
+          </Card>
+
+          <Card ico="key" title="角色" extra={<span className="x">授收都穿透 Keycloak;收权当场踢掉他的会话</span>}>
+            <QueryGate query={roles}>
+              <div className="g-chiprow">
+                {(roles.data?.roles ?? []).map((r) => {
+                  const has = u.roles.includes(r.name);
+                  return (
+                    <Btn
+                      key={r.name}
+                      className={'g-btn' + (has ? ' primary' : '')}
+                      busy={setRole.isPending && setRole.variables?.role === r.name}
+                      onClick={() => setRole.mutate({ role: r.name, granted: !has })}
+                      title={
+                        has
+                          ? `收掉「${r.name}」—— 他手上的会话会被当场踢掉`
+                          : `授予「${r.name}」(可进:${r.ends.length === 0 ? '无端' : r.ends.join(' / ')})`
+                      }
+                    >
+                      {(has ? '✓ ' : '+ ') + r.name}
+                    </Btn>
+                  );
+                })}
+              </div>
+            </QueryGate>
+          </Card>
+
+          <Card ico="network" title="所属组">
+            {u.groups.length === 0 ? (
+              <Clear>不属于任何组 —— 进出组在「组织」页签里做。</Clear>
+            ) : (
+              <div className="g-chiprow">
+                {u.groups.map((g) => (
+                  <Chip key={g.id} tone="brand" ico="network">
+                    {g.path}
+                  </Chip>
+                ))}
+              </div>
+            )}
+          </Card>
+
+          <Card ico="lock" title="口令" extra={<span className="x">一律临时口令 —— 本人首登必须改</span>}>
+            <div className="g-chiprow" style={{ alignItems: 'center' }}>
+              <input
+                className="g-input"
+                style={{ flex: 1 }}
+                type="password"
+                placeholder="新的临时口令"
+                value={pwd}
+                onChange={(e) => setPwd(e.target.value)}
+              />
+              <Btn className="g-btn" disabled={pwd === ''} busy={reset.isPending} onClick={() => reset.mutate()}>
+                重置口令
+              </Btn>
+            </div>
+            <Note>服务端不回显、不留痕 —— 这一下按完,这串字就只在你和他之间。</Note>
+          </Card>
+
+          <Card ico="power" title="启停与删除">
+            <Acts
+              items={[
+                {
+                  label: u.enabled ? '停用' : '启用',
+                  ico: 'power',
+                  danger: u.enabled,
+                  busy: setEnabled.isPending,
+                  ask: {
+                    title: `${u.enabled ? '停用' : '启用'}「${u.displayName}」`,
+                    note: u.enabled
+                      ? '停用会当场踢掉他的全部会话 —— 手上那枚 token 立刻失效,不用等过期。'
+                      : '启用之后他就能重新登录了。',
+                    impact: {
+                      who: u.displayName,
+                      undo: '可以再改回来',
+                      when: '立刻',
+                    },
+                    okLabel: u.enabled ? '确认停用' : '确认启用',
+                    onOk: () => setEnabled.mutate(!u.enabled),
+                  },
+                },
+                {
+                  label: '删除',
+                  ico: 'trash-2',
+                  danger: true,
+                  busy: drop.isPending,
+                  ask: {
+                    title: `把「${u.displayName}」从 Keycloak 删掉`,
+                    note: '本地名册那一行会停用但不删 —— 留痕、在途任务、台账里都还指着这个 sub,删了那些地方就成了悬空的 id。',
+                    impact: {
+                      who: u.displayName,
+                      undo: '不能撤销 —— 从 Keycloak 消失,再建一个是新的 sub',
+                      when: '按下即生效',
+                    },
+                    okLabel: '确认删除',
+                    onOk: () => drop.mutate(),
+                  },
+                },
+              ]}
+            />
+          </Card>
+        </>
+      )}
+    </QueryGate>
+  );
+}

apps/web/src/features/gov-staff/internal/members.tsx

@@ -0,0 +1,188 @@
+/**
+ * 成员 —— Keycloak 目录的投影(ADR-012)。
+ *
+ * **这里的写是穿透的**:建的人立刻能登录、停的人立刻登不上,没有本地草稿,也没有撤销。
+ * 所以每个写动作都走 `Acts` 的二次确认带(三必答:谁受影响 / 能不能撤 / 几时生效)。
+ *
+ * 检索与「含停用」都交给服务端 —— 那边握着全量,前端只拿要摆的那些。
+ */
+import { useState } from 'react';
+import { useMutation, useQueryClient } from '@tanstack/react-query';
+import { createOrgUserRoute, SURFACE_LABEL } from '@contracts';
+import type { Surface } from '@contracts';
+import { call } from '@web-shared/typed-fetch.ts';
+import { Acts, Card, Chip, Clear, Field, NList, NRow, Note, QueryGate, St } from '@web-shared/gov/primitives.tsx';
+import { Btn } from '@web-shared/Btn.tsx';
+import type { Nav } from '@web-shared/gov/gov-route.ts';
+import { ORG_KEYS, useOrgUsers } from '@web-shared/gov/gov-api.ts';
+
+/** 能进的端 —— 摆人读名;一个都没有就直说,别留一片空白让人以为没加载出来 */
+export function EndChips({ ends }: { ends: readonly Surface[] }) {
+  if (ends.length === 0) return <Chip tone="mute">无端可进</Chip>;
+  return (
+    <>
+      {ends.map((e) => (
+        <Chip key={e} tone="brand">
+          {SURFACE_LABEL[e]}
+        </Chip>
+      ))}
+    </>
+  );
+}
+
+export function MembersTab({ nav }: { nav: Nav }) {
+  const [q, setQ] = useState('');
+  const [includeDisabled, setIncludeDisabled] = useState(true);
+  const [creating, setCreating] = useState(false);
+  const users = useOrgUsers(q, includeDisabled);
+  const rows = users.data?.users ?? [];
+  const active = rows.filter((u) => u.enabled).length;
+  /*
+   * 数还没取回来就别摆数 —— `?? []` 会让计数在载入那几秒显示「0 人 · 0 在职」,
+   * 而那是**一句假话**:不是没有人,是还不知道有几个人(铁规矩 8)。
+   */
+  const counted = users.data !== undefined;
+
+  return (
+    <>
+      <Card
+        ico="users"
+        title="成员"
+        extra={
+          <span className="g-chiprow" style={{ alignItems: 'center' }}>
+            <input
+              className="g-input"
+              style={{ width: 240 }}
+              placeholder="按用户名 / 姓名 / 邮箱检索…"
+              value={q}
+              onChange={(e) => setQ(e.target.value)}
+            />
+            <label className="g-tick">
+              <input type="checkbox" checked={includeDisabled} onChange={(e) => setIncludeDisabled(e.target.checked)} />
+              含停用
+            </label>
+            <Chip tone={counted ? 'brand' : 'mute'}>{counted ? `${rows.length} 人 · ${active} 在职` : '数着…'}</Chip>
+            <Btn className="g-btn primary" onClick={() => setCreating((v) => !v)}>
+              {creating ? '收起' : '新建成员'}
+            </Btn>
+          </span>
+        }
+      >
+        <Note>
+          真源是 Keycloak · 停用的人<b>立刻</b>登不上;在途任务不受影响(需手动改派)。服务账号不在这份名单里 ——
+          它是身份不是人。
+        </Note>
+        {creating && <CreateMemberForm onDone={() => setCreating(false)} />}
+        <QueryGate query={users}>
+          {rows.length === 0 ? (
+            <Clear>{q === '' ? '一个人都没有 —— 去 Keycloak 建人,或用「新建成员」。' : `没有匹配「${q}」的成员。`}</Clear>
+          ) : (
+            <NList>
+              {rows.map((u) => (
+                <NRow
+                  key={u.sub}
+                  tone={u.enabled ? 'brand' : 'mute'}
+                  ico="user-round"
+                  title={u.displayName}
+                  sub={`${u.username}${u.email === undefined ? '' : ` · ${u.email}`}`}
+                  cols={[
+                    { k: '角色', v: u.roles.length === 0 ? '—' : u.roles.join(', ') },
+                    { k: '可进', v: <EndChips ends={u.ends} /> },
+                  ]}
+                  right={
+                    <St tone={u.enabled ? 'ok' : 'mute'} ico={u.enabled ? 'circle-check' : 'power'}>
+                      {u.enabled ? '在职' : '已停用'}
+                    </St>
+                  }
+                  onClick={() => nav.push({ k: 'emp', id: u.sub })}
+                />
+              ))}
+            </NList>
+          )}
+        </QueryGate>
+      </Card>
+    </>
+  );
+}
+
+/**
+ * 新建成员 —— 口令一律**临时**:本人首登必须改。
+ * 我们不存它、不回显 —— 它经过这个表单就再也不出现了,所以建完那一句话得把它说清楚。
+ */
+function CreateMemberForm({ onDone }: { onDone: () => void }) {
+  const qc = useQueryClient();
+  const [username, setUsername] = useState('');
+  const [lastName, setLastName] = useState('');
+  const [firstName, setFirstName] = useState('');
+  const [email, setEmail] = useState('');
+  const [password, setPassword] = useState('');
+  const [err, setErr] = useState<string | undefined>(undefined);
+
+  const create = useMutation({
+    mutationFn: () =>
+      call(createOrgUserRoute, {
+        body: {
+          username: username.trim(),
+          ...(lastName.trim() === '' ? {} : { lastName: lastName.trim() }),
+          ...(firstName.trim() === '' ? {} : { firstName: firstName.trim() }),
+          ...(email.trim() === '' ? {} : { email: email.trim() }),
+          ...(password === '' ? {} : { password }),
+        },
+      }),
+    onSuccess: () => {
+      // 多了一个人 → 名单变了,角色的持有数也跟着变;组没动
+      void qc.invalidateQueries({ queryKey: ORG_KEYS.users });
+      void qc.invalidateQueries({ queryKey: ORG_KEYS.roles });
+      onDone();
+    },
+    onError: (e: unknown) => setErr(e instanceof Error ? e.message : String(e)),
+  });
+
+  return (
+    <div className="g-prop">
+      <div className="g-prop-h">新建成员</div>
+      <div className="g-prop-b">
+        <Field k="用户名" hint="登录名,建后不可改">
+          <input className="g-input" value={username} onChange={(e) => setUsername(e.target.value)} placeholder="如 zhangsan" />
+        </Field>
+        <Field k="姓" hint="Keycloak 的 lastName">
+          <input className="g-input" value={lastName} onChange={(e) => setLastName(e.target.value)} />
+        </Field>
+        <Field k="名" hint="Keycloak 的 firstName">
+          <input className="g-input" value={firstName} onChange={(e) => setFirstName(e.target.value)} />
+        </Field>
+        <Field k="邮箱" hint="选填">
+          <input className="g-input" value={email} onChange={(e) => setEmail(e.target.value)} />
+        </Field>
+        <Field k="临时口令" hint="留空则建一个还登不进来的壳;填了则本人首登必须改">
+          <input className="g-input" type="password" value={password} onChange={(e) => setPassword(e.target.value)} />
+        </Field>
+        {err !== undefined && <Note tone="warn">{err}</Note>}
+        <Acts
+          align="end"
+          items={[
+            { label: '取消', onClick: onDone },
+            {
+              label: '建这个人',
+              ico: 'user-plus',
+              primary: true,
+              disabled: username.trim() === '',
+              busy: create.isPending,
+              ask: {
+                title: `在 Keycloak 里建「${username.trim()}」`,
+                note: '姓名照 Keycloak 的 lastName + firstName 拼;角色先不给 —— 建完去「权限」页签授。',
+                impact: {
+                  who: '这个人立刻能登录(若给了临时口令)',
+                  undo: '不能撤销 —— 建错了只能再删掉',
+                  when: '按下即生效,Keycloak 那边当场就有',
+                },
+                okLabel: '确认新建',
+                onOk: () => create.mutate(),
+              },
+            },
+          ]}
+        />
+      </div>
+    </div>
+  );
+}

apps/web/src/features/gov-staff/internal/orgs.tsx

@@ -0,0 +1,276 @@
+/**
+ * 组织 —— Keycloak 的组(ADR-012)。左边一棵树,右边选中那个组的成员与操作。
+ *
+ * 树是**平表**渲染的:一行一个组,靠 `depth` 缩进(契约里就不放递归结构 ——
+ * 递归 schema 到了声明文件那一层只会变成一坨 any)。按 `path` 升序,父在子前。
+ *
+ * 删组连子组一起没(Keycloak 语义),人不会被删 —— 只是不再属于这个组。
+ */
+import { useState } from 'react';
+import { useMutation, useQueryClient } from '@tanstack/react-query';
+import {
+  createOrgGroupRoute,
+  deleteOrgGroupRoute,
+  renameOrgGroupRoute,
+  setOrgUserGroupRoute,
+} from '@contracts';
+import { call } from '@web-shared/typed-fetch.ts';
+import { Acts, Card, Chip, Clear, NList, NRow, Note, QueryGate, St } from '@web-shared/gov/primitives.tsx';
+import { Btn } from '@web-shared/Btn.tsx';
+import { ORG_KEYS, useOrgGroupMembers, useOrgGroups, useOrgUsers } from '@web-shared/gov/gov-api.ts';
+import type { GovOrgGroups } from '@web-shared/gov/gov-api.ts';
+
+export function OrgsTab() {
+  const groups = useOrgGroups();
+  const rows = groups.data?.groups ?? [];
+  const [picked, setPicked] = useState<string | undefined>(undefined);
+  const current = rows.find((g) => g.id === picked);
+  const tops = rows.filter((g) => g.depth === 0).length;
+  /* 取回来之前一个数都别摆、一句「还没有组」也别说 —— 那时候我们并不知道有没有组 */
+  const loaded = groups.data !== undefined;
+
+  return (
+    <div className="g-split">
+      <Card ico="network" title="组织树" extra={<Chip tone={loaded ? 'brand' : 'mute'}>{loaded ? `${tops} 顶层组` : '数着…'}</Chip>}>
+        <Note>Keycloak 组 · 点一行看它的成员与操作</Note>
+        <QueryGate query={groups}>
+          {rows.length === 0 ? (
+            <Clear>还没有组 —— 先在下面「建顶层组」。</Clear>
+          ) : (
+            <div className="g-tree">
+              {rows.map((g) => (
+                <button
+                  key={g.id}
+                  className={'g-tree-r' + (picked === g.id ? ' on' : '')}
+                  style={{ paddingLeft: 10 + g.depth * 18 }}
+                  onClick={() => setPicked(g.id)}
+                  title={g.path}
+                >
+                  <b>{g.name}</b>
+                  <em>{`${g.memberCount} 人`}</em>
+                </button>
+              ))}
+            </div>
+          )}
+        </QueryGate>
+        <GroupCreate label="建顶层组" hint="组名(同级不得重名)" />
+      </Card>
+
+      {current === undefined ? (
+        <Card ico="users" title="成员">
+          <Clear>
+            {!loaded
+              ? '组织树还在取…'
+              : rows.length === 0
+                ? '还没有组 —— 先在左侧「建顶层组」,这里看它的成员与操作。'
+                : '在左侧点一个组,这里看它的成员与操作。'}
+          </Clear>
+        </Card>
+      ) : (
+        <GroupDetail
+          key={current.id}
+          group={current}
+          onGone={() => setPicked(undefined)}
+        />
+      )}
+    </div>
+  );
+}
+
+/** 建组 —— `parentId` 给了就是子组,不给就是顶层组 */
+function GroupCreate({ label, hint, parentId }: { label: string; hint: string; parentId?: string }) {
+  const qc = useQueryClient();
+  const [name, setName] = useState('');
+  const [err, setErr] = useState<string | undefined>(undefined);
+  const create = useMutation({
+    mutationFn: () =>
+      call(createOrgGroupRoute, {
+        body: { name: name.trim(), ...(parentId === undefined ? {} : { parentId }) },
+      }),
+    onSuccess: () => {
+      setName('');
+      setErr(undefined);
+      // 只有组变了 —— 成员那一趟很贵,别拖它下水
+      void qc.invalidateQueries({ queryKey: ORG_KEYS.groups });
+    },
+    onError: (e: unknown) => setErr(e instanceof Error ? e.message : String(e)),
+  });
+  return (
+    <div className="g-prop">
+      <div className="g-prop-h">{label}</div>
+      <div className="g-prop-b">
+        <div className="g-chiprow" style={{ alignItems: 'center' }}>
+          <input className="g-input" style={{ flex: 1 }} placeholder={hint} value={name} onChange={(e) => setName(e.target.value)} />
+          <Btn className="g-btn" disabled={name.trim() === ''} busy={create.isPending} onClick={() => create.mutate()}>
+            建组
+          </Btn>
+        </div>
+        {err !== undefined && <Note tone="warn">{err}</Note>}
+      </div>
+    </div>
+  );
+}
+
+function GroupDetail({
+  group,
+  onGone,
+}: {
+  group: { id: string; name: string; path: string; depth: number; memberCount: number };
+  onGone: () => void;
+}) {
+  const qc = useQueryClient();
+  const members = useOrgGroupMembers(group.id);
+  const all = useOrgUsers('', true);
+  const [renaming, setRenaming] = useState<string | undefined>(undefined);
+  const [err, setErr] = useState<string | undefined>(undefined);
+  /** 组这一屏的写只动组与组成员;人的角色与端一个字没变 */
+  const bust = (): void => {
+    void qc.invalidateQueries({ queryKey: ORG_KEYS.groups });
+    void qc.invalidateQueries({ queryKey: ORG_KEYS.groupMembers });
+  };
+  const fail = (e: unknown): void => setErr(e instanceof Error ? e.message : String(e));
+
+  const rename = useMutation({
+    mutationFn: (name: string) => call(renameOrgGroupRoute, { params: { id: group.id }, body: { name } }),
+    onSuccess: () => { setRenaming(undefined); setErr(undefined); bust(); },
+    onError: fail,
+  });
+  const drop = useMutation({
+    mutationFn: () => call(deleteOrgGroupRoute, { params: { id: group.id } }),
+    onSuccess: () => {
+      /*
+       * 删成功了 —— **「这个组没了」是已知事实**,不必等服务端再说一遍。
+       * 那一趟重取要好几秒(组树得逐组数成员),期间树上还钉着已经没了的组;
+       * 撞上 token 到期强刷的那一次更久,实测有一轮干脆没刷过来。
+       * 手上有的答案先落进缓存,重取照发 —— 回来时一比,一样。
+       * 子组跟着一起没(Keycloak 语义),按**路径前缀**连它们一起摘,不是只摘直属那一层。
+       */
+      qc.setQueryData<GovOrgGroups>(ORG_KEYS.groups, (old) =>
+        old === undefined
+          ? old
+          : { groups: old.groups.filter((g) => g.id !== group.id && !g.path.startsWith(`${group.path}/`)) },
+      );
+      onGone();
+      bust();
+    },
+    onError: fail,
+  });
+  const setMember = useMutation({
+    mutationFn: (v: { sub: string; member: boolean }) =>
+      call(setOrgUserGroupRoute, { params: { sub: v.sub, groupId: group.id }, body: { member: v.member } }),
+    onSuccess: () => { setErr(undefined); bust(); },
+    onError: fail,
+  });
+
+  const inGroup = members.data?.members ?? [];
+  const inIds = new Set(inGroup.map((m) => m.sub));
+  const outside = (all.data?.users ?? []).filter((u) => !inIds.has(u.sub));
+
+  return (
+    <Card
+      ico="users"
+      title={group.name}
+      extra={<St tone="ok" ico="users">{`${inGroup.length} 人`}</St>}
+    >
+      <Note>{`路径 ${group.path}`}</Note>
+
+      {renaming !== undefined && (
+        <div className="g-prop">
+          <div className="g-prop-h">改组名</div>
+          <div className="g-prop-b">
+            <div className="g-chiprow" style={{ alignItems: 'center' }}>
+              <input className="g-input" style={{ flex: 1 }} value={renaming} onChange={(e) => setRenaming(e.target.value)} />
+              <Btn className="g-btn" onClick={() => setRenaming(undefined)}>取消</Btn>
+              <Btn
+                className="g-btn primary"
+                disabled={renaming.trim() === '' || renaming.trim() === group.name}
+                busy={rename.isPending}
+                onClick={() => rename.mutate(renaming.trim())}
+              >
+                改名
+              </Btn>
+            </div>
+          </div>
+        </div>
+      )}
+
+      {err !== undefined && <Note tone="warn">{err}</Note>}
+
+      <QueryGate query={members}>
+        {inGroup.length === 0 ? (
+          <Clear>这个组还没有人 —— 在下面「把人加进来」。</Clear>
+        ) : (
+          <NList>
+            {inGroup.map((m) => (
+              <NRow
+                key={m.sub}
+                tone={m.enabled ? 'brand' : 'mute'}
+                ico="user-round"
+                title={m.displayName}
+                sub={m.username}
+                right={
+                  <Btn
+                    className="g-btn danger"
+                    busy={setMember.isPending && setMember.variables?.sub === m.sub}
+                    onClick={() => setMember.mutate({ sub: m.sub, member: false })}
+                  >
+                    移出
+                  </Btn>
+                }
+                onClick={() => undefined}
+              />
+            ))}
+          </NList>
+        )}
+      </QueryGate>
+
+      <div className="g-prop">
+        <div className="g-prop-h">把人加进来</div>
+        <div className="g-prop-b">
+          {outside.length === 0 ? (
+            <Clear>所有人都已经在这个组里了。</Clear>
+          ) : (
+            <div className="g-chiprow">
+              {outside.map((u) => (
+                <Btn
+                  key={u.sub}
+                  className="g-btn"
+                  busy={setMember.isPending && setMember.variables?.sub === u.sub}
+                  onClick={() => setMember.mutate({ sub: u.sub, member: true })}
+                >
+                  {`+ ${u.displayName}`}
+                </Btn>
+              ))}
+            </div>
+          )}
+        </div>
+      </div>
+
+      <GroupCreate label="在这个组下建子组" hint="子组名(同级不得重名)" parentId={group.id} />
+
+      <Acts
+        align="end"
+        items={[
+          { label: '改组名', ico: 'pencil-line', onClick: () => setRenaming(group.name) },
+          {
+            label: '删掉这个组',
+            ico: 'trash-2',
+            danger: true,
+            busy: drop.isPending,
+            ask: {
+              title: `删掉「${group.name}」`,
+              note: '子组会跟着一起没。人不会被删 —— 只是不再属于这个组。',
+              impact: {
+                who: `这个组里的 ${inGroup.length} 个人,以及它下面的所有子组`,
+                undo: '不能撤销 —— 组和它的层级关系直接从 Keycloak 消失',
+                when: '按下即生效',
+              },
+              okLabel: '确认删组',
+              onOk: () => drop.mutate(),
+            },
+          },
+        ]}
+      />
+    </Card>
+  );
+}

apps/web/src/features/gov-staff/internal/panel.tsx

@@ -1,367 +1,31 @@
 /**
- * feature `gov-staff` —— 员工管理:账号、岗位授权、停用前置检查
+ * feature `gov-staff` —— 成员与组织(ADR-012,2026-08-26 用户按目标件定的三页签)。
  *
- * 自 `~/coding/JCAI_PRD/governance/_components/Governance.tsx` 平移:
+ * 三个页签一一对着 Keycloak 的三样东西:
- * DOM 结构、类名(`g-*` + 色调 `t-*`)与文案原样保留,mock 常量换成服务端投影(README 平移规则 1/2/4)。
+ *   **成员** = users(目录投影;新建 / 启停 / 删除都穿透过去)
- * 区首页只负责导航,治理动作一律落在下钻详情页的**就地确认带**(影响预览三必答)。
+ *   **权限** = realm roles × 本系统的「角色 → 端」表(每个请求都按它判)
+ *   **组织** = groups(建组 / 改名 / 删组 / 成员进出组)
+ *
+ * 原「岗位授权」与「工作组」两个页签已拿掉(用户定)。**后端数据与接口原样留着** ——
+ * 岗位仍决定活动派单的候选集,工作组仍在起单那一刻快照进工作流;拿掉的只是入口。
  */
-import { useState } from 'react';
+import { MembersTab } from './members.tsx';
-import { useMutation, useQueryClient } from '@tanstack/react-query';
+import { MemberPage } from './member-page.tsx';
-import { GOVERNANCE_FUNCTION_LABEL, GRANT_ACTION_LABEL, saveWorkGroupRoute, staffIdSchema } from '@contracts';
+import { OrgsTab } from './orgs.tsx';
-import type { StaffId } from '@contracts';
+import { PermsTab, RolePage } from './perms.tsx';
-import { call } from '@web-shared/typed-fetch.ts';
-import {
-  Acts,
-  Card,
-  Chip,
-  Clear,
-  Entry,
-  Field,
-  NList,
-  NRow,
-  Note,
-  PageHead,
-  QueryGate,
-  Rows,
-  St,
-} from '@web-shared/gov/primitives.tsx';
 import type { Nav } from '@web-shared/gov/gov-route.ts';
-import { useGovGrants, useGovStaff, useGovTasks, useGovWorkGroups } from '@web-shared/gov/gov-api.ts';
 
 export type HomeProps = { tab: string; nav: Nav };
 
 export function PeopleHome({ tab, nav }: HomeProps) {
-  if (tab === 'groups') return <WorkGroupsTab />;
+  if (tab === 'perms') return <PermsTab />;
-  return <StaffHome tab={tab} nav={nav} />;
+  if (tab === 'orgs') return <OrgsTab />;
+  return <MembersTab nav={nav} />;
 }
 
-function StaffHome({ tab, nav }: HomeProps) {
+/** 详情页 `emp` —— 路由名沿用(URL 里已有的书签不该失效),内容是成员详情 */
-  const q = useGovStaff();
-  const tasks = useGovTasks();
-  const staff = q.data?.staff ?? [];
-  const positions = q.data?.positions ?? [];
-
-  if (tab === 'roles') {
-    return (
-      <>
-        <Note>
-          权限按<b>岗位</b>授予,不按人:客体三类(数据 / 工具 / 治理功能)× 动作三种(读 / 写 / 治理)。
-          人换岗即换权,权限随岗位走。
-        </Note>
-        <NList>
-          {positions.map((p) => (
-            <NRow
-              key={p.id}
-              tone="brand"
-              ico="key"
-              title={p.name}
-              sub={`岗位编码 ${p.code}`}
-              cols={[{ k: '在岗', v: staff.filter((s) => s.position.id === p.id).length }]}
-              onClick={() => nav.push({ k: 'role', id: p.id })}
-            />
-          ))}
-        </NList>
-      </>
-    );
-  }
-
-  return (
-    <QueryGate query={q}>
-    <>
-      <NList>
-        {staff.map((s) => {
-          const mine = (tasks.data?.tasks ?? []).filter((t) => t.ownerName === s.name && t.terminal === undefined);
-          return (
-            <NRow
-              key={s.id}
-              tone={s.state === 'active' ? 'brand' : 'mute'}
-              ico="user-round"
-              title={s.name}
-              sub={`${s.account} · ${s.position.name}(${s.position.code})`}
-              cols={[{ k: '在途任务', v: mine.length }]}
-              right={
-                <St tone={s.state === 'active' ? 'ok' : 'mute'} ico={s.state === 'active' ? 'circle-check' : 'power'}>
-                  {s.state === 'active' ? '在职' : '已停用'}
-                </St>
-              }
-              onClick={() => nav.push({ k: 'emp', id: s.id })}
-            />
-          );
-        })}
-      </NList>
-    </>
-    </QueryGate>
-  );
-}
-
-/* ---------------- ③ 工作流管理 ---------------- */
-
 export function EmpPage({ id, nav }: { id: string; nav: Nav }) {
-  const q = useGovStaff();
+  return <MemberPage id={id} nav={nav} />;
-  const tasks = useGovTasks();
-  const s = (q.data?.staff ?? []).find((x) => x.id === id);
-  if (s === undefined) return <Note>员工不存在。</Note>;
-  const mine = (tasks.data?.tasks ?? []).filter((t) => t.ownerName === s.name);
-  const live = mine.filter((t) => t.terminal === undefined);
-  return (
-    <>
-      <PageHead
-        ico="user-round"
-        kicker={`员工 · ${s.account}`}
-        title={s.name}
-        chips={
-          <>
-            <Chip ico="key">
-              {s.position.name} · {s.position.code}
-            </Chip>
-            <Chip tone={s.state === 'active' ? 'ok' : 'mute'}>{s.state === 'active' ? '在职' : '已停用'}</Chip>
-          </>
-        }
-        desc="停用前置检查:在途任务与待答卡须先改派完毕——停用不得让在途工作无人认领。"
-      />
-      <Card ico="list-checks" title="在途任务" extra={<span className="g-mono">{live.length}</span>}>
-        <NList>
-          {live.map((t) => (
-            <NRow key={t.id} tone="brand" ico="list-checks" title={t.title} onClick={() => nav.push({ k: 'task', id: t.id })} />
-          ))}
-          {live.length === 0 && <Clear>无在途任务——可安全停用。</Clear>}
-        </NList>
-      </Card>
-      <Entry ico="key" title="岗位授权" desc={`查看 ${s.position.name} 的授权清单`} onClick={() => nav.push({ k: 'role', id: s.position.id })} />
-    </>
-  );
 }
 
-export function RolePage({ id }: { id: string }) {
+export { RolePage };
-  const staff = useGovStaff();
-  const grants = useGovGrants(id);
-  const position = (staff.data?.positions ?? []).find((p) => p.id === id);
-  return (
-    <>
-      <PageHead
-        ico="key"
-        kicker="岗位授权"
-        title={position?.name ?? id}
-        chips={<Chip ico="hash">{position?.code ?? '—'}</Chip>}
-        desc="权限按岗位授予,不按人:客体三类(数据 / 工具 / 治理功能)× 动作三种(读 / 写 / 治理)。人换岗即换权。"
-      />
-      <div className="g-rows">
-        {(grants.data?.grants ?? []).map((g, i) => (
-          <div key={i}>
-            <em>
-              {g.object.kind === 'data'
-                ? `数据 · ${g.object.domain}.${g.object.object}`
-                : g.object.kind === 'governance'
-                  ? `治理功能 · ${GOVERNANCE_FUNCTION_LABEL[g.object.function]}`
-                  : `任务 · ${g.object.activityId ?? '全部活动'}`}
-            </em>
-            <b className="mono">{GRANT_ACTION_LABEL[g.action]}</b>
-          </div>
-        ))}
-        {(grants.data?.grants ?? []).length === 0 && <Clear>未授予任何权限。</Clear>}
-      </div>
-    </>
-  );
-}
-
-/* ---------------- 流程包 ---------------- */
-
-
-/* ---------------- 工作组(ADR-011) ---------------- */
-
-/**
- * 工作组 = 一组「岗位 → 员工」的绑定,**起单时装载、随工作流走**。
- *
- * 它是**绑定先于策略**,不是第五种负责人策略:起单人有组,整条流的岗位就按组指人;
- * 没有组才回落四策略(独任 / 轮询 / 抢单 / 指派)。
- * 装进工作流的是**快照** —— 改组不改已起的单,留痕不被改写。
- */
-function WorkGroupsTab() {
-  const groups = useGovWorkGroups();
-  const staffQ = useGovStaff();
-  const [editing, setEditing] = useState<string | undefined>(undefined);
-
-  const staff = staffQ.data?.staff ?? [];
-  const positions = staffQ.data?.positions ?? [];
-  const nameOf = (id: string) => staff.find((s) => s.id === id)?.name ?? id;
-  const rows = groups.data?.groups ?? [];
-
-  return (
-    <QueryGate query={groups}>
-      <>
-        <Note>
-          工作组把<b>岗位绑到人</b>:谁起的单,整条流的岗位就按谁的组指人 —— 绑定先于策略,
-          没绑定的岗位仍走四策略。绑定在起单那一刻<b>快照</b>进工作流,此后改组不影响已起的单。
-        </Note>
-        {rows.length === 0 ? (
-          <Clear>还没有工作组 —— 给谁建一个,他起的单整条流就能一次指到人。</Clear>
-        ) : (
-          rows.map((g) =>
-            editing === g.ownerId ? (
-              <WorkGroupForm
-                key={g.id}
-                ownerId={g.ownerId}
-                ownerName={g.ownerName}
-                name={g.name}
-                members={g.members}
-                positions={positions}
-                staff={staff}
-                onDone={() => setEditing(undefined)}
-                onCancel={() => setEditing(undefined)}
-              />
-            ) : (
-              <Card
-                key={g.id}
-                ico="users"
-                title={g.name}
-                extra={
-                  <button className="g-btn" onClick={() => setEditing(g.ownerId)}>
-                    改绑定
-                  </button>
-                }
-              >
-                <Rows
-                  items={[
-                    { k: '组长', v: g.ownerName },
-                    ...positions.map((p) => ({
-                      k: `${p.name} · ${p.code}`,
-                      v: g.members[p.code] === undefined ? '未绑定 · 走四策略' : nameOf(g.members[p.code]!),
-                    })),
-                  ]}
-                />
-              </Card>
-            ),
-          )
-        )}
-        <Card ico="user-round" title="给还没有组的人建一个">
-          <NList>
-            {staff
-              .filter((s) => !rows.some((g) => g.ownerId === s.id))
-              .map((s) =>
-                editing === s.id ? null : (
-                  <NRow
-                    key={s.id}
-                    tone="mute"
-                    ico="user-round"
-                    title={s.name}
-                    sub={`${s.position.name} · ${s.position.code}`}
-                    right={<span className="g-mono">建组 →</span>}
-                    onClick={() => setEditing(s.id)}
-                  />
-                ),
-              )}
-            {staff.every((s) => rows.some((g) => g.ownerId === s.id)) && <Clear>每个人都有组了。</Clear>}
-          </NList>
-        </Card>
-        {staff
-          .filter((s) => !rows.some((g) => g.ownerId === s.id) && editing === s.id)
-          .map((s) => (
-            <WorkGroupForm
-              key={s.id}
-              ownerId={s.id}
-              ownerName={s.name}
-              name={`${s.name}的工作组`}
-              members={{}}
-              positions={positions}
-              staff={staff}
-              onDone={() => setEditing(undefined)}
-              onCancel={() => setEditing(undefined)}
-            />
-          ))}
-      </>
-    </QueryGate>
-  );
-}
-
-/** 建组 / 改组表单:逐岗位选人,留空即该岗位不绑定 */
-function WorkGroupForm({
-  ownerId,
-  ownerName,
-  name,
-  members,
-  positions,
-  staff,
-  onDone,
-  onCancel,
-}: {
-  ownerId: string;
-  ownerName: string;
-  name: string;
-  members: Readonly<Record<string, string>>;
-  positions: ReadonlyArray<{ id: string; code: string; name: string }>;
-  staff: ReadonlyArray<{ id: string; name: string; position: { code: string; name: string } }>;
-  onDone: () => void;
-  onCancel: () => void;
-}) {
-  const queryClient = useQueryClient();
-  const [draftName, setDraftName] = useState(name);
-  const [draft, setDraft] = useState<Record<string, string>>({ ...members });
-
-  const save = useMutation({
-    mutationFn: (input: { name: string; members: Record<string, StaffId> }) =>
-      call(saveWorkGroupRoute, {
-        body: { ownerId: staffIdSchema.parse(ownerId), name: input.name, members: input.members },
-      }),
-    onSuccess: () => {
-      void queryClient.invalidateQueries({ queryKey: ['gov', 'work-groups'] });
-      onDone();
-    },
-  });
-
-  const bound = Object.values(draft).filter((v) => v !== '').length;
-
-  return (
-    <Card ico="users" title={`工作组:${ownerName}`}>
-      <Field k="组名" hint="人读的一句话,如「柴浩的工作组」">
-        <input className="g-input" value={draftName} onChange={(e) => setDraftName(e.target.value)} />
-      </Field>
-      {positions.map((p) => (
-        <Field key={p.id} k={`${p.name} · ${p.code}`} hint="留空即不绑定,该岗位仍走四策略">
-          <select
-            className="g-input"
-            value={draft[p.code] ?? ''}
-            onChange={(e) => setDraft({ ...draft, [p.code]: e.target.value })}
-          >
-            <option value="">— 不绑定 —</option>
-            {staff.map((s) => (
-              <option key={s.id} value={s.id}>
-                {s.name}({s.position.code})
-              </option>
-            ))}
-          </select>
-        </Field>
-      ))}
-      <Acts
-        align="end"
-        items={[
-          { label: '取消', ico: 'x', onClick: onCancel },
-          {
-            label: save.isPending ? '保存中…' : `保存(已绑 ${bound} 个岗位)`,
-            ico: 'circle-check',
-            primary: true,
-            disabled: draftName.trim() === '',
-            busy: save.isPending,
-            ask: {
-              title: `保存工作组:${draftName}`,
-              note: <Note>绑定先于策略 —— 起单人有组,整条流的岗位就按组指人;没绑定的岗位仍走四策略。</Note>,
-              impact: {
-                who: '仅此后新起的工作流;在途不受影响 —— 绑定是起单时的快照',
-                undo: '可随时改;解绑某岗位即回落四策略',
-                when: '确认后即时生效',
-              },
-              okLabel: '确认保存',
-              onOk: () => {
-                const picked: Record<string, StaffId> = {};
-                for (const [code, id] of Object.entries(draft)) {
-                  if (id !== '') picked[code] = staffIdSchema.parse(id);
-                }
-                save.mutate({ name: draftName, members: picked });
-              },
-            },
-          },
-        ]}
-      />
-      {save.isError && <Note tone="warn">保存失败,请重试。</Note>}
-    </Card>
-  );
-}

apps/web/src/features/gov-staff/internal/perms.tsx

@@ -0,0 +1,204 @@
+/**
+ * 权限 —— **两份事实拼在一起**(ADR-012):
+ *   角色本身是 Keycloak 的(realm roles,授收穿透过去);
+ *   「这个角色能进哪几个端」是**本系统自己的**(`sys.role_access`),Keycloak 不知道这回事。
+ *
+ * 权限只到端:设计中心 / 运营中心 / 工作台。一个请求进不进得来,鉴权中间件每次都按这张表判 ——
+ * 所以这一屏改的不是一句描述,是**下一个请求的成败**。
+ *
+ * 锁死不变量:改完之后至少还得有人能进运营中心 —— 否则这张表就再也没人改得了。
+ * 服务端算完了才落库,不过就 409;这边如实把那句话摆出来,不自己拦(拦了两处口径会分叉)。
+ */
+import { useState } from 'react';
+import { useMutation, useQueryClient } from '@tanstack/react-query';
+import type { QueryClient } from '@tanstack/react-query';
+import { deleteRoleAccessRoute, setRoleAccessRoute, SURFACE_LABEL, SURFACES } from '@contracts';
+import type { Surface } from '@contracts';
+import { call } from '@web-shared/typed-fetch.ts';
+import { Acts, Card, Chip, Clear, Note, QueryGate, St } from '@web-shared/gov/primitives.tsx';
+import { ORG_KEYS, useOrgRoles, useRoleAccess } from '@web-shared/gov/gov-api.ts';
+import { EndChips } from './members.tsx';
+
+/**
+ * 改「角色 → 端」之后,**每个人的可进端都跟着变** —— 所以人那一份也得失效,
+ * 不然成员那一屏还摆着旧的端胶囊(同一件事两屏说两句话)。组没动。
+ */
+function bustAccess(qc: QueryClient): void {
+  void qc.invalidateQueries({ queryKey: ORG_KEYS.roleAccess });
+  void qc.invalidateQueries({ queryKey: ORG_KEYS.roles });
+  void qc.invalidateQueries({ queryKey: ORG_KEYS.users });
+  void qc.invalidateQueries({ queryKey: ORG_KEYS.user });
+}
+
+export function PermsTab() {
+  const roles = useOrgRoles();
+  const access = useRoleAccess();
+  const rows = roles.data?.roles ?? [];
+
+  return (
+    <Card
+      ico="shield-check"
+      title="角色 → 能进哪几个端"
+      // 取回来之前不摆数 —— 「0 个角色」在那一刻是假话
+      extra={<Chip tone={roles.data === undefined ? 'mute' : 'brand'}>{roles.data === undefined ? '数着…' : `${rows.length} 个角色`}</Chip>}
+    >
+      <Note>
+        角色来自 Keycloak(realm roles),<b>能进哪几个端由这里说了算</b> —— 每个请求都按它判,
+        不合就回 403。改完至少要有人还能进运营中心,否则这张表自己就锁死了。
+      </Note>
+      <QueryGate query={roles}>
+        {rows.length === 0 ? (
+          <Clear>realm 里还没有业务角色 —— 去 Keycloak 建(家具角色不摆在这儿)。</Clear>
+        ) : (
+          <div className="g-rows">
+            {rows.map((r) => (
+              <RoleRow key={r.name} role={r} configured={(access.data?.roles ?? []).some((x) => x.role === r.name)} />
+            ))}
+          </div>
+        )}
+      </QueryGate>
+    </Card>
+  );
+}
+
+function RoleRow({
+  role,
+  configured,
+}: {
+  role: { name: string; description?: string | undefined; composite: boolean; ends: readonly Surface[]; holders: number };
+  configured: boolean;
+}) {
+  const qc = useQueryClient();
+  const [draft, setDraft] = useState<readonly Surface[] | undefined>(undefined);
+  const [err, setErr] = useState<string | undefined>(undefined);
+  const editing = draft !== undefined;
+  const shown = draft ?? role.ends;
+
+  const save = useMutation({
+    mutationFn: (ends: readonly Surface[]) =>
+      // 一个端都不给 = 这个角色哪儿都进不去。删掉那一行与存一行空的是同一件事,存空的更好读
+      call(setRoleAccessRoute, { params: { role: role.name }, body: { ends: [...ends] } }),
+    onSuccess: () => {
+      setDraft(undefined);
+      setErr(undefined);
+      bustAccess(qc);
+    },
+    onError: (e: unknown) => setErr(e instanceof Error ? e.message : String(e)),
+  });
+
+  const remove = useMutation({
+    mutationFn: () => call(deleteRoleAccessRoute, { params: { role: role.name } }),
+    onSuccess: () => {
+      setDraft(undefined);
+      setErr(undefined);
+      bustAccess(qc);
+    },
+    onError: (e: unknown) => setErr(e instanceof Error ? e.message : String(e)),
+  });
+
+  return (
+    <div className="g-prop">
+      <div className="g-prop-h">
+        <span className="g-mono">{role.name}</span>
+        {role.composite && <Chip tone="warn">组合角色</Chip>}
+        <span className="x">{`${role.holders} 人持有`}</span>
+      </div>
+      <div className="g-prop-b">
+        {role.description !== undefined && <Note>{role.description}</Note>}
+        {editing ? (
+          <div className="g-swrow">
+            {SURFACES.map((s) => (
+              <label key={s}>
+                <input
+                  type="checkbox"
+                  checked={shown.includes(s)}
+                  onChange={(e) =>
+                    setDraft(e.target.checked ? [...shown, s] : shown.filter((x) => x !== s))
+                  }
+                />
+                {SURFACE_LABEL[s]}
+              </label>
+            ))}
+            <small>勾上的端,持有这个角色的人就能进;一个都不勾 = 有这个角色也哪儿都进不去。</small>
+          </div>
+        ) : (
+          <div className="g-chiprow">
+            <EndChips ends={role.ends} />
+            {!configured && <Chip tone="mute">还没配过</Chip>}
+          </div>
+        )}
+        {err !== undefined && <Note tone="warn">{err}</Note>}
+        <Acts
+          align="end"
+          items={
+            editing
+              ? [
+                  { label: '取消', onClick: () => { setDraft(undefined); setErr(undefined); } },
+                  {
+                    label: '保存',
+                    ico: 'check',
+                    primary: true,
+                    busy: save.isPending,
+                    ask: {
+                      title: `把「${role.name}」的可进端改成:${shown.length === 0 ? '无' : shown.map((s) => SURFACE_LABEL[s]).join(' / ')}`,
+                      note: '这张表每个请求都在读 —— 改完下一个请求就按新的判。',
+                      impact: {
+                        who: `持有这个角色的 ${role.holders} 个人`,
+                        undo: '可以改回来 —— 但改完得还有人进得了运营中心,否则服务端会拒',
+                        when: '立刻;他们手上的 token 不用重新登录也按新表判',
+                      },
+                      okLabel: '确认改',
+                      onOk: () => save.mutate(shown),
+                    },
+                  },
+                ]
+              : [
+                  { label: '改可进端', ico: 'pencil-line', onClick: () => setDraft(role.ends) },
+                  ...(configured
+                    ? [
+                        {
+                          label: '删掉这一行',
+                          ico: 'trash-2',
+                          danger: true,
+                          busy: remove.isPending,
+                          ask: {
+                            title: `删掉「${role.name}」的端配置`,
+                            note: '删掉之后这个角色不再命中任何端 —— 与「一个端都不勾」是同一个效果。',
+                            impact: {
+                              who: `持有这个角色的 ${role.holders} 个人`,
+                              undo: '可以再配回来',
+                              when: '立刻',
+                            },
+                            okLabel: '确认删',
+                            onOk: () => remove.mutate(),
+                          },
+                        },
+                      ]
+                    : []),
+                ]
+          }
+        />
+      </div>
+    </div>
+  );
+}
+
+/** 角色详情:谁持有它 —— 从成员那一屏点进来,或从这一屏的角色名点进来 */
+export function RolePage({ id }: { id: string }) {
+  const roles = useOrgRoles();
+  const role = (roles.data?.roles ?? []).find((r) => r.name === id);
+  return (
+    <QueryGate query={roles}>
+      {role === undefined ? (
+        <Clear>{`realm 里没有角色「${id}」—— 可能刚在 Keycloak 里删了。`}</Clear>
+      ) : (
+        <Card ico="shield-check" title={role.name} extra={<St tone="ok" ico="users">{`${role.holders} 人持有`}</St>}>
+          <div className="g-chiprow">
+            <EndChips ends={role.ends} />
+          </div>
+          <Note>授收这个角色在「成员」那一屏的成员详情里做 —— 一次改一个人,收权当场踢掉他的会话。</Note>
+        </Card>
+      )}
+    </QueryGate>
+  );
+}

apps/web/src/shared/gov/gov-api.ts

@@ -23,6 +23,7 @@ import type {
   GovTriggersOutput,
   GovWorkGroupsOutput,
   GovWorkflowOutput,
+  RouteOutput,
   ProcessPackage,
   GovLedgerByActivityOutput,
 } from '@contracts';
@@ -44,6 +45,12 @@ import {
   listLlmInstancesRoute,
   listLlmProvidersRoute,
   listProcessPackagesRoute,
+  getOrgUserRoute,
+  listOrgGroupMembersRoute,
+  listOrgGroupsRoute,
+  listOrgRolesRoute,
+  listOrgUsersRoute,
+  listRoleAccessRoute,
   listStaffRoute,
   listToolsRoute,
   listTriggersRoute,
@@ -190,3 +197,65 @@ export const useGovWorkflow = (id: string): UseQueryResult<GovWorkflow> =>
 
 export const useGovTaskLog = (taskId: string): UseQueryResult<GovTaskLog> =>
   useQuery({ queryKey: ['gov', 'tasklog', taskId], queryFn: () => call<GovTaskLog>(govTaskLogRoute, { params: { taskId } }) });
+
+/* ── 成员与组织(ADR-012)———————————————————————————————————————— */
+
+/**
+ * 各屏的查询键 —— 写完**按碰到的那几屏**失效,别一把 `['gov','org']` 全清。
+ * 成员那一趟最贵(服务端要逐人问角色,见 debt),把它拖进来重取,
+ * 屏上那棵组织树就多钉着已经没了的组好几秒。
+ */
+export const ORG_KEYS = {
+  users: ['gov', 'org', 'users'] as const,
+  user: ['gov', 'org', 'user'] as const,
+  roles: ['gov', 'org', 'roles'] as const,
+  groups: ['gov', 'org', 'groups'] as const,
+  groupMembers: ['gov', 'org', 'group-members'] as const,
+  roleAccess: ['gov', 'org', 'role-access'] as const,
+};
+
+export type GovOrgUsers = RouteOutput<typeof listOrgUsersRoute>;
+export type GovOrgUserDetail = RouteOutput<typeof getOrgUserRoute>;
+export type GovOrgRoles = RouteOutput<typeof listOrgRolesRoute>;
+export type GovOrgGroups = RouteOutput<typeof listOrgGroupsRoute>;
+export type GovOrgGroupMembers = RouteOutput<typeof listOrgGroupMembersRoute>;
+export type GovRoleAccess = RouteOutput<typeof listRoleAccessRoute>;
+
+/**
+ * 成员列表 —— 检索与「含停用」都在**服务端**过滤(那边握着全量,前端只拿要摆的那些)。
+ * 服务端第一次取要几秒(Keycloak 没有批量取角色的口,见 debt),它自己有 60 秒缓存;
+ * 这边 `staleTime` 跟着设一档,免得同一屏的几个组件各要一遍。
+ */
+export const useOrgUsers = (q: string, includeDisabled: boolean): UseQueryResult<GovOrgUsers> =>
+  useQuery({
+    queryKey: ['gov', 'org', 'users', q, includeDisabled],
+    queryFn: () =>
+      call<GovOrgUsers>(listOrgUsersRoute, {
+        query: { q: q === '' ? undefined : q, includeDisabled: includeDisabled ? '1' : undefined },
+      }),
+    staleTime: 30_000,
+  });
+
+export const useOrgUser = (sub: string | undefined): UseQueryResult<GovOrgUserDetail> =>
+  useQuery({
+    queryKey: ['gov', 'org', 'user', sub],
+    queryFn: () => call<GovOrgUserDetail>(getOrgUserRoute, { params: { sub: sub! } }),
+    enabled: sub !== undefined,
+  });
+
+export const useOrgRoles = (): UseQueryResult<GovOrgRoles> =>
+  useQuery({ queryKey: ['gov', 'org', 'roles'], queryFn: () => call<GovOrgRoles>(listOrgRolesRoute), staleTime: 30_000 });
+
+export const useOrgGroups = (): UseQueryResult<GovOrgGroups> =>
+  useQuery({ queryKey: ['gov', 'org', 'groups'], queryFn: () => call<GovOrgGroups>(listOrgGroupsRoute), staleTime: 30_000 });
+
+export const useOrgGroupMembers = (groupId: string | undefined): UseQueryResult<GovOrgGroupMembers> =>
+  useQuery({
+    queryKey: ['gov', 'org', 'group-members', groupId],
+    queryFn: () => call<GovOrgGroupMembers>(listOrgGroupMembersRoute, { params: { id: groupId! } }),
+    enabled: groupId !== undefined,
+  });
+
+/** 角色 → 端 —— 这张表是**本地**的(ADR-012),不是 Keycloak 的字段 */
+export const useRoleAccess = (): UseQueryResult<GovRoleAccess> =>
+  useQuery({ queryKey: ['gov', 'org', 'role-access'], queryFn: () => call<GovRoleAccess>(listRoleAccessRoute) });

apps/web/src/shared/gov/gov-route.ts

@@ -113,10 +113,10 @@ export const ZM: Readonly<Record<GovZone, { title: string; desc: string; accent:
     desc: '活动的运行时:任务 = 活动被调起的一次运行,恰有一名负责人。这里做任务与审批单的在途监控、干预与控制——暂停可恢复、叫停归负责人、终止级联作废。工作流一级去「工作流」区看。',
   },
   people: {
-    title: '员工管理',
+    title: '成员与组织',
     icon: 'users',
     accent: 'linear-gradient(140deg,#2bc7d4,#0e9fd8)',
-    desc: '员工负载、岗位与授权。权限按岗位授予:客体三类 × 动作三种;停用前置检查——在途任务与待答卡须先改派完毕。',
+    desc: '成员与组织的真源是 Keycloak:这里建的人立刻能登录、停的人立刻登不上,没有本地草稿,也没有撤销。权限只到端——一个角色能进设计中心 / 运营中心 / 工作台的哪几个,由本系统的「角色 → 端」表说了算。',
   },
   workflows: {
     title: '流程包管理',
@@ -179,7 +179,10 @@ export const ZM: Readonly<Record<GovZone, { title: string; desc: string; accent:
  * 还留着多格的只有运营侧的任务与员工(它们确实是几个不同维度),
  * 以及 `ledgers`:它的页签是数据域,随发布动态生成(壳层运行时铺开),故此表留空。
  */
-export const TABS: Readonly<Record<GovZone, ReadonlyArray<{ key: string; label: string; ico: string }>>> = {
+/** `hint` 摆在页签栏右端 —— 一句话说清这一格管什么、写下去会发生什么 */
+export const TABS: Readonly<
+  Record<GovZone, ReadonlyArray<{ key: string; label: string; ico: string; hint?: string }>>
+> = {
   blueprint: [{ key: 'map', label: '企业蓝图', ico: 'route' }],
   /*
    * 测试台三格 —— 从前是一格加一个「两档旋钮」,旋钮长在内容里,别处跳不进来、
@@ -209,10 +212,16 @@ export const TABS: Readonly<Record<GovZone, ReadonlyArray<{ key: string; label:
     { key: 'active', label: '激活中', ico: 'zap' },
     { key: 'disabled', label: '已禁用', ico: 'ban' },
   ],
+  /*
+   * 成员与组织(2026-08-26 用户定):三个页签一一对着 Keycloak 的三样东西 ——
+   * 成员 = users、权限 = realm roles、组织 = groups。
+   * 原「岗位授权」与「工作组」两个页签先拿掉(用户定);两处**后端数据与接口原样留着**,
+   * 拿掉的只是入口 —— 岗位仍决定活动派单的候选集,工作组仍在起单那一刻快照进工作流。
+   */
   people: [
-    { key: 'emp', label: '员工', ico: 'users' },
+    { key: 'members', label: '成员', ico: 'users', hint: 'Keycloak 目录投影:成员列表 · 新建 · 启停,点行进详情' },
-    { key: 'roles', label: '岗位授权', ico: 'key' },
+    { key: 'perms', label: '权限', ico: 'shield-check', hint: '角色 → 能进哪几个端(本地配置)· 授收角色(穿透 Keycloak)' },
-    { key: 'groups', label: '工作组', ico: 'users' },
+    { key: 'orgs', label: '组织', ico: 'network', hint: '组织树:建组 / 改名 / 删组 / 成员进出组' },
   ],
   ledgers: [], // 动态:页签即数据域(短名呈现),由壳层按已发布域生成
   system: [{ key: 'chan', label: '通道实例', ico: 'mail' }],

apps/web/vite.config.ts

@@ -5,7 +5,31 @@ import { fileURLToPath } from 'node:url';
 const root = fileURLToPath(new URL('../..', import.meta.url));
 const p = (rel: string) => fileURLToPath(new URL(rel, import.meta.url));
 
+/*
+ * 稳定版(./stable.sh)用 `vite preview` 托 .build/stable 的静态文件。preview 有一道宿主校验
+ * (防 DNS rebinding),默认只放 localhost 与 IP —— 经域名 / 反代进来会被拦:
+ * 「Blocked request. This host ("…") is not allowed.」
+ * 放哪些宿主由起它的人说(PREVIEW_ALLOWED_HOSTS,逗号分隔;`.example.com` 放整个子域;`*` 全放)。
+ * 开发那台 `vite` 不读这个,不受影响。
+ */
+const previewHosts = process.env.PREVIEW_ALLOWED_HOSTS?.trim();
+const preview =
+  previewHosts === undefined || previewHosts === ''
+    ? {}
+    : {
+        preview: {
+          allowedHosts:
+            previewHosts === '*'
+              ? (true as const)
+              : previewHosts
+                  .split(',')
+                  .map((s) => s.trim())
+                  .filter((s) => s !== ''),
+        },
+      };
+
 export default defineConfig({
+  ...preview,
   plugins: [react()],
   resolve: {
     alias: {

docs/SS02-ACT-WORK-05-html/ACT-WORK-05-一键启动入参说明.md

@@ -0,0 +1,46 @@
+# ACT-WORK-05 差异评估 — 一键启动入参说明（运营端）
+
+> 本文档与《SS02-SS03-SS04_Demo台账字段细化与统一方案》字段口径一致（统一字段名、编号归并、主记录/子表结构均按该方案 4.2 节与第五节执行）。
+
+## 一、背景
+
+ACT-WORK-05 差异评估平时由上游触发：ACT-WORK-03 检索调用，或 ACT-GATE-02 路径判定后进入。
+
+**本文档是运营端一键启动功能的入参规格**：表单在独立运营端完成，参数在启动时填好传入，系统据此直接启动活动（人工扮演上游，把进入条件变成表单）。
+
+**极简原则（2026-08-26 定）**：一键启动只收 **4 个参数** —— 客户、客户需求、原 PN、替代 PN（数组）。**启动不等资料**：应用场景、BOM 位、替代类型、datasheet、需求版本调整等一切其余信息，都在活动启动后、执行过程中由工作台的数据工单逐项补齐（数据工单一单一类可多条，确认即入库，活动从断点续跑）。
+
+**渠道无感知原则**：活动与工单对触发渠道无感知——上游触发（ACT-WORK-03 / ACT-GATE-02）传入的字段集与本规格完全一致（同样 4 项）。运营端按本规格传参，活动按进入条件消费，不记录渠道；仅 `source_type=手动启动` 在运营端留痕，供 ACT-GATE-03 评审放行时追溯。
+
+## 二、入参总表
+
+一键启动的全部参数，就这四行：
+
+| 中文字段 | 统一字段名 | 必填性 | 输入方式 | 默认值 | 说明 |
+|---|---|---|---|---|---|
+| 客户 | customer_id | 必填 | L-02 选择器 | — | 新建 P-01 需求时挂客户 ID；决定通知对象与默认负责人线。 |
+| 客户需求 | request_description | 必填 | 文本 | — | 保留原始需求语义；据此新建 P-01 需求主记录（版本 V1）。 |
+| 原内部料号 | original_internal_pn | 必填 | P-08 选择器 | — | 差异评估基准，引用 P-08.internal_pn。 |
+| 候选内部料号 | candidate_internal_pn[] | 必填（**数组，≥1**） | P-08 选择器（**多选**） | — | 被评估物料，**一次可传多个**，逐个评估、逐个做存在性检查；P-08 无记录不拦启动——启动后按存在性检查逐个派数据工单创建（候选 ≥2 也可选择放弃，记录放弃原因）。 |
+
+**系统带出 / 默认值**（不在表单上出现，启动时自动落）：需求版本 V1、替代类型 Pin-to-Pin、规则版本当前发布版 R-2026.07（as_of 锁定，随结论落账）、期限 1 个工作日、负责人（PW）与审核（FAE）按客户线默认、`source_type=手动启动`。以上任何一项要改，都在启动后的工单里改，不回表单。
+
+## 三、点击启动后系统行为
+
+1. 生成任务号（如 TASK-BT02-20260818-007）；
+2. 新建 P-01 需求主记录（V1）：客户 ID + 需求描述落账，绑定原 PN 与候选 PN 数组；
+3. **存在性检查**（按 internal_pn 查 P-08 等台账，候选数组逐个查）：原 PN 无数据 → 硬阻塞，派数据工单，活动停「等待数据」；候选 PN 无数据 → 候选 ≥2 可放弃【记录放弃原因】或派数据工单创建，候选 =1 必须创建；数据工单**确认即入库**（确认人=责任人留痕）后活动自动唤醒。**启动时的存在性检查只是惰性触发的第一次**——活动执行中每次读台账仍可能派发新数据工单（一单一类可多条，D02、D03…，全部确认后从断点续跑）；
+4. 生成输入快照 input_snapshot_ref（活动自持中间产物，支持版本回溯）；
+5. 进入步骤 1 · 建立评估上下文，派执行工单 01——启动传入的 4 项只读核对，**未齐资料全部在工单里补**：应用场景、BOM 位、替代类型确认、需求版本调整等缺口字段，PW 在工作台逐项填写，不回流表单。
+
+## 四、极简参数集
+
+手工必给的只有 4 个：**客户、客户需求、原 PN、候选 PN（数组）** —— 这就是一键启动的全部入参，没有第二张表。
+
+设计意图：**启动的门槛越低，活动跑得越早**；资料不齐不该拦启动，缺口在执行中由数据工单追着人补，而不是在表单里追着人填。数据工单里 datasheet 选填（传了 AI 预填，没传全手填），同样不拦流程。
+
+## 五、与现有工单的衔接
+
+执行工单 01 的「评估输入清单」（`in.evaluation_inputs`）中，启动传入的 4 项回显为「已绑定 / 已锁定」的灰底只读行：客户、客户需求（及其新建的 P-01 需求与版本 V1）、原 PN、候选 PN（数组逐行）；其余行（应用场景、BOM 位、替代类型、规则版本确认、负责人/期限调整等）为 PW 补缺口的可编辑行。**启动参数如有误，须退回启动人在运营端修订后重新启动，工单内不可改**。工单不展示、也不区分触发渠道——上游触发传入同一字段集时，呈现与本表单回显完全相同。
+
+PN 不在库时派发的**数据工单**（`in.create_p08_fields` / `in.create_p08_params`）：datasheet 在**数据工单里**上传（选填）——传了则 AI 预填字段与参数集（示例 8 项字段 + 7 行参数），没传则人全填；人在对话区【数据卡】确认即正式入库，确认人=数据责任人并留痕，入库后活动自动唤醒进步骤 1。

docs/SS02-ACT-WORK-05-html/ACT-WORK-05-全流程分支图.html

@@ -0,0 +1,370 @@
+<!doctype html>
+<html lang="zh-CN">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>ACT-WORK-05 差异评估 · 全流程与分支一览</title>
+<style>
+:root{
+  --ink:#1f2329; --ink-2:#41464e; --ink-3:#646a73; --ink-4:#8f959e;
+  --line:#dee0e3; --line-soft:#e8eaed; --soft:#f8f9fb;
+  --brand:#3370ff; --brand-soft:#e1eaff; --brand-wash:#f0f4ff;
+  --human:#a9711e; --human-soft:#f6ecd8; --human-line:#e6d3a8;
+  --ledger:#b23a2e; --ledger-soft:#f7e4e0; --ledger-line:#ecc5bd;
+  --ok:#278717; --ok-soft:#e8f8e4;
+  --danger:#d83931; --danger-soft:#feeae9;
+  --mono:"SF Mono",Menlo,Consolas,monospace;
+}
+*{box-sizing:border-box}
+html,body{margin:0;padding:0}
+body{font-family:Inter,ui-sans-serif,system-ui,-apple-system,BlinkMacSystemFont,"Segoe UI","PingFang SC","Microsoft YaHei",sans-serif;background:#eef1f6;color:var(--ink);font-size:14px;line-height:1.7;-webkit-font-smoothing:antialiased}
+.page{max-width:1240px;margin:0 auto;padding:28px 22px 40px}
+
+/* 标题区 */
+.mast{margin-bottom:18px}
+.mast .kick{font-size:11px;letter-spacing:.1em;color:var(--ink-4);font-weight:700}
+.mast h1{margin:4px 0 4px;font-size:24px;font-weight:800;line-height:1.3}
+.mast .sub{font-size:13px;color:var(--ink-3)}
+.mast .sub b{color:var(--ink-2)}
+
+/* 通用卡片 */
+.card{background:#fff;border:1px solid var(--line-soft);border-radius:10px;padding:16px 18px;margin-bottom:14px}
+.card p{margin:0 0 6px;font-size:13px;color:var(--ink-2)}
+.card p:last-child{margin-bottom:0}
+.card b{color:var(--ink)}
+.muted{color:var(--ink-3);font-size:12.5px}
+.mono{font-family:var(--mono);font-size:12px;color:var(--ink-2)}
+
+/* 角色 pill */
+.role{display:inline-block;padding:1px 10px;border-radius:999px;font-size:11px;font-weight:800;letter-spacing:.04em;white-space:nowrap;border:1px solid transparent;vertical-align:1px}
+.role.ai{color:var(--brand);background:var(--brand-soft);border-color:#c3d6ff}
+.role.pw{color:var(--human);background:var(--human-soft);border-color:var(--human-line)}
+.role.ri{color:var(--ledger);background:var(--ledger-soft);border-color:var(--ledger-line)}
+.role.gate{color:#fff;background:var(--ledger);border-color:var(--ledger)}
+.role.data{color:var(--brand);background:var(--brand-soft);border-color:#c3d6ff}
+
+/* 推荐等级 pill */
+.lv{display:inline-block;padding:1px 10px;border-radius:999px;font-size:11.5px;font-weight:800;white-space:nowrap;border:1px solid transparent}
+.lv.cond{color:var(--human);background:var(--human-soft);border-color:var(--human-line)}
+.lv.alt{color:var(--brand);background:var(--brand-soft);border-color:#c3d6ff}
+.lv.no{color:var(--danger);background:var(--danger-soft);border-color:#f3b9b5}
+
+/* 场景卡 */
+.scene{border-left:4px solid var(--brand)}
+.scene .tagline{font-size:12px;font-weight:800;letter-spacing:.08em;color:var(--brand);margin-bottom:6px}
+
+/* 范围横幅 */
+.scope{border:2px solid var(--ok);background:linear-gradient(120deg,#f2fbf0 0%,#fff 60%,#f0f6ff 100%);padding:16px 20px}
+.scope .q{font-size:15px;font-weight:800;color:var(--ink);margin:0 0 6px}
+.scope .q em{font-style:normal;color:var(--ok)}
+.scope .nq{margin:0;font-size:12.5px;color:var(--ink-3)}
+.scope .nq b{color:var(--ink-2)}
+
+/* 进入条件卡 */
+.entry{border-left:4px solid var(--human)}
+.entry ul{margin:4px 0 0;padding-left:18px;font-size:13px;color:var(--ink-2)}
+.entry li{margin:3px 0}
+.entry .ds{display:inline-block;padding:0 8px;border-radius:999px;font-size:11px;font-weight:800;color:var(--brand);background:var(--brand-soft);border:1px solid #c3d6ff;white-space:nowrap}
+
+/* 小图标 */
+.sic{width:14px;height:14px;color:var(--ink-3);vertical-align:-2px;margin-right:3px}
+
+/* 主链 */
+.chain{margin-top:6px}
+.steprow{display:grid;grid-template-columns:minmax(0,7fr) minmax(0,5fr);gap:14px;align-items:start}
+.step{position:relative;background:#fff;border:1px solid var(--line-soft);border-radius:10px;padding:15px 18px 14px 22px;overflow:hidden}
+.step::before{content:"";position:absolute;left:0;top:0;bottom:0;width:5px;background:var(--ink-4)}
+.step.ai::before{background:var(--brand)}
+.step.pw::before{background:var(--human)}
+.step.ri::before{background:var(--ledger)}
+.step .s-head{display:flex;align-items:center;gap:10px;flex-wrap:wrap;margin-bottom:6px}
+.step .s-no{font-family:var(--mono);font-size:12px;font-weight:800;color:#fff;background:var(--ink-4);border-radius:6px;padding:1px 8px}
+.step.ai .s-no{background:var(--brand)}
+.step.pw .s-no{background:var(--human)}
+.step.ri .s-no{background:var(--ledger)}
+.step h3{margin:0;font-size:15px;font-weight:800}
+.step .wo{font-size:12px;font-weight:800;color:var(--ink-2);background:var(--soft);border:1px solid var(--line);border-radius:6px;padding:1px 8px}
+.step .wo.data{color:var(--brand);background:var(--brand-soft);border-color:#c3d6ff}
+.step p{margin:0 0 5px;font-size:13px;color:var(--ink-2)}
+.step .ledgers{font-size:12px;color:var(--ink-3)}
+.step .ledgers b{color:var(--ink-2)}
+.step .ledgers code{font-family:var(--mono);font-size:11.5px;background:var(--soft);border:1px solid var(--line-soft);border-radius:4px;padding:0 5px;color:var(--ink-2)}
+
+/* 步骤间箭头 */
+.arrow{display:flex;justify-content:flex-start;padding:2px 0 2px 46px;color:var(--ink-4);font-size:15px;line-height:1.4;user-select:none}
+.arrow::before{content:"▼"}
+
+/* 分支卡 */
+.branches{display:flex;flex-direction:column;gap:8px;padding-top:2px}
+.branches .b-title{font-size:11px;font-weight:800;letter-spacing:.1em;color:var(--ink-4);padding-left:16px}
+.br{position:relative;background:#fff;border:1px solid var(--line-soft);border-left:3px solid var(--ink-4);border-radius:8px;padding:9px 12px 9px 14px;font-size:12.5px;color:var(--ink-2);margin-left:16px}
+.br::before{content:"";position:absolute;left:-17px;top:16px;width:16px;border-top:2px dashed var(--ink-4)}
+.br.warn{border-left-color:var(--ledger)}
+.br.warn::before{border-top-color:var(--ledger)}
+.br.okp{border-left-color:var(--ok)}
+.br.okp::before{border-top-color:var(--ok)}
+.br.data{border-left-color:var(--brand);background:var(--brand-wash)}
+.br.data::before{border-top-color:var(--brand)}
+.br .b-id{font-family:var(--mono);font-weight:800;font-size:11px;color:var(--ink-3);margin-right:6px}
+.br.warn .b-id{color:var(--ledger)}
+.br.okp .b-id{color:var(--ok)}
+.br.data .b-id{color:var(--brand)}
+.br .go{display:block;margin-top:3px;font-size:11.5px;color:var(--ink-3)}
+.br .go::before{content:"╌▶ ";color:var(--ink-4);letter-spacing:-1px}
+.br.warn .go::before{color:var(--ledger)}
+.br.data .go::before{color:var(--brand)}
+.br.data .go{color:var(--ink-2)}
+
+/* 完结结果矩阵 */
+.tbl-wrap{border:1px solid var(--line-soft);border-radius:10px;overflow:hidden}
+.matrix{width:100%;border-collapse:collapse;font-size:13px;background:#fff}
+.matrix th{text-align:left;background:var(--soft);font-size:11px;letter-spacing:.05em;font-weight:800;color:var(--ink-3);padding:9px 12px;border-bottom:1px solid var(--line)}
+.matrix td{padding:10px 12px;border-bottom:1px solid var(--line-soft);vertical-align:top}
+.matrix tr:last-child td{border-bottom:0}
+
+/* 完结分支条 */
+.endbr{display:grid;grid-template-columns:repeat(4,minmax(0,1fr));gap:10px;margin-top:12px}
+.endbr .br{margin-left:0}
+.endbr .br::before{display:none}
+
+/* 下游灰显区 */
+.downstream{background:#f1f2f5;border:1px dashed var(--line);border-radius:10px;padding:14px 18px;color:var(--ink-3)}
+.downstream .d-tag{display:inline-block;font-size:11px;font-weight:800;letter-spacing:.08em;color:var(--ink-4);border:1px solid var(--line);border-radius:999px;padding:1px 10px;background:#fff;margin-bottom:8px}
+.downstream ul{margin:0;padding-left:18px;font-size:12.5px}
+.downstream li{margin:3px 0}
+
+/* 图例表 */
+.legend{width:100%;border-collapse:collapse;font-size:12.5px;background:#fff}
+.legend th{text-align:left;background:var(--soft);font-size:11px;letter-spacing:.05em;font-weight:800;color:var(--ink-3);padding:8px 12px;border-bottom:1px solid var(--line)}
+.legend td{padding:8px 12px;border-bottom:1px solid var(--line-soft);vertical-align:top;color:var(--ink-2)}
+.legend tr:last-child td{border-bottom:0}
+.legend .b-id{font-family:var(--mono);font-weight:800;font-size:11px;color:var(--ink-2);white-space:nowrap}
+
+/* 页脚 */
+.foot{margin-top:18px;font-size:11.5px;color:var(--ink-4);display:flex;justify-content:space-between;flex-wrap:wrap;gap:8px}
+
+.sec{font-size:12px;font-weight:800;letter-spacing:.12em;color:var(--ink-4);margin:20px 0 8px}
+@media(max-width:900px){.steprow{grid-template-columns:1fr}.endbr{grid-template-columns:1fr 1fr}.branches .b-title{padding-left:0}.br{margin-left:0}.br::before{display:none}}
+@media (prefers-reduced-motion: reduce){*{animation:none!important;transition:none!important}}
+</style>
+</head>
+<body>
+<div class="page">
+
+  <!-- 1. 标题区 -->
+  <div class="mast">
+    <div class="kick">SS02 · 需求分析与方案匹配 ｜ BT-02 跨品牌替代选型场景</div>
+    <h1>ACT-WORK-05 差异评估 · 全流程与分支一览</h1>
+    <div class="sub">SS02 需求分析与方案匹配 ｜ 负责人 <b>FAE/RI</b> ｜ 门禁 <b>ACT-GATE-03</b> 评审放行 ｜ 工单：<b>1 数据（条件触发）+ 1 执行 + 2 验收</b></div>
+  </div>
+
+  <!-- 2. 场景卡 -->
+  <div class="card scene">
+    <div class="tagline">业务场景（演示示例）</div>
+    <p>客户工业电源项目在用 <b>LM2596S-5.0</b>（TI，12V→5V、工业温域、40V 输入上限），原厂发布 PCN 该料转 <b>NRND</b>，客户要求验证替代料。你（FAE）从料库筛出 3 种候选：<b>A = XL2596S-5.0</b>（XLSEMI）、<b>B = LM2596S-ADJ</b>（TI 同族可调版）、<b>C = 国产某 DCDC</b>。</p>
+    <p class="muted">触发双通道：①上游触发（ACT-WORK-03 检索调用 / ACT-GATE-02 路径判定）②运营端一键启动（可快速创建需求单：request_id 系统生成、requirement_version 默认 V1）。两通道传入同一字段集——<b>活动内部不区分渠道</b>，工单无差别呈现。</p>
+  </div>
+
+  <!-- 3. 范围横幅 -->
+  <div class="card scope">
+    <p class="q">本活动只回答一个问题——<em>技术上哪种料能替</em>（输出：每个候选的推荐等级与证据）。</p>
+    <p class="nq">它<b>不回答</b>：买不买得到、数量够不够、多少钱——那些是下游活动的事（SS03 询价、ACT-WORK-24 报价），本图末尾灰显仅作衔接示意。</p>
+  </div>
+
+  <!-- 4. 进入条件卡 -->
+  <div class="card entry">
+    <p style="font-size:12px;font-weight:800;letter-spacing:.08em;color:var(--human);margin:0 0 4px">进入条件 · 启动校验（agent 创建活动实例前必查）</p>
+    <ul>
+      <li><b>任务锚点</b>（二选一）：关联已有需求 request_id，或快速创建（customer_id + 需求描述 → 系统建 P-01、生成 request_id、版本默认 V1；原 PN 与候选 PN 数组作为独立入参绑定）；</li>
+      <li><b>启动仅绑定 4 项</b>：客户 + 客户需求 + 原 PN + 候选 PN（数组）；应用场景、BOM 位等其余资料启动后在工单内补齐，不回表单；</li>
+      <li><b>datasheet 选填</b> <span class="ds">选填</span>：只影响数据工单是「AI 预填」还是「人全填」，<b>不影响能否启动</b>；</li>
+      <li><b>存在性检查 = 全链路惰性触发</b>：按主键查台账，查无记录即派数据工单；启动校验只是第一次，之后每次读数仍可能再派（D02、D03…）。</li>
+    </ul>
+  </div>
+
+  <p class="sec"><svg class="sic" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M4 6h16M4 12h16M4 18h16"/></svg>主 链 · 启动期 + 5 步工作链条（右侧挂分支）</p>
+  <div class="chain">
+
+    <!-- 0 启动期 -->
+    <div class="steprow">
+      <div class="step pw">
+        <div class="s-head"><span class="s-no">0</span><h3>启动期 · 参数绑定与存在性检查</h3><span class="role pw">运营端 / 上游 · 系统</span><span class="wo data">数据工单 01（条件触发）</span></div>
+        <p>参数绑定（任务 / 版本 / 双 PN / BOM 位 / 规则版本）→ 生成输入快照 <span class="mono">input_snapshot_ref</span>；存在性检查发现「完全没有」→ 派数据工单：活动停「等待数据」→ 确认入库 → 唤醒进步骤 1。</p>
+        <div class="ledgers"><b>读写台账：</b><code>P-01</code>（W 写入/回链）· <code>P-08</code>（R 校验）· <code>P-10</code>（R/W 校验）</div>
+      </div>
+      <div class="branches">
+        <div class="b-title">分支 · 启动前置 / 数据补齐</div>
+        <div class="br warn"><span class="b-id">0a</span>新客户无档案<span class="go">先建 L-02 客户档案（数据工单），再返回启动</span></div>
+        <div class="br data"><span class="b-id">0b</span>候选无 P-08 主数据<span class="go">同分支 1d：派数据工单创建，确认入库后继续</span></div>
+        <div class="br"><span class="b-id">0c</span>未传 datasheet<span class="go">不再拦截：datasheet 已为选填，仅意味着数据工单全手填</span></div>
+      </div>
+    </div>
+
+    <div class="arrow"></div>
+
+    <!-- 步骤 1 -->
+    <div class="steprow">
+      <div class="step pw">
+        <div class="s-head"><span class="s-no">1</span><h3>建立评估上下文</h3><span class="role pw">PW / AI</span><span class="wo">执行工单 01</span></div>
+        <p>评估输入清单（一张表）：<b>已绑定行灰底只读核对</b>（启动仅绑定 4 项：客户 / 需求 / 原 PN / 候选数组）＋ <b>缺口行可编辑补齐</b>（应用场景、BOM 位等待补项 + 默认·可改项，补充内容必填＊，可加行/删行）。工单内不可改绑定值。</p>
+        <div class="ledgers"><b>读台账：</b><code>P-01</code> · <code>P-09</code> · <code>EXT-02</code>（快照：<code>input_snapshot_ref</code>）</div>
+      </div>
+      <div class="branches">
+        <div class="b-title">分支 · 绑定、缺口与数据创建</div>
+        <div class="br data"><span class="b-id">1d</span><b>任何读数点查无记录 → 派数据工单</b><span class="go">一单一类可多条（字段即表头、每行一条，可批量创建）；模板统一（实例仅两处可变：目标台账决定表头 schema、预填内容决定行集）；多实例 D01/D02…。原 PN=硬阻塞·必须创建；候选 ≥2 可放弃或创建（人判断）；候选 =1 必须创建。确认即正式入库（无草稿无审核、确认人=责任人留痕）→ 断点续跑。只建主数据/资料，事实/证据类（P-06）不可创建、挂验证任务</span></div>
+        <div class="br warn"><span class="b-id">1a</span>绑定参数有误<span class="go">退回触发方修订后重新触发（工单内不可改；手动→退回运营端启动人，上游→退回上游活动）</span></div>
+        <div class="br"><span class="b-id">1b</span>补缺口四情形（有而不全）：参数未披露→挂验证任务 ｜ 资料版本过旧→补最新版 ｜ 应用约束不清→问客户并更新需求单版本（V1→V1.1）｜ 外部来源补充</div>
+        <div class="br"><span class="b-id">1c</span>缺口补不了<span class="go">留 UNKNOWN 进入评估（合法路径，不阻断）</span></div>
+      </div>
+    </div>
+
+    <div class="arrow"></div>
+
+    <!-- 步骤 2 -->
+    <div class="steprow">
+      <div class="step ai">
+        <div class="s-head"><span class="s-no">2</span><h3>读取并标准化资料</h3><span class="role ai">AI</span><span class="wo">不派工单</span></div>
+        <p>统一参数名 / 单位 / 版本 / 证据引用，产出标准化参数对照表。<b>每次读数做存在性检查</b>：主数据 / 资料类查无 → 派数据工单；事实 / 证据类（P-06）查无 → 挂验证任务。缺失项标记 UNKNOWN。</p>
+        <div class="ledgers"><b>读台账：</b><code>P-08</code> · <code>P-10</code> · <code>P-06</code> · <code>GOV</code>（规则版本 <code>rule_version</code> 锁定）</div>
+      </div>
+      <div class="branches">
+        <div class="b-title">分支 · 标准化冲突</div>
+        <div class="br warn"><span class="b-id">2a</span>单位冲突<span class="go">阻断，回步骤 1 补证</span></div>
+        <div class="br"><span class="b-id">2b</span>证据版本冲突<span class="go">人工复核哪份资料为准</span></div>
+      </div>
+    </div>
+
+    <div class="arrow"></div>
+
+    <!-- 步骤 3 -->
+    <div class="steprow">
+      <div class="step ai">
+        <div class="s-head"><span class="s-no">3</span><h3>逐项差异评估</h3><span class="role ai">AI</span><span class="wo">不派工单</span></div>
+        <p>按硬约束（封装 / 工艺 / 电气上限等）与软约束逐项判定，输出 <b>MATCH / MISMATCH / UNKNOWN / CONDITIONAL</b>，附影响、风险、证据与置信度，形成 P-11 差异明细子表草稿。</p>
+        <div class="ledgers"><b>读：</b>步骤 2 对照表 + GOV 规则（取参数同样做存在性检查）｜ <b>产出：</b>P-11 差异明细子表草稿（审核前不落账）</div>
+      </div>
+      <div class="branches">
+        <div class="b-title">分支 · 硬约束失败</div>
+        <div class="br warn"><span class="b-id">3a</span>硬约束 MISMATCH<span class="go">该候选直接「不推荐」——如候选 C 输入上限 32V &lt; 客户 40V</span></div>
+      </div>
+    </div>
+
+    <div class="arrow"></div>
+
+    <!-- 步骤 4 -->
+    <div class="steprow">
+      <div class="step ri">
+        <div class="s-head"><span class="s-no">4</span><h3>FAE/RI 审核与补证</h3><span class="role ri">FAE / RI</span><span class="wo">验收工单 01</span></div>
+        <p>审核 P-11 差异明细子表草稿（含<b>约束类型</b>列）：确认参数解释、风险等级、证据可信度与验证要求；四态逐项无漏项，UNKNOWN 必须有去向。</p>
+        <div class="ledgers"><b>条件写：</b><code>P-06</code>（审核意见与验证要求 <code>verification_requirement</code>）</div>
+      </div>
+      <div class="branches">
+        <div class="b-title">分支 · 审核驳回</div>
+        <div class="br warn"><span class="b-id">4a</span>UNKNOWN 无去向<span class="go">退回步骤 1~2 补证 / 挂验证任务</span></div>
+        <div class="br warn"><span class="b-id">4b</span>证据链不全<span class="go">退回补齐证据回链（证据来源含数据工单创建记录：人工录入 · 工单号 · 确认人）</span></div>
+      </div>
+    </div>
+
+    <div class="arrow"></div>
+
+    <!-- 步骤 5 -->
+    <div class="steprow">
+      <div class="step ri">
+        <div class="s-head"><span class="s-no">5</span><h3>落账与提交 ACT-GATE-03</h3><span class="role ri">FAE / RI</span><span class="role gate">门禁</span><span class="wo">验收工单 02</span></div>
+        <p>确认拟落账内容后提交门禁：<b>P-11 替代关系主记录落账</b>——推荐等级 recommendation_level 四态（推荐 / 条件推荐 / 备选 / 不推荐）、analysis_status=FAE确认；customer_approval_status 由独立审批流维护，本活动不碰。并回写 P-01。</p>
+        <div class="ledgers"><b>写台账：</b><code>P-11</code>（W）· <code>P-01</code>（W 回写）｜ 每个候选各一条 P-11 记录</div>
+      </div>
+      <div class="branches">
+        <div class="b-title">分支 · 门禁结果</div>
+        <div class="br okp"><span class="b-id">5a</span>GATE-03 放行<span class="go">P-11 落账生效，衔接下游</span></div>
+        <div class="br warn"><span class="b-id">5b</span>GATE-03 驳回<span class="go">REWORK：回步骤 4 重审，或回步骤 1 重补输入</span></div>
+      </div>
+    </div>
+
+  </div>
+
+  <!-- 7. 完结结果矩阵 -->
+  <p class="sec"><svg class="sic" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><rect x="3" y="4" width="18" height="16" rx="2"/><path d="M3 10h18M9 10v10"/></svg>完 结 · 本示例三候选评估结果</p>
+  <div class="card">
+    <div class="tbl-wrap">
+      <table class="matrix">
+        <thead><tr><th style="width:22%">候选</th><th style="width:14%">推荐等级</th><th>关键依据</th><th style="width:24%">下一步</th></tr></thead>
+        <tbody>
+          <tr>
+            <td><b>A</b> <span class="mono">XL2596S-5.0</span><br><span class="muted">XLSEMI</span></td>
+            <td><span class="lv cond">条件推荐</span></td>
+            <td>温度范围更优（-40~+125℃ vs +85℃）；使能阈值 UNKNOWN，挂 <span class="mono">VAL-2026-0188</span> 实测</td>
+            <td>验证闭环后转正</td>
+          </tr>
+          <tr>
+            <td><b>B</b> <span class="mono">LM2596S-ADJ</span><br><span class="muted">TI 同族可调版</span></td>
+            <td><span class="lv alt">备选</span></td>
+            <td>反馈网络不同（可调版 vs 固定 5V），需改 BOM 外围</td>
+            <td>客户接受改设计则启用</td>
+          </tr>
+          <tr>
+            <td><b>C</b> <span class="mono">国产某 DCDC</span></td>
+            <td><span class="lv no">不推荐</span></td>
+            <td>硬约束失败：输入上限 32V &lt; 客户 40V（分支 3a）</td>
+            <td>归档，不再评估</td>
+          </tr>
+        </tbody>
+      </table>
+    </div>
+    <p class="muted" style="margin-top:10px">注：多候选<b>并行评估、独立落账</b>（各一条 P-11 记录），不存在「选一个再评下一个」。</p>
+    <div class="endbr">
+      <div class="br okp"><span class="b-id">6a</span>至少一个推荐<span class="go">交下游衔接（见灰显区）</span></div>
+      <div class="br"><span class="b-id">6b</span>全是条件推荐<span class="go">等验证闭环：通过→升级推荐；不过→降级不推荐</span></div>
+      <div class="br warn"><span class="b-id">6c</span>全不推荐<span class="go">重新检索替代料 / 继续用原 PN / 与客户协商放宽约束</span></div>
+      <div class="br"><span class="b-id">6d</span>客户不批准<span class="go">走独立审批流（customer_approval_status），不在本活动</span></div>
+    </div>
+  </div>
+
+  <!-- 8. 下游灰显区 -->
+  <p class="sec"><svg class="sic" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M5 12h14M13 6l6 6-6 6"/></svg>下 游 · 范围外，仅作衔接示意</p>
+  <div class="downstream">
+    <span class="d-tag">范围外 · 仅作衔接示意</span>
+    <ul>
+      <li><b>ACT-WORK-08 证据归集</b>：GATE-03 放行后自动衔接，消费本活动结论。</li>
+      <li><b>SS03 询价 / ACT-WORK-24 报价</b>：商务与供货问题（价格、交期、数量），不在本活动回答。</li>
+      <li><b>客户批准审批流</b>：维护 <span class="mono">P-11.customer_approval_status</span>，独立于本活动。</li>
+    </ul>
+  </div>
+
+  <!-- 9. 分支图例表 -->
+  <p class="sec"><svg class="sic" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M4 6h16M4 12h10M4 18h7"/></svg>图 例 · 全部分支对照表（18 条）</p>
+  <div class="card" style="padding:0;overflow:hidden">
+    <table class="legend">
+      <thead><tr><th style="width:70px">分支</th><th>触发条件</th><th style="width:44%">去向</th></tr></thead>
+      <tbody>
+        <tr><td class="b-id">0a</td><td>启动期：新客户无档案</td><td>先建 L-02 客户档案（数据工单），再返回启动</td></tr>
+        <tr><td class="b-id">0b</td><td>启动期：候选无 P-08 主数据</td><td>同分支 1d：派数据工单登记创建</td></tr>
+        <tr><td class="b-id">0c</td><td>启动期：未传 datasheet</td><td>不再拦截——datasheet 已是选填，仅意味着数据工单由「AI 预填」变为「人全填」</td></tr>
+        <tr><td class="b-id">1a</td><td>步骤 1：绑定参数有误</td><td>退回触发方修订后重新触发（工单内不可改）</td></tr>
+        <tr><td class="b-id">1b</td><td>步骤 1：输入存在缺口（有而不全）</td><td>补缺口四情形：候选 PDF 未入库→补链接+版本；参数原厂未披露→挂验证任务（P-06）；原 PN 资料版本过旧→补最新版；应用约束不清→回头问客户并更新需求单版本</td></tr>
+        <tr><td class="b-id">1c</td><td>步骤 1：缺口补不了</td><td>留 UNKNOWN 进入评估（合法路径，不阻断）</td></tr>
+        <tr><td class="b-id">1d</td><td>任何读数点：查无记录（完全没有）</td><td>惰性触发派数据工单（一单一类可多条，模板统一，可多实例 D01/D02/…）：原 PN=硬阻塞·必须创建；候选 ≥2 可放弃【记录放弃原因】或创建（人判断）；候选 =1 必须创建。确认即入库（责任人留痕）→ 活动从断点续跑。事实/证据类查无（如 P-06）不可创建，挂验证任务</td></tr>
+        <tr><td class="b-id">2a</td><td>步骤 2：单位冲突</td><td>阻断，回步骤 1 补证</td></tr>
+        <tr><td class="b-id">2b</td><td>步骤 2：证据版本冲突</td><td>人工复核哪份资料为准</td></tr>
+        <tr><td class="b-id">3a</td><td>步骤 3：硬约束 MISMATCH</td><td>该候选直接「不推荐」（如候选 C 输入上限 32V &lt; 40V）</td></tr>
+        <tr><td class="b-id">4a</td><td>步骤 4：UNKNOWN 无去向</td><td>退回步骤 1~2 补证 / 挂验证任务</td></tr>
+        <tr><td class="b-id">4b</td><td>步骤 4：证据链不全</td><td>退回补齐证据回链（证据来源含数据工单创建记录：人工录入 · 工单号 · 确认人）</td></tr>
+        <tr><td class="b-id">5a</td><td>步骤 5：ACT-GATE-03 放行</td><td>P-11 落账（analysis_status=FAE确认），衔接下游</td></tr>
+        <tr><td class="b-id">5b</td><td>步骤 5：ACT-GATE-03 驳回</td><td>REWORK：回步骤 4 重审，或回步骤 1 重补输入</td></tr>
+        <tr><td class="b-id">6a</td><td>完结：至少一个推荐</td><td>交下游衔接（ACT-WORK-08 / SS03 / ACT-WORK-24）</td></tr>
+        <tr><td class="b-id">6b</td><td>完结：全是条件推荐</td><td>等验证闭环——通过→升级推荐；不过→降级不推荐</td></tr>
+        <tr><td class="b-id">6c</td><td>完结：全不推荐</td><td>重新检索替代料 / 继续用原 PN / 与客户协商放宽约束</td></tr>
+        <tr><td class="b-id">6d</td><td>完结：客户不批准</td><td>走独立审批流（customer_approval_status），不在本活动</td></tr>
+      </tbody>
+    </table>
+  </div>
+
+  <!-- 10. 页脚 -->
+  <div class="foot">
+    <span>口径与同目录工单及三份文档（活动流程与工单说明 / 一键启动入参说明 / 数据工单 note）一致；示例数据为演示占位。</span>
+    <span class="mono">ACT-WORK-05 · 差异评估 · 全流程分支图</span>
+  </div>
+
+</div>
+</body>
+</html>

docs/SS02-ACT-WORK-05-html/ACT-WORK-05-执行工单-01-评估输入与资料补齐确认.html

@@ -0,0 +1,296 @@
+<!doctype html>
+<html lang="zh-CN">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>执行工单 1 · 评估输入与资料补齐确认 · SS02 ACT-WORK-05 差异评估</title>
+<style>
+:root{
+  --ink:#1f2329; --ink-2:#41464e; --ink-3:#646a73; --ink-4:#8f959e;
+  --line:#dee0e3; --line-soft:#e8eaed; --soft:#f8f9fb;
+  --brand:#3370ff; --brand-deep:#245bdb; --brand-soft:#e1eaff; --brand-wash:#f0f4ff;
+  --human:#a9711e; --human-soft:#f6ecd8; --human-line:#e6d3a8;
+  --ok:#278717; --ok-soft:#e8f8e4; --danger:#d83931; --danger-soft:#feeae9;
+  --mono:"SF Mono",Menlo,Consolas,monospace;
+}
+*{box-sizing:border-box}
+html,body{margin:0;padding:0}
+body{font-family:Inter,ui-sans-serif,system-ui,-apple-system,BlinkMacSystemFont,"Segoe UI","PingFang SC","Microsoft YaHei",sans-serif;background:#eef1f6;color:var(--ink);font-size:14px;line-height:1.7;-webkit-font-smoothing:antialiased}
+.page{margin:0;padding:0}
+.card{background:#fff;overflow:hidden;border:0;border-radius:0;box-shadow:none}
+.card-head{display:flex;align-items:center;gap:14px;padding:18px 22px;border-bottom:2px solid var(--ink);background:linear-gradient(120deg,#fffaf1 0%,#fff 55%,#fbf6ea 100%)}
+.badge{flex:none;width:44px;height:44px;border-radius:10px;display:grid;place-items:center;background:var(--human);color:#fff;font-weight:800;font-size:13px;box-shadow:0 6px 16px rgba(169,113,30,.25)}
+.tit{flex:1;min-width:0}
+.tit .kick{font-size:11px;letter-spacing:.08em;color:var(--ink-4);font-weight:700}
+.tit h1{margin:2px 0 0;font-size:19px;font-weight:800;line-height:1.3}
+.tit .sub{font-size:12px;color:var(--ink-3);margin-top:3px}
+.side{display:flex;flex-direction:column;align-items:flex-end;gap:6px;flex:none}
+.tag{font-size:11px;font-weight:800;padding:2px 10px;border-radius:999px;color:var(--human);background:var(--human-soft);border:1px solid var(--human-line)}
+.step{font-size:12px;color:var(--ink-3)}
+.deadline{font-size:12px;color:var(--ink-3)}
+.deadline b{color:var(--danger)}
+.card-bd{padding:20px 22px}
+.zone{font-size:11px;font-weight:800;letter-spacing:.12em;color:var(--ink-4);margin:0 0 8px}
+.zone b{color:var(--ink-3)}
+.note{border:1px solid var(--line);border-left:3px solid var(--human);border-radius:8px;background:var(--soft);padding:14px 16px;margin-bottom:16px}
+.note p{margin:0;font-size:13px;color:var(--ink-2)}
+.note b{color:var(--ink)}
+.note .done{color:var(--ok);font-weight:700}
+.note .need{color:var(--human);font-weight:700}
+.jc-editgate{display:flex;align-items:center;gap:10px;flex-wrap:wrap;margin:14px 0 10px;padding:9px 12px;border-radius:9px;background:var(--soft);border:1px solid var(--line-soft);font-size:12px;color:var(--ink-3)}
+.jc-editgate-t{flex:1 1 auto;min-width:0}
+.jc-editgate-t b{color:var(--ink-2);font-weight:700}
+.jc-egbtn{flex:none;display:inline-flex;align-items:center;gap:5px;cursor:pointer;border:1px solid var(--line);border-radius:7px;padding:6px 13px;font:inherit;font-size:12px;font-weight:700;color:var(--ink-2);background:#fff;transition:border-color .16s,color .16s,background .16s}
+.jc-egbtn:hover{border-color:var(--brand);color:var(--brand)}
+.jc-egbtn.save{color:#fff;background:var(--human);border-color:var(--human)}
+.jc-egbtn.save:hover{filter:brightness(1.06);color:#fff}
+.jc-editgate .eg-cancel,.jc-editgate .eg-save{display:none}
+.jc-editgate.on{background:var(--human-soft);border-color:var(--human-line);color:#7c4a12}
+.jc-editgate.on .eg-open{display:none}
+.jc-editgate.on .eg-cancel,.jc-editgate.on .eg-save{display:inline-flex}
+.tbl-wrap{border:1px solid var(--line-soft);border-radius:10px;overflow:hidden}
+table{width:100%;border-collapse:collapse;font-size:12.5px}
+th{text-align:left;background:var(--soft);font-size:11px;letter-spacing:.03em;font-weight:800;color:var(--ink-3);padding:9px 10px;border-bottom:1px solid var(--line)}
+th.req::after{content:" ＊";color:var(--danger);font-size:11px}
+td{padding:8px 10px;border-bottom:1px solid var(--line-soft);vertical-align:middle}
+tr:last-child td{border-bottom:0}
+td.rn{position:relative;width:38px;white-space:nowrap;font-family:var(--mono);font-size:11px;color:var(--ink-4);text-align:center}
+.jc-vcell{display:block;font-size:12.5px;color:var(--ink);line-height:1.5;overflow-wrap:anywhere}
+.jc-vcell.mono{font-family:var(--mono);font-size:11.5px;color:var(--ink-2)}
+.jc-cell{display:none;width:100%;min-width:60px;border:1px solid var(--line);border-radius:6px;padding:6px 8px;font:inherit;font-size:12.5px;color:var(--ink);background:#fff}
+.jc-cell.mono{font-family:var(--mono);font-size:11.5px}
+.jc-cell:focus{border-color:var(--brand);box-shadow:0 0 0 3px var(--brand-wash);outline:none}
+table.on td>.jc-vcell{display:none}
+table.on td>.jc-cell{display:block}
+td.rn .jc-rowdel{display:none;width:22px;height:22px;margin:0 auto;cursor:pointer;border:1px solid var(--line);border-radius:6px;padding:0;font:inherit;font-size:14px;line-height:1;color:var(--ink-3);background:#fff}
+td.rn .jc-rowdel:hover{border-color:var(--danger);color:var(--danger);background:var(--danger-soft)}
+table.on td.rn .jc-rn-num{display:none}
+table.on td.rn .jc-rowdel{display:block}
+.jc-addrow{display:none;margin:8px 0 0;padding:8px 12px;border-radius:9px;background:var(--soft);border:1px dashed var(--line);font-size:12px;color:var(--ink-3)}
+.jc-addrow.show{display:flex;align-items:center;gap:8px}
+.jc-addrow button{cursor:pointer;border:1px solid var(--brand-soft);border-radius:7px;padding:5px 12px;font:inherit;font-size:12px;font-weight:700;color:var(--brand-deep);background:var(--brand-wash)}
+.jc-addrow button:hover{background:var(--brand-soft)}
+.jc-addrow em{font-style:normal;font-size:11.5px;color:var(--ink-4)}
+.flow{margin-top:16px;padding:9px 12px;border-radius:8px;background:var(--soft);border:1px dashed var(--line);font-size:12px;color:var(--ink-3)}
+.flow b{color:var(--ink)}
+.card-foot{padding:13px 22px;border-top:1px solid var(--line-soft);font-size:11.5px;color:var(--ink-4);display:flex;justify-content:space-between;flex-wrap:wrap;gap:8px}
+@media(max-width:600px){.card-head{flex-wrap:wrap}.side{align-items:flex-start}}
+/* 补充：评估输入清单状态标识（仅追加，不改动基件样式） */
+.mono{font-family:var(--mono);font-size:12px;color:var(--ink-2)}
+.st{display:inline-block;font-size:11px;font-weight:700;padding:1px 8px;border-radius:999px;border:1px solid transparent;white-space:nowrap}
+.st.bound{color:var(--ink-3);background:#eef1f6;border-color:var(--line)}
+.st.ok{color:var(--ok);background:var(--ok-soft);border-color:#c9ecc2}
+.st.miss{color:var(--human);background:var(--human-soft);border-color:var(--human-line)}
+.st.def{color:var(--brand-deep);background:var(--brand-wash);border-color:var(--brand-soft)}
+tr.ro td{background:var(--soft)}
+table.on td>.jc-vcell.ro{display:block}
+</style>
+</head>
+<body>
+<div class="page">
+<div class="card">
+
+  <header class="card-head">
+    <div class="badge">执行</div>
+    <div class="tit">
+      <div class="kick">SS02 · ACT-WORK-05 差异评估 · 执行工单 1/1</div>
+      <h1>评估输入与资料补齐确认</h1>
+      <div class="sub">收件人：<span data-slot="meta.task.owner">PW · 王工</span> · 关联任务：<span data-slot="meta.task.id">TASK-BT02-20260818-007</span></div>
+    </div>
+    <div class="side">
+      <span class="tag">执行工单</span>
+      <span class="step" data-slot="meta.phase">步骤 1/5 · 建立评估上下文</span>
+      <span class="deadline">最迟交回：<b data-slot="card.deadline">1 个工作日</b></span>
+    </div>
+  </header>
+
+  <div class="card-bd">
+
+    <p class="zone"><b>【做什么】</b>—— 启动 4 项已绑定，其余信息在工单里补齐</p>
+    <div class="note">
+      <p><span class="done">AI 已完成</span>：系统已按启动传入的 <b>4 项</b>完成绑定——客户 customer_id、客户需求 request_description（新建 P-01 · 版本 V1）、原 PN、候选 PN（数组，逐个评估）——并生成输入快照（input_snapshot_ref）。本轮评估对象：<b>LM2596S-5.0（TI）→ 3 个候选（XL2596S-5.0 / LM2596S-ADJ / 国产 DCDC）Pin-to-Pin 跨品牌替代</b>（BT-02 场景）。</p>
+      <p><span class="need">需要你补齐</span>：启动时未收的信息（应用场景、BOM 位——<b>不回表单，直接在下表补</b>）；系统已带出默认值（替代类型 Pin-to-Pin、规则版本 R-2026.07、负责人/期限），可确认可改。本单缺口只覆盖「<b>有而不全</b>」；「<b>完全没有</b>」（PN 不在库）由系统派数据工单创建整条记录，不在本单。datasheet 在数据工单里上传（选填），启动与本单都不收。点「编辑」在下表「补充内容」列填入；<b>加一行 = 补充 AI 未列出的资料项</b>，<b>删一行 = 该输入项不适用</b>。未补齐的缺口项将按 <b>UNKNOWN</b> 进入差异评估。</p>
+    </div>
+
+    <p class="zone"><b>【交回什么】</b>—— 评估输入清单（已绑定项只读核对，缺口项补齐，＊为必填）</p>
+
+    <div class="jc-editgate" id="editgate">
+      <span class="jc-editgate-t"><b data-slot="sd.input_gap_count">3 项资料存在缺口或待确认</b>（应用场景 / BOM 位 / 使能阈值），另有 3 项默认值已带出可改；「已绑定」行启动时冻结，不可改</span>
+      <button class="jc-egbtn eg-open" type="button">编辑</button>
+      <button class="jc-egbtn eg-cancel" type="button">取消</button>
+      <button class="jc-egbtn eg-save" type="button">保存</button>
+    </div>
+
+    <div class="tbl-wrap">
+      <table id="tbl">
+        <thead>
+          <tr>
+            <th style="width:38px">#</th>
+            <th data-h="输入项">输入项</th>
+            <th data-h="来源">来源</th>
+            <th data-h="状态">状态</th>
+            <th data-h="绑定值/缺口说明">绑定值 / 缺口说明</th>
+            <th class="req" data-h="补充内容">补充内容</th>
+          </tr>
+        </thead>
+        <tbody data-rows="in.evaluation_inputs">
+          <tr class="ro">
+            <td class="rn"><span class="jc-rn-num">1</span></td>
+            <td data-field="input_item"><span class="jc-vcell ro">客户 customer_id</span></td>
+            <td data-field="source_ledger"><span class="jc-vcell ro mono">L-02</span></td>
+            <td data-field="status"><span class="jc-vcell ro"><span class="st bound">已绑定</span></span></td>
+            <td data-field="detail"><span class="jc-vcell ro mono">CUS-2025-0007</span></td>
+            <td data-field="supplement"><span class="jc-vcell ro">—</span></td>
+          </tr>
+          <tr class="ro">
+            <td class="rn"><span class="jc-rn-num">2</span></td>
+            <td data-field="input_item"><span class="jc-vcell ro">客户需求 request_description</span></td>
+            <td data-field="source_ledger"><span class="jc-vcell ro mono">P-01</span></td>
+            <td data-field="status"><span class="jc-vcell ro"><span class="st bound">已绑定</span></span></td>
+            <td data-field="detail"><span class="jc-vcell ro">REQ-20260826-001 · V1（启动时新建：工业电源 12V→5V，替代 LM2596S-5.0）</span></td>
+            <td data-field="supplement"><span class="jc-vcell ro">—</span></td>
+          </tr>
+          <tr class="ro">
+            <td class="rn"><span class="jc-rn-num">3</span></td>
+            <td data-field="input_item"><span class="jc-vcell ro">原内部料号 original_internal_pn</span></td>
+            <td data-field="source_ledger"><span class="jc-vcell ro mono">P-08</span></td>
+            <td data-field="status"><span class="jc-vcell ro"><span class="st bound">已绑定</span></span></td>
+            <td data-field="detail"><span class="jc-vcell ro mono">LM2596S-5.0（TI）</span></td>
+            <td data-field="supplement"><span class="jc-vcell ro">—</span></td>
+          </tr>
+          <tr class="ro">
+            <td class="rn"><span class="jc-rn-num">4</span></td>
+            <td data-field="input_item"><span class="jc-vcell ro">候选内部料号 ① candidate_internal_pn[]</span></td>
+            <td data-field="source_ledger"><span class="jc-vcell ro mono">P-08</span></td>
+            <td data-field="status"><span class="jc-vcell ro"><span class="st bound">已绑定</span></span></td>
+            <td data-field="detail"><span class="jc-vcell ro mono">XL2596S-5.0（XLSEMI）</span></td>
+            <td data-field="supplement"><span class="jc-vcell ro">—</span></td>
+          </tr>
+          <tr class="ro">
+            <td class="rn"><span class="jc-rn-num">5</span></td>
+            <td data-field="input_item"><span class="jc-vcell ro">候选内部料号 ② candidate_internal_pn[]</span></td>
+            <td data-field="source_ledger"><span class="jc-vcell ro mono">P-08</span></td>
+            <td data-field="status"><span class="jc-vcell ro"><span class="st bound">已绑定</span></span></td>
+            <td data-field="detail"><span class="jc-vcell ro mono">LM2596S-ADJ（TI 同族可调版）</span></td>
+            <td data-field="supplement"><span class="jc-vcell ro">—</span></td>
+          </tr>
+          <tr class="ro">
+            <td class="rn"><span class="jc-rn-num">6</span></td>
+            <td data-field="input_item"><span class="jc-vcell ro">候选内部料号 ③ candidate_internal_pn[]</span></td>
+            <td data-field="source_ledger"><span class="jc-vcell ro mono">P-08</span></td>
+            <td data-field="status"><span class="jc-vcell ro"><span class="st bound">已绑定</span></span></td>
+            <td data-field="detail"><span class="jc-vcell ro">国产 DCDC（32V 输入上限 · 占位型号）</span></td>
+            <td data-field="supplement"><span class="jc-vcell ro">—</span></td>
+          </tr>
+          <tr>
+            <td class="rn"><span class="jc-rn-num">7</span><button class="jc-rowdel" type="button" title="删除此行">×</button></td>
+            <td data-field="input_item"><span class="jc-vcell">应用场景 application_scenario</span><input class="jc-cell" value="应用场景 application_scenario"></td>
+            <td data-field="source_ledger"><span class="jc-vcell mono">P-01</span><input class="jc-cell mono" value="P-01"></td>
+            <td data-field="status"><span class="jc-vcell ro"><span class="st miss">待补＊</span></span></td>
+            <td data-field="detail"><span class="jc-vcell">启动时未收，需向客户确认</span><input class="jc-cell" value="启动时未收，需向客户确认"></td>
+            <td data-field="supplement"><span class="jc-vcell">12V→5V、工业温域、40V 输入上限（示例已补）</span><input class="jc-cell" value="12V→5V、工业温域、40V 输入上限（示例已补）"></td>
+          </tr>
+          <tr>
+            <td class="rn"><span class="jc-rn-num">8</span><button class="jc-rowdel" type="button" title="删除此行">×</button></td>
+            <td data-field="input_item"><span class="jc-vcell">BOM 位 bom_position</span><input class="jc-cell" value="BOM 位 bom_position"></td>
+            <td data-field="source_ledger"><span class="jc-vcell mono">P-09</span><input class="jc-cell mono" value="P-09"></td>
+            <td data-field="status"><span class="jc-vcell ro"><span class="st miss">待补＊</span></span></td>
+            <td data-field="detail"><span class="jc-vcell">启动时未收</span><input class="jc-cell" value="启动时未收"></td>
+            <td data-field="supplement"><span class="jc-vcell">U3 电源位（示例已补）</span><input class="jc-cell" value="U3 电源位（示例已补）"></td>
+          </tr>
+          <tr>
+            <td class="rn"><span class="jc-rn-num">9</span><button class="jc-rowdel" type="button" title="删除此行">×</button></td>
+            <td data-field="input_item"><span class="jc-vcell">替代类型 substitution_type</span><input class="jc-cell" value="替代类型 substitution_type"></td>
+            <td data-field="source_ledger"><span class="jc-vcell">—</span><input class="jc-cell" value="—"></td>
+            <td data-field="status"><span class="jc-vcell ro"><span class="st def">默认·可改</span></span></td>
+            <td data-field="detail"><span class="jc-vcell">默认 Pin-to-Pin</span><input class="jc-cell" value="默认 Pin-to-Pin"></td>
+            <td data-field="supplement"><span class="jc-vcell">—</span><input class="jc-cell" value="—"></td>
+          </tr>
+          <tr>
+            <td class="rn"><span class="jc-rn-num">10</span><button class="jc-rowdel" type="button" title="删除此行">×</button></td>
+            <td data-field="input_item"><span class="jc-vcell">规则版本 rule_version</span><input class="jc-cell" value="规则版本 rule_version"></td>
+            <td data-field="source_ledger"><span class="jc-vcell mono">GOV</span><input class="jc-cell mono" value="GOV"></td>
+            <td data-field="status"><span class="jc-vcell ro"><span class="st def">默认·可改</span></span></td>
+            <td data-field="detail"><span class="jc-vcell mono">默认当前发布版 R-2026.07（as_of 锁定，随结论落账）</span><input class="jc-cell mono" value="默认当前发布版 R-2026.07（as_of 锁定，随结论落账）"></td>
+            <td data-field="supplement"><span class="jc-vcell">—</span><input class="jc-cell" value="—"></td>
+          </tr>
+          <tr>
+            <td class="rn"><span class="jc-rn-num">11</span><button class="jc-rowdel" type="button" title="删除此行">×</button></td>
+            <td data-field="input_item"><span class="jc-vcell">负责人 / 期限 owner · deadline</span><input class="jc-cell" value="负责人 / 期限 owner · deadline"></td>
+            <td data-field="source_ledger"><span class="jc-vcell">—</span><input class="jc-cell" value="—"></td>
+            <td data-field="status"><span class="jc-vcell ro"><span class="st def">默认·可改</span></span></td>
+            <td data-field="detail"><span class="jc-vcell">PW · 王工 / 审核 FAE · 李工 · 1 个工作日（按客户线默认）</span><input class="jc-cell" value="PW · 王工 / 审核 FAE · 李工 · 1 个工作日（按客户线默认）"></td>
+            <td data-field="supplement"><span class="jc-vcell">—</span><input class="jc-cell" value="—"></td>
+          </tr>
+          <tr>
+            <td class="rn"><span class="jc-rn-num">12</span><button class="jc-rowdel" type="button" title="删除此行">×</button></td>
+            <td data-field="input_item"><span class="jc-vcell">候选 PN 使能阈值</span><input class="jc-cell" value="候选 PN 使能阈值"></td>
+            <td data-field="source_ledger"><span class="jc-vcell mono">P-08</span><input class="jc-cell mono" value="P-08"></td>
+            <td data-field="status"><span class="jc-vcell ro"><span class="st miss">待确认·需补</span></span></td>
+            <td data-field="detail"><span class="jc-vcell">原厂未披露（有而不全）</span><input class="jc-cell" value="原厂未披露（有而不全）"></td>
+            <td data-field="supplement"><span class="jc-vcell mono">关联验证任务 VAL-2026-0188</span><input class="jc-cell mono" value="关联验证任务 VAL-2026-0188"></td>
+          </tr>
+          <tr>
+            <td class="rn"><span class="jc-rn-num">13</span><button class="jc-rowdel" type="button" title="删除此行">×</button></td>
+            <td data-field="input_item"><span class="jc-vcell">原 PN 资料版本</span><input class="jc-cell" value="原 PN 资料版本"></td>
+            <td data-field="source_ledger"><span class="jc-vcell mono">P-10</span><input class="jc-cell mono" value="P-10"></td>
+            <td data-field="status"><span class="jc-vcell ro"><span class="st ok">齐备</span></span></td>
+            <td data-field="detail"><span class="jc-vcell">Rev H（2023-09）已核验</span><input class="jc-cell" value="Rev H（2023-09）已核验"></td>
+            <td data-field="supplement"><span class="jc-vcell">—</span><input class="jc-cell" value="—"></td>
+          </tr>
+          <tr>
+            <td class="rn"><span class="jc-rn-num">14</span><button class="jc-rowdel" type="button" title="删除此行">×</button></td>
+            <td data-field="input_item"><span class="jc-vcell">外部来源清单</span><input class="jc-cell" value="外部来源清单"></td>
+            <td data-field="source_ledger"><span class="jc-vcell mono">EXT-02</span><input class="jc-cell mono" value="EXT-02"></td>
+            <td data-field="status"><span class="jc-vcell ro"><span class="st ok">齐备</span></span></td>
+            <td data-field="detail"><span class="jc-vcell">—</span><input class="jc-cell" value="—"></td>
+            <td data-field="supplement"><span class="jc-vcell">—</span><input class="jc-cell" value="—"></td>
+          </tr>
+        </tbody>
+      </table>
+    </div>
+
+    <div class="jc-addrow" id="addrow">
+      <button type="button">＋ 加一行（补充资料项）</button>
+      <em>新加行的「补充内容」为必填；「绑定值 / 缺口说明」栏写清这项资料是什么、AI 为什么拿不到</em>
+    </div>
+
+    <div class="flow"><b>审批 / 提交：</b>本工单只承载内容；「提交」请在对话区的【执行卡】中进行。<b>提交后去向：</b>补齐后进入步骤 2 · AI 读取与标准化，仍缺失的项将按 UNKNOWN 进入差异评估。<b>注意：</b>启动参数如有误，需退回触发方修订后重新触发，本单不可改。</div>
+
+  </div>
+
+  <footer class="card-foot">
+    <span>SS02 · ACT-WORK-05 差异评估 · 执行工单 1/1 · 评估输入与资料补齐确认</span>
+    <span style="font-family:'SF Mono',Menlo,Consolas,monospace">工单类型：执行 · <span data-slot="card.id">WO-ACT-WORK-05-01</span></span>
+  </footer>
+
+</div>
+</div>
+
+<script>
+(function(){
+  var gate = document.getElementById('editgate');
+  var tbl = document.getElementById('tbl');
+  var addrow = document.getElementById('addrow');
+  var tbody = tbl.querySelector('tbody');
+  function setEdit(on){ gate.classList.toggle('on',on); tbl.classList.toggle('on',on); addrow.classList.toggle('show',on); }
+  gate.querySelector('.eg-open').addEventListener('click', function(){ setEdit(true); });
+  gate.querySelector('.eg-cancel').addEventListener('click', function(){
+    tbody.querySelectorAll('tr').forEach(function(tr){ tr.querySelectorAll('td').forEach(function(td){ var v=td.querySelector('.jc-vcell'),c=td.querySelector('.jc-cell'); if(v&&c){c.value=v.textContent;} }); });
+    setEdit(false);
+  });
+  gate.querySelector('.eg-save').addEventListener('click', function(){
+    tbody.querySelectorAll('tr').forEach(function(tr){ tr.querySelectorAll('td').forEach(function(td){ var v=td.querySelector('.jc-vcell'),c=td.querySelector('.jc-cell'); if(v&&c){v.textContent=c.value;} }); });
+    renumber(); setEdit(false);
+  });
+  addrow.querySelector('button').addEventListener('click', function(){
+    var tr=document.createElement('tr');
+    tr.innerHTML='<td class="rn"><span class="jc-rn-num"></span><button class="jc-rowdel" type="button" title="删除此行">×</button></td>'+'<td><span class="jc-vcell"></span><input class="jc-cell" placeholder="输入项"></td>'+'<td><span class="jc-vcell mono"></span><input class="jc-cell mono" placeholder="来源"></td>'+'<td><span class="jc-vcell ro"><span class="st miss">新增·待补</span></span></td>'+'<td><span class="jc-vcell"></span><input class="jc-cell" placeholder="资料说明 / AI 为什么拿不到"></td>'+'<td><span class="jc-vcell"></span><input class="jc-cell" placeholder="补充内容（必填）"></td>';
+    tbody.appendChild(tr); renumber();
+  });
+  tbody.addEventListener('click', function(e){ if(e.target.classList.contains('jc-rowdel')){ e.target.closest('tr').remove(); renumber(); } });
+  function renumber(){ tbody.querySelectorAll('tr').forEach(function(tr,i){ tr.querySelector('.jc-rn-num').textContent=i+1; }); }
+})();
+</script>
+</body>
+</html>

docs/SS02-ACT-WORK-05-html/ACT-WORK-05-数据工单-01-芯片主数据创建.html

@@ -0,0 +1,341 @@
+<!doctype html>
+<html lang="zh-CN">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>数据工单 1 · 芯片主数据创建（P-08）· SS02 ACT-WORK-05 差异评估</title>
+<style>
+:root{
+  --ink:#1f2329; --ink-2:#41464e; --ink-3:#646a73; --ink-4:#8f959e;
+  --line:#dee0e3; --line-soft:#e8eaed; --soft:#f8f9fb;
+  --brand:#3370ff; --brand-deep:#245bdb; --brand-soft:#e1eaff; --brand-wash:#f0f4ff;
+  --data:#3370ff; --data-soft:#e1eaff; --data-line:#c3d6ff;
+  --ok:#278717; --ok-soft:#e8f8e4; --danger:#d83931; --danger-soft:#feeae9;
+  --mono:"SF Mono",Menlo,Consolas,monospace;
+}
+*{box-sizing:border-box}
+html,body{margin:0;padding:0}
+body{font-family:Inter,ui-sans-serif,system-ui,-apple-system,BlinkMacSystemFont,"Segoe UI","PingFang SC","Microsoft YaHei",sans-serif;background:#eef1f6;color:var(--ink);font-size:14px;line-height:1.7;-webkit-font-smoothing:antialiased}
+.page{margin:0;padding:0}
+.card{background:#fff;overflow:hidden;border:0;border-radius:0;box-shadow:none}
+.card-head{display:flex;align-items:center;gap:14px;padding:18px 22px;border-bottom:2px solid var(--ink);background:linear-gradient(120deg,#f0f5ff 0%,#fff 55%,#eef4ff 100%)}
+.badge{flex:none;width:44px;height:44px;border-radius:10px;display:grid;place-items:center;background:var(--data);color:#fff;font-weight:800;font-size:13px;box-shadow:0 6px 16px rgba(51,112,255,.25)}
+.tit{flex:1;min-width:0}
+.tit .kick{font-size:11px;letter-spacing:.08em;color:var(--ink-4);font-weight:700}
+.tit h1{margin:2px 0 0;font-size:19px;font-weight:800;line-height:1.3}
+.tit .sub{font-size:12px;color:var(--ink-3);margin-top:3px}
+.side{display:flex;flex-direction:column;align-items:flex-end;gap:6px;flex:none}
+.tag{font-size:11px;font-weight:800;padding:2px 10px;border-radius:999px;color:var(--data);background:var(--data-soft);border:1px solid var(--data-line)}
+.step{font-size:12px;color:var(--ink-3)}
+.deadline{font-size:12px;color:var(--ink-3)}
+.deadline b{color:var(--danger)}
+.card-bd{padding:20px 22px}
+.zone{font-size:11px;font-weight:800;letter-spacing:.12em;color:var(--ink-4);margin:0 0 8px}
+.zone b{color:var(--ink-3)}
+.note{border:1px solid var(--line);border-left:3px solid var(--data);border-radius:8px;background:var(--soft);padding:14px 16px;margin-bottom:16px}
+.note p{margin:0 0 6px;font-size:13px;color:var(--ink-2)}
+.note p:last-child{margin-bottom:0}
+.note b{color:var(--ink)}
+.note .done{color:var(--ok);font-weight:700}
+.note .need{color:var(--data);font-weight:700}
+.jc-editgate{display:flex;align-items:center;gap:10px;flex-wrap:wrap;margin:14px 0 10px;padding:9px 12px;border-radius:9px;background:var(--soft);border:1px solid var(--line-soft);font-size:12px;color:var(--ink-3)}
+.jc-editgate-t{flex:1 1 auto;min-width:0}
+.jc-editgate-t b{color:var(--ink-2);font-weight:700}
+.jc-egbtn{flex:none;display:inline-flex;align-items:center;gap:5px;cursor:pointer;border:1px solid var(--line);border-radius:7px;padding:6px 13px;font:inherit;font-size:12px;font-weight:700;color:var(--ink-2);background:#fff;transition:border-color .16s,color .16s,background .16s}
+.jc-egbtn:hover{border-color:var(--brand);color:var(--brand)}
+.jc-egbtn.save{color:#fff;background:var(--data);border-color:var(--data)}
+.jc-egbtn.save:hover{filter:brightness(1.06);color:#fff}
+.jc-editgate .eg-cancel,.jc-editgate .eg-save{display:none}
+.jc-editgate.on{background:var(--brand-wash);border-color:var(--data-line);color:#1e40af}
+.jc-editgate.on .eg-open{display:none}
+.jc-editgate.on .eg-cancel,.jc-editgate.on .eg-save{display:inline-flex}
+.tbl-wrap{border:1px solid var(--line-soft);border-radius:10px;overflow:hidden}
+table{width:100%;border-collapse:collapse;font-size:12.5px}
+th{text-align:left;background:var(--soft);font-size:11px;letter-spacing:.03em;font-weight:800;color:var(--ink-3);padding:9px 10px;border-bottom:1px solid var(--line)}
+th.req::after{content:" ＊";color:var(--danger);font-size:11px}
+td{padding:8px 10px;border-bottom:1px solid var(--line-soft);vertical-align:middle}
+tr:last-child td{border-bottom:0}
+td.rn{position:relative;width:38px;white-space:nowrap;font-family:var(--mono);font-size:11px;color:var(--ink-4);text-align:center}
+.jc-vcell{display:block;font-size:12.5px;color:var(--ink);line-height:1.5;overflow-wrap:anywhere}
+.jc-vcell.mono{font-family:var(--mono);font-size:11.5px;color:var(--ink-2)}
+.jc-cell{display:none;width:100%;min-width:60px;border:1px solid var(--line);border-radius:6px;padding:6px 8px;font:inherit;font-size:12.5px;color:var(--ink);background:#fff}
+.jc-cell.mono{font-family:var(--mono);font-size:11.5px}
+.jc-cell:focus{border-color:var(--brand);box-shadow:0 0 0 3px var(--brand-wash);outline:none}
+table.on td>.jc-vcell{display:none}
+table.on td>.jc-cell{display:block}
+td.rn .jc-rowdel{display:none;width:22px;height:22px;margin:0 auto;cursor:pointer;border:1px solid var(--line);border-radius:6px;padding:0;font:inherit;font-size:14px;line-height:1;color:var(--ink-3);background:#fff}
+td.rn .jc-rowdel:hover{border-color:var(--danger);color:var(--danger);background:var(--danger-soft)}
+table.on td.rn .jc-rn-num{display:none}
+table.on td.rn .jc-rowdel{display:block}
+.jc-addrow{display:none;margin:8px 0 0;padding:8px 12px;border-radius:9px;background:var(--soft);border:1px dashed var(--line);font-size:12px;color:var(--ink-3)}
+.jc-addrow.show{display:flex;align-items:center;gap:8px}
+.jc-addrow button{cursor:pointer;border:1px solid var(--brand-soft);border-radius:7px;padding:5px 12px;font:inherit;font-size:12px;font-weight:700;color:var(--brand-deep);background:var(--brand-wash)}
+.jc-addrow button:hover{background:var(--brand-soft)}
+.jc-addrow em{font-style:normal;font-size:11.5px;color:var(--ink-4)}
+.flow{margin-top:16px;padding:9px 12px;border-radius:8px;background:var(--soft);border:1px dashed var(--line);font-size:12px;color:var(--ink-3)}
+.flow b{color:var(--ink)}
+.card-foot{padding:13px 22px;border-top:1px solid var(--line-soft);font-size:11.5px;color:var(--ink-4);display:flex;justify-content:space-between;flex-wrap:wrap;gap:8px}
+@media(max-width:600px){.card-head{flex-wrap:wrap}.side{align-items:flex-start}}
+/* 补充：数据工单专用标识（仅追加，不改动基件样式） */
+.mono{font-family:var(--mono);font-size:12px;color:var(--ink-2)}
+.pre{font-style:normal;font-size:10.5px;font-weight:800;color:var(--data);background:var(--data-soft);border:1px solid var(--data-line);border-radius:999px;padding:0 7px;margin-left:6px;white-space:nowrap}
+table.on td>.pre{display:none}
+.ct{display:inline-block;font-size:11px;font-weight:700;padding:1px 8px;border-radius:999px;border:1px solid transparent;white-space:nowrap}
+.ct.hard{color:var(--danger);background:var(--danger-soft);border-color:#f3b9b5}
+.ct.soft{color:var(--ink-3);background:#eef1f6;border-color:var(--line)}
+.tbl-gap{margin-top:18px}
+</style>
+<style>
+/* ===== 视觉补充段 v3（通用批量模板：字段即表头、每行一条；不改基件样式与 JS 钩子） ===== */
+.hic{flex:none;width:26px;height:26px;color:var(--data)}
+.zic{width:14px;height:14px;color:var(--ink-3);vertical-align:-2px;margin-right:3px}
+/* 表头内字段说明（第二行小字） */
+.thd{display:block;font-size:10px;font-weight:600;color:var(--ink-4);letter-spacing:0;margin-top:1px;line-height:1.4}
+/* 表 1：字段即表头，内容多列，允许横向滚动 */
+#tbl1{min-width:1240px}
+#tbl1 .jc-vcell{display:inline}
+/* 表 2 列宽 */
+#tbl2 th:nth-child(2){width:150px}
+#tbl2 th:nth-child(3){width:18%}
+#tbl2 th:nth-child(4){width:14%}
+#tbl2 th:nth-child(5){width:8%;text-align:center;white-space:nowrap}
+#tbl2 th:nth-child(6){width:13%;text-align:center;white-space:nowrap}
+#tbl2 td:nth-child(5),#tbl2 td:nth-child(6){text-align:center;white-space:nowrap}
+/* 说明列（只读注释，编辑态保持可见） */
+.desc{color:var(--ink-3);font-size:12px;line-height:1.5}
+table.on td>.jc-vcell.ro{display:block}
+.tbl-wrap{overflow-x:auto}
+@media (prefers-reduced-motion: reduce){*{animation:none!important;transition:none!important}}
+</style>
+</head>
+<body>
+<div class="page">
+<div class="card">
+
+  <header class="card-head">
+    <div class="badge">数据</div>
+    <svg class="hic" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><ellipse cx="10" cy="5" rx="7" ry="3"/><path d="M3 5v14c0 1.66 3.13 3 7 3 1.13 0 2.21-.09 3.2-.26"/><path d="M3 12c0 1.66 3.13 3 7 3 1.13 0 2.21-.09 3.2-.26"/><circle cx="18" cy="18" r="4.2"/><path d="M18 15.8v4.4M15.8 18h4.4"/></svg>
+    <div class="tit">
+      <div class="kick">SS02 · ACT-WORK-05 差异评估 · 数据工单 1/1</div>
+      <h1>芯片主数据创建（P-08）</h1>
+      <div class="sub">收件人：<span data-slot="meta.task.owner">PW · 王工</span> · 关联任务：<span data-slot="meta.task.id">TASK-BT02-20260818-007</span></div>
+    </div>
+    <div class="side">
+      <span class="tag">数据工单</span>
+      <span class="step" data-slot="meta.phase">等待数据 · 步骤 0.5/5</span>
+      <span class="deadline">最迟交回：<b data-slot="card.deadline">1 个工作日</b></span>
+    </div>
+  </header>
+
+  <div class="card-bd">
+
+    <p class="zone"><svg class="zic" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><rect x="8" y="2" width="8" height="4" rx="1"/><path d="M16 4h2a2 2 0 0 1 2 2v14a2 2 0 0 1-2 2H6a2 2 0 0 1-2-2V6a2 2 0 0 1 2-2h2"/><path d="M9 12h6M9 16h4"/></svg><b>【做什么】</b>—— 批量创建 P-08 主数据记录</p>
+    <div class="note">
+      <p><span class="need">模板定位</span>：本单是「数据工单」统一模板的实例——<b>一单一类（可多条）</b>：目标台账=<b data-slot="meta.data.target_ledger">P-08</b>、本批创建=<b data-slot="meta.data.target_key">XL2596S-5.0（1 条，可加行增建）</b>；<b>字段即表头、每行一条新记录</b>。同一活动每次读数缺数据都可能再派发新实例（D02、D03…），模板与规则完全相同。</p>
+      <p><span class="need">触发原因</span>：系统按 internal_pn 查 P-08 <b>无「XL2596S-5.0」记录</b>——是「完全没有」，不是字段缺失。本单为<b>系统判断派发</b>的数据创建工单（与执行工单的「有而不全」严格区分，互不嵌套）。</p>
+      <p><span class="done">AI 预填</span>：本单已上传 datasheet（选填），AI 已预填 <b data-slot="sd.prefill_count">1 条记录 · 8 项字段 + 7 行参数</b>（标「预填」），请核对并补齐空缺；若本单未上传 datasheet，则全部手填，同为合法路径。</p>
+      <p><span class="need">纪律</span>：<b>确认即正式入库</b>（无草稿、无审核），确认人 = 数据责任人并留痕；只建主数据 / 资料，事实与证据记录（如验证记录）须实测产生；在对话区【数据卡】确认后，活动自动从「等待数据」唤醒进入步骤 1，本单不复用。</p>
+    </div>
+
+    <p class="zone"><svg class="zic" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><rect x="3" y="4" width="18" height="16" rx="2"/><path d="M3 10h18M9 10v10"/></svg><b>【创建什么 · 表 1】</b>—— 主数据记录（每行一条，＊为必填列）</p>
+
+    <div class="jc-editgate" id="gate1">
+      <span class="jc-editgate-t"><b>每行一条新记录</b>，点「编辑」核对预填、补齐空缺；「＋ 加一行」= 再建一条；必填列（＊）全齐才允许确认</span>
+      <button class="jc-egbtn eg-open" type="button">编辑</button>
+      <button class="jc-egbtn eg-cancel" type="button">取消</button>
+      <button class="jc-egbtn eg-save" type="button">保存</button>
+    </div>
+
+    <div class="tbl-wrap">
+      <table id="tbl1">
+        <thead>
+          <tr>
+            <th style="width:38px">#</th>
+            <th class="req" data-h="内部料号">内部料号 internal_pn<span class="thd">全链路统一基准，不可自由文本</span></th>
+            <th class="req" data-h="品牌名称">品牌 brand_name<span class="thd">与制造商、供应商分开</span></th>
+            <th data-h="制造商名称">制造商 manufacturer_name<span class="thd">与品牌不一致时分开记录</span></th>
+            <th class="req" data-h="规格描述">规格描述 specification_description<span class="thd">按原厂资料口径</span></th>
+            <th class="req" data-h="封装">封装 package<span class="thd">影响硬约束比对</span></th>
+            <th data-h="工艺">工艺 process_technology<span class="thd">硬约束比较项</span></th>
+            <th class="req" data-h="生命周期状态">生命周期 lifecycle_status<span class="thd">Active/NRND/EOL/停产/风险</span></th>
+            <th data-h="EOL/PCN状态">EOL/PCN eol_pcn_status<span class="thd">条件必填：通知/影响/生效时间</span></th>
+            <th data-h="Datasheet引用+版本">Datasheet 引用+版本<span class="thd">成对条件：有引用必填版本</span></th>
+            <th data-h="适配应用场景">适配场景 application_scenarios<span class="thd">判断实际适用性</span></th>
+          </tr>
+        </thead>
+        <tbody data-rows="in.create_p08_fields">
+          <tr>
+            <td class="rn"><span class="jc-rn-num">1</span><button class="jc-rowdel" type="button" title="删除此行">×</button></td>
+            <td data-field="internal_pn"><span class="jc-vcell mono">XL2596S-5.0</span><em class="pre">预填</em><input class="jc-cell mono" value="XL2596S-5.0"></td>
+            <td data-field="brand_name"><span class="jc-vcell">XLSEMI</span><em class="pre">预填</em><input class="jc-cell" value="XLSEMI"></td>
+            <td data-field="manufacturer_name"><span class="jc-vcell">XLSEMI</span><em class="pre">预填</em><input class="jc-cell" value="XLSEMI"></td>
+            <td data-field="specification_description"><span class="jc-vcell">降压型 DCDC 稳压器，3A，固定 5.0V，150kHz</span><em class="pre">预填</em><input class="jc-cell" value="降压型 DCDC 稳压器，3A，固定 5.0V，150kHz"></td>
+            <td data-field="package"><span class="jc-vcell mono">TO-263-5</span><em class="pre">预填</em><input class="jc-cell mono" value="TO-263-5"></td>
+            <td data-field="process_technology"><span class="jc-vcell">BCD</span><em class="pre">预填</em><input class="jc-cell" value="BCD"></td>
+            <td data-field="lifecycle_status"><span class="jc-vcell">Active</span><em class="pre">预填</em><input class="jc-cell" value="Active"></td>
+            <td data-field="eol_pcn_status"><span class="jc-vcell">—</span><input class="jc-cell" value="—"></td>
+            <td data-field="datasheet_ref"><span class="jc-vcell mono">xlsemi.com/datasheet/XL2596S-5.0.pdf · Rev C</span><em class="pre">预填</em><input class="jc-cell mono" value="xlsemi.com/datasheet/XL2596S-5.0.pdf · Rev C"></td>
+            <td data-field="application_scenarios"><span class="jc-vcell">工业电源；消费电源</span><input class="jc-cell" value="工业电源；消费电源"></td>
+          </tr>
+        </tbody>
+      </table>
+    </div>
+
+    <div class="jc-addrow" id="addrow1">
+      <button type="button">＋ 加一行（再建一条记录）</button>
+      <em>新行的必填列（＊）全部填写后才允许确认；删一行 = 该记录不建</em>
+    </div>
+
+    <p class="zone tbl-gap"><svg class="zic" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M4 21v-7M4 10V3M12 21v-9M12 8V3M20 21v-5M20 12V3"/><path d="M1 14h6M9 8h6M17 16h6"/></svg><b>【创建什么 · 表 2】</b>—— 标准化参数集 normalized_parameter_set（每行一个参数，按所属料号归属，＊必填）</p>
+
+    <div class="jc-editgate" id="gate2">
+      <span class="jc-editgate-t"><b>AI 已预填 7 行参数</b>（全部归属 XL2596S-5.0），点「编辑」核对修正；「＋ 加一行」补充未列出的参数</span>
+      <button class="jc-egbtn eg-open" type="button">编辑</button>
+      <button class="jc-egbtn eg-cancel" type="button">取消</button>
+      <button class="jc-egbtn eg-save" type="button">保存</button>
+    </div>
+
+    <div class="tbl-wrap">
+      <table id="tbl2">
+        <thead>
+          <tr>
+            <th style="width:38px">#</th>
+            <th class="req" data-h="所属料号">所属料号 internal_pn<span class="thd">归属表 1 哪条记录</span></th>
+            <th class="req" data-h="参数名">参数名</th>
+            <th class="req" data-h="值">值</th>
+            <th data-h="单位">单位</th>
+            <th class="req" data-h="约束类型">约束（硬/软）</th>
+            <th data-h="说明">说明</th>
+          </tr>
+        </thead>
+        <tbody data-rows="in.create_p08_params">
+          <tr>
+            <td class="rn"><span class="jc-rn-num">1</span><button class="jc-rowdel" type="button" title="删除此行">×</button></td>
+            <td data-field="internal_pn"><span class="jc-vcell mono">XL2596S-5.0</span><em class="pre">预填</em><input class="jc-cell mono" value="XL2596S-5.0"></td>
+            <td data-field="param"><span class="jc-vcell">输入电压范围</span><input class="jc-cell" value="输入电压范围"></td>
+            <td data-field="value"><span class="jc-vcell mono">4.5~40</span><input class="jc-cell mono" value="4.5~40"></td>
+            <td data-field="unit"><span class="jc-vcell">V</span><input class="jc-cell" value="V"></td>
+            <td data-field="constraint"><span class="jc-vcell"><span class="ct hard">硬约束</span></span><input class="jc-cell" value="硬约束"></td>
+            <td data-field="desc" class="desc"><span class="jc-vcell ro">必须覆盖客户输入（本例上限 40V）</span></td>
+          </tr>
+          <tr>
+            <td class="rn"><span class="jc-rn-num">2</span><button class="jc-rowdel" type="button" title="删除此行">×</button></td>
+            <td data-field="internal_pn"><span class="jc-vcell mono">XL2596S-5.0</span><em class="pre">预填</em><input class="jc-cell mono" value="XL2596S-5.0"></td>
+            <td data-field="param"><span class="jc-vcell">输出电压</span><input class="jc-cell" value="输出电压"></td>
+            <td data-field="value"><span class="jc-vcell mono">5.0（固定）</span><input class="jc-cell mono" value="5.0（固定）"></td>
+            <td data-field="unit"><span class="jc-vcell">V</span><input class="jc-cell" value="V"></td>
+            <td data-field="constraint"><span class="jc-vcell"><span class="ct hard">硬约束</span></span><input class="jc-cell" value="硬约束"></td>
+            <td data-field="desc" class="desc"><span class="jc-vcell ro">固定版 vs 可调版是硬差异点</span></td>
+          </tr>
+          <tr>
+            <td class="rn"><span class="jc-rn-num">3</span><button class="jc-rowdel" type="button" title="删除此行">×</button></td>
+            <td data-field="internal_pn"><span class="jc-vcell mono">XL2596S-5.0</span><em class="pre">预填</em><input class="jc-cell mono" value="XL2596S-5.0"></td>
+            <td data-field="param"><span class="jc-vcell">输出电流</span><input class="jc-cell" value="输出电流"></td>
+            <td data-field="value"><span class="jc-vcell mono">3</span><input class="jc-cell mono" value="3"></td>
+            <td data-field="unit"><span class="jc-vcell">A</span><input class="jc-cell" value="A"></td>
+            <td data-field="constraint"><span class="jc-vcell"><span class="ct hard">硬约束</span></span><input class="jc-cell" value="硬约束"></td>
+            <td data-field="desc" class="desc"><span class="jc-vcell ro">满载能力，须 ≥ 设计电流</span></td>
+          </tr>
+          <tr>
+            <td class="rn"><span class="jc-rn-num">4</span><button class="jc-rowdel" type="button" title="删除此行">×</button></td>
+            <td data-field="internal_pn"><span class="jc-vcell mono">XL2596S-5.0</span><em class="pre">预填</em><input class="jc-cell mono" value="XL2596S-5.0"></td>
+            <td data-field="param"><span class="jc-vcell">开关频率</span><input class="jc-cell" value="开关频率"></td>
+            <td data-field="value"><span class="jc-vcell mono">150</span><input class="jc-cell mono" value="150"></td>
+            <td data-field="unit"><span class="jc-vcell">kHz</span><input class="jc-cell" value="kHz"></td>
+            <td data-field="constraint"><span class="jc-vcell"><span class="ct soft">软约束</span></span><input class="jc-cell" value="软约束"></td>
+            <td data-field="desc" class="desc"><span class="jc-vcell ro">影响外围电感 / 电容选型</span></td>
+          </tr>
+          <tr>
+            <td class="rn"><span class="jc-rn-num">5</span><button class="jc-rowdel" type="button" title="删除此行">×</button></td>
+            <td data-field="internal_pn"><span class="jc-vcell mono">XL2596S-5.0</span><em class="pre">预填</em><input class="jc-cell mono" value="XL2596S-5.0"></td>
+            <td data-field="param"><span class="jc-vcell">静态电流</span><input class="jc-cell" value="静态电流"></td>
+            <td data-field="value"><span class="jc-vcell mono">4.2</span><input class="jc-cell mono" value="4.2"></td>
+            <td data-field="unit"><span class="jc-vcell">mA</span><input class="jc-cell" value="mA"></td>
+            <td data-field="constraint"><span class="jc-vcell"><span class="ct soft">软约束</span></span><input class="jc-cell" value="软约束"></td>
+            <td data-field="desc" class="desc"><span class="jc-vcell ro">影响待机功耗</span></td>
+          </tr>
+          <tr>
+            <td class="rn"><span class="jc-rn-num">6</span><button class="jc-rowdel" type="button" title="删除此行">×</button></td>
+            <td data-field="internal_pn"><span class="jc-vcell mono">XL2596S-5.0</span><em class="pre">预填</em><input class="jc-cell mono" value="XL2596S-5.0"></td>
+            <td data-field="param"><span class="jc-vcell">工作温度</span><input class="jc-cell" value="工作温度"></td>
+            <td data-field="value"><span class="jc-vcell mono">-40~+125</span><input class="jc-cell mono" value="-40~+125"></td>
+            <td data-field="unit"><span class="jc-vcell">℃</span><input class="jc-cell" value="℃"></td>
+            <td data-field="constraint"><span class="jc-vcell"><span class="ct hard">硬约束</span></span><input class="jc-cell" value="硬约束"></td>
+            <td data-field="desc" class="desc"><span class="jc-vcell ro">工业温域必须覆盖</span></td>
+          </tr>
+          <tr>
+            <td class="rn"><span class="jc-rn-num">7</span><button class="jc-rowdel" type="button" title="删除此行">×</button></td>
+            <td data-field="internal_pn"><span class="jc-vcell mono">XL2596S-5.0</span><em class="pre">预填</em><input class="jc-cell mono" value="XL2596S-5.0"></td>
+            <td data-field="param"><span class="jc-vcell">使能阈值</span><input class="jc-cell" value="使能阈值"></td>
+            <td data-field="value"><span class="jc-vcell mono">未披露</span><input class="jc-cell mono" value="未披露"></td>
+            <td data-field="unit"><span class="jc-vcell">V</span><input class="jc-cell" value="V"></td>
+            <td data-field="constraint"><span class="jc-vcell"><span class="ct hard">硬约束</span></span><input class="jc-cell" value="硬约束"></td>
+            <td data-field="desc" class="desc"><span class="jc-vcell ro">未披露项将进入 UNKNOWN 并挂验证任务</span></td>
+          </tr>
+        </tbody>
+      </table>
+    </div>
+
+    <div class="jc-addrow" id="addrow2">
+      <button type="button">＋ 加一行（补充参数）</button>
+      <em>所属料号 / 参数名 / 值 / 单位 / 约束类型齐全；「未披露」请直接写未披露，将进入 UNKNOWN 并挂验证任务；「说明」列为系统注释，无需填写</em>
+    </div>
+
+    <div class="flow"><b>提交 / 确认：</b>本工单只承载内容；确认请在对话区【数据卡】中进行。</div>
+
+  </div>
+
+  <footer class="card-foot">
+    <span>SS02 · ACT-WORK-05 差异评估 · 数据工单 1/1 · 芯片主数据创建（P-08）</span>
+    <span style="font-family:'SF Mono',Menlo,Consolas,monospace">工单类型：数据 · <span data-slot="card.id">WO-ACT-WORK-05-D01</span></span>
+  </footer>
+
+</div>
+</div>
+
+<script>
+(function(){
+  function wire(gateId, tblId, addrowId, addTpl){
+    var gate = document.getElementById(gateId);
+    var tbl = document.getElementById(tblId);
+    var addrow = addrowId ? document.getElementById(addrowId) : null;
+    var tbody = tbl.querySelector('tbody');
+    function setEdit(on){ gate.classList.toggle('on',on); tbl.classList.toggle('on',on); if(addrow){ addrow.classList.toggle('show',on); } }
+    function sync(fromVtoC){ tbody.querySelectorAll('tr').forEach(function(tr){ tr.querySelectorAll('td').forEach(function(td){ var v=td.querySelector('.jc-vcell'),c=td.querySelector('.jc-cell'); if(v&&c){ if(fromVtoC){c.value=v.textContent;}else{v.textContent=c.value;} } }); }); }
+    function renumber(){ tbody.querySelectorAll('tr').forEach(function(tr,i){ tr.querySelector('.jc-rn-num').textContent=i+1; }); }
+    gate.querySelector('.eg-open').addEventListener('click', function(){ setEdit(true); });
+    gate.querySelector('.eg-cancel').addEventListener('click', function(){ sync(true); setEdit(false); });
+    gate.querySelector('.eg-save').addEventListener('click', function(){ sync(false); renumber(); setEdit(false); });
+    if(addrow && addTpl){
+      addrow.querySelector('button').addEventListener('click', function(){
+        var tr=document.createElement('tr');
+        tr.innerHTML=addTpl;
+        tbody.appendChild(tr); renumber();
+      });
+      tbody.addEventListener('click', function(e){ if(e.target.classList.contains('jc-rowdel')){ e.target.closest('tr').remove(); renumber(); } });
+    }
+  }
+  wire('gate1','tbl1','addrow1',
+    '<td class="rn"><span class="jc-rn-num"></span><button class="jc-rowdel" type="button" title="删除此行">×</button></td>'+
+    '<td><span class="jc-vcell mono"></span><input class="jc-cell mono" placeholder="内部料号＊"></td>'+
+    '<td><span class="jc-vcell"></span><input class="jc-cell" placeholder="品牌＊"></td>'+
+    '<td><span class="jc-vcell"></span><input class="jc-cell" placeholder="制造商"></td>'+
+    '<td><span class="jc-vcell"></span><input class="jc-cell" placeholder="规格描述＊"></td>'+
+    '<td><span class="jc-vcell mono"></span><input class="jc-cell mono" placeholder="封装＊"></td>'+
+    '<td><span class="jc-vcell"></span><input class="jc-cell" placeholder="工艺"></td>'+
+    '<td><span class="jc-vcell"></span><input class="jc-cell" placeholder="生命周期＊"></td>'+
+    '<td><span class="jc-vcell"></span><input class="jc-cell" placeholder="EOL/PCN"></td>'+
+    '<td><span class="jc-vcell mono"></span><input class="jc-cell mono" placeholder="Datasheet 引用 · 版本"></td>'+
+    '<td><span class="jc-vcell"></span><input class="jc-cell" placeholder="适配场景"></td>');
+  wire('gate2','tbl2','addrow2',
+    '<td class="rn"><span class="jc-rn-num"></span><button class="jc-rowdel" type="button" title="删除此行">×</button></td>'+
+    '<td><span class="jc-vcell mono"></span><input class="jc-cell mono" placeholder="所属料号＊"></td>'+
+    '<td><span class="jc-vcell"></span><input class="jc-cell" placeholder="参数名"></td>'+
+    '<td><span class="jc-vcell mono"></span><input class="jc-cell mono" placeholder="值"></td>'+
+    '<td><span class="jc-vcell"></span><input class="jc-cell" placeholder="单位"></td>'+
+    '<td><span class="jc-vcell"></span><input class="jc-cell" placeholder="硬约束 / 软约束"></td>'+
+    '<td><span class="jc-vcell ro">—</span></td>');
+})();
+</script>
+</body>
+</html>

docs/SS02-ACT-WORK-05-html/ACT-WORK-05-活动流程与工单说明.md

@@ -0,0 +1,297 @@
+# ACT-WORK-05 差异评估 — 活动流程与工单说明
+
+> 素材来源：`activity/SS02-需求分析与方案匹配/SS02_ACT-WORK-05_差异评估_E04-I01架构版_V1.2.html`（v1.2 Demo 架构版）
+> 工单目录：`SS02-ACT-WORK-05-html/`（1 数据（条件触发）+ 1 执行 + 2 验收，共 4 份）
+> 本套工单已按《SS02-SS03-SS04_Demo台账字段细化与统一方案》（2026-08）完成字段级对齐。
+
+---
+
+## 一、活动定位
+
+- **活动**：ACT-WORK-05 差异评估，P0，所属 SS02 需求分析与方案匹配子系统 / BT-02 跨品牌替代选型场景，负责人 FAE/RI。
+- **是什么**：将「候选 PN 是否可替代」拆解为参数、封装、工艺、生命周期、应用边界和验证条件的逐项比较，形成逐项可复核的差异结论（MATCH / MISMATCH / UNKNOWN / CONDITIONAL），并保留证据、风险和下一步动作。输出 AI 分析草稿和 FAE 审核结论，**不自动批准替代关系**。
+- **产出物**：差异评估结论 + 推荐等级 recommendation_level（推荐 / 条件推荐 / 备选 / 不推荐），审核通过后落账 **P-11 替代关系主记录**（含 P-11 差异明细子表，一条参数差异一条记录 difference_item_id），并回写 **P-01**（风险等级、验证要求、输出链接、下一步动作、当前阶段）。
+- **触发**：双通道——①上游触发：ACT-WORK-03 检索调用 / ACT-GATE-02 路径判定后；②一键手动启动：运营端按钮表单直接启动（绕过 ACT-GATE-02 路径判定，故启动理由必填、source_type=手动启动 留痕，详见《ACT-WORK-05-一键启动入参说明.md》）。**触发渠道仅是活动外部关注点，活动内部与工单不承载触发渠道信息——两种通道传入同一字段集，工单无差别呈现。**
+- **门禁**：ACT-GATE-03 评审放行（本活动终点）。
+- **下游**：ACT-WORK-08 证据归集消费本活动结论。
+- **冷启动能力**：依赖库为空（PN 按 internal_pn 查无记录）时，系统派**数据工单**创建主数据，确认即入库后活动自动从「等待数据」唤醒继续——活动不因空库终止。
+- **台账读写**：P-01（R+W）、P-06（R/C，条件写）、P-08（R；无记录时经数据工单 W 创建）、P-09（R）、P-10（R；无记录时经数据工单 W 创建）、P-11（R+W；其中客户批准状态 customer_approval_status **只读边界**，由审批流程维护，本活动不产生）、GOV 规则（R，带版本锁定 rule_version）。
+- **进入条件（极简口径）**：启动入参仅 **4 项**——客户 customer_id、客户需求 request_description（新建 P-01·V1）、原 PN、候选 PN（数组 ≥1）；应用场景、BOM 位、替代类型、规则版本、负责人/期限等**启动后在工单内补齐，不回表单**；datasheet 在数据工单里上传（选填），只影响 AI 预填程度。
+- **退出条件**：每个候选 PN 都有差异状态、证据/缺口、风险和验证建议，并完成 FAE/RI 审核。
+
+## 二、整体流程（5 步工作链条）
+
+**步骤 1 · 建立评估上下文（PW/AI）**
+- AI 做什么：绑定评估对象，生成输入快照。
+- AI 怎么做：读 → 经读数工具读 P-01（启动新建的 demand 主记录：客户、需求描述、版本 V1）、P-09（BOM 位 bom_position）、EXT-02（外部来源清单）；加工 → 绑定启动 4 项（客户/需求/原 PN/候选数组），核对资料齐备度，标出缺口项（应用场景、BOM 位等待补）；输出 → 输入快照 input_snapshot_ref（活动自持中间产物）。
+- 人做什么：**PW 介入**——补启动时未收的信息（应用场景、BOM 位），确认或调整系统默认值（替代类型、规则版本、负责人/期限），补 AI 拿不到的资料（实测记录等）（执行工单 01）。
+- 触发纪律：触发传入参数即活动进入条件，系统据此生成 input_snapshot_ref 并完成绑定后派执行工单 01，PW 仅补缺口，绑定参数不可改（双通道与渠道无感知原则详见第七节）。
+
+**步骤 2 · 读取并标准化资料（AI）**
+- AI 做什么：把多来源资料整理成可比对的标准参数表。
+- AI 怎么做：读 → P-08（原 PN 物料基准）、P-10（候选原厂 Datasheet、补证、承诺函，资料类型由 document_type 区分）、P-06（历史验证事实）、GOV 规则（评估口径）；**每次读台账均做存在性检查：查无记录→主数据/资料类派数据工单（一单一类可多条），事实/证据类（如 P-06）挂验证任务**；加工 → 统一参数名称、单位、版本和证据引用，缺失项标记 UNKNOWN；输出 → 标准化参数对照表（活动自持）。
+- 人做什么：无需介入（纯 AI 加工态）。
+
+**步骤 3 · 逐项差异评估（AI）**
+- AI 做什么：逐项给出差异结论。
+- AI 怎么做：读 → 步骤 2 的标准化对照表 + GOV 规则版本 rule_version（取参数时同样做存在性检查：查无记录→派数据工单或挂验证任务）；加工 → 按硬约束（封装/工艺等）与软约束（constraint_type）逐项判定，输出 MATCH / MISMATCH / UNKNOWN / CONDITIONAL（difference_status），并说明影响、风险等级、证据引用与置信度；输出 → P-11 差异明细子表草稿（一条参数差异一条记录 difference_item_id，**审核前不落账**），不改变客户批准关系。
+- 人做什么：无需介入（AI 计算态），结论交步骤 4 审核。
+
+**步骤 4 · FAE/RI 审核与补证（FAE/RI）**
+- AI 做什么：把步骤 3 草稿整理成可审核视图（四态 pill + 证据链）。
+- AI 怎么做：读 → P-11 差异明细子表草稿；加工 → 按验收判据组织展示（漏项检查、UNKNOWN 去向、证据回链、硬约束检查）；输出 → 审核工单视图。
+- 人做什么：**FAE/RI 介入**——确认参数解释、风险等级、证据可信度和验证要求，必要时退回补证；审核意见与补充条件条件写 P-06（验收工单 01）。
+
+**步骤 5 · 提交评审放行（FAE/RI + Gate）**
+- AI 做什么：汇总拟落账内容供确认。
+- AI 怎么做：读 → 审后结论；加工 → 生成拟写 P-11 替代关系主记录字段值（替代类型/原内部料号/候选内部料号/推荐等级/推荐理由/差异摘要/替代分析报告/分析状态/风险等级/验证要求/证据可信度/差异规则版本）与拟回写 P-01 字段值（风险等级/验证要求/输出链接/下一步动作/当前阶段）；输出 → 落账确认视图。
+- 人做什么：**FAE/RI 介入**——确认拟落账内容无误后，在对话区卡提交 ACT-GATE-03（验收工单 02）。放行后更新 P-01 状态，结论供 ACT-WORK-08 证据归集消费；客户批准状态 customer_approval_status 仍由审批流程维护，本活动不写。
+
+## 三、工单划分逻辑
+
+本活动为**纯数据/内容生产型**（同 I01），无物理执行环节（没有拜访、递送、线下执行），因此**没有执行回执类工单**。本活动使用**三类工单**，触发条件与分工严格区分：
+
+| 类型 | 触发条件 | 判断方 | 人做什么 | 入库方式 |
+|---|---|---|---|---|
+| **数据工单** | **完全没有**：按 internal_pn 查台账（P-08 等主数据/资料类）无此记录 | 系统（硬查询） | 从零创建整条记录 | **确认即正式入库**（无草稿态、无审核环节），确认人=数据责任人并留痕 |
+| **执行工单** | **有而不全**：PN 在库、个别字段/资料缺失 | AI（字段级判断） | 补缺字段、补资料链接 | 对话区【执行卡】提交，缺口可留 UNKNOWN |
+| **验收工单** | AI 已产出结论，需人拍板 | AI 产出 + 人判断 | 通过 / 驳回 | 对话区【验收卡】通过后落账 |
+
+- 数据工单与执行工单**严格区分、互不嵌套**：一个是「整条记录不存在」（系统判断），一个是「记录存在但字段不全」（AI 判断）。
+- 数据工单**铁律一**：只能建主数据/资料类记录（P-08 / P-10 / S-03 / L-02），不能建事实/证据记录（P-06 验证记录须实测产生，只能挂任务）。
+
+对生产流程逐步判定：
+
+- **步骤 0.5（存在性检查，条件触发）**：启动校验发现 PN 不在库 → 派 **数据工单 01**（芯片主数据创建，本活动唯一数据单），确认入库前活动停在「等待数据」状态，确认后自动唤醒。
+- **步骤 1（建立评估上下文）**：AI 能读台账建快照，但「参数原厂未披露、资料版本过旧」这类 **AI 拿不到的可信来源资料只有人能补** → 派 **执行工单 01**（评估输入与资料补齐确认，本活动唯一执行单）。
+- **步骤 2（读取并标准化）、步骤 3（逐项差异评估）**：均为**纯 AI 加工态**——读台账、标准化、按规则计算，不需要人补内容、也没有产出要人拍板的中间结论 → **不派工单**，其结论并入步骤 4 的验收单呈现。
+- **步骤 4（FAE/RI 审核）**：AI 已产出差异结论（四态 + 风险 + 证据），需要人判断「结论可信不可信、UNKNOWN 有没有去向」→ 派 **验收工单 01**（差异评估结论审核）。
+- **步骤 5（提交 ACT-GATE-03）**：AI 拟好了落账内容，需要人确认「无误后入库 / 放行」→ 派 **验收工单 02**（评审放行与落账确认）。
+
+结论：**1 数据（条件触发）+ 1 执行 + 2 验收**。本活动无独立复盘流程（结论复用由下游 ACT-WORK-08 与后续替代/方案流程承担），无需拆时间轴。三条硬约束全程成立：工单不承载审批/确认动作（动作在对话区卡）；要素完整（期限/判据/必填/去向）；交回内容可校验（执行单必填＊、验收单判据清单、数据单必填全齐才允许确认）。
+
+## 四、每个工单详细说明
+
+### 工单 0：数据工单 01 · 芯片主数据创建（WO-ACT-WORK-05-D01，条件触发）
+- **对应步骤**：步骤 0.5 · 等待数据（惰性触发点之一；启动校验期的存在性检查只是第一次）。
+- **三条定稿规则**：
+  - **一单一类（可多条）**：每张数据工单只针对**一种台账**；**字段即表头、每行一条新记录，可一次创建多条**（如 P-08 一次建多个料号）；主记录与结构子表（如参数集）分表承载，子表行以主键（所属料号）归属记录；其它台账的缺失另行派发新实例。
+  - **惰性触发（不限于启动）**：活动执行到任何一步，**每次读台账**发现「完全没有」（按主键查无记录）即派一张；同一活动可派发多张，按派发顺序编号 WO-<活动>-D01/D02/…；活动进入「等待数据」状态，全部确认入库后从断点续跑。启动校验只是惰性触发的第一次，不是唯一一次。并发去重不考虑（一活动一负责人）。
+  - **模板统一**：数据工单只有**一个统一模板**（类型级），职责只有「数据创建」；实例化时按目标台账的字段 schema（《统一方案》字段表）渲染表头 + AI 预填/人全填。实例之间只有两处不同：**目标台账（决定表头 schema）、预填内容（决定行集）**（本单：目标台账=P-08 `meta.data.target_ledger`、本批记录=XL2596S-5.0 `meta.data.target_key`）。
+- **触发**：系统按主键查台账**无此记录**（完全没有，系统硬查询）——原 PN 无数据=硬阻塞必须创建；候选 PN 无数据：候选数 ≥2 时人可二选一（放弃该候选【记录放弃原因】或创建），候选数 =1 时不能放弃、必须创建。事实/证据类查无（如 P-06 无验证记录）**不可创建**，只能挂验证任务。
+- **创建什么**：①表 1 主数据记录（**字段即表头、每行一条新记录、可加行批量创建**：internal_pn★ / brand_name★ / manufacturer_name / specification_description★ / package★ / process_technology / lifecycle_status★ / eol_pcn_status（条件）/ datasheet_ref+datasheet_version（成对条件）/ application_scenarios，字段说明放表头第二行小字，tbody `in.create_p08_fields`）；②表 2 标准化参数集 normalized_parameter_set★（**每行一个参数、以「所属料号 internal_pn」列归属表 1 记录**：所属料号★/参数名/值/单位/约束类型/说明只读注释列，可加行，tbody `in.create_p08_params`，示例预填 7 行）。启动时传了 datasheet → AI 预填（计数槽 `sd.prefill_count`，示例 1 条记录 · 8 项字段 + 7 行参数）；没传 → 人全填，同为合法路径。
+- **为什么两张表（粒度不同，一张表摆不平）**：表 1 的粒度是「一个料一行」——每个字段对每条记录只有一个值，字段集合由台账 schema 定死（主记录）；表 2 的粒度是「一个参数一行」——每个料挂一串行数不固定的参数，每行内部还有 参数名/值/单位/硬软约束 四件套（结构子表）。两者行数没有固定比例，合成一张表只有两条死路：①参数塞进料号行的某格——一坨文本，机器没法逐项消费（差异评估要逐项比对）、人没法校验必填，违反《统一方案》「重复明细用子表承载，不在单一文本字段堆叠」；②参数也变成列——不同料的参数清单完全不同（DCDC 和 MCU 没有共同列），列数不固定，表头无法按 schema 统一渲染，通用模板破产。所以必须两张表，靠表 2 的「所属料号」列做连接键（映射主表+子表的外键关系）：建 3 个料 → 表 1 三行、表 2 按料号分 3 组；入库时系统按该键把参数集挂到各自主记录下。
+- **确认即入库与责任人**：人在对话区【数据卡】点确认 → **直接入正式库（record_status=有效），无草稿态、无审核环节**；确认人=该数据责任人，系统留痕（确认人 / 数据工单号 / 所属活动）；必填字段全齐才允许确认（表单级校验，不算审核）。入库后活动自动唤醒进步骤 1；入库后发现错误走主数据治理修正，工单不复用。
+- **铁律一**：只能建主数据/资料类记录（P-08 / P-10 / S-03 / L-02），不能建事实/证据记录（P-06 验证记录须实测产生，只能挂任务）。
+- **为什么是独立类型**：条件触发（只在「完全没有」时派发，非常驻）；产出是**共享资产**（进正式库、跨活动复用，不是本活动的中间产物）；模板直接来自台账字段定义（P-08 字段表），不是活动自定义表单；与执行工单「有而不全」严格区分、互不嵌套。
+
+### 工单 1：执行工单 01 · 评估输入与资料补齐确认（WO-ACT-WORK-05-01）
+- **对应步骤**：步骤 1/5 · 建立评估上下文。
+- **做什么**：确认触发传入参数已绑定（只读回显），补齐「有而不全」的缺口资料。
+- **AI 产出**：一张「评估输入清单」（`in.evaluation_inputs`）——按状态列区分：**已绑定**（灰底只读行，启动时冻结，仅 4 项：客户 customer_id、客户需求 request_description（新建 P-01 · V1）、原内部料号 original_internal_pn、候选内部料号 candidate_internal_pn[] 数组逐行）、**待补**（应用场景 application_scenario、BOM 位 bom_position——启动时未收）、**默认·可改**（替代类型 substitution_type 默认 Pin-to-Pin、规则版本 rule_version 默认 R-2026.07、负责人/期限按客户线默认）、**待确认·需补**（候选 PN 使能阈值原厂未披露，P-08）、**齐备**（原 PN 资料版本 P-10 Rev H 已核验、外部来源清单 EXT-02）；编辑闸读数 `sd.input_gap_count` 显示缺口项数。
+- **人填什么**：缺口行「补充内容」列（必填＊）——资料链接 / 任务编号；可加行补充 AI 未列出的资料项（新行自动标「新增·待补」），可删行声明不适用；已绑定行在编辑态下仍只读、不可删。未补齐项按 UNKNOWN 进入评估。启动参数如有误，退回触发方修订后重新触发，本单不可改。
+- **为什么是执行**：本单只覆盖「**有而不全**」——PN 已在库、个别字段缺失（AI 判断）；「**完全没有**」（PN 不在库）由系统派数据工单创建，不在本单，两类互不嵌套。可信来源资料的获取在 AI 识别规则之外（原厂未公开、实测未做），只有 PW 能补。
+
+### 工单 2：验收工单 01 · 差异评估结论审核（WO-ACT-WORK-05-02）
+- **对应步骤**：步骤 3~4/5 · 逐项差异评估 + FAE/RI 审核（步骤 2~3 为纯 AI 加工，不单独派单，结论并入本单）。
+- **AI 产出**：P-11 差异明细子表草稿（7 行示例：输出电压/输出电流/开关频率/封装 MATCH，工作温度 MISMATCH 高风险，使能阈值 UNKNOWN 挂 VAL-2026-0188，生命周期 CONDITIONAL 凭 P-10 供货承诺函），每项带约束类型 constraint_type（硬/软约束）、四态 pill difference_status、风险等级、证据引用 evidence_ref、AI 置信度。
+- **人审什么**（4 条判据）：关键参数差异均有明确状态（无漏项）；UNKNOWN 项均有去向（挂验证任务或补来源）；证据链完整（可追溯 P-08/P-10/P-06 或 EXT-02）；硬约束项未被自动判 MATCH。
+- **为什么是验收**：结论是 AI 按规则算出的，FAE/RI 只拍板通过/驳回，不改内容；审核意见与补充条件写 P-06。
+
+### 工单 3：验收工单 02 · 评审放行与落账确认（WO-ACT-WORK-05-03）
+- **对应步骤**：步骤 5/5 · 提交 ACT-GATE-03。
+- **AI 产出**：两张只读表——拟写 P-11 替代关系主记录（替代类型 substitution_type / 原内部料号 original_internal_pn / 候选内部料号 candidate_internal_pn / 推荐等级 recommendation_level「条件推荐」pill / 推荐理由 / 差异摘要 / 替代分析报告 analysis_report_ref RPT-2026-0188 / 分析状态 analysis_status「FAE确认」/ 客户批准状态 customer_approval_status「未提交」/ 风险等级 / 验证要求 / 证据可信度 / 差异规则版本 rule_version）；拟回写 P-01（风险等级 / 验证要求 VAL-2026-0188 / 输出链接 / 下一步动作 / 当前阶段）。
+- **人审什么**（4 条判据）：推荐等级与差异明细一致（存在 UNKNOWN/CONDITIONAL 不得给「推荐」）；分析状态与客户批准状态分离（本单只写分析层 analysis_status=FAE确认，customer_approval_status 保持未提交，不由差异评估产生）；GOV 规则版本已锁定（R-2026.07）；回写 P-01 字段完整。
+- **为什么是验收**：落账内容已由 AI 拟好，人只确认「无误后入库 + 放行」；客户批准不在本单范围（customer_approval_status 只读边界，由审批流程维护）。
+
+## 五、文件对应关系与闭环流程图
+
+| 文件 | 类型 | 对应步骤 | 一句话 |
+|---|---|---|---|
+| `ACT-WORK-05-数据工单-01-芯片主数据创建.html` | 数据 1/1（条件触发） | 步骤 0.5 | PN 不在库时系统派发，人创建整条 P-08 记录，确认即入库（责任人留痕）后活动唤醒 |
+| `ACT-WORK-05-执行工单-01-评估输入与资料补齐确认.html` | 执行 1/1 | 步骤 1 | 评估输入清单：已绑定项只读核对 + 「有而不全」缺口项 PW 补齐，缺口项按 UNKNOWN 进入评估 |
+| `ACT-WORK-05-验收工单-01-差异评估结论审核.html` | 验收 1/2 | 步骤 3~4 | FAE/RI 审核 AI 逐项差异结论（四态 + 证据链），意见写 P-06 |
+| `ACT-WORK-05-验收工单-02-评审放行与落账确认.html` | 验收 2/2 | 步骤 5 | 确认拟写 P-11 / 回写 P-01 内容，提交 ACT-GATE-03 |
+| `ACT-WORK-05-一键启动入参说明.md` | 说明文档 | 触发 | 运营端一键启动的入参总表、系统行为与工单衔接说明 |
+| `ACT-WORK-05-全流程分支图.html` | 可视化 | 全流程 | 面向业务负责人的流程与全部分支一览（自包含零依赖） |
+
+```
+触发（双通道：ACT-WORK-03 检索调用 / ACT-GATE-02 路径判定 ｜ 一键手动启动，绕过 GATE-02，启动理由留痕）
+  │
+  ▼
+步骤0.5 存在性检查（系统，条件触发）── PN 不在库？（全链路惰性检查的第一次；之后每次读台账仍可能再派 D02/D03…）
+  │──►【数据工单 01】芯片主数据创建 ── 一单一类可多条（字段即表头、每行一条），对话区【数据卡】确认即入库
+  │      确认前活动停「等待数据」；全部确认入库后从断点续跑
+  ▼
+步骤1 建立评估上下文（PW/AI）
+  │──►【执行工单 01】评估输入与资料补齐确认 ── PW 补资料，对话区【执行卡】提交
+  ▼
+步骤2 读取并标准化资料（AI，不派单）── 缺失项标 UNKNOWN
+  ▼
+步骤3 逐项差异评估（AI，不派单）── P-11 差异明细子表草稿（不落账）
+  ▼
+步骤4 FAE/RI 审核与补证
+  │──►【验收工单 01】差异评估结论审核 ── 对话区【验收卡】通过/驳回
+  │      通过：意见与验证要求条件写 P-06
+  │      驳回：退回补证 / 验证（回步骤 1 或挂 VAL 任务）
+  ▼
+步骤5 提交评审放行
+  │──►【验收工单 02】评审放行与落账确认 ── 对话区【验收卡】通过/驳回
+  │      通过：P-11 替代关系主记录落账 ＋ P-01 回写 ＋ 提交 ACT-GATE-03
+  ▼
+ACT-GATE-03 评审放行（门禁，本活动终点）
+  ▼
+下游 ACT-WORK-08 证据归集消费
+（P-11.customer_approval_status 客户批准：全程只读边界，由审批流程另行维护）
+```
+
+## 六、动态数据标注
+
+命名空间速查：`meta.*` 任务元数据 ｜ `card.*` 工单身份 ｜ `in.*` 执行/数据工单输入行集 ｜ `out.*` 验收单输出行集 ｜ `sd.*` 状态读数。
+
+### 工单 0（数据 01）动态位置
+
+| 位置 | 动态数据 | 绑定地址 | 类型 |
+|---|---|---|---|
+| 卡头 sub | 收件人 | `meta.task.owner` | data-slot |
+| 卡头 sub | 关联任务 | `meta.task.id` | data-slot |
+| 卡头 side | 当前步骤（等待数据 · 步骤 0.5/5） | `meta.phase` | data-slot |
+| 卡头 side | 最迟交回 | `card.deadline` | data-slot |
+| note 读数 | AI 预填项数 | `sd.prefill_count` | data-slot |
+| 表 1 tbody | 主数据记录行集（每行一条记录，可加行批量创建） | `in.create_p08_fields` | data-rows |
+| 表 1 表头 th / 单元格 td | 内部料号★/品牌★/制造商/规格描述★/封装★/工艺/生命周期★/EOL-PCN（条件）/Datasheet 引用+版本（成对）/适配场景 ｜ internal_pn / brand_name / manufacturer_name / specification_description / package / process_technology / lifecycle_status / eol_pcn_status / datasheet_ref / application_scenarios | data-h / data-field | 列标签 / 列绑定 |
+| 表 2 tbody | 标准化参数集行集（每行一个参数，按所属料号归属，可加行） | `in.create_p08_params` | data-rows |
+| 表 2 表头 th / 单元格 td | 所属料号★ / 参数名 / 值 / 单位 / 约束类型 / 说明（只读注释 ro） ｜ internal_pn / param / value / unit / constraint / desc | data-h / data-field | 列标签 / 列绑定 |
+| 页脚 | 工单编号 | `card.id` | data-slot |
+
+### 工单 1（执行 01）动态位置
+
+| 位置 | 动态数据 | 绑定地址 | 类型 |
+|---|---|---|---|
+| 卡头 sub | 收件人 | `meta.task.owner` | data-slot |
+| 卡头 sub | 关联任务 | `meta.task.id` | data-slot |
+| 卡头 side | 当前步骤 | `meta.phase` | data-slot |
+| 卡头 side | 最迟交回 | `card.deadline` | data-slot |
+| 编辑闸读数 | 缺口项数 | `sd.input_gap_count` | data-slot |
+| 表格 tbody | 评估输入清单行集（已绑定行只读 + 缺口行可编辑） | `in.evaluation_inputs` | data-rows |
+| 表头 th | 输入项 / 来源 / 状态 / 绑定值·缺口说明 / 补充内容（req＊） | data-h | 列标签 |
+| 单元格 td | input_item / source_ledger / status / detail / supplement | data-field | 列绑定 |
+| 页脚 | 工单编号 | `card.id` | data-slot |
+
+### 工单 2（验收 01）动态位置
+
+| 位置 | 动态数据 | 绑定地址 | 类型 |
+|---|---|---|---|
+| 卡头 sub | 收件人 | `meta.task.owner` | data-slot |
+| 卡头 sub | 关联任务 | `meta.task.id` | data-slot |
+| 卡头 side | 当前步骤 | `meta.phase` | data-slot |
+| 卡头 side | 最迟交回 | `card.deadline` | data-slot |
+| 表格 tbody | 差异明细行集（P-11 差异明细子表草稿，difference_item_id） | `out.difference_items` | data-rows |
+| 表头 th | 参数项 parameter_name / 原PN值 original_value / 候选PN值 candidate_value / 单位 parameter_unit / 约束类型 constraint_type / 结论 difference_status / 风险等级 / 证据引用 evidence_ref / AI置信度 | data-h | 列标签 |
+| 单元格 td | parameter_name / original_value / candidate_value / parameter_unit / constraint_type / difference_status / risk_level / evidence_ref / confidence | data-field | 列绑定 |
+| 页脚 | 工单编号 | `card.id` | data-slot |
+
+### 工单 3（验收 02）动态位置
+
+| 位置 | 动态数据 | 绑定地址 | 类型 |
+|---|---|---|---|
+| 卡头 sub | 收件人 | `meta.task.owner` | data-slot |
+| 卡头 sub | 关联任务 | `meta.task.id` | data-slot |
+| 卡头 side | 当前步骤 | `meta.phase` | data-slot |
+| 卡头 side | 最迟交回 | `card.deadline` | data-slot |
+| 表 1 tbody | 拟写 P-11 替代关系主记录行集 | `out.ledger_p11` | data-rows |
+| 表 2 tbody | 拟回写 P-01 行集 | `out.writeback_p01` | data-rows |
+| 表头 th | 字段 / 拟写入值 | data-h | 列标签 |
+| 单元格 td | field / value | data-field | 列绑定 |
+| 页脚 | 工单编号 | `card.id` | data-slot |
+
+---
+
+## 七、启动与触发（实现规格）
+
+1. **双通道与渠道无感知原则**：触发方式 = ①上游触发（ACT-WORK-03 检索调用 / ACT-GATE-02 路径判定）②运营端一键手动启动。两通道传入**同一字段集**；活动内部与工单不承载、不区分触发渠道。source_type / 启动理由属运营端留痕字段，不传入活动。
+2. **进入条件（启动校验，agent 必须在创建活动实例前校验，极简口径）**：启动入参仅 **4 项**——客户 customer_id、客户需求 request_description（无 P-01 记录则新建·版本 V1）、原 PN、候选 PN（数组 ≥1）。**应用场景、BOM 位、替代类型、规则版本、负责人/期限不是启动入参**——替代类型默认 Pin-to-Pin、规则版本默认当前发布版、负责人/期限按客户线默认，均在执行工单 01 列为「默认·可改」行由 PW 确认或调整；应用场景、BOM 位为「待补」行由 PW 补录。**datasheet 在数据工单里上传（选填）**——传了则 AI 在数据工单里预填，没传则人全填，不影响能否启动。
+3. **存在性检查 = 全链路惰性触发（系统硬查询）**：启动校验期的存在性检查只是**第一次**；活动执行中**每次读台账**（步骤 2 读 P-08/P-10/P-06、步骤 3 取参数等）发现「完全没有」均再派新数据工单（一单一类可多条，按派发顺序 D01/D02/…）。活动可并行等待多张数据工单，全部确认入库后从断点续跑。启动期的两档语义：
+   - 原 PN 无数据 → **硬阻塞**：必须派数据工单创建，确认入库前活动停在「等待数据」状态；
+   - 候选 PN 无数据 → 候选数 **≥2** 时人可二选一（放弃该候选【记录放弃原因】或派数据工单创建）；候选数 **=1** 时不能放弃、必须创建；
+   - 数据工单确认入库后，活动自动唤醒进入步骤 1。
+   - datasheet 的有无不参与拦截，只决定数据工单是「AI 预填」还是「人全填」。
+4. **任务锚点二选一（重点：request_id 与 requirement_version 是系统产出，不是入参）**：
+   - **关联已有需求**：选 request_id，版本自动带出；
+   - **快速创建**（客户口述需求未建档场景）：入参 = customer_id（老客户下拉选；新客户先建 L-02，属分支 0a）+ 需求描述（口述整理成文字）；系统行为 = **自动创建 P-01 记录、生成 request_id、requirement_version 默认 V1**，并把原 PN 与候选 PN 数组作为独立启动参数挂载绑定。
+5. **口述需求的版本纪律**：版本属于需求记录而非客户口述；客户后续补充 / 澄清 → 更新 P-01 记录，requirement_version 递增（V1→V1.1，旧版保留）；每次评估锁 as_of 版本（input_snapshot_ref 记录当时按哪版评），全程可回溯。
+6. **启动后系统行为序列**：校验进入条件（4 项） →（快速创建时建 P-01 · V1）→ **存在性检查**（按 internal_pn 查台账，候选数组逐个查；缺则派数据工单，活动停「等待数据」，确认入库后唤醒）→ 绑定客户 / 需求 / 原 PN / 候选数组 + 落系统默认值（替代类型、规则版本、负责人/期限）→ 生成 input_snapshot_ref → 进入步骤 1 派执行工单 01。
+7. **冻结与退回纪律**：触发时绑定的参数在工单内只读不可改；绑错的唯一处理 = 退回触发方修订后重新触发（手动 → 退回运营端启动人；上游 → 退回上游活动）。
+8. 参数字段集详见同目录《ACT-WORK-05-一键启动入参说明.md》（运营端规格）。
+
+## 八、完整流程分支总表（含示例）
+
+1. **示例场景**（口径注意：本活动只评技术可替代性，示例不涉及库存数量 / 采购情节）：客户工业电源项目在用 LM2596S-5.0（TI，12V→5V），原厂 PCN 转 NRND，客户要求验证替代；候选 A=XL2596S-5.0、B=LM2596S-ADJ、C=国产某 DCDC；一键快速创建需求单 REQ-20260826-001（V1）；应用场景（12V→5V、工业温域、40V 输入上限）启动后在执行工单 01 补录。
+2. **分支总表**（18 条全列）：
+
+| 分支 | 触发条件 | 处理与去向 |
+|---|---|---|
+| 0a | 启动期：新客户无档案 | 先建 L-02 客户档案（数据工单），再返回启动 |
+| 0b | 启动期：候选无 P-08 主数据 | 同分支 1d：派数据工单登记创建 |
+| 0c | 启动期：未传 datasheet | **不再拦截**——datasheet 已是选填，仅意味着数据工单由「AI 预填」变为「人全填」 |
+| 1a | 步骤 1：绑定参数有误 | 退回触发方修订后重新触发（工单内不可改） |
+| 1b | 步骤 1：输入存在缺口（有而不全） | 补缺口四情形：候选 PDF 未入库→补链接+版本；参数原厂未披露→挂验证任务（P-06）；原 PN 资料版本过旧→补最新版；应用约束不清→回头问客户并更新需求单版本 |
+| 1c | 步骤 1：缺口补不了 | 留 UNKNOWN 进入评估（合法路径，不阻断） |
+| 1d | 任何读数点：查无记录（完全没有） | 惰性触发派数据工单（一单一类可多条，模板统一，可多实例 D01/D02/…）：原 PN=硬阻塞·必须创建；候选 ≥2 可放弃【记录放弃原因】或创建（人判断）；候选 =1 必须创建。确认即入库（责任人留痕）→ 活动从断点续跑。事实/证据类查无（如 P-06）不可创建，挂验证任务 |
+| 2a | 步骤 2：单位冲突 | 阻断，回步骤 1 补证 |
+| 2b | 步骤 2：证据版本冲突 | 人工复核哪份资料为准 |
+| 3a | 步骤 3：硬约束 MISMATCH | 该候选直接「不推荐」（示例：候选 C 输入上限 32V &lt; 客户 40V） |
+| 4a | 步骤 4：UNKNOWN 无去向 | 退回步骤 1~2 补证 / 挂验证任务 |
+| 4b | 步骤 4：证据链不全 | 退回补齐证据回链 |
+| 5a | 步骤 5：ACT-GATE-03 放行 | P-11 落账（analysis_status=FAE确认），衔接下游 |
+| 5b | 步骤 5：ACT-GATE-03 驳回 | REWORK：回步骤 4 重审，或回步骤 1 重补输入 |
+| 6a | 完结：至少一个推荐 | 交下游衔接（ACT-WORK-08 / SS03 / ACT-WORK-24） |
+| 6b | 完结：全是条件推荐 | 等验证闭环——通过→升级推荐；不过→降级不推荐 |
+| 6c | 完结：全不推荐 | 重新检索替代料 / 继续用原 PN / 与客户协商放宽约束 |
+| 6d | 完结：客户不批准 | 走独立审批流（customer_approval_status），不在本活动 |
+
+3. **结果矩阵（示例）**：
+
+| 候选 | 推荐等级 | 关键依据 | 下一步 |
+|---|---|---|---|
+| A · XL2596S-5.0（XLSEMI） | 条件推荐 | 温度范围更优（-40~+125℃ vs +85℃）；使能阈值 UNKNOWN，挂 VAL-2026-0188 实测 | 验证闭环后转正 |
+| B · LM2596S-ADJ（TI 同族可调版） | 备选 | 反馈网络不同（可调版 vs 固定 5V），需改 BOM 外围 | 客户接受改设计则启用 |
+| C · 国产某 DCDC | 不推荐 | 硬约束失败：输入上限 32V &lt; 客户 40V（分支 3a） | 归档，不再评估 |
+
+4. **多候选并行原则**：N 个候选 = N 条独立 P-11 记录，并行评估、独立落账，不存在「选一个再评下一个」。
+5. 可视化版本见同目录《ACT-WORK-05-全流程分支图.html》。
+
+## 九、后端实现纪律（agent 必读，逐条不可违反）
+
+1. request_id / requirement_version / input_snapshot_ref 一律系统生成，agent 不得要求调用方传入。
+2. 活动实例创建前必须做进入条件校验与存在性检查；原 PN 无数据必须硬阻塞并派数据工单，返回缺什么；候选 PN 无数据按规则处理（≥2 可放弃【记录放弃原因】或创建，=1 必须创建）。
+3. 已绑定参数任何接口不允许修改；修改请求一律返回「退回触发方重新触发」。
+4. UNKNOWN 是一等公民：缺参数不得伪造、不得留空字符串冒充，必须显式标 UNKNOWN 并记录去向（挂验证任务 / 补来源）。
+5. 硬约束 MISMATCH 不得被任何人工操作改判 MATCH；人只能补证据后重评。
+6. analysis_status 与 customer_approval_status 严格分离：本活动只能推进 analysis_status（AI草稿→FAE确认），customer_approval_status 一律不碰（由独立审批流维护）。
+7. 规则版本 as_of 锁定：评估开始即记录 rule_version；评估中途 GOV 规则更新不得影响进行中的评估。
+8. 本活动输出只回答「技术可替代性」：不得在活动内做数量、价格、交期、采购判断（那是 SS03 / ACT-WORK-24 的事）。
+9. 执行工单缺口的处理闭环：补不了的缺口必须能以 UNKNOWN 合法放行，不得阻塞流程等人填（人可以不填）。
+10. 多候选并行：任何「单候选」假设（字段只存一个 candidate）都是错的，必须支持 N 候选独立评估与落账。
+11. 数据工单**确认即入库**：无草稿态、无审核环节，确认直接写正式库（record_status=有效）；确认人=数据责任人，系统必须留痕（确认人 / 数据工单号 / 所属活动）。
+12. 数据工单必填字段全齐才允许确认（表单级校验，不算审核）；缺必填不得放行确认。
+13. 事实/证据类记录禁止工单创建：P-06 验证记录等只能实测产生、挂任务闭环；数据工单只能建主数据/资料类记录（P-08 / P-10 / S-03 / L-02）。
+14. datasheet 选填：不得作为启动拦截条件；其有无只决定数据工单 AI 预填程度。无 datasheet 创建的数据，差异明细证据来源必须标「人工录入 · 数据工单 WO-xxx · 确认人 xxx」。
+15. 并发去重不考虑：一个活动只绑一个负责人，不实现数据工单的去重 / 合并逻辑。
+16. **一单一类（可多条）**：每张数据工单只针对一种台账，禁止混合台账；一张单可批量创建多条记录（字段即表头、每行一条）；不同台账 / 不同读数点的缺失 = 多张单（D01/D02/…，按派发顺序编号）。
+17. **惰性触发不限于启动**：每次读台账都必须做存在性检查，查无记录即派单；不得只在启动时检查一次。活动可同时等待多张数据工单，全部确认后从断点续跑。
+18. **模板统一**：数据工单只有一个统一模板（类型级，职责只有数据创建）；实例化按目标台账字段 schema（《统一方案》字段表）渲染表头，实例间仅两处可变——目标台账（决定表头 schema）、预填内容（决定行集）。
+
+---
+
+## 附：v1.2 待确认 4 项 — 落地状态
+
+素材第六节列出 4 项待确认问题。按《SS02-SS03-SS04_Demo台账字段细化与统一方案》（2026-08），本套工单的落地状态如下：
+
+| # | 待确认问题 | 落地状态 |
+|---|---|---|
+| 1 | 差异明细正式归属是什么？（P0） | **已落地**：差异明细 = P-11 差异明细子表（difference_item_id，一条参数一条记录）；验收工单 01 的 `out.difference_items` 行集即其草稿视图，含 parameter_name / original_value / candidate_value / parameter_unit / constraint_type / difference_status / evidence_ref 等字段。 |
+| 2 | P-11 何时允许写入？（P0） | **已落地**：以 analysis_status 枚举区分写入时机（AI草稿→FAE确认），客户批准独立为 customer_approval_status 字段，由审批流程维护，不由差异评估产生；验收工单 02 只写分析层（analysis_status=FAE确认），customer_approval_status 保持「未提交」。 |
+| 3 | 硬约束规则由哪个 GOV 对象维护？（P0） | rule_version 字段已落在差异明细子表（记录评估时采用的硬/软约束规则版本，本单锁 R-2026.07）；维护方归属仍待 GOV 确认（P0 遗留）。 |
+| 4 | 是否按 BOM 位独立评估？（P1） | bom_position 字段已落在 P-01 与 P-11 主记录（执行单评估输入清单以「BOM 位 bom_position」待补可编辑行承载，启动后补录，示例 U3 电源位）；多 BOM 位边界不混用，不做按位独立评估。 |
+| 5 | 冷启动与数据工单 | **已落地**：新增第三类工单「数据工单」——PN 不在库（完全没有，系统硬查询）时派发，人创建整条主数据记录，**确认即入库**（无草稿态、无审核环节），确认人=数据责任人并留痕；与执行工单「有而不全」严格区分、互不嵌套。 |

docs/SS02-ACT-WORK-05-html/ACT-WORK-05-验收工单-01-差异评估结论审核.html

@@ -0,0 +1,212 @@
+<!doctype html>
+<html lang="zh-CN">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>验收工单 1 · 差异评估结论审核 · SS02 ACT-WORK-05 差异评估</title>
+<style>
+:root{
+  --ink:#1f2329; --ink-2:#41464e; --ink-3:#646a73; --ink-4:#8f959e;
+  --line:#dee0e3; --line-soft:#e8eaed; --soft:#f8f9fb;
+  --brand:#3370ff; --brand-deep:#245bdb; --brand-soft:#e1eaff; --brand-wash:#f0f4ff;
+  --ledger:#b23a2e; --ledger-soft:#f7e4e0; --ledger-line:#ecc5bd;
+  --ok:#278717; --ok-soft:#e8f8e4; --danger:#d83931; --danger-soft:#feeae9;
+  --mono:"SF Mono",Menlo,Consolas,monospace;
+}
+*{box-sizing:border-box}
+html,body{margin:0;padding:0}
+body{font-family:Inter,ui-sans-serif,system-ui,-apple-system,BlinkMacSystemFont,"Segoe UI","PingFang SC","Microsoft YaHei",sans-serif;background:#eef1f6;color:var(--ink);font-size:14px;line-height:1.7;-webkit-font-smoothing:antialiased}
+.page{margin:0;padding:0}
+.card{background:#fff;overflow:hidden;border:0;border-radius:0;box-shadow:none}
+.card-head{display:flex;align-items:center;gap:14px;padding:18px 22px;border-bottom:2px solid var(--ink);background:linear-gradient(120deg,#fdf3f1 0%,#fff 55%,#fbf2f0 100%)}
+.badge{flex:none;width:44px;height:44px;border-radius:10px;display:grid;place-items:center;background:var(--ledger);color:#fff;font-weight:800;font-size:13px;box-shadow:0 6px 16px rgba(178,58,46,.25)}
+.tit{flex:1;min-width:0}
+.tit .kick{font-size:11px;letter-spacing:.08em;color:var(--ink-4);font-weight:700}
+.tit h1{margin:2px 0 0;font-size:19px;font-weight:800;line-height:1.3}
+.tit .sub{font-size:12px;color:var(--ink-3);margin-top:3px}
+.side{display:flex;flex-direction:column;align-items:flex-end;gap:6px;flex:none}
+.tag{font-size:11px;font-weight:800;padding:2px 10px;border-radius:999px;color:var(--ledger);background:var(--ledger-soft);border:1px solid var(--ledger-line)}
+.step{font-size:12px;color:var(--ink-3)}
+.deadline{font-size:12px;color:var(--ink-3)}
+.deadline b{color:var(--danger)}
+.card-bd{padding:20px 22px}
+.zone{font-size:11px;font-weight:800;letter-spacing:.12em;color:var(--ink-4);margin:0 0 8px}
+.zone b{color:var(--ink-3)}
+.note{border:1px solid var(--line);border-left:3px solid var(--ledger);border-radius:8px;background:var(--soft);padding:14px 16px;margin-bottom:16px}
+.note p{margin:0;font-size:13px;color:var(--ink-2)}
+.note b{color:var(--ink)}
+.criteria{border:1px solid var(--ledger-line);border-radius:10px;background:var(--ledger-soft);padding:13px 16px;margin-bottom:18px}
+.criteria .c-title{font-size:11px;font-weight:800;letter-spacing:.08em;color:var(--ledger);margin-bottom:7px}
+.criteria ul{margin:0;padding-left:18px;font-size:12.5px;color:var(--ink-2)}
+.criteria li{margin:4px 0}
+.criteria b{color:var(--ink)}
+.tbl-wrap{border:1px solid var(--line-soft);border-radius:10px;overflow:hidden}
+table{width:100%;border-collapse:collapse;font-size:13px}
+th{text-align:left;background:var(--soft);font-size:11px;letter-spacing:.05em;font-weight:800;color:var(--ink-3);padding:9px 12px;border-bottom:1px solid var(--line)}
+td{padding:11px 12px;border-bottom:1px solid var(--line-soft);vertical-align:top}
+tr:last-child td{border-bottom:0}
+.num{font-family:var(--mono);color:var(--ink-4);white-space:nowrap}
+.cust{font-weight:700}
+.prio{font-family:var(--mono);font-weight:800}
+.prio.hi{color:var(--danger)}
+.prio.mid{color:var(--ink-2)}
+.reason{font-size:12.5px;color:var(--ink-2)}
+.flow{margin-top:16px;padding:9px 12px;border-radius:8px;background:var(--soft);border:1px dashed var(--line);font-size:12px;color:var(--ink-3)}
+.flow b{color:var(--ink)}
+.card-foot{padding:13px 22px;border-top:1px solid var(--line-soft);font-size:11.5px;color:var(--ink-4);display:flex;justify-content:space-between;flex-wrap:wrap;gap:8px}
+@media(max-width:600px){.card-head{flex-wrap:wrap}.side{align-items:flex-start}}
+/* 补充：四态结论 pill 与风险等级（仅追加，不改动基件样式） */
+.st{display:inline-block;padding:1px 9px;border-radius:999px;font-size:11px;font-weight:800;letter-spacing:.04em;font-family:var(--mono);white-space:nowrap;border:1px solid transparent}
+.st.ok{color:var(--ok);background:var(--ok-soft);border-color:#bfe6b4}
+.st.miss{color:var(--danger);background:var(--danger-soft);border-color:#f3b9b5}
+.st.unknown{color:#8f6a12;background:#fdf3d7;border-color:#ecd9a0}
+.st.cond{color:var(--ledger);background:var(--ledger-soft);border-color:var(--ledger-line)}
+.risk{font-weight:800;font-size:12.5px}
+.risk.low{color:var(--ok)}
+.risk.mid{color:#8f6a12}
+.risk.hi{color:var(--danger)}
+.mono{font-family:var(--mono);font-size:12px;color:var(--ink-2)}
+</style>
+</head>
+<body>
+<div class="page">
+<div class="card">
+
+  <header class="card-head">
+    <div class="badge">验收</div>
+    <div class="tit">
+      <div class="kick">SS02 · ACT-WORK-05 差异评估 · 验收工单 1/2</div>
+      <h1>差异评估结论审核</h1>
+      <div class="sub">收件人：<span data-slot="meta.task.owner">FAE · 李工</span> · 关联任务：<span data-slot="meta.task.id">TASK-BT02-20260818-007</span></div>
+    </div>
+    <div class="side">
+      <span class="tag">验收工单</span>
+      <span class="step" data-slot="meta.phase">步骤 3~4/5 · 逐项差异评估 + FAE/RI 审核</span>
+      <span class="deadline">最迟交回：<b data-slot="card.deadline">1 个工作日</b></span>
+    </div>
+  </header>
+
+  <div class="card-bd">
+
+    <p class="zone"><b>【AI 结论说明】</b>—— 结论是怎么算出来的</p>
+    <div class="note">
+      <p><b>AI 已完成的计算</b>：按 GOV 评估规则（锁定版本 <b>R-2026.07</b>，rule_version），对 Original=<b>LM2596S-5.0（TI）</b> / Candidate=<b>XL2596S-5.0（XLSEMI）</b> 逐项比对，产出四态结论——<b>MATCH / MISMATCH / UNKNOWN / CONDITIONAL</b>，并给出风险等级、证据引用与置信度。差异明细 = <b>P-11 差异明细子表</b>（一条参数差异一条记录，difference_item_id）；当前为 AI 草稿，<b>FAE 审核通过前不落账</b>。评估参数可能含本次数据工单创建的主数据（确认人背书；未附 datasheet 的参数项会显式标注「人工录入」）。</p>
+    </div>
+
+    <p class="zone"><b>【验收判据】</b>—— 你据此判断「通过 / 驳回」</p>
+    <div class="criteria">
+      <div class="c-title">判断这份差异评估结论是否可信，请逐项核对</div>
+      <ul>
+        <li><b>关键参数差异均有明确状态</b>：逐项结论无漏项，每个参数都有四态之一的判定；</li>
+        <li><b>UNKNOWN 项均有去向</b>：每个 UNKNOWN 都挂了验证任务（如 VAL-2026-0188）或补来源动作，不允许悬空；</li>
+        <li><b>证据链完整</b>：每项结论可追溯至 P-08 / P-10 / P-06 或 EXT-02 的具体记录，或追溯至数据工单创建记录（标注：人工录入 · 数据工单号 · 确认人）；</li>
+        <li><b>硬约束项未被自动判 MATCH</b>：封装 / 工艺等硬约束未经证据支持不得判 MATCH。</li>
+      </ul>
+    </div>
+
+    <p class="zone"><b>【AI 产出的差异明细】</b>—— 只读展示（P-11 差异明细子表草稿 · 一条参数一条记录 difference_item_id）</p>
+    <div class="tbl-wrap">
+      <table>
+        <thead><tr><th style="width:40px">#</th><th data-h="参数项 parameter_name">参数项 parameter_name</th><th data-h="原PN值 original_value">原 PN 值 original_value</th><th data-h="候选PN值 candidate_value">候选 PN 值 candidate_value</th><th data-h="单位 parameter_unit">单位 parameter_unit</th><th data-h="约束类型 constraint_type">约束类型 constraint_type</th><th data-h="结论 difference_status">结论 difference_status</th><th data-h="风险等级">风险等级</th><th data-h="证据引用 evidence_ref">证据引用 evidence_ref</th><th data-h="AI置信度">AI 置信度</th></tr></thead>
+        <tbody data-rows="out.difference_items">
+          <tr>
+            <td class="num">1</td>
+            <td data-field="parameter_name" class="cust">输出电压</td>
+            <td data-field="original_value" class="mono">5.0</td>
+            <td data-field="candidate_value" class="mono">5.0</td>
+            <td data-field="parameter_unit">V</td>
+            <td data-field="constraint_type">硬约束</td>
+            <td data-field="difference_status"><span class="st ok">MATCH</span></td>
+            <td data-field="risk_level"><span class="risk low">低</span></td>
+            <td data-field="evidence_ref" class="mono">P-08 · P-10</td>
+            <td data-field="confidence" class="mono">0.98</td>
+          </tr>
+          <tr>
+            <td class="num">2</td>
+            <td data-field="parameter_name" class="cust">输出电流</td>
+            <td data-field="original_value" class="mono">3</td>
+            <td data-field="candidate_value" class="mono">3</td>
+            <td data-field="parameter_unit">A</td>
+            <td data-field="constraint_type">硬约束</td>
+            <td data-field="difference_status"><span class="st ok">MATCH</span></td>
+            <td data-field="risk_level"><span class="risk low">低</span></td>
+            <td data-field="evidence_ref" class="mono">P-08 · P-10</td>
+            <td data-field="confidence" class="mono">0.97</td>
+          </tr>
+          <tr>
+            <td class="num">3</td>
+            <td data-field="parameter_name" class="cust">开关频率</td>
+            <td data-field="original_value" class="mono">150</td>
+            <td data-field="candidate_value" class="mono">150</td>
+            <td data-field="parameter_unit">kHz</td>
+            <td data-field="constraint_type">硬约束</td>
+            <td data-field="difference_status"><span class="st ok">MATCH</span></td>
+            <td data-field="risk_level"><span class="risk low">低</span></td>
+            <td data-field="evidence_ref" class="mono">P-08 · P-10</td>
+            <td data-field="confidence" class="mono">0.95</td>
+          </tr>
+          <tr>
+            <td class="num">4</td>
+            <td data-field="parameter_name" class="cust">封装</td>
+            <td data-field="original_value" class="mono">TO-263-5</td>
+            <td data-field="candidate_value" class="mono">TO-263-5</td>
+            <td data-field="parameter_unit">—</td>
+            <td data-field="constraint_type">硬约束</td>
+            <td data-field="difference_status"><span class="st ok">MATCH</span></td>
+            <td data-field="risk_level"><span class="risk low">低</span></td>
+            <td data-field="evidence_ref" class="mono">P-08 · P-10</td>
+            <td data-field="confidence" class="mono">0.99</td>
+          </tr>
+          <tr>
+            <td class="num">5</td>
+            <td data-field="parameter_name" class="cust">工作温度</td>
+            <td data-field="original_value" class="mono">-40~+85</td>
+            <td data-field="candidate_value" class="mono">-40~+125</td>
+            <td data-field="parameter_unit">℃</td>
+            <td data-field="constraint_type">硬约束</td>
+            <td data-field="difference_status"><span class="st miss">MISMATCH</span></td>
+            <td data-field="risk_level"><span class="risk hi">高</span></td>
+            <td data-field="evidence_ref" class="mono">P-10</td>
+            <td data-field="confidence" class="mono">0.93</td>
+          </tr>
+          <tr>
+            <td class="num">6</td>
+            <td data-field="parameter_name" class="cust">使能阈值</td>
+            <td data-field="original_value" class="mono">1.4</td>
+            <td data-field="candidate_value" class="mono">未披露</td>
+            <td data-field="parameter_unit">V</td>
+            <td data-field="constraint_type">硬约束</td>
+            <td data-field="difference_status"><span class="st unknown">UNKNOWN</span></td>
+            <td data-field="risk_level"><span class="risk mid">中</span></td>
+            <td data-field="evidence_ref" class="mono">挂 VAL-2026-0188</td>
+            <td data-field="confidence" class="mono">—</td>
+          </tr>
+          <tr>
+            <td class="num">7</td>
+            <td data-field="parameter_name" class="cust">生命周期</td>
+            <td data-field="original_value" class="mono">Active</td>
+            <td data-field="candidate_value" class="mono">Active</td>
+            <td data-field="parameter_unit">—</td>
+            <td data-field="constraint_type">软约束</td>
+            <td data-field="difference_status"><span class="st cond">CONDITIONAL</span></td>
+            <td data-field="risk_level"><span class="risk mid">中</span></td>
+            <td data-field="evidence_ref" class="mono">P-10（候选供货承诺函）</td>
+            <td data-field="confidence" class="mono">0.90</td>
+          </tr>
+        </tbody>
+      </table>
+    </div>
+
+    <div class="flow"><b>审批：</b>本工单只承载内容；「通过 / 驳回」请在对话区的【验收卡】中进行。审核意见与补充条件写入 P-06（验证要求 verification_requirement）；<b>通过后去向：</b>进入步骤 5 · 评审放行与落账确认。</div>
+
+  </div>
+
+  <footer class="card-foot">
+    <span>SS02 · ACT-WORK-05 差异评估 · 验收工单 1/2 · 差异评估结论审核</span>
+    <span style="font-family:'SF Mono',Menlo,Consolas,monospace">工单类型：验收 · <span data-slot="card.id">WO-ACT-WORK-05-02</span></span>
+  </footer>
+
+</div>
+</div>
+</body>
+</html>

docs/SS02-ACT-WORK-05-html/ACT-WORK-05-验收工单-02-评审放行与落账确认.html

@@ -0,0 +1,226 @@
+<!doctype html>
+<html lang="zh-CN">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>验收工单 2 · 评审放行与落账确认 · SS02 ACT-WORK-05 差异评估</title>
+<style>
+:root{
+  --ink:#1f2329; --ink-2:#41464e; --ink-3:#646a73; --ink-4:#8f959e;
+  --line:#dee0e3; --line-soft:#e8eaed; --soft:#f8f9fb;
+  --brand:#3370ff; --brand-deep:#245bdb; --brand-soft:#e1eaff; --brand-wash:#f0f4ff;
+  --ledger:#b23a2e; --ledger-soft:#f7e4e0; --ledger-line:#ecc5bd;
+  --ok:#278717; --ok-soft:#e8f8e4; --danger:#d83931; --danger-soft:#feeae9;
+  --mono:"SF Mono",Menlo,Consolas,monospace;
+}
+*{box-sizing:border-box}
+html,body{margin:0;padding:0}
+body{font-family:Inter,ui-sans-serif,system-ui,-apple-system,BlinkMacSystemFont,"Segoe UI","PingFang SC","Microsoft YaHei",sans-serif;background:#eef1f6;color:var(--ink);font-size:14px;line-height:1.7;-webkit-font-smoothing:antialiased}
+.page{margin:0;padding:0}
+.card{background:#fff;overflow:hidden;border:0;border-radius:0;box-shadow:none}
+.card-head{display:flex;align-items:center;gap:14px;padding:18px 22px;border-bottom:2px solid var(--ink);background:linear-gradient(120deg,#fdf3f1 0%,#fff 55%,#fbf2f0 100%)}
+.badge{flex:none;width:44px;height:44px;border-radius:10px;display:grid;place-items:center;background:var(--ledger);color:#fff;font-weight:800;font-size:13px;box-shadow:0 6px 16px rgba(178,58,46,.25)}
+.tit{flex:1;min-width:0}
+.tit .kick{font-size:11px;letter-spacing:.08em;color:var(--ink-4);font-weight:700}
+.tit h1{margin:2px 0 0;font-size:19px;font-weight:800;line-height:1.3}
+.tit .sub{font-size:12px;color:var(--ink-3);margin-top:3px}
+.side{display:flex;flex-direction:column;align-items:flex-end;gap:6px;flex:none}
+.tag{font-size:11px;font-weight:800;padding:2px 10px;border-radius:999px;color:var(--ledger);background:var(--ledger-soft);border:1px solid var(--ledger-line)}
+.step{font-size:12px;color:var(--ink-3)}
+.deadline{font-size:12px;color:var(--ink-3)}
+.deadline b{color:var(--danger)}
+.card-bd{padding:20px 22px}
+.zone{font-size:11px;font-weight:800;letter-spacing:.12em;color:var(--ink-4);margin:0 0 8px}
+.zone b{color:var(--ink-3)}
+.note{border:1px solid var(--line);border-left:3px solid var(--ledger);border-radius:8px;background:var(--soft);padding:14px 16px;margin-bottom:16px}
+.note p{margin:0;font-size:13px;color:var(--ink-2)}
+.note b{color:var(--ink)}
+.criteria{border:1px solid var(--ledger-line);border-radius:10px;background:var(--ledger-soft);padding:13px 16px;margin-bottom:18px}
+.criteria .c-title{font-size:11px;font-weight:800;letter-spacing:.08em;color:var(--ledger);margin-bottom:7px}
+.criteria ul{margin:0;padding-left:18px;font-size:12.5px;color:var(--ink-2)}
+.criteria li{margin:4px 0}
+.criteria b{color:var(--ink)}
+.tbl-wrap{border:1px solid var(--line-soft);border-radius:10px;overflow:hidden}
+table{width:100%;border-collapse:collapse;font-size:13px}
+th{text-align:left;background:var(--soft);font-size:11px;letter-spacing:.05em;font-weight:800;color:var(--ink-3);padding:9px 12px;border-bottom:1px solid var(--line)}
+td{padding:11px 12px;border-bottom:1px solid var(--line-soft);vertical-align:top}
+tr:last-child td{border-bottom:0}
+.num{font-family:var(--mono);color:var(--ink-4);white-space:nowrap}
+.cust{font-weight:700}
+.prio{font-family:var(--mono);font-weight:800}
+.prio.hi{color:var(--danger)}
+.prio.mid{color:var(--ink-2)}
+.reason{font-size:12.5px;color:var(--ink-2)}
+.flow{margin-top:16px;padding:9px 12px;border-radius:8px;background:var(--soft);border:1px dashed var(--line);font-size:12px;color:var(--ink-3)}
+.flow b{color:var(--ink)}
+.card-foot{padding:13px 22px;border-top:1px solid var(--line-soft);font-size:11.5px;color:var(--ink-4);display:flex;justify-content:space-between;flex-wrap:wrap;gap:8px}
+@media(max-width:600px){.card-head{flex-wrap:wrap}.side{align-items:flex-start}}
+/* 补充：推荐等级 pill 与状态强调（仅追加，不改动基件样式） */
+.st{display:inline-block;padding:1px 9px;border-radius:999px;font-size:11px;font-weight:800;letter-spacing:.04em;font-family:var(--mono);white-space:nowrap;border:1px solid transparent}
+.st.ok{color:var(--ok);background:var(--ok-soft);border-color:#bfe6b4}
+.st.miss{color:var(--danger);background:var(--danger-soft);border-color:#f3b9b5}
+.st.unknown{color:#8f6a12;background:#fdf3d7;border-color:#ecd9a0}
+.st.cond{color:var(--ledger);background:var(--ledger-soft);border-color:var(--ledger-line)}
+.risk{font-weight:800;font-size:12.5px}
+.risk.mid{color:#8f6a12}
+.mono{font-family:var(--mono);font-size:12px;color:var(--ink-2)}
+.tbl-gap{margin-top:18px}
+</style>
+</head>
+<body>
+<div class="page">
+<div class="card">
+
+  <header class="card-head">
+    <div class="badge">验收</div>
+    <div class="tit">
+      <div class="kick">SS02 · ACT-WORK-05 差异评估 · 验收工单 2/2</div>
+      <h1>评审放行与落账确认</h1>
+      <div class="sub">收件人：<span data-slot="meta.task.owner">FAE · 李工</span> · 关联任务：<span data-slot="meta.task.id">TASK-BT02-20260818-007</span></div>
+    </div>
+    <div class="side">
+      <span class="tag">验收工单</span>
+      <span class="step" data-slot="meta.phase">步骤 5/5 · 提交 ACT-GATE-03</span>
+      <span class="deadline">最迟交回：<b data-slot="card.deadline">1 个工作日</b></span>
+    </div>
+  </header>
+
+  <div class="card-bd">
+
+    <p class="zone"><b>【AI 结论说明】</b>—— 本单确认什么</p>
+    <div class="note">
+      <p><b>本活动以 ACT-GATE-03 评审放行为终点。</b>本单确认拟落账内容：评估结论层写 <b>P-11 替代关系主记录</b>（替代类型 substitution_type / 原内部料号 original_internal_pn / 候选内部料号 candidate_internal_pn / 推荐等级 recommendation_level / 推荐理由 / 差异摘要 / 替代分析报告 / 分析状态 analysis_status / 风险等级 / 验证要求 / 证据可信度 / 差异规则版本），需求状态回写 <b>P-01</b>（风险等级 / 验证要求 / 输出链接 / 下一步动作 / 当前阶段）。<b>客户批准不属于本活动</b>——客户批准状态 customer_approval_status 由审批流程维护，本单只写分析层（analysis_status=FAE确认），customer_approval_status 保持「未提交」，不由差异评估产生。</p>
+    </div>
+
+    <p class="zone"><b>【验收判据】</b>—— 你据此判断「通过 / 驳回」</p>
+    <div class="criteria">
+      <div class="c-title">放行与落账前，请逐项核对</div>
+      <ul>
+        <li><b>推荐等级与差异明细一致</b>：差异明细中存在 UNKNOWN / CONDITIONAL 时，推荐等级 recommendation_level 不得给「推荐」；</li>
+        <li><b>分析状态与客户批准状态分离</b>：本单只写分析层（analysis_status=FAE确认），customer_approval_status 保持「未提交」，不由差异评估产生；</li>
+        <li><b>GOV 规则版本已锁定</b>：本次评估按 R-2026.07 执行，rule_version 随结论一并落账；</li>
+        <li><b>回写 P-01 字段完整</b>：风险等级、验证要求、输出链接、下一步动作、当前阶段五项齐全。</li>
+      </ul>
+    </div>
+
+    <p class="zone"><b>【拟写 P-11 · 替代关系主记录】</b>—— 只读展示</p>
+    <div class="tbl-wrap">
+      <table>
+        <thead><tr><th style="width:40px">#</th><th style="width:180px" data-h="字段">字段</th><th data-h="拟写入值">拟写入值</th></tr></thead>
+        <tbody data-rows="out.ledger_p11">
+          <tr>
+            <td class="num">1</td>
+            <td data-field="field" class="cust">替代类型 substitution_type</td>
+            <td data-field="value">Pin-to-Pin（BT-02 跨品牌）</td>
+          </tr>
+          <tr>
+            <td class="num">2</td>
+            <td data-field="field" class="cust">原内部料号 original_internal_pn</td>
+            <td data-field="value" class="mono">LM2596S-5.0（TI）</td>
+          </tr>
+          <tr>
+            <td class="num">3</td>
+            <td data-field="field" class="cust">候选内部料号 candidate_internal_pn</td>
+            <td data-field="value" class="mono">XL2596S-5.0（XLSEMI）</td>
+          </tr>
+          <tr>
+            <td class="num">4</td>
+            <td data-field="field" class="cust">推荐等级 recommendation_level</td>
+            <td data-field="value"><span class="st cond">条件推荐</span> <span class="reason">（枚举：推荐 / 条件推荐 / 备选 / 不推荐，四态之一）</span></td>
+          </tr>
+          <tr>
+            <td class="num">5</td>
+            <td data-field="field" class="cust">推荐理由 recommendation_reason</td>
+            <td data-field="value">温度范围候选更优，使能阈值待 VAL-2026-0188 闭环</td>
+          </tr>
+          <tr>
+            <td class="num">6</td>
+            <td data-field="field" class="cust">差异摘要 difference_summary</td>
+            <td data-field="value">7 项比对：4 MATCH / 1 MISMATCH / 1 UNKNOWN / 1 CONDITIONAL</td>
+          </tr>
+          <tr>
+            <td class="num">7</td>
+            <td data-field="field" class="cust">替代分析报告 analysis_report_ref</td>
+            <td data-field="value" class="mono">RPT-2026-0188</td>
+          </tr>
+          <tr>
+            <td class="num">8</td>
+            <td data-field="field" class="cust">分析状态 analysis_status</td>
+            <td data-field="value"><span class="st ok">FAE确认</span> <span class="reason">（枚举：AI草稿 / FAE确认 / 待客户验证 / 客户已批准 / 不批准 / 作废）</span></td>
+          </tr>
+          <tr>
+            <td class="num">9</td>
+            <td data-field="field" class="cust">客户批准状态 customer_approval_status</td>
+            <td data-field="value">未提交 <span class="reason">（由审批流程维护，本活动不产生）</span></td>
+          </tr>
+          <tr>
+            <td class="num">10</td>
+            <td data-field="field" class="cust">风险等级 risk_level</td>
+            <td data-field="value"><span class="risk mid">中</span></td>
+          </tr>
+          <tr>
+            <td class="num">11</td>
+            <td data-field="field" class="cust">验证要求 verification_requirement</td>
+            <td data-field="value" class="mono">VAL-2026-0188（使能阈值实测）</td>
+          </tr>
+          <tr>
+            <td class="num">12</td>
+            <td data-field="field" class="cust">证据可信度 confidence_score</td>
+            <td data-field="value" class="mono">0.93</td>
+          </tr>
+          <tr>
+            <td class="num">13</td>
+            <td data-field="field" class="cust">差异规则版本 rule_version</td>
+            <td data-field="value" class="mono">R-2026.07</td>
+          </tr>
+        </tbody>
+      </table>
+    </div>
+
+    <p class="zone tbl-gap"><b>【拟回写 P-01 · 需求状态】</b>—— 只读展示</p>
+    <div class="tbl-wrap">
+      <table>
+        <thead><tr><th style="width:40px">#</th><th style="width:180px" data-h="字段">字段</th><th data-h="拟写入值">拟写入值</th></tr></thead>
+        <tbody data-rows="out.writeback_p01">
+          <tr>
+            <td class="num">1</td>
+            <td data-field="field" class="cust">风险等级 risk_level</td>
+            <td data-field="value"><span class="risk mid">中</span> <span class="reason">（2 项待闭环）</span></td>
+          </tr>
+          <tr>
+            <td class="num">2</td>
+            <td data-field="field" class="cust">验证要求 verification_requirement</td>
+            <td data-field="value" class="mono">VAL-2026-0188（使能阈值实测）</td>
+          </tr>
+          <tr>
+            <td class="num">3</td>
+            <td data-field="field" class="cust">输出链接 output_ref</td>
+            <td data-field="value" class="mono">RPT-2026-0188</td>
+          </tr>
+          <tr>
+            <td class="num">4</td>
+            <td data-field="field" class="cust">下一步动作 next_action</td>
+            <td data-field="value">提交 ACT-GATE-03</td>
+          </tr>
+          <tr>
+            <td class="num">5</td>
+            <td data-field="field" class="cust">当前阶段 current_stage</td>
+            <td data-field="value">提交 ACT-GATE-03</td>
+          </tr>
+        </tbody>
+      </table>
+    </div>
+
+    <div class="flow"><b>审批：</b>本工单只承载内容；「通过 / 驳回」请在对话区的【验收卡】中进行。<b>通过后去向：</b>在对话区卡提交 ACT-GATE-03 评审放行；放行后结论供 ACT-WORK-08 证据归集消费。</div>
+
+  </div>
+
+  <footer class="card-foot">
+    <span>SS02 · ACT-WORK-05 差异评估 · 验收工单 2/2 · 评审放行与落账确认</span>
+    <span style="font-family:'SF Mono',Menlo,Consolas,monospace">工单类型：验收 · <span data-slot="card.id">WO-ACT-WORK-05-03</span></span>
+  </footer>
+
+</div>
+</div>
+</body>
+</html>

docs/SS02-ACT-WORK-05-html/SS02-SS03-SS04_Demo台账字段细化与统一方案.md

@@ -0,0 +1,632 @@
+# SS02—SS03—SS04 Demo台账字段细化与统一方案
+
+## 一、结论摘要
+
+本成果以《SS01-02-03-04-台账体系全景-18Activity关联矩阵》的台账编号为唯一编号标准，对六组Demo Activity进行字段级反推和补齐：[1] [2] [3] [4] [5] [6]。结论是：**当前全景体系的台账编号总体可承载Demo，但核心内容描述仍不足以直接支撑执行，必须补充字段级定义、条件必填规则和主记录/子表结构。**
+
+本方案将Demo中的细分编号按全景标准归并，例如P-01-01→P-01、P-08-01→P-08、P-11-01/P-11-02→P-11的不同关系状态或子对象；不新增与全景体系冲突的台账编号。[1] [2] [3] 对于逐参数差异、逐报价阶梯和逐份单证等重复明细，采用子表承载，避免在单一文本字段中堆叠数据。
+
+## 二、编号归并与建模原则
+
+> **编号原则：**全景矩阵的44个台账编号是主键标准；Demo中的-01/-02属于局部架构或对象层标识，除非全景矩阵明确存在对应台账，否则不作为新的全景台账编号。
+
+|Demo原编号/写法|统一全景编号|统一后的对象/说明|
+|---|---|---|
+|P-01-01|P-01|客户具体需求与项目任务主台账；任务、需求版本、报价上下文和Activity回链统一归入。|
+|P-06-01|P-06|样品交付与芯片验证记录台账；验证事实与样品追溯统一归入。|
+|P-08-01|P-08|芯片主数据台账；全链路只认internal_pn。|
+|P-09-02|P-09|客户技术与机会档案；技术档案字段统一挂客户ID。|
+|P-10-01/02/03|P-10|原厂技术资料库；资料类型由document_type区分。|
+|P-11-01/P-11-02|P-11|替代选型与批准关系库；analysis_status与customer_approval_status分离，差异明细设子表。|
+|P-04-01/P-04-02|P-04|交易框架与承诺台账；框架主记录与承诺子记录分层。|
+|D-01物流F组/交接E组|D-01|交易与执行台账；交接事实与物流节点作为不同对象层，但共享order_id。|
+
+## 三、Activity覆盖校验
+
+下表说明每个Demo的关键读写台账、字段补足点和覆盖结论。[1] [2] [3] [4] [5] [6]
+
+|Activity|原矩阵台账编号|统一台账编号|主写入台账|关键新增/细化字段|覆盖结论|
+|---|---|---|---|---|---|
+|ACT-WORK-05 差异评估|P-01-01、P-06-01、P-08-01、P-09-02、P-10-01/02/03、P-11-01、P-11-02、GOV|P-01、P-06、P-08、P-09、P-10、P-11、GOV|P-01、P-11；条件写P-06|requirement_version、input_snapshot_ref、bom_position、normalized_parameter_set、difference_item_id、difference_status、impact_statement、constraint_type、rule_version、confidence_score|已覆盖；差异明细由P-11差异明细子表承载，客户批准状态与差异分析状态分离。|
+|ACT-WORK-24 报价方案制定|P-01-01、P-02-01、P-03-01、P-04-01/02、P-06-01、P-08-01、P-11-02、GOV|P-01、P-02、P-03、P-04、P-06、P-08、P-11、GOV|P-02；回写P-01|quote_version、quote_type、quote_valid_until、delivery_commitment、payment_terms、tax_terms、incoterms、exchange_rate、gross_margin_status、rule_version、QuoteLine、blocking_reason、substitution_approval_status|已覆盖；P-02采用主记录+QuoteLine明细结构，正式发布与AI草稿以状态和版本区分。|
+|SS03 Activity 1 发起询价|P-01、D-15、P-08、S-03、S-05、S-04|P-01、D-15、P-08、S-03、S-05、S-04|S-04 RFQ层；条件写S-03|source_type/source_id、rfq_batch_id、rfq_line_id、quote_due_at、outbound_content_ref、sent_evidence_ref、reminder_count、last_reminded_at、overdue_flag、temporary_supplier_flag|已覆盖；最小粒度固定为询价批次×供应商×内部料号。|
+|SS03 Activity 2 回填报价/比价/定点|P-01、D-15、P-08、S-03、S-05、S-04|P-01、D-15、P-08、S-03、S-05、S-04|S-04 Quote/Decision层|supplier_quote_id、quote_revision_no、comparability_status、comparison_basis_snapshot_ref、baseline_match_status、baseline_unit_price、comparison_currency_code、conversion_rate、price_variance_pct、selected_supplier_id、selected_quote_id、unselected_reason、notification_recipient_ref、score_rule_version|已覆盖；跨币种、无基准、不可比、涨幅>10%、代理证及临时供应商门禁均有字段承载。|
+|ACT-11-A2 提货交接与风险转移|D-01、D-03、D-10、D-11、L-02、P-08、D-04|D-01、D-03、D-10、D-11、L-02、P-08、D-04|D-01、D-03；触发D-04相关门禁|allocation_ref、handover_no、receiver_name、sign_time、risk_transfer_time、handover_diff、handover_file_ref、handover_doc_status、handover_notes、document_set_complete、consistency_check_status、allocation_status、last_ship_date|已覆盖；交接事实、风险转移派生、文件状态、单证门禁和库存同步均已落台账。|
+|ACT-11-A3 物流执行信息跟踪|D-01、D-10|D-01、D-10|D-01物流节点事实层|logi_pickup/logi_clearance/logi_release/logi_departure（统一节点结构）、track_note、track_visible、logistics_confirmation_channel、logistics_confirmation_interval_days、logistics_max_reminder_count、alert_thresholds|已覆盖；每个节点包含预计时间、实际时间、来源、采集方式、确认状态、异常标记和证据引用。|
+
+## 四、字段统一总表
+
+### 4.1 通用治理字段
+
+以下字段建议作为所有涉及Demo台账的通用治理字段继承，但不要求在每张业务台账中重复手工维护。`record_status`只管理记录生命周期；`*_status`管理具体业务过程；`evidence_ref`用于AI和人工结果的可审计回链。
+
+|统一字段名|中文字段名|数据类型|必填性|维护/来源|Demo使用|定义/取值/校验规则|
+|---|---|---|---|---|---|---|
+|record_id|记录ID|Text/AutoNumber|是|系统|所有Demo|每条台账记录的唯一主键；业务编号不能替代数据库主键。|
+|record_status|记录状态|Enum|是|台账Owner|所有Demo|有效/草稿/归档/作废；不得用业务过程状态替代记录生命周期状态。|
+|record_version|记录版本|Text/Integer|是|系统/Owner|W05/W24/SS03/11-A2/11-A3|每次影响业务判断的修改递增；报价、价格、规则、客户映射必须可回溯。|
+|source_type|来源类型|Enum|条件必填|系统/上游Owner|W05/W24/SS03/11-A2|来源对象的类型，如客户需求、采购计划、价格维护、异常补货、订单、外部回复。|
+|source_id|来源对象ID|Text/Link|条件必填|系统/上游Owner|W05/W24/SS03/11-A2|与source_type成对出现；不得把说明文字写入ID字段。|
+|data_owner|数据Owner|Link|是|台账Owner|所有Demo|负责定义、质量和变更审批的角色或人员。|
+|evidence_ref|证据引用|URL/Attachment/Structure|条件必填|AI/PW/Owner|W05/W24/SS03/11-A2/11-A3|指向原始邮件、聊天记录、签署件、数据表、资料页码或其他证据；可多值。|
+|created_at|创建时间|DateTime|系统|系统|所有Demo|系统生成。|
+|updated_at|更新时间|DateTime|系统|系统|所有Demo|系统生成。|
+|last_verified_at|最后核验时间|DateTime|条件必填|Owner/PW/FAE/采购|所有Demo|对影响下游决策的事实标记最近一次人工或规则核验时间。|
+
+### 4.2 按全景台账编号展开的字段
+
+#### P-01 客户具体需求与项目任务主台账
+
+|统一字段名|中文字段名|数据类型|必填性|对象层|维护/来源|Demo使用|定义/取值/校验规则|处理建议|原字段/来源名称|
+|---|---|---|---|---|---|---|---|---|---|
+|request_id|需求编号|Text/AutoNumber|是|主记录|SS02|W05/W24/SS03-1/SS03-2/D-01|客户需求与项目任务主记录的统一业务键；SS03写入S-04.source_id。|重命名/统一|任务ID、request_id、需求编号|
+|customer_id|客户ID|Link|是|主记录|L-02/SS02|W05/W24/SS03-1/SS03-2|统一关联L-02；需求没有客户时需明确内部需求标识。|保留/细化|customer_id、客户|
+|project_id|项目ID|Link|条件必填|主记录|P-05/SS02|W05/W24/SS03-1/SS03-2|有项目场景必填；与客户ID共同确定需求归属和结果通知对象。|新增/细化|project_id、客户/项目|
+|requirement_version|需求版本|Text|是|主记录|SS02/系统|W05/W24|需求基线版本；差异评估与报价均按版本回溯。|新增/统一|任务描述/需求版本、版本|
+|request_type|需求类型|Enum|是|主记录|SS02/系统|W05/W24/SS03|客户需求/RFQ/询价/技术需求/价格维护/其他；采购来源可由source_type补充。|新增/统一|需求类型、RFQ类型|
+|request_description|需求描述|LongText|是|主记录|SS02/需求Owner|W05/W24|保留原始需求语义，不能只保留结构化字段。|新增/细化|任务描述|
+|input_snapshot_ref|输入快照|URL/Attachment/Structure|W05必填；W24条件|主记录|系统/AI|W05/W24|记录本次评估或报价运行时的输入快照，支持版本回溯。|新增|输入快照|
+|bom_id|BOM ID|Link|条件必填|主记录|SS02|W05/W24|有BOM场景必填；与bom_position一并确定物料位置。|新增|BOM范围|
+|bom_position|BOM位|Text|条件必填|主记录|SS02/FAE|W05/W24|按BOM位记录原物料、替代物料和报价明细；不同BOM位批准边界不得混用。|新增|BOM位、PN/BOM范围|
+|original_internal_pn|原内部料号|Link(P-08)|W05必填；其他条件|主记录|P-08/FAE|W05/W24|差异评估基准；引用P-08.internal_pn。|重命名/统一|原型号/原PN、原PN|
+|candidate_internal_pn|候选内部料号|Link(P-08)|W05条件；W24条件|主记录|P-08/FAE|W05/W24|候选替代物料；多个候选应进入P-11子记录而非逗号拼接。|重命名/统一|候选PN、Candidate_PN|
+|customer_pn|客户料号|Text|条件必填|主记录|L-02/D-10映射|W24/SS03/D-01|若客户使用客户料号，保留并与internal_pn分开。|新增/统一|customer_mpn、客户料号|
+|application_scenario|应用场景|LongText/Enum|W05必填；W24条件|主记录|FAE/客户|W05/W24|解释需求约束、验证条件与报价适用场景。|保留/细化|应用场景、适配场景|
+|target_qty|目标数量|Number/Structure|W24/SS03必填|主记录|需求Owner/采购|W24/SS03-1/SS03-2|正式报价、询价与比价的数量基准；阶梯放入数量阶梯子表。|重命名/统一|数量、target_qty、报价类型/数量|
+|target_delivery_date|目标交期|Date|W24/SS03必填|主记录|需求Owner/采购|W24/SS03-1/SS03-2|正式报价、询价与比价的日期基准。|重命名/统一|target_delivery_date、目标交期|
+|target_price_internal|内部目标价|Currency|否|主记录|SS02|W24/SS03|仅内部判断；默认不对外发送；币种必须同时记录。|保留/细化|target_price_internal、目标价|
+|target_price_currency_code|内部目标价币种|ISO 4217 Enum|target_price有值时必填|主记录|SS02|W24/SS03|与target_price_internal成对出现。|新增/统一|currency|
+|requested_price_types|所需价格类型|MultiEnum|SS03必填；W24条件|主记录|需求Owner/采购|W24/SS03-1/SS03-2|参考价/量产价/现货价/样品价；上游默认值可补充，删除或替换需留痕。|重命名/统一|price_types_default、price_types_requested、报价类型|
+|quote_due_at|期望报价返回时间|DateTime|SS03必填；W24条件|主记录|需求Owner/采购|W24/SS03-1/SS03-2|客户需求来源从P-01读取；内部或维护型询价由采购填写。|重命名/统一|quote_return_due_at、quote_due_at、截止时间|
+|technical_constraints|技术约束|Structure|W05/W24条件|主记录|FAE/AI|W05/W24|包含参数、单位、版本、硬约束/软约束，供差异评估和报价前提检查。|新增|参数边界、硬/软约束|
+|risk_level|风险等级|Enum|W05/W24条件|主记录|FAE/BDPM|W05/W24|低/中/高/关键；必须记录确认人和时间。|统一|FAE人工判断/风险等级、风险等级|
+|verification_requirement|验证/复测/确认要求|LongText/Structure|W05条件；W24条件|主记录|FAE|W05/W24|用于关闭UNKNOWN或CONDITIONAL，并可回链P-06验证记录。|重命名/统一|验证/复测/确认要求、验证要求|
+|latest_quote_id|最新报价ID|Link(P-02)|W24/SS03条件|主记录|系统|W24/SS03-2|聚合P-02最新有效报价，不直接复制价格。|新增|关联报价、最新报价状态|
+|latest_quote_status|最新报价状态|Lookup/Enum|W24/SS03条件|主记录|系统|W24/SS03-2|由P-02.quote_status/publish_status聚合。|重命名/统一|最新报价状态、报价状态|
+|request_status|需求状态|Enum|是|主记录|SS02|W05/W24/SS03|待处理/已响应/已成交/已放弃/关闭；不得与Activity运行状态混用。|重命名/统一|状态机、需求状态|
+|current_activity|当前Activity|Link/Enum|W05/W24条件|主记录|系统|W05/W24|如ACT-WORK-05、ACT-WORK-24；用于流程位置显示。|重命名/统一|当前Activity|
+|current_stage|当前阶段|Enum/Text|W05/W24条件|主记录|系统/Owner|W05/W24|评估、报价、审批、发布等阶段。|新增/统一|当前阶段|
+|next_action|下一步动作|LongText|W05/W24条件|主记录|FAE/BDPM/系统|W05/W24|明确责任人、动作和截止时间。|统一|下一步动作|
+|output_ref|标准输出链接|URL/Attachment|W05/W24条件|主记录|系统/FAE/BDPM|W05/W24|差异报告或报价文件的正式输出链接。|重命名/统一|标准输出类型/输出文件链接、输出链接|
+
+#### P-02 报价与商务记录台账
+
+|统一字段名|中文字段名|数据类型|必填性|对象层|维护/来源|Demo使用|定义/取值/校验规则|处理建议|原字段/来源名称|
+|---|---|---|---|---|---|---|---|---|---|
+|quote_id|报价ID|Text/AutoNumber|是|报价主记录|系统|W24/SS03-2|报价主记录唯一标识。|保留/细化|报价ID|
+|request_id|关联需求编号|Link(P-01)|是|报价主记录|系统|W24/SS03-2|回链P-01.request_id。|重命名/统一|关联任务、关联需求号|
+|quote_version|报价版本|Text|是|报价主记录|系统/BDPM|W24|同一需求条件变化创建新版本；旧版本保留不可覆盖。|新增/统一|报价版本、版本|
+|quote_type|报价类型|Enum|是|报价主记录|BDPM|W24|正式报价/参考价/项目报价/其他；与price_type（明细价格类型）区分。|新增/统一|报价类型|
+|quote_status|报价状态|Enum|是|报价主记录|系统/BDPM|W24/SS03-2|草稿/待审核/已批准/已发布/已过期/已撤回。|重命名/统一|报价发布状态、报价状态|
+|quote_currency_code|报价币种|ISO 4217 Enum|是|报价主记录|系统/BDPM|W24|报价金额的统一币种；明细价格若币种不同必须换算并留痕。|重命名/统一|报价价格/币种、currency|
+|valid_from|报价生效时间|Date/DateTime|条件必填|报价主记录|BDPM|W24|正式发布报价必须有生效时间。|新增/统一|生效期|
+|quote_valid_until|报价有效期至|Date|条件必填|报价主记录|BDPM|W24|不得与P-03价格来源有效期混用。|重命名/统一|报价有效期、valid_until|
+|delivery_commitment|报价交期承诺|Date/Text/Structure|是|报价主记录|PW/BDPM|W24|记录交期数值、计算口径、来源和是否为承诺。|重命名/统一|报价交期、交期|
+|payment_terms|付款条件|Text/Structure|条件必填|报价主记录|BDPM/P-04|W24|来源于P-04或本次商务确认。|新增/统一|付款|
+|tax_terms|税费条件|Text/Structure|条件必填|报价主记录|BDPM|W24|税率、含税/未税口径必须明确。|新增|税费|
+|incoterms|贸易术语|Enum|条件必填|报价主记录|BDPM/P-04|W24|使用标准Incoterms枚举并记录版本/地点。|新增/统一|Incoterms、交货条款|
+|quote_assumptions|报价前提条件|LongText/Structure|是|报价主记录|BDPM|W24|含付款、税费、Incoterms、MOQ/SPQ、供货边界等。|重命名/细化|报价前提条件|
+|technical_boundary|技术边界|LongText/Structure|条件必填|报价主记录|FAE/BDPM|W24|记录替代、验证、规格限制与客户批准状态。|新增|技术边界|
+|cost_basis|成本基准|Currency/Structure|条件必填|报价主记录|BDPM/采购|W24|记录成本来源、币种、数量口径和时点。|新增|成本|
+|exchange_rate|报价汇率|Number|跨币种时必填|报价主记录|系统/BDPM|W24|统一比较币种时使用；必须关联exchange_rate_source与as_of。|新增|汇率|
+|exchange_rate_source|汇率来源|Text/URL|exchange_rate有值时必填|报价主记录|系统/BDPM|W24|记录汇率来源。|新增|汇率|
+|exchange_rate_as_of|汇率时点|Date|exchange_rate有值时必填|报价主记录|系统|W24|统一币种计算基准日。|新增|汇率|
+|gross_margin_status|毛利状态|Enum/Structure|条件必填|报价主记录|系统/BDPM|W24|未计算/通过/低于阈值/缺成本；口径由GOV规则维护。|新增|毛利状态|
+|rule_version|报价规则版本|Text/Link|是|报价主记录|GOV/系统|W24|记录计算、毛利、价格优先级使用的规则版本。|新增/统一|规则版本|
+|approval_status|商务审批状态|Enum|是|报价主记录|Gate/审批人|W24|未提交/待审批/已通过/已驳回；通过前不得发布。|重命名/统一|商务联审结论/审批记录|
+|approval_comment|商务审批意见|LongText|条件必填|报价主记录|审批人|W24|驳回或有条件通过时必须填写。|新增/统一|审批记录、审批意见|
+|publish_status|报价发布状态|Enum|是|报价主记录|系统/Gate|W24|草稿/待审批/已批准/已发布/过期/撤回。|重命名/统一|报价发布状态|
+|quote_document_ref|正式报价文件链接|URL/Attachment|已发布时必填|报价主记录|系统/BDPM|W24|只指向正式发布版本。|重命名/统一|报价文件、台账链接|
+|blocking_reason|阻断原因|LongText/Structure|条件必填|报价主记录|AI/BDPM|W24|价格过期、冲突、阶梯缺失、技术批准缺失等逐项记录。|新增|阻断原因|
+|quote_line_id|报价明细ID|Text/AutoNumber|是|报价明细QuoteLine|系统|W24|最小粒度为报价版本×PN×BOM位×数量阶梯。|新增|QuoteLine|
+|internal_pn|内部料号|Link(P-08)|是|报价明细QuoteLine|P-08/FAE|W24|报价物料统一引用P-08。|统一|PN|
+|bom_position|BOM位|Text|条件必填|报价明细QuoteLine|FAE|W24|同一报价中不同BOM位不能混淆。|统一|BOM位|
+|quantity_tier|数量阶梯|Structure|是|报价明细QuoteLine|AI/BDPM|W24|含min_qty、max_qty或阶梯描述。|拆分/结构化|数量阶梯|
+|price_type|价格类型|Enum|是|报价明细QuoteLine|BDPM|W24|参考价/量产价/现货价/样品价等。|新增/统一|price_type|
+|unit_price|报价单价|Currency|是|报价明细QuoteLine|系统/BDPM|W24|与currency_code成对存在。|重命名/统一|报价价格、单价|
+|currency_code|明细币种|ISO 4217 Enum|是|报价明细QuoteLine|系统/BDPM|W24|明细币种；若与主报价币种不同必须记录换算。|重命名/统一|币种|
+|lead_time_days|供货交期天数|Number|条件必填|报价明细QuoteLine|供应商/采购/BDPM|W24|统一为自然日或工作日一种口径，口径写入字段说明。|重命名/统一|LT、报价交期|
+|moq_qty|最小起订量|Number|条件必填|报价明细QuoteLine|P-08/S-05/采购|W24|数量比较与前提条件校验。|拆分/统一|MOQ|
+|spq_qty|标准包装量|Number|条件必填|报价明细QuoteLine|P-08/S-05/采购|W24|数量比较与包装约束校验。|拆分/统一|SPQ|
+|price_source_ref|价格来源引用|Link(P-03/S-05/S-04)|是|报价明细QuoteLine|系统|W24|指向Price List、采购基准或专项询价记录。|新增/统一|来源报价、价格来源|
+|substitution_approval_status|替代批准状态|Enum|条件必填|报价明细QuoteLine|P-11|W24|未检查/待验证/已批准/不批准；未满足时阻断发布。|新增|技术替代批准状态|
+
+#### P-03 Price List台账
+
+|统一字段名|中文字段名|数据类型|必填性|对象层|维护/来源|Demo使用|定义/取值/校验规则|处理建议|原字段/来源名称|
+|---|---|---|---|---|---|---|---|---|---|
+|price_list_id|PriceList ID|Text/AutoNumber|是|价格记录|系统/BDPM|W24|价格来源唯一标识。|重命名/统一|PriceListID|
+|internal_pn|内部料号|Link(P-08)|是|价格记录|P-08/价格Owner|W24|统一引用P-08。|重命名/统一|PN/料号|
+|customer_id|适用客户ID|Link(L-02)|条件必填|价格记录|价格Owner|W24|客户专属价必填；公共渠道价可用scope_type标识。|新增|客户或渠道|
+|price_scope_type|价格适用范围|Enum|是|价格记录|BDPM|W24|客户专属/渠道/公共/项目。|新增|客户或渠道|
+|price_type|价格类型|Enum|是|价格记录|BDPM|W24|与报价所需价格类型对齐。|新增/统一|价格类型|
+|list_unit_price|Price List单价|Currency|是|价格记录|价格Owner|W24|与currency_code成对。|重命名/统一|客户专属价/单价|
+|currency_code|价格币种|ISO 4217 Enum|是|价格记录|价格Owner|W24|统一币种编码。|重命名/统一|币种|
+|release_version|Release版本|Text|是|价格记录|价格Owner|W24|报价时按as_of选取有效版本。|重命名/统一|Release版本、版本|
+|valid_from|生效时间|Date|是|价格记录|价格Owner|W24|与valid_to组成有效区间。|保留/细化|生效期|
+|valid_to|失效时间|Date|是|价格记录|价格Owner|W24|报价时点必须落在有效区间内。|重命名/统一|失效期、有效期|
+|quantity_tier|数量阶梯|Structure|条件必填|价格记录|价格Owner|W24|含适用数量和折扣条件。|拆分/结构化|数量阶梯/折扣条款|
+|discount_terms|折扣条款|LongText/Structure|条件必填|价格记录|价格Owner|W24|结构化记录折扣条件和例外。|细化|折扣条款|
+|source_quote_id|来源报价ID|Link(P-02/S-04)|条件必填|价格记录|系统/BDPM|W24|能追溯价格来源。|重命名/统一|来源报价|
+|price_status|价格状态|Enum|是|价格记录|价格Owner|W24|草稿/有效/暂停/过期/替代。|新增/统一|状态|
+
+#### P-04 交易框架与承诺台账
+
+|统一字段名|中文字段名|数据类型|必填性|对象层|维护/来源|Demo使用|定义/取值/校验规则|处理建议|原字段/来源名称|
+|---|---|---|---|---|---|---|---|---|---|
+|framework_id|交易框架ID|Text/AutoNumber|是|框架主记录|商务Owner|W24|统一框架合同主键。|重命名/统一|框架ID|
+|customer_id|客户ID|Link(L-02)|是|框架主记录|商务Owner|W24|交易框架归属客户。|保留/统一|客户名称|
+|contract_version|合同版本|Text|是|框架主记录|商务Owner|W24|报价采用的合同/框架版本。|重命名/统一|合同版本|
+|contract_status|合同状态|Enum|是|框架主记录|商务Owner|W24|草稿/有效/到期/终止。|保留/细化|合同状态|
+|account_status|交易账户状态|Enum|是|框架主记录|商务Owner|W24|正常/冻结/待准入/关闭。|重命名/统一|交易账户状态|
+|payment_terms|账期与付款条款|Text/Structure|条件必填|框架主记录|商务Owner|W24|供报价继承；与D-04信用台账区分。|重命名/统一|账期条款、付款条件|
+|credit_limit|信用额度|Currency|条件必填|框架主记录|商务Owner|W24/11-A2条件|可供信用门禁使用。|保留/细化|信用额度|
+|cooperation_scope|合作范围|LongText/Structure|条件必填|框架主记录|商务Owner|W24|定义品牌、产品线、区域等边界。|保留/细化|合作范围|
+|incoterms|默认贸易术语|Enum|条件必填|框架主记录|商务Owner|W24|报价若覆盖本条件，回链本字段。|新增/统一|交易条款、Incoterms|
+|effective_from|框架生效时间|Date|是|框架主记录|商务Owner|W24|有效区间。|新增/统一|生效期|
+|effective_to|框架失效时间|Date|条件必填|框架主记录|商务Owner|W24|有效区间。|新增/统一|生效期|
+|commitment_id|承诺ID|Text/AutoNumber|条件必填|承诺子记录|系统/商务Owner|W24|每条价格、交期、数量或条件承诺一个ID。|重命名/统一|承诺ID|
+|commitment_party|承诺方|Enum/Link|是|承诺子记录|商务Owner|W24|我方/客户/供应商/其他。|统一|承诺方|
+|commitment_type|承诺类型|Enum|是|承诺子记录|商务Owner|W24|价格/交期/数量/质量/付款/其他。|新增/统一|承诺内容|
+|commitment_content|承诺内容|LongText/Structure|是|承诺子记录|商务Owner|W24|结构化值+说明，避免只写自由文本。|细化|承诺内容|
+|commitment_due_date|承诺期限|Date|条件必填|承诺子记录|商务Owner|W24|到期前可触发提醒。|重命名/统一|期限|
+|commitment_status|承诺状态|Enum|是|承诺子记录|商务Owner/系统|W24|未生效/生效/已兑现/逾期/取消。|重命名/统一|状态|
+|fulfillment_record_ref|兑现记录引用|Link/URL|条件必填|承诺子记录|系统/履约|W24|回链D-01/D-09等执行事实。|重命名/统一|兑现记录|
+|unresolved_risk_list|未决商务风险清单|LongText/Structure|条件必填|主记录|商务Owner|W24|报价前置风险；未关闭时可阻断审批。|重命名/细化|未决风险清单、商务风险|
+
+#### P-06 样品交付与芯片验证记录台账
+
+|统一字段名|中文字段名|数据类型|必填性|对象层|维护/来源|Demo使用|定义/取值/校验规则|处理建议|原字段/来源名称|
+|---|---|---|---|---|---|---|---|---|---|
+|validation_id|验证ID|Text/AutoNumber|是|验证主记录|系统|W05/W24|验证记录唯一标识。|保留/统一|Validation_ID、验证编号|
+|request_id|关联需求编号|Link(P-01)|条件必填|验证主记录|系统/FAE|W05/W24|回链需求与验证目的。|新增/统一|需求号|
+|project_id|关联项目ID|Link(P-05)|条件必填|验证主记录|系统/FAE|W05/W24|项目场景验证必填。|新增/统一|项目|
+|customer_id|客户ID|Link(L-02)|条件必填|验证主记录|系统/FAE|W05/W24|客户验证必填。|新增/统一|客户ID|
+|validation_internal_pn|验证内部料号|Link(P-08)|是|验证主记录|FAE|W05/W24|统一引用P-08.internal_pn。|重命名/统一|Validation_PN、验证PN|
+|validation_type|验证类型|Enum|是|验证主记录|FAE|W05/W24|Pin-to-Pin/功能/可靠性/认证/复测。|新增/统一|验证类型|
+|test_condition|测试条件|LongText/Structure|是|验证主记录|FAE/验证Owner|W05|环境、输入、负载、样品状态等。|重命名/统一|测试条件|
+|test_parameters|测试参数|Structure|是|验证主记录|FAE/验证Owner|W05|参数名、值、单位、版本必须结构化。|重命名/统一|测试参数|
+|test_result|测试结果|LongText/Structure|是|验证主记录|验证Owner|W05|实测数据与结论，必要时附原始数据。|重命名/统一|测试结果|
+|validation_status|验证状态|Enum|是|验证主记录|FAE/验证Owner|W05/W24|未开始/进行中/通过/不通过/条件通过/待补证。|新增/统一|通过状态、验证状态|
+|issue_risk|问题与风险|LongText/Structure|条件必填|验证主记录|AI/FAE|W05/W24|记录未关闭问题、风险等级、责任人和关闭条件。|重命名/统一|问题与风险|
+|sample_version|样品版本|Text|条件必填|验证主记录|验证Owner|W05|样品追溯。|重命名/统一|样品版本|
+|sample_lot|样品批次|Text|条件必填|验证主记录|验证Owner|W05|与D-07或样品出库记录回链。|重命名/统一|样品批次、批次|
+|evidence_ref|验证证据引用|URL/Attachment/Structure|是|验证主记录|验证Owner/FAE|W05/W24|原始数据、照片、报告、资料页码等。|统一|证据引用|
+|next_validation_action|后续验证动作|LongText/Structure|条件必填|验证主记录|FAE|W05/W24|UNKNOWN/CONDITIONAL时必须有关闭动作。|新增|验证建议/缺口|
+
+#### P-08 芯片主数据台账
+
+|统一字段名|中文字段名|数据类型|必填性|对象层|维护/来源|Demo使用|定义/取值/校验规则|处理建议|原字段/来源名称|
+|---|---|---|---|---|---|---|---|---|---|
+|internal_pn|内部料号|Text|是|物料主记录|SS02/FAE|W05/W24/SS03/11-A2|全链路料号统一基准；不可使用自由文本替代。|重命名/统一|标准型号PN、pn、mpn|
+|customer_pn|客户料号|Text|条件必填|物料主记录|SS02/D-10映射|W24/SS03/11-A2|客户料号映射优先维护在D-10，P-08可作为别名索引。|新增/统一|customer_mpn|
+|brand_name|品牌名称|Text/Link|是|物料主记录|FAE/数据Owner|W05/W24/SS03/11-A2|品牌统一引用；外部供应商品牌与原厂制造商分开。|重命名/统一|brand、manufacturer_brand、原厂或品牌|
+|manufacturer_name|制造商名称|Text/Link|条件必填|物料主记录|数据Owner|W05/W24|品牌与制造商不一致时分开记录。|新增/统一|原厂|
+|specification_description|规格描述|LongText|是|物料主记录|数据Owner/原厂资料|W05/W24|标准规格文本。|重命名/统一|Specification Description、产品描述|
+|normalized_parameter_set|标准化参数集|Structure|W05必填；W24条件|物料主记录|FAE/数据Owner|W05/W24|参数名、值、单位、精度、版本，用于硬/软约束比较。|新增|参数名称、单位、版本|
+|package|封装|Enum/Text|条件必填|物料主记录|数据Owner|W05/W24/SS03|影响硬约束和报价识别。|保留/细化|封装|
+|process_technology|工艺|Text/Enum|条件必填|物料主记录|数据Owner|W05|硬约束比较项。|重命名/统一|工艺|
+|lifecycle_status|生命周期状态|Enum|是|物料主记录|数据Owner|W05/W24/SS03|Active/NRND/EOL/停产/风险。|重命名/统一|生命周期状态、lifecycle_status、产品状态|
+|eol_pcn_status|EOL/PCN状态|Enum/Structure|条件必填|物料主记录|数据Owner/原厂|W05/W24|记录通知状态、影响和生效时间。|新增/统一|EoL/PCN状态|
+|datasheet_ref|Datasheet引用|URL/Link(P-10)|条件必填|物料主记录|P-10/原厂|W05/W24|官方资料链接。|重命名/统一|Datasheet链接|
+|datasheet_version|Datasheet版本|Text|datasheet_ref有值时必填|物料主记录|P-10/原厂|W05/W24|用于证据版本回链。|重命名/统一|Datasheet版本/版本|
+|application_scenarios|适配应用场景|MultiEnum/Structure|条件必填|物料主记录|FAE/数据Owner|W05/W24|判断物料实际适用性。|重命名/统一|应用场景、适配场景|
+|pin_to_pin_relation_ref|Pin-to-Pin关系引用|Link(P-11)|条件必填|物料主记录|FAE|W05/W24|引用P-11关系记录，避免在P-08复制批准结论。|新增/统一|Pin-to-Pin替代关系|
+
+#### P-09 客户技术与机会档案
+
+|统一字段名|中文字段名|数据类型|必填性|对象层|维护/来源|Demo使用|定义/取值/校验规则|处理建议|原字段/来源名称|
+|---|---|---|---|---|---|---|---|---|---|
+|customer_id|客户ID|Link(L-02)|是|客户技术档案|SS02/FAE|W05/W24|区别于L-02的商务画像，技术档案以客户ID为主键。|保留/统一|客户 ID|
+|technical_stack|客户技术栈|Structure|条件必填|客户技术档案|FAE|W05/W24|记录平台、架构、关键技术约束。|重命名/统一|技术栈|
+|product_line_direction|产品线技术方向|Text/Structure|条件必填|客户技术档案|FAE/BDPM|W24|报价上下文与应用场景。|重命名/统一|产品线方向|
+|bom_brand_usage|BOM品牌使用情况|Structure|条件必填|客户技术档案|FAE|W05/W24|记录客户当前BOM品牌、料号及替代空间。|重命名/统一|BOM品牌|
+|validation_process|客户验证流程|LongText/Structure|条件必填|客户技术档案|FAE/客户|W05/W24|支持验证要求和报价前提判断。|重命名/统一|验证流程|
+|technical_decision_maker_ref|技术决策人引用|Link(L-08)|条件必填|客户技术档案|FAE|W05/W24|引用联系人，不复制姓名。|重命名/统一|技术决策人|
+|rd_capability_assessment|研发能力评估|Enum/LongText|条件必填|客户技术档案|FAE|W05/W24|用于技术支持与验证路径判断。|重命名/统一|研发能力|
+|technical_preference_tags|技术偏好标签|MultiEnum|条件必填|客户技术档案|FAE|W05/W24|用于推荐和方案匹配。|重命名/统一|技术偏好标签|
+|opportunity_id|机会ID|Text/AutoNumber|条件必填|机会子记录|系统/BDPM|W05/W24|需求或报价对应的机会对象。|新增/统一|机会记录|
+
+#### P-10 原厂技术资料库
+
+|统一字段名|中文字段名|数据类型|必填性|对象层|维护/来源|Demo使用|定义/取值/校验规则|处理建议|原字段/来源名称|
+|---|---|---|---|---|---|---|---|---|---|
+|document_id|资料ID|Text/AutoNumber|是|资料主记录|系统|W05/W24|资料唯一标识。|新增/统一|资料记录|
+|document_type|资料类型|Enum|是|资料主记录|FAE|W05/W24|Datasheet/应用笔记/参考设计/白皮书/样片资料/其他。|新增/统一|资料类型|
+|internal_pn|关联内部料号|Link(P-08)|条件必填|资料主记录|P-08/FAE|W05/W24|料号相关资料必须回链P-08。|新增/统一|PN|
+|brand_name|品牌名称|Text/Link|是|资料主记录|数据Owner|W05/W24|统一引用P-08.brand_name。|重命名/统一|原厂|
+|document_title|资料标题|Text|是|资料主记录|资料Owner|W05/W24|资料可识别名称。|新增|资料|
+|document_version|资料版本|Text|是|资料主记录|资料Owner|W05/W24|评估必须回链版本。|重命名/统一|版本|
+|document_date|资料发布日期|Date|条件必填|资料主记录|资料Owner|W05/W24|用于时效判断。|新增|更新记录|
+|document_ref|资料文件链接|URL/Attachment|是|资料主记录|资料Owner|W05/W24|官方资料文件。|重命名/统一|Datasheet链接、资料|
+|citation_locator|证据定位|Text/Structure|W05必填；W24条件|资料主记录|AI/FAE|W05/W24|页码、章节、表格或段落，支持参数证据引用。|新增|证据引用、页码或证据段落|
+|source_contact_ref|原厂支持联系人|Link(L-08)/Text|条件必填|资料主记录|FAE|W05/W24|需要补证时的联系人。|重命名/统一|原厂支持联系人|
+|document_status|资料状态|Enum|是|资料主记录|资料Owner|W05/W24|有效/过期/待核实/作废。|新增/统一|状态|
+
+#### P-11 替代选型与批准关系库
+
+|统一字段名|中文字段名|数据类型|必填性|对象层|维护/来源|Demo使用|定义/取值/校验规则|处理建议|原字段/来源名称|
+|---|---|---|---|---|---|---|---|---|---|
+|substitution_relation_id|替代关系ID|Text/AutoNumber|是|替代关系主记录|系统|W05/W24|原P-11-01与P-11-02统一后的关系主键。|新增/统一|P-11-01/P-11-02记录ID|
+|original_internal_pn|原内部料号|Link(P-08)|是|替代关系主记录|P-08/FAE|W05/W24|评估基准物料。|重命名/统一|Original_PN、原PN、目标替代料号|
+|candidate_internal_pn|候选内部料号|Link(P-08)|是|替代关系主记录|P-08/FAE|W05/W24|被评估物料。|重命名/统一|Candidate_PN、候选PN|
+|substitution_type|替代类型|Enum|是|替代关系主记录|FAE|W05/W24|Pin-to-Pin/功能替代/参数替代/其他。|重命名/统一|替代类型、关系类型|
+|recommendation_level|推荐等级|Enum|是|替代关系主记录|AI/FAE|W05/W24|推荐/条件推荐/备选/不推荐。|重命名/统一|替代等级、推荐|
+|recommendation_reason|推荐理由|LongText|是|替代关系主记录|AI/FAE|W05/W24|说明技术和商务依据。|新增/统一|推荐理由|
+|difference_summary|差异摘要|LongText|是|替代关系主记录|AI/FAE|W05|供P-01和后续流程消费。|新增/统一|评论、差异摘要|
+|difference_item_id|差异明细ID|Text/AutoNumber|是|差异明细子表|系统|W05|一条参数差异一条记录。|新增|逐参数差异明细|
+|parameter_name|标准参数名|Text/Link(GOV)|是|差异明细子表|AI/FAE|W05|参数名称标准化。|新增/统一|参数名称|
+|original_value|原物料参数值|Text/Number/Structure|是|差异明细子表|AI|W05|引用P-08或资料证据。|新增|参数A|
+|candidate_value|候选物料参数值|Text/Number/Structure|是|差异明细子表|AI|W05|引用P-08或资料证据。|新增|参数B|
+|parameter_unit|参数单位|Text/Link(GOV)|条件必填|差异明细子表|AI/FAE|W05|统一单位后比较。|新增/统一|单位|
+|constraint_type|约束类型|Enum|是|差异明细子表|GOV/AI|W05|硬约束/软约束。|新增/统一|硬/软约束标识|
+|difference_status|差异状态|Enum|是|差异明细子表|AI/FAE|W05|MATCH/MISMATCH/UNKNOWN/CONDITIONAL。|新增/统一|Status、差异状态|
+|impact_statement|影响说明|LongText|MISMATCH/CONDITIONAL必填|差异明细子表|AI/FAE|W05|说明对应用、验证、报价的影响。|新增|Impact、影响说明|
+|evidence_ref|差异证据引用|URL/Attachment/Structure|是|差异明细子表|AI/FAE|W05|具体资料、页码、测试记录。|统一|证据引用|
+|rule_version|差异规则版本|Text/Link(GOV)|是|差异明细子表|GOV/系统|W05|记录评估时采用的硬/软约束规则版本。|新增/统一|GOV规则版本|
+|risk_level|替代风险等级|Enum|是|替代关系主记录|FAE/RI|W05/W24|低/中/高/关键。|统一|风险等级|
+|verification_requirement|验证要求|LongText/Structure|CONDITIONAL/UNKNOWN必填|替代关系主记录|FAE|W05/W24|与P-06.validation_id或待验证任务回链。|统一|验证要求|
+|validation_id|关联验证ID|Link(P-06)|条件必填|替代关系主记录|系统/FAE|W05/W24|验证完成后回链事实。|新增/统一|验证编号、验证结果|
+|analysis_status|分析状态|Enum|是|替代关系主记录|系统/FAE|W05/W24|AI草稿/FAE确认/待客户验证/客户已批准/不批准/作废。|新增/统一|写入权限与时机、批准状态|
+|customer_approval_status|客户批准状态|Enum|是|替代关系主记录|审批流程|W05/W24|未提交/待批准/已批准/不批准/有条件批准；不由差异评估自动产生。|重命名/统一|批准状态、客户批准|
+|customer_approval_at|客户批准时间|DateTime|客户已批准时必填|替代关系主记录|审批流程|W05/W24|客户批准事实时间。|新增/统一|批准时间|
+|customer_approval_ref|客户批准凭证|URL/Attachment|客户已批准时必填|替代关系主记录|审批流程|W05/W24|签核邮件、系统审批单或客户文件。|新增/统一|批准凭证|
+|customer_feedback|客户反馈|LongText|条件必填|替代关系主记录|FAE/BDPM|W05/W24|记录客户对候选物料的反馈。|保留/细化|客户反馈|
+|request_id|关联需求编号|Link(P-01)|条件必填|替代关系主记录|系统|W05/W24|明确候选关系适用的需求。|新增/统一|关联需求|
+|project_id|关联项目ID|Link(P-05)|条件必填|替代关系主记录|系统|W05/W24|不同项目批准边界可不同。|新增/统一|关联项目|
+|bom_position|关联BOM位|Text|条件必填|替代关系主记录|FAE|W05/W24|批准边界定位。|新增/统一|BOM位|
+|analysis_report_ref|替代分析报告|URL/Attachment|条件必填|替代关系主记录|系统/FAE|W05|正式结构化结果或附件回链。|重命名/统一|替代分析报告、报告链接|
+|confidence_score|证据可信度|Percent/Enum|条件必填|替代关系主记录|AI/FAE|W05|AI输出可信度，需与人工确认区分。|新增/统一|证据可信度|
+
+#### S-03 供应商主台账
+
+|统一字段名|中文字段名|数据类型|必填性|对象层|维护/来源|Demo使用|定义/取值/校验规则|处理建议|原字段/来源名称|
+|---|---|---|---|---|---|---|---|---|---|
+|supplier_id|供应商ID|Text/AutoNumber|是|供应商主记录|SS03|SS03-1/SS03-2|统一供应商主体键；临时供应商定点前必须转正式ID。|保留/统一|supplier_id、Supplier ID|
+|supplier_name|供应商名称|Text|是|供应商主记录|采购/SS03|SS03-1/SS03-2|临时供应商可先占位，定点前补齐正式名称。|保留/统一|supplier_name、供应商名称|
+|supplier_type|供应商分类|Enum|是|供应商主记录|SS03|SS03-1/SS03-2|原厂/授权代理/贸易/分销/其他。|保留/细化|supplier_type、供应商分类|
+|supplier_status|供应商状态|Enum|是|供应商主记录|SS03|SS03-1/SS03-2|临时/正式/停用；临时状态不可定点。|新增/统一|supplier_status|
+|temporary_supplier_flag|临时供应商标记|Boolean|是|供应商主记录|采购|SS03-1/SS03-2|临时新增立即可询价，但必须受定点门禁约束。|新增|临时供应商|
+|sales_contact_ref|业务联系人引用|Link/Text|SS03-1必填|供应商主记录|采购/供应商Owner|SS03-1|至少一名联系人，用于邮件或即时通讯外发。|重命名/统一|sales_contact、联系人|
+|contact_channel|首选联系渠道|Enum|条件必填|供应商主记录|供应商Owner|SS03-1|邮件/即时通讯/电话；需与外发记录一致。|新增/统一|send_channel、确认通道|
+|rfq_product_scope|当前询价品牌/料号范围|Structure|临时供应商定点前必填|供应商主记录|采购|SS03-1/SS03-2|允许不预建完整品牌覆盖，但必须覆盖当前询价。|新增/统一|rfq_product_scope|
+|authorized_brand_scope|授权品牌范围|Structure|代理/原厂条件必填|供应商主记录|SS03|SS03-1/SS03-2|判断品牌授权和可供范围。|新增/统一|品牌授权|
+|agency_certificate_ref|代理证凭证|URL/Attachment|supplier_type=授权代理时必填|供应商主记录|供应商Owner/采购|SS03-2|无有效代理证不得提交定点审批。|保留/细化|agency_certificate_ref、代理证|
+|agency_certificate_valid_to|代理证有效期至|Date|代理证有值时必填|供应商主记录|供应商Owner|SS03-2|定点前检查有效期。|新增|代理证|
+|qualification_status|准入资质状态|Enum|定点前必填|供应商主记录|SS03|SS03-2|待准入/合格/限制/不合格。|新增/统一|资质/准入|
+|compliance_status|合规状态|Enum|定点前必填|供应商主记录|SS03|SS03-2|通过/待核查/不通过。|新增/统一|合规|
+|commercial_terms_ref|长期商务规则引用|Link/Structure|条件必填|供应商主记录|SS03|SS03-2|长期条款不在本次询价Activity维护，但应有引用。|新增/统一|商务规则、长期条款|
+|supplier_health_score|供应商健康度|Percent/Enum|条件必填|供应商主记录|SS03/SS04|SS03-2|由履约数据计算，不作为单次询价事实覆盖。|新增/统一|供应商绩效/健康度|
+
+#### S-04 询价、报价、比价与采购决策记录台账
+
+|统一字段名|中文字段名|数据类型|必填性|对象层|维护/来源|Demo使用|定义/取值/校验规则|处理建议|原字段/来源名称|
+|---|---|---|---|---|---|---|---|---|---|
+|rfq_batch_id|询价批次号|Text/AutoNumber|是|RFQ层|系统/采购|SS03-1/SS03-2|同一批次可含多料号、多供应商；品牌或料号变化必须新开批次。|保留/统一|rfq_batch_id、询价批次号|
+|rfq_line_id|询价行ID|Text/AutoNumber|是|RFQ层|系统|SS03-1/SS03-2|最小粒度为询价批次×供应商×内部料号。|保留/统一|rfq_line_id、询价行ID|
+|source_type|需求来源类型|Enum|是|RFQ层|采购/上游台账|SS03-1/SS03-2|P-01客户需求/D-15采购计划/价格维护/异常补货。|统一|source_type|
+|source_id|来源对象ID|Text/Link|条件必填|RFQ层|系统/上游台账|SS03-1/SS03-2|与source_type成对；P-01写request_id，D-15写purchase_plan_id。|统一|source_id|
+|customer_id|客户ID|Link(L-02)|条件必填|RFQ层|P-01/D-15|SS03-1/SS03-2|用于需求归属与通知。|新增/统一|customer_id|
+|project_id|项目ID|Link(P-05)|条件必填|RFQ层|P-01/D-15|SS03-1/SS03-2|用于需求归属与通知。|新增/统一|project_id|
+|brand_name|询价品牌|Text/Link(P-08)|是|RFQ层|P-08/采购|SS03-1/SS03-2|与internal_pn精确匹配；品牌变化新开批次。|重命名/统一|brand、manufacturer_brand|
+|internal_pn|询价内部料号|Link(P-08)|是|RFQ层|P-08/采购|SS03-1/SS03-2|统一引用P-08.internal_pn。|重命名/统一|pn、料号|
+|target_qty|目标数量|Number|是|RFQ层|P-01/D-15/采购|SS03-1/SS03-2|比价基准；来自P-01.target_qty或D-15.trigger_qty。|统一|target_qty、purchase_trigger_qty|
+|target_delivery_date|目标交期|Date|是|RFQ层|P-01/D-15/采购|SS03-1/SS03-2|比价基准；来自P-01或D-15.requirement_date。|统一|target_delivery_date、requirement_date|
+|requested_price_types|所需价格类型|MultiEnum|是|RFQ层|P-01/采购|SS03-1|参考价/量产价/现货价/样品价。|重命名/统一|price_types_requested|
+|quote_due_at|报价回复截止时间|DateTime|是|RFQ层|P-01/采购|SS03-1|供应商回复时效基准。|重命名/统一|quote_due_at、期望报价返回时间|
+|target_price_internal|内部目标价|Currency|否|RFQ层|P-01|SS03-1/SS03-2|仅内部判断；如实际披露需留痕。|统一|target_price_internal|
+|supplier_id|供应商ID|Link(S-03)|是|RFQ层|S-03/采购|SS03-1/SS03-2|临时供应商定点前转正式ID。|统一|supplier_id|
+|send_channel|询价发送渠道|Enum|是|RFQ层|采购/系统|SS03-1|邮件/即时通讯/电话。|统一|send_channel|
+|sent_at|询价发送时间|DateTime|是|RFQ层|系统|SS03-1|系统生成；未发送不得标记已发送。|保留/细化|sent_at|
+|outbound_content_ref|外发内容引用|URL/Attachment|是|RFQ层|系统/采购|SS03-1|记录对外披露内容和附件。|新增/统一|对外披露内容、附件|
+|sent_evidence_ref|外发凭证|URL/Attachment|是|RFQ层|系统|SS03-1|原始邮件、聊天发送记录等。|新增/统一|发送凭证、evidence|
+|rfq_status|询价状态|Enum|是|RFQ层|系统/采购|SS03-1|草稿/已发送/部分回复/全部回复/已到期未回复/催询中/关闭。|保留/细化|rfq_status|
+|reminder_count|催询次数|Integer|是|RFQ层|系统|SS03-1|自动提醒与人工催询均计数。|新增|跟进回复时效|
+|last_reminded_at|最后催询时间|DateTime|条件必填|RFQ层|系统/采购|SS03-1|有催询时必填。|新增|催询|
+|overdue_flag|询价超期标记|Boolean|是|RFQ层|系统|SS03-1|quote_due_at已过且未完成回复或未发出时触发。|新增|已到期未回复、发起超期|
+|supplier_quote_id|供应商报价ID|Text/AutoNumber|是|Quote层|系统|SS03-2|同一询价行可有报价修订历史。|新增/统一|报价记录ID|
+|quote_status|供应商报价状态|Enum|是|Quote层|采购|SS03-2|已报价/拒绝报价/未回复/待确认。|保留/细化|quote_status|
+|price_type|报价价格类型|Enum|条件必填|Quote层|采购|SS03-2|必须与requested_price_types匹配。|保留/统一|price_type|
+|unit_price|报价单价|Currency|已报价时必填|Quote层|采购|SS03-2|与currency_code成对。|重命名/统一|unit_price、价格|
+|currency_code|报价币种|ISO 4217 Enum|已报价时必填|Quote层|采购|SS03-2|统一币种比较前保留原币种。|重命名/统一|currency|
+|actual_qty|报价适用数量|Number|已报价时条件必填|Quote层|采购|SS03-2|判断与target_qty可比性。|重命名/统一|actual_qty|
+|lead_time_days|报价交期天数|Number|已报价时条件必填|Quote层|采购|SS03-2|统一工作日/自然日口径；原始文字可放lead_time_note。|重命名/统一|lead_time、LT|
+|lead_time_note|交期说明|LongText|条件必填|Quote层|采购|SS03-2|无法标准化时保留供应商原文。|新增|lead_time|
+|moq_qty|MOQ|Number|条件必填|Quote层|采购|SS03-2|最小起订量。|拆分/统一|MOQ-SPQ、MOQ|
+|spq_qty|SPQ|Number|条件必填|Quote层|采购|SS03-2|标准包装量。|拆分/统一|MOQ-SPQ、SPQ|
+|quote_valid_until|报价有效期至|Date|条件必填|Quote层|采购|SS03-2|报价是否仍可用。|重命名/统一|valid_until、报价有效期|
+|special_terms|本次特殊商务条款|LongText/Structure|否|Quote层|采购|SS03-2|一次性条款；长期供应商条款回链S-03。|重命名/细化|special_terms、特殊条款|
+|response_at|实际回复时间|DateTime|已回复时必填|Quote层|系统/采购|SS03-2|回复时间事实。|保留/细化|response_at|
+|no_quote_reason|未报价原因|LongText|拒绝/未回复时必填|Quote层|采购|SS03-2|拒绝报价或未回复必须填写。|保留/细化|no_quote_reason|
+|quote_evidence_ref|原始报价凭证|URL/Attachment|报价/拒绝均必填|Quote层|系统/采购|SS03-2|邮件、聊天截图、供应商报价单。|重命名/统一|evidence、原始沟通凭证|
+|quote_revision_no|同轮报价修订号|Integer|是|Quote层|系统/采购|SS03-2|同轮修改保留修订历史，当前报价可聚合展示。|新增|报价与版本|
+|comparison_group_id|比价组ID|Text/AutoNumber|是|Decision层|系统|SS03-2|由rfq_batch_id+internal_pn+target_qty+target_delivery_date组成。|重命名/统一|comparison_group|
+|comparability_status|可比性状态|Enum|是|Decision层|AI/采购|SS03-2|可直接比较/条件可比/不可比；不可比必须说明原因。|新增|正式比价组、不可直接比较|
+|comparison_basis_snapshot_ref|比价基准快照|Structure/URL|是|Decision层|系统|SS03-2|固化目标数量、目标交期、价格类型、汇率和基准版本。|新增|比价组|
+|system_score|系统评分|Number|是|Decision层|系统|SS03-2|按询价类型权重计算，0-100。|重命名/统一|score|
+|system_recommendation|系统推荐|Enum|是|Decision层|系统|SS03-2|推荐/备选/不推荐。|重命名/统一|recommendation|
+|procurement_confirm|采购确认意见|Enum|意见确认时必填|Decision层|采购|SS03-2|认可/调整/否决。|保留/细化|procurement_confirm|
+|confirm_reason|确认或调整理由|LongText|与系统推荐不一致时必填|Decision层|采购|SS03-2|采购调整或否决系统建议时必填。|重命名/统一|confirm_reason|
+|baseline_id|采购基准ID|Link(S-05)|有基准时必填|Decision层|系统|SS03-2|与品牌、料号、价格类型、数量和有效期匹配。|新增/统一|baseline_id|
+|baseline_match_status|基准匹配状态|Enum|是|Decision层|系统|SS03-2|已匹配/无基准/条件匹配/不匹配。|新增|无基准可比、基准比较|
+|baseline_unit_price|比较基准单价|Currency|有基准时必填|Decision层|系统|SS03-2|复制当次采用的S-05基准快照，避免历史重算漂移。|新增/统一|benchmark_unit_price|
+|comparison_currency_code|比价统一币种|ISO 4217 Enum|跨币种时必填|Decision层|系统|SS03-2|统一币种并回链汇率。|新增|汇率/统一币种|
+|conversion_rate|币种换算汇率|Number|跨币种时必填|Decision层|系统|SS03-2|记录换算基准和来源。|新增|汇率|
+|price_variance_pct|相对基准涨幅|Percent|有基准时派生|Decision层|系统|SS03-2|(报价-基准)/基准；涨幅>10%标红。|重命名/统一|price_variance_pct、涨幅|
+|variance_reason|涨价原因|LongText|涨幅>10%时必填|Decision层|采购|SS03-2|说明供应商涨价、市场、交期或其他原因。|保留/细化|variance_reason、涨价原因|
+|selected_supplier_id|中选供应商ID|Link(S-03)|定点通过时必填|Decision层|系统/采购|SS03-2|审批通过的定点对象。|新增/统一|推荐供应商、中选供应商|
+|selected_quote_id|中选报价ID|Link(S-04 Quote)|定点通过时必填|Decision层|系统|SS03-2|关联被选中的供应商报价。|新增/统一|定点结论|
+|approval_status|定点审批状态|Enum|是|Decision层|审批流|SS03-2|待审批/已通过/已驳回。|重命名/统一|approval_status|
+|approval_comment|定点审批意见|LongText|驳回/条件通过时必填|Decision层|审批人|SS03-2|审批意见。|重命名/统一|approval_comment|
+|decision_status|定点结论状态|Enum|是|Decision层|系统/采购|SS03-2|待定点/已定点/无法定点/建议关闭/已变更。|重命名/统一|decision_status、定点结论|
+|unselected_reason|未选/无法定点原因|LongText|无法定点或未选时必填|Decision层|采购|SS03-2|完整说明比较、准入或供应条件原因。|新增/统一|未选原因、无法定点原因|
+|notification_status|结果通知状态|Enum|是|Decision层|系统|SS03-2|待通知/已通知/通知失败。|重命名/统一|notification_status|
+|notification_recipient_ref|结果通知对象|Link/Text|定点结论产生时必填|Decision层|系统|SS03-2|按source_type通知P-01负责人、D-15负责人或其他发起人。|新增/统一|通知需求发起人|
+|score_rule_version|评分规则版本|Text/Link(GOV)|是|Decision层|GOV/系统|SS03-2|记录不同询价类型的权重版本。|新增/统一|规则版本|
+
+#### S-05 采购基准与供应能力台账
+
+|统一字段名|中文字段名|数据类型|必填性|对象层|维护/来源|Demo使用|定义/取值/校验规则|处理建议|原字段/来源名称|
+|---|---|---|---|---|---|---|---|---|---|
+|baseline_id|采购基准ID|Text/AutoNumber|是|基准主记录|系统|SS03-1/SS03-2|基准唯一标识。|保留/统一|baseline_id|
+|brand_name|基准品牌|Text/Link(P-08)|是|基准主记录|采购/SS03|SS03-1/SS03-2|与internal_pn精确匹配。|重命名/统一|brand|
+|internal_pn|基准内部料号|Link(P-08)|是|基准主记录|P-08/采购|SS03-1/SS03-2|统一引用P-08。|重命名/统一|pn|
+|supplier_id|基准供应商ID|Link(S-03)|是|基准主记录|S-03/采购|SS03-1/SS03-2|当前采购基准的供应商。|统一|supplier_id|
+|price_type|基准价格类型|Enum|是|基准主记录|采购|SS03-2|必须与本次报价价格类型一致后比较。|统一|price_type|
+|baseline_unit_price|采购基准单价|Currency|是|基准主记录|采购|SS03-2|历史/当前有效采购基准，不被单次询价直接覆盖。|重命名/统一|benchmark_unit_price|
+|currency_code|基准币种|ISO 4217 Enum|是|基准主记录|采购|SS03-2|与单价成对。|重命名/统一|currency|
+|quantity_tier|适用数量阶梯|Structure|是|基准主记录|采购|SS03-2|匹配目标数量。|拆分/结构化|applicable_qty、数量阶梯|
+|valid_from|基准生效时间|Date|是|基准主记录|采购|SS03-2|有效期判断。|重命名/统一|effective_from|
+|valid_to|基准失效时间|Date|是|基准主记录|采购|SS03-2|有效期判断。|重命名/统一|effective_to|
+|lead_time_days|基准交期天数|Number|条件必填|基准主记录|采购|SS03-1/SS03-2|供应能力比较。|重命名/统一|lead_time、LT|
+|moq_qty|基准MOQ|Number|条件必填|基准主记录|采购|SS03-2|供应能力比较。|拆分/统一|MOQ|
+|spq_qty|基准SPQ|Number|条件必填|基准主记录|采购|SS03-2|供应能力比较。|拆分/统一|SPQ|
+|availability_status|可供状态|Enum|是|基准主记录|采购|SS03-1/SS03-2|可供/部分可供/不可供/待确认。|重命名/统一|availability_status、可供状态|
+|supply_risk_level|供应风险等级|Enum|条件必填|基准主记录|采购|SS03-2|低/中/高/关键。|新增/统一|供应风险|
+|baseline_status|基准状态|Enum|是|基准主记录|采购|SS03-2|Active/暂停/过期/替代。|保留/细化|baseline_status|
+|source_quote_ref|基准来源报价引用|Link(S-04/P-02)|条件必填|基准主记录|系统/采购|SS03-2|记录基准形成依据。|重命名/统一|来源报价|
+|locked_at|基准锁定时间|DateTime|条件必填|基准主记录|采购|SS03-2|锁定后单次询价不得直接覆盖。|新增|报价锁定基准|
+
+#### D-15 采购计划与执行需求台账
+
+|统一字段名|中文字段名|数据类型|必填性|对象层|维护/来源|Demo使用|定义/取值/校验规则|处理建议|原字段/来源名称|
+|---|---|---|---|---|---|---|---|---|---|
+|purchase_plan_id|采购计划ID|Text/AutoNumber|是|采购计划主记录|SS04|SS03-1/SS03-2|内部采购需求唯一引用；写入S-04.source_id。|保留/统一|purchase_plan_id|
+|customer_id|客户ID|Link(L-02)|条件必填|采购计划主记录|SS04|SS03-1/SS03-2|客户需求型采购必填。|统一|customer_id|
+|project_id|项目ID|Link(P-05)|条件必填|采购计划主记录|SS04|SS03-1/SS03-2|项目型采购必填。|统一|project_id|
+|internal_pn|内部料号|Link(P-08)|是|采购计划主记录|P-08/SS04|SS03-1/SS03-2|统一引用P-08。|重命名/统一|pn|
+|forecast_version|Forecast版本|Text/Link(D-02)|条件必填|采购计划主记录|D-02/SS04|SS03-1/SS03-2|Forecast来源时必填。|统一|Forecast版本、版本号|
+|customer_pickup_demand|客户提货需求|Number/Date/Structure|条件必填|采购计划主记录|SS04|SS03-1/SS03-2|客户提货需求的数量和时间。|重命名/统一|提货需求|
+|requirement_date|内部需求日期|Date|是|采购计划主记录|SS04|SS03-1/SS03-2|作为询价目标交期或内部需求时点。|重命名/统一|requirement_date、需求日期|
+|inventory_ref|库存引用|Link(D-03)|条件必填|采购计划主记录|系统|SS03-1/SS03-2|用于采购建议量判断。|新增/统一|库存引用|
+|in_transit_ref|在途引用|Link(D-03/D-16)|条件必填|采购计划主记录|系统|SS03-1/SS03-2|用于采购建议量判断。|新增/统一|在途引用|
+|recommended_purchase_qty|建议采购量|Number|是|采购计划主记录|系统/采购|SS03-1/SS03-2|形成询价目标数量的依据。|新增/统一|建议采购量|
+|trigger_qty|采购触发数量|Number|是|采购计划主记录|SS04|SS03-1/SS03-2|进入询价的正式数量输入。|重命名/统一|purchase_trigger_qty、触发数量|
+|purchase_type|采购类型|Enum|是|采购计划主记录|SS04|SS03-1/SS03-2|量产/样品/现货/异常补货。|保留/细化|purchase_type|
+|urgency_flag|紧急程度|Enum/Boolean|是|采购计划主记录|SS04|SS03-1/SS03-2|普通/紧急/特急；影响评分权重。|保留/细化|urgency_flag|
+|plan_status|采购计划状态|Enum|是|采购计划主记录|SS04|SS03-1/SS03-2|有效/待执行/询价中/已满足/关闭。|保留/细化|plan_status|
+|triggered_at|触发询价时间|DateTime|条件必填|采购计划主记录|系统|SS03-1|记录进入询价流程的时间。|新增/统一|触发时间|
+|po_ref|关联采购订单引用|Link(D-16)|条件必填|采购计划主记录|系统|SS03-2|定点/执行后回链D-16。|重命名/统一|关联后续PO|
+
+#### L-02 客户主台账
+
+|统一字段名|中文字段名|数据类型|必填性|对象层|维护/来源|Demo使用|定义/取值/校验规则|处理建议|原字段/来源名称|
+|---|---|---|---|---|---|---|---|---|---|
+|customer_id|客户ID|Text/AutoNumber|是|客户主记录|SS01|W24/SS03/11-A2|所有客户侧台账统一锚点。|保留/统一|唯一ID、customer_id|
+|customer_name|客户名称|Text|是|客户主记录|SS01|W05/W24/11-A2|展示名称；法律主体与展示名称如不同需分开。|新增/统一|客户名称、客户|
+|legal_entity_name|客户法律主体|Text|条件必填|客户主记录|SS01|11-A2条件|单证、合同或制裁筛查需要时必填。|新增|主体信息|
+|customer_status|客户状态|Enum|是|客户主记录|SS01|W24/11-A2|有效/暂停/终止。|新增/统一|状态机|
+|default_contact_ref|默认联系人引用|Link(L-08)|条件必填|客户主记录|SS01|11-A2|与D-10提货联系人区分；D-10可覆盖为履约联系人。|新增/统一|联系人|
+
+#### D-01 交易与执行台账
+
+|统一字段名|中文字段名|数据类型|必填性|对象层|维护/来源|Demo使用|定义/取值/校验规则|处理建议|原字段/来源名称|
+|---|---|---|---|---|---|---|---|---|---|
+|order_id|订单号|Text/AutoNumber|是|订单主记录|SS04|11-A2/11-A3|订单执行主键。|保留/统一|order_id、订单号|
+|request_id|需求编号|Link(P-01)|条件必填|订单主记录|系统|11-A2|回链P-01需求。|统一|需求编号|
+|customer_id|客户ID|Link(L-02)|是|订单主记录|系统|11-A2/11-A3|客户名称通过L-02展示。|统一|customer_id|
+|project_id|项目ID|Link(P-05)|条件必填|订单主记录|系统|11-A2|项目追溯。|统一|项目|
+|internal_pn|内部料号|Link(P-08)|是|订单主记录|P-08/SS04|11-A2|内部料号统一引用P-08。|重命名/统一|mpn、料号|
+|customer_pn|客户料号|Text/Link(D-10)|条件必填|订单主记录|D-10/SS04|11-A2|通过D-10映射获得。|重命名/统一|customer_mpn|
+|order_qty|订单数量|Number|是|订单主记录|订单/系统|11-A2|交接实发数量核对基准。|保留/统一|order_qty|
+|allocation_ref|分配批次引用|Link(D-03)|条件必填|订单主记录|D-03/SS04|11-A2|指向D-03批次分配记录。|新增/统一|inventory_lot|
+|promised_delivery_date|承诺交期|Date|条件必填|订单主记录|P-04/SS04|11-A2|订单承诺交期。|重命名/统一|承诺交期|
+|trade_term|贸易术语|Enum|条件必填|订单主记录|D-10/P-04|11-A2|EXW等；风险转移逻辑依赖。|新增/统一|BT类型、贸易术语|
+|milestones|履约里程碑|Structure|是|订单主记录|系统/SS04|11-A2/11-A3|至少含交接；每个节点有状态、时间、来源、证据。|细化|milestones、里程碑|
+|pickup_status|提货状态|Enum|是|提货交接事实层|PW/系统|11-A2|待提货/已预约/已提货/待重新预约/取消。|保留/细化|pickup_status|
+|ship_date|发货日期|Date|现场交接时必填|提货交接事实层|PW|11-A2|现场事实；由PW唯一录入。|保留/细化|ship_date|
+|shipped_qty|实发数量|Number|现场交接时必填|提货交接事实层|PW|11-A2|现场事实；与order_qty及D-03同步校验。|保留/细化|shipped_qty|
+|handover_no|交接单号|Text|交接完成时必填|提货交接事实层|系统|11-A2|格式HD-YYYYMMDD-NNN。|保留/细化|handover_no|
+|receiver_name|签收人姓名|Text|交接完成时必填|提货交接事实层|PW|11-A2|双方签署事实。|重命名/统一|receiver、签收人姓名|
+|sign_time|交接签署时间|DateTime|交接完成时必填|提货交接事实层|PW|11-A2|EXW风险转移时点的事实基础。|保留/细化|sign_time、签署时间|
+|risk_transfer_time|风险转移时点|DateTime|签署后派生|提货交接事实层|系统/AI/PW确认|11-A2/11-A3|EXW场景默认等于sign_time；作为开票和后续追踪锚点。|保留/细化|risk_transfer_time|
+|handover_diff|交接差异|Enum/Structure|条件必填|提货交接事实层|PW/RI|11-A2|无差异/数量差异/型号差异/批次差异/包装差异/其他；关联差异单。|保留/细化|handover_diff|
+|handover_file_ref|交接单影像/文件|URL/Attachment|交接完成时必填|提货交接事实层|PW|11-A2|必须区分草稿、已签署、已归档。|重命名/统一|handover_file|
+|handover_doc_status|交接单文件状态|Enum|有handover_file_ref时必填|提货交接事实层|PW/系统|11-A2|草稿/已签署/已归档/作废；下游只消费已签署或已归档。|新增/统一|文档状态|
+|handover_notes|交接注意事项|LongText|条件必填|提货交接事实层|D-10/PW|11-A2|模板或现场特殊注意事项。|新增|交接注意事项|
+|logi_pickup|提货节点事实|Structure|11-A3必填|物流节点事实层|AI/PW|11-A3|含estimated_time、actual_time、source、collection_method、confirmation_status、anomaly_flag、evidence_ref。|保留/结构化|logi_pickup|
+|logi_clearance|报关节点事实|Structure|11-A3必填|物流节点事实层|AI/PW|11-A3|同上；异常如报关受阻、查验。|保留/结构化|logi_clearance|
+|logi_release|放行节点事实|Structure|11-A3必填|物流节点事实层|AI/PW|11-A3|同上。|保留/结构化|logi_release|
+|logi_departure|离港节点事实|Structure|11-A3必填|物流节点事实层|AI/PW|11-A3|同上；异常如离港延误。|保留/结构化|logi_departure|
+|track_note|物流跟踪/决策备注|LongText|条件必填|物流节点事实层|PW/RI|11-A3|货代不配合时记录降级为到货确认或销售协调等决策。|重命名/统一|track_note、决策记录|
+|track_visible|物流信息可查状态|Boolean|四节点完成后必填|物流节点事实层|系统|11-A3|四节点实际事实齐备后为True；不是人工主观勾选。|保留/细化|track_visible|
+|invoice_status|开票状态|Enum|是|订单状态层|系统/财务|11-A2|待开票/已触发/已开票/异常；risk_transfer_time为触发锚点。|新增/统一|开票状态|
+|acceptance_status|验收状态|Enum|是|订单状态层|履约Owner|11-A2|待验收/已确认/争议/不适用。|新增/统一|验收状态|
+|order_status|订单状态|Enum|是|订单状态层|系统/SS04|11-A2/11-A3|已放行/已交接/物流跟踪中/已完成/异常/关闭。|重命名/统一|订单状态机|
+|closed_flag|关闭标记|Boolean|是|订单状态层|系统/SS04|11-A2/11-A3|所有必需节点或异常处置完结后关闭。|新增/统一|关闭状态|
+|close_reason|关闭原因|LongText|关闭时必填|订单状态层|SS04|11-A2/11-A3|正常完成/取消/转异常流程等。|新增|关闭状态|
+|pickup_appointment_time|预约提货时间|DateTime|分支2场景必填|提货交接事实层|D-10/PW|11-A2|用于预约提醒、未按预约提货判断及重新预约。|新增/统一|提货预约时间|
+|physical_check_status|实物核对状态|Enum|交接前必填|提货交接事实层|PW|11-A2|未核对/已核对/不一致；核对数量、型号、批次标签和包装。|新增|实物一致性核对|
+|diff_handling_result|差异处理结果|Enum/Structure|有差异时必填|提货交接事实层|RI/PW|11-A2|补齐后交接/按实发量交接并标注/暂停并转后续Activity。|新增/统一|差异处理结果|
+|ri_gate_decision|RI门禁判断|Enum/LongText|差异或超时升级时必填|提货交接事实层|RI|11-A2/11-A3|放行/补齐后放行/暂停/转异常/降级追踪/联系客户核实。|新增/统一|RI门禁判断、决策记录|
+|ri_escalated_at|RI升级时间|DateTime|发生升级时必填|提货交接事实层|系统|11-A2/11-A3|差异、预约超时或节点反馈超时的升级事实。|新增|升级时限|
+|node_type|物流节点类型|Enum|是|物流节点子表（适用于logi_*）|系统|11-A3|提货/报关/放行/离港；对应logi_*字段。|新增/统一|四个关键节点|
+|estimated_time|节点预计时间|DateTime|是|物流节点子表（适用于logi_*）|系统/AI|11-A3|到达预计时间后触发确认请求。|新增/统一|节点预计时间|
+|actual_time|节点实际时间|DateTime|收到事实时必填|物流节点子表（适用于logi_*）|AI/PW|11-A3|收到反馈或人工电话确认的实际时间。|新增/统一|时间|
+|source|节点事实来源|Text/Link|是|物流节点子表（适用于logi_*）|AI/PW|11-A3|回复单位、系统或具体联系人；不得只写“外部”。|重命名/统一|来源、Source|
+|collection_method|节点采集方式|Enum|是|物流节点子表（适用于logi_*）|AI/PW|11-A3|邮件/微信/即时通讯/电话/人工录入。|重命名/统一|采集方式、Method|
+|confirmation_status|节点确认状态|Enum|是|物流节点子表（适用于logi_*）|系统/PW|11-A3|待确认/已确认/超时/异常/已升级。|新增/统一|确认状态|
+|anomaly_flag|节点异常标记|Boolean|是|物流节点子表（适用于logi_*）|AI/PW|11-A3|报关受阻、查验、离港延误等为True。|新增/统一|Anomaly Flag、异常节点标记|
+|anomaly_type|节点异常类型|Enum/Text|anomaly_flag=True时必填|物流节点子表（适用于logi_*）|AI/PW|11-A3|报关受阻/查验/离港延误/其他。|新增/统一|异常节点|
+|node_evidence_ref|节点事实证据|URL/Attachment|已确认或异常时必填|物流节点子表（适用于logi_*）|AI/PW|11-A3|回复原文、电话记录或其他节点证据。|新增/统一|证据引用|
+|reminder_count|节点提醒次数|Integer|是|物流节点子表（适用于logi_*）|系统|11-A3|按D-10最大提醒次数控制。|新增/统一|最大提醒次数|
+|last_request_at|最后请求时间|DateTime|有请求时必填|物流节点子表（适用于logi_*）|系统|11-A3|支持间隔天数和超时判断。|新增|确认请求|
+|node_ri_escalation_status|节点RI升级状态|Enum|超时/异常时必填|物流节点子表（适用于logi_*）|系统/RI|11-A3|未升级/已升级/已核实/已降级。|新增/统一|升级RI门禁|
+
+#### D-04 回款与信用台账
+
+|统一字段名|中文字段名|数据类型|必填性|对象层|维护/来源|Demo使用|定义/取值/校验规则|处理建议|原字段/来源名称|
+|---|---|---|---|---|---|---|---|---|---|
+|credit_record_id|信用记录ID|Text/AutoNumber|是|信用门禁主记录|系统|11-A2|回款信用门禁记录主键。|新增/统一|信用记录|
+|customer_id|客户ID|Link(L-02)|是|信用门禁主记录|SS04|11-A2|关联客户信用主体。|统一|客户ID|
+|payment_terms|账期条款|Text/Structure|是|信用门禁主记录|P-04/SS04|11-A2|从交易框架读取，作为信用判断依据。|重命名/统一|账期条款|
+|credit_limit|信用额度|Currency|条件必填|信用门禁主记录|商务/财务|11-A2|与currency_code成对。|统一|信用额度|
+|outstanding_amount|应收金额|Currency|是|信用门禁主记录|财务|11-A2|当前应收，需记录币种。|新增/统一|应收|
+|paid_amount|已回款金额|Currency|是|信用门禁主记录|财务|11-A2|当前已回款，需记录币种。|新增/统一|已回款|
+|overdue_days|逾期天数|Integer|是|信用门禁主记录|系统/财务|11-A2|信用预警触发依据。|保留/细化|逾期天数|
+|credit_rating|信用评级|Enum|是|信用门禁主记录|财务/商务|11-A2|正常/关注/高风险/冻结。|保留/细化|信用评级|
+|warning_status|信用预警状态|Enum|是|信用门禁主记录|系统/财务|11-A2|无预警/预警/拦截/已解除。|保留/细化|预警状态|
+
+#### D-03 库存与在途台账
+
+|统一字段名|中文字段名|数据类型|必填性|对象层|维护/来源|Demo使用|定义/取值/校验规则|处理建议|原字段/来源名称|
+|---|---|---|---|---|---|---|---|---|---|
+|inventory_record_id|库存记录ID|Text/AutoNumber|是|库存批次记录|系统|11-A2|库存事实主键。|新增/统一|库存记录|
+|internal_pn|内部料号|Link(P-08)|是|库存批次记录|P-08/SS04|11-A2|统一引用P-08。|重命名/统一|料号|
+|manufacturer_lot|原厂批次|Text|条件必填|库存批次记录|供应商/仓库|11-A2|交接单/COC披露。|重命名/统一|mfr_lot、lot|
+|date_code|日期码DC|Text|条件必填|库存批次记录|供应商/仓库|11-A2|交接单/COC披露。|重命名/统一|dc、Date Code|
+|available_qty|可用数量|Number|是|库存批次记录|仓库|11-A2|可出库库存。|新增/统一|可用|
+|inspection_qty|待检数量|Number|是|库存批次记录|仓库|11-A2|状态数量。|新增/统一|待检|
+|frozen_qty|冻结数量|Number|是|库存批次记录|仓库|11-A2|状态数量。|新增/统一|冻结|
+|in_transit_qty|在途数量|Number|是|库存批次记录|系统|11-A2|与D-16履约关联。|新增/统一|在途|
+|allocation_id|分配记录ID|Text/AutoNumber|是|库存批次记录|系统|11-A2|批次占用与订单绑定。|新增/统一|子表2|
+|allocated_qty|已分配数量|Number|是|库存批次记录|系统|11-A2|与allocation_status配套。|新增/统一|分配数量|
+|allocation_status|分配状态|Enum|是|库存批次记录|系统/PW确认|11-A2|已分配/部分出库/已出库/释放。|重命名/统一|alloc_status|
+|shipped_qty|已出库数量|Number|是|库存批次记录|系统/PW确认|11-A2|与D-01.shipped_qty同步。|保留/细化|shipped_qty|
+|last_ship_date|最后出库日期|Date|条件必填|库存批次记录|系统/PW确认|11-A2|该批次最后一次出库事实。|保留/细化|last_ship_date|
+|moq_qty|库存批次MOQ|Number|条件必填|库存批次记录|S-05/供应商|11-A2|备货决策参考。|新增/统一|MOQ|
+|lead_time_days|库存批次交期天数|Number|条件必填|库存批次记录|S-05/供应商|11-A2|备货与在途判断。|新增/统一|交期|
+|stocking_decision|备货决策|Enum/Structure|条件必填|库存批次记录|履约Owner|11-A2|维持/补货/冻结/退出。|新增/统一|备货决策|
+|exit_plan|退出方案|LongText/Structure|stocking_decision=退出时必填|库存批次记录|履约Owner|11-A2|异常PN或库存退出动作。|新增/统一|退出方案|
+
+#### D-10 客户履约主数据台账
+
+|统一字段名|中文字段名|数据类型|必填性|对象层|维护/来源|Demo使用|定义/取值/校验规则|处理建议|原字段/来源名称|
+|---|---|---|---|---|---|---|---|---|---|
+|execution_profile_id|履约参数档案ID|Text/AutoNumber|是|执行参数主记录|SS04|11-A2/11-A3|客户履约参数的版本化主键。|新增/统一|执行参数|
+|customer_id|客户ID|Link(L-02)|是|执行参数主记录|SS04|11-A2/11-A3|履约参数按客户维护。|统一|客户|
+|incoterms|贸易术语|Enum|是|执行参数主记录|履约Owner|11-A2|EXW等；影响风险转移规则。|新增/统一|贸易术语|
+|packaging_requirements|包装要求|LongText/Structure|条件必填|执行参数主记录|履约Owner|11-A2|生成交接单和实物核对依据。|重命名/统一|包装|
+|label_requirements|标签要求|LongText/Structure|条件必填|执行参数主记录|履约Owner|11-A2|实物核对依据。|重命名/统一|标签|
+|document_requirements|单证要求|Structure|条件必填|执行参数主记录|履约Owner|11-A2|客户格式与单证清单要求。|重命名/统一|单证要求|
+|logistics_preference|物流偏好|Structure|条件必填|执行参数主记录|履约Owner|11-A3|节点采集偏好。|重命名/统一|物流偏好|
+|service_level|服务等级|Enum/Structure|条件必填|执行参数主记录|履约Owner|11-A3|节点可见性和响应要求。|新增/统一|服务等级|
+|alert_thresholds|预警阈值|Structure|条件必填|执行参数主记录|履约Owner|11-A3|节点超时、异常延误等阈值。|新增/统一|预警阈值|
+|pickup_contact_ref|提货联系人引用|Link(L-08)/Text|是|执行参数主记录|履约Owner|11-A2/11-A3|用于交接单和未按预约提货提醒。|重命名/统一|pickup_contact|
+|pickup_appointment_mode|预约提货方式|Enum|是|执行参数主记录|履约Owner|11-A2|预约/临时/固定窗口等。|重命名/统一|pickup_appt_mode|
+|logistics_confirmation_channel|物流节点确认渠道|Enum|是|执行参数主记录|履约Owner|11-A3|邮件/微信/即时通讯/电话。|重命名/统一|logi_channel、确认通道|
+|logistics_confirmation_interval_days|节点确认间隔天数|Integer|是|执行参数主记录|履约Owner|11-A3|默认3天；可按客户配置。|重命名/统一|logi_interval|
+|logistics_max_reminder_count|最大提醒次数|Integer|是|执行参数主记录|履约Owner|11-A3|默认3次；达到后升级RI。|重命名/统一|logi_max_retry|
+|handover_template_ref|交接单模板引用|URL/Attachment|是|执行参数主记录|履约Owner|11-A2|生成交接单草稿。|重命名/统一|handover_tpl|
+|handover_notes|交接注意事项|LongText|条件必填|执行参数主记录|履约Owner|11-A2|客户特殊注意事项；生成交接单。|新增/统一|交接注意事项|
+|mapping_id|料号映射ID|Text/AutoNumber|是|料号映射子表|系统|11-A2|客户料号与内部料号一对一版本记录。|新增|料号映射|
+|customer_pn|客户料号|Text|是|料号映射子表|履约Owner|11-A2|客户侧料号。|重命名/统一|客户料号、customer_mpn|
+|internal_pn|内部料号|Link(P-08)|是|料号映射子表|履约Owner|11-A2|内部统一料号。|重命名/统一|internal_pn|
+|mapping_version|映射版本|Text|是|料号映射子表|履约Owner|11-A2|料号映射版本受控。|新增/统一|版本|
+|mapping_status|映射状态|Enum|是|料号映射子表|履约Owner|11-A2|有效/待确认/过期/作废。|新增/统一|状态|
+|difference_flag|映射差异标记|Boolean/Structure|是|料号映射子表|系统/履约Owner|11-A2|客户料号与内部料号无法一一对应时标记并说明。|新增/统一|差异标注|
+
+#### D-11 出口单证台账
+
+|统一字段名|中文字段名|数据类型|必填性|对象层|维护/来源|Demo使用|定义/取值/校验规则|处理建议|原字段/来源名称|
+|---|---|---|---|---|---|---|---|---|---|
+|document_set_id|单证包ID|Text/AutoNumber|是|单证包主记录|系统|11-A2|订单级单证包唯一标识。|新增/统一|证据包|
+|order_id|订单号|Link(D-01)|是|单证包主记录|系统|11-A2|回链D-01订单。|新增/统一|订单号|
+|invoice_ref|发票文件引用|URL/Attachment|条件必填|单证包主记录|履约/财务|11-A2|随货单证之一。|重命名/统一|发票|
+|packing_list_ref|箱单文件引用|URL/Attachment|条件必填|单证包主记录|履约|11-A2|随货单证之一。|重命名/统一|箱单|
+|coc_ref|COC文件引用|URL/Attachment|条件必填|单证包主记录|履约/质量|11-A2|随货单证之一。|重命名/统一|COC|
+|certificate_of_origin_ref|产地证文件引用|URL/Attachment|条件必填|单证包主记录|履约|11-A2|按客户或贸易场景要求。|重命名/统一|产地证|
+|warranty_certificate_ref|质保书文件引用|URL/Attachment|条件必填|单证包主记录|履约|11-A2|随货单证之一。|重命名/统一|质保书|
+|required_document_types|应提供单证类型|MultiEnum|是|单证包主记录|D-10/履约|11-A2|根据D-10.document_requirements生成。|新增/统一|单证清单、客户格式要求|
+|document_set_complete|单证包齐套状态|Enum|是|单证包主记录|系统/PW|11-A2|未齐套/已齐套；已齐套至少满足本订单required_document_types。|保留/细化|doc_set_complete|
+|consistency_check_status|单证一致性审核状态|Enum|是|单证包主记录|系统/PW|11-A2|未审核/通过/不通过/待补正；核对订单、料号、数量、批次、客户信息。|新增/统一|一致性审核|
+|consistency_check_result|单证一致性审核结果|LongText/Structure|审核后必填|单证包主记录|系统/PW|11-A2|记录差异项、责任人和补正动作。|新增/统一|一致性审核记录|
+|document_archive_ref|单证包归档引用|URL/Attachment|归档时必填|单证包主记录|系统/履约|11-A2|正式证据包统一归档。|新增/统一|证据包|
+|archive_due_date|归档期限|Date|条件必填|单证包主记录|履约Owner|11-A2|依据客户或合规要求。|新增/统一|归档期限|
+|document_type|单证类型|Enum|是|单证明细子表|系统|11-A2|发票/箱单/COC/产地证/质保书/其他。|新增/统一|doc_list|
+|document_ref|单证文件引用|URL/Attachment|是|单证明细子表|履约|11-A2|单证文件。|重命名/统一|doc_list|
+|document_status|单证文件状态|Enum|是|单证明细子表|系统/履约|11-A2|草稿/已核验/已归档/作废。|新增/统一|文档状态|
+|document_version|单证版本|Text|是|单证明细子表|系统/履约|11-A2|单证修改必须递增。|新增/统一|版本|
+
+
+## 五、重叠字段与统一命名清单
+
+下表列出不同Activity或台账中“含义相同但写法不同”“层级不同却使用同名”“同一字段承载多个语义”的主要问题，以及本次建议的统一口径。
+
+|冲突主题|涉及台账/Activity|原有写法|统一字段名|统一口径|
+|---|---|---|---|---|
+|客户ID|P-01/P-02/P-04/P-06/P-09/S-04/D-01/D-10/L-02；W05/W24/SS03/11-A2|customer_id、客户ID、客户/项目、客户名称|customer_id；展示字段customer_name|ID只存L-02.customer_id；名称通过关联展示，不在业务台账重复维护。|
+|项目关联|P-01/P-02/P-04/P-06/P-09/S-04/D-15/D-01；W05/W24/SS03/11-A2|project_id、客户/项目、项目|project_id|项目对象只保留ID关联；项目名称由P-05展示。|
+|内部料号|P-01/P-02/P-03/P-06/P-08/P-11/S-04/S-05/D-15/D-01/D-03/D-10；W05/W24/SS03/11-A2|pn、mpn、标准型号PN、Validation_PN、Original_PN、Candidate_PN|internal_pn；原物料用original_internal_pn，候选物料用candidate_internal_pn|全链路只认P-08.internal_pn；不得将mpn、pn、型号混作同一字段。|
+|客户料号|P-01/P-08/D-01/D-10；W05/W24/11-A2|customer_mpn、客户料号|customer_pn|客户料号与internal_pn分开；正式映射落D-10料号映射子表。|
+|品牌/原厂|P-08/P-10/S-04/S-05/SS03|brand、manufacturer_brand、原厂或品牌|brand_name；制造商另用manufacturer_name|品牌、制造商、供应商不是同一对象；S-04/S-05引用brand_name与supplier_id。|
+|数量|P-01/S-04/D-15/D-01/D-03/W24/SS03/11-A2|数量、target_qty、purchase_trigger_qty、order_qty、shipped_qty、actual_qty|target_qty、trigger_qty、order_qty、actual_qty、shipped_qty、allocated_qty|按业务语义分开；数量阶梯统一用quantity_tier子表，不用文本拼接。|
+|交期/时间窗|P-01/S-04/D-15/P-02/S-05/W24/SS03|target_delivery_date、requirement_date、quote_return_due_at、quote_due_at、lead_time/LT|target_delivery_date、requirement_date、quote_due_at、lead_time_days|目标日期、需求日期、报价截止时间、供货时长四类概念分开；原始说明写lead_time_note。|
+|价格类型|P-01/P-02/P-03/S-04/S-05/W24/SS03|price_types_default、price_types_requested、price_type、报价类型|requested_price_types（需求层）；price_type（价格明细层）；quote_type（报价主记录层）|需求要什么价格、这一行是什么价格、这份报价属于什么业务类型分别建字段。|
+|价格/币种|P-01/P-02/P-03/S-04/S-05/W24/SS03|报价价格/币种、unit_price、benchmark_unit_price、currency|金额字段按对象命名，币种统一currency_code；跨币种另记comparison_currency_code/conversion_rate|金额与币种成对出现；currency不再作为模糊字段名。|
+|有效期|P-02/P-03/S-04/S-05/W24/SS03|生效期、失效期、报价有效期、valid_until、effective_from/to|valid_from、valid_to；报价主记录用quote_valid_until|Price List/采购基准的有效区间用valid_from/valid_to；报价对外有效期用quote_valid_until。|
+|状态|P-01/P-02/P-03/P-06/P-11/S-04/S-05/D-01/D-03/D-10/D-11/W05/W24/SS03/11-A2/11-A3|状态机、状态、approval_status、publish_status、doc_set_complete|对象业务状态与record_status分离；各对象保留*_status命名|record_status只管记录生命周期；quote_status、approval_status等只管业务流程。|
+|版本|P-01/P-02/P-03/P-06/P-08/P-10/P-11/D-10/S-04/W05/W24/SS03/11-A2|版本、需求版本、Release版本、报价版本、Datasheet版本、规则版本|对象字段用requirement_version/quote_version/release_version/document_version/mapping_version；通用用record_version；规则用rule_version|版本必须绑定对象和用途，不再使用裸字段version。|
+|证据/附件/链接|P-01/P-02/P-06/P-10/P-11/S-04/D-01/D-11/W05/W24/SS03/11-A2/11-A3|evidence、证据引用、输出文件链接、handover_file、doc_list|evidence_ref；对象文件用*_ref；输出用output_ref；交接单用handover_file_ref|证据引用可多值且必须可定位；业务对象文件链接按对象命名。|
+|供应商主体/联系人|S-03/S-04/S-05/SS03|supplier_id、供应商ID、sales_contact、联系人|supplier_id；sales_contact_ref；contact_channel|供应商主体与联系人分离；联系渠道记录在供应商主数据，实际发送渠道记录在S-04.send_channel。|
+|询价批次/比价组|S-04/SS03|rfq_batch_id、comparison_group|rfq_batch_id；comparison_group_id|批次是询价过程容器；比价组是同条件可比集合，两者不可互代。|
+|MOQ/SPQ|P-02/S-04/S-05/D-03/W24/SS03/11-A2|MOQ-SPQ、MOQ、SPQ|moq_qty、spq_qty|拆分为两个数值字段，适用对象前缀由台账区分。|
+|交期LT|S-04/S-05/P-02/SS03/W24|LT、lead_time、交期|lead_time_days；lead_time_note|标准化时长与原始说明分开；统一日历口径由GOV定义。|
+|替代关系与批准|P-01/P-02/P-06/P-08/P-11/W05/W24|替代等级、推荐、批准状态、验证结果、P-11-01/P-11-02|recommendation_level、analysis_status、customer_approval_status、validation_status|推荐、分析、验证、客户批准四个阶段分开，P-11作为统一关系主对象。|
+|风险等级|P-01/P-02/P-06/P-11/S-05/D-18/W05/W24/SS03|风险等级、供应风险、问题与风险|risk_level（通用决策风险）；supply_risk_level（供应能力风险）；issue_risk（问题明细）|不同风险对象不共用一个自由文本字段。|
+|交接/物流节点|D-01/D-03/D-10/D-11/11-A2/11-A3|milestones、ship_date、logi_pickup、track_note、交接|milestones；交接事实字段；logi_*节点结构；track_note|交接是法律/责任事实；物流节点是后续过程事实，统一回链同一order_id但不混成一个字段。|
+
+## 六、必须落地的结构化规则
+
+|标准项|标准定义|示例|
+|---|---|---|
+|ID命名|业务对象主键使用<对象>_id；跨台账引用保留同名ID并采用Link。|request_id、supplier_id、order_id|
+|料号命名|internal_pn表示内部标准料号；customer_pn表示客户料号；original_internal_pn/candidate_internal_pn只用于替代关系上下文。|P-08.internal_pn、D-10.customer_pn|
+|金额与币种|所有金额字段必须与currency_code成对；跨币种比较在决策记录中另记comparison_currency_code与conversion_rate。|unit_price + currency_code|
+|数量阶梯|数量阶梯使用结构化子表，至少包含min_qty、max_qty、price或discount；禁止把多个阶梯拼接为自由文本。|P-02 QuoteLine.quantity_tier|
+|时间字段|发生时点用*_at（DateTime），业务日期用*_date（Date），持续时长用*_days（Number）。|quote_due_at、target_delivery_date、lead_time_days|
+|版本字段|不使用裸version；必须指明对象：requirement_version、quote_version、release_version、document_version、record_version、rule_version。|P-02.quote_version|
+|状态字段|record_status管记录生命周期；对象业务流程用*_status；派生可见性用*_flag或*_visible。|record_status、approval_status、track_visible|
+|证据字段|evidence_ref表示证据集合；对象文件按对象命名为*_ref；证据必须支持URL/附件/定位信息。|quote_evidence_ref、handover_file_ref、citation_locator|
+|节点结构|物流节点统一包含estimated_time、actual_time、source、collection_method、confirmation_status、anomaly_flag、evidence_ref。|D-01.logi_pickup|
+|主记录与子表|主记录保存上下文、状态和汇总；逐PN/BOM位/阶梯/参数/单证的重复明细使用子表。|P-02 QuoteLine、P-11差异明细、D-11单证明细|
+
+## 七、实施优先级与待确认事项
+
+**P0：**先落实P-01、P-02、P-11、S-04、D-01的主记录与子表结构，并建立统一ID、料号、版本、状态和证据字段。P-02如果不建立QuoteLine，PN×BOM位×数量阶梯无法稳定支撑报价和版本管理；P-11如果不建立差异明细，差异评估只能保留摘要，无法被AI复核或下游消费；S-04如果不拆RFQ/Quote/Decision三层，询价事实、供应商回复和定点结论会互相覆盖。
+
+**P1：**落实条件必填与校验规则，包括代理证、涨价原因、跨币种换算、报价/基准有效期、风险转移时点、交接文件状态、物流节点异常及提醒次数。
+
+**P1：**明确以下业务口径后固化到GOV规则：lead_time_days按自然日还是工作日；毛利计算公式和阈值；价格来源优先级；汇率来源与as_of；Incoterms及地点字段；客户批准与FAE分析结论的权限边界；D-10履约参数的客户级/物流公司级配置粒度。
+
+**P2：**将S-05基准、D-03库存与D-16采购履约的数据同步关系做成系统接口；将D-01物流节点结构接入客户可查询视图，并将异常节点回链D-18或既有异常归集Activity。
+
+
+## 八、交付物说明
+
+本Markdown用于评审和阅读；配套Excel提供可直接继续维护的“字段总表”“Activity覆盖矩阵”“重叠字段统一”“字段标准”四张工作表，并保留“说明”页作为使用口径。
+
+
+## 参考附件
+
+[1]: /home/ubuntu/upload/SS01-02-03-04-台账体系全景-18Activity关联矩阵(2).html "SS01-02-03-04-台账体系全景：18 Activity关联矩阵"
+
+[2]: /home/ubuntu/upload/SS02_ACT-WORK-05_差异评估_E04-I01架构版_V1.2(1).html "SS02 ACT-WORK-05 差异评估"
+
+[3]: /home/ubuntu/upload/SS02_ACT-WORK-24_报价方案制定_E04-I01架构版_V1.2(1).html "SS02 ACT-WORK-24 报价方案制定"
+
+[4]: /home/ubuntu/upload/SS03询价ActivityDemo(1).html "SS03 询价 Activity Demo"
+
+[5]: /home/ubuntu/upload/20260826-11-A2架构版（E04-I01v1.2）.html "SS04 ACT-11-A2 提货交接与风险转移"
+
+[6]: /home/ubuntu/upload/20260826-SS04-SOP-11活动描述样板（11-A3）.html "SS04 11-A3 物流执行信息跟踪活动描述样板"

docs/adr/ADR-012-keycloak-identity.md

@@ -55,3 +55,26 @@
 - Keycloak 侧前置(管理员):本服务 client(建议复用 `api-gateway`)、`web-console` 补 audience mapper、
   provisioning 服务账号、e2e 服务账号 client(`bpos-e2e`,realm 角色 admin,firstName「AI」)。
 - 欠账见 `docs/debt.md`「鉴权」段。
+
+## 补充(2026-08-26):成员与组织三页签
+
+运营中心「员工」那一屏按目标件重做成三个页签,一一对着 Keycloak 的三样东西:
+
+| 页签 | 数据来自 | 写去哪 |
+|---|---|---|
+| **成员** | Keycloak users(合本地的岗位与「几时来过」) | 穿透 Keycloak:新建 / 改资料 / 启停 / 重置口令 / 删除 |
+| **权限** | Keycloak realm roles × 本地 `sys.role_access` | 端配置写本地;角色授收穿透 Keycloak |
+| **组织** | Keycloak groups | 穿透:建组 / 改名 / 删组 / 成员进出组 |
+
+`/api/gov/org/*` 十五条,`access` 一律 `ops`。三处口径值得记:
+
+1. **写是穿透的,没有撤销** —— 这里建的人立刻能登录、停的人立刻登不上。界面上凡写必二次确认
+   (三必答:谁受影响 / 能不能撤 / 几时生效)。
+2. **服务账号是身份不是人** —— 目录读一律剔除、写面一律 403。停掉它的后果不显眼却很重:
+   试跑与 e2e 第二天全趴下。
+3. **两种 502 分开说**:`keycloak-misconfigured`(服务账号缺角色,重试无益,去补权限)与
+   `keycloak-unavailable`(暂时够不着,可退避重试)。**重试有没有意义**是分界 —— 混成一个 code,
+   界面只能说一句含糊的「出错了」。
+
+同批拿掉的:「岗位授权」与「工作组」两个页签(用户定)。**后端数据与接口原样留着** ——
+岗位仍决定活动派单的候选集,工作组仍在起单那一刻快照进工作流;拿掉的只是入口。

packages/contracts/src/api/http.ts

@@ -64,6 +64,13 @@ export const API_ERROR_CODES = [
   'precondition-failed',
   'internal',
   'gone',
+  /*
+   * 成员目录专用的两档 502(ADR-012)—— **重试有没有意义**是它们的分界,
+   * 前端据此说两句不同的话:一句「找管理员补权限」,一句「过会儿再点」。
+   * 混成一个 code 的话,界面只能说一句含糊的「出错了」。
+   */
+  'keycloak-misconfigured',
+  'keycloak-unavailable',
 ] as const;
 export type ApiErrorCode = (typeof API_ERROR_CODES)[number];
 

packages/contracts/src/api/index.ts

@@ -1,5 +1,6 @@
 export * from './http.ts';
 export * from './workbench.ts';
 export * from './governance.ts';
+export * from './org-directory.ts';
 export * from './ingest.ts';
 export * from './mail.ts';

packages/contracts/src/api/org-directory.ts

@@ -0,0 +1,260 @@
+/**
+ * 成员与组织(ADR-012 · 运营中心「员工」那一屏的三个页签)。
+ *
+ * **真源是 Keycloak**:读接口是它的投影,写接口**直接穿透**到 Admin API ——
+ * 这里建的人立刻能登录、这里停的人立刻登不上、这里删的人从 Keycloak 消失。
+ * 没有「先存本地草稿再同步」这回事,**也没有撤销**;界面上凡写必二次确认。
+ *
+ * 与本地名册的关系:`sys.staff` 是这份目录的投影 + 一列本地岗位(见 org/CONTRACT.md)。
+ * 涉及身份的写(停用 / 删除 / 授收角色)之后,本地那一行当场跟手 —— 两屏不许说两句话。
+ *
+ * 三处口径与 Keycloak 的形状有关,写在这儿免得每条接口重复:
+ *  ① **服务账号一律不可见、不可写**:目录读剔除 `service-account-*`(它是身份不是人,
+ *    见 `staffKindSchema`);写面对着服务账号的 sub 一律 403。
+ *  ② **组树是平表**:一行一个组,靠 `parentId` / `depth` 表达层级(按 `path` 升序已排好)。
+ *    契约里不放递归结构 —— 递归 schema 到了声明文件那一层只会变成一坨 any。
+ *  ③ **列表无分页**:realm 不大,一次拉全;Keycloak 那一侧的 100 条上限由适配器分页兜住。
+ */
+import { z } from 'zod';
+import type { RouteContract } from './http.ts';
+import { surfaceSchema } from './http.ts';
+
+/* ── 成员 ─────────────────────────────────────────────────────────────── */
+
+export const orgUserSchema = z.object({
+  /** Keycloak 用户 id(= `sub`,业务外键用它,不用用户名) */
+  sub: z.string().min(1),
+  /** 登录名,建后不可改 */
+  username: z.string().min(1),
+  /** `firstName lastName` 直拼;皆空回落 username —— 不会是空串 */
+  displayName: z.string().min(1),
+  email: z.string().optional(),
+  enabled: z.boolean(),
+  /** realm 角色(家具角色已滤) */
+  roles: z.array(z.string()),
+  /** 这些角色合起来能进哪几个端 —— 由 `sys.role_access` 算,不是 Keycloak 的字段 */
+  ends: z.array(surfaceSchema),
+  /** 本地名册记的「几时来过」;没有 = 还没拿这枚身份访问过本系统 */
+  lastSeenAt: z.string().optional(),
+  /** 本地岗位(哨兵岗 NONE = 未分配)—— 目录里只读,改岗位走 `setStaffPositionRoute` */
+  positionCode: z.string().optional(),
+});
+export type OrgUser = z.infer<typeof orgUserSchema>;
+
+export const orgUserDetailSchema = orgUserSchema.extend({
+  firstName: z.string().optional(),
+  lastName: z.string().optional(),
+  emailVerified: z.boolean(),
+  /** 直属组;`path` 形如 `/技术部/平台组` */
+  groups: z.array(z.object({ id: z.string(), path: z.string() })),
+});
+export type OrgUserDetail = z.infer<typeof orgUserDetailSchema>;
+
+export const listOrgUsersRoute = {
+  method: 'GET',
+  path: '/api/gov/org/users',
+  access: 'ops',
+  output: z.object({ users: z.array(orgUserSchema) }),
+} as const satisfies RouteContract;
+
+export const getOrgUserRoute = {
+  method: 'GET',
+  path: '/api/gov/org/users/:sub',
+  access: 'ops',
+  params: z.object({ sub: z.string().min(1) }),
+  output: orgUserDetailSchema,
+} as const satisfies RouteContract;
+
+/**
+ * 新建成员 —— 建完立刻能登录。口令是**临时**的:本人首登必须改
+ * (`temporary:true`,手册 §14.2);我们不存它,也不回显。
+ */
+export const createOrgUserRoute = {
+  method: 'POST',
+  path: '/api/gov/org/users',
+  access: 'ops',
+  body: z.object({
+    username: z.string().min(1),
+    firstName: z.string().optional(),
+    lastName: z.string().optional(),
+    email: z.string().optional(),
+    /** 临时口令;不给就建一个登不进来的壳(人自己去改密码那条路) */
+    password: z.string().min(1).optional(),
+    /** 一并授的 realm 角色;不给就只有 Keycloak 的默认角色 */
+    roles: z.array(z.string()).optional(),
+  }),
+  output: orgUserSchema,
+} as const satisfies RouteContract;
+
+/** 改资料(姓名 / 邮箱)—— 用户名建后不可改,不在这里 */
+export const patchOrgUserRoute = {
+  method: 'PATCH',
+  path: '/api/gov/org/users/:sub',
+  access: 'ops',
+  params: z.object({ sub: z.string().min(1) }),
+  body: z.object({
+    firstName: z.string().optional(),
+    lastName: z.string().optional(),
+    email: z.string().optional(),
+  }),
+  output: orgUserSchema,
+} as const satisfies RouteContract;
+
+/**
+ * 启用 / 停用。停用**立刻踢掉该用户全部会话** —— 不然他攥着的 token
+ * 还能用到过期为止,而「已停用」这三个字在界面上已经写出去了(界面不撒谎)。
+ */
+export const setOrgUserEnabledRoute = {
+  method: 'POST',
+  path: '/api/gov/org/users/:sub/enabled',
+  access: 'ops',
+  params: z.object({ sub: z.string().min(1) }),
+  body: z.object({ enabled: z.boolean() }),
+  output: orgUserSchema,
+} as const satisfies RouteContract;
+
+/** 重置口令 —— 一律临时口令,本人首登必须改;服务端不回显、不留痕 */
+export const resetOrgUserPasswordRoute = {
+  method: 'POST',
+  path: '/api/gov/org/users/:sub/reset-password',
+  access: 'ops',
+  params: z.object({ sub: z.string().min(1) }),
+  body: z.object({ password: z.string().min(1) }),
+  output: z.object({ ok: z.literal(true) }),
+} as const satisfies RouteContract;
+
+/** 删人 —— 从 Keycloak 消失,不可撤销;本地名册那一行同批停用(留痕与在途还挂着他) */
+export const deleteOrgUserRoute = {
+  method: 'DELETE',
+  path: '/api/gov/org/users/:sub',
+  access: 'ops',
+  params: z.object({ sub: z.string().min(1) }),
+  output: z.object({ ok: z.literal(true) }),
+} as const satisfies RouteContract;
+
+/* ── 权限:realm 角色 × 能进哪几个端 × 谁持有 ─────────────────────────── */
+
+export const orgRoleSchema = z.object({
+  name: z.string().min(1),
+  description: z.string().optional(),
+  /** Keycloak 的组合角色(展开后会带出别的角色) */
+  composite: z.boolean(),
+  /** 这个角色能进哪几个端(`sys.role_access`;没配过 = 空 = 哪儿都进不去) */
+  ends: z.array(surfaceSchema),
+  /** 持有它的成员数(已剔服务账号) */
+  holders: z.number().int().nonnegative(),
+});
+export type OrgRole = z.infer<typeof orgRoleSchema>;
+
+export const listOrgRolesRoute = {
+  method: 'GET',
+  path: '/api/gov/org/roles',
+  access: 'ops',
+  output: z.object({ roles: z.array(orgRoleSchema) }),
+} as const satisfies RouteContract;
+
+/**
+ * 授 / 收一个 realm 角色。收权**立刻踢掉该用户全部会话**(手册 §17.3)——
+ * 否则他手上那枚 token 还带着旧角色,收权要等到 token 过期才生效。
+ * 不能收自己的最后一条进运营中心的路(409)—— 收完没人进得来,这扇门就锁死了。
+ */
+export const setOrgUserRoleRoute = {
+  method: 'POST',
+  path: '/api/gov/org/users/:sub/roles/:role',
+  access: 'ops',
+  params: z.object({ sub: z.string().min(1), role: z.string().min(1) }),
+  body: z.object({ granted: z.boolean() }),
+  output: orgUserSchema,
+} as const satisfies RouteContract;
+
+/* ── 组织:Keycloak 组 ─────────────────────────────────────────────────── */
+
+export const orgGroupSchema = z.object({
+  id: z.string().min(1),
+  name: z.string().min(1),
+  /** 从根拼下来,如 `/技术部/平台组` */
+  path: z.string().min(1),
+  /** 顶层组为空 */
+  parentId: z.string().optional(),
+  /** 0 = 顶层 */
+  depth: z.number().int().nonnegative(),
+  /** 本组**直属**成员数(已剔服务账号,不含子组) */
+  memberCount: z.number().int().nonnegative(),
+});
+export type OrgGroup = z.infer<typeof orgGroupSchema>;
+
+/** 组树平表,按 `path` 升序 —— 层级看 `parentId` / `depth` */
+export const listOrgGroupsRoute = {
+  method: 'GET',
+  path: '/api/gov/org/groups',
+  access: 'ops',
+  output: z.object({ groups: z.array(orgGroupSchema) }),
+} as const satisfies RouteContract;
+
+/** 组的直属成员(含被停用的人 —— 这一屏管的是归属,不是能不能登录) */
+export const listOrgGroupMembersRoute = {
+  method: 'GET',
+  path: '/api/gov/org/groups/:id/members',
+  access: 'ops',
+  params: z.object({ id: z.string().min(1) }),
+  output: z.object({ members: z.array(orgUserSchema) }),
+} as const satisfies RouteContract;
+
+/** 建组:`parentId` 给了就是子组,不给就是顶层组。同级不得重名(Keycloak 那一侧拦,409) */
+export const createOrgGroupRoute = {
+  method: 'POST',
+  path: '/api/gov/org/groups',
+  access: 'ops',
+  body: z.object({ name: z.string().min(1), parentId: z.string().optional() }),
+  output: orgGroupSchema,
+} as const satisfies RouteContract;
+
+export const renameOrgGroupRoute = {
+  method: 'PATCH',
+  path: '/api/gov/org/groups/:id',
+  access: 'ops',
+  params: z.object({ id: z.string().min(1) }),
+  body: z.object({ name: z.string().min(1) }),
+  output: orgGroupSchema,
+} as const satisfies RouteContract;
+
+/** 删组 —— 连同子组一起没(Keycloak 语义);人不会被删,只是不再属于这个组 */
+export const deleteOrgGroupRoute = {
+  method: 'DELETE',
+  path: '/api/gov/org/groups/:id',
+  access: 'ops',
+  params: z.object({ id: z.string().min(1) }),
+  output: z.object({ ok: z.literal(true) }),
+} as const satisfies RouteContract;
+
+/** 成员进 / 出组 */
+export const setOrgUserGroupRoute = {
+  method: 'POST',
+  path: '/api/gov/org/users/:sub/groups/:groupId',
+  access: 'ops',
+  params: z.object({ sub: z.string().min(1), groupId: z.string().min(1) }),
+  body: z.object({ member: z.boolean() }),
+  output: z.object({ ok: z.literal(true) }),
+} as const satisfies RouteContract;
+
+/**
+ * 这一屏的全部路由 —— 归属一处列全,测试拿它逐条断言。
+ * 逐个 import 去断言的写法,新增一条只要忘了加进名单就悄悄漏过去了。
+ */
+export const ORG_DIRECTORY_ROUTES = [
+  listOrgUsersRoute,
+  getOrgUserRoute,
+  createOrgUserRoute,
+  patchOrgUserRoute,
+  setOrgUserEnabledRoute,
+  resetOrgUserPasswordRoute,
+  deleteOrgUserRoute,
+  listOrgRolesRoute,
+  setOrgUserRoleRoute,
+  listOrgGroupsRoute,
+  listOrgGroupMembersRoute,
+  createOrgGroupRoute,
+  renameOrgGroupRoute,
+  deleteOrgGroupRoute,
+  setOrgUserGroupRoute,
+] as const satisfies readonly RouteContract[];

packages/contracts/src/org.ts

@@ -21,6 +21,20 @@ export const STAFF_STATES = ['active', 'disabled'] as const;
 export const staffStateSchema = z.enum(STAFF_STATES);
 export type StaffState = z.infer<typeof staffStateSchema>;
 
+/**
+ * 人,还是服务账号。
+ *
+ * Keycloak 给每个开了 `serviceAccountsEnabled` 的 client 自动建一个用户,用户名恒为
+ * `service-account-<clientId>` —— 那是 Keycloak 自己的命名,不是我们的约定;它也不出现在
+ * 管理台的 Users 列表、Admin API 的 `GET /users` 里(名册同步的下限保护②为此存在)。
+ *
+ * 它是**真身份**(试跑与 e2e 就用它跑单,铁规矩 6),但**不是人**:
+ * 员工管理那一屏不摆它,试跑台的负责人下拉照旧摆。
+ * 这条判断归后端 —— 界面不该去猜账号名长什么样。
+ */
+export const staffKindSchema = z.enum(['person', 'service']);
+export type StaffKind = z.infer<typeof staffKindSchema>;
+
 export const staffSchema = z.object({
   /** = Keycloak `sub`(手册硬约束 8:业务外键用 sub,不用用户名) */
   id: staffIdSchema,
@@ -35,6 +49,8 @@ export const staffSchema = z.object({
   state: staffStateSchema.default('active'),
   /** realm 角色快照(token 签发时;噪声角色已滤) */
   roles: z.array(z.string()).default([]),
+  /** 人 / 服务账号 —— 由账号名判(见 `staffKindSchema`),不落库 */
+  kind: staffKindSchema.default('person'),
 });
 export type Staff = z.infer<typeof staffSchema>;
 

stable.sh

@@ -0,0 +1,366 @@
+#!/bin/bash
+# 稳定版 —— 把**当前代码**构建成一份快照,在另一组端口上常驻,给外部访问。
+# 与 ./start.sh 起的开发服务(:8787 / :5173,tsup --watch + vite HMR)互不相干:
+# 开发那边改代码、重启、崩掉,这边一个字都不动;要发新版,显式跑一次 update。
+#
+#   ./stable.sh                 起(没有快照就先构建;已在跑的不动)
+#   ./stable.sh update          用当前代码重建快照,然后重启两个 —— 这才是「发一版」
+#   ./stable.sh restart         不重建,只重启
+#   ./stable.sh stop            停掉两个
+#   ./stable.sh status          只看状态,一个进程都不动
+#   ./stable.sh logs [api|web]  看日志(tail -f)
+#   ./stable.sh env-from-dev    把开发服务(:8787)进程里的环境变量抄成 .stable/env
+#
+# 落盘位置(全部 gitignore):
+#   apps/api/.build/stable/   后端快照(tsup 一次性构建,不 watch)—— 必须住在 apps/api 下,
+#                           产物里 `import "hono"` 这类裸名要从 apps/api/node_modules 解析
+#   apps/web/.build/stable/   前端快照(vite build),由 vite preview 托静态 + /api 反代到稳定版后端
+#   .stable/env             环境变量(KEY=VALUE,600 权限)。缺它起不来 —— Keycloak 三样是硬门
+#   .stable/logs/           api.log / web.log / build.log
+#   .stable/RELEASE         这份快照是哪个 commit、什么时候构的
+#
+# .stable/env 长这样(env-from-dev 会自动照开发进程抄一份;要单独一套自己改):
+#   KEYCLOAK_URL=https://…            KEYCLOAK_REALM=corp    KEYCLOAK_CLIENT_ID=task-dispatcher
+#   KEYCLOAK_PROVISIONING_CLIENT_ID=… KEYCLOAK_PROVISIONING_CLIENT_SECRET=…(可选,名册同步)
+#   JCAI_TEST_ACCOUNTS=…              JCAI_SECRET_KEY=…(开发没设的话这里也别设 —— 库里的密文
+#                                      是用哪把钥匙封的就得用哪把开)
+#   DATABASE_URL=…                    (不填 = 与开发共用一个库,见下)
+#   STABLE_API_PORT=8790              STABLE_WEB_PORT=5180
+#   STABLE_ALLOWED_HOSTS=jcai-bpos.akhr-ai.com   经域名/反代访问时要列在这儿(逗号分隔,`*` 全放)——
+#                                      vite preview 有宿主校验,不列会 403「This host is not allowed」
+#
+#   ./stable.sh stop web / restart api  —— 第二个参数可只动一个
+#
+# 关于数据库:默认与开发共用同一个库(两台后端连一个库是本仓库既有的跑法,跨进程租约与
+# LISTEN/NOTIFY 桥都为此做过)。代价要知道:开发那边 `reset-runs` 会把稳定版上外部人跑出来的
+# 任务一起清掉;开发那边跑了新迁移,稳定版的旧代码就在改过的表结构上跑。真要隔离,
+# 在 .stable/env 里把 DATABASE_URL 指到另一个库,并自己跑一遍迁移 + 播种。
+#
+# 沿用 start.sh 踩过的坑:端口属主只认 LISTEN(不然会把浏览器的连接当成占用者);
+# 起完轮询到 /api/health 的 body 里 db:"up" 才算数(它在库挂了时照样返 200)。
+set -u
+cd "$(dirname "$0")" || exit 1
+REPO=$(pwd)
+STABLE="$REPO/.stable"
+ENV_FILE="$STABLE/env"
+LOGDIR="$STABLE/logs"
+API_DIR="$REPO/apps/api"
+WEB_DIR="$REPO/apps/web"
+API_OUT="$API_DIR/.build/stable"
+WEB_OUT="$WEB_DIR/.build/stable"
+DEV_API_PORT=8787
+mkdir -p "$LOGDIR"
+WHAT=${1:-start}
+
+say() { printf '%s\n' "$*"; }
+die() { say "  ✗ $*"; exit 1; }
+
+# ── 环境 ────────────────────────────────────────────────────────────────
+ENV_KEYS='KEYCLOAK_URL KEYCLOAK_REALM KEYCLOAK_CLIENT_ID KEYCLOAK_PROVISIONING_CLIENT_ID KEYCLOAK_PROVISIONING_CLIENT_SECRET JCAI_TEST_ACCOUNTS JCAI_SECRET_KEY JCAI_DEEPSEEK_API_KEY JCAI_LLM_API_KEY JCAI_LLM_BASE_URL DATABASE_URL JCAI_ATTACHMENT_ROOT JCAI_DISPATCH_INTERVAL_MS JCAI_MAIL_POLL_TICK_MS NODE_ENV'
+
+# 端口的真属主 —— 只认 LISTEN
+owner_of() { lsof -ti:"$1" -sTCP:LISTEN 2>/dev/null | head -1; }
+
+env_from_dev() {
+  local pid envs k v n=0
+  pid=$(owner_of "$DEV_API_PORT")
+  [ -n "$pid" ] || die "开发后端(:$DEV_API_PORT)没在跑,抄不到环境 —— 先 ./start.sh api,或照文件头的模版手写 $ENV_FILE"
+  # macOS 的 ps -E 把环境变量追在命令后面,空格分隔;这几个键的值都不含空格
+  envs=$(ps -E -p "$pid" -o command= 2>/dev/null | tr ' ' '\n')
+  [ -n "$envs" ] || die "读不到 pid $pid 的环境(不是同一个用户起的?)"
+  : > "$ENV_FILE"
+  chmod 600 "$ENV_FILE"
+  for k in $ENV_KEYS; do
+    v=$(printf '%s\n' "$envs" | grep -m1 "^$k=" | cut -d= -f2-)
+    if [ -n "$v" ]; then
+      printf '%s=%s\n' "$k" "$v" >> "$ENV_FILE"
+      n=$((n + 1))
+    fi
+  done
+  printf '%s=%s\n%s=%s\n%s=%s\n' STABLE_API_PORT "${STABLE_API_PORT:-8790}" STABLE_WEB_PORT "${STABLE_WEB_PORT:-5180}" \
+    STABLE_ALLOWED_HOSTS "${STABLE_ALLOWED_HOSTS:-}" >> "$ENV_FILE"
+  say "  ✓ 从开发后端(pid $pid)抄了 $n 个变量 → $ENV_FILE(600)"
+  say "    $(cut -d= -f1 "$ENV_FILE" | tr '\n' ' ')"
+}
+
+load_env() {
+  if [ ! -f "$ENV_FILE" ]; then
+    say "  $ENV_FILE 还没有,先照开发后端抄一份:"
+    env_from_dev
+  fi
+  set -a
+  # shellcheck disable=SC1090
+  . "$ENV_FILE"
+  set +a
+  API_PORT=${STABLE_API_PORT:-8790}
+  WEB_PORT=${STABLE_WEB_PORT:-5180}
+  for k in KEYCLOAK_URL KEYCLOAK_REALM KEYCLOAK_CLIENT_ID; do
+    eval "v=\${$k:-}"
+    # shellcheck disable=SC2154
+    [ -n "$v" ] || die "$ENV_FILE 里缺 $k —— 统一鉴权中心是唯一的登录途径,缺了后端拒绝启动(ADR-012)"
+  done
+}
+
+# ── 构建快照 ────────────────────────────────────────────────────────────
+build() {
+  local sha dirty at
+  say '构建快照:'
+  say "  api → apps/api/.build/stable …"
+  # --out-dir 盖过 tsup.config 的 outDir;config 里的 clean:true 清的就是这个目录,碰不到开发的 dist/
+  if ! (cd "$API_DIR" && pnpm exec tsup --out-dir .build/stable) > "$LOGDIR/build.log" 2>&1; then
+    tail -20 "$LOGDIR/build.log"
+    die 'api 构建失败(全文 .stable/logs/build.log)'
+  fi
+  [ -f "$API_OUT/main.js" ] || die "构建说成功,可 $API_OUT/main.js 不在"
+  say "  web → apps/web/.build/stable …"
+  if ! (cd "$WEB_DIR" && pnpm exec vite build --outDir .build/stable --emptyOutDir) >> "$LOGDIR/build.log" 2>&1; then
+    tail -20 "$LOGDIR/build.log"
+    die 'web 构建失败(全文 .stable/logs/build.log)'
+  fi
+  [ -f "$WEB_OUT/index.html" ] || die "构建说成功,可 $WEB_OUT/index.html 不在"
+  sha=$(git rev-parse --short HEAD 2>/dev/null || echo unknown)
+  dirty=$([ -n "$(git status --porcelain 2>/dev/null)" ] && echo '+未提交改动' || echo '')
+  at=$(date '+%Y-%m-%d %H:%M:%S')
+  printf 'commit=%s%s\nbuilt_at=%s\n' "$sha" "$dirty" "$at" > "$STABLE/RELEASE"
+  say "  ✓ 快照:$sha$dirty · $at"
+}
+
+have_snapshot() { [ -f "$API_OUT/main.js" ] && [ -f "$WEB_OUT/index.html" ]; }
+
+# ── 起停 ────────────────────────────────────────────────────────────────
+# 直接 exec node,进程链上不留 pnpm/bash:pid 文件里记的就是真正听端口的那个进程
+start_api() {
+  if [ -n "$(owner_of "$API_PORT")" ]; then
+    say "  api :$API_PORT 已在跑,不动它"
+    return 0
+  fi
+  # cwd 必须是 apps/api:附件根目录默认 cwd/.data/attachments,与开发服务同一处 ——
+  # 共用一个库时,库里存的 file:// 指针两边都得指得到
+  ( cd "$API_DIR" && PORT="$API_PORT" exec nohup node .build/stable/main.js < /dev/null >> "$LOGDIR/api.log" 2>&1 ) &
+  echo $! > "$STABLE/api.pid"
+  disown 2>/dev/null
+  say "  api :$API_PORT 启动中… (pid $(cat "$STABLE/api.pid"),日志 .stable/logs/api.log)"
+}
+
+start_web() {
+  if [ -n "$(owner_of "$WEB_PORT")" ]; then
+    say "  web :$WEB_PORT 已在跑,不动它"
+    return 0
+  fi
+  # vite preview:托 .build/stable 的静态文件,/api 反代沿用 vite.config 的 server.proxy(preview 默认继承),
+  # 目标由 API_PROXY_TARGET 指到稳定版后端;--host 绑全部网卡,外部才连得进来
+  ( cd "$WEB_DIR" && API_PROXY_TARGET="http://127.0.0.1:$API_PORT" PREVIEW_ALLOWED_HOSTS="${STABLE_ALLOWED_HOSTS:-}" \
+      exec nohup node node_modules/vite/bin/vite.js preview \
+      --outDir .build/stable --host --port "$WEB_PORT" --strictPort < /dev/null >> "$LOGDIR/web.log" 2>&1 ) &
+  echo $! > "$STABLE/web.pid"
+  disown 2>/dev/null
+  say "  web :$WEB_PORT 启动中… (pid $(cat "$STABLE/web.pid"),日志 .stable/logs/web.log)"
+}
+
+# 只杀「确实是我们起的那个」:pid 文件里的 pid 还活着且命令里带 .build/stable,或端口属主命令里带 .build/stable
+# (dist-stable 是 08-26 之前的旧落点,留着认一阵子,免得换目录那一刻停不掉老进程)
+is_ours() { ps -o command= -p "$1" 2>/dev/null | grep -qE '\.build/stable|dist-stable'; }
+
+stop_one() {
+  local label=$1 port=$2 pidfile=$3 pid owner i
+  pid=$(cat "$pidfile" 2>/dev/null || true)
+  owner=$(owner_of "$port")
+  if [ -z "$owner" ] && { [ -z "$pid" ] || ! kill -0 "$pid" 2>/dev/null; }; then
+    say "  $label 本来就没在跑"
+    rm -f "$pidfile"
+    return 0
+  fi
+  # pid 文件里的与端口属主多半是同一个进程,别对它说两遍话
+  [ "$owner" = "$pid" ] && owner=''
+  for i in $pid $owner; do
+    if is_ours "$i"; then
+      kill "$i" 2>/dev/null
+    elif [ -n "$(ps -o command= -p "$i" 2>/dev/null)" ]; then
+      say "  ! :$port 的属主 pid $i 不是稳定版的进程,不动它:$(ps -o command= -p "$i" | cut -c1-80)"
+    fi
+  done
+  for i in 1 2 3 4 5 6 7 8; do
+    [ -z "$(owner_of "$port")" ] && { say "  $label 已停"; rm -f "$pidfile"; return 0; }
+    sleep 1
+  done
+  owner=$(owner_of "$port")
+  if is_ours "$owner"; then
+    kill -9 "$owner" 2>/dev/null
+    sleep 1
+    [ -z "$(owner_of "$port")" ] && { say "  $label 已停(-9)"; rm -f "$pidfile"; return 0; }
+  fi
+  say "  ! $label :$port 还被占着 —— 手工看看 lsof -i:$port"
+  return 1
+}
+
+# ── 核实 ────────────────────────────────────────────────────────────────
+http_code() { curl -s -o /dev/null -m 3 -w '%{http_code}' "$1" 2>/dev/null; }
+
+# /api/health 在库挂了时照样返 200,得看 body 里的 db
+wait_api() {
+  local i body
+  for i in $(seq 1 45); do
+    body=$(curl -s -m 3 "http://127.0.0.1:$API_PORT/api/health" 2>/dev/null)
+    case "$body" in
+      *'"db":"up"'*) say "  ✓ api 就绪 (${i}s) $body"; return 0 ;;
+      *'"db":"down"'*) say "  ✗ api 起来了但连不上库:$body"; return 1 ;;
+    esac
+    # 进程已经死了就别等满 45 秒
+    if [ -f "$STABLE/api.pid" ] && ! kill -0 "$(cat "$STABLE/api.pid")" 2>/dev/null; then
+      say '  ✗ api 进程已退出 —— 日志末尾:'
+      tail -5 "$LOGDIR/api.log" | sed 's/^/      /'
+      return 1
+    fi
+    sleep 1
+  done
+  say '  ✗ api 45 秒没有应答 —— 看 .stable/logs/api.log'
+  return 1
+}
+
+wait_web() {
+  local i code
+  for i in $(seq 1 30); do
+    code=$(http_code "http://127.0.0.1:$WEB_PORT/")
+    [ "$code" = '200' ] && { say "  ✓ web 就绪 (${i}s)"; return 0; }
+    if [ -f "$STABLE/web.pid" ] && ! kill -0 "$(cat "$STABLE/web.pid")" 2>/dev/null; then
+      say '  ✗ web 进程已退出 —— 日志末尾:'
+      tail -5 "$LOGDIR/web.log" | sed 's/^/      /'
+      return 1
+    fi
+    sleep 1
+  done
+  say '  ✗ web 30 秒没有应答 —— 看 .stable/logs/web.log'
+  return 1
+}
+
+verify() {
+  local rc=0 proxy spa
+  wait_api || rc=1
+  wait_web || rc=1
+  proxy=$(http_code "http://127.0.0.1:$WEB_PORT/api/health")
+  [ "$proxy" = '200' ] && say '  ✓ 反代 /api → 200' || { say "  ✗ 反代 /api → ${proxy:-连不上}"; rc=1; }
+  # 三个台面是同一个 SPA,刷新 /design /ops 要吐 index.html
+  spa=$(http_code "http://127.0.0.1:$WEB_PORT/design")
+  [ "$spa" = '200' ] && say '  ✓ SPA 回退 /design → 200' || { say "  ✗ SPA 回退 /design → ${spa:-连不上}"; rc=1; }
+  return $rc
+}
+
+lan_ip() { ipconfig getifaddr en0 2>/dev/null || ipconfig getifaddr en1 2>/dev/null || true; }
+
+# 登录能不能跳回来,Keycloak 那一侧说了算:web-portal 客户端没登记这个来源的 redirect URI,
+# 页面开得了、点「前往统一登录」就吃一句 Invalid parameter: redirect_uri。
+# 服务起好了不等于能用 —— 这里替人先问一次 Keycloak(只看它对 redirect_uri 的裁决,不登录)。
+WEB_CLIENT_ID=$(grep -m1 '^VITE_KEYCLOAK_CLIENT_ID=' "$WEB_DIR/.env.production" 2>/dev/null | cut -d= -f2-)
+kc_redirect_ok() {
+  local origin=$1 enc body
+  enc=$(printf '%s/' "$origin" | sed 's,/,%2F,g; s,:,%3A,g')
+  body=$(curl -s -m 10 "$KEYCLOAK_URL/realms/$KEYCLOAK_REALM/protocol/openid-connect/auth?client_id=${WEB_CLIENT_ID:-web-portal}&response_type=code&scope=openid&redirect_uri=$enc&code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM&code_challenge_method=S256" 2>/dev/null)
+  case "$body" in
+    '') return 2 ;;                                   # Keycloak 连不上,说不出
+    *'Invalid parameter: redirect_uri'*) return 1 ;;  # 明确拒了
+    *) return 0 ;;
+  esac
+}
+
+# 列进 STABLE_ALLOWED_HOSTS 的域名,外部多半是 https 进来的,一并问 Keycloak(通配与整子域问不了,跳过)
+allowed_origins() {
+  local h
+  for h in $(printf '%s' "${STABLE_ALLOWED_HOSTS:-}" | tr ',' ' '); do
+    case "$h" in '*' | .*) ;; *) printf 'https://%s\n' "$h" ;; esac
+  done
+}
+
+report_kc() {
+  local origin
+  set -- "$@" $(allowed_origins)
+  for origin in "$@"; do
+    kc_redirect_ok "$origin"
+    case $? in
+      0) say "  ✓ Keycloak 接受 $origin 的 redirect_uri" ;;
+      1) say "  ✗ Keycloak 拒绝 $origin 的 redirect_uri —— 去 realm $KEYCLOAK_REALM 的客户端 ${WEB_CLIENT_ID:-web-portal} 把 $origin/* 加进 Valid redirect URIs 与 Web origins,不然这个入口登不进" ;;
+      *) say "  ? Keycloak($KEYCLOAK_URL)没应答,登录能不能跳回来说不准" ;;
+    esac
+  done
+}
+
+finish() {
+  local ip
+  say ''
+  if [ "$1" = '0' ]; then
+    ip=$(lan_ip)
+    say "  稳定版都好了 → http://localhost:$WEB_PORT/"
+    [ -n "$ip" ] && say "  局域网          → http://$ip:$WEB_PORT/"
+    report_kc "http://localhost:$WEB_PORT" ${ip:+"http://$ip:$WEB_PORT"}
+  else
+    say '  有起不来的,日志在 .stable/logs/'
+  fi
+}
+
+status() {
+  local ip
+  say '稳定版状态:'
+  [ -f "$STABLE/RELEASE" ] && sed 's/^/  快照   /' "$STABLE/RELEASE" || say '  快照   (还没构建过)'
+  say "  api    :$API_PORT   $(http_code "http://127.0.0.1:$API_PORT/api/health")  $(curl -s -m 3 "http://127.0.0.1:$API_PORT/api/health" 2>/dev/null)  pid $(owner_of "$API_PORT")"
+  say "  web    :$WEB_PORT   $(http_code "http://127.0.0.1:$WEB_PORT/")  pid $(owner_of "$WEB_PORT")"
+  say "  反代   /api    $(http_code "http://127.0.0.1:$WEB_PORT/api/health")"
+  ip=$(lan_ip)
+  [ -n "$ip" ] && say "  入口   http://localhost:$WEB_PORT/  ·  http://$ip:$WEB_PORT/"
+  report_kc "http://localhost:$WEB_PORT" ${ip:+"http://$ip:$WEB_PORT"}
+}
+
+# ── 分派 ────────────────────────────────────────────────────────────────
+case "$WHAT" in
+  env-from-dev)
+    env_from_dev
+    exit 0
+    ;;
+  logs)
+    exec tail -n 50 -f "$LOGDIR/${2:-api}.log"
+    ;;
+  status)
+    load_env
+    status
+    exit 0
+    ;;
+  stop)
+    load_env
+    say '停止稳定版:'
+    [ "${2:-}" != 'web' ] && stop_one api "$API_PORT" "$STABLE/api.pid"
+    [ "${2:-}" != 'api' ] && stop_one web "$WEB_PORT" "$STABLE/web.pid"
+    exit 0
+    ;;
+  start)
+    load_env
+    have_snapshot || build
+    say "起稳定版(api :$API_PORT · web :$WEB_PORT):"
+    start_api
+    start_web
+    ;;
+  update)
+    load_env
+    build
+    say '重启稳定版:'
+    stop_one api "$API_PORT" "$STABLE/api.pid"
+    stop_one web "$WEB_PORT" "$STABLE/web.pid"
+    start_api
+    start_web
+    ;;
+  restart)
+    load_env
+    have_snapshot || die '还没有快照,先 ./stable.sh update'
+    say "重启稳定版${2:+($2)}:"
+    [ "${2:-}" != 'web' ] && stop_one api "$API_PORT" "$STABLE/api.pid"
+    [ "${2:-}" != 'api' ] && stop_one web "$WEB_PORT" "$STABLE/web.pid"
+    start_api
+    start_web
+    ;;
+  *)
+    say "不认识的参数:$WHAT(可用:start / update / restart / stop / status / logs [api|web] / env-from-dev)"
+    exit 2
+    ;;
+esac
+
+RC=0
+verify || RC=1
+finish $RC
+exit $RC