契约:三个端与路由归属(access 必填)、Principal / 角色→端 / 名册同步 schema、退役路由标 @deprecated(ADR-012)

- packages/contracts/src/api/http.ts:新增 SURFACES / surfaceSchema / Surface / SURFACE_LABEL /
  RouteAccess;RouteContract.access 必填;API_ERROR_CODES 增 'gone'。
- packages/contracts/src/org.ts:staffSchema 补 email? / roles(realm 角色快照);新增
  principalSchema/Principal、roleAccessSchema/RoleAccess、rosterSyncOutcomeSchema/RosterSyncOutcome、
  inFlightWorkSchema/InFlightWork;旧岗位授权(grant* / governanceFunction*)与 sessionSchema/Session
  全部标 @deprecated 留一轮(web 编译不受影响,下个迭代删)。
- workbench.ts / governance.ts / ingest.ts:每条既有路由补 access(按所属端/两端共用/退役 public);
  新增 meRoute、authTicketRoute(access:'any')与 syncStaffRoute、setStaffPositionRoute、
  staffInFlightRoute、listRoleAccessRoute、setRoleAccessRoute、deleteRoleAccessRoute(access:'ops')。
- apps/api 的 org-service.ts 两处 staff.insert 补 roles: [](staffSchema 新必填字段,该文件下个
  迭代会整份替换,这里只是让本次 typecheck 过)。
- 新增 packages/contracts/src/__tests__/route-access.test.ts:95 条路由的 access 归属断言。

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015kAzS35kMnZNt4YGgJXtfw

packages/contracts/src/api/http.ts

@@ -4,14 +4,35 @@
  * 前端只经 `shared/typed-fetch` + 本目录的路由契约与服务端交互;组件内禁止裸 fetch。
  * **禁止 Hono RPC 客户端** —— 它要求前端 import 后端类型,违反 §5.1。
  */
-import type { z } from 'zod';
+import { z } from 'zod';
 
 export const HTTP_METHODS = ['GET', 'POST', 'PUT', 'PATCH', 'DELETE'] as const;
 export type HttpMethod = (typeof HTTP_METHODS)[number];
 
+/**
+ * 三个端(ADR-012):设计中心 / 运营中心 / 工作台。
+ * 权限只到端 —— 一个角色能进哪几个端由运营中心的「角色 → 端」表定,不写死在代码里。
+ */
+export const SURFACES = ['design', 'ops', 'workbench'] as const;
+export const surfaceSchema = z.enum(SURFACES);
+export type Surface = z.infer<typeof surfaceSchema>;
+
+export const SURFACE_LABEL: Readonly<Record<Surface, string>> = {
+  design: '设计中心',
+  ops: '运营中心',
+  workbench: '工作台',
+};
+
+/**
+ * 一条路由归哪个端(ADR-012):
+ *   `public` 不需要凭据;`any` 登录即可、不看端;端名 / 端名数组 —— 能进其中任一端即可。
+ * 鉴权中间件按它统一判,路由里不再各写守卫;漏写编译不过(`satisfies RouteContract`)。
+ */
+export type RouteAccess = 'public' | 'any' | Surface | readonly Surface[];
+
 /**
  * 一条路由契约。`path` 用 `:name` 表示路径参数,与 `params` 的键一一对应。
- * body 只在 POST/PATCH 上有意义;GET 用 query。
+ * body 只在 POST/PUT/PATCH 上有意义;GET 用 query。
  */
 export type RouteContract<
   TParams extends z.ZodTypeAny = z.ZodTypeAny,
@@ -21,6 +42,7 @@ export type RouteContract<
 > = {
   readonly method: HttpMethod;
   readonly path: string;
+  readonly access: RouteAccess;
   readonly params?: TParams;
   readonly query?: TQuery;
   readonly body?: TBody;
@@ -32,7 +54,7 @@ export type RouteBody<R extends RouteContract> = R['body'] extends z.ZodTypeAny
   ? z.infer<R['body']>
   : never;
 
-/** 结构化错误:前端按 code 分辨,不解析文案 */
+/** 结构化错误:前端按 code 分辨,不解析文案。`gone` = 410,路由已随统一鉴权中心退役 */
 export const API_ERROR_CODES = [
   'unauthenticated',
   'forbidden',
@@ -41,6 +63,7 @@ export const API_ERROR_CODES = [
   'conflict',
   'precondition-failed',
   'internal',
+  'gone',
 ] as const;
 export type ApiErrorCode = (typeof API_ERROR_CODES)[number];