diff --git a/docs/developer-guide/architecture.md b/docs/developer-guide/architecture.md new file mode 100644 index 0000000..b29df0f --- /dev/null +++ b/docs/developer-guide/architecture.md @@ -0,0 +1,109 @@ +--- +title: 系统架构 +description: Ikaros 分层架构、模块划分与关键技术决策（ADR）摘要 +--- + +# 系统架构 + +> 本文是对 Ikaros 主仓库《概要设计文档（HLD）》第 2 章"系统架构"的提炼总结， +> 完整内容见 [ikaros-dev/ikaros](https://github.com/ikaros-dev/ikaros) `docs/High-Level-Design.md`。 + +## 分层架构 + +``` +┌─────────────────────────────────────────────────────────────────┐ +│ 客户端层 (Clients) │ +│ Web Console (Vue3 SPA) │ App (Flutter 六端) │ Subsonic 客户端 │ +│ App：Windows/Android/iOS/macOS/Linux/Web，含视频/音乐/阅读 │ +└───────────────────────────────┬─────────────────────────────────┘ + │ HTTPS / HTTP +┌───────────────────────────────┴─────────────────────────────────┐ +│ 接入层 (Security) │ +│ SecurityWebFilterChain：Basic / Form / JWT / OAuth2 / TOTP │ +│ 匿名用户 → RequestAuthorizationManager(RBAC) → 端点路由 │ +├───────────────────────────────┬─────────────────────────────────┤ +│ 路由层 (Router / Endpoint) │ +│ CoreEndpointsBuilder (函数式路由 + SpringDoc) │ +│ CustomEndpointsBuilder (自定义Scheme动态端点) │ +│ PluginCompositeRouterFunction (插件端点) │ +│ SubsonicRouter (/rest/** 协议分发) │ +├───────────────────────────────┼─────────────────────────────────┤ +│ 领域服务层 (Core Services) │ +│ Subject/Episode/Collection/Attachment/Tag/Binding/Music/... │ +│ ★ 服务接口(api模块) + 默认实现(server模块, XxxService/Default) │ +├───────────────────────────────┼─────────────────────────────────┤ +│ 横切能力层 (Infrastructure) │ +│ 缓存(CacheAspect: 内存/Redis) │ 任务(Task) │ 事件(Event) │ +│ Lucene搜索 │ 邮件通知 │ WebClient │ 全局异常处理 │ +├───────────────────────────────┼─────────────────────────────────┤ +│ 数据访问层 (Store) │ +│ R2DBC Repository (Spring Data R2DBC + 响应式 R2dbcTemplate) │ +├───────────────────────────────┼─────────────────────────────────┤ +│ 数据存储层 │ +│ PostgreSQL 18 │ Redis(可选) │ Lucene索引(工作目录/indices) │ +│ 文件系统(附件) │ 工作目录(~/.ikaros: plugins/themes/statics) │ +└─────────────────────────────────────────────────────────────────┘ +``` + +## 模块架构（Gradle 多模块） + +``` +ikaros +├── api/ ★ API契约层（独立可被插件依赖） +│ ├── constant/ 常量（OpenApi/Security/String/File/App） +│ ├── core/ 领域模型与操作接口（subject/episode/attachment/collection/ +│ │ tag/authority/role/user/meta/music/subsonic/binding/...） +│ ├── custom/ 自定义Scheme模型（Custom注解/客户端/异常） +│ ├── endpoint/ 端点接口（Endpoint/CustomEndpoint） +│ ├── infra/ 工具（utils）与异常体系（exception） +│ ├── plugin/ 插件API（BasePlugin/ExtensionPoint/事件/常量） +│ ├── search/ 搜索契约（SearchParam/Result/SubjectDoc/Hint/Service） +│ ├── store/ 枚举（enums）与仓库接口约定 +│ └── wrap/ 统一包装（CommonResult/PagingWrap） +│ +├── server/ ★ 服务端实现（Spring Boot 应用） +│ ├── core/ 领域服务实现（subject/attachment/binding/music/subsonic/...） +│ │ ├── /endpoint 函数式路由端点 +│ │ ├── /service 服务接口+impl实现 +│ │ ├── /listener 事件监听 +│ │ └── /handler 责任链步骤/处理器 +│ ├── security/ 认证授权（basicauth/formlogin/jwt/oauth2/totp/logout） +│ ├── plugin/ PF4J 插件管理（加载器/扩展点发现/上下文隔离） +│ ├── search/ Lucene 索引实现 +│ ├── cache/ 缓存抽象（Aspect + 内存/Redis Manager） +│ ├── store/ 实体（entity）+ 仓库（repository） +│ ├── custom/ 自定义Scheme运行时 +│ ├── console/ Console 静态资源托管 +│ ├── theme/ 主题服务 +│ ├── config/ R2DBC/任务/异步/调度/全局异常等配置 +│ └── resources/db/migration/ 版本化 SQL 迁移 +│ +├── console/ ★ Web 控制台（Vue 3 SPA，构建产物嵌入 bootJar） +│ └── packages/ shared（共享类型/菜单）/ api-client（生成的API客户端） +│ +├── platform/ 平台相关模块 +└── config/ Checkstyle 等构建配置 +``` + +## 关键技术决策（ADR 摘要） + +| 决策 | 方案 | 理由 | +|------|------|------| +| ADR-01 响应式栈 | Spring WebFlux + R2DBC | IO 密集场景（流媒体/大目录扫描）下高并发、低资源占用 | +| ADR-02 函数式路由 | RouterFunction + SpringDoc 编程式文档 | 与 WebFlux 契合，端点定义集中、便于插件聚合 | +| ADR-03 插件框架 | PF4J（org.pf4j） | 成熟、类加载器隔离、状态机完整（RESOLVED→STARTED→STOPPED/DISABLED/FAILED） | +| ADR-04 数据库迁移 | 版本化 SQL 迁移（Flyway 风格） | 无缝升级、破坏性变更受控（全面 PostgreSQL） | +| ADR-05 搜索 | Lucene + IKAnalyzer（中文分词） | 毫秒级全文检索，索引落盘工作目录，支持重建 | +| ADR-06 缓存 | 注解切面（Mono/Flux Cacheable/Evict）+ 内存/Redis 可切换 | 对业务代码侵入小，可开关 | +| ADR-07 ID 生成 | UUID v7（时间有序）为主键默认值 | 分布式友好、索引性能优于 UUID v4 | +| ADR-08 附件驱动 | Fetcher 扩展点 + 挂载服务 | 本地/WebDAV/插件自定义统一抽象，安全校验集中 | +| ADR-09 授权模型 | 权限目标字符串（Authority Target）+ 角色绑定 | 细粒度到接口路径，MASTER 超管兜底 | + +## 核心机制（要点） + +- **端点聚合**：`CoreEndpoint` 统一收集；`CustomEndpoint` 支持自定义 Scheme 动态生成端点；插件端点经 `PluginCompositeRouterFunction` 聚合。 +- **领域服务模式**：`XxxService`（接口，位于 api 模块）+ `DefaultXxxService`（实现，位于 server 模块），类/方法/属性要求中文 Javadoc。 +- **附件驱动**：`AttachmentDriverFetcher` 扩展点是本地/WebDAV/插件（如 S3）驱动的统一接入点，流式接口支持 Range（206）与外部直链 307 重定向。 +- **目录绑定工作流**：通过责任链步骤（`DirectoryBindingStep`）将本地目录扫描结果绑定为条目/剧集。 + +> 更多设计细节（核心设计模式与机制、部署架构、接口总览）请参考 HLD 原文。 \ No newline at end of file diff --git a/docs/developer-guide/contribution-guide.md b/docs/developer-guide/contribution-guide.md new file mode 100644 index 0000000..de3e20c --- /dev/null +++ b/docs/developer-guide/contribution-guide.md @@ -0,0 +1,148 @@ +--- +title: 贡献指南 +description: Ikaros 开源参与指南：协作流程规范、代码贡献步骤、提交与 PR 规范 +--- + +# 贡献指南 + +> 本文整理自 Ikaros 主仓库根目录 `CONTRIBUTING.md`， +> 原文见 https://github.com/ikaros-dev/ikaros/blob/main/CONTRIBUTING.md +> +> 仓库开发环境的搭建（JDK 21 + Gradle + PostgreSQL + Vue 3）见 +> [快速开始（安装）](/docs/getting-started/prepare) 与项目 README。 + +## 协作流程规范 + +新需求、新交互（特别是偏向破坏性的更新）：**确定的先提 issue，不确定的提 discussion**， +确定后再创建或转为 issue；issue 定了之后，再 fork 切新分支提 PR。 + +- 一个 discussion 对应多个 issue +- 一个 issue 对应一个问题，一个 PR 解决一个问题 + +```mermaid +flowchart TD + S([新需求 / 新交互
特别是破坏性更新]) --> Q{是否确定？} + Q -->|确定| I1[创建 issue] + Q -->|不确定| D1[创建 discussion 讨论] + D1 --> Q2{讨论后确定？} + Q2 -->|是| I2[创建或转为 issue] + Q2 -->|否| D1 + I2 --> I1 + I1 --> F[fork 仓库切新分支
进行开发] + F --> P[提交 PR] + P --> M[合并，issue 关闭] + D1 -.->|一个 discussion 可衍生多个 issue| I1 + I1 -.->|一个 issue 对应一个问题| P +``` + +## 代码贡献步骤 + +### 1. Fork 仓库 + +点击 [Ikaros 仓库](https://github.com/ikaros-dev/ikaros) 主页右上角 `Fork` 按钮。 + +### 2. Clone 仓库到本地 + +```bash +git clone https://github.com/{YOUR_USERNAME}/ikaros --recursive +``` + +### 3. 添加主仓库（upstream） + +方便未来同步主仓库最新 commits，并基于最新代码创建分支： + +```bash +git remote add upstream https://github.com/ikaros-dev/ikaros.git +git fetch upstream +``` + +### 4. 初始化 git submodule + +主题模板通过 git submodule 关联了另一个仓库： + +```bash +git submodule init +git submodule update +``` + +### 5. 创建新的开发分支 + +从主仓库的主分支（main）创建： + +```bash +git checkout upstream/main +git checkout -b {YOU_BRANCH_NAME} +``` + +### 6. 开发 + +在新分支上进行开发。 + +### 7. 提交代码 + +```bash +git add . +git commit -s -m "Fix a bug or issue" +``` + +### 8. 推送到你的 fork 库 + +提交 PR 前尽量与上游保持同步： + +```bash +git fetch upstream main +git merge upstream/main # 有冲突需手动解决 +git push origin {YOU_BRANCH_NAME} +``` + +### 9. 创建 Pull Request + +完成代码编写、测试与自测后，在自己的 fork 页面选择 `New pull request`， +向主仓库的 `main` 分支提交 PR，等待 Code Review。 + +注意事项： + +- 提交 PR 前请充分自测 +- 每个 PR 尽量只解决一个 issue +- 应尽可能多地添加单元测试，集成测试和 E2E 测试视情况添加 + +### 10. Review 后更新 commits + +直接在当前分支 commit 并 push 即可，无需关闭重开 PR： + +```bash +git add . +git commit -s -m "Refactor some code according code review" +git push origin bug/xxx +``` + +> 进入 Code Review 阶段后**不要强制推送**（force push），否则 Reviewers 需要从头 Review。 + +### 11. PR 合并后的操作 + +```bash +# 删本地分支 +git checkout main +git branch -D {YOU_BRANCH_NAME} +# 删远端 fork 分支 +git push origin --delete {YOU_BRANCH_NAME} +# 清理远端分支引用 +git remote prune origin +# 更新本地与 fork 主分支 +git pull upstream main +git push origin main +``` + +## 提交 / PR 规范（补充约定） + +Ikaros 主仓库在协作实践中还遵循以下约定（见项目内 `AGENTS.md` / 提交记录）： + +- Commit 消息格式：`type(scope): 中文描述`，如 `fix(attachment): 附件流接口重定向由 302 改为 307` +- type 取值：feat / fix / refactor / chore / docs / config / style / perf / test +- 服务实现类命名：`XxxService` + `DefaultXxxService`；所有类/方法/属性加中文 Javadoc +- 必须添加单元测试；必须更新 `CHANGELOG.md` +- 不使用 `Signed-off-by` / `Co-Authored-By` 尾部签名 + +## 参考 + +- 本指南参考 [开源项目 Halo 贡献指南](https://github.com/halo-dev/halo/blob/master/CONTRIBUTING.md) \ No newline at end of file diff --git a/docs/developer-guide/data-model.md b/docs/developer-guide/data-model.md new file mode 100644 index 0000000..09a95a2 --- /dev/null +++ b/docs/developer-guide/data-model.md @@ -0,0 +1,120 @@ +--- +title: 数据模型 +description: Ikaros 内容数据模型：Subject/Episode/Attachment 统一模型、ER 图与音乐/漫画/小说映射 +--- + +# 数据模型 + +> 本文整合自 Ikaros 主仓库《内容数据结构文档》文档族\n> （`docs/data-structure/README.md` 及 subject/music/comic/novel 分篇）。\n> 主仓库原文：https://github.com/ikaros-dev/ikaros/tree/main/docs/data-structure + +## 核心设计思想 + +Ikaros 的内容数据采用 **"一种条目、二级剧集、通用附件"** 的统一模型，而不是为每种媒体类型分别建表： + +``` +Subject（条目，type 区分 ANIME/COMIC/GAME/MUSIC/NOVEL/REAL/OTHER） + └── Episode（剧集/歌曲/话/章节，group + sequence 组织） + └── Attachment（附件/文件，经 attachment_reference 绑定） +``` + +| 内容类型 | 条目 | 剧集 | 附件绑定 | 前端绑定方式 | +|----------|------|------|----------|--------------| +| 动画 ANIME | Subject | 集（MAIN 正片 / OP / ED / SP…） | 每集 1 个视频（可选字幕） | 单资源 | +| 音乐 MUSIC | Subject（专辑） | 歌曲（MAIN，sequence=曲序） | 每首歌 1 音频（可多资源：音频+歌词） | 多资源 | +| 漫画 COMIC | Subject | 话/卷（MAIN，sequence=话序） | 每话多张页面图片（按附件 ID 排序） | 多资源 | +| 小说 NOVEL | Subject | 章节（MAIN，sequence=章序） | 每章 1 个文本文件 | 单资源 | + +> 单/多资源判定：前端 `SubjectDetails.vue#initEpisodeHasMultiResource` —— ANIME/GAME/NOVEL 单资源，其余多资源。 + +## 全局 ER 图 + +```mermaid +erDiagram + SUBJECT ||--o{ EPISODE : "包含" + SUBJECT ||--o{ SUBJECT_COLLECTION : "被收藏" + SUBJECT ||--o{ SUBJECT_RELATION : "关联(出)" + SUBJECT ||--o{ SUBJECT_SYNC : "同步" + SUBJECT ||--o{ SUBJECT_PERSON : "参与人员" + SUBJECT ||--o{ SUBJECT_CHARACTER : "登场角色" + SUBJECT ||--o{ ATTACHMENT_REFERENCE : "绑定附件" + EPISODE ||--o{ EPISODE_COLLECTION : "观看进度" + EPISODE ||--o{ ATTACHMENT_REFERENCE : "绑定附件" + ATTACHMENT ||--o{ ATTACHMENT_REFERENCE : "被引用" + ATTACHMENT ||--o{ ATTACHMENT_RELATION : "附件间关系" + ATTACHMENT }o--|| ATTACHMENT_DRIVER : "由驱动提供" + PERSON }o--o{ CHARACTER : "person_character" + PERSON }o--o{ SUBJECT : "subject_person" + CHARACTER }o--o{ SUBJECT : "subject_character" + IKUSER ||--o{ SUBJECT_COLLECTION : "收藏" + IKUSER ||--o{ EPISODE_COLLECTION : "进度" + + SUBJECT { + uuid id PK + varchar type "SubjectType" + varchar name + varchar name_cn + varchar cover + varchar infobox "key:value 逐行" + varchar summary + boolean nsfw + timestamp air_time + double score + } + EPISODE { + uuid id PK + uuid subject_id FK + varchar name + varchar ep_group "EpisodeGroup" + real sequence + varchar description + timestamp air_time + } + ATTACHMENT { + uuid id PK + uuid parent_id "目录树父节点" + varchar type "File/Directory/Driver_*" + varchar url / path / fs_path + varchar name + bigint size + boolean deleted + uuid driver_id + varchar sha1 + } + ATTACHMENT_REFERENCE { + uuid id PK + varchar type "SUBJECT/EPISODE/USER_AVATAR" + uuid attachment_id + uuid reference_id + } +``` + +## 核心表与约束 + +| 表 | 作用 | 关键约束 | +|----|------|----------| +| `subject` | 条目主表 | `type`/`name`/`nsfw` 必填 | +| `episode` | 剧集/歌曲/话/章节 | **唯一 `(subject_id, ep_group, sequence, name)`** | +| `attachment` | 附件（文件） | 唯一 `(type, parent_id, name)`；不含审计字段 | +| `attachment_driver` | 附件驱动（LOCAL/WEBDAV/CUSTOM） | — | +| `attachment_reference` | 附件↔条目/剧集绑定 | `type` ∈ SUBJECT/EPISODE/USER_AVATAR | +| `attachment_relation` | 附件间关系（视频↔字幕） | `type=VIDEO_SUBTITLE` | +| `subject_collection` | 用户收藏 | `type` ∈ WISH/DOING/DONE/SHELVE/DISCARD | +| `episode_collection` | 剧集进度 | finish/progress/duration | +| `subject_relation` | 条目关系（前传/续集/OST…） | `relation_type` + 目标条目 | +| `subject_sync` | 外部同步 | **唯一 `(platform, platform_id)`** | +| `tag` | 标签（SUBJECT/EPISODE/ATTACHMENT） | — | + +> 通用约定：主键均为 uuidv7（时间有序）；业务实体默认含审计字段\n> （create_time/create_uid/update_time/update_uid/ol_version/delete_status），`attachment` 除外。 + +## 聚合视图（API 层） + +- `EpisodeRecord(episode, List)`：剧集 + 附件资源（attachmentId/url/canRead/name/tags） +- `SubjectRecord(subject, List, List, List, extra)`：条目完整聚合 +- 资源按 **attachment_id（uuidv7 时间序）** 排序 —— 漫画页序、字幕顺序即绑定顺序 + +## 各内容类型详细文档 + +- 条目结构：见主仓库 `docs/data-structure/subject.md`（含 infobox 约定、收藏/同步/关系/人员/角色关联） +- 音乐：`docs/data-structure/music.md`（专辑=Subject(MUSIC)、歌曲=Episode 映射、播放数据流） +- 漫画：`docs/data-structure/comic.md`（卷/话/页三级结构、页序约定、阅读流程） +- 小说：`docs/data-structure/novel.md`（章节=Episode、每章单文本附件、阅读流程） \ No newline at end of file diff --git a/docs/developer-guide/detailed-design.md b/docs/developer-guide/detailed-design.md new file mode 100644 index 0000000..49ba901 --- /dev/null +++ b/docs/developer-guide/detailed-design.md @@ -0,0 +1,114 @@ +--- +title: 模块详细设计 +description: Ikaros 各核心模块详细设计摘要：安全认证、条目剧集附件、收藏、目录绑定、搜索、插件、音乐、客户端 App 与测试设计 +--- + +# 模块详细设计 + +> 本文是对 Ikaros 主仓库《详细设计文档（LLD）》的模块级提炼总结， +> 完整内容见 [ikaros-dev/ikaros](https://github.com/ikaros-dev/ikaros) `docs/Low-Level-Design.md`。 + +## 模块设计总则 + +- 分层：`api`（契约）→ `server`（`endpoint` 路由 → `service` 领域服务 → `store` 数据访问） +- 服务接口与实现分离：`XxxService` / `DefaultXxxService` +- 响应式全链路：`Mono` / `Flux` 从端点贯通到 R2DBC 数据访问 +- 端点函数式注册：`SpringdocRouteBuilder` 同时生成 OpenAPI 文档 + +## 核心模块要点 + +### 安全与认证 + +- 认证链：Basic / Form / JWT / OAuth2 / TOTP（多因素可选） +- 授权：`RequestAuthorizationManager` 基于权限目标字符串做 RBAC 判定；`MASTER` 角色兜底 +- 匿名访问按端点配置（如条目列表可匿名读） + +### 用户 / 角色 + +- `ikuser` 表承载账号（username 唯一），角色（role）+ 权限目标（authority）绑定 +- 用户头像经 `attachment_reference(type=USER_AVATAR)` 绑定附件 + +### 条目（Subject）模块 + +- 统一条目模型 + `SubjectType` 枚举；`Subject` DTO 必填：`type` / `name` / `nsfw` +- `infobox` 为 `key: value` 逐行文本（前端解析为 Map 展示） +- 关联：收藏（subject_collection）、关系（subject_relation）、同步（subject_sync）、人员/角色 +- 聚合视图 `SubjectRecord`：条目 + 剧集（含资源）+ 标签 + 同步信息 + 扩展 + +### 剧集（Episode）模块 + +- 唯一约束 `(subject_id, ep_group, sequence, name)` +- 资源绑定：`attachment_reference(type=EPISODE)`，按附件 ID（uuidv7 时间序）排序返回 `EpisodeResource` +- `episode_sequence_regular`：正则责任链自动从附件文件名解析剧集序号/分组 +- 自定义剧集列表：`episode_list` 系列表 + +### 附件（Attachment）模块 + +- 目录树组织（`parent_id` 指向父目录，虚拟根 `V_ROOT_DIRECTORY_PARENT_ID`） +- 附件驱动：LOCAL / WEBDAV / CUSTOM（插件，如 S3），驱动表存挂载与凭证 +- 流式接口：`GET /attachment/stream/id/{id}`，本地代理流（Range 206）或外部直链 307 重定向 +- 附件间关系：`attachment_relation(type=VIDEO_SUBTITLE)` 视频↔字幕 + +### 收藏（Collection）模块 + +- 条目收藏：WISH / DOING / DONE / SHELVE / DISCARD + 私密 + 短评 + 评分 +- 剧集进度：finish / progress / duration，驱动"看到第几集" + +### 目录绑定工作流 + +- 责任链步骤（`DirectoryBindingStep`）：扫描预览 → 媒体探测（视频/音频/字幕轨道）→ 确认分配 → 幂等写入条目/剧集/音乐 + +### 搜索与缓存 + +- Lucene + IKAnalyzer 中文分词；索引落盘工作目录，支持重建 +- 注解缓存（Mono/Flux Cacheable/Evict），内存/Redis 可切换 + +### 插件系统 + +- PF4J 生命周期管理；扩展点：附件驱动 Fetcher、端点注册、事件监听、自定义 Scheme +- 插件打包为独立 jar 放入 `~/.ikaros/plugins` + +### 音乐模块（v1.2） + +- 专辑=Subject(MUSIC)，歌曲=Episode，音频附件经 attachment_reference 绑定 +- Subsonic 兼容端点（`/rest/**`）复用同一数据源 + +### 客户端 App + +- Flutter 六端（Windows/Android/iOS/macOS/Linux/Web） +- 看番（视频流+字幕）、听歌（音频流）、阅读（漫画逐页/小说文本） + +## 数据库表结构（LLD 第 13 章摘要） + +核心表：`subject` / `episode` / `attachment` / `attachment_driver` / `attachment_reference` / +`attachment_relation` / `subject_collection` / `episode_collection` / `subject_relation` / +`subject_sync` / `subject_person` / `subject_character` / `person` / `character` / `tag` / +`episode_list` 系列 / `episode_sequence_regular` / `custom` + `custom_metadata` / `task` / `ikuser` + +> 各表字段、约束与 ER 图见[数据模型](./data-model.md)与主仓库 `docs/data-structure/` 文档族。 + +## 关键时序图（LLD 第 14 章示例） + +```mermaid +sequenceDiagram + participant C as Console + participant E as SubjectEndpoint + participant S as SubjectService + participant R as SubjectRepository + + C->>E: GET /subject/{id} + E->>S: findById(id) + S->>R: findById(id) + R-->>S: SubjectEntity + S->>S: 转换 DTO + 聚合 Episode/资源 + S-->>E: SubjectRecord + E-->>C: JSON +``` + +## 测试设计（LLD 第 16 章摘要） + +- 单元测试：Mockito 单测为主（服务层、端点路由行为） +- 集成测试：R2DBC + 内存库（H2 PG 兼容模式） +- E2E：Console 关键链路（条目增删改、附件上传、播放） + +> 各模块完整类图、字段说明与详细时序请参考 LLD 原文。 \ No newline at end of file diff --git a/docs/developer-guide/requirements.md b/docs/developer-guide/requirements.md new file mode 100644 index 0000000..41e3a40 --- /dev/null +++ b/docs/developer-guide/requirements.md @@ -0,0 +1,69 @@ +--- +title: 产品需求 +description: Ikaros 产品需求概述：目标用户、功能需求编号体系、非功能需求与数据模型概览 +--- + +# 产品需求 + +> 本文是对 Ikaros 主仓库《产品需求文档（PRD）》的提炼总结， +> 完整内容见 [ikaros-dev/ikaros](https://github.com/ikaros-dev/ikaros) `docs/Product-Requirements-Document.md`。 + +## 产品概述 + +Ikaros 是一款自托管的番剧 / 漫画 / 音乐 / 小说内容管理与播放系统，面向个人与家庭场景： + +- 统一管理多类媒体内容（动画、漫画、游戏、音乐、小说、现实影视、其他） +- 支持本地目录扫描绑定与在线资源下载（插件生态） +- 多端消费：Web Console、Flutter 客户端（Windows/Android/iOS/macOS/Linux/Web） +- 兼容 Subsonic 客户端（音乐流媒体协议） + +## 目标用户与使用场景 + +| 用户 | 场景 | +|------|------| +| 个人媒体爱好者 | 收藏/整理本地番剧、漫画、音乐、小说，跨设备观看 | +| 家庭用户 | 集中部署（NAS/1Panel），家庭成员共享收藏与进度 | +| 轻度折腾用户 | 使用插件接入在线源（bgm.tv 同步、115、Jellyfin、Mikan 等） | + +## 功能需求编号体系 + +PRD 按域编号功能需求，格式为 `FR-<域>-<序号>`，主要域： + +| 域 | 覆盖内容 | +|----|----------| +| FR-APP | 客户端 App：看番/听歌/阅读/追番等场景 | +| FR-SUBJECT / FR-EPISODE | 条目与剧集管理 | +| FR-ATTACHMENT | 附件与附件驱动管理 | +| FR-COLLECTION | 收藏、进度、评分 | +| FR-PLUGIN | 插件体系 | +| FR-SYNC | 外部平台同步（bgm.tv / TMDB / AniDB / TVDB / VNDB / 豆瓣） | + +> 该编号体系同时用于需求与设计文档的追溯（LLD 各模块章节引用对应 FR）。 + +## 非功能需求（NFR）要点 + +- 响应式性能：流媒体播放与目录扫描场景低资源占用、高吞吐（技术选型见[系统架构](./architecture.md)） +- 可部署性：Docker / 1Panel / 快速启动 Jar 三种方式 +- 数据安全：默认强制登录，匿名访问可配置；附件访问鉴权集中 +- 可扩展性：插件（PF4J）与自定义 Scheme 双通道扩展 + +## 数据模型概览（PRD 视角） + +PRD 中描述的数据模型与主仓库《内容数据结构文档》一致： + +- **条目（Subject）**：统一模型，`type` 区分 ANIME/COMIC/GAME/MUSIC/NOVEL/REAL/OTHER +- **剧集（Episode）**：条目的二级结构（集/歌曲/话/章节），`group` + `sequence` 组织 +- **附件（Attachment）**：文件实体，经 `attachment_reference` 绑定条目/剧集 + +> 详细结构见[数据模型](./data-model.md)。 + +## 版本规划与里程碑（摘要） + +| 版本 | 重点 | +|------|------| +| v1.0 | 条目/剧集/附件基础模型、Web Console、本地附件驱动 | +| v1.1 | 附件驱动扩展（WebDAV）、目录绑定、收藏进度 | +| v1.2 | 音乐模块、子索尼克（Subsonic）兼容、目录绑定工作流、搜索 | +| 后续 | 客户端 App 六端、漫画/小说阅读体验完善、插件生态扩充 | + +> 详细章节（风险与约束、成功指标、附录）请参考 PRD 原文。 \ No newline at end of file diff --git a/sidebars.js b/sidebars.js index be3312d..a1f52e0 100644 --- a/sidebars.js +++ b/sidebars.js @@ -63,6 +63,21 @@ const sidebars = { "user-guide/faq" ] }, + { + "type": "category", + "label": "developer-guide", + "link": { + "type": "generated-index" + }, + "collapsed": false, + "items": [ + "developer-guide/requirements", + "developer-guide/architecture", + "developer-guide/detailed-design", + "developer-guide/data-model", + "developer-guide/contribution-guide" + ] + }, { "type": "category", "label": "plugins",