pomaster 0.1.0 → 0.2.0

package/TRADEMARKS.md

@@ -3,10 +3,10 @@
 **POMaster** 名称、POMaster logo 及其他项目标识（合称「项目标识」）归项目版权所有者所有。
 
 - 版权与许可主体署名见根目录 [`LICENSE`](./LICENSE) 的 Required Notice 行：Copyright (c) 2026 River-Singer。
-- Owner 署名主体占位：TODO(Owner): 如以法人/其他主体持有商标，在此补全法定主体名称。
+- Owner 署名主体占位：Xu Jianyang: 如以法人/其他主体持有商标，在此补全法定主体名称。
 
 项目标识**不在** PolyForm Noncommercial 1.0.0 或商业授权协议的授权范围内；上述许可仅覆盖代码与文档等版权客体，不授予任何商标权。
 
 未经事先书面许可，不得在可能引起来源混淆的方式下使用项目标识。对 POMaster 原始代码的如实、指明来源的分发与描述性提及（nominative fair use）不在此限。
 
-**商标授权联系**：TODO(Owner): 填联系邮箱/渠道
+**商标授权联系**：allenxujianyang@outlook.com

package/catalog/archetypes/archetype.api.error.json

@@ -0,0 +1,55 @@
+{
+  "id": "ARCHETYPE.API.ERROR",
+  "kind": "archetype",
+  "layer": "ARCHETYPE",
+  "title_zh": "API 错误契约原型",
+  "summary_zh": "问题细节标准错误信封原型（PRD §44）：五个标准成员逐字（type/title/status/detail/instance）；业务码/链路追踪/字段级错误如实定位为扩展成员（客户端必须忽略未识别扩展——RFC 9457 §3.2 语义），以 application/problem+json 承载。",
+  "semantic": {
+    "responsibility": "错误响应的形状与语义单点：五个标准成员承载问题类型/概要/状态/详情/实例定位，扩展成员承载机器码与字段级错误——机器可判卷与人可读分层",
+    "when_to_use": "所有 HTTP 错误响应的信封（与 API 资源原型 error 绑定位配对）；前后端错误分型映射的契约源（前端错误目录的消费面对齐本原型）",
+    "when_not_to_use": "成功响应的包装信封（本原型只管错误面）；前端错误呈现分型本身（前端错误目录承载）"
+  },
+  "composition": {
+    "requires": [],
+    "optional": [],
+    "incompatible": []
+  },
+  "standard_members": {
+    "type": "URI 引用标识问题类型；建议绝对 URI；缺省 about:blank（注册类型：无超出 HTTP 状态码的额外语义）",
+    "title": "问题类型的简短人读概要——不应随出现次数变化（本地化除外）",
+    "status": "JSON 数字，仅建议性；必须与真实 HTTP 状态码一致（规范 MUST：Generators MUST use the same status code in the actual HTTP response）",
+    "detail": "本次出现的人读解释——消费者不应解析 detail 提取信息（扩展成员更适合机器消费）",
+    "instance": "标识本次问题具体发生处的 URI 引用；不可解引用时作不透明唯一标识"
+  },
+  "extensions": {
+    "members": [
+      "code",
+      "trace_id",
+      "field_errors"
+    ],
+    "positioning": "扩展成员（非标准成员）——规范 §3.2：问题类型定义可扩展附加成员，客户端 MUST ignore 未识别扩展",
+    "field_errors_note": "字段级错误建议对齐官方校验示例的 errors[] 数组形态（每条含 detail 与位置指针）"
+  },
+  "constraints": [
+    "status 必须与真实 HTTP 状态码一致（MUST）",
+    "media type 用 application/problem+json（canonical 形态）",
+    "引用现行规范 RFC 9457（已取代 RFC 7807——Appendix D 自述相对 7807 的变更）"
+  ],
+  "x-research-anchors": {
+    "note": "【研究纠偏·差异表 §44 行】PRD 把 code/trace_id/field_errors 与五成员并列列出，但三者不是标准成员而是扩展成员（客户端 MUST ignore 未识别扩展语义如实落位）；五成员逐字定义与 about:blank 注册类型为 RFC 9457 官方文本 2026-09-03 实抓",
+    "sources": [
+      {
+        "url": "https://www.rfc-editor.org/rfc/rfc9457.html",
+        "fetched": "2026-09-03"
+      },
+      {
+        "url": "doc/POMaster-vNext-PRD-v0.6.1-Engineering-Substrate-Archetype-Catalog.md §44",
+        "fetched": "2026-09-03"
+      },
+      {
+        "url": ".trellis/tasks/09-02-vnext-prd-v06-governed-substrate/research/backend-references.md 题 4",
+        "fetched": "2026-09-03"
+      }
+    ]
+  }
+}

package/catalog/archetypes/archetype.api.pagination.json

@@ -0,0 +1,68 @@
+{
+  "id": "ARCHETYPE.API.PAGINATION",
+  "kind": "archetype",
+  "layer": "ARCHETYPE",
+  "title_zh": "API 分页原型",
+  "summary_zh": "分页三批准模式原型（PRD §45 逐字闭包）：OFFSET/CURSOR/KEYSET 三选一；业界现行对照锚——Azure 服务端分页 value[]+nextLink、Stripe 对象 ID 游标、Relay Connections 不透明游标；Microsoft 原单一 REST 指南已废弃分拆（差异注记在场）。",
+  "semantic": {
+    "responsibility": "集合读取的分页契约单点：模式从批准闭包内选择、页大小有界、排序稳定、续页位形（has_more 或 next_link 二选一）固定",
+    "when_to_use": "任何列表/检索面的分页契约（与查询面原型配对）；深分页代价需要预先声明时（OFFSET 深翻页代价、KEYSET 需稳定排序键、CURSOR 需不透明令牌语义）",
+    "when_not_to_use": "一次性全量小数据（可不分页但须显式声明上界）；单体读取（API 资源原型 GET item 承载）"
+  },
+  "composition": {
+    "requires": [],
+    "optional": [],
+    "incompatible": []
+  },
+  "approved_modes": [
+    "OFFSET",
+    "CURSOR",
+    "KEYSET"
+  ],
+  "defaults": {
+    "page_size_bounded": true,
+    "stable_sort_required": true,
+    "continuation_field": "has_more 或 next_link 二选一的约定位",
+    "total_count": "不默认返回全量计数（Azure SHOULD NOT——全量计数可能代价高昂）"
+  },
+  "industry_anchors": {
+    "azure": "服务端分页：顶层 value[] + nextLink（绝对 URL、不透明续页令牌）；最后一页不返回 nextLink 字段（禁 null 值形态）；文档必须声明跨页可能跳过或重复；未支持查询参数必须报错",
+    "stripe": "cursor=对象 ID（按稳定序的 KEYSET——keyset-by-id 形态）；响应形 data[]+has_more；参数 limit/starting_after/ending_before；默认新→旧排序",
+    "relay": "GraphQL Relay Connections：Connection 必含 edges 与 pageInfo；Edge 必含 node 与 cursor；前向 first/after、后向 last/before；cursor 是不透明字符串"
+  },
+  "deprecation_note": "Microsoft 原单一 REST Guidelines 已废弃分拆（2026-09-03 实抓：原文档头部声明 deprecated，分拆为 Azure 与 Graph 两份现行指南）——引用时改引 Azure REST API Guidelines 并注明原文档已废弃",
+  "mode_note": "nextLink = CURSOR 的不透明服务端形态（opaque continuation token）——三批准模式闭包容纳业界现行形态（Azure/Stripe/Relay 对照均落回三模式之一）",
+  "constraints": [
+    "模式只能从三批准模式闭包内选择（PRD §45：项目只能选择批准模式）",
+    "最后一页禁返回 null 值 nextLink（Azure DO NOT 逐字）"
+  ],
+  "x-research-anchors": {
+    "note": "【差异注记·差异表 §45 行】三模式与业界现行实践兼容；Microsoft 现行形态是 opaque nextLink（CURSOR 的服务端形态），且原单一 REST Guidelines 已 deprecated 分拆为 Azure/Graph 两份——注记随物料在场。Azure/Stripe/Relay 三处词形为官方文档 2026-09-03 实抓",
+    "sources": [
+      {
+        "url": "https://github.com/microsoft/api-guidelines/blob/vNext/Guidelines.md",
+        "fetched": "2026-09-03"
+      },
+      {
+        "url": "https://raw.githubusercontent.com/microsoft/api-guidelines/vNext/azure/Guidelines.md",
+        "fetched": "2026-09-03"
+      },
+      {
+        "url": "https://docs.stripe.com/pagination",
+        "fetched": "2026-09-03"
+      },
+      {
+        "url": "https://relay.dev/graphql/connections.htm",
+        "fetched": "2026-09-03"
+      },
+      {
+        "url": "doc/POMaster-vNext-PRD-v0.6.1-Engineering-Substrate-Archetype-Catalog.md §45",
+        "fetched": "2026-09-03"
+      },
+      {
+        "url": ".trellis/tasks/09-02-vnext-prd-v06-governed-substrate/research/backend-references.md 题 4",
+        "fetched": "2026-09-03"
+      }
+    ]
+  }
+}

package/catalog/archetypes/archetype.api.resource.json

@@ -0,0 +1,45 @@
+{
+  "id": "ARCHETYPE.API.RESOURCE",
+  "kind": "archetype",
+  "layer": "ARCHETYPE",
+  "title_zh": "API 资源原型",
+  "summary_zh": "REST 风格标准端点五操作原型（PRD §43 逐字）：集合读取/单体读取/新建/单体修改/移除；授权/错误/分页/校验/兼容性五绑定必须配置——绑定缺失即契约不完整。",
+  "semantic": {
+    "responsibility": "单体实体的 HTTP 面形状基线：五操作闭包 + 五项强制绑定（authorization/error/pagination/validation/compatibility）——绑定面显式声明而非隐式约定",
+    "when_to_use": "实体需要标准 HTTP 面时（与后端标准写读面原型配对：操作闭包与其五操作一一对应）",
+    "when_not_to_use": "动词语义的业务命令面（配幂等命令原型）；事件订阅面（走发件箱事件原型的通道侧）"
+  },
+  "composition": {
+    "requires": [],
+    "optional": [],
+    "incompatible": []
+  },
+  "operations": [
+    "GET collection",
+    "GET item",
+    "POST item",
+    "PUT/PATCH item",
+    "DELETE item"
+  ],
+  "bindings": [
+    "authorization",
+    "error",
+    "pagination",
+    "validation",
+    "compatibility"
+  ],
+  "bindings_source": "PRD §43 逐字：必须绑定 authorization / error / pagination / validation / compatibility。",
+  "x-research-anchors": {
+    "note": "五操作与五绑定为 PRD §43 逐字（2026-09-03 对照 backend-references.md 题 4/差异表 §44-§45 行核实链）；error 绑定与 API 错误契约原型互链、pagination 绑定与分页原型互链",
+    "sources": [
+      {
+        "url": "doc/POMaster-vNext-PRD-v0.6.1-Engineering-Substrate-Archetype-Catalog.md §43",
+        "fetched": "2026-09-03"
+      },
+      {
+        "url": ".trellis/tasks/09-02-vnext-prd-v06-governed-substrate/research/backend-references.md 题 4",
+        "fetched": "2026-09-03"
+      }
+    ]
+  }
+}

package/catalog/archetypes/archetype.backend.approval_workflow.json

@@ -0,0 +1,63 @@
+{
+  "id": "ARCHETYPE.BACKEND.APPROVAL_WORKFLOW",
+  "kind": "archetype",
+  "layer": "ARCHETYPE",
+  "title_zh": "审批流原型",
+  "summary_zh": "标准审批状态机原型（PRD §31 逐字链）：草稿经递交事件进入已递交态，审批通过转通过、驳回转驳回；可选撤回/重开转移与多级会签变体。",
+  "semantic": {
+    "responsibility": "审批单生命周期与合法转移的单点声明：四态两事件为标准链，扩展转移（撤回/重开）与多级会签变体为可选档——合法转移之外无隐式状态",
+    "when_to_use": "需要人审的单据类写流程（请假/报销/变更单等）——状态闭包显式登记，审批动作留痕进审计",
+    "when_not_to_use": "无审批环节的直写流程（走事务性写原型）；自由流程编排诉求（本原型是闭包状态机，非流程引擎）"
+  },
+  "composition": {
+    "requires": [],
+    "optional": [],
+    "incompatible": []
+  },
+  "states": [
+    "DRAFT",
+    "SUBMITTED",
+    "APPROVED",
+    "REJECTED"
+  ],
+  "transitions": [
+    {
+      "from": "DRAFT",
+      "event": "SUBMIT",
+      "to": "SUBMITTED"
+    },
+    {
+      "from": "SUBMITTED",
+      "event": "APPROVE",
+      "to": "APPROVED"
+    },
+    {
+      "from": "SUBMITTED",
+      "event": "REJECT",
+      "to": "REJECTED"
+    }
+  ],
+  "optional": {
+    "transitions": [
+      "WITHDRAW",
+      "REOPEN"
+    ],
+    "variants": [
+      "MULTI_STAGE"
+    ],
+    "source": "PRD §31 逐字：可选：WITHDRAW / REOPEN / MULTI_STAGE。"
+  },
+  "x-research-anchors": {
+    "note": "四态两事件链与三可选位为 PRD §31 逐字（2026-09-03 对照 backend-references.md 差异表无冲突确认）；状态机闭包词形与前端状态机原型（STATE_ARCHETYPE 族）同构，本原型是后端单据域实例化",
+    "sources": [
+      {
+        "url": "doc/POMaster-vNext-PRD-v0.6.1-Engineering-Substrate-Archetype-Catalog.md §31",
+        "fetched": "2026-09-03"
+      },
+      {
+        "url": ".trellis/tasks/09-02-vnext-prd-v06-governed-substrate/research/backend-references.md",
+        "fetched": "2026-09-03"
+      }
+    ]
+  }
+}

package/catalog/archetypes/archetype.backend.audit.json

@@ -0,0 +1,44 @@
+{
+  "id": "ARCHETYPE.BACKEND.AUDIT",
+  "kind": "archetype",
+  "layer": "ARCHETYPE",
+  "title_zh": "审计原型",
+  "summary_zh": "审计两档原型（PRD §41 逐字）：基础档四字段（创建/更新的时间与操作人）；严格档六要素（变更前后值/操作类型/理由/操作者/链路追踪）——档位由数据分级决定而非默认全量。",
+  "semantic": {
+    "responsibility": "『谁在何时对什么做了什么改动』的可回答性：基础档回答元数据层，严格档回答逐字段前后值与理由链——两档显式分档，禁默认全量严格审计",
+    "when_to_use": "任何标准写面的默认基础档（对应后端标准写读面物料的审计默认档）；台账/财务/权限类数据升级严格档",
+    "when_not_to_use": "外部系统调用的遥测（走外部集成原型可观测位）；只读检索面"
+  },
+  "composition": {
+    "requires": [],
+    "optional": [],
+    "incompatible": []
+  },
+  "basic_fields": [
+    "created_at",
+    "created_by",
+    "updated_at",
+    "updated_by"
+  ],
+  "strict_fields": [
+    "before",
+    "after",
+    "action",
+    "reason",
+    "actor",
+    "trace"
+  ],
+  "x-research-anchors": {
+    "note": "基础四字段与严格六要素为 PRD §41 逐字（2026-09-03 对照 backend-references.md 差异表无冲突确认）；与主数据表原型的审计四字段（批次 1 recommended_fields）同源",
+    "sources": [
+      {
+        "url": "doc/POMaster-vNext-PRD-v0.6.1-Engineering-Substrate-Archetype-Catalog.md §41",
+        "fetched": "2026-09-03"
+      },
+      {
+        "url": ".trellis/tasks/09-02-vnext-prd-v06-governed-substrate/research/backend-references.md",
+        "fetched": "2026-09-03"
+      }
+    ]
+  }
+}

package/catalog/archetypes/archetype.backend.crud_resource.json

@@ -0,0 +1,56 @@
+{
+  "id": "ARCHETYPE.BACKEND.CRUD_RESOURCE",
+  "kind": "archetype",
+  "layer": "ARCHETYPE",
+  "title_zh": "标准企业 CRUD 资源",
+  "summary_zh": "Create/Read/Update/Delete/List 五操作的标准资源原型：分页/校验/审计/乐观锁为默认档，软删/批量/导入/导出为可选档；错误契约与授权为强制约束。",
+  "semantic": {
+    "responsibility": "单实体的标准写面与单点读面（get）",
+    "when_to_use": "实体需要标准维护 API 时；业务决定字段/权限/删除策略（v0.6.1 §70）",
+    "when_not_to_use": "纯查询报表资源（配 QUERY_RESOURCE）；事件驱动写路径"
+  },
+  "composition": {
+    "requires": [],
+    "optional": [
+      "ARCHETYPE.BACKEND.QUERY_RESOURCE",
+      "DATA_ARCHETYPE.MASTER_DATA"
+    ],
+    "incompatible": []
+  },
+  "operations": [
+    "create",
+    "get",
+    "list",
+    "update",
+    "delete"
+  ],
+  "defaults": {
+    "pagination": true,
+    "validation": true,
+    "audit": true,
+    "optimistic_lock": true
+  },
+  "optional_capabilities": {
+    "soft_delete": null,
+    "batch": null,
+    "import": null,
+    "export": null
+  },
+  "constraints": [
+    "api_error_contract",
+    "authorization_required"
+  ],
+  "verification": [
+    "unit",
+    "contract",
+    "persistence"
+  ],
+  "x-research-anchors": {
+    "sources": [
+      {
+        "url": "doc/POMaster-vNext-PRD-v0.6.1-Engineering-Substrate-Archetype-Catalog.md §26-§27/§83",
+        "fetched": "2026-09-02"
+      }
+    ]
+  }
+}

package/catalog/archetypes/archetype.backend.export.json

@@ -0,0 +1,40 @@
+{
+  "id": "ARCHETYPE.BACKEND.EXPORT",
+  "kind": "archetype",
+  "layer": "ARCHETYPE",
+  "title_zh": "导出原型",
+  "summary_zh": "数据导出双档原型（PRD §33 逐字）：小量同步直出（SYNC_SMALL）；大量异步三段（ASYNC_LARGE）——请求立任务、产物落对象存储、下载凭据交付。",
+  "semantic": {
+    "responsibility": "导出的量级分档与产物生命周期单点化：异步档把长耗时产物移出请求生命周期，凭据化下载替代大文件直传",
+    "when_to_use": "列表/报表数据导出文件——按量级选档（小量同步、大量异步），异步档任务态可查询可重试",
+    "when_not_to_use": "系统间数据同步（走外部集成/发件箱事件原型）；实时流式取数（走查询面）"
+  },
+  "composition": {
+    "requires": [],
+    "optional": [],
+    "incompatible": []
+  },
+  "modes": [
+    "SYNC_SMALL",
+    "ASYNC_LARGE"
+  ],
+  "async_chain": [
+    "Request",
+    "Job",
+    "Object Storage",
+    "Download Token"
+  ],
+  "x-research-anchors": {
+    "note": "双档词形与异步四段链为 PRD §33 逐字（2026-09-03 对照 backend-references.md 差异表无冲突确认）；产物落对象存储与文件二进制不入关系库字段同向（§40 File Resource 原型边界）",
+    "sources": [
+      {
+        "url": "doc/POMaster-vNext-PRD-v0.6.1-Engineering-Substrate-Archetype-Catalog.md §33",
+        "fetched": "2026-09-03"
+      },
+      {
+        "url": ".trellis/tasks/09-02-vnext-prd-v06-governed-substrate/research/backend-references.md",
+        "fetched": "2026-09-03"
+      }
+    ]
+  }
+}

package/catalog/archetypes/archetype.backend.external_integration.json

@@ -0,0 +1,89 @@
+{
+  "id": "ARCHETYPE.BACKEND.EXTERNAL_INTEGRATION",
+  "kind": "archetype",
+  "layer": "ARCHETYPE",
+  "title_zh": "外部集成原型",
+  "summary_zh": "外部系统调用八要素原型（PRD §38 逐字）：超时/重试/断路器/限流感知/鉴权/错误映射/可观测/回退；韧性默认档锚 Resilience4j 2.4.0 六模块现行文档——限流以『周期时长+每周期许可数』二元组显式给定（库默认周期是纳秒级形参，禁照抄）。",
+  "semantic": {
+    "responsibility": "把对外部系统每次调用的失效模式显式化：超时有时限、重试有上界、故障有熔断、过载有限流、失败有映射与回退——每一项都是显式配置而非默认假设",
+    "when_to_use": "同步/异步调用外部系统（第三方服务/跨域内部服务）的集成点——每个远端被调方一个独立韧性实例（官方 Golden Rule：MUST NOT share）",
+    "when_not_to_use": "进程内函数调用；库与事件最终一致的可靠外发（走发件箱事件原型）；用户交互内的本域写路径（走事务性写原型）"
+  },
+  "composition": {
+    "requires": [],
+    "optional": [],
+    "incompatible": []
+  },
+  "eight_elements": {
+    "timeout": {
+      "timeout_duration": "1s",
+      "cancel_running_future": true
+    },
+    "retry": {
+      "max_attempts": 3,
+      "wait_duration": "500ms",
+      "backoff": "fixed（指数退避为可选位，需显式启用退避与抖动配置）"
+    },
+    "circuit_breaker": {
+      "failure_rate_threshold": "50%",
+      "sliding_window": "COUNT_BASED 100 次",
+      "minimum_number_of_calls": 100,
+      "wait_duration_in_open_state": "60s",
+      "permitted_number_of_calls_in_half_open_state": 10
+    },
+    "bulkhead": {
+      "max_concurrent_calls": 25,
+      "max_wait_duration": "0（快失败默认）"
+    },
+    "rate_limit_awareness": {
+      "form": "period_and_permits_pair——『周期时长 + 每周期许可数』二元组必须显式给定",
+      "note": "库默认周期是纳秒级形参（词形误导），禁照抄默认值；且此限流是客户端本侧限速（许可桶），不是对端服务保护"
+    },
+    "auth": "凭据注入与刷新单点",
+    "error_mapping": "外部错误到本域错误分型的单点映射链",
+    "observability": "每次调用埋点（时延/结果/重试次数/熔断态）",
+    "fallback": "降级回退（recover 语义承接）"
+  },
+  "constraints": [
+    "每个远端服务一个独立韧性实例（官方 Golden Rule 逐字：\"Create a unique instance (with a unique ID) for each protected remote service or backend you communicate with.\"——CircuitBreaker 属实例感知模式 MUST NOT share）",
+    "限流语义是客户端本侧限速，非对端服务保护"
+  ],
+  "module_map_note": "Resilience4j 2.4.0 六核心模块对照：circuitbreaker/ratelimiter/bulkhead/retry/timelimiter/cache（另有 hedge 与 spring-boot3/spring-boot4 等适配模块）；2.4.0（2026-03-14）起基线 JDK 17→21",
+  "x-research-anchors": {
+    "note": "六模块清单与五模块全部默认值为官方 README/docs 2026-09-03 逐字实抓；RateLimiter 默认值按研究裁定不照抄（纳秒级周期形参误导）——改写为显式二元组要求；版本 2.4.0 与 JDK 21 基线取自 repo1.maven.org 官方 metadata 与 release notes",
+    "sources": [
+      {
+        "url": "https://github.com/resilience4j/resilience4j",
+        "fetched": "2026-09-03"
+      },
+      {
+        "url": "https://resilience4j.readme.io/docs/circuitbreaker",
+        "fetched": "2026-09-03"
+      },
+      {
+        "url": "https://resilience4j.readme.io/docs/retry",
+        "fetched": "2026-09-03"
+      },
+      {
+        "url": "https://resilience4j.readme.io/docs/ratelimiter",
+        "fetched": "2026-09-03"
+      },
+      {
+        "url": "https://resilience4j.readme.io/docs/bulkhead",
+        "fetched": "2026-09-03"
+      },
+      {
+        "url": "https://resilience4j.readme.io/docs/timeout",
+        "fetched": "2026-09-03"
+      },
+      {
+        "url": "https://repo1.maven.org/maven2/io/github/resilience4j/resilience4j-bom/maven-metadata.xml",
+        "fetched": "2026-09-03"
+      },
+      {
+        "url": ".trellis/tasks/09-02-vnext-prd-v06-governed-substrate/research/backend-references.md 题 6a",
+        "fetched": "2026-09-03"
+      }
+    ]
+  }
+}

package/catalog/archetypes/archetype.backend.idempotent_command.json

@@ -0,0 +1,65 @@
+{
+  "id": "ARCHETYPE.BACKEND.IDEMPOTENT_COMMAND",
+  "kind": "archetype",
+  "layer": "ARCHETYPE",
+  "title_zh": "幂等命令原型",
+  "summary_zh": "非幂等操作的容错重试原型（PRD §35 四件套）：键/作用域/过期/结果重放；标准现状如实锚定——IETF 草案 draft-ietf-httpapi-idempotency-key-header -07（2025-10-15）已过期未成标准，实践口径锚 Stripe 幂等请求与 Smithy 幂等令牌特质。",
+  "semantic": {
+    "responsibility": "以客户端生成键识别并丢弃重放请求：首个请求的结果（含失败形态）被保存，同键重放返回同一结果——幂等性是服务端承诺而非重试端自觉",
+    "when_to_use": "支付/递交/审批/导入/外部回调等非幂等写操作需要容错重试时（PRD §35 适用清单：payment/submit/approve/import/external callback）",
+    "when_not_to_use": "天然幂等的读操作；键无存储载体的纯内存操作；GET/删除类方法（收键无效果）"
+  },
+  "composition": {
+    "requires": [],
+    "optional": [],
+    "incompatible": []
+  },
+  "structure": {
+    "idempotency_key": "字符串 ≤255 字符，建议 UUID 或熵充足随机串（IETF RECOMMENDED + Stripe 建议 + Smithy 客户端自动填 UUID 三源一致）",
+    "scope": "唯一性作用域 + 载荷指纹（指纹候选枚举——IETF §2.4：整包校验和/选中元素校验和/字段值匹配/请求摘要或签名）",
+    "expiry": "默认 24h 保留窗口（Stripe 实践：键至少 24 小时后可自动清除）；过期策略必须写入 API 文档（IETF SHOULD）",
+    "result_replay": "保存首个请求的状态码与响应体（无论成败，含 5xx——Stripe 逐字口径：saving the resulting status code and body of the first request ... regardless of whether it succeeds or fails）"
+  },
+  "error_semantics": {
+    "missing_key": 400,
+    "in_flight_conflict": 409,
+    "payload_mismatch": 422,
+    "source": "IETF -07 正文错误语义（缺键 400；同键仍在处理中 409 Conflict；同键载荷不同 422——键不得跨不同载荷复用）"
+  },
+  "constraints": [
+    "仅对非幂等方法（POST/PATCH 类命令）启用；GET/删除类不收键（Stripe：Don't send idempotency keys in GET and DELETE requests because it has no effect.）",
+    "校验失败/并发冲突不落结果、可安全重试（Stripe：只在端点执行开始后才保存结果）",
+    "键禁含敏感数据（email/个人标识——Stripe）",
+    "标准状态如实引用：expired Internet-Draft（-07，2025-10-15，Intended status 字段为 None、无正式编号）+ Stripe/Smithy 实践——引用词形禁冒称已成正式标准"
+  ],
+  "optional": {
+    "fail_closed_on_missing_key": "缺键时拒绝（400）或忽略——服务自定（IETF SHOULD 级别留白）",
+    "retry_safety_baseline": "未标幂等令牌特质的操作默认应视为不可安全重试（Smithy 行为特质规范同页基线）",
+    "auto_client_key": "客户端实现可自动填键（Smithy MAY；AWS SDK 自动填 v4 UUID 先例）"
+  },
+  "x-research-anchors": {
+    "note": "【研究纠偏】任务问的 draft-ietf-httpapi-idempotency-key-resources 在 IETF datatracker 不存在（404）；真实词形为 draft-ietf-httpapi-idempotency-key-header，最新版 -07（2025-10-15）状态 Expired & archived、无正式编号——本物料全文不冒称已成正式标准（集成 spec 断言全文无该缩写词形）。Stripe（首个结果保存+24h 窗口+255 字符）与 Smithy idempotencyToken trait（服务端 MUST 在服务定义时段内防重放）为官方文档 2026-09-03 实抓",
+    "sources": [
+      {
+        "url": "https://datatracker.ietf.org/doc/draft-ietf-httpapi-idempotency-key-header/",
+        "fetched": "2026-09-03"
+      },
+      {
+        "url": "https://datatracker.ietf.org/doc/html/draft-ietf-httpapi-idempotency-key-header-07",
+        "fetched": "2026-09-03"
+      },
+      {
+        "url": "https://docs.stripe.com/api/idempotent_requests",
+        "fetched": "2026-09-03"
+      },
+      {
+        "url": "https://smithy.io/2.0/spec/behavior-traits.html",
+        "fetched": "2026-09-03"
+      },
+      {
+        "url": ".trellis/tasks/09-02-vnext-prd-v06-governed-substrate/research/backend-references.md 题 3",
+        "fetched": "2026-09-03"
+      }
+    ]
+  }
+}

package/catalog/archetypes/archetype.backend.import.json

@@ -0,0 +1,47 @@
+{
+  "id": "ARCHETYPE.BACKEND.IMPORT",
+  "kind": "archetype",
+  "layer": "ARCHETYPE",
+  "title_zh": "批量导入原型",
+  "summary_zh": "文件批量导入七步链原型（PRD §32 逐字）：上传→解析→校验→预览→确认→执行→结果；行级错误/部分失败/幂等/事务/审计五项必须预定义。",
+  "semantic": {
+    "responsibility": "把『文件进库』标准化为预览确认两段式：校验先行、人确认后才执行——执行形态（全量事务/部分失败）与行级错误报告显式预定义而非事后补",
+    "when_to_use": "电子表格/CSV 类批量建档与更新（参照数据初始化、期初导入等）——预定义五项缺一即契约不完整",
+    "when_not_to_use": "单条建档（走标准写面）；系统间定期同步（走外部集成/发件箱事件原型）"
+  },
+  "composition": {
+    "requires": [],
+    "optional": [],
+    "incompatible": []
+  },
+  "pipeline": [
+    "Upload",
+    "Parse",
+    "Validate",
+    "Preview",
+    "Confirm",
+    "Apply",
+    "Result"
+  ],
+  "predefined": [
+    "row_error",
+    "partial_failure",
+    "idempotency",
+    "transaction",
+    "audit"
+  ],
+  "predefined_source": "PRD §32 逐字：必须预定义：row error / partial failure / idempotency / transaction / audit。",
+  "x-research-anchors": {
+    "note": "七步链与预定义五项为 PRD §32 逐字（2026-09-03 对照 backend-references.md 差异表无冲突确认）；幂等项与幂等命令原型语义互链（重复导入以键防重）",
+    "sources": [
+      {
+        "url": "doc/POMaster-vNext-PRD-v0.6.1-Engineering-Substrate-Archetype-Catalog.md §32",
+        "fetched": "2026-09-03"
+      },
+      {
+        "url": ".trellis/tasks/09-02-vnext-prd-v06-governed-substrate/research/backend-references.md",
+        "fetched": "2026-09-03"
+      }
+    ]
+  }
+}

package/catalog/archetypes/archetype.backend.master_data.json

@@ -0,0 +1,45 @@
+{
+  "id": "ARCHETYPE.BACKEND.MASTER_DATA",
+  "kind": "archetype",
+  "layer": "ARCHETYPE",
+  "title_zh": "后端主数据原型",
+  "summary_zh": "标准主数据域后端原型（PRD §29）：增删改查写面与列表检索读面为基座，叠加审计、状态位、业务唯一键与可选版本位的六件套组合语义——组合语义定义住主数据域的标准后端形态。",
+  "semantic": {
+    "responsibility": "以六件套组合语义承载主数据域的标准后端形态：写面（新增/修改/删除）与读面分离，公共横切面（审计/状态/唯一键/版本）显式组合而非各自发明",
+    "when_to_use": "新建主数据域（组织/客商/物料字典等共享参照数据）的后端时——六件套组合即标准答案，不需要从零设计（v0.6.1 §90 Tracer：AI 不需要从零设计标准表结构）",
+    "when_not_to_use": "交易流水类（走交易流水数据原型——不默认软删）；纯一次性批量导入场景（导入原型承载流程而非实体形状）"
+  },
+  "composition": {
+    "requires": [
+      "ARCHETYPE.BACKEND.CRUD_RESOURCE",
+      "ARCHETYPE.BACKEND.QUERY_RESOURCE"
+    ],
+    "optional": [
+      "ARCHETYPE.BACKEND.AUDIT",
+      "DATA_ARCHETYPE.MASTER_DATA"
+    ],
+    "incompatible": []
+  },
+  "prd_combination": [
+    "CRUD_RESOURCE",
+    "QUERY_RESOURCE",
+    "AUDIT",
+    "STATUS",
+    "UNIQUE_BUSINESS_KEY",
+    "OPTIONAL_VERSION"
+  ],
+  "prd_combination_note": "PRD §29 组合清单逐字（CRUD_RESOURCE/QUERY_RESOURCE/AUDIT 三件为在册 catalog 物料——requires/optional 槽承载；STATUS/UNIQUE_BUSINESS_KEY/OPTIONAL_VERSION 三件为组合位词形，物理载体归 CRUD 物料的 defaults 审计/唯一约束/版本位）",
+  "x-research-anchors": {
+    "note": "组合语义为 PRD §29 逐字；与批次 1 在册物料的引用关系（CRUD/QUERY/DATA_ARCHETYPE.MASTER_DATA）经 backend-references.md 差异表 §47-§51 行 2026-09-03 对照无冲突；软删保持 optional 位（题 6b：GDPR Art.17 兼容但个人数据须有最终硬删路径）",
+    "sources": [
+      {
+        "url": "doc/POMaster-vNext-PRD-v0.6.1-Engineering-Substrate-Archetype-Catalog.md §29",
+        "fetched": "2026-09-03"
+      },
+      {
+        "url": ".trellis/tasks/09-02-vnext-prd-v06-governed-substrate/research/backend-references.md",
+        "fetched": "2026-09-03"
+      }
+    ]
+  }
+}