pomaster 0.3.0 → 0.4.0

package/seeds/specs/hard/backend/13-privacy-data-lifecycle-protocol.md

@@ -0,0 +1,68 @@
+---
+seed_source: pomaster/components/backend-hard-spec/assets/universal/13-privacy-data-lifecycle-protocol.md
+seed_source_sha256: df20ccb85008f8744ea16db3ea64e54bdf9fd19d7aa3098c45dc44fff94c3d8d
+seed_version: B6C
+lane: backend
+status: CURRENT
+authority_scope: mixed_required_and_advisory
+applies_to: [backend]
+related_evidence_specs: []
+related_tools: []
+legacy_id: backend:privacy-data-lifecycle-protocol
+criticality: critical
+injection_mode: triggered
+stages: [prepare, implement, check, release]
+triggers: [sensitive-data, privacy, data-export]
+requires: []
+---
+
+# 隐私与数据生命周期协议
+
+## Scope
+
+规范数据最小化、分类、脱敏、保留、删除、导出、接收方与审计。
+
+## Non-Scope
+
+不替代一般安全控制或业务合法性确认。
+
+## Terms
+
+生命周期覆盖收集、传输、存储、使用、共享、导出、保留与删除。
+
+## MUST
+
+- 敏感数据必须有目的、来源、接收方、保留期、删除触发与访问控制。
+
+## MUST NOT
+
+- 不得因“以后可能有用”收集或无限期保留数据。
+
+## SHOULD
+
+- 应在非必要场景使用最小字段、脱敏值或不可逆标识。
+
+## Contract
+
+数据设计必须记录分类、处理目的、存储位置、流向、保留与删除证据。
+
+## Checklist
+
+- [ ] URL、日志、trace、缓存、导出和备份均已检查敏感数据。
+
+## Examples
+
+- 审计记录保存必要标识与操作事实，不复制完整敏感 payload。
+
+## Anti-patterns
+
+- 在测试样例、日志或分析事件中使用真实敏感数据。
+
+## Ownership
+
+数据 Owner 决定用途与保留，Backend 实施并证明技术控制。
+
+## Change Policy
+
+扩大处理范围或接收方必须重新评审目的、权限与保留规则。
+

package/seeds/specs/hard/backend/14-business-rules-state-protocol.md

@@ -0,0 +1,68 @@
+---
+seed_source: pomaster/components/backend-hard-spec/assets/universal/14-business-rules-state-protocol.md
+seed_source_sha256: fb255dd2331ac35e73a1ad222e4de4ec2f5fb3a09e675de0e1919d80022ac291
+seed_version: B6C
+lane: backend
+status: CURRENT
+authority_scope: mixed_required_and_advisory
+applies_to: [backend]
+related_evidence_specs: []
+related_tools: []
+legacy_id: backend:business-rules-state-protocol
+criticality: critical
+injection_mode: triggered
+stages: [prepare, implement, check]
+triggers: [business-rules, state-transition]
+requires: []
+---
+
+# 业务规则与状态协议
+
+## Scope
+
+规范服务端权威不变量、状态机、计算、校验和失败语义。
+
+## Non-Scope
+
+不发明 BP 未确认的业务规则、阈值或状态。
+
+## Terms
+
+不变量是在任何成功事务后都必须成立的业务条件。
+
+## MUST
+
+- 状态转移必须定义前置条件、权限、效果、失败码和并发行为。
+
+## MUST NOT
+
+- 不得只依赖前端禁用按钮或流程顺序维护业务不变量。
+
+## SHOULD
+
+- 应集中表达同一权威规则并覆盖边界与非法转移测试。
+
+## Contract
+
+规则设计必须绑定 BP 来源、输入、状态、输出、失败和证据。
+
+## Checklist
+
+- [ ] 不变量、状态、权限、事务与并发边界已对齐。
+
+## Examples
+
+- 审批操作在服务端校验当前状态与操作权限后原子更新。
+
+## Anti-patterns
+
+- 在多个 Controller 和 SQL 中复制略有差异的状态判断。
+
+## Ownership
+
+BP 拥有业务语义，Backend 拥有服务端一致实现。
+
+## Change Policy
+
+业务语义变化必须来自正式 delta，并同步状态迁移与兼容计划。
+

package/seeds/specs/hard/backend/15-data-model-protocol.md

@@ -0,0 +1,68 @@
+---
+seed_source: pomaster/components/backend-hard-spec/assets/universal/15-data-model-protocol.md
+seed_source_sha256: 21cdd88fac93c9dc834a51d62978b51453ca02eca68f223859aeca0ada99c3f2
+seed_version: B6C
+lane: backend
+status: CURRENT
+authority_scope: mixed_required_and_advisory
+applies_to: [backend]
+related_evidence_specs: []
+related_tools: []
+legacy_id: backend:data-model-protocol
+criticality: standard
+injection_mode: triggered
+stages: [prepare, implement, check]
+triggers: [data-model, dto, mapping]
+requires: []
+---
+
+# 数据模型协议
+
+## Scope
+
+规范 Command、DTO、Domain Model、Entity 与持久化模型的边界和映射。
+
+## Non-Scope
+
+不定义具体项目字段、表或业务枚举。
+
+## Terms
+
+边界模型是在特定层或契约中表达数据的稳定结构。
+
+## MUST
+
+- 每次转换必须明确字段来源、空值、默认值、精度、时间和枚举语义。
+
+## MUST NOT
+
+- 不得让 API DTO、ORM Entity 与领域模型无条件共用同一类型。
+
+## SHOULD
+
+- 应只在边界转换一次，并通过契约或 round-trip 测试验证。
+
+## Contract
+
+映射必须声明源、目标、必填性、丢失规则和失败行为。
+
+## Checklist
+
+- [ ] 新增字段已追踪到所有生产、转换、存储与消费边界。
+
+## Examples
+
+- API 字符串枚举在入口转换为受控领域值，未知值返回稳定错误。
+
+## Anti-patterns
+
+- 使用反射复制掩盖字段语义、精度或空值差异。
+
+## Ownership
+
+各边界 Owner 维护模型契约，映射实现者负责 round-trip 证据。
+
+## Change Policy
+
+模型变化必须评估 API、数据、消息和历史数据兼容性。
+

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

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

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

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

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

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

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

@@ -0,0 +1,68 @@
+---
+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 格式或保留期变化必须处理旧记录和滚动发布兼容。
+