Files
MySpace/docs/v4-development.md

91 lines
14 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# MySpace V4 开发交接
更新:2026-11-11。本文是新版 UI、交互和后续任务的入口。现有接口以代码为准,[API 文档](api.md)记录现有契约,[历史交接](handoff.md)和[原计划](implementation-plan.md)供追溯。下文保留 V4 全量目标。当前工程已实现后台导航及工具子路由、工作台、四个内容模块、统一回收站、笔记版本、RSS 手动刷新、效率中心、收集箱、备份和 AI Studio。模型能力由部署配置启用。访客生成和定时工作流仍待开放。
## 1. 参考与取舍
原型目录:`/Users/xzh/Documents/MySpace/MySpace_修复版_V4`。保持四个 HTML 与两个 JS 在同一目录;从 `MySpace-管理后台.html` 打开,在右上角「公开发布」同步,再从后台分别打开三张公开页。对照时建议以同一个本地静态站点提供四页,避免不同浏览器对直接打开文件时的存储行为影响判断。
| 原型文件 | 开发参考 |
|---|---|
| `MySpace-管理后台.html` | 后台页面、工具中心、发布中心、各模块联动;以最后加载的 V4 修复层及实际事件为准 |
| `MySpace_Public_Blog.html` | 公开博客列表、分类、搜索、阅读详情、订阅入口 |
| `MySpace_Public_Nav.html` | 公开导航分组、链接卡片与主题 |
| `MySpace_Public_AI.html` | 对话/生图入口、模型选择、提示词书架、访客会话和公开图片 |
| `myspace-client.js`、`admin_router.js` | 浏览器快照、主题、错误提示和原型路由参考 |
| `README_修复说明_V4.md` | 变更和历史验收线索;末尾「公开页面导航调整」覆盖正文的旧互跳描述 |
**公开页独立。** 后台可进入博客、导航和 AI,三张公开页均不放其他公开页或后台的入口(包括移动菜单和浮动入口)。保留各自业务导航、主题切换和发布状态。
**复刻交互,重写数据层。** 原型用 localStorage 在同浏览器同步,且包含模拟 AI、RSS 示例和叠加事件处理。正式版沿用 Vue/TypeScript、Spring Boot、PostgreSQL、Flyway、登录 Cookie 与 CSRF。业务记录和发布结果以服务器为准;本地只保存主题、视图偏好、可清除的访客会话等。生产空状态与加载失败独立呈现,不混入示例文章、模型或订阅。
## 2. 页面范围及实现差距
| 页面 | V4 目标及开发切入点 |
|---|---|
| 工作台 | 沿用已有统计和最近笔记;补快捷收集、待办摘要、通知和发布状态。计数来自实际记录。 |
| 知识库 | 现有笔记 CRUD、分类、收藏、Markdown 编辑与预览继续使用。新增文件夹、多标签、网格/列表、筛选排序、批量操作、模板、双链/反链及图谱;编辑器补 AI 助手、配图、版本与导出。分类与文件夹是两个维度。 |
| 博客 | 复用现有草稿/已发布、Markdown、摘要、封面和 slug;补分类、图床/生成封面、从笔记建草稿、转笔记、公开预览。公开 URL 沿用 `/blog`、`/blog/:slug`。 |
| 图床 | 复用真实上传、预览、下载。新增图片/文件视图、文件夹、标签、批量移动/删除、详情与复制链接/Markdown。私有素材使用认证地址;公开素材使用受发布范围约束的稳定地址。 |
| 书签 | 已有新增、删除、分类和图床图标;补编辑、收藏、多标签、手动顺序、列表/卡片、批量操作、浏览器 HTML/JSON 导入导出、公开勾选。沿用 `/bookmarks`;仅接受 HTTP(S) 网址,导入先预览去重并显示跳过原因。 |
| RSS | 新增订阅源、分类、抓取状态、阅读器、已读/收藏、搜索和批量标记;文章可存笔记、待办、收集箱或发给 AI 摘要。删除订阅保留已抓取内容。 |
| 效率中心 | 新增待办、日历、代码片段。待办支持完成和状态筛选;日程可创建、编辑、删除;代码片段可编辑、复制。 |
| AI Studio | 新增对话、生图、供应商、模型、历史、素材库、提示词、用量、日志、偏好。历史区分对话/图片,素材库区分全部/收藏;模型失效时清理失效筛选和默认项,区分未生成与未收藏。 |
| 工具中心 | 七个入口:标签管理、版本历史、回收站、批量管理、自动化工作流、浏览器工具、联动说明。以真实计数和状态展示,另提供收集箱、全局搜索、公开发布入口。自动化和浏览器工具的服务端能力分期,未接通时说明限制。 |
| 收集箱 | 新增手动快速收集及浏览器捕捉入口,记录标题、内容/网址、来源和处理状态;整理成笔记、书签或待办。 |
| 设置 | 新增资料、主题与编辑偏好、备份导入导出。导入先校验版本和预览影响;缺失模块不注入样例。凭据不随备份导出,附件备份是否包含文件须在界面说明。 |
| 公开博客 | 复用 `PublicBlog.vue`,补 V4 分类、更多分类、搜索和发布状态;搜索与分类可叠加,详情支持直接打开和返回。RSS 入口只在真实订阅地址就绪后启用。 |
| 公开导航 | 复用 `PublicBookmarks.vue`,按公开分类和顺序展示,空分组不渲染;统一绿色系与深浅色,保留网址访问和图标失败回退。 |
| 公开 AI | 新增建议路径 `/ai`。欢迎页、模型选择、提示词填入、对话/生图、访客历史搜索与回看、公开图集;真实能力未就绪时明确禁用。 |
后台主导航按 V4 顺序:工作台 → 知识库 → 博客 → 图床 → 书签 → RSS → 效率中心 → AI Studio → 工具中心 → 收集箱 → 设置。工具中心子页用独立路由状态;父入口、子页名称、面包屑、页面标题和浏览器返回一致。现有后台入口继续可达,管理深链可采用 `/admin/...`,确认前端回退配置并保留原入口。搜索弹窗支持 Cmd/Ctrl+K,结果按类型携带稳定 ID,进入对应详情而非仅切换模块;覆盖笔记、博客、素材、书签、RSS、待办、日程、代码片段、提示词、AI 会话和图片,未交付的模块随其上线纳入。
## 3. 关键流程和数据规则
### 公开发布
- **现状**:公开博客直接读已发布文章;公开书签接口及图标接口目前没有可见性过滤,所有现有书签可被匿名列出。V4 原型首次发布可能默认全选书签,发布函数传入全量提示词开关,空模型白名单也可能回退到全部。正式版不继承这些默认行为。
- **目标**:发布面板列出符合条件的文章,允许明确勾选书签、提示词、模型及图片,并设置访客生图。新建书签/提示词/图片默认私有,空白名单代表关闭全部模型,生图默认关闭。发布前预览数量,显示最近成功时间及「有改动待同步」,支持导出同一份公开数据 JSON。
- **建议契约**:`GET /api/v1/publication` 返回待发布预览、当前发布版本、时间和差异;`POST /api/v1/publication` 按预览版本原子提交,只生成允许公开的字段与资源引用,返回新版本和各模块数量。公开接口保留原路径和可兼容字段,以服务器发布版本作为 ETag 的一部分。发布失败保留旧版本并显示原因。草稿化、取消公开、移入回收站、禁用模型或关闭生图立即在服务端撤销可见性/执行权;恢复只回私有区或草稿,重新公开需显式操作。
- **迁移**:升级前列出现有公开博客、书签及图片引用。已有已发布博客可作为首版基线保留原 slug;现有书签在管理员明确勾选前不进入新发布清单。切换时同时替换匿名列表、详情和图片的权限条件;验证清空选择、缓存更新、直接访问旧图标地址和无登录的新设备。公开响应不得含供应商凭据、内部日志或未选内容。
### 回收站与版本
- 笔记、博客、书签、图床素材、日程、代码片段的单条及批量删除统一进回收站。现有四类 DELETE 需改为软删除;所有常规列表、搜索、计数和公开读取排除已删除。图床保留文件字节直到永久删除;有活跃引用的素材永久删除前显示影响并拒绝操作,待引用解除后重试。
- 建议保留源记录及 ID,增加删除时间并用统一回收站视图查询;`GET /api/v1/trash` 支持按类型分页,`POST /api/v1/trash/{kind}/{id}/restore` 恢复,`DELETE /api/v1/trash/{kind}/{id}` 永久删除。原分类/文件夹还在则回原位置,缺失则提示选择替代位置;恢复失败保留记录,成功写入通知。清空需要明确确认与逐项结果。
- 笔记的有效保存(含自动保存)在同一事务中记录保存前的标题、正文、分类、文件夹、标签等,再提交正文与版本号;无变化不生成重复快照。历史使用不可变版本 ID,可按笔记分页查询/预览。恢复前再存当前版本,使用现有乐观锁;冲突返回 409 并保留编辑稿。编辑器两个导出入口生成相同 UTF-8 Markdown,YAML 用序列化器处理标题、标签、换行和特殊字符。保留策略独立配置,不沿用原型数组截断作为生产规则。
### 模块联动与 AI
- RSS → 笔记、待办、收集箱;笔记 → 博客草稿,博客 → 可编辑笔记;书签 → 收集箱(含网址和描述),素材 → 收集箱(元数据和内部引用);收集箱 → 笔记/书签/待办。保留来源 ID 或链接,创建成功后才更新收集状态,重试不重复创建。完成后提供打开目标入口。
- 笔记 AI 助手、笔记配图、博客封面和 RSS 摘要进入对应 AI 模式并预填提示词;引用卡片按 ID 打开原文,再返回时保留对话和未发送草稿。生成结果经用户选择可存图床并作为封面;生成过程不自动发布或修改正文。
- 输入限制统一为 8000 字符;后台按原型在预填/提交前提示并提供截断后的可编辑预览,访客侧超限显示计数、禁用发送;后端按相同计数规则校验并拒绝超限。访客发送时重新校验模型 ID、供应商及能力开关,公开接口只返回可展示字段。凭据仅后端保存;AI 失败保留草稿,日志和用量只记录必要字段,访客调用设置频率、用量限制和超时。访客历史与管理员会话隔离。
- RSS 抓取、AI 服务和工作流接入前,UI 只展示可用能力。正式 RSS 刷新显示成功时间与失败状态,按来源和文章标识去重;自动化执行和工具接入后单独定义权限、运行记录与失败恢复。
## 4. 实施顺序
| 批次 | 工作包与交付条件 |
|---|---|
| A:发布边界和 UI 骨架 | 统一后台壳、工具入口、三张公开页入口规则;完成公开书签和图片过滤、发布面板及发布版本;改造已存在的公开博客/导航并保留旧链接。AI 页可先显示能力关闭状态。 |
| B:现有模块完整流程 | 笔记、博客、图床、书签扩展字段和编辑交互;同批接入统一回收站、笔记版本与 Markdown 导出。验证现有库升级、分类和原 slug。 |
| C:新增本地业务 | 收集箱、效率中心、标签/批量、通知、全局搜索、备份;补齐笔记/博客/素材/书签之间的联动。新增模块随交付接入搜索与回收站。 |
| D:外部服务 | RSS 订阅与真实抓取、AI Studio 与公开 AI、用量与日志、自动化和浏览器工具的后端接入。分别验证权限、失败恢复与实际调用;按能力开放。 |
开发入口:`frontend/src/main.ts` 负责公开页入口,`App.vue` 是现有后台,`api.ts` 是接口层;按模块拆出页面与状态,复用 Markdown 和素材组件。后端沿用现有 controller、认证及集成测试,从下一未使用的 Flyway 版本开始(当前目录最大 V16)。迁移新增字段先回填再约束;保留现有 UUID、slug、分类关系和文件引用。不改已应用 SQL。不自动导入 HTML 原型示例;若后续需要迁移真实原型数据,应走带校验和预览的显式导入,包含旧回收站按类型和源 ID 去重。
## 5. 验收清单
| 编号 | 验收场景 |
|---|---|
| V4-01 | 工具中心七个入口均打开对应页面;面包屑、高亮、浏览器返回和刷新后的路由一致;无重复一级导航。 |
| V4-02 | 六种支持对象单条删除、各支持模块批量删除后,从列表、搜索及公开页消失;恢复保持 ID 和分类或明确要求重选;永久删除后不可恢复。 |
| V4-03 | 自动和手动保存分别产生有效历史,无变化不重复;可预览、恢复且恢复前留档;并发冲突不覆盖另一稿。两个导出入口能下载并解析含特殊字符的 YAML。 |
| V4-04 | 在无登录的新浏览器验证已发布文章、选中书签/提示词/图片和白名单模型;草稿、未选内容、直链图片及空模型名单不泄露。失败保留原发布版本,撤回后重新请求拿不到旧内容。 |
| V4-05 | 公开博客分类与搜索组合可用,详情直链和返回正常;公开导航分组正常;三张公开页均无互跳或后台入口,后台仍可打开三页。 |
| V4-06 | AI 历史/素材筛选可切换;禁用模型后默认项修正;无生成/无收藏状态不同;8000 和 8001 字符边界前后端一致;关闭生图后访客既不能从 UI 发送也不能直接调用。 |
| V4-07 | 笔记引用回原文后返回 AI 草稿仍在;配图/封面预填正确;搜索同名结果打开各自 ID;RSS/收集箱转存失败后仍可重试且不重复创建。 |
| V4-08 | 按 1150、900、680、430px 断点两侧及 360px 检查工具中心、编辑器、设置、AI 和三张公开页;深浅色、键盘焦点、弹窗关闭后焦点恢复、错误提示可见、页面无横向溢出。 |
| V4-09 | 用空库和已有数据各跑一次迁移;已有公开文章 slug、登录、笔记、上传下载继续工作。备份导入预览及错误分支不改原有数据。 |
每批在后端集成测试覆盖访问权限、迁移和状态变化,在浏览器验收端到端关键流程。原型 README 中的 24 项后台和 7 项公开页通过记录仅作为原型历史,不能替代工程验收;当前实现范围见工程 README。