pomaster 0.4.0 → 0.5.1

package/seeds/specs/hard/frontend/01-development-checklist-protocol.md

@@ -1,86 +0,0 @@
----
-seed_source: pomaster/components/frontend-hard-spec/assets/universal/01-development-checklist-protocol.md
-seed_source_sha256: fa8914b29dbf7af25c8128aa1b8936fd658e37854e0a4f457175e2e3c82c3a03
-seed_version: B6B-1
-lane: frontend
-status: CURRENT
-authority_scope: mixed_required_and_advisory
-applies_to: [frontend]
-related_evidence_specs: []
-related_tools: []
----
-
-# 01 开发检查项协议
-
-## Scope
-
-P0。把规范转成每次开发前、开发中、开发后的强制动作，适用于功能、修复、重构、配置和文档驱动变更。
-
-## Non-Scope
-
-不定义技术栈命令，不替代测试协议、验收门禁和发布审批。
-
-## Terms
-
-- Change Classification：局部、同类模式、公共能力、契约、平台或工程变更。
-- Impact Set：必须修改、需要同步、明确禁止修改的范围。
-- Evidence：搜索、测试、截图、构建、契约差异等可复核证据。
-- Spec Update Review：开发完成后判断是否需要补充 spec 的强制复核。
-
-## MUST
-
-- 开发前完成变更分类、协议选择、复用搜索和影响范围。
-- 写代码前列出 Must Change、Must Sync、Must Not Change。
-- 缺少正式字段、状态、权限、接口或业务规则时先补契约或阻塞确认。
-- 开发中发现范围扩大时重新分类并更新计划。
-- 开发后提供检查结果、影响说明和残余风险。
-- 开发后、任务关闭或收口（closeout）流程前必须完成 Spec Update Review。
-- 发现新规则、重复坑点、接口/组件/目录/测试约定时必须更新对应 spec；无更新时必须记录原因。
-
-## MUST NOT
-
-- MUST NOT 先实现后补范围。
-- MUST NOT 用“应该没问题”代替证据。
-- MUST NOT 混入无关清理、升级或重构。
-- MUST NOT 跳过 Spec Update Review 后直接归档、收口或发布。
-- MUST NOT 将一次性实现细节写入长期 spec。
-
-## SHOULD
-
-- SHOULD 将检查项集成任务模板、PR 模板和自动化门禁。
-- SHOULD 按风险扩大检查，而非机械执行无关项目。
-
-## Contract
-
-```text
-Goal, Classification, ProtocolsLoaded, SpecStatus, ReuseSearch,
-MustChange, MustSync, MustNotChange, ContractsAffected,
-ValidationRequired, Evidence, SpecUpdateDecision, ResidualRisk
-```
-
-## Checklist
-
-- [ ] 已分类并加载协议。
-- [ ] 已搜索已有能力。
-- [ ] 已声明影响与禁止范围。
-- [ ] 已确认契约、安全和数据边界。
-- [ ] 已提供验证证据。
-- [ ] 已完成 Spec Update Review，并记录更新或不更新的原因。
-
-## Examples
-
-### 内容示例，可删除
-
-修复单页列宽时，先证明根因属于页面 schema，只修改该 schema 和页面测试，并明确禁止修改全局样式。
-
-## Anti-patterns
-
-直接修改公共组件，既不搜索调用方，也不验证同类页面，把局部问题扩散成全局回归。
-
-## Ownership
-
-实现者负责填写，Reviewer 核验范围与证据，协议 Owner 裁决歧义。
-
-## Change Policy
-
-新增检查项必须定义触发、验证和失败动作；降级 P0 检查项必须批准并记录期限。

package/seeds/specs/hard/frontend/02-ai-generated-code-protocol.md

@@ -1,82 +0,0 @@
----
-seed_source: pomaster/components/frontend-hard-spec/assets/universal/02-ai-generated-code-protocol.md
-seed_source_sha256: a80ea1c51c9afc0b96001cfffa0675edafb1572563652840bcf88770d81203c8
-seed_version: B6B-1
-lane: frontend
-status: CURRENT
-authority_scope: mixed_required_and_advisory
-applies_to: [frontend]
-related_evidence_specs: []
-related_tools: []
----
-
-# 02 AI 生成代码协议
-
-## Scope
-
-P0。约束 AI 分析、生成、修改、评审和验证代码时的行为。
-
-## Non-Scope
-
-不替代人工需求决策、代码所有权、测试、合规审批或上线责任。
-
-## Terms
-
-- AI Change Plan：写代码前声明的协议、事实、范围和验证计划。
-- Invented Contract：无正式来源而猜测的字段、状态、权限、API 或规则。
-- Unrelated Change：当前目标不需要的修改。
-
-## MUST
-
-- AI 写代码前读取适用协议并输出 Change Plan。
-- AI 必须先搜索已有组件、抽象、契约、工具和同类实现。
-- AI 必须区分事实、推断和待确认项。
-- AI 必须说明为什么修改这些文件、为什么不修改其他层。
-- AI 必须运行可用检查并如实报告未验证项。
-- AI 必须保留与任务无关的用户现有改动。
-
-## MUST NOT
-
-- MUST NOT 发明正式字段、枚举、公式、权限码、接口、路由或配置。
-- MUST NOT 重复创建已有能力。
-- MUST NOT 删除测试、降低断言、关闭规则或用类型逃逸掩盖问题。
-- MUST NOT 声称执行了实际未运行的验证。
-
-## SHOULD
-
-- SHOULD 把重复决策沉淀为协议、contract 或自动检查。
-- SHOULD 为高风险公共变更提供迁移和回滚。
-
-## Contract
-
-```text
-Goal, Protocols, Facts, Assumptions, TODO_CONFIRM,
-ReuseSearch, FilesToChange, FilesNotToChange,
-Validation, ResidualRisk
-```
-
-## Checklist
-
-- [ ] 已读协议和正式契约。
-- [ ] 已证明新建必要性。
-- [ ] 未猜测业务和接口事实。
-- [ ] 修改与同步范围明确。
-- [ ] 验证结果真实可复核。
-
-## Examples
-
-### 内容示例，可删除
-
-AI 修复报表列宽前识别列 schema 所属层级，验证相同表格类型，再修改领域 preset。
-
-## Anti-patterns
-
-未搜索组件库便新建相似组件，并顺手重构 store、API 和全局样式。
-
-## Ownership
-
-AI 仅为 Contributor；任务、代码、评审和上线分别由对应人类 Owner 负责。
-
-## Change Policy
-
-放宽 AI 禁止规则必须由工程治理和领域 Owner 批准；新型 AI 错误应转为协议或门禁。

package/seeds/specs/hard/frontend/03-acceptance-gate-protocol.md

@@ -1,86 +0,0 @@
----
-seed_source: pomaster/components/frontend-hard-spec/assets/universal/03-acceptance-gate-protocol.md
-seed_source_sha256: 646dcbd7035d43d84ca592218a356c08a4baca36619109797322d90ba3d99b73
-seed_version: B6B-1
-lane: frontend
-status: CURRENT
-authority_scope: mixed_required_and_advisory
-applies_to: [frontend]
-related_evidence_specs: []
-related_tools: []
----
-
-# 03 验收门禁协议
-
-## Scope
-
-P0。定义变更何时可以进入 Review、提测和上线，以及各阶段的必备证据。
-
-## Non-Scope
-
-不指定测试框架，不替代业务验收、发布平台操作或人工批准责任。
-
-## Terms
-
-- Ready for Review：实现和自检完成。
-- Ready for Test：评审阻塞关闭，构建可测试。
-- Ready for Release：质量、安全、监控和回滚可用。
-- Ready for Development：相关项目级和需求级 spec 已达到 Baseline 或批准的 Candidate。
-- Blocker：不满足即禁止进入下一阶段的问题。
-
-## MUST
-
-- 每个阶段输出 pass、fail 或有期限的 exception，并附证据。
-- P0 门禁失败时禁止进入下一阶段。
-- 契约、权限、安全、数据迁移和回滚风险必须确认。
-- 公共能力变更必须验证全部受影响调用方。
-- 例外必须记录负责人、风险、补偿措施和期限。
-- 开发前必须确认命中的项目级、需求级、组件级和接口级 spec 状态。
-- Review、提测、上线或任务关闭前必须确认 Spec Update Review 已完成。
-
-## MUST NOT
-
-- MUST NOT 以时间紧、人工点过或本地正常绕过 P0。
-- MUST NOT 在测试失败、契约未冻结或回滚不可用时放行。
-- MUST NOT 将未知风险标记为通过。
-- MUST NOT 在 spec 仍为 Draft 且无批准 Candidate 的情况下进入正式开发。
-- MUST NOT 将收口（closeout）、归档、发布记录当作 Spec Update Review 的替代品。
-
-## SHOULD
-
-- SHOULD 自动采集 lint、类型、测试、构建、安全和包体证据。
-- SHOULD 按风险设置附加门禁。
-
-## Contract
-
-```text
-Gate, SpecStatus, Result, Evidence[], Blockers[], Risks[],
-Approver, ExceptionExpiry?, RollbackVerified?, SpecUpdateReviewed?
-```
-
-## Checklist
-
-- [ ] Review 前范围、契约、自检齐全。
-- [ ] 提测前评审关闭、构建成功、环境明确。
-- [ ] 上线前回归、安全、监控、灰度、回滚通过。
-- [ ] 例外有负责人和到期时间。
-- [ ] 开发前 Ready for Development 已通过。
-- [ ] 收尾前 Spec Update Review 已完成。
-
-## Examples
-
-### 内容示例，可删除
-
-公共表格变更在组件测试、代表页面 E2E 和视觉回归通过后才可提测。
-
-## Anti-patterns
-
-仅凭“改动很小”跳过构建和调用方验证，直接交付测试或发布。
-
-## Ownership
-
-实现者提供 Review 证据，Reviewer/QA 确认提测，发布和风险 Owner 确认上线。
-
-## Change Policy
-
-门禁降级或删除必须有书面风险评估、批准人和恢复计划。

package/seeds/specs/hard/frontend/05-environment-configuration-protocol.md

@@ -1,80 +0,0 @@
----
-seed_source: pomaster/components/frontend-hard-spec/assets/universal/05-environment-configuration-protocol.md
-seed_source_sha256: 3affc23c84d64d10c8911b84bd9db82a34fcb9b675f7365672d554ecf34c8fb6
-seed_version: B6B-1
-lane: frontend
-status: CURRENT
-authority_scope: mixed_required_and_advisory
-applies_to: [frontend]
-related_evidence_specs: []
-related_tools: []
----
-
-# 05 环境与配置协议
-
-## Scope
-
-P0。管理环境划分、配置来源、环境变量、API 地址、Mock、日志等级和 Feature Flag 接入。
-
-## Non-Scope
-
-不保存真实密钥，不定义后端部署，也不替代安全或 Feature Flag 业务协议。
-
-## Terms
-
-- Build-time Config：构建时固化的公开配置。
-- Runtime Config：部署后可替换的公开配置。
-- Secret：不得进入前端的敏感值。
-- Environment：相互隔离的运行域。
-
-## MUST
-
-- 配置必须有 schema、类型、默认值、必填校验和环境矩阵。
-- API、Mock、日志和环境标识从统一配置模块读取。
-- 生产默认关闭 Mock、调试日志和开发工具。
-- 缺少必填配置时启动失败或安全降级，不得猜值。
-- 所有客户端配置均按公开信息处理。
-
-## MUST NOT
-
-- MUST NOT 在业务代码硬编码环境 URL、密钥或凭据。
-- MUST NOT 让组件读取底层环境变量。
-- MUST NOT 意外跨环境连接数据。
-- MUST NOT 将环境文件当密钥保险箱提交。
-
-## SHOULD
-
-- SHOULD 提供无敏感值的配置示例和启动校验。
-- SHOULD 明确标识非生产环境。
-
-## Contract
-
-```text
-ConfigKey, Type, Required, Public, Default,
-AllowedEnvironments, Validation, Owner
-```
-
-## Checklist
-
-- [ ] schema 和环境矩阵完整。
-- [ ] 生产安全默认值明确。
-- [ ] 前端产物无秘密值。
-- [ ] Mock、日志和 API 来源统一。
-
-## Examples
-
-### 内容示例，可删除
-
-业务 API 只读取 typed config 的 `apiBaseUrl`，组件不知道原始变量名称。
-
-## Anti-patterns
-
-在多个 API 文件硬编码不同测试地址，通过注释切换生产地址。
-
-## Ownership
-
-平台维护环境值，前端架构维护 schema，安全 Owner 裁决敏感性。
-
-## Change Policy
-
-配置增删改必须同步 schema、示例、部署矩阵和回滚；破坏性变更提供迁移期。

package/seeds/specs/hard/frontend/06-change-governance-protocol.md

@@ -1,90 +0,0 @@
----
-seed_source: pomaster/components/frontend-hard-spec/assets/universal/06-change-governance-protocol.md
-seed_source_sha256: 2f19b46e451153cab35e9fb511d9da0f072f86424e7d3f7a6b307cd17a9d1b32
-seed_version: B6B-1
-lane: frontend
-status: CURRENT
-authority_scope: mixed_required_and_advisory
-applies_to: [frontend]
-related_evidence_specs: []
-related_tools: []
----
-
-# 06 变更治理协议
-
-## Scope
-
-P0。管理公共组件、公共 API、样式、状态、schema 和平台能力的影响评估、兼容、废弃和迁移。
-
-## Non-Scope
-
-不定义单个组件的业务功能，不替代版本发布和代码评审。
-
-## Terms
-
-- Public Contract：被多个调用方依赖的稳定接口或默认行为。
-- Breaking Change：要求调用方修改才能继续工作的变更。
-- Deprecated：仍可用但已声明迁移目标和删除期限的能力。
-- Spec Status：Draft、Candidate、Baseline、Controlled Change 或 Release Review。
-- Baseline：可作为开发依据的冻结版本。
-- Controlled Change：Baseline 后带影响、Owner、迁移和验证证据的受控修改。
-
-## MUST
-
-- 公共变更前列出直接/间接调用方和受影响场景。
-- 保持兼容或提供迁移方案、版本范围和回滚。
-- 更新 contract、示例、测试、文档和通知。
-- 删除前必须先 deprecated 并确认无使用方。
-- 局部问题与公共问题必须按根因选择修改层级。
-- 项目级 spec、需求级 spec、公共组件 spec 和接口 spec 必须记录状态、版本、Owner、更新时间和生效范围。
-- Baseline 后修改公共组件 API、接口字段、权限码、错误码、Design Token、目录边界、状态模型、金额精度或验收门禁，必须走 Controlled Change。
-- 每次开发后的 Spec Update Review 必须把新规则归类为：需求级记录、长期 spec、通用规范候选或无需更新。
-
-## MUST NOT
-
-- MUST NOT 随意改变公共默认行为。
-- MUST NOT 为单页临时需求修改公共 API。
-- MUST NOT 只修一个页面来掩盖公共问题。
-- MUST NOT 无迁移地删除 props、事件、字段或状态。
-- MUST NOT 把 Draft 或示例内容当作 Baseline 执行。
-- MUST NOT 把 Draft 或示例内容当作 Baseline 执行。
-
-## SHOULD
-
-- SHOULD 使用影响模板、自动调用图和 deprecated 提示。
-- SHOULD 将公共变更拆成兼容引入、迁移、删除阶段。
-
-## Contract
-
-```text
-Change, SpecStatus, Version, Owner, AffectedConsumers[],
-Compatibility, Migration, DeprecationDate?, RemovalDate?,
-Tests, Rollback, SpecUpdateDecision
-```
-
-## Checklist
-
-- [ ] 根因层级明确。
-- [ ] 调用方清单完整。
-- [ ] 兼容、迁移和回滚可执行。
-- [ ] 测试、示例和通知已更新。
-- [ ] Spec 状态、版本、Owner 和生效范围已记录。
-- [ ] 开发后规则回填已归类并执行。
-
-## Examples
-
-### 内容示例，可删除
-
-新增 props 保留旧默认值，发布迁移说明，调用方完成迁移后再删除旧 props。
-
-## Anti-patterns
-
-为一个页面修改公共组件默认 padding，导致所有页面布局变化且没有视觉回归。
-
-## Ownership
-
-公共能力 Owner 对兼容负责，调用方 Owner 对迁移负责，架构 Owner 裁决跨模块影响。
-
-## Change Policy
-
-Breaking Change 必须版本化；紧急修复仍需事后补齐影响、通知和迁移记录。

package/seeds/specs/hard/frontend/07-frontend-backend-communication-protocol.md

@@ -1,219 +0,0 @@
----
-seed_source: pomaster/components/frontend-hard-spec/assets/universal/07-frontend-backend-communication-protocol.md
-seed_source_sha256: b14d2f8281198ff663e6e21e58df2e429c4683907cb77b6ebcdb6609d37f72d2
-seed_version: B6B-1
-lane: frontend
-status: CURRENT
-authority_scope: mixed_required_and_advisory
-applies_to: [frontend]
-related_evidence_specs: []
-related_tools: []
----
-
-# 07 前后端通信协议
-
-## Scope
-
-P0。定义前后端共同确认的接口、认证、错误、幂等、并发、文件、任务、实时通信和版本契约。
-
-## Non-Scope
-
-不规定前端请求库实现、页面错误呈现或具体后端框架。
-
-## Terms
-
-- Formal Contract：可版本化、可校验的 OpenAPI 或等价契约。
-- Idempotency：重复请求不产生重复业务结果。
-- Optimistic Concurrency：通过 version/ETag 防止静默覆盖。
-- TraceId：贯穿请求、任务和日志的问题定位标识。
-
-## MUST
-
-- 每个 endpoint 定义 URL、Method、参数位置、类型、响应、错误、权限和 owner。
-- 分页、筛选、排序、空值、枚举、单位和时间语义必须明确。
-- 写操作定义幂等、并发版本和缓存影响。
-- 文件、异步任务和实时消息使用正式 schema。
-- 破坏性变更必须版本化并提供迁移期。
-- 所有错误和任务链路可通过 TraceId 追踪。
-- 错误码到 UI 状态的映射必须维护在单一事实源 `outputs/frontend/10_planned/api-error-mapping.yaml`，并与契约版本同步。
-
-## MUST NOT
-
-- MUST NOT 用口头、截图、Mock 或示例替代正式契约。
-- MUST NOT 依赖 message 文本表达业务错误。
-- MUST NOT 用按钮 loading 代替后端幂等。
-- MUST NOT 未版本化地修改字段、枚举、分页或错误语义。
-
-## SHOULD
-
-- SHOULD 以机器可读契约生成类型、Mock 和校验。
-- SHOULD 对任务进度优先使用 SSE，双向场景再用 WebSocket。
-
-## Contract
-
-### 接口元数据
-
-```text
-Endpoint, Method, Auth, Permission, RequestSchema,
-ResponseSchema, ErrorSchema, Idempotency,
-Concurrency, Cache, RateLimit, Version, Owner
-```
-
-每个接口还必须记录用途、所属领域、稳定 operation id、超时、弃用状态和变更历史。口头约定、Mock、抓包结果和前端临时类型只能作为评审输入，不能成为主契约。
-
-### URL 与 Method
-
-- URL 使用稳定资源名和层级，不把页面动作或展示标题编码进路径。
-- GET 只读且可安全重试；POST/PUT/PATCH/DELETE 的创建、替换、部分更新和删除语义必须明确。
-- 提交、审批、归档、计算等非 CRUD 动作使用明确领域动作，不使用 `doAction` 等万能端点。
-- Path 参数标识资源，Query 表达分页/筛选/排序，Header 表达协议上下文，Body 表达命令或资源数据。
-
-### 请求参数
-
-每个字段必须定义：名称、位置、类型、必填、nullable、默认值、长度/范围、格式、枚举、单位、时区、示例和未知值策略。空字符串、null、缺失字段和空数组的语义不得混用。
-
-### 响应结构
-
-- 成功响应必须声明 HTTP status、内容类型、数据 schema、可空性和 TraceId。
-- 列表必须固定数据数组、页码或游标、pageSize、total/hasNext 的语义。
-- 删除、提交、异步创建等操作必须明确同步结果、任务标识或无内容响应。
-- 前端不得为同一业务同时兼容多个未版本化 envelope。
-
-### 错误结构
-
-```text
-Error {
-  httpStatus,
-  code,
-  safeMessage?,
-  traceId,
-  fieldErrors?,
-  itemErrors?,
-  retryable,
-  retryAfter?,
-  conflictVersion?
-}
-```
-
-- HTTP status 表达认证、权限、资源、冲突、校验、限流和服务状态。
-- 业务 code 必须稳定且可枚举，message 仅用于展示或诊断，不能驱动逻辑。
-- 字段错误包含稳定 field key、错误码和参数；批量错误包含对象/行标识。
-- 409 返回冲突实体或重新获取方式；429 返回明确退避信息；5xx 不代表所有请求均可重试。
-
-### DTO、Adapter 与 ViewModel
-
-接口契约定义 DTO。前端通过 Adapter 转成稳定 Domain Model/ViewModel；公共组件、表格列和模板不得直接依赖 DTO。字段重命名、null、枚举、日期和金额转换只能在边界完成。
-
-### 分页、筛选与排序
-
-- 页码起点或游标语义、pageSize 上限、total 是否精确必须固定。
-- 筛选字段采用允许列表，并定义操作符、组合逻辑、空值和时间区间。
-- 排序字段和方向采用允许列表；需要稳定结果时声明次排序。
-- 导出必须复用列表筛选语义，并明确当前页、选中项或符合条件的全量范围。
-
-### 权限通信
-
-- 接口声明认证要求、操作权限和数据范围。
-- 后端只返回调用方有权访问的数据；前端隐藏入口不能替代鉴权。
-- 字段可见、脱敏、编辑和导出权限必须有稳定 contract。
-- 权限变化后 token、缓存和已打开页面如何失效必须明确。
-
-### 认证与 Token
-
-必须定义 access/refresh token 生命周期、传输位置、刷新、撤销、退出、多标签同步、并发 401 合并和 CSRF 策略。Token 不得出现在 URL、日志、埋点或业务组件。
-
-### 幂等性
-
-- 创建、提交、审批、批量动作、导入、导出和计算等可能重复执行的命令必须声明幂等支持。
-- 幂等键的生成方、作用域、有效期、重复请求响应和冲突行为必须固定。
-- 前端按钮禁用和 loading 只是体验保护，不构成业务幂等。
-
-### 并发与数据冲突
-
-- 可编辑资源返回 version、updatedAt 或 ETag，并在更新命令携带预期版本。
-- 冲突必须显式返回，不允许静默 last-write-wins。
-- 契约声明刷新、放弃本地修改、重新提交和字段 diff 所需数据。
-
-### 缓存与刷新
-
-接口声明可缓存性、ETag/version、数据实时性和写操作影响资源。权限、BOM、成本、审批等高风险数据不得由调用方擅自延长缓存；mutation 必须提供足够信息完成准确失效。
-
-### 文件上传与下载
-
-- 上传声明 multipart 字段、类型、大小、数量、文件名、校验阶段和安全错误。
-- 下载声明内容类型、文件名编码、权限、数据范围、有效期和断点/大文件策略。
-- 文件 URL 不得成为永久越权入口，下载时必须重新授权。
-
-### 异步任务
-
-```text
-Job {
-  taskId, type, status, progress,
-  message?, result?, error?, traceId,
-  createdAt, updatedAt
-}
-```
-
-必须定义创建、查询、取消、重试、结果、错误明细、过期和幂等。状态机至少区分 pending、running、success、failed、cancelled；新增状态需契约变更。
-
-### 实时通信
-
-- 服务端单向进度和通知优先 SSE；双向协作才使用 WebSocket；轮询为降级。
-- 消息至少包含 messageId、type、payload、timestamp、version 和 TraceId。
-- 必须定义鉴权、心跳、断线重连、重复、乱序、丢失、回放、完成终止和降级行为。
-
-### 版本兼容
-
-- 新增可选字段通常向后兼容；删除、改名、类型、枚举或语义变化属于破坏性变更。
-- 未知枚举必须安全兜底，但不得静默赋予业务含义。
-- 破坏性变化提供新版本、调用方清单、迁移期、弃用日期和回滚。
-- 生成类型、Adapter、Mock、导入导出和测试必须随契约同步。
-
-### 联调流程
-
-正式流程为：契约提案 -> 示例/Mock -> 前后端与业务评审 -> 冻结 -> 类型生成/Adapter -> 联调 -> 非理想态验收 -> 发布。联调不能只验证 200，至少覆盖 401、403、409、422、429、5xx、超时和部分成功。
-
-### TraceId
-
-客户端操作、HTTP 请求、异步任务、实时消息、后端日志和用户可见错误应能关联 TraceId/OperationId。TraceId 不携带敏感信息，并在跨服务时保持或建立明确父子关系。
-
-### 错误码到 UI 状态映射
-
-`outputs/frontend/10_planned/api-error-mapping.yaml` 是每个项目必须维护的事实源，字段包括：
-
-```text
-ErrorCode, HttpStatus, UIState, RecoverAction, DefaultMessage, TraceIdRequired, ContractVersion
-```
-
-- 每个稳定业务 code 必须映射到唯一 UI 状态（idle/loading/error/success/retry/conflict/permission）。
-- 映射必须随契约版本升级；破坏性 code 变化属于契约变更。
-- UI 不得直接按 message 文本或 HTTP status 推导状态；未映射 code 必须进入兜底状态并记录。
-
-## Checklist
-
-- [ ] 请求/响应和错误完整。
-- [ ] 参数位置、空值、枚举、单位和时间语义明确。
-- [ ] 分页、筛选、排序和导出语义一致。
-- [ ] 权限、幂等、并发明确。
-- [ ] 文件/任务/实时契约完整。
-- [ ] 兼容和 TraceId 可验证。
-- [ ] 类型、Adapter、Mock 和错误场景随契约同步。
-- [ ] api-error-mapping.yaml 已维护并与契约版本一致。
-
-## Examples
-
-### 内容示例，可删除
-
-更新实体携带预期 version；冲突返回 409、稳定错误码、服务器版本和 TraceId。批量导入返回 taskId，进度消息使用固定 Job/Realtime schema，完成后按契约刷新受影响资源。
-
-## Anti-patterns
-
-前端按 Mock 猜字段，后端改名后页面同时兼容多种响应并比较错误 message；创建、导入和审批只靠按钮 loading 防重；轮询、SSE 和 WebSocket 又各自定义一套任务状态。
-
-## Ownership
-
-前后端 API Owner 共同负责，业务 Owner 确认语义，安全 Owner 确认认证和权限。
-
-## Change Policy
-
-契约先评审、再冻结、后实现；破坏性变化必须有版本、调用方清单、迁移和退役日期。