pomaster 0.4.0 → 0.5.1

package/seeds/specs/hard/backend/16-error-code-protocol.md

@@ -1,68 +0,0 @@
----
-seed_source: pomaster/components/backend-hard-spec/assets/universal/16-error-code-protocol.md
-seed_source_sha256: aa80ee60f7431e14859f61e563784e71b2002f35e220964170a779800fdde090
-seed_version: B6C
-lane: backend
-status: CURRENT
-authority_scope: mixed_required_and_advisory
-applies_to: [backend]
-related_evidence_specs: []
-related_tools: []
-legacy_id: backend:error-code-protocol
-criticality: standard
-injection_mode: triggered
-stages: [prepare, implement, check]
-triggers: [error-code, error-handling]
-requires: []
----
-
-# 错误码协议
-
-## Scope
-
-规范错误分类、稳定错误码、状态映射、字段错误、重试性与安全消息。
-
-## Non-Scope
-
-不负责日志采样、告警或业务规则本身。
-
-## Terms
-
-稳定错误码是调用方可依赖且不暴露内部实现的机器语义。
-
-## MUST
-
-- 失败必须映射到稳定 code、适当状态、可选字段错误、retryable 与 TraceId。
-
-## MUST NOT
-
-- 不得向调用方返回堆栈、SQL、secret 或不稳定内部异常文本。
-
-## SHOULD
-
-- 应区分认证、鉴权、未找到、冲突、校验、限流和服务失败。
-
-## Contract
-
-错误注册项必须包含语义、状态映射、消息边界、重试性和所有者。
-
-## Checklist
-
-- [ ] 新错误已验证客户端恢复、日志关联和兼容行为。
-
-## Examples
-
-- 乐观锁冲突返回稳定冲突 code，并明确客户端是否可重试。
-
-## Anti-patterns
-
-- 所有异常都返回 HTTP 200 或统一未知错误。
-
-## Ownership
-
-Backend 维护错误注册表，API 消费方按稳定语义处理。
-
-## Change Policy
-
-已发布错误码不得复用；废弃必须保留兼容说明。
-

package/seeds/specs/hard/backend/17-permission-authorization-protocol.md

@@ -1,68 +0,0 @@
----
-seed_source: pomaster/components/backend-hard-spec/assets/universal/17-permission-authorization-protocol.md
-seed_source_sha256: d85a431b682a3a7c3dd4a6ee1f67fc375b54edb4a8e7fe98d283103b64a6b41e
-seed_version: B6C
-lane: backend
-status: CURRENT
-authority_scope: mixed_required_and_advisory
-applies_to: [backend]
-related_evidence_specs: []
-related_tools: []
-legacy_id: backend:permission-authorization-protocol
-criticality: critical
-injection_mode: triggered
-stages: [prepare, implement, check]
-triggers: [authorization, tenant, data-scope]
-requires: []
----
-
-# 权限与鉴权协议
-
-## Scope
-
-规范操作权限、数据范围、租户隔离、资源归属和字段脱敏。
-
-## Non-Scope
-
-不替代认证机制、业务状态规则或隐私保留决策。
-
-## Terms
-
-数据范围是主体在当前租户、角色与资源关系下可访问的记录集合。
-
-## MUST
-
-- 每个受保护操作必须在服务端验证主体、操作、租户、数据范围和资源归属。
-
-## MUST NOT
-
-- 不得只依赖路由隐藏、按钮状态或客户端传入的租户与 owner。
-
-## SHOULD
-
-- 应采用集中策略并测试越权、跨租户、批量与导出场景。
-
-## Contract
-
-权限契约必须定义主体、资源、动作、范围、拒绝语义和审计。
-
-## Checklist
-
-- [ ] 单条、列表、搜索、批量、导入与导出均执行一致范围控制。
-
-## Examples
-
-- 查询在数据库条件中收紧租户与数据范围，而不是返回后再过滤。
-
-## Anti-patterns
-
-- 只检查角色名，不检查目标资源归属和字段敏感级别。
-
-## Ownership
-
-BP 定义业务权限语义，Backend 执行最终授权。
-
-## Change Policy
-
-扩大权限范围必须经过正式业务确认、安全评审和回归测试。
-

package/seeds/specs/hard/backend/18-database-schema-migration-protocol.md

@@ -1,68 +0,0 @@
----
-seed_source: pomaster/components/backend-hard-spec/assets/universal/18-database-schema-migration-protocol.md
-seed_source_sha256: e7d0b660673dc1978653c39c9efcc7ad7d9b2809c4a88040a6fcf74839bc82c0
-seed_version: B6C
-lane: backend
-status: CURRENT
-authority_scope: mixed_required_and_advisory
-applies_to: [backend]
-related_evidence_specs: []
-related_tools: []
-legacy_id: backend:database-schema-migration-protocol
-criticality: critical
-injection_mode: triggered
-stages: [prepare, implement, check, release]
-triggers: [database-schema, migration, data-repair]
-requires: []
----
-
-# 数据库 Schema 与迁移协议
-
-## Scope
-
-规范 table、column、type、约束、索引、migration、回滚和数据修复。
-
-## Non-Scope
-
-不规定具体数据库产品的语法或项目表名。
-
-## Terms
-
-迁移是受版本控制、顺序稳定且可验证的数据结构或数据变更。
-
-## MUST
-
-- 每次 schema 变化必须有前向迁移、兼容分析、验证和回退或 roll-forward 路径。
-
-## MUST NOT
-
-- 不得依赖 ORM 自动改表、手工生产操作或无记录脚本作为正式迁移。
-
-## SHOULD
-
-- 应采用 expand/migrate/contract，避免应用与数据库无法并行部署。
-
-## Contract
-
-迁移记录必须包含对象、影响数据、锁风险、顺序、验证、修复和恢复。
-
-## Checklist
-
-- [ ] 约束、索引、默认值、历史数据、备份与发布窗口已检查。
-
-## Examples
-
-- 先新增可空字段并双写，完成回填与读切换后再收紧约束。
-
-## Anti-patterns
-
-- 在同一步中删除旧字段并发布仍依赖它的应用版本。
-
-## Ownership
-
-数据 Owner 审批语义，Backend 维护 migration 与验证证据。
-
-## Change Policy
-
-已执行 migration 不得原地改写；修正必须追加新 migration。
-

package/seeds/specs/hard/backend/19-query-index-sql-protocol.md

@@ -1,68 +0,0 @@
----
-seed_source: pomaster/components/backend-hard-spec/assets/universal/19-query-index-sql-protocol.md
-seed_source_sha256: 60a660730a82a4f911bc6c18d5f6808a320f722df27d397a4e4b13835111610d
-seed_version: B6C
-lane: backend
-status: CURRENT
-authority_scope: mixed_required_and_advisory
-applies_to: [backend]
-related_evidence_specs: []
-related_tools: []
-legacy_id: backend:query-index-sql-protocol
-criticality: standard
-injection_mode: triggered
-stages: [implement, check]
-triggers: [sql, query, index, pagination]
-requires: []
----
-
-# 查询、索引与 SQL 协议
-
-## Scope
-
-规范参数化 SQL、查询形态、分页、N+1、索引和执行计划证据。
-
-## Non-Scope
-
-不规定具体数据库的固定索引或性能阈值。
-
-## Terms
-
-查询形态包括过滤、连接、排序、分页、聚合与预期数据规模。
-
-## MUST
-
-- SQL 必须参数化，并以真实查询形态验证结果、边界和执行计划。
-
-## MUST NOT
-
-- 不得用字符串拼接构造不可信 SQL 或无界读取大结果集。
-
-## SHOULD
-
-- 应让索引服务于已知查询，并记录写放大与存储取舍。
-
-## Contract
-
-关键查询必须记录输入、排序稳定性、分页语义、索引和验证数据规模。
-
-## Checklist
-
-- [ ] 空结果、重复排序键、深分页、N+1 与慢查询已检查。
-
-## Examples
-
-- 游标分页包含稳定唯一排序键并验证并发写入下的行为。
-
-## Anti-patterns
-
-- 仅凭列名添加索引，不检查选择性和实际执行计划。
-
-## Ownership
-
-查询维护者提供计划证据，数据 Owner 评审容量与一致性影响。
-
-## Change Policy
-
-索引删除或查询重写必须先验证所有已知消费者和回滚路径。
-

package/seeds/specs/hard/backend/20-transaction-boundary-protocol.md

@@ -1,68 +0,0 @@
----
-seed_source: pomaster/components/backend-hard-spec/assets/universal/20-transaction-boundary-protocol.md
-seed_source_sha256: 4c4634b71f1e07e9cae074f9790fa50b3425f0af71300ab2ac12e644b521eff4
-seed_version: B6C
-lane: backend
-status: CURRENT
-authority_scope: mixed_required_and_advisory
-applies_to: [backend]
-related_evidence_specs: []
-related_tools: []
-legacy_id: backend:transaction-boundary-protocol
-criticality: critical
-injection_mode: triggered
-stages: [prepare, implement, check]
-triggers: [transaction]
-requires: []
----
-
-# 事务边界协议
-
-## Scope
-
-规范事务所有者、边界、隔离、传播、重试、补偿与外部调用。
-
-## Non-Scope
-
-不替代业务不变量、锁选择或数据库产品细节。
-
-## Terms
-
-事务边界是需要原子提交或一致失败的一组本地持久化操作。
-
-## MUST
-
-- 写流程必须明确事务入口、隔离、传播、失败、重试和提交后动作。
-
-## MUST NOT
-
-- 不得在长事务中执行无界网络调用、用户等待或不可控批处理。
-
-## SHOULD
-
-- 应缩短锁持有时间，并将外部副作用设计为可重试或可补偿。
-
-## Contract
-
-事务设计必须列出读写集合、锁、唯一约束、外部调用和一致性证据。
-
-## Checklist
-
-- [ ] 异常、超时、重试、部分失败和提交后发布均已测试。
-
-## Examples
-
-- 本地事务写入 outbox，提交后由可靠发布器发送外部消息。
-
-## Anti-patterns
-
-- 通过扩大事务范围掩盖跨系统一致性设计缺失。
-
-## Ownership
-
-应用服务拥有事务编排，Repository 提供明确持久化语义。
-
-## Change Policy
-
-边界或隔离变化必须复核并发、锁、性能和失败恢复。
-

package/seeds/specs/hard/backend/21-concurrency-locking-protocol.md

@@ -1,68 +0,0 @@
----
-seed_source: pomaster/components/backend-hard-spec/assets/universal/21-concurrency-locking-protocol.md
-seed_source_sha256: 6141612e1135cc67ccd9d47553ea5fa7b9c00e05b6e50706f8e117c80d3b8d95
-seed_version: B6C
-lane: backend
-status: CURRENT
-authority_scope: mixed_required_and_advisory
-applies_to: [backend]
-related_evidence_specs: []
-related_tools: []
-legacy_id: backend:concurrency-locking-protocol
-criticality: critical
-injection_mode: triggered
-stages: [prepare, implement, check]
-triggers: [concurrency, locking]
-requires: []
----
-
-# 并发与锁协议
-
-## Scope
-
-规范乐观锁、悲观锁、唯一约束、分布式锁和冲突响应。
-
-## Non-Scope
-
-不替代事务边界或业务状态规则。
-
-## Terms
-
-竞争窗口是多个执行者可基于同一旧状态作出冲突决策的时间范围。
-
-## MUST
-
-- 并发写必须明确竞争对象、原子条件、冲突结果、重试与最终一致性。
-
-## MUST NOT
-
-- 不得把进程内锁用于跨实例互斥或忽略锁超时与所有权。
-
-## SHOULD
-
-- 应优先使用数据库约束或带版本条件的原子更新保护不变量。
-
-## Contract
-
-锁设计必须记录粒度、顺序、超时、续租、释放、失败和可观测性。
-
-## Checklist
-
-- [ ] 重复请求、乱序、死锁、超时、崩溃和多实例场景已测试。
-
-## Examples
-
-- 以版本号条件更新并将零行更新映射为稳定冲突错误。
-
-## Anti-patterns
-
-- 先查询再无条件更新，并假设请求不会并发。
-
-## Ownership
-
-业务用例 Owner 定义冲突语义，持久化维护者验证原子性。
-
-## Change Policy
-
-锁策略变化必须重新评估事务、性能、恢复和兼容行为。
-

package/seeds/specs/hard/backend/22-idempotency-protocol.md

@@ -1,68 +0,0 @@
----
-seed_source: pomaster/components/backend-hard-spec/assets/universal/22-idempotency-protocol.md
-seed_source_sha256: c97d003622b9075f0c094ec5c5bfa950a977e18b2f4ce8ffc9bc014858e27670
-seed_version: B6C
-lane: backend
-status: CURRENT
-authority_scope: mixed_required_and_advisory
-applies_to: [backend]
-related_evidence_specs: []
-related_tools: []
-legacy_id: backend:idempotency-protocol
-criticality: critical
-injection_mode: triggered
-stages: [prepare, implement, check]
-triggers: [idempotency, callback, replay]
-requires: []
----
-
-# 幂等协议
-
-## Scope
-
-规范创建、提交、审批、导入、回调和任务重放语义。
-
-## Non-Scope
-
-不把所有读取或天然无副作用操作强制包装为幂等流程。
-
-## Terms
-
-幂等键标识同一业务意图，而不是单次网络请求。
-
-## MUST
-
-- 可重试写操作必须定义 key 范围、请求指纹、保留期、并发和响应重放。
-
-## MUST NOT
-
-- 不得仅依赖客户端防抖、按钮禁用或短时进程内缓存。
-
-## SHOULD
-
-- 应对相同 key 不同 payload 返回稳定冲突，而非重复执行。
-
-## Contract
-
-幂等记录必须包含主体、操作、key、指纹、状态、结果与过期语义。
-
-## Checklist
-
-- [ ] 并发首请求、失败重试、超时、重放和过期边界已测试。
-
-## Examples
-
-- 回调以供应方事件 ID 和租户范围去重，并原子保存处理结果。
-
-## Anti-patterns
-
-- 用当前时间生成幂等键，使每次重试都成为新操作。
-
-## Ownership
-
-API 或任务 Owner 定义业务意图，存储实现维护原子去重。
-
-## Change Policy
-
-key 格式或保留期变化必须处理旧记录和滚动发布兼容。
-

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

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

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

@@ -1,68 +0,0 @@
----
-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
-
-参数或状态变化必须兼容历史任务和进行中的执行。
-