diff --git a/docs/docs-handoff.md b/docs/docs-handoff.md new file mode 100644 index 00000000..0c7d89a2 --- /dev/null +++ b/docs/docs-handoff.md @@ -0,0 +1,20 @@ +# 站外文档交接 + +应用仓库维护实现、兼容边界和可运行示例;[ray-template-doc](https://github.com/XiaoDaiGua-Ray/ray-template-doc) 负责读者指南、迁移步骤、站点导航和视觉。站外文档基于明确的源码提交,站点构建不读取本机应用仓库。 + +本轮基线:`548de9427d59502cdc7f06b86943f8c0dba9f907`;包版本为 `5.2.5`,迁移对照标签为 `v5.2.4`。这里记录的是源码行为;是否打标签和发布需要另行核实。 + +| 领域 | 应用侧证据 | 必须交代的边界 | +| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| 组件入口与 TablePro | [公开导出](../src/components/index.ts)、[TablePro 契约](../src/components/RTablePro/README.md)、[六个示例](../src/views/demo/tables) | `base/`、`pro/` 深层路径失效;`RTable`、`useTable`、`useTablePro` 已移除。远端 `total` 是筛选后的总数;取消依赖请求函数传递 signal;导出和打印默认仅当前页可见数据列。 | +| 路由与权限 | [路由说明](../src/router/README.md)、[路由类型](../src/router/types.ts)、[权限守卫](../src/router/utils/permission.ts) | 菜单显隐不等于访问授权;会话和接口权限由后端校验。缓存需要路由 name 对应组件 name,验证菜单进入、直达和刷新。 | +| 布局与 Pinia | [布局插槽和偏好](../src/layout/README.md)、[Store 约定](../src/store/README.md) | 全局 UI 单例已迁入 `runtime`,不持久化。保留历史设置和锁屏格式;自定义内容插槽时,由接入方负责保留请求取消及路由缓存。 | +| 请求与 Mock | [Axios 实现](../src/axios/instance.ts)、[取消器](../src/axios/utils/RequestCanceler.ts)、[人员查询](../src/api/demo/mock/person.ts) | 实例成功返回 body,失败拒绝;调用方传 signal 时关闭模板的默认 signal 注入。Mock HTTP 仅用于开发,静态演示有独立本地数据分支。 | +| Hooks、工具与图标 | [Hooks 行为](../src/hooks/README.md)、[工具兼容入口](../src/utils/README.md)、[图标生成](../src/icons/A_README.md) | `@/hooks` 与 `@/utils` 公共入口保留;旧裸图标仅在缓存读取边界按唯一名称迁移。截图和打印测试不代表原生浏览器能力验收。 | +| 工具链与部署 | [工具链记录](toolchain-upgrade.md)、[架构地图](architecture.md)、[Vite 配置](../vite.custom.config.ts) | Node/pnpm 以清单为准。应用默认 base 为 `/ray-template/`,站外文档为 `/ray-template-doc/`;应用生产部署上传 `dist/production`。 | + +## 联动流程 + +1. 应用改动影响公开导入、配置、缓存或行为时,先更新所属模块的 README 和示例,写清旧用法、新用法、兼容性及回归路径。记录已验证的应用提交;可从 `pnpm harness context` 定位任务域。 +2. 文档仓库在对应变更中标注应用提交,按任务组织教程,给关键说法附固定提交的源码链接。破坏性改动进入迁移清单;旧 URL 映射到新版主题,旧正文可从历史提交查阅。 +3. 应用运行 `pnpm harness verify`;文档运行 `pnpm build` 并预览生产子路径,检查导航、搜索、旧链接、明暗主题和窄屏。两个仓库的变更互相链接。发布前确认文档引用的应用提交已可访问,且在线演示已部署相应能力。 diff --git a/harness/README.md b/harness/README.md index d9bbcb2d..3e7c6dc9 100644 --- a/harness/README.md +++ b/harness/README.md @@ -51,4 +51,6 @@ GitHub Actions 在 Linux、Windows 和 macOS 运行同一份 `pnpm check`。单 ## 维护 +影响外部读者的功能或兼容性改动,按 [站外文档交接](../docs/docs-handoff.md) 同步到文档仓库。 + 任务域的路径或测试位置变化时,更新 `scopes.json` 并运行 `pnpm harness check`。测试目录以 `/` 结尾,单个文件使用仓库相对路径。优先完善现有测试和上下文入口,把可稳定复现的失败纳入共同检查。 diff --git a/src/axios/README.md b/src/axios/README.md index 8796e4b9..2fbd0918 100644 --- a/src/axios/README.md +++ b/src/axios/README.md @@ -1,71 +1,23 @@ -## 说明 +# 请求与拦截器 -> axios 包,全局的 axios 使用入口 -> `src/axios/instance.ts` 文件为 axios 实例文件,应该不可更改,如果需要有拦截器相关的操作,应该在 `src/axios/inject` 文件下按照需求在对应注册器中进行注册相关方法。该项目将 axios instance 与 axios interceptor 进行解耦,避免实例文件的臃肿。 +业务接口放在 `src/api`,使用 `@/axios` 导出的 `request`。成功拦截器返回响应体,`request()` 解析为 `T`;失败仍拒绝。需要响应头或 HTTP 状态时,使用保留完整响应的 Axios 实例。 -## 工具函数 +默认请求配置位于 `src/app-config/request-config.ts`。通用请求和响应逻辑分别放入 `axios-interceptor/request/plugins` 与 `axios-interceptor/response/plugins`,在各自的 `provider.ts` 中登记。成功队列使用 `AxiosRequestInterceptor` 或 `AxiosResponseInterceptor`,失败队列使用 `FetchErrorFunction`;调整队列顺序时核对前置逻辑。 -- FetchFunction -- FetchErrorFunction +## 取消请求 -> 两个工具函数方便类型推导。 - -## 约束 - -### 拦截器添加 - -> 这里以请求拦截器添加为示例 +默认取消器按 URL、方法、序列化参数与请求体识别重复请求,并为当前请求注入 signal。默认布局中的 `AppRequestCancelerProvider` 会在路由更新前取消受它管理的待处理请求。 ```ts -/** - * - * 拦截器说明 - * - * 注册一个根据系统当前环境是否携带测试环境请求拦截器 - */ +import { request } from '@/axios' -import { appendRequestHeaders } from '@/axios/helper/axiosCopilot' -import type { - FetchErrorFunction, - FetchFunction, - RequestInterceptorConfig, -} from '@/axios/types' - -const injectRequestHeaderOfEnv: FetchFunction = ( - ins, - mode, -) => { - if (mode === 'development') { - appendRequestHeaders(ins, [ - { - key: 'Development-Mode', - value: 'development', - }, - ]) - } -} - -/** - * - * 在 setupRequestInterceptor 中注册 - */ - -export const setupRequestInterceptor = () => { - setImplement( - 'implementRequestInterceptorArray', - [injectRequestHeaderOfEnv], - 'ok', - ) -} - -/** 至此完成了请求拦截器的注册 */ +const loadOrders = (signal: AbortSignal) => + request<{ id: string }[]>({ + url: '/api/orders', + method: 'get', + signal, + cancelConfig: { cancel: false }, + }) ``` -### 注册器 - -> 每个类型注册器都有两个方法,用于注册拦截器方法。都以 setupXXX 开头命名。注册器以队列形式管理拦截器方法,所以可能需要注意执行顺序。如果有新的拦截器方法,需要根据其使用场景在对应的注册器中注册(注册器第二个参数中注册)。 - -- 请求注册器: setupRequestInterceptor -- 请求错误注册器: setupRequestErrorInterceptor -- 响应注册器: setupResponseInterceptor -- 响应错误注册器: setupResponseErrorInterceptor +调用方提供 signal 时,将 `cancelConfig.cancel` 设为 `false`,避免被默认取消器覆盖,并由调用方负责中止。人员列表展示了 [TablePro 传递 signal 的方式](../api/demo/mock/person.ts)。`useRequest` 包装同一实例,需在有效的 Vue effect 作用域中调用。