diff --git a/docs/maintenance.md b/docs/maintenance.md index beb40e0..c9022d8 100644 --- a/docs/maintenance.md +++ b/docs/maintenance.md @@ -53,6 +53,47 @@ - 在 `status.md`、调研或 ADR 中记录昂贵验证对应的 commit、环境、结果和适用边界,PR 可以引用该记录,使后续工作能判断证据是否仍有效,而不是机械重跑。 - 发布、安全边界、数据库迁移和部署切换仍按其风险执行必要的最终门禁;“批量验证”不是跳过会被当前变更影响的检查。 +## 阶段验收后的有界架构收敛 + +这是一项明确延期的收官任务。只有当前主要功能基本完成、相关主线变更合并且阶段验收完成后才可启动;它不阻断或抢占当前的质量证据、自动路由 exact-room canary、native sender 或部署工作。启动时从届时最新 `main` 建立一个短期 `refactor/` 或 `chore/` 分支。当前只记录审查契约,不实施重构。 + +2026-08-19 的一次只读盘点估算约有 14,153 行产品源码和 31,094 行第一方文本,并标出以下高集中度 owner: + +- `src/server/hybrid-media-router.ts`:约 1,605 行; +- `src/client/pages/HostPage.tsx`:约 1,455 行; +- `src/server/signaling.ts`:约 1,057 行; +- `scripts/peer-assisted-benchmark.ts`:约 2,049 行。 + +这些总量、分类口径和“产品源码可能净减少 7%-14%”都只是当日待重测的审查假设,不是删除指标、承诺区间或 LOC KPI。文件长度也不单独证明职责错误。正式审查必须先重新读取 `AGENTS.md`、当前 memory/status、需求、相关研究及 [ADR-0004](adr/0004-peer-assisted-media-experiment.md)/[ADR-0005](adr/0005-automatic-hybrid-media-routing.md),重新统计届时 `main`,明确计数口径,并按消费者和测试把代码分为: + +1. 当前生产路径必需; +2. 自动 `direct P2P -> peer-assisted -> optional SFU` 目标必需; +3. 有明确下一阶段消费者和退出条件的实验能力; +4. 已被替代、重复、无消费者或仅服务一次性定位的代码。 + +任何实现开始前,先输出基于证据的候选清单、行为与迁移风险,以及按 owner 说明依据的预计净减少范围;范围可以低于 7%、为零,或证明当前不值得改。评审该输出后再决定是否实施,不能用预设比例反推删除。 + +审查优先减少状态 owner、重复路径和认知负担:先删除已证明无消费者的代码,再合并重复逻辑,只在已有独立职责和消费者时提取窄模块。重点检查: + +- `SignalingServer` 是否能只保留认证、WebSocket 分发与薄协调职责; +- `HybridMediaRouter` 的拓扑计划、SFU grant/lifecycle、intent drain 和广播是否形成可独立验证的自然边界; +- `HostPage`/`ViewerPage` 的纯媒体编排与展示状态能否适度分离,而不建立新的前端架构层; +- benchmark 的一次性探针和重复 CDP 逻辑能否收缩,同时保留可重复验收与结果可比性; +- 测试 setup/fixtures 能否合并,同时完整保留竞态、鉴权和 host edge 上限覆盖。 + +不要为了缩短文件机械拆分,也不要引入通用框架、工厂、事件总线或更多状态机。Peer/SFU 代码不能因默认关闭就视为多余:若 canary 和 ADR 门槛支持该路线,则保留并整理;若路线被实测否决或明确替代,则删除失败路径,不长期保留无消费者的负担。 + +任何候选改动都必须保持以下行为不变: + +- 用户无感的自动 `direct P2P -> peer-assisted -> optional SFU` 梯级; +- 每条 P2P 边独立执行 ICE,并可使用短期凭据回退到鉴权 TURN; +- host 下游活跃媒体边不超过两个; +- 普通桌面或移动浏览器 Viewer 无需安装应用; +- break-before-make、安全授权、重连、回滚和陈旧消息隔离语义; +- 功能默认关闭,并保留 exact-room allowlist 灰度边界。 + +实现期间只运行覆盖当前改动的窄测;完整候选形成后统一运行一次 full check。除非媒体行为或证据采集逻辑改变,不重跑昂贵浏览器/网络矩阵。实现 PR 必须原位同步 status、project memory 和相关 ADR,删除失效描述,不新增过程流水账文档。 + ## 在线调研规则 非平凡的设计、实现和 bug 修复先读仓库,再查当前的一手资料。优先级为规范/官方文档、官方源码与维护者说明、原始论文,然后才是高质量社区复现与运行经验。安全、网络协议、浏览器能力、依赖版本和云服务行为属于易变化信息,必须按当前日期重新验证。 diff --git a/docs/project-memory.md b/docs/project-memory.md index 468e882..8ebe002 100644 --- a/docs/project-memory.md +++ b/docs/project-memory.md @@ -27,7 +27,8 @@ Last updated: 2026-08-19 - Prefer direct UDP, then TURN/UDP, with TURN/TCP as the required non-UDP fallback. Optional TURN/TLS uses TCP 5349 by default; TCP 443 needs a dedicated address or validated L4/SNI routing. - Treat video settings as ceilings. Production defaults clarity-first with bounded manual controls, but reported degradation is unclassified. Before ADR-0007 implementation, correlate same-tick capture settings and outbound deltas/identity, then add only the minimal authenticated viewer report needed for per-path `HIGH`/`FALLBACK`. Do not use UA for quality or build a composite score. Keep browser audio request/presence-only. - Do not add custom scene detection or dynamic-FPS control until WebRTC statistics and host resource measurements prove a material gap. Keep browser codec order until target hardware proves a more efficient common codec. -- Keep room policy deployment-driven. Public and password-only deployments use random temporary rooms. A site password plus SQLite path enables sequential persistent rooms; stopping sharing leaves the room and viewer link available. +- Keep room policy deployment-driven. Public/password-only deployments use random temporary rooms. A site password plus SQLite path enables sequential persistent rooms; stopping leaves the room and viewer link available. +- Deferred architecture audit: `docs/maintenance.md`. ## Current Implementation diff --git a/docs/status.md b/docs/status.md index ba55042..9781259 100644 --- a/docs/status.md +++ b/docs/status.md @@ -67,11 +67,11 @@ no-RTX remains research-only. ## Blockers And Decisions -Production enablement of peer assistance and automatic routing is No-Go until -ADR-0004/0005 gates pass. Without LiveKit, two mobile leaves can occupy both -host roots and leave later viewers without media; use only an exact-room -allowlisted isolated canary. -Native shared encode and multi-tree striping remain separate experiments. +Peer assistance and automatic routing remain No-Go until ADR-0004/0005 pass. +Without LiveKit, two mobile leaves can fill both host roots; use an isolated +exact-room canary only. +Native shared encode and striping remain separate experiments. +Deferred architecture audit: `docs/maintenance.md`. - Whole-system versus selected-game audio for the first release. - Initial deployment region and network cohort.