91 lines
14 KiB
Markdown
91 lines
14 KiB
Markdown
# 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。
|