@umacloud/knowledge 1.0.15 → 1.0.16

package/experts/product-manager/prd-template-and-structure.md

@@ -0,0 +1,144 @@
+---
+id: prd-template-and-structure
+title: Product Manager — PRD Template & Structure (EARS-anchored)
+domain: experts
+category: product-manager
+difficulty: intermediate
+tags: [prd, product-requirements, template, ears, acceptance-criteria, scope, traceability, definition-of-done, writing]
+quality_score: 95
+last_updated: 2026-06-29
+---
+# Product Manager — PRD Template & Structure (EARS-anchored)
+
+> A PRD is not a pitch deck and not a wish list. It is the **contract between
+> intent and implementation**: a document an engineer can build from, a QA can
+> test against, and a stakeholder can sign off on — without a meeting to decode
+> it. A commercial-grade PRD anchors every requirement in the structured
+> acceptance syntax (see `experts/product-manager/requirements-engineering-ears`)
+> so that *what we are building* and *how we will know it works* are the same
+> artifact, not two documents that drift apart.
+
+## 1. What a PRD must do
+
+A PRD earns its place only if it answers five questions unambiguously:
+
+- **Why** — the problem, who has it, and why now (the case for building at all).
+- **What** — the requirements, each atomic, triggered, and testable.
+- **What not** — explicit out-of-scope, so scope creep is visible.
+- **How we'll know** — acceptance criteria and success metrics with numbers.
+- **What it touches** — data, contracts, dependencies, and risks.
+
+A PRD that reads beautifully but cannot be turned into test cases has failed,
+no matter how polished the prose.
+
+## 2. The PRD skeleton
+
+Fill every section. "N/A" is an acceptable answer; a blank is not — a blank
+means the question was never asked.
+
+| # | Section | Content |
+|---|---|---|
+| 1 | **Summary** | One paragraph: what this is, for whom, and the outcome. Readable by someone outside the team. |
+| 2 | **Problem & context** | The user problem, evidence it's real (data/research, not opinion), and why now. |
+| 3 | **Goals & non-goals** | Goals as measurable outcomes; non-goals as explicit exclusions. |
+| 4 | **Success metrics** | The numbers that define success + how each is measured (see §5). |
+| 5 | **Users & scenarios** | Target users/personas and the key scenarios (jobs to be done). |
+| 6 | **Requirements** | The core: structured functional requirements + acceptance criteria (see §3). |
+| 7 | **Non-functional requirements** | Performance, availability, security, accessibility, privacy — each with a number and a method. |
+| 8 | **Scope** | In-scope this release vs out-of-scope / later, stated explicitly. |
+| 9 | **Dependencies & risks** | Upstream/downstream systems, data, teams; risks with mitigation. |
+| 10 | **Data & contract impact** | New/changed data, API/contract changes, migration and privacy implications. |
+| 11 | **Rollout & success gate** | How it ships (flagged/phased), what metric gates each stage, how it rolls back. |
+| 12 | **Open questions** | Unresolved decisions with an owner and a needed-by date. |
+| 13 | **Traceability** | The matrix tying requirement → criteria → design/API → tests (see §6). |
+
+## 3. The heart: requirements + acceptance criteria
+
+Every functional requirement is written in one of the five structured patterns
+(ubiquitous / event-driven / state-driven / unwanted-behavior / optional-feature)
+and immediately followed by its acceptance criteria in Given–When–Then form.
+The requirement says *what must hold*; the criteria enumerate *the cases that
+prove it*. Use this block, repeated per requirement:
+
+```
+### FR-012  Checkout creates exactly one order
+
+Requirement (event-driven):
+  When a signed-in user submits the checkout form with a valid card,
+  the system shall create one order, charge the card exactly once,
+  and return HTTP 201 with the order id.
+
+Acceptance criteria:
+  - Given a valid cart and card, when checkout is submitted,
+    then an order is created and HTTP 201 with orderId is returned.
+  - Given the same idempotency key is replayed, when checkout is submitted twice,
+    then exactly one order and one charge exist.
+  - Given the card is declined, when checkout is submitted,
+    then no order is created and the decline reason is shown (HTTP 402).
+  - Given the network drops after charge but before response, when the client retries,
+    then no second charge occurs.
+
+Out of scope: saved-card management; partial refunds.
+```
+
+Mandatory case coverage per requirement — enumerate criteria across:
+**happy path · boundary values · error/unwanted · permission · concurrency ·
+state (empty/loading/partial/stale) · idempotency**. A requirement with only a
+happy path is not ready.
+
+## 4. Goals and non-goals (kill scope creep early)
+
+| Goal (measurable outcome) | Non-goal (explicit exclusion) |
+|---|---|
+| Reduce checkout abandonment by 15% in 90 days | Redesigning the cart UI |
+| Support guest checkout end to end | Loyalty/points integration (next release) |
+
+Rules: goals are **outcomes** (a metric moves), not outputs ("build a button");
+every non-goal prevents a future "but I assumed…" argument.
+
+## 5. Success metrics (numbers, not adjectives)
+
+| Metric | Target | How measured | Guardrail |
+|---|---|---|---|
+| Checkout completion rate | +15% vs baseline | Funnel analytics, 90-day window | No drop in payment success rate |
+| Checkout p95 latency | < 800ms | Server metrics | — |
+
+Every product metric needs a **guardrail metric** — a thing that must *not*
+get worse while you optimize the target (e.g., don't raise conversion by
+hiding fees). State the baseline; "improve" without a baseline is unfalsifiable.
+
+## 6. Traceability matrix
+
+The PRD ships (or generates) a matrix so coverage gaps are visible at a glance:
+
+| Req ID | Requirement (structured) | Acceptance criteria | Design/API | Tests | Status |
+|---|---|---|---|---|---|
+| FR-012 | When … shall create one order … | AC-012a..d | `POST /orders` | T-101..104 | Ready |
+
+Rules: every requirement has ≥1 criterion and ≥1 planned test; every screen and
+endpoint traces back to a requirement (no orphan features); a requirement with
+no test is not shippable, a test with no requirement is scope creep — resolve, don't ignore.
+
+## 7. Definition of Ready (the PRD may enter build only if)
+
+- [ ] Problem stated with evidence; goals are measurable outcomes; non-goals explicit.
+- [ ] Every functional requirement in a structured pattern (atomic, triggered, observable).
+- [ ] Acceptance criteria enumerated across happy/boundary/error/permission/concurrency/state/idempotency.
+- [ ] NFRs carry numbers and a measurement method (no "fast", "secure", "intuitive").
+- [ ] Scope: in-scope vs out-of-scope stated; dependencies and risks identified.
+- [ ] Data/contract/migration/privacy impact described.
+- [ ] Rollout + rollback + success-gate metrics defined.
+- [ ] Open questions each have an owner and a needed-by date.
+- [ ] Traceability matrix present; no orphan features, no untested requirements.
+
+## 8. Anti-patterns (reject in review)
+
+1. **Solution-as-requirement** — "use a modal / use React" in a requirement; that's design, decided later.
+2. **Adjective acceptance** — "should be fast/intuitive" with no observable, measurable outcome.
+3. **Happy-path-only** — no error, boundary, permission, or concurrency criteria.
+4. **No non-goals** — everything is implicitly in scope, so scope creep is invisible.
+5. **Output goals** — "ship a settings page" instead of the outcome it should produce.
+6. **Vanity metric, no guardrail** — optimize one number while quietly degrading another.
+7. **Orphan feature** — a screen/endpoint with no requirement behind it.
+8. **Drift** — acceptance criteria live in a separate doc and fall out of sync with the requirement.
+9. **Blank ≠ N/A** — sections silently skipped, so unasked questions surface mid-build.

package/experts/product-manager/requirements-engineering-ears.md

@@ -0,0 +1,133 @@
+---
+id: requirements-engineering-ears
+title: Product Manager — Structured Acceptance Syntax (EARS Patterns)
+domain: experts
+category: product-manager
+difficulty: intermediate
+tags: [acceptance, criteria, ears, product, requirements, specification, traceability, writing]
+quality_score: 95
+last_updated: 2026-06-29
+---
+# Product Manager — Structured Acceptance Syntax (EARS Patterns)
+
+> Free-text requirements ("the system should be fast and user-friendly") cannot
+> be tested, estimated, or signed off. A commercial-grade PRD writes every
+> requirement in a **constrained sentence syntax** so it is unambiguous,
+> singular, and verifiable. This is the bridge between a product idea and a
+> test case.
+
+## 1. Why a constrained syntax
+
+Natural-language requirements fail in four predictable ways: they are
+**ambiguous** (multiple readings), **compound** (several requirements in one
+sentence), **untestable** (no observable outcome), or **silent on triggers and
+preconditions** (when does this apply?). A structured syntax removes all four by
+forcing every requirement into one of five fixed shapes, each with an explicit
+trigger, an explicit subject (the system), and an explicit, observable response.
+
+A requirement is well-formed only if it is:
+- **Atomic** — exactly one testable behavior (no "and"/"also" hiding a second requirement).
+- **Triggered** — states the precondition or event under which it applies.
+- **Observable** — the response is something a test can assert (status code, value, state, screen).
+- **Unconditionally testable** — no vague adjectives ("fast", "intuitive", "robust").
+
+## 2. The five sentence patterns
+
+Use exactly one keyword per pattern. The subject is always the system (or a named component).
+
+| Pattern | Shape | Use when |
+|---|---|---|
+| **Ubiquitous** | `The <system> shall <response>.` | An always-true invariant, no trigger. |
+| **Event-driven** | `When <trigger>, the <system> shall <response>.` | A discrete event causes a response. |
+| **State-driven** | `While <state>, the <system> shall <response>.` | A behavior holds for the duration of a state. |
+| **Unwanted-behavior** | `If <unwanted condition>, then the <system> shall <response>.` | Error, abuse, or failure handling. |
+| **Optional-feature** | `Where <feature is present>, the <system> shall <response>.` | Behavior only when a feature/config is enabled. |
+| **Complex** | Combine keywords: `While <state>, when <trigger>, the <system> shall <response>.` | A trigger that only applies in a state. |
+
+### Examples (vague → structured)
+
+| Vague | Structured |
+|---|---|
+| "Login should be secure." | **If** 5 failed login attempts occur from one account within 10 minutes, **then** the system **shall** lock the account for 15 minutes and return HTTP 429. |
+| "The dashboard should load fast." | **When** a signed-in user requests `/dashboard`, the system **shall** return First Contentful Paint under 1.5s on a 4G connection at the 75th percentile. |
+| "Handle payment failures gracefully." | **If** the payment provider returns a decline, **then** the system **shall** preserve the cart, display the provider's decline reason, and **shall not** charge the card. |
+| "Show notifications." | **Where** browser push is enabled, **when** an order ships, the system **shall** deliver a push notification within 60 seconds. |
+| "Search should work." | **When** a user submits a query of 1–256 characters, the system **shall** return matching results ranked by relevance within 300ms p95. |
+
+## 3. From requirement to acceptance criteria
+
+Each structured requirement expands into concrete acceptance criteria in
+**Given–When–Then** form — the executable companion of the requirement. The
+requirement says *what must hold*; the criteria enumerate the *cases that prove it*.
+
+**Requirement (event-driven):**
+> When a user submits the checkout form with a valid card, the system shall create the order, charge the card exactly once, and return HTTP 201 with the order id.
+
+**Acceptance criteria:**
+- Given a valid cart and card, when checkout is submitted, then an order is created and HTTP 201 with `orderId` is returned.
+- Given the same idempotency key is replayed, when checkout is submitted twice, then exactly one order and one charge exist.
+- Given the card is declined, when checkout is submitted, then no order is created and the decline reason is shown (HTTP 402).
+- Given the network drops after charge but before response, when the client retries, then no second charge occurs.
+
+Every criterion must be **independently verifiable** and map to at least one
+automated test. A requirement with zero acceptance criteria is not done; it is a wish.
+
+## 4. Mandatory case coverage per requirement
+
+For every requirement, the PRD must enumerate criteria across these axes (the
+same edge-case discipline applied to specification, not just QA):
+
+- **Happy path** — the normal success case.
+- **Boundary values** — 0, 1, max, max+1, empty, negative, oversize.
+- **Error / unwanted** — invalid input, missing fields, downstream failure, timeout.
+- **Permission** — unauthenticated, authenticated-but-forbidden, owner vs non-owner.
+- **Concurrency** — duplicate submit, race, stale read, double-click.
+- **State** — empty (no data yet), loading, partial, deleted/stale.
+- **Idempotency** — safe to retry; replays produce one effect.
+
+## 5. Non-functional requirements are requirements too
+
+NFRs use the same syntax and must carry a number and a measurement method —
+never an adjective.
+
+| Category | Structured NFR | How to verify |
+|---|---|---|
+| Performance | When a list endpoint is called, the system shall respond within 200ms p95. | Load test + server metrics |
+| Availability | The system shall sustain 99.9% monthly uptime. | Uptime monitor + error budget |
+| Capacity | While under 1000 concurrent users, the system shall keep error rate below 0.1%. | Load test |
+| Security | The system shall reject any request without a valid token with HTTP 401. | Automated auth test |
+| Accessibility | The system shall meet AA contrast and full keyboard operability on all interactive elements. | Automated a11y scan + manual keyboard pass |
+| Privacy | The system shall encrypt personal data at rest and in transit. | Config audit + scan |
+
+## 6. Traceability matrix
+
+Every requirement is traceable end to end. A commercial PRD ships (or generates)
+a matrix so coverage gaps are visible:
+
+| Req ID | Requirement (structured) | Acceptance criteria | Design/API | Test cases | Status |
+|---|---|---|---|---|---|
+| FR-012 | When … shall create the order … | AC-012a..d | `POST /orders` | T-101..104 | Done |
+
+Rules:
+- Every requirement ID has ≥1 acceptance criterion and ≥1 test case.
+- Every API endpoint and screen traces back to a requirement (no orphan features).
+- A requirement with no test is **not** shippable; a test with no requirement is **scope creep** — resolve, don't ignore.
+
+## 7. Definition of Ready (a requirement may enter a sprint only if)
+
+- [ ] Written in one of the five structured patterns (atomic, triggered, observable).
+- [ ] Acceptance criteria enumerated across happy / boundary / error / permission / concurrency.
+- [ ] Non-functional targets stated with numbers and a measurement method.
+- [ ] Out-of-scope explicitly listed (what this requirement does **not** cover).
+- [ ] Dependencies and data/contract impacts identified.
+- [ ] No vague adjectives remain ("fast", "easy", "nice", "secure", "robust").
+
+## 8. Anti-patterns (reject in review)
+
+1. **Compound requirement** — one sentence hiding two behaviors joined by "and".
+2. **Solutioning** — "use a dropdown" / "use React" in a requirement (that's design, not requirement).
+3. **Adjective acceptance** — "should be intuitive" with no observable outcome.
+4. **Happy-path only** — no error, boundary, or permission criteria.
+5. **Untriggered** — no precondition, so the reader can't tell when it applies.
+6. **Unmeasurable NFR** — "should be fast" with no number, percentile, or method.
+7. **Orphan feature** — a screen or endpoint with no requirement behind it.

package/experts/qa-lead/test-plan-template.md

@@ -0,0 +1,127 @@
+---
+id: test-plan-template
+title: QA Lead — Risk-Based Test Plan Template
+domain: experts
+category: qa-lead
+difficulty: intermediate
+tags: [acceptance, criteria, defect, experts, qa, risk, test-plan, traceability]
+quality_score: 95
+last_updated: 2026-06-29
+---
+# QA Lead — Risk-Based Test Plan Template
+
+> A test plan is not "we will test everything." It is a **risk-prioritized,
+> traceable contract** stating what will be tested, to what depth, in which
+> environment, and the explicit criteria for declaring a release ready. Effort
+> follows risk: the highest-risk flows get the deepest coverage.
+
+## 1. Scope
+
+State precisely, in two lists:
+- **In scope** — features, flows, endpoints, platforms, and quality attributes (functional, performance, security, accessibility, compatibility) this plan covers.
+- **Out of scope** — what this plan deliberately does **not** cover, and why (covered elsewhere, accepted risk, future iteration). An unstated exclusion is a coverage gap waiting to surprise you.
+
+## 2. Risk-based prioritization
+
+Rank every feature/flow by **risk = likelihood of failure × impact of failure**.
+Allocate test depth by risk tier, not uniformly.
+
+| Risk tier | Examples | Depth |
+|---|---|---|
+| Critical | Auth, payments, data integrity, anything irreversible or money-moving | Exhaustive: happy + all boundaries + all error/abuse paths + concurrency + E2E |
+| High | Core user journeys, permission boundaries, data export/import | Happy + key boundaries + main error paths + E2E smoke |
+| Medium | Secondary features, admin tools | Happy + obvious errors |
+| Low | Cosmetic, rarely used, low blast radius | Smoke / spot check |
+
+Impact axes to weigh: money loss, data loss/corruption, security/privacy breach,
+legal/compliance, number of users affected, reversibility, brand/trust.
+
+## 3. Test approach per layer
+
+Map each area to the right test layer (test each layer at the right altitude — see `testing/01-standards/test-strategy-and-layering`):
+
+| Layer | What is verified here | Type |
+|---|---|---|
+| Domain logic | Business rules, invariants, state machines, calculations | Unit (no IO) |
+| Application/service | Use-case orchestration, transactions, error paths (deps mocked) | Unit / integration |
+| Persistence | Real reads/writes, mapping, query correctness | Integration (real DB) |
+| API/interface | Routing, validation, status codes, error envelope, authz | Integration / contract |
+| Cross-cutting | Performance, security, accessibility, compatibility | Specialized suites |
+| Critical journeys | Signup → core action → checkout, with key failures | E2E |
+
+## 4. Entry and exit criteria
+
+Make "ready to test" and "ready to ship" objective, not a feeling.
+
+**Entry criteria (testing may begin when):**
+- [ ] Requirements have structured, testable acceptance criteria.
+- [ ] Build deploys to a test environment and boots cleanly.
+- [ ] Test data and accounts are available; dependencies/stubs are up.
+- [ ] Smoke test of the critical path passes (no point deep-testing a dead build).
+
+**Exit criteria (release is ready when):**
+- [ ] 100% of critical and high acceptance criteria pass.
+- [ ] No open critical/blocker defects; high defects triaged with a decision.
+- [ ] Coverage thresholds met (variance and diff coverage — see `testing/01-standards/ci-test-gates-and-coverage`).
+- [ ] Performance, security, and accessibility checks pass their budgets.
+- [ ] No unexplained flaky tests in the required suite.
+- [ ] Rollback procedure documented and verified.
+
+## 5. Traceability matrix
+
+Prove coverage end to end — every requirement maps to acceptance criteria to test cases, with no orphans either way.
+
+| Req ID | Acceptance criteria | Test case IDs | Layer | Risk | Status |
+|---|---|---|---|---|---|
+| FR-012 | AC-012a..d | T-101..104 | API + E2E | Critical | Pass |
+
+Rules:
+- Every acceptance criterion has ≥1 test case (no untested requirement).
+- Every test case traces to a requirement (no test for a feature nobody asked for).
+- Coverage gaps (a requirement with no test) are visible and block exit.
+
+## 6. From acceptance criteria to test cases
+
+Each criterion expands into multiple cases across the standard axes — happy,
+boundary, error, permission, concurrency, state. Example for a login criterion:
+
+1. Valid credentials → success + redirect.
+2. Wrong password → generic error (no user enumeration).
+3. Non-existent user → same generic error.
+4. Empty/invalid-format fields → field validation.
+5. N failed attempts → lockout + 429.
+6. Injection / script in fields → sanitized, no execution.
+7. Concurrent duplicate submit → one session, no double effect.
+8. Redirect back to originally requested page after login.
+
+## 7. Defect severity and triage
+
+Classify every defect; severity drives whether it blocks release.
+
+| Severity | Definition | Release impact |
+|---|---|---|
+| Blocker | Core flow unusable, data loss, security hole, money error | Must fix before ship |
+| Critical | Major feature broken, no acceptable workaround | Must fix or formally accept |
+| Major | Feature impaired, workaround exists | Fix soon; may ship with sign-off |
+| Minor | Cosmetic, edge inconvenience | Backlog |
+
+A defect report must be reproducible: steps, expected vs actual, environment,
+build/version, evidence (logs/screenshot), and severity. "It doesn't work" is not a defect report.
+
+## 8. Environments and test data
+
+- Test in an environment that mirrors production (config, dependencies, data shape).
+- Use isolated, disposable test data per case; never depend on shared mutable state or execution order.
+- Anonymize any production-derived data; never test against real personal data.
+- Make non-determinism controllable: injectable clock, fixed seeds, stable ordering.
+
+## 9. Test plan checklist (the plan is ready when)
+
+- [ ] In-scope and out-of-scope explicitly listed.
+- [ ] Every feature risk-tiered; depth allocated by risk.
+- [ ] Each area mapped to the correct test layer.
+- [ ] Entry and exit criteria defined and objective.
+- [ ] Traceability matrix links requirements ↔ acceptance ↔ tests.
+- [ ] Non-functional coverage (perf/security/a11y/compat) planned with budgets.
+- [ ] Defect severity scale and triage path agreed.
+- [ ] Environments, test data, and rollback verification covered.

package/frontend/01-standards/accessibility-acceptance-gate.md

@@ -0,0 +1,91 @@
+---
+id: accessibility-acceptance-gate
+title: 无障碍验收门禁规范（WCAG 作为可阻断的上线门，商业级必读）
+domain: frontend
+category: 01-standards
+difficulty: advanced
+tags: [accessibility, a11y, wcag, acceptance-gate, ship-blocker, keyboard, screen-reader, contrast, focus, acceptance-criteria, audit, 无障碍, 验收门禁, 上线阻断, 可达性, 键盘, 屏幕阅读器, 商业级]
+quality_score: 95
+last_updated: 2026-06-29
+---
+# 无障碍验收门禁规范（商业级必读）
+
+> 无障碍不是上线后"有空再补"的优化项，而是和"功能能不能用、安全过不过"同级的**验收门**。"我们关注无障碍"这种软承诺没有意义——AI 生成与赶工的 UI 几乎必然漏掉键盘、焦点、对比度和标签。
+> 这份规范把无障碍从"指南"升级成**可阻断上线的门禁**：每条要求都给出**可判定的验收标准 + 验证方法 + 严重度 + 是否阻断发布**。怎么写无障碍代码见 `frontend/01-standards/accessibility-standard` 与 `frontend/02-playbooks/accessibility-a11y-playbook`；本规范回答的是"做到什么程度才允许发版"。
+
+## 1. 门禁目标与适用
+
+- **目标等级**：交互式 Web 产品对齐 **WCAG 2.x AA**。这是商业产品的合规基线（多地法规要求）与用户覆盖问题，不是加分项。
+- **适用范围**：所有面向用户的页面与组件——尤其是注册/登录、表单、结算/支付、核心任务流。后台/内部系统同样适用（员工里也有依赖辅助技术的人）。
+- **门禁含义**：存在**阻断级（Blocker）**问题 → 不允许上线，必须修复后重验；**严重级（Critical）**问题需带期限的整改承诺方可放行；其余记入待办。
+
+## 2. 验收维度与可判定标准
+
+每条都必须是**可判定的**（能明确判通过/不通过），而不是"尽量做到"。
+
+| 维度 | 验收标准（通过条件） | 验证方法 | 严重度 |
+|---|---|---|---|
+| 键盘可达 | 所有交互能力纯键盘完成，无鼠标依赖；无键盘陷阱 | 拔鼠标走查全流程 | Blocker |
+| 焦点可见 | 每个可聚焦元素有清晰可见焦点指示；焦点顺序符合视觉/逻辑顺序 | 键盘 Tab 走查 | Blocker |
+| 焦点管理 | 弹窗/抽屉打开聚焦其内、关闭归还触发元素、有焦点陷阱；动态内容焦点不丢 | 键盘 + 屏幕阅读器 | Critical |
+| 文本替代 | 有意义图片有 alt，装饰图片 alt 为空/隐藏；图标按钮有可访问名 | 自动扫描 + 人工核 | Critical |
+| 表单可达 | 每个输入有关联 `<label>`；错误以文本+程序化方式提示并指向出错字段 | 屏幕阅读器走查表单 | Blocker |
+| 对比度 | 正文文本 ≥ 4.5:1，大字 ≥ 3:1，UI 组件/状态边界 ≥ 3:1 | 对比度工具量测 | Critical |
+| 语义结构 | 正确标题层级（单 h1、不跳级）、地标区域、列表/表格用语义元素 | 自动扫描 + 人工核 | Critical |
+| 屏幕阅读器可用 | 核心任务流用屏幕阅读器能独立完成，朗读内容准确、无"未标记按钮" | 屏幕阅读器端到端走查 | Blocker |
+| 动态更新可感知 | 异步结果/错误/提示通过 live region 播报，不只视觉变化 | 屏幕阅读器走查 | Critical |
+| 不只靠颜色 | 状态/错误/必填不仅用颜色区分，另有文本/图标/形状 | 人工核 + 灰度模拟 | Critical |
+| 触控目标 | 触控目标足够大且有间距，避免误触 | 人工核 / 量测 | Minor |
+| 缩放与回流 | 放大到 200% 文本不截断、不重叠、不丢功能 | 浏览器缩放走查 | Critical |
+| 动效安全 | 尊重"减少动态效果"偏好；无强闪烁内容 | 人工核 + 偏好设置 | Critical |
+
+## 3. 验证方法（自动 + 人工，缺一不可）
+
+自动化只能覆盖一部分问题，**键盘、焦点、屏读语义、对比语境这些必须人工**：
+
+- **自动扫描进 CI**：把无障碍静态/运行时扫描接入构建，对关键页面跑无障碍断言。自动扫描**0 阻断违规**作为流水线门禁的一道。
+- **键盘走查**：拔掉鼠标，纯键盘完成每条核心任务流——这一关挡掉的问题最多。
+- **屏幕阅读器走查**：用真实屏幕阅读器端到端走核心任务流，听朗读是否准确、是否出现"未命名按钮/图片"。
+- **对比度量测**：对文本与 UI 组件量测对比度，不靠肉眼。
+- **缩放/回流走查**：200% 缩放与窄视口下验证不丢功能、不重叠。
+- **纳入设计验收**：组件态（hover/focus/error/disabled）的可达性在设计评审就锁定，不留到实现后返工。
+
+## 4. 严重度与发布判定
+
+| 严重度 | 定义 | 发布判定 |
+|---|---|---|
+| Blocker | 整类用户**完全无法**完成核心任务（如纯键盘无法下单、屏读无法填表） | 阻断上线，修复后重验 |
+| Critical | 严重妨碍但有勉强可行路径（对比不足、焦点丢失、错误未播报） | 需带期限整改承诺方可放行 |
+| Minor | 体验受损但不阻断完成 | 记入待办，排期处理 |
+
+判定原则：**核心任务流（注册/登录/支付/关键转化）的 Blocker 与 Critical 一律不放过**；门禁结果与证据（走查记录、扫描报告）随发布留痕，可审计。
+
+## 5. 落地到交付流程
+
+- **设计阶段**：在 UIUX 文档里就规定对比度、焦点态、键盘交互、错误提示方式，作为设计验收项。
+- **实现阶段**：组件默认带语义与焦点态；CI 跑自动无障碍断言，阻断违规即红。
+- **测试阶段**：核心流的键盘 + 屏读人工走查列入测试用例，不是"有空看看"。
+- **发布门**：把"无障碍门禁通过"列入生产就绪审查（见 `operations/01-standards/production-readiness-review`）的必过项之一。
+- **回归保护**：核心交互的无障碍断言进自动化回归，防止后续改动悄悄破坏。
+
+## 6. 反模式（出现即不合格）
+
+1. **把无障碍当上线后再补**：没有门、没有判定，"关注一下"等于不做。
+2. **只跑自动扫描就签字**：忽略键盘/焦点/屏读语义——这些自动化测不全。
+3. **`div` 当按钮 + `outline:none`**：丢失原生键盘/焦点/角色，又不补替代。
+4. **只用颜色表达状态**：错误/必填/状态仅靠红绿，色觉障碍用户无法分辨。
+5. **图标按钮无可访问名**：屏读只念"按钮"，用户不知道是干嘛的。
+6. **弹窗不管焦点**：打开焦点不进、关闭不归还、无焦点陷阱，键盘用户迷路。
+7. **动态结果只改视觉**：异步成功/失败不播报，屏读用户毫无感知。
+8. **门禁可绕过**：定了门禁却不强制，开发学会跳过，等于没有。
+
+## 7. 最低交付 checklist
+
+- [ ] 明确目标等级（AA）与适用范围，门禁判定规则（Blocker 阻断/Critical 带期限/Minor 排期）写清。
+- [ ] 每个验收维度有可判定标准、验证方法与严重度，不用"尽量"措辞。
+- [ ] 自动无障碍扫描进 CI，关键页 0 阻断违规作为门禁一道。
+- [ ] 核心任务流完成纯键盘走查与屏幕阅读器端到端走查并留证。
+- [ ] 文本对比度量测达标；200% 缩放不丢功能；状态不只靠颜色。
+- [ ] 弹窗/动态内容焦点管理与 live region 播报验证通过。
+- [ ] 无障碍门禁通过列入生产就绪审查必过项；核心交互断言进回归。
+- [ ] 设计阶段即锁定对比度/焦点态/键盘交互/错误提示方式。

package/frontend/01-standards/accessibility-complete.md

@@ -5,8 +5,8 @@ domain: frontend
 category: 01-standards
 difficulty: intermediate
 tags: [accessibility, aria, complete, frontend, html, 屏幕阅读器优化, 属性, 概述]
-quality_score: 70
-last_updated: 2026-06-15
+quality_score: 90
+last_updated: 2026-06-29
 ---
 # Web 无障碍完整指南
 
@@ -402,7 +402,7 @@ function DropdownMenu({ items }: { items: MenuItem[] }) {
   padding-left: 12px;
 }
 .error::before {
-  content: "⚠ ";
+  content: "! ";
 }
 ```
 

package/frontend/01-standards/ui-states-and-resilient-data-fetching.md

@@ -0,0 +1,97 @@
+---
+id: ui-states-and-resilient-data-fetching
+title: UI 状态与健壮数据获取规范（商业级前端必读）
+domain: frontend
+category: 01-standards
+difficulty: intermediate
+tags: [ui-states, loading, empty, error, optimistic-update, data-fetching, retry, resilience, 状态, 商业级]
+quality_score: 95
+last_updated: 2026-06-29
+---
+# UI 状态与健壮数据获取规范（商业级前端必读）
+
+> 区分"demo 级"和"商业级"前端的，不是动效，而是**对每一种状态的处理**：加载、空、错误、部分、离线、并发。
+> 只画 happy path（有数据、网络好、不点重复）的界面，一上真实网络就白屏、转圈卡死、数据错乱。
+> 每个会取数或提交的界面，都必须显式设计完整的状态矩阵。
+
+## 1. 状态矩阵（每个数据视图都要覆盖）
+
+任何"从后端取数据"的视图，至少要显式处理这些状态——缺一即不合格：
+
+| 状态 | 含义 | UI 要求 |
+|---|---|---|
+| Loading（首次）| 还没有数据 | 骨架屏/占位，**不要**只放一个居中转圈占满屏 |
+| Loading（刷新）| 已有旧数据、在拉新 | 保留旧内容 + 局部加载指示（不闪白） |
+| Empty | 请求成功但无数据 | 友好空态：说明 + 引导操作（"还没有订单，去下单"），区分"无数据"与"加载中" |
+| Partial | 部分成功/分页中 | 显示已有 + "加载更多"/继续指示 |
+| Error | 请求失败 | 明确错误信息 + **重试按钮**，不要白屏或一直转 |
+| Success | 正常有数据 | 正常渲染 |
+| Forbidden | 无权限 | 明确"无权限"而非空态或报错 |
+| Offline | 无网络 | 离线提示 + 恢复后自动/手动重试 |
+
+**反模式**：把 Empty 当 Loading（无数据时永远转圈）、把 Error 当 Empty（失败却显示"暂无数据"误导用户）、加载时整屏白屏闪烁。
+
+## 2. 加载体验
+
+- **骨架屏优先**：列表/卡片/详情用与最终布局一致的骨架占位，避免布局跳动（CLS）。
+- **保留旧数据刷新**：翻页/筛选/轮询时保留当前内容做局部 loading，别清空成白屏（stale-while-revalidate 思路）。
+- **延迟显示 loading**：极快的请求（<300ms）可不显示 spinner，避免"闪一下"的抖动；超过阈值才显示。
+- **防止布局跳动**：为图片/异步内容预留尺寸，占位与真实内容同尺寸。
+
+## 3. 错误处理
+
+- **永远有出路**：任何错误态都要给"重试"或"返回"，绝不留死界面。
+- **可理解的信息**：把后端错误信封（`code/message`）映射成用户能懂的话；不要把原始 500 堆栈/技术错误码甩给用户。
+- **就近显示**：表单字段错误显示在字段旁，全局错误用 toast/横幅；区分"可重试的系统错误"和"用户需修正的输入错误"。
+- **错误边界（error boundary）**：组件级渲染异常要被边界捕获，降级为局部错误块，**不要整页崩白**。
+- **超时也是错误**：请求设超时，超时给明确反馈与重试，不要无限转圈。
+
+## 4. 健壮的数据获取
+
+- **客户端重试**：对幂等的 GET 失败做有限次指数退避+抖动重试；非幂等提交不自动重试（需幂等键，见 `backend/01-standards/idempotency-and-safe-retries`）。
+- **请求竞态（latest-wins）**：快速切换筛选/搜索时，旧请求的响应可能后到并覆盖新结果——必须取消过期请求或丢弃过期响应（按发起序号/AbortController），保证"显示的是最后一次请求的结果"。
+- **缓存与重验证**：列表数据可缓存并在后台重验证（stale-while-revalidate），先给旧值再悄悄刷新，提升感知速度。
+- **去抖/节流**：搜索框输入去抖（debounce），滚动/resize 节流，避免请求风暴。
+- **分页/无限滚动**：明确"加载更多/到底了/加载失败可重试"三态，别静默停住。
+
+## 5. 提交与乐观更新
+
+- **防重复提交**：提交中禁用按钮 + 显示进行态；双击/回车连发只触发一次。配合服务端幂等。
+- **乐观更新要可回滚**：先更新 UI 再发请求时，必须保存前值，**失败回滚**并提示，绝不让界面停留在"假成功"。
+- **明确的提交结果**：成功给确认（toast/跳转），失败保留用户输入（别清空表单）+ 显示原因。
+- **长操作**：耗时操作给进度/可取消，而不是冻结界面。
+
+## 6. 表单状态
+
+- 校验分层：即时（失焦校验单字段）+ 提交时整体校验；错误就近显示。
+- 提交中：禁用提交、显示 loading、阻止重复提交。
+- 失败：保留已填数据，定位到第一个错误字段。
+- 离开未保存：脏表单离开前提示，避免误丢输入。
+
+## 7. 可访问性与状态
+
+- 加载/错误/成功要对辅助技术可感知：用 `aria-live` 通知动态变化，loading 用 `aria-busy`，错误关联到字段（`aria-describedby`）。
+- 焦点管理：错误后把焦点移到错误区/首个错误字段；模态打开/关闭正确收发焦点。
+- 不要只用颜色传达状态（红=错），要有文字/图标兜底。
+
+## 8. 反模式（出现即不合格）
+
+1. **只做 happy path**：无 empty/error/loading 处理，真实网络下白屏或转圈不止。
+2. **空态当加载**：无数据时永远 spinner。
+3. **错误吞掉**：catch 后什么都不显示，用户面对死界面。
+4. **整页崩白**：单个组件抛错拖垮整页（无 error boundary）。
+5. **请求竞态覆盖**：快速切换后显示的是旧请求的结果。
+6. **乐观更新不回滚**：失败后界面停在假成功。
+7. **可重复提交**：双击下单两次、扣两次款。
+8. **加载闪白/布局跳动**：刷新清空内容、异步内容撑开布局。
+
+## 9. 最低交付 checklist
+
+- [ ] 每个取数视图覆盖 loading/empty/error/partial/forbidden/offline 全状态。
+- [ ] 错误态都有重试出口，错误信息对用户可理解。
+- [ ] 首次加载用骨架屏，刷新保留旧数据不闪白。
+- [ ] 组件级 error boundary 防整页崩。
+- [ ] 取数处理请求竞态（latest-wins / 取消过期请求）。
+- [ ] 提交防重复 + 乐观更新可回滚 + 失败保留输入。
+- [ ] 幂等的失败有限重试（退避+抖动），非幂等不自动重试。
+- [ ] 状态变化对辅助技术可感知（aria-live/focus 管理）。

package/high-quality-engineering-playbook.md

@@ -7,7 +7,7 @@ tags: [engineering, high, high-quality-engineering-playbook.md, playbook, qualit
 quality_score: 70
 last_updated: 2026-06-15
 ---
-# 开发：Excellent（11964948@qq.com）
+# high-quality-engineering-playbook
 
 ## 高质量工程知识库（Web 全栈版）
 

package/incident/02-playbooks/chaos-engineering-playbook.md

@@ -10,7 +10,7 @@ difficulty: intermediate
 quality_score: 70
 ---
 
-# 开发：Excellent（11964948@qq.com）
+# 混沌工程作战手册
 # 功能：混沌工程全流程作战手册
 # 作用：指导团队安全地实施混沌实验以验证系统韧性
 # 创建时间：2026-03-28

package/incident/postmortem-and-response-deep-dive.md

@@ -8,7 +8,7 @@ tags: [and, deep, dive, incident, postmortem, response, 事故响应与复盘深
 quality_score: 70
 last_updated: 2026-06-15
 ---
-# 开发：Excellent（11964948@qq.com）
+# postmortem-and-response-deep-dive
 
 ## 事故响应与复盘深度知识库