跳转到内容
YBO 技术文档

20260921-1701-switch-line-document-structure Give the Switch line one document model for brief, features, spec and development requirements

  • status: completed
  • createdAt: 2026-09-21 17:01
  • approvedAt: 2026-09-22 00:05
  • relatedTask: 20260921-1700-switch-line-document-structure

Context

章节标题：“Context”

The Switch line (bizplan/product/switch/) is 14 pages, 1353 lines: a line spec and brief, three sub-packages (Air, Key, Air Hub) and one evaluation. The owner's complaint is that the four registers a reader looks for — customer description (说明展示), functional description (功能描述), target specification (规格书) and development requirements for the design house and contract manufacturer (开发需求) — are not in one recognisable place per product.

Two document models in one line

章节标题：“Two document models in one line”
Register Air (P05-air.md, 286 lines) Air Hub (P05-air-hub.md, 242 lines) Key (4 files, 416 lines)
说明展示 P05-air-brief.md P05-air-hub-brief.md P05-key-brief.md
功能描述 spec §3 (AIR-nn, SYS, SEC, IF, MFG) spec §3 (GW-nn …) spec §3 (FR-01…20) and guide §3 (KEY-01…07, SYS, SEC, IF, MFG)
规格书 spec §1, §2, §6, §8 spec §1, §2, §3.1, §6, §8 spec §1, §2, §4, §7
开发需求 spec §4, §5, §7 (platform, design, supplier delivery in the same file) spec §4, §5, §7 spec §5–§6 and P05-key-design.md and P05-key-guide.md

Air and Air Hub follow decision docs/decisions/2026-09-14-air-single-file-spec.md (one self-contained file, sunset 2026-12-31). Key follows the standard slot split. Each product therefore answers "where is the development requirement" differently, and the chapter skeletons differ as well: line spec 5 chapters, Air/Air Hub 9 parts, Key spec 7 ad-hoc chapters, Key design 7, Key guide 12. None matches the 16-chapter hardware template that bizplan/product/index.md still announces.

Key package defects

章节标题：“Key package defects”
  1. Same content in three registers. The chip table (STM32G0B1CE + TJA1463 + LP5024 + LMR36506-Q1/TLV755P) is in the spec §5, the design §1–§4 and the guide §4. The 32-key scaling argument is in spec §5 and design §2–§3. Verification, EOL and deliverables are in spec §6, design §7 and guide §9–§12. This is the drift pattern the 2026-09-14 decision removed from Air.
  2. Two requirement ID schemes. The spec numbers requirements FR-01…FR-20 and maps only some of them to the guide's KEY-01…07 ("FR-01 / KEY-03"); the guide's table is a different, shorter list with its own wording. Air and Air Hub use one scheme each.
  3. Sleep contradiction. Spec FR-10 and guide KEY-05 say Key defines no sleep (decision of 2026-09-11, task 20260911-1916). Design §4 ("休眠须保持有效 CAN 唤醒电源，MCU 以低功耗模式和按键 中断唤醒"), guide §5 ("CAN 唤醒所需电源不得在休眠时完全关闭"), guide V-06 ("冷启动/休眠"), guide §10 ("工作/休眠电流") and product-plan.md §P5 ("休眠 ≤5 mA@12 V") still describe a sleeping panel.
  4. Backlight budget lives in Level 2 only. Spec §2 says "最大背光见 KEY-05 的逐键预算"; KEY-05 gives no number; design §3 says "输入 ≤60 mA@12 V"; product-plan.md §P5 says "最大背光 ≤60 mA@12 V". A Level 1 figure is set by a Level 2 page.
  5. CAN FD after the Classical CAN decision. X01 §1 fixed the bus to Classical CAN 2.0B, 500 kbit/s, no BRS on 2026-09-11; the Air Hub spec follows it. Key spec §4 still says "500 kbit/s / 2 Mbit/s 为联调起点" and guide §7 says "500 kbit/s 仲裁 / 2 Mbit/s 数据段 … 不得私自改为 经典 CAN、不带 BRS", which instructs the supplier to do the opposite of the bus decision.
  6. Stale names. Hub (renamed Mate on 2026-09-11) in spec §1, FR-08, FR-12, guide §2 diagram and V-01. Guide §1 says "§1、§2、§7、§8、§10、§11、§12 与 Air 指南为共同条款，改动其中任何一条 必须同步另一份" and the relations list links "Air / Air Hub 设计与代工指南" — the Air guide was deleted on 2026-09-14. Spec §1 links "P09 Control" to an evaluation page instead of the P09 spec.
  7. Layout rules. Spec, design and guide have no ## 变更记录 table (spec §7 holds two prose entries); relations lists use labels outside the fixed set (用途, 简称) or the wrong order (治理摘要 → 总交付要求 → 设计附录, no 产品入口); titles use "—" where the standard's other pages use "——".

Line-level and cross-package

章节标题：“Line-level and cross-package”
  1. bizplan/product/index.md and product-plan.md §P5 call P05-air.md "Air / Air Hub 指南" and "供应商交付指南"; it is the spec. product/index.md §文件模板 describes three different skeletons for one line.
  2. The evaluation evaluations/esp32h2.md is still titled "Air Switch 备选平台评估" (old product name).
  3. Air Hub cites the Air file for §4.4, §6 and §7 common clauses; Key repeats those clauses in full. The common supplier clauses (markers, responsibility table, D0–D4 gates, EOL flow, quotation format) therefore exist twice and were, per the deleted Air guide, the clauses that "must be changed in both places".
  4. Inbound links from outside the line: product-plan.md (5), open-questions.md (3), product/index.md (1), X01 and X02 (2), Mate (3), Studio (2), Control (4) and its evaluation (6), Tag (4), research (2), the 2026-09-14 decision (1). About twelve of them target section anchors that move if the single files are split.

Proposal

章节标题：“Proposal”
章节标题：“A. Recommended: one four-slot model for every Switch product”

Each product package carries the same four files, and each file is one register:

Register File Content Rule
说明展示 P05-<x>-brief.md eight-section brief, unchanged template restates capability only
功能描述 + 规格书 P05-<x>.md (spec, Level 1) 1 定位与边界 · 2 型号与目标规格 · 3 功能与状态行为（ID 表） · 4 系统位置与失效安全 · 5 接口 · 6 安全 · 7 合规路径 · 8 待决事项 · 9 变更记录 the only file that carries a number; chapter 3 is the functional description
开发需求（内部设计输入） P05-<x>-design.md (Level 2) 1 范围 · 2 平台与选型（方案对比、推荐器件、替代规则） · 3 架构与框图 · 4 电源、功耗与热预算 · 5 引脚、PCB 与射频 · 6 固件结构与失败行为 · 7 结构与制造 · 8 变更记录 cites spec IDs; never restates a target
开发需求（供应商交付） P05-<x>-guide.md 1 用途与标记 · 2 责任边界（产品特有行） · 3 需求追踪（ID → 验收 → 证据，无需求正文） · 4 验证矩阵 V-nn · 5 工厂测试 · 6 设计关口 · 7 报价格式与交付清单 · 8 变更记录 the RFQ hand-out; readable without the design file

The functional description is chapter 3 of the spec rather than a fifth file, because the documentation standard has no such slot and the ID table is what a supplier responds to; the sub-package index.md names it explicitly in its content column.

A1 — Line level. P05-switch.md keeps its five chapters and gains a short 文档地图 that states the four registers once. A line-level P05-switch-guide.md holds the common supplier clauses (markers, responsibility table, D0–D4 gates, EOL flow, quotation and deliverable format) once; the three product guides carry only product-specific rows and cite it. The lint accepts a guide slot on the line directory (P05-switch-guide.md matches the spec slug switch), and the standard's "needs only its line spec and brief" is a minimum.

A2 — Air and Air Hub are split, not rewritten. Content moves by chapter:

Today (P05-air.md / P05-air-hub.md) Goes to
§1 边界与定位, §2 目标规格, §3 功能与状态行为 (+ §3.1), §6 安全 (requirement sentences), §8 待决事项, §9 变更记录 spec
§4 平台与选型, §5 设计要点, §6 安全 (implementation: LE Secure Connections, GATT, key handling) design
§7 供应商交付与验收 guide (product rows) and P05-switch-guide.md (common rows)

The 2026-09-14 decision is superseded by docs/decisions/2026-09-22-switch-four-slot-model.md (status of the old record set to superseded, first paragraph names the successor). The new record states why the split is safe now where it drifted before: figures exist once, the guide carries no requirement text, common clauses exist once at line level, and the decision frontmatter waiver is removed from both specs.

A3 — Key is normalised onto the same skeleton. Spec §5 (chips, scaling) moves into the design; spec §6 (verification, production, delivery) moves into the guide; the design and guide lose their duplicate chip tables. Requirement IDs: the spec's chapter 3 becomes the single table. Recommended: renumber the twenty FR-nn rows into KEY-08…KEY-27, keep KEY-01…07 as they are, and record the FR → KEY mapping in the spec's 变更记录 so the Key package uses one scheme like AIR-nn and GW-nn. The alternative (keep both, complete the mapping) is listed under Open Items because the line spec R0.2 promised stable IDs.

A4 — Contradictions are resolved where a governing decision exists, and marked 待决 where none does (the rule plan 20260913-2340 used):

Item Governing record Treatment
Key sleep wording (design §4, guide §5, V-06, §10; product-plan.md §P5) task 20260911-1916: only Air sleeps reword to 静态/低功耗待机 with the receiver kept on; product-plan.md §P5 "休眠 ≤5 mA" becomes "静态 ≤5 mA"
Key CAN FD text (spec §4, guide §7) X01 §1, 2026-09-11 Classical CAN, 500 kbit/s, no BRS; the FD sentence is deleted, not softened
Key backlight ceiling product-plan.md §P5: ≤60 mA@12 V spec §2 carries "Key 4 / Key 8 ≤60 mA@12 V (t)" citing §P5; ≥32-key configurations stay "基数 + 每键增量" under KEY-O-07
Stale Hub, Air 指南, P09 link, evaluation title rename records of 2026-09-11/14 replaced
Any figure that differs between the Air single file and the Key files without a record none left as is and listed in the plan's Annotations before implementation if found during the move

A5 — References. Inbound anchors that move (P05-air.md#4-平台与选型, #43-…, #6-安全配对与接口, P05-air-hub.md#5-6, …) are rewritten to the design or guide file. bizplan/product/index.md §产品包 and §文件模板 describe one skeleton per kind and drop the Air exception; product-plan.md §P5 and open-questions.md §P5 stop calling the spec a guide. No page is renamed, so public/_redirects is untouched.

B. Alternative: extend the single-file model to Key

章节标题：“B. Alternative: extend the single-file model to Key”

Keep the 2026-09-14 decision and make Key one self-contained file with the same nine-part outline as Air (spec §1–§3 = 功能描述 + 规格书; §4–§5 = design; §7 = supplier delivery). Line becomes 3 self-contained specs + 3 briefs + line spec/brief + evaluation (9 pages). Same defect fixes as A3–A5. What it does not give: a development-requirements document a supplier can receive without the internal design chapters, and the four registers as four files. It is the review the 2026-09-14 decision scheduled for its sunset, brought forward.

C. Minimal: keep the hybrid, fix Key only

章节标题：“C. Minimal: keep the hybrid, fix Key only”

Apply A3–A5 to Key and the stale labels; leave Air and Air Hub as they are. Fixes every contradiction, leaves two models in one line.

Risks

章节标题：“Risks”
  • A reverses a one-week-old decision. The 2026-09-14 record chose the single file because the previous split drifted. A keeps the split from drifting by rule (figures once, guide without requirement text, common clauses once) rather than by file count; the rule is written into the new decision record and checked in the verification below.
  • Anchor breakage. About twelve inbound links target sections that move in A; the build fails on dead links, so a miss is caught, but an anchor that resolves to the wrong section is not. Each rewritten link is checked by hand against the section it names.
  • ID renumbering (A3). If a supplier already holds Key R0.1 with FR-nn, the mapping table is what keeps their response valid. If the owner prefers stable IDs, the Open Item alternative avoids the renumbering.
  • Parallel session. Task 20260921-1659 (site tooling, three research pages) is active; docs/sitemap.md is regenerated by both builds. No Switch file overlaps.
  • Content loss during the move. Mitigated by the ID-by-ID and figure-by-figure checks.

Scope

章节标题：“Scope”

Option A:

  • New: switch/air/P05-air-design.md, switch/air/P05-air-guide.md, switch/air-hub/P05-air-hub-design.md, switch/air-hub/P05-air-hub-guide.md, switch/P05-switch-guide.md, docs/decisions/2026-09-21-switch-four-slot-model.md.
  • Rewritten (content moved, values unchanged): P05-air.md, P05-air-hub.md, P05-key.md, P05-key-design.md, P05-key-guide.md, P05-switch.md.
  • Updated: switch/index.md, three sub-package index.md, four briefs (re-checked against the moved spec, wording only), evaluations/esp32h2.md (title), docs/decisions/2026-09-14-air-single-file-spec.md (superseded), docs/decisions/index.md, bizplan/product/index.md, bizplan/governance/product-plan.md §P5, bizplan/governance/open-questions.md §P5, shared/X01, shared/X02, Mate (3), Studio (2), Control (2 + evaluation), Tag (3), research (2) — link text and anchors only.
  • docs/changelog.md entry; task and plan status.
  • No Level 1 value changes except the three recorded in A4, each of which already has a governing record.

Option B touches the same set minus the four new product files and the line guide; Option C touches only the Key package, the line index, the labels in governance and product index.

Verification

章节标题：“Verification”
  1. Every ID present today (AIR-nn, GW-nn, KEY-nn, FR-nn, SYS, SEC, IF, MFG, V-nn, AIR-O, KEY-O, SW-O, CTL-O-11) is defined exactly once afterwards, or has a mapping row → verify: ID list before and after, diffed.
  2. No numeral with a unit in a design or guide file is absent from its spec, except derived Level 2 figures marked as such (battery integration, LED channel counts) → verify: grep for unit tokens (mA, µA, V, mm, °C, ms, s, $) in design/guide, each hit checked against the spec.
  3. rg -n "2 Mbit|BRS|休眠" bizplan/product/switch/key returns nothing that describes Key sleeping or CAN FD; rg -n "Air 指南|Hub/|无需 Air Hub、Hub" returns nothing.
  4. Every controlled Switch page has a fixed-order relations list and a ## 变更记录 table → verify: read each page head and tail.
  5. Every inbound link listed under Context item 11 resolves to the section it names → verify: open each rewritten anchor.
  6. bun run docs:lint && bun run docs:build && git diff --check passes; the sub-package index tables list every slot file with the right 类型/状态.

Open Items

章节标题：“Open Items”
  • Key requirement IDs: renumber FR-nn → KEY-nn with a mapping (recommended), or keep both schemes with a complete cross-reference.
  • Whether the functional description should become a fifth slot in the documentation standard instead of spec chapter 3; A assumes chapter 3.
  • Whether the line-level supplier guide (A1) is wanted, or each product guide should carry the common clauses in full.

Annotations

章节标题：“Annotations”
  • 2026-09-22 00:05 owner: "用A". Option A approved; the three open items were left to the recommendation: FR-nn renumbered into KEY-08…17 with the mapping in the Key spec change log, the functional description stays as spec chapter 3, and the line-level supplier guide was created. The decision record is dated 2026-09-22 (the day it was written), not 2026-09-21 as drafted above; its sunset is 2027-03-31.
  • 2026-09-22 07:40: completed. Verification 1–6 passed; the only ID token not found verbatim afterwards is FR-19, which appears in the mapping row as FR-07/FR-19→KEY-10. Figures remaining only in design or guide files are datasheet values, rows derived from the spec's 750 mAh budget, internal rail voltages and test sample sizes. The Key brief, Air brief and Air Hub brief needed no wording change. Inbound §n text references to old sections were repointed; links without a section number were left as they were.