pomaster 0.3.0 → 0.5.0

package/seeds/specs/hard/themes/integration-and-async-runtime.md

@@ -0,0 +1,331 @@
+---
+seed_source: packages/cli/seeds/aggregation-manifest.json
+seed_source_sha256: 039b637ccffacdfe3ce30d85e193f4b38928fcdfb16efdc4eb255e35e05af91f
+seed_version: B7-THEME
+lane: [backend]
+status: CURRENT
+authority_scope: mixed_required_and_advisory
+applies_to: [backend]
+related_evidence_specs: []
+related_tools: []
+legacy_id: theme:integration-and-async-runtime
+criticality: critical # 聚合注记：取源最高；info 性注记非执行语义
+injection_mode: triggered # 聚合注记：来源同值；info 性注记非执行语义
+stages: [prepare, implement, check, release] # 聚合注记：来源 stages 并集；info 性注记非执行语义
+triggers: [external-integration, resilience, async-job, scheduler, import-export, runtime, deployment, configuration] # 聚合注记：来源 triggers 并集；info 性注记非执行语义
+requires: [] # 聚合注记：来源 requires 并集（全空）
+x-aggregation: # 聚合来源（D6）：逐源 vendor pin（sha256 与卡 vendor_pin 同值）
+  - seed_source: pomaster/components/backend-hard-spec/assets/universal/24-external-integration-resilience-protocol.md
+    sha256: e6b0626c9169e9126319bd08ee5d5bdbe38421cfa175509524145aee30ff539a
+    seed_version: B6C
+  - seed_source: pomaster/components/backend-hard-spec/assets/universal/25-async-job-scheduler-protocol.md
+    sha256: 36af3b4466b4e617a9c552a404d98ab74604752b7410e15756d7f132394fb980
+    seed_version: B6C
+  - seed_source: pomaster/components/backend-hard-spec/assets/universal/31-runtime-deployment-protocol.md
+    sha256: c791451de0be3aa0629fd562e2b43cc54066e4b10d786264fa7a333c561ef23a
+    seed_version: B6C
+x-language-sections: # 语言节同步源（R-J 资产层唯一权威；注入面为同步副本）
+  - overlay: pomaster/components/backend-hard-spec/assets/stacks/spring-webflux/spring-webflux-reactive-overlay.md
+    sha256: 4d2045c5bfa66004516dffa55e965e90958270adba9599f116990ac27cc489f8
+    attach: primary
+  - overlay: pomaster/components/backend-hard-spec/assets/stacks/spring-batch/spring-batch-job-overlay.md
+    sha256: 58f710fcfeeaeafcaa19fd4ef27bce22c3c34d8d1ef7992f95f65a3e1bd9cd78
+    attach: primary
+  - overlay: pomaster/components/backend-hard-spec/assets/stacks/tomcat/tomcat-runtime-overlay.md
+    sha256: 133f15dbb7866e9e06cecf4e2cfcc2b2f14eeb06d9ea3d29be68c9e11cdd1e11
+    attach: primary
+  - overlay: pomaster/components/backend-hard-spec/assets/stacks/nginx/nginx-proxy-overlay.md
+    sha256: 442da24b2bb5274003978636cf793bae02b25f24aa080fcc926c5347da39ce19
+    attach: primary
+  - overlay: pomaster/components/backend-hard-spec/assets/stacks/kubernetes-ingress/kubernetes-ingress-overlay.md
+    sha256: 4369b51a677453c24b5ec4d4b97001c91932918fc779c55562012ebc6b312bf5
+    attach: primary
+  - overlay: pomaster/components/backend-hard-spec/assets/stacks/messaging/messaging-reliability-overlay.md
+    sha256: ed7f82208521675510ab4a42b229f9be269a52514cf5188c9bf83323d7590572
+    attach: primary
+---
+
+# 集成与异步运行时
+
+> **聚合纪律**：本文档 12 节正文规则行逐字取自 frontmatter x-aggregation 所列来源协议（节内按「端 → 源编号升序」以加粗来源行分块，源内标题与层级原样保留），零新增、零改写、零删除；新增文本仅限文档标题、本注记与逐节来源行。
+文末「语言与栈节」为 stacks overlay 资产 Scope/Rules/Checklist 的逐字节同步副本（标题降 2 级，正文零改动）——资产层为唯一权威，改规则只改 overlay、本区随同步。
+
+## Scope
+
+**源：BE 24 外部集成与韧性协议（pomaster/components/backend-hard-spec/assets/universal/24-external-integration-resilience-protocol.md）**
+
+规范外部契约、超时、重试、熔断、补偿、对账和供应方故障。
+
+**源：BE 25 异步任务与调度协议（pomaster/components/backend-hard-spec/assets/universal/25-async-job-scheduler-protocol.md）**
+
+规范 Job 生命周期、进度、取消、重试、调度锁、结果与保留。
+
+**源：BE 31 运行时与部署协议（pomaster/components/backend-hard-spec/assets/universal/31-runtime-deployment-protocol.md）**
+
+规范部署单元、实例、网络、TLS、代理头、健康检查、容器与运行时加固。
+
+## Non-Scope
+
+**源：BE 24 外部集成与韧性协议**
+
+不发明供应方 SLA、字段或错误语义。
+
+**源：BE 25 异步任务与调度协议**
+
+不绑定具体调度器、队列或批处理框架。
+
+**源：BE 31 运行时与部署协议**
+
+不默认选择 Nginx、Ingress、Tomcat、容器平台或具体 JVM 参数。
+
+## Terms
+
+**源：BE 24 外部集成与韧性协议**
+
+补偿用于处理无法由单一原子事务覆盖的已发生副作用。
+
+**源：BE 25 异步任务与调度协议**
+
+Job instance 是由稳定业务参数标识的一次可追踪执行意图。
+
+**源：BE 31 运行时与部署协议**
+
+部署拓扑描述入口链路、信任边界、运行单元、状态依赖与观测链路。
+
+## MUST
+
+**源：BE 24 外部集成与韧性协议 · §MUST**
+
+- 每个外部调用必须定义超时、重试条件、幂等、失败映射和恢复路径。
+
+**源：BE 25 异步任务与调度协议 · §MUST**
+
+- 任务必须定义身份、状态、幂等、重试、取消、超时和结果访问。
+
+**源：BE 31 运行时与部署协议 · §MUST**
+
+- 必须记录真实打包、启动、端口、协议、实例、状态依赖和配置来源。
+
+## MUST NOT
+
+**源：BE 24 外部集成与韧性协议 · §MUST NOT**
+
+- 不得无限重试、重试非幂等操作或在事务内执行无界调用。
+
+**源：BE 25 异步任务与调度协议 · §MUST NOT**
+
+- 不得用固定 sleep、无主线程或无状态记录的后台执行承载关键任务。
+
+**源：BE 31 运行时与部署协议 · §MUST NOT**
+
+- 不得把开发机拓扑、默认端口或未验证容器行为当作生产事实。
+
+## SHOULD
+
+**源：BE 24 外部集成与韧性协议 · §SHOULD**
+
+- 应采用隔离、熔断、限流、降级与对账控制故障扩散。
+
+**源：BE 25 异步任务与调度协议 · §SHOULD**
+
+- 应支持进度、心跳、并发限制、失败恢复和过期清理。
+
+**源：BE 31 运行时与部署协议 · §SHOULD**
+
+- 应支持优雅启动停止、健康检查、滚动发布、最小权限和故障隔离。
+
+## Contract
+
+**源：BE 24 外部集成与韧性协议 · §Contract**
+
+集成契约必须记录版本、认证、请求响应、错误、限额、追踪与所有者。
+
+**源：BE 25 异步任务与调度协议 · §Contract**
+
+任务契约必须包含触发源、参数、状态机、输出、错误、保留和权限。
+
+**源：BE 31 运行时与部署协议 · §Contract**
+
+部署设计必须包含入口、网络、信任、依赖、扩缩容、恢复和证据。
+
+## Checklist
+
+**源：BE 24 外部集成与韧性协议 · §Checklist**
+
+- [ ] 超时、限流、部分失败、重复响应和供应方中断已测试。
+
+**源：BE 25 异步任务与调度协议 · §Checklist**
+
+- [ ] 重复触发、节点崩溃、接管、取消、重跑与过期已测试。
+
+**源：BE 31 运行时与部署协议 · §Checklist**
+
+- [ ] 多实例、代理链、TLS、健康、配置、日志与回滚已演练。
+
+## Examples
+
+**源：BE 24 外部集成与韧性协议 · §Examples**
+
+- 写入本地意图后异步调用供应方，并通过状态机与对账收敛。
+
+**源：BE 25 异步任务与调度协议 · §Examples**
+
+- 导出任务返回 job ID，调用方查询状态并从受权地址下载结果。
+
+**源：BE 31 运行时与部署协议 · §Examples**
+
+- 明确 Ingress 到 Service 再到应用的代理头与健康检查责任。
+
+## Anti-patterns
+
+**源：BE 24 外部集成与韧性协议 · §Anti-patterns**
+
+- 捕获外部异常后记录日志并返回业务成功。
+
+**源：BE 25 异步任务与调度协议 · §Anti-patterns**
+
+- 调度表达式重叠时并发执行同一不可重入任务。
+
+**源：BE 31 运行时与部署协议 · §Anti-patterns**
+
+- 应用无条件信任任意来源的 `X-Forwarded-*`。
+
+## Ownership
+
+**源：BE 24 外部集成与韧性协议 · §Ownership**
+
+集成 Owner 维护供应方契约，业务 Owner 决定降级与补偿语义。
+
+**源：BE 25 异步任务与调度协议 · §Ownership**
+
+任务 Owner 定义生命周期，运行平台提供调度与执行证据。
+
+**源：BE 31 运行时与部署协议 · §Ownership**
+
+Backend 拥有应用运行契约，平台角色拥有受控部署环境。
+
+## Change Policy
+
+**源：BE 24 外部集成与韧性协议 · §Change Policy**
+
+供应方版本或认证变化必须经过兼容窗口和演练。
+
+**源：BE 25 异步任务与调度协议 · §Change Policy**
+
+参数或状态变化必须兼容历史任务和进行中的执行。
+
+**源：BE 31 运行时与部署协议 · §Change Policy**
+
+拓扑或打包变化必须同步技术基线、发布方案与运行验证。
+
+## 语言与栈节（overlay 资产同步区）
+
+> 本区各小节 = stacks/ overlay 资产 Scope/Rules/Checklist 的**逐字节同步副本**（标题降 2 级，正文零改动）。资产层（overlay 文件，catalog 在册、research 锚、bound 语义挂点）为唯一权威；本区为注入面副本，改规则只改 overlay、本区随同步。x-research-anchors 留在 overlay 资产 frontmatter，不复制进本主题文档（防双锚漂移）。
+
+### spring-webflux（源：stacks/spring-webflux/spring-webflux-reactive-overlay.md · B02 主挂点）
+
+#### Scope
+
+本 Overlay 具体化响应式请求链、背压、调度器和非阻塞边界。
+
+#### Rules
+
+- 必须识别并隔离阻塞 I/O，不得在事件循环中执行不可控阻塞操作。
+- 必须验证取消、超时、背压和上下文传播。
+- 与 Spring MVC 并存时必须记录模块、端口或应用边界。
+
+#### Checklist
+
+- [ ] Java 与 Spring Boot 依赖已显式选择。
+- [ ] 阻塞边界与容量证据可复核。
+
+
+### spring-batch（源：stacks/spring-batch/spring-batch-job-overlay.md · B02 主挂点）
+
+#### Scope
+
+本 Overlay 具体化 Job、Step、重启、分片、元数据和批处理事务边界。
+
+#### Rules
+
+- 作业参数、实例身份、重启语义和幂等边界必须稳定。
+- 分片、重试、跳过和失败恢复必须有数据一致性证据。
+- 调度系统与 Spring Batch 的职责必须分开记录。
+
+#### Checklist
+
+- [ ] Java 与 Spring Boot 依赖已显式选择。
+- [ ] 重跑、取消、并发和结果保留策略已验证。
+
+
+### tomcat（源：stacks/tomcat/tomcat-runtime-overlay.md · B02 主挂点）
+
+#### Scope
+
+本 Overlay 具体化 embedded 与 external Tomcat 的连接器、线程、部署和加固边界。
+
+#### Rules
+
+- 必须在技术基线中明确 embedded 或 external，以及 JAR 或 WAR。
+- 连接器、代理头、线程和请求限制必须与入口及容量方案一致。
+- 不得把本地启动形态当作生产运行事实。
+
+#### Checklist
+
+- [ ] Java 依赖已显式选择。
+- [ ] 容器版本、打包、配置来源和运行证据一致。
+
+
+### nginx（源：stacks/nginx/nginx-proxy-overlay.md · B02 主挂点）
+
+#### Scope
+
+本 Overlay 具体化 TLS 终止、代理头、超时、上传限制和入口路由边界。
+
+#### Rules
+
+- 必须声明可信代理链、原始客户端地址与协议头的处理方式。
+- 超时、body 限制和缓冲策略必须与应用行为一致。
+- 与 Kubernetes Ingress 并存时必须记录完整入口链路与各自责任。
+
+#### Checklist
+
+- [ ] 配置语法、路由、TLS 与健康检查有可复核证据。
+- [ ] 默认页、管理面和敏感头未意外暴露。
+
+
+### kubernetes-ingress（源：stacks/kubernetes-ingress/kubernetes-ingress-overlay.md · B02 主挂点）
+
+#### Scope
+
+本 Overlay 具体化集群入口、Service 路由、TLS、annotation 与健康检查边界。
+
+#### Rules
+
+- 必须记录实际 Ingress Controller、入口类和可信代理链。
+- annotation 与超时不得依赖未审计的集群默认值。
+- 与 Nginx 并存时必须记录完整入口链路与各自责任。
+
+#### Checklist
+
+- [ ] manifest、路由、证书和回滚路径可复核。
+- [ ] 控制器特有行为已在项目技术基线中声明。
+
+
+### messaging（源：stacks/messaging/messaging-reliability-overlay.md · B02 主挂点）
+
+#### Scope
+
+本 Overlay 具体化消息契约、投递、消费、重试、死信与可观测边界。
+
+#### Rules
+
+- topic、事件 schema、版本、顺序和重复投递语义必须明确。
+- 消费者必须按契约处理幂等、毒消息、重试和死信。
+- 不得把 broker 可用性等同于业务处理成功。
+
+#### Checklist
+
+- [ ] 生产、消费、补偿和对账证据可关联。
+- [ ] 敏感数据、保留期和权限符合安全与隐私协议。
+

package/seeds/specs/hard/themes/internationalization-and-copywriting.md

@@ -0,0 +1,350 @@
+---
+seed_source: packages/cli/seeds/aggregation-manifest.json
+seed_source_sha256: 039b637ccffacdfe3ce30d85e193f4b38928fcdfb16efdc4eb255e35e05af91f
+seed_version: B7-THEME
+lane: [frontend]
+status: CURRENT
+authority_scope: mixed_required_and_advisory
+applies_to: [frontend]
+related_evidence_specs: []
+related_tools: []
+legacy_id: theme:internationalization-and-copywriting
+criticality: standard # 聚合注记：来源无 criticality 字段，取中性默认；info 性注记非执行语义
+injection_mode: mixed # 聚合注记：来源无 injection_mode 字段（默认基线 + 任务命中激活模型）；info 性注记非执行语义
+stages: [] # 聚合注记：来源无 stages 字段；info 性注记非执行语义
+triggers: [] # 聚合注记：来源无 triggers 字段；info 性注记非执行语义
+requires: [] # 聚合注记：来源 requires 并集（全空）
+x-aggregation: # 聚合来源（D6）：逐源 vendor pin（sha256 与卡 vendor_pin 同值）
+  - seed_source: pomaster/components/frontend-hard-spec/assets/universal/38-internationalization-protocol.md
+    sha256: 68ed4e126042eee191f071786d58983b3b2df94a826a13b50fc52aaa6536c7fa
+    seed_version: B6B-2
+  - seed_source: pomaster/components/frontend-hard-spec/assets/universal/39-copywriting-protocol.md
+    sha256: 5df3a2ddcd1140b2e62dd80f547cf6c0197c44a91ebbdda02ded44bcaefed351
+    seed_version: B6B-2
+---
+
+# 国际化与文案
+
+> **聚合纪律**：本文档 12 节正文规则行逐字取自 frontmatter x-aggregation 所列来源协议（节内按「端 → 源编号升序」以加粗来源行分块，源内标题与层级原样保留），零新增、零改写、零删除；新增文本仅限文档标题、本注记与逐节来源行。
+
+## Scope
+
+**源：FE 38 国际化协议（pomaster/components/frontend-hard-spec/assets/universal/38-internationalization-protocol.md）**
+
+P2。定义前端多语言机制：locale 标识与切换、文案外置与 key 命名、ICU MessageFormat、日期/时间/时区/相对时间、数字/货币/百分比/单位、列表/排序/搜索、RTL 与双向文本、文本膨胀与排版、图片/图标/颜色文化适配、翻译工作流与字典管理、SSR hydration 一致性、第三方 SDK / 浏览器原生文案 / 后端错误文案的本地化。
+
+**源：FE 39 文案协议（pomaster/components/frontend-hard-spec/assets/universal/39-copywriting-protocol.md）**
+
+P2。定义按钮、确认、成功、错误、空态、删除、导入导出和高风险操作文案。
+
+## Non-Scope
+
+**源：FE 38 国际化协议**
+
+- 不翻译用户数据、不定义业务文案内容质量（语气/术语/voice）—— 见 `39-copywriting-protocol.md`。
+- 不定义金额精度、业务时区、合规区域本身。
+- 不替代 CLDR/Intl API 的实现细节，只规定必须使用的决策、契约和证据。
+
+**源：FE 39 文案协议**
+
+不定义业务规则和错误码，不允许文案隐藏系统行为。
+
+## Terms
+
+**源：FE 38 国际化协议**
+
+- Locale：IETF BCP 47 语言标签（如 `zh-CN`、`en-US`、`ja-JP`、`ar-SA`），决定语言、格式、排序、方向和数字系统。
+- Translation Key：稳定文案标识，不随目标语言变化。
+- Formatter Registry：日期、时间、数字、金额、百分比、币种、单位、枚举和空值显示的唯一策略源。
+- RTL：Right-to-Left 文本方向；LTR：Left-to-Right。
+- ICU MessageFormat：Unicode ICU MessageFormat 2.0，用于复数、select、ordinal、offset 和命名占位符。
+
+**源：FE 39 文案协议**
+
+- Actionable Copy：说明发生什么、影响什么和下一步的文案。
+- Risk Copy：明确不可逆性、对象和后果的文案。
+
+## MUST
+
+**源：FE 38 国际化协议 · §MUST**
+
+- 明确支持 locale 列表、默认 locale 和完整回退链（如 `zh-CN` → `zh` → `en-US`）。
+- 使用 IETF BCP 47 语言标签标识 locale；禁止手写 `zh`、`cn`、`en` 等不精确别名。
+- locale 切换后所有已渲染的格式化值同步刷新，不允许旧 locale 残留。
+- URL 路径或子域携带 locale（如 `/zh-CN/dashboard`），或提供可书签化的 Cookie/LocalStorage 回退并由服务端首屏读取。
+- 切换 locale 时不丢失页面状态（query string、hash、表单草稿）。
+- 禁止在模板/组件/脚本中硬编码任何自然语言文本（用户数据除外）。
+- key 使用稳定标识，禁止用中文/英文文案本身作为 key。
+- key 采用命名空间隔离，如 `module:page.section.element` 或扁平点分 `login.form.submit`。
+- 插值占位符使用命名占位符 `{userName}`；禁止用位置占位符 `{0}`。
+- 占位符内容在运行时做 HTML 转义；如需输出 HTML，必须显式标记并经安全审查（XSS 边界，见 `04-security-protocol.md`）。
+- key 删除/改名必须走废弃别名机制，不能直接删除。
+- 复数、性别、状态选择使用 ICU MessageFormat `plural` / `select` / `selectordinal`；禁止用字符串拼接实现。
+- `plural` / `select` / `selectordinal` 必须包含 `other` 分支。
+- 日期、时间、相对时间通过 Formatter Registry 统一输出；禁止页面本地拼接 `YYYY-MM-DD` 或写死 "2 天前"。
+- 存储时间使用 ISO 8601 / UTC；显示时间按用户 locale + 显式时区转换。
+- 使用 `Intl.DateTimeFormat` 时显式传入 `timeZone`；禁止依赖系统时区。
+- 数字、货币、百分比、单位统一通过 Formatter Registry 输出。
+- 货币代码使用 ISO 4217（`CNY`、`USD`、`EUR`）；禁止用 `$`、`￥` 符号硬编码。
+- 货币格式化显式指定 `currencyDisplay`（`symbol`/`narrowSymbol`/`code`/`name`）。
+- 小数/千分位分隔符由 CLDR 决定；禁止硬编码 `.` 或 `,`。
+- 百分比与原始数值分离存储，排序/计算用原始值。
+- 列表连接使用 `Intl.ListFormat`；禁止用 `, ` 或 `/` 硬编码。
+- locale-aware 排序使用 `Intl.Collator`；禁止用 `Array.prototype.sort()` 默认字节序。
+- 大小写折叠、搜索归一化使用 locale 感知方法；禁止 `toLowerCase()` 处理非英语搜索。
+- 正则表达式考虑 Unicode 属性（`\p{Letter}`）；禁止只用 `[a-zA-Z]`。
+- HTML 根元素 `dir` 与当前 locale 方向一致；RTL locale（ar/he/fa/ur 等）使用 `dir="rtl"`。
+- 使用 CSS logical properties（`margin-inline-start`、`border-inline-end` 等）替代物理方向属性。
+- 镜像布局要素：导航顺序、按钮组、表单标签位置、图标方向（前进/后退、播放/进度条）。
+- 对动态插入的数字/用户生成内容使用 `<bdi>` 或 CSS `unicode-bidi: isolate`。
+- 德语、芬兰语等长文本膨胀系数按 1.3–1.5 预留空间；按钮、表头、标签必须支持换行或截断策略。
+- 所有文案容器定义 `overflow-wrap` / `word-break` 策略；禁止固定宽度导致文字被截断不可读。
+- 图片不得依赖文字传递关键信息；图标必须可本地化或带文本标签。
+- 避免文化敏感符号、颜色、手势、宗教/政治隐喻。
+- 日期/节假日按 locale 显示；禁止硬编码单一文化节日。
+- 度量衡单位按 locale 适配（英里/公里、磅/千克、华氏/摄氏）。
+- 明确 source-of-truth 语言；字典文件版本化并与代码同步发布。
+- 缺失 key 必须回退到 source 语言并标记告警。
+- 翻译平台 API 与 CI 集成；禁止手动复制 JSON 到代码库。
+- 字典文件支持命名空间/代码分割；禁止单个巨型 JSON。
+- SSR 首屏 locale 由服务端根据 URL/Cookie/Header 确定，并在 HTML 中序列化供 hydration。
+- 构建时抽取翻译 key，避免运行时扫描文件系统。
+- hydration 前后 locale 和初始字典一致；禁止服务端用默认 locale、客户端切换导致 mismatch。
+- 后端错误 message 必须映射为前端翻译 key，禁止直接展示后端原始 message。
+- 第三方 SDK/组件的 locale 配置必须显式传入当前 locale，禁止静默使用默认英文。
+- 验证第三方组件的 RTL 支持能力；不支持 RTL 的第三方组件必须评估替代方案或包装隔离。
+
+### 分层责任（按目录层级）
+
+国际化是跨层机制，按目录层级分担责任；层级划分与 `09-module-boundary-protocol` 一致。
+
+- **app 层 — locale 入口与切换**：初始化 i18n Provider、默认 locale、回退链、locale 协商策略、URL/Cookie 持久化。MUST NOT 在应用入口硬编码 locale 或把 `navigator.language` 作为唯一业务来源。
+- **platform 层 — 全局 formatter 与字典**：维护 Formatter Registry、全局字典加载/分割、伪本地化、翻译平台同步。MUST NOT 让各页面自行格式化数据或复制组件实现多语言。
+- **api 层 — 后端契约本地化**：错误码映射为翻译 key、货币/单位/时区字段语义对齐、API 响应不携带未本地化的自然语言。MUST NOT 直接展示后端原始 message。
+- **domain 层 — 领域值本地化策略**：金额精度、单位换算、枚举显示、空值/缺省值显示由 domain 决定策略，由 Formatter Registry 执行显示。MUST NOT 在 domain 逻辑中用翻译文本做业务判断。
+- **feature 层 — 页面级 i18n 契约**：页面声明支持的 locale、RTL 需求、key namespace、第三方 SDK locale 矩阵。MUST NOT 页面本地拼接日期/货币/列表格式。
+- **shared 层 — 组件级 i18n 内置**：公共组件内置文案外置、RTL 兼容、logical properties、图标方向翻转、可本地化空态。MUST NOT 组件内部硬编码自然语言或假设 LTR。
+
+**源：FE 39 文案协议 · §MUST**
+
+- 按钮使用明确动作和对象。
+- 错误说明发生内容、可恢复性和下一步。
+- 空态区分无数据与筛选无结果。
+- 高风险确认明确对象、后果和是否可恢复。
+- 导入导出说明范围、进度、部分成功和结果有效期。
+- 同类操作使用同一名称和语气。
+
+## MUST NOT
+
+**源：FE 38 国际化协议 · §MUST NOT**
+
+- MUST NOT 各页面自行格式化数据。
+- MUST NOT 用中文/英文标题作为程序 key。
+- MUST NOT 复制组件实现多语言。
+- MUST NOT 将格式化字符串用于计算或排序。
+- MUST NOT 用浏览器 `navigator.language` 作为唯一来源决定业务权限、价格或合规区域。
+- MUST NOT 用中文/英文文案本身作为 key。
+- MUST NOT 用位置占位符 `{0}` / `{1}`。
+- MUST NOT 在源码中直接写 locale-specific 复数分支。
+- MUST NOT 用 `Date.prototype.toLocaleString()` 无参调用。
+- MUST NOT 手动拼接币种和单位符号。
+- MUST NOT 硬编码小数点/千分位分隔符。
+- MUST NOT 用字符串拼接实现复数/选择/序数。
+- MUST NOT 用 `Array.prototype.sort()` 默认字节序做业务排序。
+- MUST NOT 用 `toLowerCase()` / `toUpperCase()` 处理非英语搜索。
+- MUST NOT 用物理方向 CSS（`margin-left/right`）替代 logical properties。
+- MUST NOT 硬编码 `dir="ltr"` 包裹整个应用。
+- MUST NOT 假设源语言（中文）紧凑即所有语言都紧凑。
+- MUST NOT 图片包含不可翻译文字作为关键信息。
+- MUST NOT 硬编码单一文化节日、单位换算或数字系统。
+- MUST NOT 把 UI 文案 key 用作业务逻辑判断（如 `if (t('status') === '已启用')`）。
+- MUST NOT 在源码提交后才发现缺失 key。
+- MUST NOT 在服务端 render 中读取 `window.navigator.language`。
+- MUST NOT 将未本地化的第三方错误文案直接呈现给用户。
+
+**源：FE 39 文案协议 · §MUST NOT**
+
+- MUST NOT 直接展示后端原始 message 或技术堆栈。
+- MUST NOT 高风险操作只写“确定吗”。
+- MUST NOT 用颜色或感叹号代替清晰说明。
+- MUST NOT 用模糊“操作”“处理”隐藏动作。
+
+## SHOULD
+
+**源：FE 38 国际化协议 · §SHOULD**
+
+- SHOULD 支持缺失 key 检测和伪本地化。
+- SHOULD 明确存储时区与显示时区。
+- SHOULD 提供 locale 协商：URL > 用户显式选择 > Cookie > `Accept-Language` > 默认。
+- SHOULD 维护 key 命名约定文档 + 禁用词表。
+- SHOULD 提供复数/选择消息的视觉回归测试（阿拉伯语/俄语/波兰语等复杂复数）。
+- SHOULD 在关键业务场景（预约/截止时间）显示时区全名。
+- SHOULD 支持 accounting 格式（负数括号表示）。
+- SHOULD 对关键 UI 文案做 "longest translation" 回归测试。
+- SHOULD 建立可本地化素材清单（illustration/color/icon/photo）。
+- SHOULD 支持 pseudo-localization（伪本地化：lengthening、accents、fake-RTL）做布局回归。
+- SHOULD 在关键错误/空态使用自定义组件替代浏览器原生 `alert()` / `confirm()`。
+- SHOULD 维护第三方 SDK locale/RTL 兼容性矩阵。
+
+**源：FE 39 文案协议 · §SHOULD**
+
+- SHOULD 简洁、专业、可行动。
+- SHOULD 复用文案模板和错误码映射。
+
+## Contract
+
+**源：FE 38 国际化协议 · §Contract**
+
+```text
+Locale, Fallback, KeyNamespace, DateTimePolicy,
+NumberPolicy, CurrencyPolicy, UnitPolicy, EnumPolicy, EmptyPolicy,
+RTLPolicy, PluralPolicy, ListFormatPolicy, CollatorPolicy,
+TranslationWorkflowPolicy, ThirdPartyLocaleMatrix
+```
+
+- `Locale` / `Fallback`：支持的 locale 列表和回退链。
+- `KeyNamespace`：文案 key 的命名空间约定。
+- `DateTimePolicy` / `NumberPolicy` / `CurrencyPolicy` / `UnitPolicy` / `EnumPolicy` / `EmptyPolicy`：Formatter Registry 策略 ID。
+- `RTLPolicy`：RTL locale 列表和布局镜像策略。
+- `PluralPolicy`：ICU MessageFormat 版本和复数分支要求。
+- `ListFormatPolicy` / `CollatorPolicy`：列表连接与排序策略。
+- `TranslationWorkflowPolicy`：source 语言、翻译平台、命名空间拆分、review 策略。
+- `ThirdPartyLocaleMatrix`：第三方 SDK/组件的 locale 与 RTL 兼容性矩阵。
+
+### Formatter Registry
+
+`outputs/frontend/10_planned/formatter-registry.yaml` 记录项目级 formatter 策略：
+
+```text
+Category, PolicyId, DefaultValue, UnknownValue, DeprecatedValue,
+Examples, Owner, Version
+```
+
+- Category 至少覆盖 date、time、datetime、number、money、percent、currency、unit、enum、empty。
+- 每个页面或组件必须通过 registry 中声明的 formatter 输出值，禁止本地拼接格式。
+
+**源：FE 39 文案协议 · §Contract**
+
+```text
+Scenario, Title, Message, PrimaryAction,
+SecondaryAction, Consequence, Recoverability, TraceDisplay
+```
+
+## Checklist
+
+**源：FE 38 国际化协议 · §Checklist**
+
+- [ ] locale 列表、默认 locale、回退链和 locale 协商策略已明确。
+- [ ] 文案外置，无硬编码自然语言；key 使用稳定命名空间标识。
+- [ ] 插值使用命名占位符，HTML 输出经显式标记和安全审查。
+- [ ] ICU MessageFormat 用于复数/性别/状态/序数，且包含 `other` 分支。
+- [ ] 日期/时间/相对时间/数字/货币/百分比/单位通过 Formatter Registry 输出。
+- [ ] 显式时区，不依赖系统时区；UTC 存储，locale 显示。
+- [ ] 列表连接、排序、搜索使用 `Intl.ListFormat` / `Intl.Collator` / locale 感知归一化。
+- [ ] RTL locale 已识别，`dir`、`logical properties`、图标翻转和 `<bdi>` 已处理。
+- [ ] 文本膨胀系数、换行/截断策略、长文案回归已安排。
+- [ ] 图片/图标/颜色/节日/单位/数字系统已做文化适配审查。
+- [ ] source-of-truth 语言、翻译平台、命名空间拆分、review 策略已建立。
+- [ ] SSR 首屏 locale 由服务端确定并序列化；hydration 前后一致。
+- [ ] 后端错误 message 映射为翻译 key；第三方 SDK locale/RTL 矩阵已维护。
+- [ ] 分层国际化责任已按 app/platform/api/domain/feature/shared 分担。
+
+**源：FE 39 文案协议 · §Checklist**
+
+- [ ] 动作和对象明确。
+- [ ] 风险与恢复清晰。
+- [ ] 同类文案一致。
+- [ ] 无原始技术信息。
+
+## Examples
+
+**源：FE 38 国际化协议 · §Examples**
+
+### locale 切换保留 URL state
+
+```text
+切换前: /zh-CN/dashboard?tab=1#section-a
+切换后: /en-US/dashboard?tab=1#section-a
+```
+
+### 命名占位符与 ICU plural
+
+```text
+key: "cart.item_count"
+en-US: "You have {itemCount, number} {itemCount, plural, one {item} other {items}}."
+ar-SA: "لديك {itemCount, number} {itemCount, plural, zero {} one {عنصر} two {عنصرين} few {عناصر} many {عنصرًا} other {عنصر}}."
+```
+
+### Formatter Registry 统一货币显示
+
+```text
+原始值: 1234.5
+zh-CN 显示: ¥1,234.50
+en-US 显示: $1,234.50
+de-DE 显示: 1.234,50 EUR
+排序/计算仍使用原始数值 1234.5
+```
+
+### RTL 使用 logical properties
+
+```css
+/* 推荐 */
+margin-inline-start: 1rem;
+/* 不推荐 */
+margin-left: 1rem;
+```
+
+### 后端错误映射为翻译 key
+
+```text
+后端返回: { "code": "ORDER.OUT_OF_STOCK", "message": "Insufficient inventory" }
+前端显示: t('error.ORDER.OUT_OF_STOCK') -> "库存不足，无法完成订单。"
+```
+
+**源：FE 39 文案协议 · §Examples**
+
+### 内容示例，可删除
+
+“该数据已被其他人更新。请比较最新版本后重新提交。”
+
+## Anti-patterns
+
+**源：FE 38 国际化协议 · §Anti-patterns**
+
+- 模板拼接币种和单位，切换语言后顺序、间距和小数规则错误。
+- 用 `if (count === 1)` 拼接单复数，阿拉伯语/俄语/波兰语分支错误。
+- 用 `{0}` 位置占位符，翻译调整语序后插值错位。
+- `Date.prototype.toLocaleString()` 无参调用，依赖用户系统时区导致显示不一致。
+- 硬编码 `$` / `￥` 符号，德语、法语显示格式错误。
+- 对格式化后的金额字符串做排序，导致 1000 < 99。
+- 用 `margin-left/right` 物理方向，RTL 布局破裂。
+- 图片包含 "New!" "Sale" 等英文文字，未做本地化即上线。
+- 硬编码春节/圣诞作为默认节日，其他 locale 用户困惑。
+- 后端错误 message 直接展示给用户，暴露内部术语或英文。
+- SSR 服务端用默认 locale 渲染，客户端 hydration 后闪烁切换。
+
+**源：FE 39 文案协议 · §Anti-patterns**
+
+系统异常只显示“失败！”，用户不知道对象、原因或下一步。
+
+## Ownership
+
+**源：FE 38 国际化协议 · §Ownership**
+
+产品/内容 Owner 维护语言范围和文化适配清单，i18n Owner 维护工具、key、Formatter Registry 和翻译工作流，领域 Owner 维护枚举语义和后端错误码映射，前端架构 Owner 维护 locale 切换、SSR hydration 和第三方 SDK 矩阵。
+
+**源：FE 39 文案协议 · §Ownership**
+
+内容/产品 Owner 维护语气，领域 Owner 确认语义，前端负责正确映射。
+
+## Change Policy
+
+**源：FE 38 国际化协议 · §Change Policy**
+
+Key 改名先提供别名或迁移；新增 locale 必须补资源、格式、布局回归和 RTL 测试。Formatter Registry 策略变化须评估所有页面/组件影响；第三方 SDK locale/RTL 兼容性矩阵随 SDK 版本更新而更新。
+
+**源：FE 39 文案协议 · §Change Policy**
+
+公共文案模板变化需评估全部场景；业务术语变化同步 i18n 和帮助内容。
+
+> **语言节**：本主题无语言节挂点（缺席诚实）；规则本体即上文通用节。