pomaster 0.3.0 → 0.4.0

package/seeds/specs/hard/backend/23-cache-redis-consistency-protocol.md

@@ -0,0 +1,68 @@
+---
+seed_source: pomaster/components/backend-hard-spec/assets/universal/23-cache-redis-consistency-protocol.md
+seed_source_sha256: 073da5821658adfc0580798873fde95c49dc9d993a63949b3b1543a9c0e18a11
+seed_version: B6C
+lane: backend
+status: CURRENT
+authority_scope: mixed_required_and_advisory
+applies_to: [backend]
+related_evidence_specs: []
+related_tools: []
+legacy_id: backend:cache-redis-consistency-protocol
+criticality: critical
+injection_mode: triggered
+stages: [prepare, implement, check, release]
+triggers: [redis, cache]
+requires: []
+---
+
+# 缓存与 Redis 一致性协议
+
+## Scope
+
+规范 key、value schema、TTL、序列化、失效、一致性、防击穿与降级。
+
+## Non-Scope
+
+不默认指定 Redis，也不规定项目 key 与 TTL 数值。
+
+## Terms
+
+权威数据源是在冲突时决定业务事实的持久来源。
+
+## MUST
+
+- 缓存必须定义 key 维度、权限隔离、TTL、更新失效、故障和恢复行为。
+
+## MUST NOT
+
+- 不得让不同租户、权限、过滤或版本的数据共享含混 key。
+
+## SHOULD
+
+- 应设计缓存穿透、击穿、雪崩和热 key 的限制与观测。
+
+## Contract
+
+缓存契约必须包含权威源、schema 版本、读写顺序、陈旧容忍和降级。
+
+## Checklist
+
+- [ ] DB 提交、缓存失败、并发更新、淘汰和重建已测试。
+
+## Examples
+
+- 写库提交后删除版本化缓存，读路径在 miss 时受控回源。
+
+## Anti-patterns
+
+- 先写缓存再写数据库且没有补偿或一致性说明。
+
+## Ownership
+
+数据 Owner 定义一致性，缓存维护者提供失效与恢复证据。
+
+## Change Policy
+
+value schema 或 key 变化必须版本化并规划旧数据清理。
+

package/seeds/specs/hard/backend/24-external-integration-resilience-protocol.md

@@ -0,0 +1,68 @@
+---
+seed_source: pomaster/components/backend-hard-spec/assets/universal/24-external-integration-resilience-protocol.md
+seed_source_sha256: e6b0626c9169e9126319bd08ee5d5bdbe38421cfa175509524145aee30ff539a
+seed_version: B6C
+lane: backend
+status: CURRENT
+authority_scope: mixed_required_and_advisory
+applies_to: [backend]
+related_evidence_specs: []
+related_tools: []
+legacy_id: backend:external-integration-resilience-protocol
+criticality: critical
+injection_mode: triggered
+stages: [prepare, implement, check, release]
+triggers: [external-integration, resilience]
+requires: []
+---
+
+# 外部集成与韧性协议
+
+## Scope
+
+规范外部契约、超时、重试、熔断、补偿、对账和供应方故障。
+
+## Non-Scope
+
+不发明供应方 SLA、字段或错误语义。
+
+## Terms
+
+补偿用于处理无法由单一原子事务覆盖的已发生副作用。
+
+## MUST
+
+- 每个外部调用必须定义超时、重试条件、幂等、失败映射和恢复路径。
+
+## MUST NOT
+
+- 不得无限重试、重试非幂等操作或在事务内执行无界调用。
+
+## SHOULD
+
+- 应采用隔离、熔断、限流、降级与对账控制故障扩散。
+
+## Contract
+
+集成契约必须记录版本、认证、请求响应、错误、限额、追踪与所有者。
+
+## Checklist
+
+- [ ] 超时、限流、部分失败、重复响应和供应方中断已测试。
+
+## Examples
+
+- 写入本地意图后异步调用供应方，并通过状态机与对账收敛。
+
+## Anti-patterns
+
+- 捕获外部异常后记录日志并返回业务成功。
+
+## Ownership
+
+集成 Owner 维护供应方契约，业务 Owner 决定降级与补偿语义。
+
+## Change Policy
+
+供应方版本或认证变化必须经过兼容窗口和演练。
+

package/seeds/specs/hard/backend/25-async-job-scheduler-protocol.md

@@ -0,0 +1,68 @@
+---
+seed_source: pomaster/components/backend-hard-spec/assets/universal/25-async-job-scheduler-protocol.md
+seed_source_sha256: 36af3b4466b4e617a9c552a404d98ab74604752b7410e15756d7f132394fb980
+seed_version: B6C
+lane: backend
+status: CURRENT
+authority_scope: mixed_required_and_advisory
+applies_to: [backend]
+related_evidence_specs: []
+related_tools: []
+legacy_id: backend:async-job-scheduler-protocol
+criticality: standard
+injection_mode: triggered
+stages: [prepare, implement, check, release]
+triggers: [async-job, scheduler, import-export]
+requires: []
+---
+
+# 异步任务与调度协议
+
+## Scope
+
+规范 Job 生命周期、进度、取消、重试、调度锁、结果与保留。
+
+## Non-Scope
+
+不绑定具体调度器、队列或批处理框架。
+
+## Terms
+
+Job instance 是由稳定业务参数标识的一次可追踪执行意图。
+
+## MUST
+
+- 任务必须定义身份、状态、幂等、重试、取消、超时和结果访问。
+
+## MUST NOT
+
+- 不得用固定 sleep、无主线程或无状态记录的后台执行承载关键任务。
+
+## SHOULD
+
+- 应支持进度、心跳、并发限制、失败恢复和过期清理。
+
+## Contract
+
+任务契约必须包含触发源、参数、状态机、输出、错误、保留和权限。
+
+## Checklist
+
+- [ ] 重复触发、节点崩溃、接管、取消、重跑与过期已测试。
+
+## Examples
+
+- 导出任务返回 job ID，调用方查询状态并从受权地址下载结果。
+
+## Anti-patterns
+
+- 调度表达式重叠时并发执行同一不可重入任务。
+
+## Ownership
+
+任务 Owner 定义生命周期，运行平台提供调度与执行证据。
+
+## Change Policy
+
+参数或状态变化必须兼容历史任务和进行中的执行。
+

package/seeds/specs/hard/backend/26-engineering-tooling-protocol.md

@@ -0,0 +1,68 @@
+---
+seed_source: pomaster/components/backend-hard-spec/assets/universal/26-engineering-tooling-protocol.md
+seed_source_sha256: b0fcecee17a3acdb11f59f065ae7cac269cc292e999dd39444e5293565d38fe1
+seed_version: B6C
+lane: backend
+status: CURRENT
+authority_scope: mixed_required_and_advisory
+applies_to: [backend]
+related_evidence_specs: []
+related_tools: []
+legacy_id: backend:engineering-tooling-protocol
+criticality: standard
+injection_mode: triggered
+stages: [prepare, implement, check]
+triggers: [build, tooling, ci]
+requires: []
+---
+
+# 工程工具协议
+
+## Scope
+
+规范构建、静态检查、生成产物、CI、版本固定、ADR 与可复现性。
+
+## Non-Scope
+
+不规定所有项目使用同一构建工具。
+
+## Terms
+
+可复现构建是从受控输入得到可核对产物的过程。
+
+## MUST
+
+- 运行时、构建工具、依赖锁定和质量命令必须在仓库或受控环境中可发现。
+
+## MUST NOT
+
+- 不得手工修改生成产物或让本地与 CI 使用不一致的门禁。
+
+## SHOULD
+
+- 应自动校验生成代码、契约、migration、依赖和容器配置漂移。
+
+## Contract
+
+工具链记录必须包含版本来源、入口命令、输入、输出和失败门禁。
+
+## Checklist
+
+- [ ] 干净环境可完成构建、测试和静态检查。
+
+## Examples
+
+- CI 重新生成 OpenAPI 产物并拒绝未提交差异。
+
+## Anti-patterns
+
+- 依赖开发机全局工具或未记录的 IDE 操作。
+
+## Ownership
+
+平台维护者维护工具链，模块维护者确保项目命令持续可运行。
+
+## Change Policy
+
+工具升级必须验证兼容、锁文件、生成差异和回退。
+

package/seeds/specs/hard/backend/27-dependency-supply-chain-protocol.md

@@ -0,0 +1,68 @@
+---
+seed_source: pomaster/components/backend-hard-spec/assets/universal/27-dependency-supply-chain-protocol.md
+seed_source_sha256: 7e0817507039ab5f633ff4cb7eb3590d8755a547b8db91867f92bc702a64ddfe
+seed_version: B6C
+lane: backend
+status: CURRENT
+authority_scope: mixed_required_and_advisory
+applies_to: [backend]
+related_evidence_specs: []
+related_tools: []
+legacy_id: backend:dependency-supply-chain-protocol
+criticality: critical
+injection_mode: triggered
+stages: [prepare, implement, check, release]
+triggers: [dependency, supply-chain]
+requires: []
+---
+
+# 依赖与供应链协议
+
+## Scope
+
+规范依赖准入、版本、漏洞、许可证、来源、锁文件和构建供应链。
+
+## Non-Scope
+
+不规定具体语言的包管理器命令。
+
+## Terms
+
+直接依赖由项目显式声明，传递依赖由解析图间接引入。
+
+## MUST
+
+- 新增或升级依赖必须验证必要性、来源、版本、许可证、漏洞和维护状态。
+
+## MUST NOT
+
+- 不得从不可信源下载执行代码或忽略锁文件与校验差异。
+
+## SHOULD
+
+- 应减少重复能力、限制依赖范围并生成可追溯物料清单。
+
+## Contract
+
+依赖变更必须记录原因、影响图、风险、测试、生成差异和回退。
+
+## Checklist
+
+- [ ] 直接与传递依赖、插件、镜像和构建脚本均已审计。
+
+## Examples
+
+- 安全升级同时验证 API 兼容、配置变化和运行回归。
+
+## Anti-patterns
+
+- 为一个简单函数引入高权限且维护不明的大型依赖。
+
+## Ownership
+
+依赖引入者负责评审，安全与平台角色维护阻断策略。
+
+## Change Policy
+
+紧急漏洞例外必须限时、可追踪并安排后续完整验证。
+

package/seeds/specs/hard/backend/28-testing-protocol.md

@@ -0,0 +1,68 @@
+---
+seed_source: pomaster/components/backend-hard-spec/assets/universal/28-testing-protocol.md
+seed_source_sha256: f5df73dd7bec4ccf4132c3d7a9918a6f1cb0dd9682aa17956cb24446aa406ad7
+seed_version: B6C
+lane: backend
+status: CURRENT
+authority_scope: mixed_required_and_advisory
+applies_to: [backend]
+related_evidence_specs: []
+related_tools: []
+legacy_id: backend:testing-protocol
+criticality: critical
+injection_mode: triggered
+stages: [prepare, check, release]
+triggers: [testing, acceptance]
+requires: []
+---
+
+# 测试协议
+
+## Scope
+
+规范单元、API、集成、契约、迁移、并发、安全、性能与故障测试。
+
+## Non-Scope
+
+不规定统一覆盖率阈值或替代验收证据协议。
+
+## Terms
+
+测试层级按需要隔离的边界与要证明的风险划分。
+
+## MUST
+
+- 测试计划必须覆盖变更行为、边界、失败、兼容和高风险交互。
+
+## MUST NOT
+
+- 不得用固定 sleep、共享脏数据或只测成功路径获得虚假稳定性。
+
+## SHOULD
+
+- 应控制时间、随机、网络和外部依赖，并保留失败诊断信息。
+
+## Contract
+
+测试证据必须包含范围、环境、命令、结果、失败和未覆盖风险。
+
+## Checklist
+
+- [ ] API、DB、事务、并发、幂等、缓存、安全和回滚按影响选择。
+
+## Examples
+
+- migration 在真实数据库版本上验证前向、兼容与恢复。
+
+## Anti-patterns
+
+- Mock 掉所有边界后声称集成行为已验证。
+
+## Ownership
+
+实现者维护变更测试，测试与评审角色检查风险覆盖。
+
+## Change Policy
+
+删除或放宽测试必须说明替代证据和风险审批。
+

package/seeds/specs/hard/backend/29-observability-logging-tracing-protocol.md

@@ -0,0 +1,68 @@
+---
+seed_source: pomaster/components/backend-hard-spec/assets/universal/29-observability-logging-tracing-protocol.md
+seed_source_sha256: e871f5d7d1e9fe68956881877baba94f376a5539753441853f8cfa12939f5ebd
+seed_version: B6C
+lane: backend
+status: CURRENT
+authority_scope: mixed_required_and_advisory
+applies_to: [backend]
+related_evidence_specs: []
+related_tools: []
+legacy_id: backend:observability-logging-tracing-protocol
+criticality: standard
+injection_mode: triggered
+stages: [implement, check, release]
+triggers: [observability, logging, tracing]
+requires: []
+---
+
+# 可观测性、日志与追踪协议
+
+## Scope
+
+规范日志、指标、TraceId、审计、告警和事故诊断证据。
+
+## Non-Scope
+
+不替代错误码、隐私、安全或具体监控平台配置。
+
+## Terms
+
+可观测信号包括结构化日志、指标、trace、审计和健康状态。
+
+## MUST
+
+- 关键操作必须可关联版本、环境、主体、操作结果与 TraceId。
+
+## MUST NOT
+
+- 不得记录 token、密码、secret、完整敏感 payload 或无界高基数值。
+
+## SHOULD
+
+- 应为关键失败、延迟、容量和依赖建立可行动的指标与告警。
+
+## Contract
+
+信号设计必须定义 schema、级别、采样、保留、脱敏、Owner 与排障用途。
+
+## Checklist
+
+- [ ] 成功、失败、重试、降级和恢复均能通过信号关联。
+
+## Examples
+
+- 外部调用 trace 记录供应方、结果类和延迟，不记录认证凭据。
+
+## Anti-patterns
+
+- 只打印自由文本异常，无法按请求、版本或业务操作聚合。
+
+## Ownership
+
+服务维护者拥有诊断信号，运行角色维护告警与事故流程。
+
+## Change Policy
+
+信号 schema、采样或保留变化必须评估仪表盘、告警和隐私影响。
+

package/seeds/specs/hard/backend/30-performance-capacity-protocol.md

@@ -0,0 +1,68 @@
+---
+seed_source: pomaster/components/backend-hard-spec/assets/universal/30-performance-capacity-protocol.md
+seed_source_sha256: b575dd07e4bb6def646acb55c3d62d086a9fd12035b2ab359ec353bf443773e5
+seed_version: B6C
+lane: backend
+status: CURRENT
+authority_scope: mixed_required_and_advisory
+applies_to: [backend]
+related_evidence_specs: []
+related_tools: []
+legacy_id: backend:performance-capacity-protocol
+criticality: standard
+injection_mode: triggered
+stages: [prepare, check, release]
+triggers: [performance, capacity]
+requires: []
+---
+
+# 性能与容量协议
+
+## Scope
+
+规范延迟、吞吐、连接池、线程、批处理、背压、容量和压测证据。
+
+## Non-Scope
+
+不在 universal 中规定具体数值阈值或硬件规模。
+
+## Terms
+
+性能预算是由业务目标与运行环境确认的可测量约束。
+
+## MUST
+
+- 性能结论必须绑定负载模型、数据规模、环境、版本和统计口径。
+
+## MUST NOT
+
+- 不得用单次本地耗时、平均值或无代表性数据声称满足容量。
+
+## SHOULD
+
+- 应同时观察尾延迟、错误率、资源、排队、背压和依赖瓶颈。
+
+## Contract
+
+容量计划必须包含场景、预算、峰值、瓶颈、扩缩容和降级策略。
+
+## Checklist
+
+- [ ] 连接池、线程池、队列、批量、缓存与数据库联动已验证。
+
+## Examples
+
+- 在目标数据量和并发模型下报告 p95/p99、错误率与资源曲线。
+
+## Anti-patterns
+
+- 盲目增大池大小导致下游过载和更长排队。
+
+## Ownership
+
+业务 Owner 提供负载目标，Backend 与运行角色验证容量。
+
+## Change Policy
+
+预算或容量模型变化必须记录来源并重新运行代表性测试。
+

package/seeds/specs/hard/backend/31-runtime-deployment-protocol.md

@@ -0,0 +1,68 @@
+---
+seed_source: pomaster/components/backend-hard-spec/assets/universal/31-runtime-deployment-protocol.md
+seed_source_sha256: c791451de0be3aa0629fd562e2b43cc54066e4b10d786264fa7a333c561ef23a
+seed_version: B6C
+lane: backend
+status: CURRENT
+authority_scope: mixed_required_and_advisory
+applies_to: [backend]
+related_evidence_specs: []
+related_tools: []
+legacy_id: backend:runtime-deployment-protocol
+criticality: critical
+injection_mode: triggered
+stages: [prepare, implement, check, release]
+triggers: [runtime, deployment, configuration]
+requires: []
+---
+
+# 运行时与部署协议
+
+## Scope
+
+规范部署单元、实例、网络、TLS、代理头、健康检查、容器与运行时加固。
+
+## Non-Scope
+
+不默认选择 Nginx、Ingress、Tomcat、容器平台或具体 JVM 参数。
+
+## Terms
+
+部署拓扑描述入口链路、信任边界、运行单元、状态依赖与观测链路。
+
+## MUST
+
+- 必须记录真实打包、启动、端口、协议、实例、状态依赖和配置来源。
+
+## MUST NOT
+
+- 不得把开发机拓扑、默认端口或未验证容器行为当作生产事实。
+
+## SHOULD
+
+- 应支持优雅启动停止、健康检查、滚动发布、最小权限和故障隔离。
+
+## Contract
+
+部署设计必须包含入口、网络、信任、依赖、扩缩容、恢复和证据。
+
+## Checklist
+
+- [ ] 多实例、代理链、TLS、健康、配置、日志与回滚已演练。
+
+## Examples
+
+- 明确 Ingress 到 Service 再到应用的代理头与健康检查责任。
+
+## Anti-patterns
+
+- 应用无条件信任任意来源的 `X-Forwarded-*`。
+
+## Ownership
+
+Backend 拥有应用运行契约，平台角色拥有受控部署环境。
+
+## Change Policy
+
+拓扑或打包变化必须同步技术基线、发布方案与运行验证。
+

package/seeds/specs/hard/backend/32-release-versioning-rollback-protocol.md

@@ -0,0 +1,68 @@
+---
+seed_source: pomaster/components/backend-hard-spec/assets/universal/32-release-versioning-rollback-protocol.md
+seed_source_sha256: 26a6a23928fc24338f69fb34199ecdea5f654e21534a76ac53a7c0b78030b3c8
+seed_version: B6C
+lane: backend
+status: CURRENT
+authority_scope: mixed_required_and_advisory
+applies_to: [backend]
+related_evidence_specs: []
+related_tools: []
+legacy_id: backend:release-versioning-rollback-protocol
+criticality: critical
+injection_mode: triggered
+stages: [prepare, check, release]
+triggers: [release, rollback, versioning]
+requires: []
+---
+
+# 发布、版本与回滚协议
+
+## Scope
+
+规范版本、灰度、开关、发布记录、兼容窗口、回滚和数据库演进。
+
+## Non-Scope
+
+不替代具体平台操作手册或证据验收协议。
+
+## Terms
+
+可回退包括代码回滚、配置恢复、流量撤回和数据 roll-forward 的组合能力。
+
+## MUST
+
+- 发布前必须确认版本、依赖顺序、兼容、观测、停止条件和恢复路径。
+
+## MUST NOT
+
+- 不得在无法恢复数据或无监控信号时进行不可逆全量发布。
+
+## SHOULD
+
+- 应采用小批量灰度、可撤回开关和前后版本并行兼容。
+
+## Contract
+
+发布记录必须包含变更范围、产物 hash、步骤、门禁、指标、Owner 与结果。
+
+## Checklist
+
+- [ ] 应用、数据库、配置、消息、缓存与消费者版本已对齐。
+
+## Examples
+
+- 先发布兼容读写版本，完成数据迁移后再清理旧契约。
+
+## Anti-patterns
+
+- 把数据库回滚等同于逆向执行破坏性 migration。
+
+## Ownership
+
+发布责任人执行门禁，Backend 提供兼容与恢复证据。
+
+## Change Policy
+
+发布流程和阻断门禁变化必须通过演练与审计后生效。
+