$page) { if (!is_string($pageKey) || preg_match(self::PAGE_PATTERN, $pageKey) !== 1) { throw new InvalidArgumentException( '文案页面键格式无效:' . (string) $pageKey ); } if (!is_array($page)) { throw new InvalidArgumentException( '文案页面定义必须是数组:' . $pageKey ); } self::assertExactFields($page, ['label', 'scopes'], '页面 ' . $pageKey); $label = self::requiredText($page['label'] ?? null, '页面标签 ' . $pageKey, 128); if (!is_array($page['scopes']) || $page['scopes'] === []) { throw new InvalidArgumentException( '页面必须声明至少一个 scope:' . $pageKey ); } $scopes = []; foreach ($page['scopes'] as $scope) { if (!is_string($scope) || preg_match(self::NAME_PATTERN, $scope) !== 1) { throw new InvalidArgumentException( '页面 scope 格式无效:' . $pageKey ); } $scopes[$scope] = true; } $pages[$pageKey] = [ 'label' => $label, 'scopes' => array_keys($scopes), ]; } $entries = []; foreach ($manifest['entries'] as $position => $entry) { if (!is_array($entry)) { throw new InvalidArgumentException( '文案词条定义必须是数组:#' . $position ); } self::assertExactFields($entry, self::ENTRY_FIELDS, '词条 #' . $position); $copyKey = $entry['key'] ?? null; if (!is_string($copyKey) || preg_match(self::KEY_PATTERN, $copyKey) !== 1 || preg_match(self::GENERATED_KEY_PATTERN, $copyKey) === 1) { throw new InvalidArgumentException( '文案词条键必须是静态语义键:' . (string) $copyKey ); } if (array_key_exists($copyKey, $entries)) { throw new InvalidArgumentException( '文案词条键重复:' . $copyKey ); } $scope = self::name($entry['scope'] ?? null, '词条 scope ' . $copyKey); $page = (string) ($entry['page'] ?? ''); if (!isset($pages[$page])) { throw new InvalidArgumentException( '词条引用了未声明页面:' . $copyKey ); } if (!in_array($scope, $pages[$page]['scopes'], true)) { throw new InvalidArgumentException( '词条 scope 不属于声明页面:' . $copyKey ); } $kind = (string) ($entry['kind'] ?? ''); if (!in_array($kind, self::KINDS, true)) { throw new InvalidArgumentException( '词条类型无效:' . $copyKey ); } $source = self::requiredText($entry['source'] ?? null, '词条中文基线 ' . $copyKey, 4000); $format = (string) ($entry['format'] ?? 'plain_text'); if (!in_array($format, self::FORMATS, true)) { throw new InvalidArgumentException( '词条格式无效:' . $copyKey ); } $parameters = self::parameters( $entry['parameters'] ?? [], $copyKey ); self::assertSourceParameters($source, $parameters, $copyKey); if ($parameters !== [] && $format !== 'icu') { throw new InvalidArgumentException( '带参数词条必须使用 ICU 格式:' . $copyKey ); } $criticality = (string) ($entry['criticality'] ?? 'normal'); if (!in_array($criticality, self::CRITICALITIES, true)) { throw new InvalidArgumentException( '词条安全等级无效:' . $copyKey ); } if (!is_bool($entry['allow_hide'] ?? null)) { throw new InvalidArgumentException( '词条 allow_hide 必须是布尔值:' . $copyKey ); } $allowHide = $entry['allow_hide']; if ($allowHide && $criticality !== 'normal') { throw new InvalidArgumentException( '必需或高风险词条不能隐藏:' . $copyKey ); } $toastTone = $entry['toast_tone'] ?? null; $isToast = str_starts_with($kind, 'toast_'); if ($isToast) { if (!is_string($toastTone) || !in_array($toastTone, self::TOAST_TONES, true)) { throw new InvalidArgumentException( 'Toast 词条必须声明有效 tone:' . $copyKey ); } } elseif ($toastTone !== null) { throw new InvalidArgumentException( '非 Toast 词条不能声明 tone:' . $copyKey ); } $editorSurface = (string) ($entry['editor_surface'] ?? ''); if (!in_array($editorSurface, self::EDITOR_SURFACES, true)) { throw new InvalidArgumentException( '词条编辑表面无效:' . $copyKey ); } $editorGroup = (string) ($entry['editor_group'] ?? ''); if (preg_match(self::PAGE_PATTERN, $editorGroup) !== 1) { throw new InvalidArgumentException( '词条编辑分组无效:' . $copyKey ); } $entries[$copyKey] = [ 'key' => $copyKey, 'scope' => $scope, 'page' => $page, 'kind' => $kind, 'source' => $source, 'format' => $format, 'parameters' => $parameters, 'criticality' => $criticality, 'allow_hide' => $allowHide, 'toast_tone' => $toastTone, 'editor_surface' => $editorSurface, 'editor_group' => $editorGroup, ]; } ksort($pages, SORT_STRING); ksort($entries, SORT_STRING); return [ 'version' => 1, 'pages' => $pages, 'entries' => array_values($entries), ]; } public static function digest(array $manifest): string { $validated = self::validate($manifest); $json = json_encode($validated, JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE); if (!is_string($json)) { throw new InvalidArgumentException('无法编码文案 Manifest。'); } return hash('sha256', $json); } private static function parameters($value, string $copyKey): array { if (!is_array($value)) { throw new InvalidArgumentException( '词条参数合同必须是数组:' . $copyKey ); } $parameters = []; foreach ($value as $name => $type) { if (!is_string($name) || preg_match(self::NAME_PATTERN, $name) !== 1 || !is_string($type) || !in_array($type, self::PARAMETER_TYPES, true)) { throw new InvalidArgumentException( '词条参数合同无效:' . $copyKey ); } if (isset($parameters[$name])) { throw new InvalidArgumentException( '词条参数重复:' . $copyKey . ':' . $name ); } $parameters[$name] = $type; } ksort($parameters, SORT_STRING); return $parameters; } private static function assertSourceParameters( string $source, array $parameters, string $copyKey ): void { preg_match_all('/\{([a-z][a-z0-9_]*)\s*(?:[,}])/D', $source, $matches); $used = array_values(array_unique($matches[1] ?? [])); sort($used, SORT_STRING); $declared = array_keys($parameters); sort($declared, SORT_STRING); if ($used !== $declared) { throw new InvalidArgumentException( '词条参数与中文基线不一致:' . $copyKey ); } } private static function requiredText( $value, string $label, int $maximumLength ): string { if (!is_string($value) || trim($value) === '') { throw new InvalidArgumentException($label . '不能为空。'); } if (mb_strlen($value) > $maximumLength || preg_match( '/[\x00-\x08\x0B\x0C\x0E-\x1F\x7F\x{202A}-\x{202E}\x{2066}-\x{2069}]/u', $value )) { throw new InvalidArgumentException($label . '包含非法内容。'); } return $value; } private static function name($value, string $label): string { if (!is_string($value) || preg_match(self::NAME_PATTERN, $value) !== 1) { throw new InvalidArgumentException($label . '格式无效。'); } return $value; } private static function assertExactFields( array $value, array $allowed, string $label ): void { $unknown = array_values(array_diff(array_keys($value), $allowed)); $missing = array_values(array_diff($allowed, array_keys($value))); if ($unknown !== []) { throw new InvalidArgumentException( $label . ' 包含未声明字段:' . implode(', ', $unknown) ); } if ($missing !== []) { throw new InvalidArgumentException( $label . ' 缺少字段:' . implode(', ', $missing) ); } } }