pomaster 0.3.0 → 0.4.0

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

@@ -0,0 +1,219 @@
+---
+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
+
+契约先评审、再冻结、后实现；破坏性变化必须有版本、调用方清单、迁移和退役日期。

package/seeds/specs/hard/frontend/08-role-responsibility-protocol.md

@@ -0,0 +1,80 @@
+---
+seed_source: pomaster/components/frontend-hard-spec/assets/universal/08-role-responsibility-protocol.md
+seed_source_sha256: 732ac305cd16207e4a7bd4c95a6774d1aca33fb4e45cf29991ac0f6475605d6f
+seed_version: B6B-1
+lane: frontend
+status: CURRENT
+authority_scope: mixed_required_and_advisory
+applies_to: [frontend]
+related_evidence_specs: []
+related_tools: []
+---
+
+# 08 角色责任协议
+
+## Scope
+
+P0/P1 治理协议。定义需求、设计、前端、后端、测试、平台、安全、协议和 AI 协作中的责任边界。
+
+## Non-Scope
+
+不规定组织架构、职级、绩效或人员姓名，不替代项目管理系统。
+
+## Terms
+
+- Responsible：执行者。
+- Accountable：最终责任者。
+- Consulted：必须征询者。
+- Informed：必须通知者。
+- Approver：有权放行例外者。
+
+## MUST
+
+- 每个协议、公共组件、接口、业务规则和发布都有 Accountable Owner。
+- 跨团队变更开发前确定 Reviewer 和通知范围。
+- 无 Owner 的关键决策必须阻塞并升级。
+- AI 输出必须由人类 Owner Review，AI 不得成为 Approver。
+
+## MUST NOT
+
+- MUST NOT 用“团队共同负责”隐藏无人负责。
+- MUST NOT 让前端单方面决定后端契约、公式或数据权限。
+- MUST NOT 让设计稿覆盖安全、可访问性或公共 API。
+- MUST NOT 让 AI 代替业务、合规或上线签字。
+
+## SHOULD
+
+- SHOULD 为跨层能力维护轻量 RACI。
+- SHOULD 为 Owner 缺席定义代理和升级路径。
+
+## Contract
+
+```text
+ArtifactOrDecision, Responsible, Accountable,
+Consulted[], Informed[], RequiredReviewers[], EscalationPath
+```
+
+## Checklist
+
+- [ ] 各阶段 Owner 明确。
+- [ ] 跨层 Reviewer 已确定。
+- [ ] 例外有批准者。
+- [ ] AI 输出有人类责任人。
+
+## Examples
+
+### 内容示例，可删除
+
+业务 Owner 定义金额口径，后端负责权威计算，前端负责无损展示，QA 验证边界。
+
+## Anti-patterns
+
+接口含义未确认时由前端和 AI 自行解释，最终无人能判断哪个结果正确。
+
+## Ownership
+
+项目负责人维护角色模型，各领域 Owner 维护其 RACI，治理 Owner 处理无人归属。
+
+## Change Policy
+
+角色或批准边界变化必须通知协作者；临时代理必须有范围和期限。

package/seeds/specs/hard/frontend/09-module-boundary-protocol.md

@@ -0,0 +1,81 @@
+---
+seed_source: pomaster/components/frontend-hard-spec/assets/universal/09-module-boundary-protocol.md
+seed_source_sha256: f9a3c194910bbb31cd322849cb277db5d2ae0fd74773eef7df34197b8ad89c4f
+seed_version: B6B-1
+lane: frontend
+status: CURRENT
+authority_scope: mixed_required_and_advisory
+applies_to: [frontend]
+related_evidence_specs: []
+related_tools: []
+---
+
+# 09 模块边界协议
+
+## Scope
+
+P0。定义顶层目录职责、依赖方向、公开入口、shared 下沉和跨模块协作。
+
+## Non-Scope
+
+不规定具体框架目录名，不替代组件、状态或业务规则协议。
+
+## Terms
+
+- Module：有明确职责、Owner 和公开入口的代码边界。
+- Public API：允许其他模块依赖的最小出口。
+- Internal：只允许模块内部使用的实现。
+- Shared：无特定业务所有权且满足复用门槛的能力。
+
+## MUST
+
+- 顶层目录和模块职责必须文档化。
+- 依赖方向和禁止方向必须可检查。
+- 模块外部只能通过 Public API 引用。
+- 跨模块流程进入明确的 orchestration/feature 层。
+- shared 下沉必须证明稳定复用和低业务耦合。
+- 循环依赖必须被工具检测并阻止。
+
+## MUST NOT
+
+- MUST NOT 引用其他模块内部文件。
+- MUST NOT 把页面代码作为其他模块依赖。
+- MUST NOT 因方便把业务能力放进 shared。
+- MUST NOT 新建无职责说明的顶层目录。
+
+## SHOULD
+
+- SHOULD 每个模块维护 contract、owner 和 index/public exports。
+- SHOULD 用依赖图和 lint 自动执行边界。
+
+## Contract
+
+```text
+Module, Responsibility, Owner, PublicExports[],
+AllowedDependencies[], ForbiddenDependencies[], InternalPaths[]
+```
+
+## Checklist
+
+- [ ] 新文件归属可解释。
+- [ ] 只通过公开入口依赖。
+- [ ] shared 满足下沉条件。
+- [ ] 无循环或越层引用。
+
+## Examples
+
+### 内容示例，可删除
+
+两个业务域共同参与的导入流程放入 feature/orchestration 层，而不是让域 A 引用域 B 的页面。
+
+## Anti-patterns
+
+把带客户、订单、成本语义的组件放入 shared，再被多个模块反向耦合。
+
+## Ownership
+
+架构 Owner 维护顶层边界，模块 Owner 维护公开入口，Reviewer 阻止越层引用。
+
+## Change Policy
+
+新增顶层模块、改变依赖方向或扩大 Public API 必须经过架构评审和迁移说明。

package/seeds/specs/hard/frontend/10-engineering-tooling-protocol.md

@@ -0,0 +1,89 @@
+---
+seed_source: pomaster/components/frontend-hard-spec/assets/universal/10-engineering-tooling-protocol.md
+seed_source_sha256: c628d47dcae1ddd58ea3651eeae9dd84ff5157365a3892a367bd7b5bf0af2b9d
+seed_version: B6B-1
+lane: frontend
+status: CURRENT
+authority_scope: mixed_required_and_advisory
+applies_to: [frontend]
+related_evidence_specs: []
+related_tools: []
+---
+
+# 10 工程工具协议
+
+## Scope
+
+P0。用类型、格式、Lint、契约、测试、示例、CI 和 ADR 固化团队协议。
+
+## Non-Scope
+
+不强制所有项目使用同一框架或供应商工具，不替代依赖评审。
+
+## Terms
+
+- Quality Command：本地与 CI 共用的标准检查入口。
+- Generated Artifact：由可重复命令生成、禁止手改的文件。
+- ADR：记录重要架构决策及后果的文档。
+
+## MUST
+
+- 项目明确 TypeScript/类型、Lint、Format、样式、测试和构建工具。
+- 本地与 CI 使用相同标准命令。
+- 接口契约和生成物必须可重复生成和校验。
+- 公共组件必须有可运行示例。
+- 重要架构和工具决策必须记录 ADR/RFC。
+- 工具违规必须产生明确失败而非仅提示。
+- 运行时、包管理器和关键构建工具版本必须被仓库内机器可读配置固定，并由 CI 校验。
+- TypeScript 项目必须启用与代码库兼容的严格类型检查；暂不能启用的严格选项必须有范围、Owner、迁移计划和期限。
+- 外部数据必须先经运行时校验再进入可信类型；类型断言和非空断言不得替代边界验证。
+- 配置必须有单一有效来源，废弃配置应移除或显式失效，避免多个配置文件竞争生效。
+
+## MUST NOT
+
+- MUST NOT 只靠口头约定格式、类型、接口和组件用法。
+- MUST NOT 手改生成物。
+- MUST NOT 为局部问题关闭全局规则。
+- MUST NOT 让 CI 与本地使用不同质量标准。
+- MUST NOT 依赖开发机全局安装的工具或隐式环境状态完成构建和检查。
+- MUST NOT 用项目级忽略、`any`、类型断言或关闭规则掩盖局部问题；例外必须最小化并可追踪。
+
+## SHOULD
+
+- SHOULD 自动检测依赖边界、契约漂移、包体、可访问性和视觉回归。
+- SHOULD 提供一条命令执行常规质量门禁。
+
+## Contract
+
+```text
+Tool, Purpose, VersionPolicy, Command,
+Inputs, Outputs, FailureCondition, Owner
+```
+
+## Checklist
+
+- [ ] 工具和命令明确。
+- [ ] CI 可自动发现违规。
+- [ ] 生成过程可重复。
+- [ ] 公共组件有示例。
+- [ ] 重要决策有记录。
+- [ ] 运行时和工具版本可复现，未依赖全局安装。
+- [ ] 类型严格度和例外有边界、Owner 与迁移计划。
+
+## Examples
+
+### 内容示例，可删除
+
+类型、lint、单测和构建通过统一脚本运行，CI 直接调用相同脚本。
+
+## Anti-patterns
+
+开发者本地忽略类型错误，CI 又没有 typecheck，问题直到上线构建才暴露。
+
+## Ownership
+
+工程 Owner 维护工具链，模块 Owner 修复违规，CI Owner 保证门禁可靠。
+
+## Change Policy
+
+工具新增、替换或规则放宽必须评估迁移、性能和开发体验，并提供版本化配置。

package/seeds/specs/hard/frontend/11-dependency-package-management-protocol.md

@@ -0,0 +1,87 @@
+---
+seed_source: pomaster/components/frontend-hard-spec/assets/universal/11-dependency-package-management-protocol.md
+seed_source_sha256: a0cc135edaf0dfd1f5122d2ff7298866143ef3a273ad4d45f5e1eff763691867
+seed_version: B6B-1
+lane: frontend
+status: CURRENT
+authority_scope: mixed_required_and_advisory
+applies_to: [frontend]
+related_evidence_specs: []
+related_tools: []
+---
+
+# 11 依赖与包管理协议
+
+## Scope
+
+P1。管理包管理器、锁文件、依赖引入、版本、许可证、安全、升级和删除。
+
+## Non-Scope
+
+不规定具体框架选型，不替代供应链扫描和法律审查。
+
+## Terms
+
+- Runtime Dependency：进入生产运行路径的依赖。
+- Development Dependency：仅构建、测试或开发使用。
+- Dependency Budget：包体、维护、安全和替换成本预算。
+
+## MUST
+
+- 固定包管理器、锁文件和受信 registry。
+- 固定 runtime 与包管理器版本；仓库只能有一种生效锁文件，CI 使用 frozen/immutable 安装并在 manifest 与锁文件漂移时失败。
+- 引入前检查现有能力、维护状态、许可证、安全、包体和替代方案。
+- 依赖变更必须审查直接与传递依赖、完整性/来源、安装脚本、可执行代码、发布内容和锁文件差异。
+- 正确区分 runtime/dev 并保证可重复安装。
+- 升级审查 breaking changes、测试和回滚。
+- 删除未使用依赖及其配置、适配和文档。
+- 构建插件、CI action、代码生成器和远程脚本按供应链依赖治理；可变引用必须改为不可变版本或受控版本策略。
+
+## MUST NOT
+
+- MUST NOT 为简单函数引入大型库。
+- MUST NOT 并存职责重复的核心库而无批准。
+- MUST NOT 手改或绕过锁文件。
+- MUST NOT 忽略高危漏洞和许可证冲突。
+- MUST NOT 盲目执行依赖安装脚本、远程脚本或自动修复命令而不审查将执行和变更的内容。
+- MUST NOT 只审查 `package.json` 而忽略锁文件、传递依赖和 CI/构建依赖变化。
+
+## SHOULD
+
+- SHOULD 选择维护活跃、tree-shakable、类型完整的依赖。
+- SHOULD 通过 adapter 隔离高替换成本 API。
+- SHOULD 自动执行依赖差异、安全、许可证和来源审查；发布包时生成可验证 provenance/SBOM，并检查发布内容不含凭据、测试身份或私有 source map。
+
+## Contract
+
+```text
+Package, Purpose, AlternativesChecked, RuntimeOrDev,
+VersionPolicy, LockfileImpact, TransitiveDiff, Integrity, Provenance,
+InstallScripts, BundleImpact, License, Security, Owner, RemovalPlan
+```
+
+## Checklist
+
+- [ ] 新增必要性已证明。
+- [ ] 安全、许可、维护、包体已评估。
+- [ ] 安装可重复。
+- [ ] 有升级和移除策略。
+- [ ] 传递依赖、安装脚本和构建/CI 依赖已审查。
+
+## Examples
+
+### 内容示例，可删除
+
+引入表格引擎前比较现有组件、许可证、虚拟滚动、可访问性和长期维护，并通过 adapter 隔离。
+
+## Anti-patterns
+
+多个页面分别引入不同日期库，只为格式化日期，造成包体和时区行为不一致。
+
+## Ownership
+
+工程 Owner 维护策略，模块 Owner 负责新增，安全/法务裁决风险。
+
+## Change Policy
+
+新增或主版本升级需要评审记录；紧急安全升级可加速但必须补测试。

package/seeds/specs/hard/frontend/12-business-rules-protocol.md

@@ -0,0 +1,79 @@
+---
+seed_source: pomaster/components/frontend-hard-spec/assets/universal/12-business-rules-protocol.md
+seed_source_sha256: dda683a7c907989032c82a2c1c3e552b51226e0e0cd5bdf3b6068cc7f649c525
+seed_version: B6B-1
+lane: frontend
+status: CURRENT
+authority_scope: mixed_required_and_advisory
+applies_to: [frontend]
+related_evidence_specs: []
+related_tools: []
+---
+
+# 12 业务规则协议
+
+## Scope
+
+P1。定义领域校验、操作许可、状态流转、时间范围、金额规则入口和后端兜底关系。
+
+## Non-Scope
+
+不定义视觉呈现，不允许前端规则替代后端权威规则。
+
+## Terms
+
+- Domain Rule：不依赖具体页面的业务判断。
+- State Machine：合法状态及转换集合。
+- Authoritative Validation：决定业务结果的后端校验。
+
+## MUST
+
+- 规则集中存放、命名、测试并有 Owner。
+- 页面和组件调用规则函数，不复制表达式。
+- 状态转换声明来源、目标、条件、权限和失败码。
+- 金额、比例、日期区间和操作限制有明确契约。
+- 后端执行最终一致性和权威校验。
+
+## MUST NOT
+
+- MUST NOT 将同一规则散落在组件、文案和 API 回调。
+- MUST NOT 以按钮禁用代替后端校验。
+- MUST NOT 在无正式来源时发明状态或公式。
+- MUST NOT 用展示文案作为规则返回值。
+
+## SHOULD
+
+- SHOULD 使用纯函数、schema 和状态机表达可测试规则。
+- SHOULD 返回稳定原因码供 UI 映射文案。
+
+## Contract
+
+```text
+RuleId, Inputs, Preconditions, Result,
+ReasonCodes[], BackendEnforcement, Owner, Version
+```
+
+## Checklist
+
+- [ ] 规则来源和 Owner 明确。
+- [ ] 页面未复制规则。
+- [ ] 状态与错误码完整。
+- [ ] 后端有权威兜底。
+
+## Examples
+
+### 内容示例，可删除
+
+`canApprove(entity, actor)` 返回允许状态和原因码，页面仅决定如何展示。
+
+## Anti-patterns
+
+三个页面分别用不同 if 判断“审批中不可编辑”，导致规则漂移。
+
+## Ownership
+
+业务/领域 Owner 定义语义，后端 Owner 保证权威执行，前端负责一致呈现。
+
+## Change Policy
+
+规则或状态变化必须版本化并同步 API、权限、审计、文案和测试。