pomaster 0.3.0 → 0.4.0

package/seeds/specs/hard/frontend/41-design-handoff-protocol.md

@@ -0,0 +1,80 @@
+---
+seed_source: pomaster/components/frontend-hard-spec/assets/universal/41-design-handoff-protocol.md
+seed_source_sha256: 335df4991a29eb77222b0596de5db7fcc0bd5d9019ecf9bf882a08cea74c1937
+seed_version: B6B-2
+lane: frontend
+status: CURRENT
+authority_scope: mixed_required_and_advisory
+applies_to: [frontend]
+related_evidence_specs: []
+related_tools: []
+---
+
+# 41 设计交付协议
+
+## Scope
+
+P2。定义设计到代码的组件来源、token、状态、响应式、可访问性和验收交付。
+
+## Non-Scope
+
+不允许设计稿覆盖正式组件 API、安全、业务规则和工程边界。
+
+## Terms
+
+- Design Handoff：可供实现和验收的完整设计交付。
+- State Matrix：默认、加载、空、错误、权限、禁用、长文本和小屏等状态。
+- Design Source：设计系统组件和 token 的唯一来源。
+
+## MUST
+
+- 交付页面类型、组件来源、token、关键视口和交互流程。
+- 提供完整 State Matrix，不只理想态。
+- 标注响应式、长文本、缩放、键盘和焦点要求。
+- 表格/报表交付列宽、固定列、大数据和导出状态。
+- 设计变更有版本、原因、影响范围和通知。
+- 设计验收同时检查可用性、可访问性和契约。
+
+## MUST NOT
+
+- MUST NOT 未标注来源就要求新建相似组件。
+- MUST NOT 用设计稿临时值覆盖 token。
+- MUST NOT 只交付桌面理想成功态。
+- MUST NOT 通过页面局部 CSS 修补系统问题。
+
+## SHOULD
+
+- SHOULD 使用设计系统组件实例和 token 变量。
+- SHOULD 将高风险交互做可点击原型和键盘说明。
+
+## Contract
+
+```text
+PageOrComponent, DesignVersion, SourceComponents[],
+Tokens[], States[], Viewports[], Interaction, Accessibility, Owner
+```
+
+## Checklist
+
+- [ ] 组件和 token 来源明确。
+- [ ] 状态与视口完整。
+- [ ] 表格/长文本/a11y 已覆盖。
+- [ ] 版本和影响可追踪。
+
+## Examples
+
+### 内容示例，可删除
+
+设计交付同时包含正常、无权限、错误、长文本、125% 缩放和键盘焦点状态。
+
+## Anti-patterns
+
+只有一张理想截图，未说明组件来源、错误状态和小屏行为，开发只能猜测。
+
+## Ownership
+
+Design Owner 负责交付完整性，Frontend Owner 负责可实现性，QA/Accessibility Owner 负责验收。
+
+## Change Policy
+
+开发开始后的设计变化必须更新版本和影响范围；公共组件变化走变更治理。

package/seeds/specs/hard/frontend/42-browser-runtime-lifecycle-protocol.md

@@ -0,0 +1,86 @@
+---
+seed_source: pomaster/components/frontend-hard-spec/assets/universal/42-browser-runtime-lifecycle-protocol.md
+seed_source_sha256: b328c8b3bab2006254587143c634e17ff554d2f0103056d07edba5ffaba29fe1
+seed_version: B6B-2
+lane: frontend
+status: CURRENT
+authority_scope: mixed_required_and_advisory
+applies_to: [frontend]
+related_evidence_specs: []
+related_tools: []
+---
+
+# 42 浏览器运行时资源生命周期协议
+
+## Scope
+
+P1。定义事件监听、计时器、动画帧、Observer、请求、流、长连接、Worker、对象 URL 和页面生命周期资源的所有权、暂停、恢复与释放。
+
+## Non-Scope
+
+不规定具体框架的生命周期 API，不替代请求重试、缓存新鲜度或后端连接治理。
+
+## Terms
+
+- Runtime Resource：必须显式取得并释放的浏览器资源或异步工作。
+- Resource Owner：唯一负责创建、暂停、恢复和销毁资源的作用域。
+- Obsolete Work：页面、参数、身份或权限上下文变化后已不再有效的异步工作。
+- Page Lifecycle：页面可见、隐藏、冻结、恢复、前进后退缓存和销毁等状态。
+
+## MUST
+
+- 每个 Runtime Resource 必须声明 Owner、创建条件、释放动作、暂停/恢复策略和失效触发器。
+- `addEventListener`、计时器、动画帧、Observer、订阅、流、WebSocket、EventSource、BroadcastChannel、Worker 和对象 URL 必须有成对的移除、清除、断开、关闭、终止或撤销动作。
+- 请求、异步计算和回调在作用域结束或上下文变化时必须取消；无法取消时必须在提交结果前验证当前请求、身份、权限和参数版本。
+- 路由离开、组件销毁、注销、切换账号/租户、权限变化和功能关闭必须清理对应资源与敏感上下文。
+- 页面隐藏、冻结或进入前进后退缓存时必须暂停无必要轮询和高频工作；恢复时重新验证数据新鲜度、连接状态和权限上下文。
+- `beforeunload` 只能在确有未保存数据时动态注册，并在风险解除后移除。
+- 重复进入、挂载、恢复或重试必须保持资源数量有界，并有自动化证据证明不会重复订阅或产生开放句柄。
+
+## MUST NOT
+
+- MUST NOT 依赖 `unload` 完成保存、上报、释放或业务提交。
+- MUST NOT 让过期请求、Worker 或订阅结果覆盖新状态。
+- MUST NOT 在隐藏或冻结页面持续无必要轮询、动画或重计算。
+- MUST NOT 创建没有 Owner 和释放路径的全局监听、计时器、Observer、长连接或第三方实例。
+- MUST NOT 在作用域销毁后继续写入 UI、缓存或用户状态。
+
+## SHOULD
+
+- SHOULD 使用 `AbortSignal` 或等价的统一取消机制聚合作用域内资源。
+- SHOULD 为复杂页面提供资源注册表或诊断计数，便于测试重复挂载、导航和恢复。
+- SHOULD 优先使用 `pagehide`、`pageshow`、`visibilitychange` 等可恢复的页面生命周期信号。
+
+## Contract
+
+```text
+ResourceId, ResourceType, OwnerScope, AcquireCondition,
+PauseTrigger, ResumeTrigger, DisposeAction, InvalidationTriggers[],
+LateResultGuard, DiagnosticEvidence
+```
+
+## Checklist
+
+- [ ] 每个资源有唯一 Owner 和成对释放动作。
+- [ ] 路由、身份、权限和参数变化会取消旧工作。
+- [ ] 隐藏、冻结和恢复行为已验证。
+- [ ] 重复挂载不会增加订阅或开放句柄。
+- [ ] 不依赖 unload 完成关键行为。
+
+## Examples
+
+### 内容示例，可删除
+
+页面作用域通过同一个取消信号管理请求和事件监听；离开页面时关闭订阅、终止 Worker、撤销对象 URL，并拒绝晚到结果写回。
+
+## Anti-patterns
+
+每次进入页面都新增轮询和全局监听，离开时不清理；返回页面后同一消息被处理多次，旧请求还覆盖了新筛选结果。
+
+## Ownership
+
+平台 Owner 维护资源基础设施，页面/组件 Owner 声明资源边界，测试 Owner 验证释放和恢复行为。
+
+## Change Policy
+
+新增资源类型或改变生命周期时必须同步 Owner、释放、恢复、身份失效和测试证据，并检查 `universal:performance-protocol`、`universal:state-management-protocol` 与 `universal:security-protocol`。

package/seeds/specs/hard/frontend/43-time-temporal-protocol.md

@@ -0,0 +1,86 @@
+---
+seed_source: pomaster/components/frontend-hard-spec/assets/universal/43-time-temporal-protocol.md
+seed_source_sha256: 4669cc3d927289f99bbd66c3e906f97d548f0cf8ea9e94b66e8b21cb24d00afb
+seed_version: B6B-2
+lane: frontend
+status: CURRENT
+authority_scope: mixed_required_and_advisory
+applies_to: [frontend]
+related_evidence_specs: []
+related_tools: []
+---
+
+# 43 时间、日期与时区协议
+
+## Scope
+
+P1。定义时间点、日历日期、墙上时间、带时区计划、持续时长、序列化、计算、显示和测试语义。
+
+## Non-Scope
+
+不决定项目业务时区、营业日历、节假日或具体日期库，不替代国际化显示协议。
+
+## Terms
+
+- Instant：全球唯一的精确时间点。
+- Local Date：不带时间与时区的日历日期。
+- Wall-clock Time：某地日历和时钟上的本地时间，不天然对应唯一 Instant。
+- Zoned Schedule：带命名时区和日历规则的计划时间。
+- Duration：两个时间点之间的经过量或业务定义时长。
+
+## MUST
+
+- 每个时间字段必须分类为 Instant、Local Date、Wall-clock Time、Zoned Schedule 或 Duration，并在契约中记录精度、时区、日历和空值语义。
+- 跨系统传输必须使用无歧义、版本化的机器格式；Instant 携带 UTC 或明确 offset，Zoned Schedule 同时保留命名时区。
+- Local Date 不得隐式转换为午夜 Instant；Wall-clock Time 转换为 Instant 时必须提供时区和夏令时歧义策略。
+- 解析必须使用明确格式，不依赖浏览器 locale、宿主默认时区或实现相关的字符串猜测。
+- 比较、排序、筛选和计算必须使用规范化原始值，不得使用本地化显示文本。
+- 时间单位必须显式，秒、毫秒、微秒等不得依靠数值大小猜测。
+- 当前时间必须经可替换 Clock 获取；测试必须固定 Clock、时区和 locale，并覆盖月末、闰日、夏令时跳变及重复时刻。
+- 经过时长和超时测量必须使用不受系统时钟回拨影响的单调时间来源；业务日历计算使用明确规则。
+
+## MUST NOT
+
+- MUST NOT 用字符串截断、手工 offset 加减或固定 24 小时替代日历/时区运算。
+- MUST NOT 把无时区值静默解释为浏览器本地时区或 UTC。
+- MUST NOT 混用秒与毫秒、日期与时间点、经过时长与日历天数。
+- MUST NOT 将格式化后的日期时间用于计算、排序、缓存键或接口提交。
+- MUST NOT 在业务代码中直接读取不可控的系统当前时间。
+
+## SHOULD
+
+- SHOULD 使用能区分日期、时间点、带时区时间和 Duration 的标准平台 API 或经评审的时间库。
+- SHOULD 在用户界面明确展示与用户预期不同的业务时区。
+- SHOULD 在日志和审计中同时记录规范化时间、时区上下文和事件顺序标识。
+
+## Contract
+
+```text
+Field, TemporalKind, MachineFormat, Precision, TimeZone,
+Calendar, AmbiguityPolicy, DisplayZone, ClockSource, TestMatrix
+```
+
+## Checklist
+
+- [ ] 时间字段类型和单位无歧义。
+- [ ] 日期、时间点和带时区计划未混用。
+- [ ] 解析、排序和计算不依赖显示文本或宿主默认值。
+- [ ] Clock 可替换，边界日期和夏令时已有测试。
+
+## Examples
+
+### 内容示例，可删除
+
+审计事件保存为 Instant，生日保存为 Local Date，跨地区会议保存为带命名时区的 Zoned Schedule；三者使用不同类型和 adapter。
+
+## Anti-patterns
+
+把 `YYYY-MM-DD` 直接构造成时间点，再用浏览器默认时区显示，导致部分地区日期前移或后移一天。
+
+## Ownership
+
+领域 Owner 定义业务时间语义，接口 Owner 定义传输格式，前端平台 Owner 维护 Clock、解析和格式化能力。
+
+## Change Policy
+
+改变时间类型、精度、时区或序列化格式属于契约变更，必须迁移数据、缓存、测试和调用方，并同步 `universal:data-model-protocol` 与 `universal:internationalization-protocol`。

package/seeds/specs/hard/frontend/44-privacy-data-lifecycle-protocol.md

@@ -0,0 +1,87 @@
+---
+seed_source: pomaster/components/frontend-hard-spec/assets/universal/44-privacy-data-lifecycle-protocol.md
+seed_source_sha256: 5b3472bba296c1bb437c3ce41e1c937b636605e39b78cf06747d1010e46ba08e
+seed_version: B6B-2
+lane: frontend
+status: CURRENT
+authority_scope: mixed_required_and_advisory
+applies_to: [frontend]
+related_evidence_specs: []
+related_tools: []
+---
+
+# 44 隐私与客户端数据生命周期协议
+
+## Scope
+
+P0。约束个人、敏感和可关联数据在前端的收集、访问、传输、存储、复制、第三方共享、保留、撤回与清理。
+
+## Non-Scope
+
+不替代适用法律、组织隐私政策、后端数据治理或安全控制；安全负责防止未授权访问，隐私还负责数据是否必要以及应保留多久。
+
+## Terms
+
+- Data Purpose：收集或处理数据的明确用户/业务目的。
+- Data Minimization：仅处理实现已批准目的所需的最少数据。
+- User Control：同意、拒绝、撤回、删除或选择数据范围的有效机制。
+- Privacy Boundary：数据进入浏览器、第三方 SDK、剪贴板、通知、下载或监控系统的边界。
+
+## MUST
+
+- 每类受保护数据必须声明分类、目的、来源、接收方、客户端存储、保留期、删除触发器、用户控制和 Owner。
+- 请求、缓存、日志、埋点和第三方共享必须限制为已批准目的所需的最小字段和最小精度。
+- 浏览器存储、草稿、下载、剪贴板和通知必须遵守身份、租户、权限、过期和清理策略。
+- 注销、切换账号/租户、权限降低、目的撤回或数据过期时，必须停止相关处理并清理无权继续保留的数据与运行时资源。
+- 在政策要求同意或选择时，数据采集和第三方 SDK 必须在有效选择之后启用；撤回必须阻止后续采集且不得暗中回退。
+- 调用摄像头、麦克风、位置、剪贴板等敏感能力必须由可理解的用户动作触发，并提供拒绝后的安全路径。
+- 第三方脚本和数据目的必须有清单、字段白名单、目标域、保留策略、禁用方式和负责人。
+- 客户端持久化内容读取时必须视为不可信输入，并执行 schema、身份、权限和版本校验。
+
+## MUST NOT
+
+- MUST NOT 为“以后可能有用”收集、传输或长期保留额外数据。
+- MUST NOT 将敏感原值、搜索原文、文件内容或可识别信息放入 URL、日志、trace、埋点或未批准第三方载荷。
+- MUST NOT 将去标识化、哈希或内部 ID 自动视为匿名且无隐私风险。
+- MUST NOT 用客户端存储内容证明身份、权限或用户已同意。
+- MUST NOT 通过默认勾选、阻碍撤回或与目的无关的强制授权获取选择。
+
+## SHOULD
+
+- SHOULD 对新增浏览器权限、稳定标识符、第三方 SDK、跨域传输和持久化数据进行隐私评审。
+- SHOULD 为数据访问、导出、删除、撤回和过期清理建立可测试路径。
+- SHOULD 优先在本地或边界处聚合、截断或脱敏，避免传输不必要原值。
+
+## Contract
+
+```text
+DataClass, Purpose, MinimumFields, Source, Recipients[],
+ClientStorage, Retention, DeletionTriggers[], UserControl,
+ThirdPartyPolicy, Redaction, Owner, Evidence
+```
+
+## Checklist
+
+- [ ] 每类数据有明确目的和最小字段。
+- [ ] 存储、保留、撤回和清理可执行。
+- [ ] 第三方和遥测载荷已白名单化。
+- [ ] 身份、租户和权限变化不会遗留数据。
+- [ ] 敏感权限有拒绝和撤回路径。
+
+## Examples
+
+### 内容示例，可删除
+
+分析事件只发送批准的事件 key、粗粒度结果和随机 operation id；搜索原文、用户输入和业务数据不进入事件载荷，撤回后停止初始化 SDK。
+
+## Anti-patterns
+
+为了未来分析把完整表单、查询词和页面文本发送给第三方 SDK，并在用户退出后继续保留在本地缓存。
+
+## Ownership
+
+隐私/安全 Owner 定义政策，产品 Owner 证明目的与必要性，前端 Owner 实施边界、用户控制和清理，数据 Owner 审核接收与保留。
+
+## Change Policy
+
+新增目的、字段、接收方、持久化或保留期必须重新评审并更新用户控制；不得用功能发布记录替代隐私批准。同步检查 `universal:security-protocol`、`universal:analytics-protocol` 与 `universal:browser-storage-protocol`。

package/seeds/specs/hard/frontend/45-browser-storage-protocol.md

@@ -0,0 +1,87 @@
+---
+seed_source: pomaster/components/frontend-hard-spec/assets/universal/45-browser-storage-protocol.md
+seed_source_sha256: 01d0d3cb618519c94c939658526a97ad1df851a8f820a22a9b4595bef03cc2cb
+seed_version: B6B-2
+lane: frontend
+status: CURRENT
+authority_scope: mixed_required_and_advisory
+applies_to: [frontend]
+related_evidence_specs: []
+related_tools: []
+---
+
+# 45 浏览器存储协议
+
+## Scope
+
+P1。定义 Cookie、Web Storage、IndexedDB、Cache API 和其他客户端持久化的选择、隔离、校验、配额、迁移、一致性与清理。
+
+## Non-Scope
+
+不定义服务端数据库或 HTTP/CDN 缓存，不允许客户端存储替代后端权威状态、认证或鉴权。
+
+## Terms
+
+- Storage Class：存储介质及其可见范围、持久性和安全属性。
+- Isolation Key：用户、租户、组织、权限范围和数据版本等隔离维度。
+- Storage Schema：持久化数据的版本化结构。
+- Eviction：浏览器因策略、配额或用户操作删除数据。
+
+## MUST
+
+- 每个持久化项必须声明用途、Storage Class、Isolation Key、schema 版本、大小预算、过期时间、迁移/重置策略、清理触发器和 Owner。
+- 从浏览器存储读取的数据必须执行 schema、版本、身份、租户和权限校验；失败时保守重置，不得直接信任。
+- 必须处理不可用、隐私模式、配额不足、写入失败、被驱逐和数据损坏，并为关键流程提供非持久化降级路径。
+- 注销、切换账号/租户、权限变化和数据目的撤回必须清除或重新隔离相关数据。
+- 跨标签页共享的数据必须定义冲突、通知、版本和最终一致性策略；不得假设内存状态会自动同步。
+- IndexedDB 等版本化数据库必须处理升级阻塞、连接关闭、迁移失败和回滚/重置路径。
+- Service Worker 与 Cache API 必须限定作用域、版本化缓存、验证响应来源，并在发布和退出策略中清理过期内容。
+- 凭据类数据必须遵守 `universal:security-protocol`；可被脚本读取的存储不得持久化 session identifier、refresh token、secret 或等价凭据，除非存在经批准且有期限的安全例外。
+
+## MUST NOT
+
+- MUST NOT 使用客户端存储值证明身份、权限、价格、审批或其他权威业务事实。
+- MUST NOT 多个用户、租户或权限范围复用未隔离的 key、数据库或缓存条目。
+- MUST NOT 无限期持久化草稿、文件、接口响应或敏感偏好。
+- MUST NOT 在 schema 变化后静默读取旧结构并猜测字段语义。
+- MUST NOT 假设客户端存储可靠、保密、不会被修改或永不被驱逐。
+
+## SHOULD
+
+- SHOULD 只在明确需要跨刷新或跨会话时持久化，短生命周期状态优先留在内存。
+- SHOULD 提供存储占用、迁移失败和清理结果的安全诊断信息。
+- SHOULD 对大型或敏感持久化建立容量、性能和隐私测试。
+
+## Contract
+
+```text
+StorageId, Purpose, StorageClass, IsolationKeys[], SchemaVersion,
+SizeBudget, Expiry, Migration, ResetPolicy, EvictionFallback,
+CrossTabPolicy, CleanupTriggers[], Owner
+```
+
+## Checklist
+
+- [ ] 存储必要性和介质选择合理。
+- [ ] schema、身份、租户和权限均被校验。
+- [ ] 配额、驱逐、损坏和不可用有降级路径。
+- [ ] 跨标签页和版本迁移行为明确。
+- [ ] 注销和权限变化会安全清理。
+
+## Examples
+
+### 内容示例，可删除
+
+用户列偏好按用户、租户和 schema 版本隔离；读取失败或版本不兼容时恢复默认值，不影响核心查询和编辑流程。
+
+## Anti-patterns
+
+把 token、完整权限矩阵和接口响应长期写入 localStorage，所有账号共享同一 key，并把读取结果直接当作可信状态。
+
+## Ownership
+
+平台 Owner 维护存储适配和迁移机制，领域 Owner 定义数据必要性与隔离键，安全/隐私 Owner 审核敏感持久化。
+
+## Change Policy
+
+改变介质、key、schema、隔离或保留策略必须提供迁移、重置、回滚和受影响用户说明，并同步 `universal:state-management-protocol`、`universal:cache-protocol` 与 `universal:privacy-data-lifecycle-protocol`。