pomaster 0.3.0 → 0.4.0

package/seeds/specs/hard/frontend/13-monetary-precision-protocol.md

@@ -0,0 +1,81 @@
+---
+seed_source: pomaster/components/frontend-hard-spec/assets/universal/13-monetary-precision-protocol.md
+seed_source_sha256: 4930246c7dfed2751d3a71d617a21e24b46b376131723451b39152582c7a3d4f
+seed_version: B6B-1
+lane: frontend
+status: CURRENT
+authority_scope: mixed_required_and_advisory
+applies_to: [frontend]
+related_evidence_specs: []
+related_tools: []
+---
+
+# 13 金额精度协议
+
+## Scope
+
+P1。定义金额、单价、成本、汇率、比例和汇总的传输、计算、比较、展示与导出精度。
+
+## Non-Scope
+
+不定义业务公式、税务政策、币种范围或最终结算口径。
+
+## Terms
+
+- Amount：十进制定点值。
+- Currency：正式币种标识。
+- Scale：小数位数量。
+- Rounding Mode/Stage：舍入方式与时点。
+
+## MUST
+
+- 金额声明 amount、currency、scale 和舍入规则。
+- 传输使用十进制字符串或无歧义最小单位整数。
+- 权威计算使用 Decimal/BigDecimal 等十进制能力。
+- 区分原始、计算、展示和导出值。
+- 汇总按正式顺序计算和舍入。
+- 百分比声明传输倍率。
+
+## MUST NOT
+
+- MUST NOT 使用二进制浮点执行正式金额累计、乘除和相等比较。
+- MUST NOT 用 `toFixed` 代替十进制计算。
+- MUST NOT 混合币种直接求和。
+- MUST NOT 页面、报表、导出各自决定精度。
+
+## SHOULD
+
+- SHOULD 使用统一 Money/Decimal 类型、parser 和 formatter。
+- SHOULD 测试负数、极值、尾数 5、汇总和跨币种边界。
+
+## Contract
+
+```text
+Money { amount: decimal-string, currency: string, scale: integer }
+Rule { calculationScale, displayScale, roundingMode, roundingStage }
+```
+
+## Checklist
+
+- [ ] amount/currency/scale/rounding 完整。
+- [ ] 未使用浮点做正式计算。
+- [ ] 展示、汇总和导出一致。
+- [ ] 比例和跨币种语义明确。
+
+## Examples
+
+### 内容示例，可删除
+
+保留接口金额字符串，通过统一 formatter 展示，不先转为浮点数。
+
+## Anti-patterns
+
+用 `parseFloat` 累加成本，再 `toFixed(2)` 生成正式报表。
+
+## Ownership
+
+业务/财务定义口径，后端负责权威计算，前端负责无损传输，QA 验证边界。
+
+## Change Policy
+
+精度、币种、舍入或比例语义变化属于破坏性契约变更，必须同步全链路。

package/seeds/specs/hard/frontend/14-data-model-protocol.md

@@ -0,0 +1,85 @@
+---
+seed_source: pomaster/components/frontend-hard-spec/assets/universal/14-data-model-protocol.md
+seed_source_sha256: 7d4e31ef04a1f57d88e982c01dabc22c421bafc850b7295a73d084ec3c6fc838
+seed_version: B6B-1
+lane: frontend
+status: CURRENT
+authority_scope: mixed_required_and_advisory
+applies_to: [frontend]
+related_evidence_specs: []
+related_tools: []
+---
+
+# 14 数据模型协议
+
+## Scope
+
+P1。定义 API DTO、Adapter、Domain Model、ViewModel、FormModel 和 RowModel 的分层。
+
+## Non-Scope
+
+不定义接口传输协议或具体业务公式，不允许模型层承担页面布局。
+
+## Terms
+
+- DTO：接口原始结构。
+- Adapter：边界转换函数。
+- Domain Model：稳定业务语义模型。
+- ViewModel：面向展示或交互的模型。
+
+## MUST
+
+- 使用 `DTO -> Adapter -> Domain Model -> View/Form/Row Model` 链路。
+- 明确类型命名、位置、Owner 和公开边界。
+- 空值、未知枚举、日期、金额和单位在边界统一处理。
+- API、浏览器存储、跨窗口消息、运行时配置和第三方 SDK 等外部数据必须在信任边界执行 schema 校验后再转换；失败时保守降级并产生安全监控。
+- opaque ID、超出 JavaScript safe integer 的整数和高精度数值必须使用不会静默丢失精度的传输与模型类型。
+- 后端字段变化优先只影响契约和 adapter。
+- adapter 有正常、空值、未知值和边界测试。
+
+## MUST NOT
+
+- MUST NOT 让 DTO 穿透公共组件、模板或列定义。
+- MUST NOT 在页面重复字段转换和兜底。
+- MUST NOT 使用万能对象代替类型。
+- MUST NOT 在模型转换中隐藏正式业务计算。
+- MUST NOT 用 TypeScript 类型、类型断言或生成类型替代运行时外部数据校验。
+- MUST NOT 把 opaque ID 或大整数转成可能丢失精度的 `number`。
+
+## SHOULD
+
+- SHOULD 使用 schema 校验外部数据。
+- SHOULD 为未知枚举保留安全兜底和监控。
+
+## Contract
+
+```text
+SourceDTO, RuntimeSchema, Adapter, DomainModel, ConsumerModel,
+NullPolicy, EnumPolicy, IdentifierPolicy, PrecisionPolicy, FormatPolicy, Owner
+```
+
+## Checklist
+
+- [ ] 模型层次明确。
+- [ ] 外部数据已校验转换。
+- [ ] 组件只消费稳定模型。
+- [ ] adapter 测试完整。
+- [ ] 外部数据校验失败和大整数/opaque ID 已覆盖。
+
+## Examples
+
+### 内容示例，可删除
+
+API 的 snake_case DTO 经 adapter 转成稳定 Domain Model，再生成表格 RowModel。
+
+## Anti-patterns
+
+模板直接访问后端字段并在多个单元格各自处理 null 和枚举。
+
+## Ownership
+
+API Owner 维护 DTO，领域 Owner 维护 Domain Model，前端模块 Owner 维护 adapter/ViewModel。
+
+## Change Policy
+
+模型字段变化必须说明兼容、迁移和受影响消费者；公共模型不得静默改语义。

package/seeds/specs/hard/frontend/15-request-api-protocol.md

@@ -0,0 +1,87 @@
+---
+seed_source: pomaster/components/frontend-hard-spec/assets/universal/15-request-api-protocol.md
+seed_source_sha256: b9489d69e35a19b8d5ba2442108190e7b99989ef471c8cf413d9e4e408ca2969
+seed_version: B6B-1
+lane: frontend
+status: CURRENT
+authority_scope: mixed_required_and_advisory
+applies_to: [frontend]
+related_evidence_specs: []
+related_tools: []
+---
+
+# 15 请求与 API 协议
+
+## Scope
+
+P1。定义正式契约进入前端后的请求封装、取消、重试、loading、错误归一化和 API 函数。
+
+## Non-Scope
+
+不定义后端接口本身，不负责页面错误文案和缓存业务规则。
+
+## Terms
+
+- HTTP Client：统一传输基础设施。
+- Domain API：面向业务语义的请求函数。
+- Request Context：认证、语言、trace、幂等等上下文。
+
+## MUST
+
+- 页面只调用封装的 Domain API。
+- HTTP Client 统一处理 base URL、认证、超时、取消、trace 和 envelope。
+- 请求函数使用稳定领域动词命名并有类型。
+- 查询可取消和丢弃过期响应。
+- mutation 明确幂等和重试边界。
+- 错误转换为统一结构。
+- 传输成功与业务成功必须分别判断；HTTP 非成功状态、契约解析失败、取消、超时、离线和业务错误不得混为一类。
+- 重试必须服从幂等性、服务端 `Retry-After` 或受控退避，并能取消；取消或已被替代的请求不得提示为用户错误。
+- 请求结果提交前必须验证身份、租户、权限、参数和请求版本，防止旧上下文结果写回。
+- endpoint、redirect 和 base URL 只能来自受控配置或契约，不得由不可信 URL 参数直接拼接。
+
+## MUST NOT
+
+- MUST NOT 在页面直接写 fetch/axios 或拼 endpoint。
+- MUST NOT 多处重复 token、错误码和重试逻辑。
+- MUST NOT 对非幂等 mutation 默认自动重试。
+- MUST NOT 让组件解析原始响应 envelope。
+- MUST NOT 把“网络在线”提示当成请求成功证明，或假设 HTTP 404/500 一定以 Promise rejection 表现。
+
+## SHOULD
+
+- SHOULD 通过生成客户端或 typed adapter 对接正式契约。
+- SHOULD 让 loading 来源唯一，避免重复状态。
+
+## Contract
+
+```text
+FunctionName, InputType, OutputType, ErrorType,
+StatusPolicy, Cancellation, Retry, RetryAfter, Idempotency,
+ContextVersion, LateResultGuard, Trace
+```
+
+## Checklist
+
+- [ ] 页面只使用 Domain API。
+- [ ] 类型和错误统一。
+- [ ] 取消、重试、幂等明确。
+- [ ] 无重复 loading/认证逻辑。
+- [ ] 状态判断、旧结果防护和 endpoint 来源明确。
+
+## Examples
+
+### 内容示例，可删除
+
+`getEntityList(query, signal)` 返回稳定分页模型，调用方不认识 endpoint 和 envelope。
+
+## Anti-patterns
+
+每个页面各自创建请求实例、刷新 token 并比较 message。
+
+## Ownership
+
+平台 Owner 维护 HTTP Client，领域 Owner 维护 Domain API，契约 Owner 维护类型来源。
+
+## Change Policy
+
+客户端公共行为变化必须评估全部请求；函数破坏性变化提供迁移和弃用期。

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

@@ -0,0 +1,79 @@
+---
+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

@@ -0,0 +1,79 @@
+---
+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

@@ -0,0 +1,88 @@
+---
+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

@@ -0,0 +1,79 @@
+---
+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

@@ -0,0 +1,88 @@
+---
+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
+
+删除测试必须证明行为已删除或由等价测试覆盖；门禁测试降级需批准。