# specs

**Repository Path**: wemusic/specs

## Basic Information

- **Project Name**: specs
- **Description**: The WeMusic Core specs
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-08
- **Last Updated**: 2026-06-04

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# WeMusic Specs

> - WeMusic 分布式音乐共享平台的协议与设计规范仓库。
> - 面向中大型企业内部网场景，定义从零信任节点身份到文件传输的完整 P2P 网络协议栈。

## 文档清单

| 文档 | 状态 | 说明 |
|------|------|------|
| [design-key.md](design-key.md) | ✅ 定稿 | 跨文档通用原则、P0/P1/P2 范围划分、安全合规框架 |
| [network-protocol.md](network-protocol.md) | ✅ 定稿（P0 核心协议，P1/P2 扩展标注） | **分布式网络层协议**——节点身份、网络发现、加密传输、DHT 内容寻址、消息协议、文件传输 |
| [reputation.md](reputation.md) | ✅ 定稿（P0 核心框架，P1 扩展应用） | **信誉机制设计**——多维度局部信誉（MLR）、观察期、背书、合规熔断 |
| [system-architecture.md](system-architecture.md) | ✅ 定稿 | **系统架构设计**——三层拓扑、Daemon 模块、内容抽象层、存储层、性能基线、故障场景手册、升级与数据迁移 |
| [search.md](search.md) | ✅ 定稿 | **搜索功能设计**——本地搜索、P2P 网络搜索、搜索类型与匹配、排序算法、渐进式搜索、安全与隐私 |
| [api/README.md](api/README.md) | ✅ 定稿（P0 核心 API，P1/P2 扩展 API 标注阶段） | **公共 API 接口**——传输与认证、节点管理、音乐库、搜索、下载、媒体资源、错误码体系；WebSocket 为 P1 实时事件增强。详细规范见 [`api/`](api/) 子目录 |
| [privacy-audit-design.md](privacy-audit-design.md) | ✅ 定稿 | **隐私与审计策略**——四层数据分级、三档运行模式、本地签名链、日志导出 |
| [security-defense.md](security-defense.md) | ✅ 定稿（P0 核心防御 + P1 扩展机制） | **安全防御设计**——威胁模型（STRIDE）、零信任落地、身份认证、访问控制、Sybil/Eclipse/毒化/DDoS 防御、入侵检测、安全配置基线 |
| [multitenancy-isolation-draft.md](multitenancy-isolation-draft.md) | 📝 草案 | 多租户/部门隔离风险记录——P0/P1 边界与 P2+ 命名空间预留 |
| [sync-listening-room-draft.md](sync-listening-room-draft.md) | 📝 草案 | 同步听歌房间专题设计——P2 房间模型、控制信令、同步算法与 API 方向 |

> API 详细规范已收敛到 [`api/`](api/) 目录，完整索引见 [`api/README.md`](api/README.md)。

## 推荐阅读顺序

1. **[design-key.md](design-key.md)** — 先读。理解项目背景、场景假设、P0/P1/P2 范围和安全基线。
2. **[network-protocol.md](network-protocol.md)** — 再读。网络层协议的完整规范，所有实现者的首要参考文档。
3. **[reputation.md](reputation.md)** — 第三。信誉是跨层核心机制，影响搜索排序、连接管理、安全防御和合规熔断。
4. **[system-architecture.md](system-architecture.md)** — 第四。系统架构、内容抽象层、元数据规范、文件类型校验、性能基线。
5. **[search.md](search.md)** — 第五。搜索功能的唯一权威设计来源，涵盖本地搜索、P2P 网络搜索、排序算法与渐进式搜索。
6. **[api/overview.md](api/overview.md)** → 按需读 `api/nodes.md` / `api/library.md` / `api/search.md` / `api/transfers.md` — 第六。先读通用基础设施，再按需阅读具体模块的 API 详细规范。
7. **[privacy-audit-design.md](privacy-audit-design.md)** — 第七。隐私与审计策略，四层数据分级与三档运行模式。
8. **[security-defense.md](security-defense.md)** — 第八。安全防御设计的完整展开，涵盖威胁模型、攻击防御、安全配置基线。
9. **其他草案** — 按需阅读。作为特定专题的详细设计补充。

## 文档关系

```
design-key.md (总纲)
    ├── network-protocol.md (网络层协议)
    │   └── 定义：节点身份、发现、传输、DHT、消息、文件传输
    ├── reputation.md (信誉机制)
    │   └── 被 network-protocol.md / design-key.md 引用，为安全防御与搜索排序提供基础
    ├── system-architecture.md (系统架构)
    │   └── 依赖 protocol / reputation，定义 Daemon 模块、内容抽象层、存储层
    ├── search.md (搜索功能)
    │   └── 被 api/search.md / network-protocol.md / system-architecture.md 引用，为搜索策略与语义的唯一权威来源
    ├── api/README.md (API 文档索引)
    │   └── 总索引、接口边界、快速定位
    ├── api/overview.md (API 通用基础设施)
    │   └── 概述、传输认证、版本管理、错误码、异步模式、数据模型
    ├── api/nodes.md (节点管理 API，核心业务)
    ├── api/library.md (音乐库 API，核心业务)
    ├── api/search.md (搜索 API，核心业务)
    ├── api/transfers.md (传输与资源 API，核心业务)
    ├── api/compliance.md (信誉与合规 API)
    │   └── 被 privacy-audit-design.md / reputation.md 引用
    ├── api/websocket.md (WebSocket 事件)
    │   └── 被 api/extended.md 引用
    ├── api/extended.md (扩展 API)
    │   └── P1/P2 阶段功能扩展
    ├── privacy-audit-design.md (隐私与审计)
    │   └── 被 design-key.md / api/compliance.md / system-architecture.md 引用
    ├── security-defense.md (安全防御)
    │   └── 被 design-key.md / network-protocol.md / reputation.md / system-architecture.md / api/overview.md 引用
    ├── multitenancy-isolation-draft.md (多租户/部门隔离)
    │   └── P2+ 风险记录与命名空间预留
    └── sync-listening-room-draft.md (同步听歌房间)
        └── P2 房间模型、信令同步与 API 草案
```

## 规范版本

- **当前 Specs 版本**：`v1.0.0`