ray-template/docs/docs-handoff.md
2026-11-04 16:47:18 +08:00

5.6 KiB
Raw Permalink Blame History

应用与文档联动

读者指南、迁移步骤和 API 参考在 apps/docs 维护。VitePress 与应用共用 workspace 锁文件,从同一工作区加载交互示例。旧站内容和历史保留在 ray-template-doc。

官网当前面向 v6,源码链接使用 Monorepo 路径,发布构建时用 RAY_TEMPLATE_SOURCE_REF 固定到发布提交。页内示例随工作区源码构建。v5 的源码与发布标签见版本分界。

领域 应用侧证据 必须交代的边界
组件入口与 TablePro 公开导出、TablePro 契约、表格示例 base/、pro/ 深层路径失效;RTable、useTable 已移除。useTablePro 保留注册写法,提供 isReady 和当前页取数。远端 total 是筛选后的总数;取消依赖请求函数传递 signal;导出和打印默认仅当前页可见数据列。
路由与权限 路由说明、路由类型、权限守卫 菜单显隐不等于访问授权;会话和接口权限由后端校验。缓存需要路由 name 对应组件 name,验证菜单进入、直达和刷新。
布局与 Pinia 布局插槽和偏好、Store 约定 全局 UI 单例已迁入 runtime,不持久化。保留历史设置和锁屏格式;自定义内容插槽时,由接入方负责保留请求取消及路由缓存。
请求与 Mock Axios 实现、取消器、人员查询 实例成功返回 body,失败拒绝;调用方传 signal 时关闭模板的默认 signal 注入。Mock HTTP 仅用于开发,静态演示有独立本地数据分支。
Hooks、工具与图标 Hooks 行为、工具兼容入口、图标生成 @/hooks 与 @/utils 公共入口保留;旧裸图标仅在缓存读取边界按唯一名称迁移。截图和打印测试不代表原生浏览器能力验收。
工具链与部署 工具链记录、架构地图、Vite 配置 Node/pnpm 以清单为准。应用 base 为 /ray-template/,内置文档为 /ray-template/docs/。已发布旧站仍使用 /ray-template-doc/。

联动流程

  1. 应用改动影响公开导入、配置、缓存或行为时,在同一变更更新模块说明及 apps/docs 中受影响的文档和示例。破坏性改动进入迁移清单。
  2. 展示正在运行的示例源码。轻量示例位于 apps/docs/examples,使用共享包的公开入口;需要后台上下文的示例嵌入 example.html,源码引用指向实际的后台演示页。定位入口见文档主题索引。
  3. 运行 pnpm harness verify,再用 pnpm docs:preview 在 /ray-template/docs/ 检查导航、搜索、旧路径、明暗主题、窄屏和交互。线上迁址另行验证新旧地址。

待同步到读者指南的内容

应用侧已准备好 路由接入文档、Schema、Segment 说明 和 页面设计说明。在 apps/docs/guide/routing.md 补充来源切换、接口示例和版本校验,在组件参考中补充 fitContent 的选中态与过渡规则。截图使用更新后的登录页与管理页,并核对部署子路径。

guide/layout.md 补充减少动态效果和浮动退出按钮;guide/routing.md 增加可视化与 JSON 两个入口,明确可视化应用仅保存在当前浏览器;reference/hooks/layout.md 说明加载提示以可见内容区为基准。

guide/layout.md 同步设置抽屉的偏好导入导出:JSON 只包含抽屉内偏好,校验通过后即时保存,独立于路由管理的 JSON 配置。