pomaster 0.4.0 → 0.5.1

package/seeds/specs/hard/frontend/16-error-handling-protocol.md

@@ -1,79 +0,0 @@
----
-seed_source: pomaster/components/frontend-hard-spec/assets/universal/16-error-handling-protocol.md
-seed_source_sha256: 0c6adc425e01a003e1f3c83fcf51f1d287767c95a4da50c15f5f639d9104f07f
-seed_version: B6B-1
-lane: frontend
-status: CURRENT
-authority_scope: mixed_required_and_advisory
-applies_to: [frontend]
-related_evidence_specs: []
-related_tools: []
----
-
-# 16 错误处理协议
-
-## Scope
-
-P1。定义认证、权限、资源、冲突、校验、限流、服务、网络和部分失败的前端呈现与恢复。
-
-## Non-Scope
-
-不定义后端错误码本身，不替代监控采集和业务校验。
-
-## Terms
-
-- Field Error：可定位到字段/单元格的错误。
-- Recover Action：登录、刷新、重试、重载、联系管理员或解决冲突。
-- Error Boundary：隔离渲染失败的边界。
-
-## MUST
-
-- 将原始错误归一化为稳定 code、trace、fieldErrors、retryable 和 recoverAction。
-- 401、403、404、409、422、429、5xx 和网络错误分别处理。
-- 字段错误定位字段，部分失败提供逐项明细。
-- 分层设置错误边界，局部失败不得导致整页白屏。
-- 用户知道发生什么、能否恢复和下一步。
-
-## MUST NOT
-
-- MUST NOT 用一个 Toast 处理所有错误。
-- MUST NOT 吞掉字段错误、冲突或 TraceId。
-- MUST NOT 展示技术堆栈、敏感参数或原始 HTML。
-- MUST NOT 自动重试不安全 mutation。
-
-## SHOULD
-
-- SHOULD 区分页面错误、字段错误、后台任务和短暂反馈。
-- SHOULD 在错误恢复后刷新受影响数据。
-
-## Contract
-
-```text
-Error { status?, code, safeMessage, traceId?,
-fieldErrors?, retryable, recoverAction? }
-```
-
-## Checklist
-
-- [ ] 错误分类和位置正确。
-- [ ] 恢复动作可执行。
-- [ ] TraceId 可定位。
-- [ ] 敏感信息未泄露。
-
-## Examples
-
-### 内容示例，可删除
-
-409 保留本地编辑，提示比较最新版本，而不是自动覆盖。
-
-## Anti-patterns
-
-所有失败统一 Toast“操作失败”，字段输入被清空且无错误编号。
-
-## Ownership
-
-契约 Owner 定义错误码，平台 Owner 维护归一化，页面 Owner 负责上下文呈现。
-
-## Change Policy
-
-错误码或恢复语义变化必须同步契约、映射、文案、Mock、监控和测试。

package/seeds/specs/hard/frontend/17-permission-protocol.md

@@ -1,79 +0,0 @@
----
-seed_source: pomaster/components/frontend-hard-spec/assets/universal/17-permission-protocol.md
-seed_source_sha256: 3f51aeb30497c07a3b552c8f21ecff22730d276c85fd504fde16e9e17b622ec0
-seed_version: B6B-1
-lane: frontend
-status: CURRENT
-authority_scope: mixed_required_and_advisory
-applies_to: [frontend]
-related_evidence_specs: []
-related_tools: []
----
-
-# 17 权限协议
-
-## Scope
-
-P1。定义菜单、页面、按钮、字段、数据范围和接口权限的前端一致表现。
-
-## Non-Scope
-
-不替代后端鉴权，不允许前端扩大或计算权威数据权限。
-
-## Terms
-
-- Operation Permission：可执行某动作。
-- Field Permission：字段可见、脱敏、只读或编辑。
-- Data Scope：允许访问的数据集合。
-
-## MUST
-
-- 菜单、路由、按钮、字段和接口使用同一权限语义。
-- 直达 URL 仍经过页面权限守卫。
-- 字段权限明确可见、脱敏、只读和编辑策略。
-- 数据范围由后端过滤并影响查询、详情和导出。
-- 权限不足提供一致、可解释状态。
-
-## MUST NOT
-
-- MUST NOT 只隐藏菜单或按钮而省略后端鉴权。
-- MUST NOT 前端获取全量数据后自行过滤敏感内容。
-- MUST NOT 按角色名称硬编码权限。
-- MUST NOT 将 Feature Flag 当权限。
-
-## SHOULD
-
-- SHOULD 使用统一 gate/hook/component。
-- SHOULD 对禁用动作展示只读原因。
-
-## Contract
-
-```text
-PermissionCode, Resource, Action, FieldPolicy?,
-DataScope?, BackendEnforcement, DeniedPresentation
-```
-
-## Checklist
-
-- [ ] 菜单到接口一致。
-- [ ] URL 无法绕过。
-- [ ] 字段和数据范围安全。
-- [ ] 无权限状态可解释。
-
-## Examples
-
-### 内容示例，可删除
-
-无导出权限时入口按产品策略隐藏或禁用，后端导出接口仍拒绝请求。
-
-## Anti-patterns
-
-前端按 `role === 'admin'` 显示全部按钮，并认为无需后端校验。
-
-## Ownership
-
-业务/安全 Owner 定义权限，后端执行鉴权，前端平台维护统一呈现。
-
-## Change Policy
-
-权限码和数据范围变化必须同步菜单、路由、缓存、接口、测试和审计。

package/seeds/specs/hard/frontend/18-state-management-protocol.md

@@ -1,88 +0,0 @@
----
-seed_source: pomaster/components/frontend-hard-spec/assets/universal/18-state-management-protocol.md
-seed_source_sha256: 72445fcd0ac7e21ebea38a5f72849543f936c7a96eee54eb99330226acaaf400
-seed_version: B6B-1
-lane: frontend
-status: CURRENT
-authority_scope: mixed_required_and_advisory
-applies_to: [frontend]
-related_evidence_specs: []
-related_tools: []
----
-
-# 18 状态管理协议
-
-## Scope
-
-P1。定义 local、page、URL、global、server、form 和 persisted state 的归属与生命周期。
-
-## Non-Scope
-
-不指定状态库品牌，不替代缓存和路由协议。
-
-## Terms
-
-- Local State：单组件短生命周期状态。
-- Server State：远端权威数据及请求生命周期。
-- URL State：需分享、刷新或返回恢复的状态。
-- Persisted Preference：跨会话用户偏好。
-
-## MUST
-
-- 每个状态声明 owner、更新者、存储位置、生命周期和清理策略。
-- server state 由查询缓存层管理。
-- 可分享和可恢复状态进入 URL。
-- 全局 store 只保存稳定跨页面状态。
-- 用户、权限或范围切换时清除越权风险状态。
-- 表单区分 initial、current、dirty、errors、submitting 和 conflict。
-- 状态拥有的监听器、计时器、观察器、请求、流、连接、Worker 和对象 URL 必须声明释放时机，并在卸载、身份切换或能力关闭时清理。
-- 第三方 SDK 实例、DOM 节点、连接句柄等不可序列化资源必须保持为不透明运行时引用，不进入持久化、URL 或可序列化全局状态。
-- 持久化状态必须区分用户/租户/环境命名空间，并在登出、权限收缩或版本不兼容时失效或迁移。
-
-## MUST NOT
-
-- MUST NOT 将组件状态放入全局 store。
-- MUST NOT 复制 server state 到全局 store 手动同步。
-- MUST NOT 将敏感或未提交表单写入 URL。
-- MUST NOT 共享未隔离的页面状态。
-- MUST NOT 把认证凭据、敏感表单原值或第三方资源句柄写入通用持久化状态。
-- MUST NOT 让已取消请求、旧订阅或旧身份上下文的迟到结果继续写入当前状态。
-
-## SHOULD
-
-- SHOULD 让状态更新来源唯一且可追踪。
-- SHOULD 使用 schema/version 管理持久化状态。
-
-## Contract
-
-```text
-StateId, Category, Owner, Writer, Storage,
-Persistence, IsolationKey, CleanupTrigger
-```
-
-## Checklist
-
-- [ ] 状态分类正确。
-- [ ] writer 和生命周期明确。
-- [ ] URL/global 白名单遵守。
-- [ ] 切换身份可安全清理。
-- [ ] 运行时资源有释放时机，迟到结果不会污染新上下文。
-- [ ] 持久化命名空间、版本迁移和失效策略明确。
-
-## Examples
-
-### 内容示例，可删除
-
-分页筛选进入 URL，列表数据留在 server cache，抽屉开关留在页面状态。
-
-## Anti-patterns
-
-把所有列表、筛选、弹窗和表单都塞进一个全局 store。
-
-## Ownership
-
-平台 Owner 维护状态基础设施，页面/领域 Owner 负责具体状态归属。
-
-## Change Policy
-
-状态位置或持久化变化必须提供迁移、清理和兼容策略，尤其是用户隔离数据。

package/seeds/specs/hard/frontend/19-cache-protocol.md

@@ -1,79 +0,0 @@
----
-seed_source: pomaster/components/frontend-hard-spec/assets/universal/19-cache-protocol.md
-seed_source_sha256: 893d5651016233eec36333775441a935746fe1202c8924dc2edf753d61523daf
-seed_version: B6B-1
-lane: frontend
-status: CURRENT
-authority_scope: mixed_required_and_advisory
-applies_to: [frontend]
-related_evidence_specs: []
-related_tools: []
----
-
-# 19 缓存协议
-
-## Scope
-
-P1。定义字典、用户、权限、列表、详情、任务和偏好的缓存、隔离与失效。
-
-## Non-Scope
-
-不定义 HTTP/CDN 服务端缓存，不替代状态管理和接口契约。
-
-## Terms
-
-- Query Key：唯一描述结果集合的结构化键。
-- Stale Time：数据可视为新鲜的时间。
-- Invalidation：写操作后使依赖缓存失效。
-
-## MUST
-
-- 每个缓存声明 key、参数、身份/权限隔离、stale、保留和失效规则。
-- Query Key 包含所有影响结果的筛选和上下文。
-- 写操作定义依赖失效矩阵。
-- 用户、角色、组织和数据范围切换时清理风险缓存。
-- schema 变化时迁移或重置持久化偏好。
-
-## MUST NOT
-
-- MUST NOT 用同一 key 表示不同筛选或权限范围。
-- MUST NOT mutation 后只改视觉而不刷新依赖。
-- MUST NOT 长缓存实时敏感数据而无批准。
-- MUST NOT 将 server cache 再复制进全局 store。
-
-## SHOULD
-
-- SHOULD 使用结构化 key factory 和集中失效策略。
-- SHOULD 在后台刷新时保留可用旧数据并标识 stale。
-
-## Contract
-
-```text
-Resource, QueryKey, IsolationKeys[], StaleTime,
-Retention, RefetchTriggers[], MutationInvalidations[]
-```
-
-## Checklist
-
-- [ ] key 覆盖所有结果参数。
-- [ ] 身份与权限隔离安全。
-- [ ] mutation 失效完整。
-- [ ] schema 迁移明确。
-
-## Examples
-
-### 内容示例，可删除
-
-列表 key 同时包含用户数据范围、分页、筛选和排序；权限变化后整体清除。
-
-## Anti-patterns
-
-所有用户共用 `['entity-list']`，导致筛选串扰甚至越权复用。
-
-## Ownership
-
-平台 Owner 维护缓存工具，领域 Owner 定义数据依赖和实时性。
-
-## Change Policy
-
-Key 结构或持久化 schema 改变必须版本化并提供迁移/清理。

package/seeds/specs/hard/frontend/20-testing-protocol.md

@@ -1,88 +0,0 @@
----
-seed_source: pomaster/components/frontend-hard-spec/assets/universal/20-testing-protocol.md
-seed_source_sha256: 477dc049d1e1ec72898a07615655ee374924c7796a0210741e8c97474644a4d6
-seed_version: B6B-1
-lane: frontend
-status: CURRENT
-authority_scope: mixed_required_and_advisory
-applies_to: [frontend]
-related_evidence_specs: []
-related_tools: []
----
-
-# 20 测试协议
-
-## Scope
-
-P1。定义类型、单元、组件、集成、E2E、视觉、可访问性和性能测试边界。
-
-## Non-Scope
-
-不替代验收门禁、业务 UAT 或生产监控。
-
-## Terms
-
-- Risk-based Testing：按变更风险和影响面选择测试。
-- Contract Test：验证跨层 schema 和行为一致性。
-- Regression Set：受公共变更影响的代表性场景集合。
-
-## MUST
-
-- 公共函数/组件、复杂表单、关键流程、权限和错误态必须测试。
-- 页面覆盖 loading、empty、error、permission、normal 和大数据。
-- 公共变更扩大到全部受影响调用方。
-- 接口变化同步 contract、adapter、Mock 和页面测试。
-- 测试必须稳定、可重复并断言用户可观察行为。
-- 跨进程或跨信任边界的 API、存储、消息、配置和第三方 SDK 数据必须包含运行时 schema 失败用例。
-- 测试必须隔离并在结束时清理 cookie、浏览器存储、服务端测试数据、Mock、订阅和未完成异步任务。
-- 时间、时区、locale、随机数、网络延迟和失败模式必须可控制；并发与取消场景必须覆盖迟到结果不会污染新状态。
-
-## MUST NOT
-
-- MUST NOT 只测试成功场景。
-- MUST NOT 只靠人工点页面验收公共变更。
-- MUST NOT 为通过测试删除用例、降低断言或跳过风险状态。
-- MUST NOT 让测试依赖随机时间和不稳定外部数据。
-- MUST NOT 用固定 sleep 等待异步完成；应等待可观察状态、事件或受控时钟。
-- MUST NOT 用实现细节选择器作为 E2E 主定位方式；优先使用角色、可访问名称和稳定的用户语义。
-- MUST NOT 用自动重试掩盖 flakiness；重试后的通过仍必须可追踪并治理根因。
-
-## SHOULD
-
-- SHOULD 使用测试金字塔并保留少量高价值 E2E。
-- SHOULD 自动生成受影响测试清单。
-- SHOULD 在 CI 中固定时区、locale、依赖与浏览器版本，并对关键组合做显式矩阵验证。
-
-## Contract
-
-```text
-ChangeType, Unit[], Component[], Contract[], E2E[],
-Visual[], Accessibility[], Performance[], Evidence
-```
-
-## Checklist
-
-- [ ] 风险状态覆盖。
-- [ ] 公共调用方回归。
-- [ ] 契约与 Mock 同步。
-- [ ] 测试稳定可重复。
-- [ ] 外部状态已隔离和清理，异步任务无泄漏。
-- [ ] 时钟、时区、随机与网络条件可控制。
-
-## Examples
-
-### 内容示例，可删除
-
-表格壳变更同时测试列配置、固定列、横向滚动和不同表格类型。
-
-## Anti-patterns
-
-只测 API 200 和当前页面截图，忽略 403、409、空态和大数据。
-
-## Ownership
-
-实现者维护近层测试，QA 维护关键流程，公共能力 Owner 维护回归集。
-
-## Change Policy
-
-删除测试必须证明行为已删除或由等价测试覆盖；门禁测试降级需批准。

package/seeds/specs/hard/frontend/21-design-system-protocol.md

@@ -1,79 +0,0 @@
----
-seed_source: pomaster/components/frontend-hard-spec/assets/universal/21-design-system-protocol.md
-seed_source_sha256: 317d4086949eb7d26ea2465adc6521ba6ebb611dca0d2f32aec2c57a985be4f3
-seed_version: B6B-1
-lane: frontend
-status: CURRENT
-authority_scope: mixed_required_and_advisory
-applies_to: [frontend]
-related_evidence_specs: []
-related_tools: []
----
-
-# 21 设计系统协议
-
-## Scope
-
-P1。定义合法 UI 的 token、组件、视觉状态、栅格、密度和动效来源。
-
-## Non-Scope
-
-不决定具体品牌主题，不替代页面结构、可访问性和设计交付协议。
-
-## Terms
-
-- Design Token：可复用的设计决策变量。
-- Semantic Token：按用途而非具体值命名的 token。
-- Component Token：组件级语义变量。
-
-## MUST
-
-- 定义颜色、字体、间距、圆角、阴影、层级、断点、状态和动效 token。
-- UI 只能从 token 和批准组件取得视觉规则。
-- hover、active、focus、disabled、loading、empty、error 状态完整。
-- token 到代码和设计工具的映射有唯一来源。
-- 新视觉规则有复用语义和 Owner。
-
-## MUST NOT
-
-- MUST NOT 写孤立色值、魔法间距和临时阴影。
-- MUST NOT 用“看起来差不多”代替 token。
-- MUST NOT 在业务页面创建第二套视觉语言。
-- MUST NOT 用设计稿临时样式覆盖 Design Token。
-
-## SHOULD
-
-- SHOULD 使用语义 token 分离品牌值与组件用途。
-- SHOULD 自动校验 token 使用和弃用。
-
-## Contract
-
-```text
-TokenName, Layer, SemanticMeaning, ValueByTheme,
-AllowedConsumers, Deprecated?, Owner
-```
-
-## Checklist
-
-- [ ] 所有视觉值来自 token。
-- [ ] 状态与断点完整。
-- [ ] 设计和代码来源一致。
-- [ ] 新 token 有复用语义。
-
-## Examples
-
-### 内容示例，可删除
-
-组件使用 `color.action.primary`，而不是直接写品牌蓝十六进制值。
-
-## Anti-patterns
-
-页面根据设计截图手写近似颜色和 13px/17px 等孤立间距。
-
-## Ownership
-
-Design System Owner 与前端 Owner 共同维护，组件 Owner 消费但不私自改值。
-
-## Change Policy
-
-Token 改名/删除先 deprecated；值变化评估所有组件并执行视觉与对比度回归。

package/seeds/specs/hard/frontend/22-theme-protocol.md

@@ -1,79 +0,0 @@
----
-seed_source: pomaster/components/frontend-hard-spec/assets/universal/22-theme-protocol.md
-seed_source_sha256: b93ed272a0def5abc689fe66d939b87cacf6f38cce5d6278cfd5c94d1754b3ec
-seed_version: B6B-1
-lane: frontend
-status: CURRENT
-authority_scope: mixed_required_and_advisory
-applies_to: [frontend]
-related_evidence_specs: []
-related_tools: []
----
-
-# 22 主题协议
-
-## Scope
-
-P1。定义亮暗、品牌、紧凑、大字体等主题及 token 覆盖、切换和持久化。
-
-## Non-Scope
-
-不定义基础 token 语义，不允许主题改变业务含义。
-
-## Terms
-
-- Theme：一组完整 token 值。
-- Theme Mode：light/dark 或其他可选模式。
-- Theme Adapter：同步第三方组件、图表和 portal 的适配层。
-
-## MUST
-
-- 明确支持的主题列表和默认主题。
-- 所有主题覆盖完整语义 token，而非只换背景。
-- 表格、图表、弹层、焦点和状态随主题同步。
-- 切换、持久化、系统偏好和失败回退有策略。
-- 每个主题满足可访问性和视觉回归。
-
-## MUST NOT
-
-- MUST NOT 在业务组件写死应由主题控制的颜色。
-- MUST NOT 让局部页面自行换肤。
-- MUST NOT 只处理页面背景而遗漏 portal/图表。
-- MUST NOT 用主题切换表达权限或业务状态。
-
-## SHOULD
-
-- SHOULD 使用 CSS variables 或等价运行时 token。
-- SHOULD 避免主题切换闪烁和布局变化。
-
-## Contract
-
-```text
-ThemeId, TokenSet, Default, Persistence,
-SystemPreference, ThirdPartyAdapters[], Fallback
-```
-
-## Checklist
-
-- [ ] 支持范围和默认值明确。
-- [ ] token 覆盖完整。
-- [ ] 第三方与 portal 同步。
-- [ ] 对比度和回退通过。
-
-## Examples
-
-### 内容示例，可删除
-
-主题切换统一更新页面、弹窗、表格和图表 palette。
-
-## Anti-patterns
-
-仅给 body 加 dark class，而下拉、弹窗和图表仍使用亮色。
-
-## Ownership
-
-Design System Owner 维护主题 token，平台 Owner 维护切换，组件 Owner 负责兼容。
-
-## Change Policy
-
-新增主题必须完整覆盖和验收；删除主题需迁移用户偏好并提供回退。