插件生态 Round 3 稳定性与扩展性方案（v0.4.x）
该方案承接 Round 2（M1-M6）后的下一阶段实施，目标是把 sharelife 从“功能可用”推进到“可长期演进、可稳定扩容”。
1. 目标与边界
1.1 阶段目标
- 稳定性：在并发、异常、版本演进下保持可预测行为。
- 扩展性：降低后续市场规模增长、治理策略增长带来的改造成本。
- 发展预期对齐：保持“高精度复刻 + 安全治理”主轴，不引入与产品定位冲突的重型技术栈。
1.2 非目标
- 本阶段不做全量前端框架重写（不直接迁移到 React/Vue）。
- 本阶段不引入分布式数据库或多节点强一致架构。
- 本阶段不做“自动安装自动放行”的弱治理模式。
2. 建议筛选结论
以下是对你给出的建议按“可采纳性（稳定性/扩展性/成本）”的筛选结果。
2.1 采纳（进入实施）
- 前端构建链路引入
Vite（保留 vanilla 模块语义），解决无打包、无压缩、无依赖治理的问题。 - 前端状态层收敛为单一事件总线（
EventTarget），减少跨模块状态漂移与重复渲染。 - 全量动态内容注入前进行 HTML 清洗（
DOMPurify），补齐 XSS 面。 - 前端补齐最小可访问性基线：ARIA、键盘焦点流、抽屉/弹窗 focus trap。
- 存储层升级为“仓储接口 + SQLite 实现 + JSON 兼容回退”，先保证单机稳定并发。
- 扫描/对比等重任务改为后台执行（
asyncio.to_thread/任务队列），避免阻塞请求线程。 - 安全中间件强化：鉴权依赖统一、限流、CORS 白名单策略、基础安全响应头。
- 可观测性增强：结构化日志（
structlog）+ 核心指标（Prometheus 文本导出）。 - 官方容器化交付：多阶段 Docker +
docker-compose，统一部署路径。 - CI 增加关键门禁：前后端关键链路覆盖率阈值、i18n/文档/协议一致性校验。
2.2 暂缓（保留到后续阶段）
- PWA 离线能力与安装壳：价值明确，但优先级低于安全与并发稳定。
- 无限滚动与复杂前端分页策略：当前目录量级未逼近瓶颈，先做服务端分页接口。
- 深度前端样式体系重构（Tailwind 全量替换）：本阶段只做 CSS 变量与暗色模式基础。
- 数据库直接上 PostgreSQL/
asyncpg：先 SQLite 跑稳，后续按并发与查询复杂度升级。
2.3 不采纳（当前阶段明确不做）
- 全量替换为重型 SPA 框架并重写所有页面。
- 牺牲审核门禁换取“一键自动安装”默认开启。
3. 技术决策（ADR 摘要）
ADR-1: 前端演进策略
决策：
- 保留 vanilla JS 模块边界。
- 引入 Vite 构建与产物管理。
- 新增
ui_event_bus统一状态广播。
理由：
- 最小化重写风险，保持现有可运行能力。
- 解决全局脚本污染与手工加载成本。
- 为后续逐步引入声明式更新预留位。
ADR-2: 持久化策略
决策：
- 统一仓储接口（market/profile-pack/audit/trial）。
- 默认实现切换到 SQLite。
- 保留 JSON 仓储作为开发/回退选项。
理由：
- 低迁移成本提升并发写入稳定性。
- 不破坏现有服务分层。
- 可渐进切换，不阻断线上演进。
ADR-3: 安全与可观测性优先级
决策：
- 先补认证、限流、安全头、异常屏蔽。
- 同步引入结构化日志与指标。
理由：
- 先降低风险暴露，再追求功能扩展速度。
- 缺可观测性会导致后续扩展不可控。
4. 里程碑（N1-N5）
N1（稳定性收口）
范围：
- 版本一致性收口（插件版本、元数据、WebUI API 版本、文档基线）。
- Round 2 文档状态与实现对齐（M6 完成态说明）。
- 统一错误码到文档真值表。
验收：
- 版本一致性 meta 测试通过。
- 文档状态断言通过。
N2（前端可维护性与安全）
范围：
- Vite 构建接入与产物发布路径接入。
- 事件总线落地，替换跨模块直接状态写入关键路径。
- DOMPurify 接入所有用户输入展示位。
- 补 ARIA + 键盘导航 + 弹窗焦点管理。
验收：
node --test tests/webui/*.js全绿。- E2E 覆盖
market -> drawer -> wizard -> compare主链路。 - 安全测试中反射型注入样例被清洗。
N3（后端存储与并发基础）
范围：
- SQLite 仓储实现与迁移脚本。
- 服务层读写切换到仓储接口。
- 关键查询加索引（pack_id/status/risk_level/created_at）。
验收：
- JSON 与 SQLite 双后端回归测试通过。
- 并发写入场景无状态损坏。
N4（安全网与可观测性）
范围：
- 登录/接口限流策略。
- 统一安全头与 CORS 白名单规则。
- 结构化日志字段标准化（request_id/actor/route/error_code）。
- 指标导出与基础告警阈值建议。
验收：
- 安全回归（越权、爆破、跨域）通过。
- 关键 API 在日志/指标上可定位问题。
N5（交付与运维）
范围：
- 官方 Docker 镜像与 compose 样例。
- 数据目录挂载与健康检查端点。
- 发布流程与回滚手册更新。
验收：
- 容器一键启动可跑通 WebUI 与核心 API。
- 文档覆盖本地与容器部署路径。
5. 风险与权衡
- 引入构建链路会提高前端工程复杂度。 对策：保留模块边界与纯 JS 编码约束，不同时引入重框架。
- 存储切换存在历史数据迁移风险。 对策：先实现双写/导入工具与只读核对脚本，再默认切换。
- 安全中间件加强可能影响局域网便捷访问。 对策：给出明确的 dev/prod 配置模板并默认安全。
6. 进度快照（截至 2026-04-02）
- N1 已完成：版本与文档一致性测试已接入 CI。
- N2 已完成：事件总线、i18n 同步收口、可访问性焦点控制、浏览器级 E2E 主链路全部通过。
- N3 已完成：
MarketService、ProfilePackService、PreferenceService、RetryQueueService、TrialService、TrialRequestService、AuditService、InMemoryNotifier已切仓储抽象，包含 JSON/SQLite 双实现、SQLite 索引和 legacy 数据迁移路径。 - N4 基线已完成： 登录/API 限流、安全响应头、请求 ID 追踪、结构化请求日志、统一错误结构（含
internal_server_error兜底）与/api/metrics指标导出（含 auth/rate-limit 专项计数），并补齐 metrics path 基数保护与错误风暴抓取稳定性回归测试。 - N5 基线已完成： 官方 Dockerfile/compose、健康检查、独立 WebUI 启动脚本已提供，并新增可观测性/回滚 runbook 供值班运维直接执行。
- N5+ 运维闭环已完成： 新增
docker-compose可观测性叠加文件、自动化 smoke 脚本（scripts/smoke_observability_stack.sh）以及定时/手动执行并自动上传诊断产物的ops-smokeGitHub Actions 工作流。 - N5++ 诊断提速已完成： smoke 诊断产物自动生成结构化摘要/数据（
output/ops-smoke/triage.md+triage.json），并同步写入 Job Summary 与 signal/action annotations，降低值班排障首响时间。
7. 执行顺序（推荐）
- N1 -> N2 -> N3 -> N4 -> N5
- 只有 N1-N2 完成后才进入高频功能扩展。
- 每个里程碑结束必须补齐：测试、文档、回滚说明。
8. 与现有路线的关系
- Round 2 产物（profile-pack、developer mode、market compare）保持不变。
- Round 3 是“工程质量层”的升级，不改变“社区优先治理”核心策略。
- 新增能力必须继续遵循：先 dry-run、再 apply、可 rollback、可审计。