pomaster 0.3.0 → 0.4.0

package/seeds/specs/hard/frontend/28-form-protocol.md

@@ -0,0 +1,88 @@
+---
+seed_source: pomaster/components/frontend-hard-spec/assets/universal/28-form-protocol.md
+seed_source_sha256: 1359f0b753ece0f633b1aadea11e4ffd03dfc38f5b1f59e8cd869eba502e4807
+seed_version: B6B-2
+lane: frontend
+status: CURRENT
+authority_scope: mixed_required_and_advisory
+applies_to: [frontend]
+related_evidence_specs: []
+related_tools: []
+---
+
+# 28 表单协议
+
+## Scope
+
+P1。定义表单布局、模型、校验、联动、提交、回显、草稿、错误和冲突。
+
+## Non-Scope
+
+不定义具体业务字段和后端权威规则，不替代页面结构。
+
+## Terms
+
+- FormModel：独立于 DTO 的编辑模型。
+- Dirty State：当前值偏离初始值。
+- Field Error：绑定具体字段的错误。
+
+## MUST
+
+- 使用独立 FormModel 和 typed schema。
+- 必填、只读、自动计算、回填和无权限字段可区分。
+- 前端先做格式校验，后端字段错误定位并聚焦字段。
+- 提交防重复并保留失败输入。
+- 联动规则集中可测试，隐藏字段清值策略明确。
+- dirty 离开、草稿隔离和版本冲突有策略。
+- 每个输入必须有持久可见且程序化关联的标签、格式说明和必要性提示；placeholder 不得替代标签。
+- 校验错误必须与字段程序化关联，并在可行时给出修复建议；错误摘要必须能导航到对应字段。
+- 姓名、地址、联系方式、认证等常见字段必须使用语义正确的 autocomplete/inputmode 等浏览器提示，除非有明确的安全或业务理由。
+- 同一流程已提供的数据必须复用或允许用户确认，避免重复录入；删除、提交、转账等高风险动作必须提供复核、确认、撤销或等效防错。
+
+## MUST NOT
+
+- MUST NOT 直接绑定 DTO。
+- MUST NOT 在 template 临时写业务校验。
+- MUST NOT 提交失败清空输入。
+- MUST NOT 用大量互相触发 watcher 实现联动。
+- MUST NOT 只用颜色、图标、toast 或页面顶部文案表达字段错误。
+- MUST NOT 禁止密码管理器或无理由阻止粘贴。
+
+## SHOULD
+
+- SHOULD 大表单按业务语义分区或分步。
+- SHOULD 提供错误摘要和首错导航。
+
+## Contract
+
+```text
+FormModel, Schema, InitialValues, Validation,
+SubmitCommand, DraftPolicy, DirtyPolicy, ConflictPolicy
+```
+
+## Checklist
+
+- [ ] 模型和 schema 独立。
+- [ ] 字段错误可定位。
+- [ ] 防重复与冲突完整。
+- [ ] 草稿和离开策略安全。
+- [ ] 标签、说明、错误和字段程序化关联。
+- [ ] 自动填充、重复录入和高风险动作已检查。
+
+## Examples
+
+### 内容示例，可删除
+
+后端 422 字段错误映射到对应输入，保留用户数据并聚焦第一个错误。
+
+## Anti-patterns
+
+表单直接修改 DTO，失败后 reset，用户输入全部丢失。
+
+## Ownership
+
+领域 Owner 维护字段规则，前端 Owner 维护 FormModel，后端 Owner 维护权威校验。
+
+## Change Policy
+
+字段或联动变化必须同步 schema、adapter、草稿版本、错误映射和测试。

package/seeds/specs/hard/frontend/29-routing-url-protocol.md

@@ -0,0 +1,79 @@
+---
+seed_source: pomaster/components/frontend-hard-spec/assets/universal/29-routing-url-protocol.md
+seed_source_sha256: 3066c383489e1cb72271fe48d4a716860c58381d90e46ee1b2f114c61010949e
+seed_version: B6B-2
+lane: frontend
+status: CURRENT
+authority_scope: mixed_required_and_advisory
+applies_to: [frontend]
+related_evidence_specs: []
+related_tools: []
+---
+
+# 29 路由与 URL 协议
+
+## Scope
+
+P1。定义路由命名、参数、URL 状态、返回恢复、守卫和异常页面。
+
+## Non-Scope
+
+不定义页面内部布局、权限来源和全局状态库。
+
+## Terms
+
+- Route Contract：name、path、meta 和页面 key 的稳定定义。
+- Shareable State：刷新、分享、返回后应恢复的状态。
+- Ephemeral State：弹窗、hover、未提交输入等临时状态。
+
+## MUST
+
+- 每个页面路由有稳定 name、path、page key、title、权限和布局 meta。
+- 分页、筛选、排序、tab 等 Shareable State 进入 URL。
+- Query 有 schema、默认值、解析失败兜底和版本策略。
+- 返回恢复分页、筛选、排序和必要视图状态。
+- 401、403、404、500 和资源删除有统一路由策略。
+
+## MUST NOT
+
+- MUST NOT 把 token、敏感信息、大对象和未提交表单放入 URL。
+- MUST NOT 用标题字符串或 URL 截取判断菜单。
+- MUST NOT 在页面直接修改全局路由表。
+- MUST NOT 改 path/name 而不更新调用方。
+
+## SHOULD
+
+- SHOULD 由 Page Contract 生成路由、菜单和埋点关联。
+- SHOULD 使用 typed query parser。
+
+## Contract
+
+```text
+RouteName, Path, PageKey, Meta, ParamsSchema,
+QuerySchema, RestorePolicy, ErrorRoutes
+```
+
+## Checklist
+
+- [ ] 路由和页面 key 一致。
+- [ ] URL 状态可分享恢复。
+- [ ] 临时/敏感状态未进入 URL。
+- [ ] 异常路由完整。
+
+## Examples
+
+### 内容示例，可删除
+
+列表分页筛选写入 query，返回列表时按 URL 恢复，不依赖全局临时 store。
+
+## Anti-patterns
+
+用中文标题匹配当前菜单，将所有页面筛选永久存入全局状态。
+
+## Ownership
+
+平台路由 Owner 维护机制，页面 Owner 维护 Route Contract，权限 Owner 维护守卫语义。
+
+## Change Policy
+
+路由破坏性变化必须提供重定向、链接迁移和监控观察期。

package/seeds/specs/hard/frontend/30-data-grid-protocol.md

@@ -0,0 +1,83 @@
+---
+seed_source: pomaster/components/frontend-hard-spec/assets/universal/30-data-grid-protocol.md
+seed_source_sha256: c702a9956fd5e7aac40e1eefebcdd7a3518b95bd1a750bfcb31cbaddb80f41ff
+seed_version: B6B-2
+lane: frontend
+status: CURRENT
+authority_scope: mixed_required_and_advisory
+applies_to: [frontend]
+related_evidence_specs: []
+related_tools: []
+---
+
+# 30 数据表格协议
+
+## Scope
+
+P1。定义表格壳、列 schema、列宽、固定列、分页、排序筛选、虚拟滚动、列配置和导出。
+
+## Non-Scope
+
+不定义业务字段口径，不允许表格库决定页面权限和数据契约。
+
+## Terms
+
+- Grid Type：可编辑宽表、只读表、报表、主数据表等类型。
+- Column Schema：列 key、类型、宽度、权限和行为契约。
+- Saved View：用户保存的列、筛选和排序配置。
+
+## MUST
+
+- 表格通过统一壳和 typed Column Schema 渲染。
+- 每列有稳定 key、标题、值类型、宽度策略、权限和导出规则。
+- 大数据使用服务端分页/筛选/排序及虚拟化。
+- 列配置按页面、表格、用户和 schema 版本隔离。
+- 列宽修复先判断单页、同类型、领域 preset、表格壳或全局 token。
+- 公共壳变更验证全部 Grid Type。
+- 表格的交互状态（行 click / double-click / select / drag-select / 列头排序 click / 单元格 focus 等）MUST 在 `interaction-contract-registry` 中逐项声明，每项绑定触发的 `action_id` 与调用的 `api_requirement_ids`；表格不得存在未声明的交互。并非每个表格都要支持所有交互，但所支持的交互子集 MUST 显式界定并说明触发后果。排斥键盘的交互（drag / drag-select / hover-only）MUST 声明键盘等价路径（协议 23）。
+
+## MUST NOT
+
+- MUST NOT template 手写列或跨页面复制列数组。
+- MUST NOT 为单页列宽修改全局 CSS。
+- MUST NOT 不同类型表格共享污染配置 key。
+- MUST NOT 前端加载全量数据假分页。
+
+## SHOULD
+
+- SHOULD 固定关键标识/操作列并限制冻结总宽。
+- SHOULD 支持键盘、复制粘贴、冲突和保存视图的明确契约。
+
+## Contract
+
+```text
+GridType, RowKey, ColumnSchema[], ServerOperations,
+Virtualization, SavedViewKey, ExportScope, Permissions,
+InteractionContracts[]
+```
+
+## Checklist
+
+- [ ] 表格由 schema 驱动。
+- [ ] 列宽影响层级正确。
+- [ ] 大数据和配置隔离安全。
+- [ ] 导出与当前视图一致。
+- [ ] 每个支持的交互（行点击/双击/拖选/排序/聚焦）在 interaction-contract-registry 声明并绑定 action + API。
+
+## Examples
+
+### 内容示例，可删除
+
+同类型报表共享 column preset；单页例外写在 page contract，不改可编辑宽表。
+
+## Anti-patterns
+
+为某报表加全局 `.table td { width }`，导致所有列表和宽表一起变化。
+
+## Ownership
+
+表格平台 Owner 维护壳，领域 Owner 维护列 schema，页面 Owner 维护例外。
+
+## Change Policy
+
+列 schema 和保存视图结构必须版本化；公共行为变化遵循影响评估和视觉回归。

package/seeds/specs/hard/frontend/31-performance-protocol.md

@@ -0,0 +1,137 @@
+---
+seed_source: pomaster/components/frontend-hard-spec/assets/universal/31-performance-protocol.md
+seed_source_sha256: 416ff411c75e538feec3aad8be5e733b95913580fd937c0abebd16aa0d21608c
+seed_version: B6B-2
+lane: frontend
+status: CURRENT
+authority_scope: mixed_required_and_advisory
+applies_to: [frontend]
+related_evidence_specs: []
+related_tools: []
+---
+
+# 31 性能协议
+
+## Scope
+
+P1。定义首屏、包体、请求、列表、表格、图表、长任务和渲染稳定的性能规则。
+
+## Non-Scope
+
+不替代后端容量规划和基础设施性能，不允许只追分数牺牲正确性。
+
+## Terms
+
+- Performance Budget：可验证的时间、大小或资源阈值。
+- Core Web Vitals：LCP、INP、CLS 等反映加载、交互响应和视觉稳定性的用户体验指标。
+- RUM Distribution：按页面类型、设备、网络、浏览器、版本和采样窗口聚合的真实用户指标分布。
+- Virtualization：仅渲染可见窗口数据。
+- Stale Response：已被新请求替代的旧响应。
+
+## MUST
+
+- 定义首屏、包体、交互和核心页面预算。
+- 路由、图表和重组件按需加载。
+- 大列表服务端分页，宽表虚拟化。
+- 搜索防抖、旧请求取消、过期响应丢弃。
+- 长任务异步执行并可恢复。
+- 性能变更用同数据量测量并记录结果。
+- 性能预算必须区分实验室数据与真实用户数据，记录设备、网络、浏览器、采样窗口、指标版本和 p75 等统计口径。
+- 启用真实用户监测时，核心 Web Vitals 应按当前稳定定义分设备评估；默认参考目标为 p75 的 LCP ≤ 2.5s、INP ≤ 200ms、CLS ≤ 0.1，项目可基于证据收紧或批准例外。
+- LCP、INP、CLS、FCP、TTFB、长任务和关键业务交互预算必须声明数据源、指标版本、测量起止点、样本下限、排除规则、聚合窗口和适用页面类型；p75 用于主要放行判断，p95/p99 用于尾部退化诊断。
+- RUM 报告必须按页面类型、设备类别、网络类别、浏览器和应用版本切分，实验室结果不得冒充真实用户分布；运行采集与传输韧性引用 `34-monitoring-logging-protocol`。
+- 页面隐藏、恢复与离开时必须暂停不必要工作并释放资源，恢复后重新校验数据新鲜度；遵守浏览器运行时生命周期协议。
+
+### 分层性能责任（按目录层级）
+
+性能是架构期约束，按目录层级分担责任；每层有明确的性能检查点与禁止行为。层级划分与 `09-module-boundary-protocol` 一致。
+
+- **app 层 — 应用启动性能**：初始化代码、Provider 数量、全局插件、首屏依赖必须精简。路由必须懒加载（router-level lazy loading）。MUST NOT 在应用入口（如 `main.ts`）直接同步 import 重型编辑器、图表库或大表组件（用户打开登录页即加载整个系统能力 → 首屏变慢）。
+- **platform 层 — 状态管理性能**：server state 走 Query Cache，local UI state 走状态库（如 Pinia）。MUST NOT 在全局 store 存储大量业务数据（如 10 万 BOM 节点入 Pinia → reactive 开销、刷新慢、内存增加）。
+- **api 层 — 网络性能治理**：页面初始化请求必须并行或由后端聚合。MUST NOT 串行发起可并行的请求（如打开页面串行 GET user/permission/menu/bom/supplier/price/config = N×RTT）。
+- **domain 层 — 计算性能**：实时轻计算在前端，重计算后台异步。MUST NOT 前端遍历大数据全集做计算（如改一个零件价格就遍历 10 万 BOM 节点 → CPU 100%、页面冻结）。
+- **feature 层 — 页面级性能**：页面进入核心优先、非核心延迟加载（如 BOM 编辑页：核心表格先加载，历史/图表/分析延迟）。MUST NOT 一次加载页面全部重组件。
+- **shared 层 — 公共组件性能**：Table / Tree / Select / Form / Modal / Virtual List 面对大数据必须虚拟滚动或分页。MUST NOT 大列表用普通 `v-for` 渲染全量数据（如 10000 行表格普通渲染）。
+
+## MUST NOT
+
+- MUST NOT 一次渲染大数据全部节点。
+- MUST NOT 每次按键立即请求。
+- MUST NOT 让旧响应覆盖新状态。
+- MUST NOT 在 render 中执行复杂计算。
+- MUST NOT 为追求性能分数牺牲安全、正确性、可访问性或用户可恢复性。
+- MUST NOT 混用不同版本、不同环境或不同统计口径的性能结果作直接回归结论。
+- MUST NOT 只报告平均值而省略样本量、分位数、窗口和切分维度。
+- MUST NOT 在本协议定义业务行为漏斗或事件用途；这些规则归 `40-analytics-protocol`。
+- MUST NOT 在应用入口同步 import 重型编辑器、图表库或大表组件（首屏重依赖）。
+- MUST NOT 在全局状态库存储大量业务数据（server state 须走 Query Cache）。
+- MUST NOT 串行发起可并行的页面初始化请求（须并行或后端聚合）。
+- MUST NOT 前端遍历大数据全集做计算（须实时轻计算 + 后台异步重计算）。
+- MUST NOT 一次加载页面全部重组件（须核心优先、非核心延迟加载）。
+- MUST NOT 大列表用普通 `v-for` 渲染全量数据（须虚拟滚动或分页）。
+
+## SHOULD
+
+- SHOULD 监控真实用户核心指标和业务交互时间。
+- SHOULD 同时观察 p75 与 p95/p99，区分总体回归和长尾退化，并为样本不足标记不可判定而非假定通过。
+- SHOULD 保持行高、工具栏和 loading 尺寸稳定。
+
+## Contract
+
+```text
+Scenario, DatasetSize, BudgetMetric, Threshold,
+MeasurementMethod, DataSource, MetricVersion, SampleWindow, SampleSize,
+Percentile, Dimensions, Baseline, Owner
+```
+
+分层性能责任契约（按目录层级，与 `09-module-boundary-protocol` 层级一致）：
+
+```text
+Layer, Responsibility, CheckPoint, Forbidden
+app, 启动性能/路由懒加载, 入口依赖 + Provider/插件数 + 首屏包, 入口同步 import 重型组件
+platform, 状态管理性能, server vs local 归属 + store 数据量, 全局 store 存大数据
+api, 网络性能, 请求并行/聚合 + 串行风暴, 可并行请求串行发起
+domain, 计算性能, 实时轻计算 + 后台异步, 前端遍历大数据全集
+feature, 页面级性能, 核心优先 + 非核心延迟, 一次加载全部重组件
+shared, 公共组件性能, 虚拟滚动/分页, 大列表普通 v-for
+```
+
+## Checklist
+
+- [ ] 预算和数据量明确。
+- [ ] 分包、分页、虚拟化合理。
+- [ ] 请求并发安全。
+- [ ] 有测量证据。
+- [ ] 实验室/真实用户口径、指标版本和分位数已记录。
+- [ ] LCP/INP/CLS 等预算含数据源、样本下限、窗口、排除规则和页面适用范围。
+- [ ] RUM 报告包含 p75 主要口径与 p95/p99 长尾诊断，样本不足不会被提升为通过。
+- [ ] 隐藏、恢复与离开场景无无效工作和资源泄漏。
+- [ ] 分层性能责任已按 app/platform/api/domain/feature/shared 分担，每层检查点与禁止行为已确认。
+
+## Examples
+
+### 内容示例，可删除
+
+筛选输入防抖并取消旧请求，详情抽屉按需加载，导出创建后台任务。
+
+## Anti-patterns
+
+下载十万行到浏览器假分页，导致内存和交互崩溃。
+
+应用入口同步 import 重型编辑器/图表/大表组件，导致登录页首屏被拖慢。
+
+全局 Pinia store 存储 10 万 BOM 节点，reactive 开销致刷新慢、内存涨。
+
+打开页面串行发起 6 个可并行请求，体验 N×RTT。
+
+修改一个零件价格即遍历 10 万 BOM 节点重新计算，CPU 100%、页面冻结。
+
+10000 行表格用普通 `v-for` 渲染，未虚拟滚动。
+
+## Ownership
+
+前端性能 Owner 维护预算，模块 Owner 修复回归，后端 Owner 配合数据和接口容量。
+
+## Change Policy
+
+预算放宽必须有数据和批准；新增重依赖或核心页面需建立基线。

package/seeds/specs/hard/frontend/32-file-import-export-protocol.md

@@ -0,0 +1,80 @@
+---
+seed_source: pomaster/components/frontend-hard-spec/assets/universal/32-file-import-export-protocol.md
+seed_source_sha256: 2262d7ce2e910e4d64b0c6f3ef1af0b72c3cafc31d6cb1a796a8fb8b1801cbbc
+seed_version: B6B-2
+lane: frontend
+status: CURRENT
+authority_scope: mixed_required_and_advisory
+applies_to: [frontend]
+related_evidence_specs: []
+related_tools: []
+---
+
+# 32 文件、导入与导出协议
+
+## Scope
+
+P1。定义文件上传、下载、模板、导入校验、错误明细、导出范围和后台任务。
+
+## Non-Scope
+
+不定义底层存储实现，不替代安全、权限和异步任务接口契约。
+
+## Terms
+
+- Import Template：与 schema 版本匹配的输入模板。
+- Partial Success：部分行成功、失败、跳过或警告。
+- Export Scope：当前页、选中行、筛选全量、保存视图或汇总。
+
+## MUST
+
+- 上传声明类型、大小、数量、文件名和安全校验。
+- 导入流程包含模板、上传、校验、任务、进度、结果和错误明细。
+- 错误明细至少包含行、列、字段、原值、错误码和修复建议。
+- 导出明确范围、字段、权限和有效期。
+- 大文件使用后台任务，完成后刷新依赖数据。
+- 下载时重新鉴权和校验数据范围。
+
+## MUST NOT
+
+- MUST NOT 静默导入失败。
+- MUST NOT 大文件同步阻塞页面。
+- MUST NOT 页面自行拼导出字段或绕过权限。
+- MUST NOT 成功后遗漏缓存刷新。
+
+## SHOULD
+
+- SHOULD 支持取消、重试、结果通知和来源页面跳转。
+- SHOULD 让模板和错误文件可追踪 schema 版本。
+
+## Contract
+
+```text
+FilePolicy, TemplateVersion, ImportJob,
+ErrorRowSchema, ExportScope, ResultExpiry, Permissions
+```
+
+## Checklist
+
+- [ ] 文件策略明确。
+- [ ] 导入全流程和部分成功完整。
+- [ ] 导出范围与权限一致。
+- [ ] 大文件任务化。
+
+## Examples
+
+### 内容示例，可删除
+
+导入完成显示成功、失败、跳过和警告数量，并提供字段级错误文件。
+
+## Anti-patterns
+
+上传后只显示“导入失败”，没有行号、原因、TraceId 或重试路径。
+
+## Ownership
+
+业务 Owner 定义字段，文件/任务 Owner 维护流程，安全 Owner 维护文件策略。
+
+## Change Policy
+
+模板、字段和错误 schema 变化必须版本化并提供兼容/迁移说明。

package/seeds/specs/hard/frontend/33-release-versioning-protocol.md

@@ -0,0 +1,79 @@
+---
+seed_source: pomaster/components/frontend-hard-spec/assets/universal/33-release-versioning-protocol.md
+seed_source_sha256: aae0557f4935bac24d04e37ebde5638471b709ff568fea0d13de35bd5dd404af
+seed_version: B6B-2
+lane: frontend
+status: CURRENT
+authority_scope: mixed_required_and_advisory
+applies_to: [frontend]
+related_evidence_specs: []
+related_tools: []
+---
+
+# 33 版本与发布协议
+
+## Scope
+
+P2。定义版本标识、分支/提交、灰度、回滚、公共 API 兼容和发布证据。
+
+## Non-Scope
+
+不替代验收门禁、组织发布平台和基础设施部署流程。
+
+## Terms
+
+- App Version：可关联提交、构建、环境和 source map 的版本。
+- Gray Release：受控用户/环境范围内逐步发布。
+- Rollback：恢复到已验证版本和兼容状态。
+
+## MUST
+
+- 每个构建有可观测版本和来源。
+- 发布前契约、测试、安全、配置、监控和回滚满足门禁。
+- 高风险变更定义灰度和停止条件。
+- 回滚同时考虑前端资源、接口、缓存、任务和数据兼容。
+- 公共 breaking change 先 deprecated 并提供迁移期。
+
+## MUST NOT
+
+- MUST NOT 无版本标识发布。
+- MUST NOT 无回滚上线破坏性变化。
+- MUST NOT 直接删除公共 API。
+- MUST NOT 发布后才补监控和 source map。
+
+## SHOULD
+
+- SHOULD 自动生成变更摘要和发布证据。
+- SHOULD 使用 Feature Flag 降低高风险上线范围。
+
+## Contract
+
+```text
+Version, Commit, BuildTime, Environment, Changes,
+Flags, Migration, Monitoring, Rollback, Owner
+```
+
+## Checklist
+
+- [ ] 版本可追踪。
+- [ ] 门禁和契约通过。
+- [ ] 灰度与回滚可执行。
+- [ ] deprecated/迁移完整。
+
+## Examples
+
+### 内容示例，可删除
+
+公共组件新 API 与旧 API 并存一个迁移周期，再在版本公告后删除旧 API。
+
+## Anti-patterns
+
+静态资源已回滚，但新缓存 schema 和后台任务仍不兼容旧页面。
+
+## Ownership
+
+发布 Owner 负责流程，模块 Owner 负责兼容，平台 Owner 负责回滚和监控。
+
+## Change Policy
+
+版本和发布策略变化必须同步 CI/CD、门禁、文档和责任人。

package/seeds/specs/hard/frontend/34-monitoring-logging-protocol.md

@@ -0,0 +1,128 @@
+---
+seed_source: pomaster/components/frontend-hard-spec/assets/universal/34-monitoring-logging-protocol.md
+seed_source_sha256: 3c37c1c3aa3ade8d43532a1fcc7561e95aef42a19e46b6eb53d864054a2da013
+seed_version: B6B-2
+lane: frontend
+status: CURRENT
+authority_scope: mixed_required_and_advisory
+applies_to: [frontend]
+related_evidence_specs: []
+related_tools: []
+---
+
+# 34 监控与日志协议
+
+## Scope
+
+P1。作为前端运行可观测性的主权威，定义结构化日志、技术遥测、错误与白屏、Trace/Span/Breadcrumb、RED 指标、RUM 采集、告警和遥测传输韧性。
+
+## Non-Scope
+
+不替代后端审计、基础设施容量监控和具体 APM 厂商选型；业务行为事件、漏斗和分析用途归 `40-analytics-protocol`，LCP/INP/CLS 等性能预算、RUM 统计口径和分位数归 `31-performance-protocol`。不允许监控收集权限外数据。
+
+## Terms
+
+- Error Event：可定位的运行失败记录。
+- Trace：一次端到端请求的因果链，由 trace-id 贯穿。
+- Span：Trace 内的单个操作单元，记录开始/结束时间、父关系和受控元数据。
+- Breadcrumb：错误前的受控操作路径。
+- RED 指标：Rate（请求率）、Errors（错误率）、Duration（耗时）。
+- RUM：Real User Monitoring，采集真实用户设备、网络、性能和交互指标的运行监测方式。
+- Source Map：映射压缩代码到源代码的受控文件。
+
+## MUST
+
+- 每个应用、页面和关键 API 面必须声明运行可观测性 Owner，负责日志字段、技术指标、追踪、告警和恢复证据。
+- 采集并分类运行错误、Promise rejection、资源失败、接口错误、白屏和根组件渲染失败；每类必须关联 `16-error-handling-protocol` 定义的 UI 状态与恢复策略。
+- 结构化日志包含时间、级别、稳定 message_id、版本、环境、页面、组件/操作、trace-id、浏览器和安全上下文摘要。
+- 关键 API 调用必须生成或传播 trace-id；请求、响应、错误日志与 breadcrumb 必须保持同一关联标识，Span 必须记录父子关系、耗时、结果和受控元数据。
+- HTTP client 与关键异步任务必须聚合 RED 指标；指标名称、单位、维度和版本必须稳定，完整 URL、DOM 文本、用户输入或其他高基数字段不得作为维度。
+- 启用 RUM 时必须采集真实用户运行信号，并携带页面类别、设备类别、网络类别、应用版本和指标版本；性能预算、统计窗口与分位数引用 `31-performance-protocol`，不得在本协议重复定义阈值。
+- source map 与版本对应且受权限保护。
+- 日志字段脱敏并限制请求/响应摘要。
+- 关键错误率、API 失败率、白屏率和运行退化信号必须有告警阈值、升级策略、负责人、静默窗口和运行手册。
+- 监控事件 schema、版本、采样率、批大小、缓存上限、刷新时机、重试退避、用途、保留期限和删除策略必须明确；页面隐藏、卸载或网络恢复时必须按受控策略尽力刷新待发送遥测。
+- 监控 SDK 初始化失败、遥测序列化失败或发送失败必须 fail-open，不得阻断应用主流程；失败本身必须产生可恢复的安全诊断信号，且缓存必须有容量与过期边界。
+
+### 分层运行可观测性责任（按目录层级）
+
+运行可观测性是架构期横切能力，层级划分与 `09-module-boundary-protocol` 一致。
+
+- **app 层 — 启动与全局运行观测**：初始化日志、指标、追踪和 RUM SDK，注册全局错误处理器与白屏检测，声明全局 trace 传播策略；不得用入口 console 输出替代生产遥测或吞错不上报。
+- **platform 层 — 状态与网络观测**：统一记录全局状态操作的受控 span，在 HTTP client 注入请求/响应拦截、RED 指标与 trace-id；不得记录完整状态对象或让业务请求自定义 trace 头格式。
+- **api 层 — 请求链路观测**：记录请求分类、耗时、错误码、重试次数和 trace 传播；不得记录 token，也不得以完整 URL 或 DOM 文本制造高基数维度。
+- **domain 层 — 计算与转换观测**：记录复杂计算/转换耗时、输入量级、异常分支和异步任务状态；不得把 UI Toast/Alert 当作唯一诊断手段。
+- **feature 层 — 页面运行观测**：声明页面运行状态转换、错误边界、关键 API 技术信号和性能预算对比；业务 page-view/action 漏斗与事件去重归 `40-analytics-protocol`。
+- **shared 层 — 组件与工具观测**：公共组件暴露受控 telemetry hook，工具函数记录异常边界；不得把内部调试日志当正式遥测或硬编码业务分析 schema。
+
+## MUST NOT
+
+- MUST NOT 记录 token、密码、敏感原值或完整文件。
+- MUST NOT 仅用 console 作为生产监控。
+- MUST NOT 捕获后静默吞错。
+- MUST NOT 公开部署 source map。
+- MUST NOT 把用户标识、PII、认证信息或业务原值放入 Trace Context、breadcrumb 或高基数字段。
+- MUST NOT 在没有 trace-id 的情况下发起关键 API 请求。
+- MUST NOT 让页面、组件或请求层各自发明不兼容的日志、指标或追踪字段。
+- MUST NOT 让 SDK 初始化、遥测缓存或发送重试阻塞首屏、用户操作或错误恢复。
+- MUST NOT 把业务行为漏斗、转化口径或分析用途定义在运行诊断 schema 中。
+
+## SHOULD
+
+- SHOULD 关联用户操作、请求和异步任务 TraceId。
+- SHOULD 控制采样并防止告警风暴。
+- SHOULD 在启用分布式追踪时遵循 W3C Trace Context，并验证跨来源边界的头部传播和信任策略。
+- SHOULD 对告警关联运行手册、最近变更和可回滚版本。
+- SHOULD 对遥测批处理、缓存、退避和丢弃量建立自监控，但不得形成无限递归上报。
+
+## Contract
+
+```text
+SignalType, SchemaVersion, AppVersion, Environment, Page, ComponentOrOperation,
+TraceId, SpanId, ParentSpanId, MessageId, ErrorCode, Duration, SafeDimensions,
+SamplingPolicy, Retention, Timestamp, Owner
+```
+
+分层运行可观测性责任契约（与 `09-module-boundary-protocol` 层级一致）：
+
+```text
+Layer, Responsibility, CheckPoint, Forbidden
+app, SDK/全局错误/白屏/trace 策略, 初始化降级 + 全局处理器 + 版本绑定, console 替代遥测 / 吞错
+platform, 状态与网络技术遥测, store span + HTTP RED + trace 注入, 完整状态对象 / 自定义 trace 格式
+api, 请求链路, 分类 + 耗时 + 错误码 + 重试 + trace, token / 高基数 URL 或 DOM
+domain, 计算与异步任务, 耗时 + 数据量级 + 异常分支 + 任务状态, UI 提示作为唯一诊断
+feature, 页面运行状态, 错误边界 + 技术信号 + 性能预算引用, 重复定义业务分析漏斗
+shared, 公共 telemetry hook, 组件/工具异常边界, 调试日志当正式遥测 / 业务 schema 硬编码
+```
+
+## Checklist
+
+- [ ] 错误和白屏可定位。
+- [ ] 版本与 source map 对应。
+- [ ] 日志无敏感信息。
+- [ ] 告警和 Owner 明确。
+- [ ] Trace/Span/Breadcrumb 与关键 API、错误和异步任务可关联。
+- [ ] RED 与 RUM 技术信号有稳定名称、单位、维度和指标版本；预算与分位数口径引用 31。
+- [ ] schema、版本、采样、批处理、缓存、重试、保留和删除策略明确。
+- [ ] 遥测故障不影响主流程，Trace Context 不携带敏感数据。
+- [ ] 分层责任已按 app/platform/api/domain/feature/shared 分担并引用 09。
+
+## Examples
+
+### 内容示例，可删除
+
+系统错误展示 TraceId；HTTP client、错误日志和 breadcrumb 记录同一 TraceId 与版本。遥测按受控批次发送，SDK 故障时主流程继续并记录安全降级信号，不记录输入原值。
+
+## Anti-patterns
+
+生产只打印 console.error，用户截图是唯一定位依据。
+
+每个页面自行初始化 SDK、定义 trace 头和日志字段，导致链路无法关联；发送失败时无限重试并阻塞页面卸载。
+
+## Ownership
+
+Observability/平台 Owner 维护运行遥测 schema、SDK、trace 传播和告警；模块 Owner 维护安全上下文与恢复映射；性能 Owner 维护 31 的预算与统计口径；数据/产品 Owner 维护 40 的业务分析事件；安全/隐私 Owner 审核字段、采样、保留和删除策略。
+
+## Change Policy
+
+运行遥测 schema、日志字段、技术指标、trace 传播、采样、批处理、缓存、重试、保留、告警和 source map 策略变化必须评审隐私、性能、成本、兼容性和可诊断性；不得把 31/40 的权威规则复制回本协议。