pomaster 0.4.0 → 0.5.0

package/seeds/specs/hard/themes/release-and-feature-flags.md

@@ -0,0 +1,237 @@
+---
+seed_source: packages/cli/seeds/aggregation-manifest.json
+seed_source_sha256: 039b637ccffacdfe3ce30d85e193f4b38928fcdfb16efdc4eb255e35e05af91f
+seed_version: B7-THEME
+lane: [frontend, backend]
+status: CURRENT
+authority_scope: mixed_required_and_advisory
+applies_to: [frontend, backend]
+related_evidence_specs: []
+related_tools: []
+legacy_id: theme:release-and-feature-flags
+criticality: critical # 聚合注记：取源最高；info 性注记非执行语义
+injection_mode: triggered # 聚合注记：来源同值；info 性注记非执行语义
+stages: [prepare, check, release] # 聚合注记：来源 stages 并集；info 性注记非执行语义
+triggers: [release, rollback, versioning] # 聚合注记：来源 triggers 并集；info 性注记非执行语义
+requires: [] # 聚合注记：来源 requires 并集（全空）
+x-aggregation: # 聚合来源（D6）：逐源 vendor pin（sha256 与卡 vendor_pin 同值）
+  - seed_source: pomaster/components/frontend-hard-spec/assets/universal/33-release-versioning-protocol.md
+    sha256: aae0557f4935bac24d04e37ebde5638471b709ff568fea0d13de35bd5dd404af
+    seed_version: B6B-2
+  - seed_source: pomaster/components/frontend-hard-spec/assets/universal/36-feature-flag-protocol.md
+    sha256: ba6cf2d5607ba54d9864cd6c07899d2e13a8d33ea248fbd7469b92c23474f474
+    seed_version: B6B-2
+  - seed_source: pomaster/components/backend-hard-spec/assets/universal/32-release-versioning-rollback-protocol.md
+    sha256: 26a6a23928fc24338f69fb34199ecdea5f654e21534a76ac53a7c0b78030b3c8
+    seed_version: B6C
+---
+
+# 发布与开关
+
+> **聚合纪律**：本文档 12 节正文规则行逐字取自 frontmatter x-aggregation 所列来源协议（节内按「端 → 源编号升序」以加粗来源行分块，源内标题与层级原样保留），零新增、零改写、零删除；新增文本仅限文档标题、本注记与逐节来源行。
+
+## Scope
+
+**源：FE 33 版本与发布协议（pomaster/components/frontend-hard-spec/assets/universal/33-release-versioning-protocol.md）**
+
+P2。定义版本标识、分支/提交、灰度、回滚、公共 API 兼容和发布证据。
+
+**源：FE 36 Feature Flag 协议（pomaster/components/frontend-hard-spec/assets/universal/36-feature-flag-protocol.md）**
+
+P2。定义功能开关来源、命名、灰度范围、关闭表现、默认值和生命周期。
+
+**源：BE 32 发布、版本与回滚协议（pomaster/components/backend-hard-spec/assets/universal/32-release-versioning-rollback-protocol.md）**
+
+规范版本、灰度、开关、发布记录、兼容窗口、回滚和数据库演进。
+
+## Non-Scope
+
+**源：FE 33 版本与发布协议**
+
+不替代验收门禁、组织发布平台和基础设施部署流程。
+
+**源：FE 36 Feature Flag 协议**
+
+不替代权限、业务状态和环境配置。
+
+**源：BE 32 发布、版本与回滚协议**
+
+不替代具体平台操作手册或证据验收协议。
+
+## Terms
+
+**源：FE 33 版本与发布协议**
+
+- App Version：可关联提交、构建、环境和 source map 的版本。
+- Gray Release：受控用户/环境范围内逐步发布。
+- Rollback：恢复到已验证版本和兼容状态。
+
+**源：FE 36 Feature Flag 协议**
+
+- Flag Key：稳定唯一的开关键。
+- Targeting：按环境、用户、角色或组织控制命中。
+- Kill Switch：紧急关闭新能力的开关。
+
+**源：BE 32 发布、版本与回滚协议**
+
+可回退包括代码回滚、配置恢复、流量撤回和数据 roll-forward 的组合能力。
+
+## MUST
+
+**源：FE 33 版本与发布协议 · §MUST**
+
+- 每个构建有可观测版本和来源。
+- 发布前契约、测试、安全、配置、监控和回滚满足门禁。
+- 高风险变更定义灰度和停止条件。
+- 回滚同时考虑前端资源、接口、缓存、任务和数据兼容。
+- 公共 breaking change 先 deprecated 并提供迁移期。
+
+**源：FE 36 Feature Flag 协议 · §MUST**
+
+- 每个 flag 有 owner、目的、默认值、目标范围、期限和清理日期。
+- 入口、路由和后台请求在关闭时一致停用。
+- 获取失败使用保守默认值。
+- Flag 与权限同时通过才允许操作。
+- 全量稳定后删除临时判断和旧路径。
+
+**源：BE 32 发布、版本与回滚协议 · §MUST**
+
+- 发布前必须确认版本、依赖顺序、兼容、观测、停止条件和恢复路径。
+
+## MUST NOT
+
+**源：FE 33 版本与发布协议 · §MUST NOT**
+
+- MUST NOT 无版本标识发布。
+- MUST NOT 无回滚上线破坏性变化。
+- MUST NOT 直接删除公共 API。
+- MUST NOT 发布后才补监控和 source map。
+
+**源：FE 36 Feature Flag 协议 · §MUST NOT**
+
+- MUST NOT 在多个页面手写同一判断。
+- MUST NOT 将 flag 当权限或业务状态。
+- MUST NOT 使用无 owner、无期限的永久临时 flag。
+- MUST NOT 关闭 UI 却继续触发后台请求。
+
+**源：BE 32 发布、版本与回滚协议 · §MUST NOT**
+
+- 不得在无法恢复数据或无监控信号时进行不可逆全量发布。
+
+## SHOULD
+
+**源：FE 33 版本与发布协议 · §SHOULD**
+
+- SHOULD 自动生成变更摘要和发布证据。
+- SHOULD 使用 Feature Flag 降低高风险上线范围。
+
+**源：FE 36 Feature Flag 协议 · §SHOULD**
+
+- SHOULD 支持灰度、回滚、监控和实验审计。
+- SHOULD 对关键写操作提供 kill switch。
+
+**源：BE 32 发布、版本与回滚协议 · §SHOULD**
+
+- 应采用小批量灰度、可撤回开关和前后版本并行兼容。
+
+## Contract
+
+**源：FE 33 版本与发布协议 · §Contract**
+
+```text
+Version, Commit, BuildTime, Environment, Changes,
+Flags, Migration, Monitoring, Rollback, Owner
+```
+
+**源：FE 36 Feature Flag 协议 · §Contract**
+
+```text
+FlagKey, Owner, Default, Targeting, Fallback,
+StartAt, EndAt, CleanupAt, Metrics
+```
+
+**源：BE 32 发布、版本与回滚协议 · §Contract**
+
+发布记录必须包含变更范围、产物 hash、步骤、门禁、指标、Owner 与结果。
+
+## Checklist
+
+**源：FE 33 版本与发布协议 · §Checklist**
+
+- [ ] 版本可追踪。
+- [ ] 门禁和契约通过。
+- [ ] 灰度与回滚可执行。
+- [ ] deprecated/迁移完整。
+
+**源：FE 36 Feature Flag 协议 · §Checklist**
+
+- [ ] 默认和失败行为安全。
+- [ ] UI/路由/请求一致。
+- [ ] 不绕过权限。
+- [ ] 有清理日期。
+
+**源：BE 32 发布、版本与回滚协议 · §Checklist**
+
+- [ ] 应用、数据库、配置、消息、缓存与消费者版本已对齐。
+
+## Examples
+
+**源：FE 33 版本与发布协议 · §Examples**
+
+### 内容示例，可删除
+
+公共组件新 API 与旧 API 并存一个迁移周期，再在版本公告后删除旧 API。
+
+**源：FE 36 Feature Flag 协议 · §Examples**
+
+### 内容示例，可删除
+
+新编辑器 flag 关闭后回到旧编辑器，相关新 API 不再调用。
+
+**源：BE 32 发布、版本与回滚协议 · §Examples**
+
+- 先发布兼容读写版本，完成数据迁移后再清理旧契约。
+
+## Anti-patterns
+
+**源：FE 33 版本与发布协议 · §Anti-patterns**
+
+静态资源已回滚，但新缓存 schema 和后台任务仍不兼容旧页面。
+
+**源：FE 36 Feature Flag 协议 · §Anti-patterns**
+
+组件中散落环境判断，开关关闭后深链接仍能访问新功能。
+
+**源：BE 32 发布、版本与回滚协议 · §Anti-patterns**
+
+- 把数据库回滚等同于逆向执行破坏性 migration。
+
+## Ownership
+
+**源：FE 33 版本与发布协议 · §Ownership**
+
+发布 Owner 负责流程，模块 Owner 负责兼容，平台 Owner 负责回滚和监控。
+
+**源：FE 36 Feature Flag 协议 · §Ownership**
+
+功能 Owner 维护业务生命周期，平台 Owner 维护系统，安全/权限 Owner 审查边界。
+
+**源：BE 32 发布、版本与回滚协议 · §Ownership**
+
+发布责任人执行门禁，Backend 提供兼容与恢复证据。
+
+## Change Policy
+
+**源：FE 33 版本与发布协议 · §Change Policy**
+
+版本和发布策略变化必须同步 CI/CD、门禁、文档和责任人。
+
+**源：FE 36 Feature Flag 协议 · §Change Policy**
+
+Flag 语义和目标规则变化必须记录；转长期配置时迁移到正式配置系统。
+
+**源：BE 32 发布、版本与回滚协议 · §Change Policy**
+
+发布流程和阻断门禁变化必须通过演练与审计后生效。
+
+> **语言节**：本主题无语言节挂点（缺席诚实）；规则本体即上文通用节。

package/seeds/specs/hard/{frontend/04-security-protocol.md → themes/security.md}

@@ -1,19 +1,36 @@
 ---
-seed_source: pomaster/components/frontend-hard-spec/assets/universal/04-security-protocol.md
-seed_source_sha256: 4d9bb6bd34a64fcc3e362c969492bc326533e16ef4c6d2284dc01442733504e6
-seed_version: B6B-1
-lane: frontend
+seed_source: packages/cli/seeds/aggregation-manifest.json
+seed_source_sha256: 039b637ccffacdfe3ce30d85e193f4b38928fcdfb16efdc4eb255e35e05af91f
+seed_version: B7-THEME
+lane: [frontend, backend]
 status: CURRENT
 authority_scope: mixed_required_and_advisory
-applies_to: [frontend]
+applies_to: [frontend, backend]
 related_evidence_specs: []
 related_tools: []
+legacy_id: theme:security
+criticality: critical # 聚合注记：取源最高；info 性注记非执行语义
+injection_mode: triggered # 聚合注记：来源同值；info 性注记非执行语义
+stages: [prepare, implement, check, release] # 聚合注记：来源 stages 并集；info 性注记非执行语义
+triggers: [security, api-input, authentication, authorization, file-processing, secrets] # 聚合注记：来源 triggers 并集；info 性注记非执行语义
+requires: [] # 聚合注记：来源 requires 并集（全空）
+x-aggregation: # 聚合来源（D6）：逐源 vendor pin（sha256 与卡 vendor_pin 同值）
+  - seed_source: pomaster/components/frontend-hard-spec/assets/universal/04-security-protocol.md
+    sha256: 4d9bb6bd34a64fcc3e362c969492bc326533e16ef4c6d2284dc01442733504e6
+    seed_version: B6B-1
+  - seed_source: pomaster/components/backend-hard-spec/assets/universal/10-security-protocol.md
+    sha256: 56387f03edd35df50a5a701f4daab174b744d490663393f43331cf5401149f67
+    seed_version: B6C
 ---
 
-# 04 安全协议
+# 安全
+
+> **聚合纪律**：本文档 12 节正文规则行逐字取自 frontmatter x-aggregation 所列来源协议（节内按「端 → 源编号升序」以加粗来源行分块，源内标题与层级原样保留），零新增、零改写、零删除；新增文本仅限文档标题、本注记与逐节来源行。
 
 ## Scope
 
+**源：FE 04 安全协议（pomaster/components/frontend-hard-spec/assets/universal/04-security-protocol.md）**
+
 P0。从访问控制与威胁防御视角约束前端代码：XSS/CSRF/CSP、认证/token 生命周期、授权边界、输入校验、敏感数据脱敏、依赖与供应链、传输安全、第三方脚本/iframe/postMessage、客户端存储、错误信息泄露。本协议聚焦前端/客户端可治理项；后端安全、基础设施安全、隐私政策与组织安全流程不替代。
 
 与 `universal:16-error-handling-protocol` 的边界：安全只审计错误信息泄露风险，完整错误处理策略见 16。
@@ -22,12 +39,24 @@ P0。从访问控制与威胁防御视角约束前端代码：XSS/CSRF/CSP、认
 与 `universal:44-privacy-data-lifecycle-protocol` 的边界：数据是否该收集、保留多久由 44 负责，安全负责防止未授权访问与脱敏。
 与 `universal:45-browser-storage-protocol` 的边界：存储介质选择与隔离策略由 45 负责，安全负责凭据/敏感数据不得持久化到脚本可读存储。
 
+**源：BE 10 安全协议（pomaster/components/backend-hard-spec/assets/universal/10-security-protocol.md）**
+
+规范认证、鉴权、输入与文件校验、注入防护、密钥和安全默认值。
+
 ## Non-Scope
 
+**源：FE 04 安全协议**
+
 不替代后端鉴权、服务端校验、安全审计、基础设施安全、隐私政策和组织安全流程。
 
+**源：BE 10 安全协议**
+
+不替代隐私保留规则或具体基础设施加固 Overlay。
+
 ## Terms
 
+**源：FE 04 安全协议**
+
 - Threat Defense：防止常见 Web 攻击的纵深防御集合。
 - Dangerous Sink：把字符串解释为 HTML、脚本、URL、CSS 或导航目标的浏览器入口。
 - Sanitization：按白名单清洗不可信内容。
@@ -37,8 +66,14 @@ P0。从访问控制与威胁防御视角约束前端代码：XSS/CSRF/CSP、认
 - Sensitive Data：受隐私、业务或权限保护的数据。
 - SRI：Subresource Integrity，外部资源完整性校验。
 
+**源：BE 10 安全协议**
+
+信任边界是数据或调用从较低信任域进入较高权限域的位置。
+
 ## MUST
 
+**源：FE 04 安全协议 · §MUST**
+
 - 建立项目级安全 Owner，对 12 个安全维度（SEC-01~SEC-12）建立要求、检查点和异常审批流程。
 - 统一定义 token、cookie、CSRF、退出和刷新策略。
 - 所有输入、URL、文件名、消息和 HTML 默认不可信。
@@ -178,8 +213,14 @@ P0。从访问控制与威胁防御视角约束前端代码：XSS/CSRF/CSP、认
 - **feature 层 — 页面级安全**：每个页面声明 CSP/第三方执行/敏感字段/权限守卫需求；页面内 return URL、外链、iframe、postMessage 按白名单执行；错误展示使用归一化文案。MUST NOT 页面单独发明不兼容的 token 存储或错误格式；MUST NOT 页面直接 import 未经清单化的第三方脚本。
 - **shared 层 — 组件与工具安全**：公共组件暴露安全属性（sanitizer_policy、mask_rule、allowed_actions）；工具函数提供上下文编码/URL 白名单/敏感字段过滤。MUST NOT 把组件内部调试日志当正式安全审计；MUST NOT 在共享库中硬编码业务 secret 或页面级 capability。
 
+**源：BE 10 安全协议 · §MUST**
+
+- 所有信任边界必须执行服务端校验、最小权限、失败关闭和安全审计。
+
 ## MUST NOT
 
+**源：FE 04 安全协议 · §MUST NOT**
+
 - MUST NOT 渲染未经清洗的 HTML。
 - MUST NOT 将 secret、token 或生产凭据写入源码、URL、日志或公开变量。
 - MUST NOT 将 session identifier、refresh token 或等价凭据持久化到可被脚本读取的存储，除非存在经安全 Owner 批准且有期限的例外。
@@ -192,8 +233,14 @@ P0。从访问控制与威胁防御视角约束前端代码：XSS/CSRF/CSP、认
 - MUST NOT 加载无 SRI/无来源清单的第三方脚本或 iframe。
 - MUST NOT 用 localStorage/sessionStorage 证明身份、权限或同意状态。
 
+**源：BE 10 安全协议 · §MUST NOT**
+
+- 不得信任前端隐藏、客户端校验、代理头或用户提供的资源归属。
+
 ## SHOULD
 
+**源：FE 04 安全协议 · §SHOULD**
+
 - SHOULD 使用由 report-only 逐步收紧到 enforce 的 CSP、受控 sanitizer/Trusted Types、依赖安全扫描和短期下载 URL；CSP 是纵深防御，不能替代输出编码和净化。
 - SHOULD 对外部静态资源使用自托管、完整性校验或受控沙箱，并限制 iframe 能力和未使用的浏览器权限。
 - SHOULD 对高风险输入、文件和权限变化建立专项测试。
@@ -201,8 +248,14 @@ P0。从访问控制与威胁防御视角约束前端代码：XSS/CSRF/CSP、认
 - SHOULD 在 CI 中集成静态安全扫描（eslint-plugin-security / Semgrep）和 SCA。
 - SHOULD 将 security 需求纳入 page-tech-spec §12 非功能需求与运行边界。
 
+**源：BE 10 安全协议 · §SHOULD**
+
+- 应采用参数化接口、集中密钥管理和可轮换凭据。
+
 ## Contract
 
+**源：FE 04 安全协议 · §Contract**
+
 ```text
 SecurityRequirement, Scope, Dimension, Priority, Status, Owner,
 SanitizerPolicy, SinkAllowlist, CsrfMechanism, SameSitePolicy, CspMode,
@@ -229,8 +282,14 @@ feature, 页面级安全, 页面CSP/第三方/敏感字段/权限守卫 + return
 shared, 组件与工具安全, 组件安全属性 + 编码/白名单/过滤工具, 调试日志当安全审计 || 硬编码业务secret或capability
 ```
 
+**源：BE 10 安全协议 · §Contract**
+
+安全设计必须列出资产、威胁、控制、失败语义、日志限制和验证证据。
+
 ## Checklist
 
+**源：FE 04 安全协议 · §Checklist**
+
 - [ ] 项目级安全 Owner 已指派，12 个维度（SEC-01~SEC-12）要求/检查点/异常审批已建立。
 - [ ] XSS：不可信输入输出编码、危险 sink 管控、富文本 sanitizer/Trusted Types 已确认。
 - [ ] CSRF：状态变更请求带 token、Cookie SameSite/Secure、token 不在 URL。
@@ -246,8 +305,14 @@ shared, 组件与工具安全, 组件安全属性 + 编码/白名单/过滤工
 - [ ] 错误泄露：错误归一化、不暴露堆栈/内部路径/token/PII、监控脱敏。
 - [ ] 分层安全责任已按 app/platform/api/domain/feature/shared 分担。
 
+**源：BE 10 安全协议 · §Checklist**
+
+- [ ] 认证、鉴权、输入、输出、文件、secret 与审计路径已检查。
+
 ## Examples
 
+**源：FE 04 安全协议 · §Examples**
+
 登录表单提交后服务端返回 `HttpOnly; Secure; SameSite=Strict` 的 session cookie；前端在内存中保存短期 access token，refresh token 由后端 Cookie 存储并自动轮换；登出时调用 revoke 接口并触发 BroadcastChannel 清理所有标签页状态。
 
 搜索框输入先经前端白名单校验长度/字符集，服务端再次校验；查询参数中的关键字经 URL 编码，渲染到结果列表时经 HTML entity 编码；结果中的富文本由后端给出白名单 HTML，前端使用 DOMPurify 二次清洗并配置 Trusted Types policy。
@@ -256,8 +321,14 @@ shared, 组件与工具安全, 组件安全属性 + 编码/白名单/过滤工
 
 第三方客服 widget 必须在第三方执行清单登记，iframe 使用 `sandbox="allow-scripts"` 并限制 `allow` 权限，postMessage 仅向 `https://trusted-cdn.example.com` 发送且接收端校验 origin；widget 停用后立即从 CSP/页面中移除。
 
+**源：BE 10 安全协议 · §Examples**
+
+- 下载接口同时验证操作权限、数据范围和资源归属。
+
 ## Anti-patterns
 
+**源：FE 04 安全协议 · §Anti-patterns**
+
 把 access token 放进 URL 或 localStorage，导致 XSS 可直取凭据。
 
 前端按角色名硬编码隐藏按钮，未调用后端鉴权，用户可直接构造请求执行敏感操作。
@@ -274,10 +345,28 @@ shared, 组件与工具安全, 组件安全属性 + 编码/白名单/过滤工
 
 HTTPS 页面加载 HTTP 图片/脚本，触发混合内容并绕过 CSP 边界。
 
+**源：BE 10 安全协议 · §Anti-patterns**
+
+- 把 token、密码或敏感 payload 写入日志与异常。
+
 ## Ownership
 
+**源：FE 04 安全协议 · §Ownership**
+
 安全 Owner 负责政策、12 维度基线和异常审批；平台 Owner 负责 CSP/安全头/HTTP client 安全拦截；业务与后端 Owner 负责数据权限与后端强制；前端 Owner 负责页面级安全呈现与组件安全属性；DevOps Owner 负责传输层与证书管理。
 
+**源：BE 10 安全协议 · §Ownership**
+
+服务端拥有最终安全判断，安全评审者维护阻断门禁。
+
 ## Change Policy
 
+**源：FE 04 安全协议 · §Change Policy**
+
 任何安全放宽必须经过风险评估、批准和期限；高危问题修复优先于交互便利性。新增第三方脚本、放宽 CSP、引入新的 token 存储方式、允许敏感字段明文展示或改变默认安全失败模式，必须走 `universal:change-governance-protocol` 的受控变更流程。
+
+**源：BE 10 安全协议 · §Change Policy**
+
+放宽安全控制必须经过显式风险审批、范围限制和到期复审。
+
+> **语言节**：本主题无语言节挂点（缺席诚实）；规则本体即上文通用节。