feat(harness): add task-oriented repository index

This commit is contained in:
XiaoDaiGua-Ray 2026-11-04 16:47:18 +08:00
parent 58fc0b63a6
commit 85b5fc628d
No known key found for this signature in database
22 changed files with 539 additions and 233 deletions

View File

@ -1,9 +1,9 @@
# Ray Template
Vue 3 + TSX 中后台模板。项目协作、定向验证和交付证据统一从 [AI Harness](harness/README.md) 开始。按任务选择上下文,不必通读仓库。
Vue 3 + TSX 中后台模板,包含后台应用、文档站与共享包。
- `pnpm harness context` 列出任务域。`pnpm harness context <scope>` 给出入口、约定与回归命令。跨模块变更可查 [架构地图](docs/architecture.md)。
- 需要定位实现时,从 [任务索引](llms.txt) 或 `pnpm harness context <scope>` 选相关主题。跨模块变更再查 [架构地图](docs/architecture.md)。
- 先看 `git status`,保留已有改动。变更路由、持久化、请求或公共组件时,追踪调用方和现有数据契约。
- 新增或修改注释时遵循 [注释规范](docs/comment-style.md)。页面文案同时维护中英文,页面改动按 Harness 指南验收。
- 完成实现后运行 `pnpm harness verify`。它执行 `pnpm check` 并留存结果。交付说明实际验证及未验证项。
- 新增或修改注释时遵循 [注释规范](docs/comment-style.md)。页面文案同时维护中英文,页面改动按 [Harness 指南](harness/README.md#浏览器验收) 验收。
- 完成实现后运行 `pnpm harness verify`,执行全量检查并留存报告。交付说明实际验证及未验证项。
- 使用当前源码、清单和锁文件核对工程事实。敏感数据不进入源码、提示词或证据。提交、推送与部署遵循用户授权。

View File

@ -134,4 +134,4 @@ Use the [architecture map](docs/architecture.md) to find module and configuratio
[MIT License](LICENSE) · [Changelog](CHANGELOG.md) · [Issues](https://github.com/XiaoDaiGua-Ray/ray-template/issues)
Agents can start with the [LLM entry point](llms.txt) and open only the relevant task scope.
Use the [task index](llms.txt) to find the owning implementation, its consumers, and verification steps without installing dependencies. `pnpm harness context <scope>` shows the same index entry alongside the commands it runs.

View File

@ -134,4 +134,4 @@ export default defineComponent({
[MIT 许可证](LICENSE) · [更新日志](CHANGELOG.md) · [问题反馈](https://github.com/XiaoDaiGua-Ray/ray-template/issues)
AI 助手可从 [LLM 入口](llms.txt) 按任务读取源码和验证命令。
从[任务索引](llms.txt)查找实现归属、调用方和验证方式,无需安装依赖。`pnpm harness context <scope>` 显示同一份索引及验证命令。

View File

@ -17,26 +17,31 @@ let fixture: string
beforeEach(() => {
fixture = mkdtempSync(join(tmpdir(), 'ray-harness-'))
mkdirSync(join(fixture, 'harness'))
mkdirSync(join(fixture, 'harness/context'), { recursive: true })
mkdirSync(join(fixture, 'docs'))
mkdirSync(join(fixture, '__test__/demo'), { recursive: true })
copyFileSync(
new URL('../../harness/run.mjs', import.meta.url),
join(fixture, 'harness/run.mjs'),
)
for (const path of [
'AGENTS.md',
'docs/architecture.md',
'docs/docs-handoff.md',
'harness/README.md',
'harness/plan.md',
]) {
writeFileSync(join(fixture, path), '# Fixture\n')
}
writeFileSync(join(fixture, 'llms.txt'), '[Demo](harness/context/demo.md)\n')
writeFileSync(
join(fixture, 'harness/scopes.json'),
JSON.stringify({
demo: {
description: 'Demo',
paths: ['harness'],
tests: ['__test__/demo/'],
},
}),
)
writeFileSync(
join(fixture, 'package.json'),
JSON.stringify({ scripts: { 'env:check': 'node -e "process.exit(23)"' } }),
join(fixture, 'harness/context/demo.md'),
'# Demo\n\n先读 [架构](../../docs/architecture.md#fixture)。\n',
)
writeScope({ tests: ['__test__/demo/'] })
writeScripts({ 'env:check': 'node -e "process.exit(23)"' })
})
afterEach(() => {
@ -50,6 +55,26 @@ function run(...args: string[]) {
})
}
function writeScope(targets: { tests?: string[]; checks?: string[] }) {
writeFileSync(
join(fixture, 'harness/scopes.json'),
JSON.stringify({ demo: { description: 'Demo', ...targets } }),
)
}
function writeScripts(scripts: Record<string, string>) {
writeFileSync(join(fixture, 'package.json'), JSON.stringify({ scripts }))
}
function readReport() {
const runs = join(fixture, '.harness-local/runs')
const [runDirectory] = readdirSync(runs)
return JSON.parse(
readFileSync(join(runs, runDirectory, 'report.json'), 'utf8'),
)
}
it('拒绝没有回归用例的目录', () => {
const result = run('check')
@ -57,18 +82,72 @@ it('拒绝没有回归用例的目录', () => {
expect(result.stderr).toContain('回归测试路径没有用例:__test__/demo/')
})
it('移动索引引用的实现后,检查会报告来源与断链', () => {
writeFileSync(join(fixture, '__test__/demo/example.spec.ts'), '')
expect(run('check').status).toBe(0)
rmSync(join(fixture, 'docs/architecture.md'))
const result = run('check')
expect(result.status).toBe(1)
expect(result.stderr).toContain(
'harness/context/demo.md 的相对链接无效:../../docs/architecture.md#fixture',
)
})
it('拒绝未从静态入口链接的已注册主题', () => {
writeFileSync(join(fixture, '__test__/demo/example.spec.ts'), '')
writeFileSync(join(fixture, 'llms.txt'), '# 空入口\n')
const result = run('check')
expect(result.status).toBe(1)
expect(result.stderr).toContain('llms.txt 缺少可用的主题链接')
})
it('无 Vitest 的任务域能展示索引并执行现有项目检查', () => {
writeScope({ checks: ['docs:check'] })
writeScripts({
'env:check': 'node --version',
'docs:check': 'node -e "console.log(process.cwd())"',
})
expect(run('check').status).toBe(0)
const context = run('context', 'demo')
expect(context.status).toBe(0)
expect(context.stdout).toContain(
'先读 [架构](../../docs/architecture.md#fixture)',
)
expect(context.stdout).toContain('pnpm docs:check')
expect(run('verify', 'demo').status).toBe(0)
expect(readReport()).toMatchObject({
scope: 'demo',
status: 'passed',
steps: [
{ command: 'pnpm env:check', exitCode: 0 },
{ command: 'pnpm docs:check', exitCode: 0 },
],
})
})
it('拒绝把全量检查登记为定向检查,避免递归调用', () => {
writeScope({ checks: ['check'] })
writeScripts({ check: 'node harness/run.mjs check' })
const result = run('verify', 'demo')
expect(result.status).toBe(1)
expect(result.stderr).toContain('demo 的检查命令未注册:check')
})
it('子命令失败时停止后续验证,并记录失败状态', () => {
writeFileSync(join(fixture, '__test__/demo/example.spec.ts'), '')
const result = run('verify', 'demo')
const runs = join(fixture, '.harness-local/runs')
const [runDirectory] = readdirSync(runs)
const report = JSON.parse(
readFileSync(join(runs, runDirectory, 'report.json'), 'utf8'),
)
expect(result.status).toBe(23)
expect(report).toMatchObject({
expect(readReport()).toMatchObject({
scope: 'demo',
status: 'failed',
steps: [{ command: 'pnpm env:check', exitCode: 23 }],

View File

@ -2,21 +2,21 @@
## 常用命令
| 命令 | 用途 |
| -------------------------------- | ---------------------------------------------------------- |
| `pnpm env:check` | 校验 Node、pnpm 与依赖安装 |
| `pnpm dev` | 同步图标清单并启动 Vite |
| `pnpm harness context` | 查任务域;追加 `routing`、`ui`、`api` 等可看实现入口和回归 |
| `pnpm harness verify ui` | 按域运行定向测试 |
| `pnpm harness verify` | 运行全量检查并生成本地报告 |
| `pnpm typecheck` | 验证图标清单,检查应用、Node 配置和测试类型 |
| `pnpm dev-build` / `pnpm report` | 构建开发版,或输出静态打包报告 |
| `pnpm build` / `pnpm preview` | 构建并在本机验收产物 |
| `pnpm packages:check` | 检查公开入口、依赖声明和循环依赖 |
| `pnpm pages:build` | 将后台与文档组装到 `dist/pages` |
| `pnpm docs:dev` | 启动文档开发站 |
| `pnpm docs:check` | 验证文档示例类型、站内链接与生产构建 |
| `pnpm docs:preview` | 预览已构建的文档站 |
| 命令 | 用途 |
| -------------------------------- | -------------------------------------------------------------- |
| `pnpm env:check` | 校验 Node、pnpm 与依赖安装 |
| `pnpm dev` | 同步图标清单并启动 Vite |
| `pnpm harness context` | 查任务域;追加 `routing`、`table-pro`、`docs` 等查看实现与验证 |
| `pnpm harness verify table-pro` | 按域运行定向测试或项目检查 |
| `pnpm harness verify` | 运行全量检查并生成本地报告 |
| `pnpm typecheck` | 验证图标清单,检查应用、Node 配置和测试类型 |
| `pnpm dev-build` / `pnpm report` | 构建开发版,或输出静态打包报告 |
| `pnpm build` / `pnpm preview` | 构建并在本机验收产物 |
| `pnpm packages:check` | 检查公开入口、依赖声明和循环依赖 |
| `pnpm pages:build` | 将后台与文档组装到 `dist/pages` |
| `pnpm docs:dev` | 启动文档开发站 |
| `pnpm docs:check` | 验证文档示例类型、站内链接与生产构建 |
| `pnpm docs:preview` | 预览已构建的文档站 |
全量检查包含环境、Harness、图标同步、类型、ESLint、Prettier、Vitest 和生产构建。Harness 在 `.harness-local/runs/` 写结果;Chrome 验收单独记录。改动交互或布局时,额外验收中英文、明暗主题和窄屏。

View File

@ -1,79 +1,63 @@
# 架构地图
Ray Template 是前端中后台模板,包含可运行的组件与路由示例。Mock 只用于演示;接入真实业务时需要自己的后端、会话和权限校验。
Ray Template 是一个 pnpm workspace:后台负责宿主集成,文档站解释公开用法,共享包拥有可复用实现。按功能定位文件从[任务索引](../llms.txt)进入;本页用于判断代码归属和追踪跨模块调用。
Ray Template 由一个 pnpm workspace 管理。**Ray Admin** 位于 `apps/admin`,在应用入口接入路由、会话、主题和数据。**文档**位于 [apps/docs](../apps/docs/README.md),直接使用共享包的公开入口。
## 工作区
| 工作区 | 公开职责 |
| --------------------------- | -------------------------------------------------------------------------------- |
| `@ray-template/utils` | 精度、类型判断、数据与文件工具,以及接收存储实现的 JSON 读写。 |
| `@ray-template/composables` | 可独立使用的 Vue Hooks、元素与作用域工具。 |
| `@ray-template/directives` | Vue 指令与注册器。复制提示由宿主提供。 |
| `@ray-template/icons` | SVG 资源、清单、图标名称类型与查询。 |
| `@ray-template/ui` | 可复用组件及主题样式。TablePro、图表和条码支持按入口导入。 |
| `@ray-template/http` | 每个客户端独立的请求拦截和取消。 |
| `@ray-template/routing` | 路由配置校验、路由展开和菜单遍历。页面注册表由应用传入。 |
| `@ray-template/admin-shell` | 布局框架、布局设置、路由过渡和页面缓存渲染。宿主传入导航、内容、偏好和路由状态。 |
| 目录 | 职责与权威入口 |
| ----------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
| [apps/admin](../apps/admin) | Ray Admin。应用配置、路由注册、Pinia、Provider、页面、演示数据与开发 Mock。Vite 的应用根目录是这里。 |
| [apps/docs](../apps/docs/README.md) | VitePress 站点。读者指南、API、迁移和交互示例,消费共享包公开入口。 |
| [packages](../packages) | 下表列出的共享包;根入口和可导入子路径由各自的 `package.json#exports` 定义。 |
| [**test**](../__test__) | Vitest 回归,按行为分类而非逐一镜像源码目录。通过 [Harness 任务域](../harness/scopes.json) 反查覆盖。 |
| [docs](./)、[harness](../harness/README.md) | 维护者约定与跨模块说明;Harness 管理任务导航、定向验证与证据。对外文档属于 `apps/docs`。 |
| [scripts](../scripts)、[vite-helper](../vite-helper)、[unplugin](../unplugin) | 仓库级检查、Vite 插件辅助和自动导入的生成声明。根目录保留构建、类型和 CI 配置。 |
应用的 `@/components`、`@/hooks` 和 `@/utils` 继续作为模板中的导入入口。共享包声明直接依赖,公开入口通过 `exports` 控制。`pnpm packages:check` 检查跨包导入和循环依赖,独立 TypeScript 项目检查共享包能脱离应用的路径别名和全局声明。
| 共享包 | 实现归属 | 宿主边界 |
| ----------------------------------------------------------------- | ---------------------------------------------- | --------------------------------------------------------------- |
| [@ray-template/utils](../packages/utils/package.json) | 精度、类型判断、数据与文件工具、通用 JSON 存储 | 调用方提供 Storage;应用的 key、缓存后端和旧 AES 格式留在应用。 |
| [@ray-template/composables](../packages/composables/package.json) | Vue 组合式函数、DOM、元素与作用域工具 | 应用专用导航、主题和内容区 Hooks 留在应用。 |
| [@ray-template/directives](../packages/directives/package.json) | Vue 指令与注册器 | 宿主提供复制提示,并选择何时注册。 |
| [@ray-template/icons](../packages/icons/package.json) | SVG、清单、图标名类型与查询 | 构建将资源生成雪碧图,宿主提供图标解析服务。 |
| [@ray-template/ui](../packages/ui/package.json) | 通用组件、共享主题及 UI 服务接口 | 后台注入翻译、主题、存储等;应用组件入口转导出通用组件。 |
| [@ray-template/http](../packages/http/package.json) | 独立 HTTP 客户端、拦截器和取消机制 | 应用传入请求配置和拦截器,封装实际业务 API。 |
| [@ray-template/routing](../packages/routing/package.json) | 路由配置校验、路由展开和菜单遍历 | 应用持有页面注册表、配置来源、角色、会话和守卫。 |
| [@ray-template/admin-shell](../packages/admin-shell/package.json) | 布局外壳、布局设置、过渡与页面缓存渲染 | 宿主提供路由状态、偏好、导航和内容插槽。 |
## 启动链路
应用侧 `@/components`、`@/hooks`、`@/utils` 有兼容入口。跟随实际导出判断实现归属。共享包不可依赖后台别名或跨 workspace 相对导入;[包边界检查](../scripts/check-package-boundaries.mjs)校验依赖声明、公开入口和循环依赖。
`apps/admin/index.html` → `apps/admin/src/main.ts` → Pinia → 国际化 → Router → Day.js → 全局指令 → `App.tsx`。`main.ts` 同时保留无界微前端挂载和卸载入口;调整启动顺序时检查这两条路径。
## 关键运行链路
`src/App.tsx` 组合全局 Provider 与布局。布局位于 `src/layout`;全局 Naive UI 消息等实例由 `src/app-components/provider` 提供。不要在 Provider 初始化前使用 `window.$message` 等对象。
| 链路 | 调用顺序与边界 | 继续阅读 |
| -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
| 后台启动 | [index.html](../apps/admin/index.html) → [main.ts](../apps/admin/src/main.ts) → Pinia → 国际化 → Router → Day.js → 指令与自动补全设置 → 挂载 [App.tsx](../apps/admin/src/App.tsx)。普通和无界模式共用插件注册顺序。 | [布局与启动](../harness/context/layout.md) |
| 导航与缓存 | [路由初始化](../apps/admin/src/router/index.ts)加载来源 → [应用模块](../apps/admin/src/router/app-route-modules.ts)展开配置 → 注册守卫和页面 → 应用菜单 Store 与布局消费路由。应用维护缓存名单,共享壳渲染过渡与 KeepAlive。 | [路由](../harness/context/routing.md)、[布局](../harness/context/layout.md) |
| 请求与演示数据 | [API](../apps/admin/src/api) → [应用 Axios 实例](../apps/admin/src/axios/instance.ts) → [共享客户端](../packages/http/src/client.ts)。开发 Mock 走 HTTP;静态人员演示可用本地数据。生产会话和资源授权由接入方后端负责。 | [API](../harness/context/api.md) |
| 文档示例 | 文档可直接消费共享包;需要后台上下文时由 [AdminExample.vue](../apps/docs/examples/AdminExample.vue) 嵌入 [example.html](../apps/admin/example.html),使用独立启动、限定路由和内存缓存。 | [文档与示例](../harness/context/docs.md) |
| 应用配置 | [Vite](../vite.config.ts) 注入 `__APP_CFG__` 和 `__DEV__`;[应用配置](../apps/admin/src/app-config)按设计、请求、路由和缓存分组。 | [构建与工具链](../harness/context/toolchain.md) |
## 模块与扩展入口
| 需求 | 入口 | 相关约定 |
| -------------- | --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
| 新增页面与菜单 | `src/views`、`src/router/modules` | [路由文档](../apps/admin/src/router/README.md),菜单由路由生成 |
| 权限与守卫 | `src/router/utils/vue-router-register.ts`、`src/router/utils/permission.ts` | 同时检查菜单显示与实际导航;前端权限不能替代后端授权 |
| 全局状态 | `src/store/modules`、`src/store/hooks` | [Store 文档](../apps/admin/src/store/README.md),持久化配置使用 `pick`/`omit` |
| 请求与接口 | `src/api`、`src/axios` | [请求文档](../apps/admin/src/axios/README.md),请求/响应拦截器分开注册 |
| 演示接口 | `mock/demo`、`src/demo-data` | `vite-plugin-mock-dev-server`,生产环境按实际后端切换 |
| 通用组件 | `src/components` | 组件、props、types、hook、样式放在同一功能目录 |
| 模板绑定组件 | `src/app-components` | [组件说明](../apps/admin/src/app-components/README.md) |
| 公共工具 | `src/utils` | [分包、兼容入口和测试](../apps/admin/src/utils/README.md) |
| 组合式函数 | `src/hooks/web`、`template`、`components` | [19 个 Hook 的示例与生命周期](../apps/admin/src/hooks/README.md),回归测试在 `__test__/hooks` |
| 国际化 | `src/locales/lang`、`src/hooks/web/useI18n.ts` | [国际化说明](../apps/admin/src/locales/README.md),中文和英文成对维护 |
| 主题与全局样式 | `src/app-config/design-config.ts`、`src/styles` | 保留 CSS 变量和 Naive UI 明暗主题配置 |
| SVG 图标 | `src/icons`、`RIcon` | [图标说明](../packages/icons/src/A_README.md),名称与分包约定影响 symbol ID |
| 全局指令 | `src/directives/modules` | [注册约定](../apps/admin/src/directives/README.md)、[用法](../apps/admin/src/directives/README.DIR.md) |
| 构建与插件 | `vite.config.ts`、`vite.plugin.config.ts`、`vite.custom.config.ts` | 部署 base、输出目录、CDN、开发代理均在配置中管理 |
| 自动导入 | `vite.plugin.config.ts`、`unplugin` | 首次构建可更新生成声明;生成声明需要随对应依赖变化一起提交 |
| 测试 | `__test__`、`vitest.config.ts` | Happy DOM 单元测试,不能证明真实浏览器布局、下载或打印正确 |
## 数据与调用约束
- `src/app-config` 管理模板配置。运行时 `__APP_CFG__` 由 Vite 注入;`__DEV__` 表示 development 模式。
- 路径别名 `@`、`@api`、`@images`、`@mock` 在 Vite 和 TypeScript 中必须一致。
- `src/store/hooks` 是已有业务对 Store 的访问层;所有全局可变 UI 状态统一归入 Pinia:临时状态由 `runtime` 管理且不持久化,布局偏好在 `setting.layoutConfig` 中沿用原缓存 key。
- `src/utils/legacy-crypto`(原 `src/utils/c`)仍使用 CryptoJS 4.2.0 的同步 AES 格式。改用 Web Crypto 前需设计异步接口和历史密文迁移,不能直接替换并让既有数据无法解密。
- 演示页与业务组件同样属于模板能力。删除 demo 或更换第三方库前需要明确任务范围;升级工具链时应保留示例功能。
布局模式、配置与插槽见 [布局说明](../apps/admin/src/layout/README.md)。图标按包生成独立雪碧图,完整名称和严格类型由 `scripts/icons.mjs` 统一生成。
页面标题、配色与示例排版见 [视觉与排版](ui-design.md);注释位置与格式遵循 [注释规范](comment-style.md)。
公开行为变更按[应用与文档联动](docs-handoff.md)维护指南和可运行示例。页面排版见[视觉与排版](ui-design.md);代码注释见[注释规范](comment-style.md)。
## TypeScript 项目配置
[根配置](../tsconfig.json) 引用应用、Node 和测试项目。严格模式、模块解析和类型检查别名集中在 [共享配置](../tsconfig.base.json)。修改别名时同步更新 `vite.custom.config.ts`。
[根配置](../tsconfig.json)引用四个项目。严格模式、模块解析和类型检查别名集中在[共享配置](../tsconfig.base.json)。调整路径别名时同步核对 [Vite](../vite.custom.config.ts) 和 [Vitest](../vitest.config.ts)。
| 配置 | 检查范围 |
| ----------------------------- | -------------------------------------------------- |
| [应用](../tsconfig.app.json) | `src`、Vue JSX 与自动生成声明 |
| [Node](../tsconfig.node.json) | 构建与测试配置、`vite-helper`、`mock` |
| [测试](../tsconfig.test.json) | `__test__` 与引用源码,加载 Happy DOM 和 Node 类型 |
| 配置 | 检查范围 |
| ------------------------------------ | ----------------------------------------------------------------------------------------- |
| [应用](../tsconfig.app.json) | 后台 `apps/admin/src`、Vue JSX 和生成声明。 |
| [Node](../tsconfig.node.json) | 根构建与测试配置、`vite-helper`、后台 Mock。 |
| [测试](../tsconfig.test.json) | `__test__` 与引用源码,加载 Vitest 和 Node 类型。运行时环境由 Vitest 配置及测试文件决定。 |
| [共享包](../tsconfig.packages.json) | `packages/*/src`,不继承应用别名或自动导入声明。 |
| [文档站](../apps/docs/tsconfig.json) | 独立检查文档示例,由 `pnpm docs:check` 执行。 |
`pnpm typecheck` 通过 `vue-tsc --build` 检查三个项目,增量缓存存放于 `node_modules/.cache/ray-template/`。需要完整重查时使用 `pnpm exec vue-tsc --build --force`。单独检查应用或测试可用 `pnpm exec vue-tsc -p tsconfig.app.json` 或 `pnpm exec vue-tsc -p tsconfig.test.json`,Node 配置可用 `pnpm exec tsc -p tsconfig.node.json`。
`pnpm typecheck` 先检查图标同步,再通过 `vue-tsc --build` 检查根配置引用的四个项目;增量缓存位于 `node_modules/.cache/ray-template/`。单独检查可使用 `pnpm exec vue-tsc -p <配置文件>`。
## Deployment and search discovery
`pnpm build` 生成 `dist/production`,`pnpm pages:build` 将后台与文档组合到 `dist/pages`;将该目录的内容部署到 `vite.custom.config.ts` 中 `base` 对应的路径。默认路径为 `/ray-template/`,部署在域名根目录时改用 `/`。
`pnpm build` 生成后台 `dist/production`;`pnpm docs:build` 生成 `apps/docs/.vitepress/dist`。`pnpm pages:build` 将两者合并到 `dist/pages`,文档放在其 `docs/` 下。后台默认 base 为 `/ray-template/`,文档默认 base 为 `/ray-template/docs/`。自建根路径或其他子路径时,同步核对[后台 base](../vite.custom.config.ts)、[文档 base](../apps/docs/.vitepress/config.mts)和[旧站跳转目标](../scripts/assemble-pages.mjs)。
从 `dist` 分支发布 GitHub Pages 时,Vite 会将 `public/.nojekyll` 复制到产物根目录。手动上传产物时也要保留此文件,让 Pages 跳过 Jekyll,避免过滤 `_toKey-*.js` 等以下划线开头的文件。[GitHub Pages 发布说明](https://docs.github.com/en/pages/getting-started-with-github-pages/creating-a-github-pages-site)
[CI](../.github/workflows/ci.yaml)在主分支检查通过后将组合产物发布到 `dist` 分支。[后台 public 中的 .nojekyll](../apps/admin/public/.nojekyll)会随产物复制;手动部署到 Pages 时保留它,以便加载带下划线前缀的资源。
官方 GitHub Pages 部署会设置 `RAY_TEMPLATE_SITE_ORIGIN=https://xiaodaigua-ray.github.io`。如需让自己的公开部署被搜索引擎检索,在生产构建中设置该变量为实际站点源地址,例如 `https://example.com`,路径由 Vite 的 `base` 提供。在 fork 的 GitHub Actions 中可以使用同名的仓库变量。未设置时,构建输出 `noindex`,适合预览和内部部署。
公开构建用 `RAY_TEMPLATE_SITE_ORIGIN` 配置实际站点源地址,路径由 base 提供。未设置时,后台生产构建输出 `noindex`。公开后台首页生成 canonical、分享预览和 `sitemap.xml`,不把登录后的 hash 路由列为公开页面。域名级抓取规则由站点根目录的 `/robots.txt` 管理。站内旧链接由 [VitePress 映射](../apps/docs/.vitepress/legacy.mts)生成;配置站点源地址时,合并脚本另生成 `dist/legacy-docs`,供旧站迁移使用。
公开构建在 HTML 中输出页面描述、规范链接(canonical)和分享预览,并生成 `sitemap.xml`。站点地图只列出公开首页;登录后的 hash 路由仍用作交互演示。可在 [Google Search Console](https://search.google.com/search-console/about) 提交部署路径下的 sitemap。若管理整个域名,也可从域名根目录的 `/robots.txt` 指向 sitemap;子目录里的 `robots.txt` 不会被识别。
只阅读已跟踪的源码和配置来判断实现。生成产物、依赖、缓存和 `.harness-local/` 报告适合查构建与验证结果。

View File

@ -4,25 +4,25 @@
官网当前面向 v6,源码链接使用 Monorepo 路径,发布构建时用 `RAY_TEMPLATE_SOURCE_REF` 固定到发布提交。页内示例随工作区源码构建。v5 的源码与发布标签见[版本分界](../apps/docs/migration.md)。
| 领域 | 应用侧证据 | 必须交代的边界 |
| ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 组件入口与 TablePro | [公开导出](../apps/admin/src/components/index.ts)、[TablePro 契约](../apps/admin/src/components/RTablePro/README.md)、[表格示例](../apps/admin/src/views/demo/tables) | `base/`、`pro/` 深层路径失效;`RTable`、`useTable` 已移除。`useTablePro` 保留注册写法,提供 `isReady` 和当前页取数。远端 `total` 是筛选后的总数;取消依赖请求函数传递 signal;导出和打印默认仅当前页可见数据列。 |
| 路由与权限 | [路由说明](../apps/admin/src/router/README.md)、[路由类型](../apps/admin/src/router/types.ts)、[权限守卫](../apps/admin/src/router/utils/permission.ts) | 菜单显隐不等于访问授权;会话和接口权限由后端校验。缓存需要路由 name 对应组件 name,验证菜单进入、直达和刷新。 |
| 布局与 Pinia | [布局插槽和偏好](../apps/admin/src/layout/README.md)、[Store 约定](../apps/admin/src/store/README.md) | 全局 UI 单例已迁入 `runtime`,不持久化。保留历史设置和锁屏格式;自定义内容插槽时,由接入方负责保留请求取消及路由缓存。 |
| 请求与 Mock | [Axios 实现](../apps/admin/src/axios/instance.ts)、[取消器](../apps/admin/src/axios/utils/RequestCanceler.ts)、[人员查询](../apps/admin/src/api/demo/mock/person.ts) | 实例成功返回 body,失败拒绝;调用方传 signal 时关闭模板的默认 signal 注入。Mock HTTP 仅用于开发,静态演示有独立本地数据分支。 |
| Hooks、工具与图标 | [Hooks 行为](../apps/admin/src/hooks/README.md)、[工具兼容入口](../apps/admin/src/utils/README.md)、[图标生成](../packages/icons/src/A_README.md) | `@/hooks` 与 `@/utils` 公共入口保留;旧裸图标仅在缓存读取边界按唯一名称迁移。截图和打印测试不代表原生浏览器能力验收。 |
| 工具链与部署 | [工具链记录](toolchain-upgrade.md)、[架构地图](architecture.md)、[Vite 配置](../vite.custom.config.ts) | Node/pnpm 以清单为准。应用 base 为 `/ray-template/`,内置文档为 `/ray-template/docs/`。已发布旧站仍使用 `/ray-template-doc/`。 |
| 领域 | 应用侧证据 | 必须交代的边界 |
| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 组件入口与 TablePro | [公开导出](../apps/admin/src/components/index.ts)、[TablePro 契约](../packages/ui/src/RTablePro/README.md)、[表格示例](../apps/admin/src/views/demo/tables) | `base/`、`pro/` 深层路径失效;`RTable`、`useTable` 已移除。`useTablePro` 保留注册写法,提供 `isReady` 和当前页取数。远端 `total` 是筛选后的总数;取消依赖请求函数传递 signal;导出和打印默认仅当前页可见数据列。 |
| 路由与权限 | [路由说明](../apps/admin/src/router/README.md)、[路由类型](../apps/admin/src/router/types.ts)、[权限守卫](../apps/admin/src/router/utils/permission.ts) | 菜单显隐不等于访问授权;会话和接口权限由后端校验。缓存需要路由 name 对应组件 name,验证菜单进入、直达和刷新。 |
| 布局与 Pinia | [布局插槽和偏好](../apps/admin/src/layout/README.md)、[Store 约定](../apps/admin/src/store/README.md) | 全局 UI 单例已迁入 `runtime`,不持久化。保留历史设置和锁屏格式;自定义内容插槽时,由接入方负责保留请求取消及路由缓存。 |
| 请求与 Mock | [Axios 实现](../apps/admin/src/axios/instance.ts)、[取消器](../packages/http/src/RequestCanceler.ts)、[人员查询](../apps/admin/src/api/demo/mock/person.ts) | 实例成功返回 body,失败拒绝;调用方传 signal 时关闭模板的默认 signal 注入。Mock HTTP 仅用于开发,静态演示有独立本地数据分支。 |
| Hooks、工具与图标 | [Hooks 行为](../apps/admin/src/hooks/README.md)、[工具兼容入口](../apps/admin/src/utils/README.md)、[图标生成](../packages/icons/src/A_README.md) | `@/hooks` 与 `@/utils` 公共入口保留;旧裸图标仅在缓存读取边界按唯一名称迁移。截图和打印测试不代表原生浏览器能力验收。 |
| 工具链与部署 | [工具链记录](toolchain-upgrade.md)、[架构地图](architecture.md)、[Vite 配置](../vite.custom.config.ts) | Node/pnpm 以清单为准。应用 base 为 `/ray-template/`,内置文档为 `/ray-template/docs/`。已发布旧站仍使用 `/ray-template-doc/`。 |
## 联动流程
1. 应用改动影响公开导入、配置、缓存或行为时,在同一变更更新模块说明及 `apps/docs` 中受影响的文档和示例。破坏性改动进入迁移清单。
2. 交互和展示的代码使用同一个 `apps/docs/examples` 文件。优先用 workspace 包,复用应用组件时按模块导入,浏览器专用示例在客户端加载。
2. 展示正在运行的示例源码。轻量示例位于 `apps/docs/examples`,使用共享包的公开入口;需要后台上下文的示例嵌入 `example.html`,源码引用指向实际的后台演示页。定位入口见[文档主题索引](../harness/context/docs.md)。
3. 运行 `pnpm harness verify`,再用 `pnpm docs:preview` 在 `/ray-template/docs/` 检查导航、搜索、旧路径、明暗主题、窄屏和交互。线上迁址另行验证新旧地址。
## 待同步到读者指南的内容
应用侧已准备好 [路由接入文档](../apps/admin/src/router/README.md)、[Schema](../apps/admin/src/router/config/schema.ts)、[Segment 说明](../apps/admin/src/components/RSegment/README.md) 和 [页面设计说明](ui-design.md)。在 `apps/docs/guide/routing.md` 补充来源切换、接口示例和版本校验,在组件参考中补充 `fitContent` 的选中态与过渡规则。截图使用更新后的登录页与管理页,并核对部署子路径。
应用侧已准备好 [路由接入文档](../apps/admin/src/router/README.md)、[Schema](../packages/routing/src/schema.ts)、[Segment 说明](../packages/ui/src/RSegment/README.md) 和 [页面设计说明](ui-design.md)。在 `apps/docs/guide/routing.md` 补充来源切换、接口示例和版本校验,在组件参考中补充 `fitContent` 的选中态与过渡规则。截图使用更新后的登录页与管理页,并核对部署子路径。
`guide/layout.md` 补充右侧导航、通栏分组、减少动态效果和浮动退出按钮;`guide/routing.md` 增加可视化与 JSON 两个入口,明确可视化应用仅保存在当前浏览器;`reference/hooks/layout.md` 说明加载提示以可见内容区为基准。
`guide/layout.md` 补充减少动态效果和浮动退出按钮;`guide/routing.md` 增加可视化与 JSON 两个入口,明确可视化应用仅保存在当前浏览器;`reference/hooks/layout.md` 说明加载提示以可见内容区为基准。
`guide/layout.md` 同步设置抽屉的偏好导入导出:JSON 只包含抽屉内偏好,校验通过后即时保存,独立于路由管理的 JSON 配置。

View File

@ -1,17 +1,17 @@
# Ray Template AI Harness
从 [AGENTS.md](../AGENTS.md) 进入。LLM 可先读取 [入口索引](../llms.txt) 定位相关文件。任务上下文来自 [scopes.json](scopes.json),跨模块关系见 [架构地图](../docs/architecture.md)。CLI 使用项目锁定的 Node.js 和 pnpm,可在本机和 CI 运行。
从 [AGENTS.md](../AGENTS.md) 进入。需要查实现时,从 [任务索引](../llms.txt) 打开相关主题;跨模块关系见 [架构地图](../docs/architecture.md)。只阅读索引无需安装依赖。
## 开始任务
1. 根据 `.nvmrc` 和 `package.json#packageManager` 选择运行时,首次执行 `pnpm install --frozen-lockfile` 和 `pnpm env:check`。
2. 查看 `git status`。用 `pnpm harness context` 查找任务域,再用 `pnpm harness context <scope>` 找到入口和回归测试。跨域变更分别查看受影响的任务域。
3. 明确可观察的验收条件。涉及多步迁移或跨会话接续时,记录范围、分阶段验收、关键决策与剩余项。可参考 [建设计划](plan.md)。
4. 追踪调用方和数据流后实施。先用定向测试缩短反馈周期,最后运行全量验收。
1. 查看 `git status`。用静态入口或 `pnpm harness context` 选择任务域;`pnpm harness context <scope>` 显示对应索引及验证命令。跨域变更分别查看受影响的任务域。
2. 需要运行验证时,根据 `.nvmrc` 和 `package.json#packageManager` 选择运行时,首次执行 `pnpm install --frozen-lockfile` 和 `pnpm env:check`。
3. 明确可观察的验收条件,追踪调用方和数据流后实施。多步迁移或跨会话接续时,记录范围、分阶段验收、关键决策与剩余项。可参考 [建设计划](plan.md)。
4. 先运行定向验证,最后运行全量验收。
```sh
pnpm harness context routing
pnpm harness verify routing
pnpm harness context table-pro
pnpm harness verify table-pro
pnpm harness verify
```
@ -28,8 +28,8 @@ pnpm harness verify
| 命令 | 验证范围 |
| ----------------------------- | --------------------------------------------------------------- |
| `pnpm harness check` | 上下文路径存在,回归路径至少指向一个测试文件 |
| `pnpm harness verify <scope>` | 环境检查和该任务域的 Vitest 回归 |
| `pnpm harness check` | 主题已登记并可从入口到达;相对链接、回归路径和检查命令有效 |
| `pnpm harness verify <scope>` | 环境检查和该任务域登记的 Vitest 回归或项目检查 |
| `pnpm harness verify` | `pnpm check` 的全部检查 |
| `pnpm check` | 环境、Harness、图标同步、类型、规范、格式、单测、应用与文档构建 |
@ -47,10 +47,12 @@ GitHub Actions 在 Linux、Windows 和 macOS 运行同一份 `pnpm check`。单
| 路由、权限或缓存 | 从菜单进入、直接访问、刷新,核对守卫和恢复行为 |
| 图标、部署 base 或构建 | 检查生产预览、资源 URL 和控制台 |
在交付或 PR 中记录复现步骤、实际结果及未验证项。临时报告、日志和截图放入 `.harness-local/`。浏览器结果单独记录,单元测试报告仅覆盖其中列出的命令。
在交付或 PR 中记录复现步骤、实际结果及未验证项。临时报告、日志和截图放入 `.harness-local/`。浏览器结果单独记录,CLI 报告仅覆盖其中列出的命令。
## 维护
影响外部读者的功能或兼容性改动,按 [文档联动说明](../docs/docs-handoff.md) 在同一变更中更新 `apps/docs`。单独用 `pnpm docs:check` 检查示例类型、文档链接和构建;用 `pnpm docs:preview` 验收生产子路径下的交互。
任务域的路径或测试位置变化时,更新 `scopes.json` 并运行 `pnpm harness check`。测试目录以 `/` 结尾,单个文件使用仓库相对路径。优先完善现有测试和上下文入口,把可稳定复现的失败纳入共同检查。
- 移动实现、适配层或示例时,更新 `harness/context/` 中受影响的索引。每个主题说明何时使用、先读哪些文件、谁拥有实现及如何验证。API 细节留在源码、模块 README 或读者文档。
- 新增任务域时,在 [scopes.json](scopes.json) 注册简介和 `tests` 或 `checks`,添加同名 `harness/context/<scope>.md`,并从 [llms.txt](../llms.txt) 链入。测试目录以 `/` 结尾;项目检查复用 CLI 允许的根脚本。原有任务域可保留为较宽的验证入口。
- 索引用普通行内相对链接指向仓库文件或目录。`pnpm harness check` 检查主题及其入口文档的文件目标,不请求外部链接或验证标题锚点。调整内容后再从一个真实任务出发走查实现和测试归属。

14
harness/context/api.md Normal file
View File

@ -0,0 +1,14 @@
# API、请求与 Mock
用于新增接口、调试 Axios 响应和拦截器、定位重复请求或切页取消、修改演示数据。先看[请求契约](../../apps/admin/src/axios/README.md)。
| 要查什么 | 先读 | 接着追踪 |
| ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 业务接口、分页数据、请求配置 | [应用 API](../../apps/admin/src/api)、[应用请求实例](../../apps/admin/src/axios/instance.ts)、[请求配置](../../apps/admin/src/app-config/request-config.ts) | [人员接口调用](../../apps/admin/src/api/demo/mock/person.ts)、[接入指南](../../apps/docs/guide/requests.md) |
| Axios 拦截器、异常和客户端隔离 | [共享客户端](../../packages/http/src/client.ts)、[共享类型](../../packages/http/src/types.ts) | [应用请求拦截器](../../apps/admin/src/axios/axios-interceptor/request/provider.ts)、[响应拦截器](../../apps/admin/src/axios/axios-interceptor/response/provider.ts) |
| 重复请求、AbortSignal、切页取消 | [共享 RequestCanceler](../../packages/http/src/RequestCanceler.ts)、[应用取消 Provider](../../apps/admin/src/app-components/provider/AppRequestCancelerProvider) | [布局内容插槽](../../apps/admin/src/layout/default/ContentWrapper/index.tsx)、[TablePro 远端请求](table-pro.md) |
| 开发 Mock 与静态演示不同 | [开发 Mock](../../apps/admin/mock/demo/person.mock.ts)、[共用演示数据](../../apps/admin/src/demo-data/people.ts) | [应用调用的环境分支](../../apps/admin/src/api/demo/mock/person.ts)、[Vite Mock 插件](../../vite.plugin.config.ts) |
应用 `axios/utils` 中有兼容转导出。请求的默认 signal 只在调用方未传 signal、且未禁用默认取消时注入。演示数据不代表生产接口或授权;前端 `VITE_*` 配置不可用于密钥。
定向验证:`pnpm harness verify api`,包括[应用请求](../../__test__/axios/request.spec.ts)、[客户端隔离](../../__test__/workspace/http-client.spec.ts)和 [Mock](../../__test__/mock/database.spec.ts)。生产后端接入、浏览器下载和真实链路需另验。

14
harness/context/docs.md Normal file
View File

@ -0,0 +1,14 @@
# 文档站与可运行示例
用于修改指南、API 参考、导航、主题、旧链接或交互示例。站点开发和预览命令见[文档站 README](../../apps/docs/README.md)。
| 要查什么 | 先读 | 接着追踪 |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 对外用法、API 或兼容迁移 | [开发指南](../../apps/docs/guide)、[API 参考](../../apps/docs/reference/index.md)、[迁移说明](../../apps/docs/migration.md) | [应用与文档联动](../../docs/docs-handoff.md)、[共享包边界](../../docs/architecture.md) |
| 站点主题、导航、源码链接 | [VitePress 配置](../../apps/docs/.vitepress/config.mts)、[侧栏](../../apps/docs/.vitepress/sidebar.mts)、[主题](../../apps/docs/.vitepress/theme) | [版本与仓库链接](../../apps/docs/.vitepress/source.mts) |
| 旧文档路径与重定向 | [站内旧路径映射](../../apps/docs/.vitepress/legacy.mts) | [合并站点和旧站跳转产物](../../scripts/assemble-pages.mjs)、[构建与部署](toolchain.md) |
| 页内交互与源码引用 | [轻量 Vue 示例](../../apps/docs/examples)、[后台 iframe 包装](../../apps/docs/examples/AdminExample.vue) | [example.html](../../apps/admin/example.html)、[独立演示启动与路由](../../apps/admin/src/documentation-example.tsx)、[后台示例页面](../../apps/admin/src/views/demo) |
轻量示例通过共享包公开入口运行。需要后台上下文的示例走 `example.html` 的限定路由和内存缓存;使用和展示同一份运行源码。涉及公开契约时回到所属主题核实,维护指南、示例及迁移说明。
定向验证:`pnpm harness verify docs` 执行 `docs:check`,包含类型、站内链接和生产构建。嵌入后台、部署子路径和旧站跳转使用 `pnpm pages:build` 生成组合产物,再按 [README](../../apps/docs/README.md) 预览。

View File

@ -0,0 +1,13 @@
# Harness、索引和验证证据
用于新增或改动任务索引、回归范围、命令和本地报告。执行方式见 [Harness README](../README.md)。
| 要查什么 | 先读 | 接着追踪 |
| -------------------------- | ---------------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
| 助手从哪里进入、怎么选主题 | [根约定](../../AGENTS.md)、[静态任务入口](../../llms.txt) | [主题索引](./)、[跨模块地图](../../docs/architecture.md) |
| CLI、上下文与定向目标 | [任务注册表](../scopes.json)、[CLI 实现](../run.mjs) | [CLI 回归](../../__test__/harness/cli.spec.ts)、[根检查命令](../../package.json) |
| 全量验证、报告和历史决策 | [验证与证据](../README.md#验收与证据)、[CI](../../.github/workflows/ci.yaml) | [建设计划与设计自审](../plan.md)、[工具链记录](../../docs/toolchain-upgrade.md) |
移动源码时更新受影响的索引链接。新增主题时同步任务注册表、同名 Markdown 和静态入口;长篇契约保留在所属模块。报告由现有 CLI 写入被忽略的 `.harness-local/runs/`;截图和其他临时证据不放进索引。
定向验证:先运行 `pnpm harness check` 检查索引,变更 CLI 后运行 `pnpm harness verify harness`。涉及全量流程时,用真实 `pnpm harness verify` 验证报告。

13
harness/context/icons.md Normal file
View File

@ -0,0 +1,13 @@
# SVG 图标与生成
用于新增或移动图标、排查图标类型、symbol ID、雪碧图 URL 或热更新。
| 要查什么 | 先读 | 接着追踪 |
| ------------------------ | ---------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
| 资源、分包及命名 | [图标维护说明](../../packages/icons/src/A_README.md)、[SVG 资源目录](../../packages/icons/src) | [包公开入口](../../packages/icons/package.json)、[应用适配](../../apps/admin/src/icons) |
| 清单、类型、生成及 HMR | [生成器](../../packages/icons/scripts/icons.mjs)、[根脚本入口](../../scripts/icons.mjs) | [Vite 图标适配](../../vite-helper/icons.ts)、[插件配置](../../vite.plugin.config.ts) |
| 渲染、应用注入和读者用法 | [RIcon](../../packages/ui/src/RIcon/index.ts)、[应用图标服务](../../apps/admin/src/App.tsx) | [图标示例](../../apps/admin/src/views/demo/svg-icons)、[读者参考](../../apps/docs/reference/icons.md) |
SVG 与生成器是来源;[manifest.ts](../../packages/icons/src/manifest.ts) 由 `pnpm icons:generate` 更新。移动分包可能改变完整名称;检查菜单、路由配置、缓存中的引用及生产资源 URL。
定向验证:`pnpm icons:check` 与 `pnpm harness verify icons`,包括[生成](../../__test__/icons/generation.spec.ts)和[热更新](../../__test__/icons/hmr.spec.ts)回归。资源路径变更按[浏览器验收](../README.md#浏览器验收)核对生产预览。

14
harness/context/layout.md Normal file
View File

@ -0,0 +1,14 @@
# 启动、布局与应用状态
用于定位 Provider、导航布局、页面缓存、设置抽屉、Pinia 或持久化问题。
| 要查什么 | 先读 | 接着追踪 |
| --------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| 首屏、无界挂载、全局服务 | [应用启动](../../apps/admin/src/main.ts)、[App Provider 组装](../../apps/admin/src/App.tsx) | [应用 Provider](../../apps/admin/src/app-components/provider)、[共享 UI 服务接口](../../packages/ui/src/services.ts)、[模板启动后校验](../../apps/admin/src/__ray-template/index.ts) |
| 侧栏、顶部导航、标签与搜索 | [应用布局适配](../../apps/admin/src/layout/index.tsx)、[应用导航 Hook](../../apps/admin/src/hooks/template/useAppNavigation.ts) | [共享 AdminShell](../../packages/admin-shell/src/AdminShell.tsx)、[宿主布局部件](../../apps/admin/src/layout/components)、[插槽契约](../../apps/admin/src/layout/README.md) |
| 内容区、加载、切页及 KeepAlive | [宿主内容插槽](../../apps/admin/src/layout/default/ContentWrapper/index.tsx)、[宿主过渡适配](../../apps/admin/src/components/RTransitionComponent) | [共享过渡与缓存渲染](../../packages/admin-shell/src/RouteTransition.vue)、[缓存名单](../../apps/admin/src/store/modules/keep-alive/index.ts)、[页面请求取消](api.md) |
| 布局偏好、JSON 导入导出、临时状态 | [设置 Store](../../apps/admin/src/store/modules/setting/index.ts)、[偏好文件校验](../../apps/admin/src/store/modules/setting/preference-file.ts)、[runtime Store](../../apps/admin/src/store/modules/runtime/index.ts) | [宿主设置抽屉](../../apps/admin/src/layout/components/SiderBar/components/SettingDrawer/index.tsx)、[共享布局设置](../../packages/admin-shell/src/LayoutSettings.tsx)、[读者指南](../../apps/docs/guide/layout.md) |
布局包负责壳和渲染,应用提供导航、设置、内容及运行时状态。应用 Store 通过 [hooks](../../apps/admin/src/store/hooks) 访问;持久化范围和历史格式见 [Store 约定](../../apps/admin/src/store/README.md)。偏好文件只处理布局设置,路由来源和 JSON 归[路由](routing.md)。
定向验证:`pnpm harness verify layout`,包括[布局回归](../../__test__/layout)、[Provider](../../__test__/app/global-provider.spec.ts)和相关 Hook。浏览器复核受影响的布局模式、窄屏、缓存恢复及偏好读回。

View File

@ -0,0 +1,14 @@
# 路由、菜单与权限
用于新增页面或菜单、调试直达和刷新、变更动态路由来源或配置。先看[路由接入与配置契约](../../apps/admin/src/router/README.md)中与任务相关的段落。
| 要查什么 | 先读 | 接着追踪 |
| ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 静态页面注册、菜单排序 | [应用路由模块](../../apps/admin/src/router/modules)、[路由模块装配](../../apps/admin/src/router/app-route-modules.ts) | [视图](../../apps/admin/src/views)、[菜单 Store](../../apps/admin/src/store/modules/menu/index.ts)、[共享展开逻辑](../../packages/routing/src/expand-routes.ts) |
| 动态 JSON 字段、校验错误、允许的页面 | [共享 Schema](../../packages/routing/src/schema.ts)、[JSON Schema 导出](../../packages/routing/src/json-schema.ts)、[应用页面 ID 注册表](../../apps/admin/src/router/config/views.ts) | [应用绑定](../../apps/admin/src/router/config/contract.ts)、[管理页](../../apps/admin/src/views/route-management)、[读者指南](../../apps/docs/guide/routing.md) |
| 静态、本地、远端来源及降级 | [来源加载与保存](../../apps/admin/src/router/config/source.ts) | [路由初始化](../../apps/admin/src/router/index.ts)、[实际注册的路由](../../apps/admin/src/router/routes.ts) |
| 菜单可见性、直达、登录后落地 | [导航守卫](../../apps/admin/src/router/utils/permission.ts)、[路由与白名单配置](../../apps/admin/src/app-config/router-config.ts) | [菜单显隐](../../apps/admin/src/router/utils/valid-menu-item-show.ts)、[会话 Store](../../apps/admin/src/store/modules/signing/index.ts)、[共享导航遍历](../../packages/routing/src/navigation.ts) |
[应用 Schema](../../apps/admin/src/router/config/schema.ts) 是转导出;共享包负责通用校验,页面加载器、角色和登录状态由应用接入。保持路由名唯一;启用缓存的页面检查组件名与路由名。前端菜单和守卫都不能替代服务端授权。
定向验证:`pnpm harness verify routing`,优先看[动态配置](../../__test__/router/config.spec.ts)和[权限回归](../../__test__/router/permission.spec.ts)。行为改动补测菜单进入、直接访问、刷新及切换来源;涉及缓存或设置再看[布局与状态](layout.md)。

View File

@ -0,0 +1,14 @@
# TablePro
用于 `RTablePro`、`useTablePro`、高级搜索、远端分页、列设置、导出或打印。共享包拥有实现,后台和文档站分别消费同一公开 API。
| 要查什么 | 先读 | 接着追踪 |
| ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 导出、Props、实例方法 | [共享入口](../../packages/ui/src/RTablePro/index.ts)、[Props](../../packages/ui/src/RTablePro/src/props.ts)、[类型](../../packages/ui/src/RTablePro/src/types.ts) | [注册 Hook](../../packages/ui/src/RTablePro/src/useTablePro.ts)、[包导出](../../packages/ui/package.json)、[应用组件入口](../../apps/admin/src/components/index.ts) |
| 搜索草稿、校验、条件生效、请求竞争 | [搜索状态](../../packages/ui/src/RTablePro/src/useTableSearch.ts)、[搜索值处理](../../packages/ui/src/RTablePro/src/search.ts)、[分页与请求](../../packages/ui/src/RTablePro/src/TablePro.tsx) | [搜索控件](../../packages/ui/src/RTablePro/src/components/Search.tsx)、[后台搜索示例](../../apps/admin/src/views/demo/tables/search.tsx)、[搜索回归](../../__test__/components/table-pro-search.spec.ts) |
| 列可见性、布局、当前页导出与打印 | [表格面板](../../packages/ui/src/RTablePro/src/TablePanel.tsx)、[列设置](../../packages/ui/src/RTablePro/src/columns.ts) | [CSV](../../packages/ui/src/RTablePro/src/csv.ts)、[打印](../../packages/ui/src/RTablePro/src/printing.ts)、[列回归](../../__test__/components/table-pro-columns.spec.ts) |
| 示例、文案和公开约定 | [组件契约](../../packages/ui/src/RTablePro/README.md)、[文档参考](../../apps/docs/reference/table-pro.md) | [后台示例和夹具](../../apps/admin/src/views/demo/tables)、[文档轻量示例](../../apps/docs/examples/TableProDemo.vue)、[组件语言资源](../../packages/ui/src/RTablePro/src/locale.ts) |
远端 `total` 是筛选后的总数,取消需要请求函数透传 `signal`。修改实例能力时同时检查组件暴露、Hook 和公开导出;修改示例参数时确认是文档轻量示例还是[嵌入后台示例](docs.md)。
定向验证:`pnpm harness verify table-pro` 覆盖表格、搜索、列和导出。真实滚动、下载、打印和窄屏布局使用对应示例在浏览器验收。

View File

@ -0,0 +1,14 @@
# 工作区、类型检查、构建与 CI
用于修改依赖、公开导出、别名、自动导入、生产构建或部署配置。运行时以 [.nvmrc](../../.nvmrc) 和[根清单](../../package.json)为准。
| 要查什么 | 先读 | 接着追踪 |
| ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 工作区和依赖边界 | [pnpm workspace](../../pnpm-workspace.yaml)、[锁文件](../../pnpm-lock.yaml)、[工作区清单与职责](../../docs/architecture.md#工作区) | [包边界检查](../../scripts/check-package-boundaries.mjs)、[环境检查](../../scripts/doctor.mjs) |
| 路径别名、类型检查和自动导入 | [TypeScript 项目图](../../docs/architecture.md#typescript-项目配置)、[共享配置](../../tsconfig.base.json)、[Vite 别名](../../vite.custom.config.ts) | [插件配置](../../vite.plugin.config.ts)、[生成声明](../../unplugin)、[Vitest 配置](../../vitest.config.ts) |
| 构建入口、部署 base 与 SEO | [应用 Vite 配置](../../vite.config.ts)、[部署配置](../../vite.custom.config.ts)、[站点元数据](../../vite-helper/site-seo.ts) | [文档站配置](../../apps/docs/.vitepress/config.mts)、[产物合并](../../scripts/assemble-pages.mjs)、[部署约定](../../docs/architecture.md#deployment-and-search-discovery) |
| CI、镜像和发布产物 | [GitHub Actions](../../.github/workflows/ci.yaml)、[Dockerfile](../../Dockerfile)、[Compose](../../docker-compose.yml) | [全量验证步骤](../../harness/README.md)、[工具链演进记录](../../docs/toolchain-upgrade.md) |
公开导出以对应 workspace 的 `package.json#exports` 为准;改别名时比较 Vite、TypeScript 和 Vitest 的解析。生成声明通过配置更新。发布组合站点时同时核对后台和文档的 base。
定向验证:`pnpm harness verify toolchain` 执行包边界和类型检查。改动构建或部署时还需全量检查、生成相关产物并预览;定向通过不能证明 CI、Docker 或线上发布成功。

15
harness/context/ui.md Normal file
View File

@ -0,0 +1,15 @@
# 页面、公共组件、Hooks 与指令
用于新增或修改页面、公共 UI、主题、双语文案、Vue Hooks 或指令。TablePro 和布局各有更窄的入口:[表格](table-pro.md)、[布局](layout.md)。
| 要查什么 | 先读 | 接着追踪 |
| ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 页面、登录、示例 | [页面目录](../../apps/admin/src/views)、[登录页](../../apps/admin/src/views/login/index.tsx)、[演示页骨架](../../apps/admin/src/views/demo/components/DemoPage.tsx) | [路由注册](routing.md)、[视觉约定](../../docs/ui-design.md) |
| Modal、Segment、图表、条码等通用组件 | [应用组件入口](../../apps/admin/src/components/index.ts)、[共享 UI 公开导出](../../packages/ui/package.json) | [组件实现](../../packages/ui/src)、[API 参考](../../apps/docs/reference/components.md) |
| 依赖模板状态的组件与 Provider | [应用组件说明](../../apps/admin/src/app-components/README.md) | [App 组装](../../apps/admin/src/App.tsx)、[Naive UI 自动补全默认值](../../apps/admin/src/app-components/provider/AppAutocompleteDefaults) |
| 主题、样式、应用文案 | [应用设计配置](../../apps/admin/src/app-config/design-config.ts)、[样式入口](../../apps/admin/src/styles/entry.ts)、[语言资源](../../apps/admin/src/locales/README.md) | [应用主题 Hook](../../apps/admin/src/hooks/template/useTheme.ts)、[共享主题](../../packages/ui/src/theme.css)、[文档站样式](docs.md) |
| Hooks、全局指令 | [应用 Hooks 入口](../../apps/admin/src/hooks/index.ts)、[共享组合式函数入口](../../packages/composables/src/index.ts)、[应用指令注册](../../apps/admin/src/directives/index.ts) | [Hooks 说明](../../apps/admin/src/hooks/README.md)、[共享指令实现](../../packages/directives/src/modules)、[指令用法](../../apps/admin/src/directives/README.DIR.md) |
应用的 `@/components` 和部分 Hook/指令路径保留兼容导出;修通用行为前沿导出进入所属共享包。宿主特有服务通过注入接入,避免共享包引用应用别名。界面新增文案应补齐中英文。
定向验证:`pnpm harness verify ui`,先按实际行为选择[组件](../../__test__/components)、[Hooks](../../__test__/hooks)或[跨包消费](../../__test__/workspace/consumer.spec.tsx)用例。涉及页面效果,按 [Harness 浏览器验收](../README.md#浏览器验收) 检查。

14
harness/context/utils.md Normal file
View File

@ -0,0 +1,14 @@
# 工具、缓存与数据兼容
用于修改基础工具、精度、文件、缓存读写或历史密文。先通过[应用入口说明](../../apps/admin/src/utils/README.md)确认实现归属。
| 要查什么 | 先读 | 接着追踪 |
| ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| 精度、对象、文件与基础工具 | [共享包导出](../../packages/utils/package.json)、[共享工具](../../packages/utils/src) | [应用兼容入口](../../apps/admin/src/utils/index.ts)、[工具 API](../../apps/docs/reference/utils.md) |
| 应用缓存 key、Storage 后端、文档示例隔离 | [应用缓存](../../apps/admin/src/utils/cache.ts)、[缓存后端](../../apps/admin/src/utils/cache-backend.ts)、[key 前缀](../../apps/admin/src/utils/app/prefix-cache-key.ts) | [应用缓存键配置](../../apps/admin/src/app-config/app-config.ts)、[共享 JSON 存储](../../packages/utils/src/storage.ts)、[布局和状态](layout.md) |
| 历史同步 AES 密文 | [兼容实现](../../apps/admin/src/utils/legacy-crypto)、[旧导入入口](../../apps/admin/src/utils/c/index.ts) | [历史密文回归](../../__test__/utils-contracts/legacy-crypto.spec.ts) |
| Vue 生命周期、DOM 和元素工具 | [共享组合式函数与工具](../../packages/composables/src) | [应用 Hooks 与 UI](ui.md)、[Vue 工具回归](../../__test__/vue) |
保持调用方依赖的 key、存储类型和序列化格式。共享存储由调用方传入 Storage 实现;应用持久化和文档 iframe 的内存缓存需分别检查。同步 AES 格式或 API 若需替换,先设计历史数据迁移。
定向验证:`pnpm harness verify utils`,从[缓存测试](../../__test__/cache)、[精度测试](../../__test__/precision)或[工具契约](../../__test__/utils-contracts)选择与任务相关的回归。

View File

@ -11,3 +11,31 @@
日常维护时,以实际反复出现的失败为依据扩充 Harness。优先将已有覆盖缺口补进 Vitest,待浏览器流程有稳定夹具和可重复结果时,再评估纳入自动化门禁。迁移的实测结果见 [工具链记录](../docs/toolchain-upgrade.md)。
设计参考 [OpenAI Docs 的仓库工作流实践](https://developers.openai.com/cookbook/examples/codex/iterating-development-workflows-with-codex) 与 [上下文分层建议](https://developers.openai.com/blog/rethinking-skills-and-prompts-for-gpt-6-astra)。
## Monorepo 索引补全
审查基线为 `58fc0b63`。现有命令、回归和报告已形成反馈闭环,主要缺口在查找和判断代码归属:
| 发现 | 影响 |
| -------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
| 架构地图混用旧 `src/` 路径与工作区路径,仍将路由、图标和组件实现归到应用目录 | 目录存在不等于拥有实现。例如应用侧 Schema、取消器和部分组件只是兼容入口 |
| `ui` 同时覆盖布局、公共组件、文案、Hooks 和演示;没有 TablePro、文档站及构建的独立入口 | 查表格筛选或 VitePress 重定向时,需要自行从大目录找实现、示例和验证 |
| `llms.txt`、架构地图与 `scopes.json` 分别列源码路径;检查只覆盖 JSON 里的路径 | 文件移动后,入口和说明可以互相矛盾而全量检查仍通过 |
### 设计
1. `AGENTS.md` 只保留仓库级协作约定和入口;`llms.txt` 提供无需运行时的任务路由,按需链接 [架构地图](../docs/architecture.md) 和具体主题。
2. `harness/context/<scope>.md` 按实际问题列首读源码、应用/共享包/示例边界及相关测试。行为契约留在源码、就近 README 和公开文档中。架构地图说明工作区、关键运行链和部署。
3. `scopes.json` 保存主题简介与可执行验证配置;按 ID 定位同名索引,`context <scope>` 直接显示。保留六个已有 ID 和各自测试,新增 TablePro、布局、文档站和工具链。文档与工具链使用已有检查脚本。
4. 将索引入口、相对链接和测试目标接入现有 `harness check`,继续由 `pnpm check` 和 CI 执行。范围是导航文档,不追踪外链或证明描述正确;语义通过走查和回归验证。
### 实施前自审
| 检查 | 修订后的决定 |
| -------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
| 是否要在 JSON 和 Markdown 重复维护实现路径? | 用同名索引作为 CLI 输出,正文只维护一份;不生成第二份源码树 |
| 是否让每个任务先跑命令、阅读全图? | 保留静态入口;按需求打开一张主题索引。架构图用于跨模块任务,不作为前置必读 |
| 是否给所有任务域强行配 Vitest? | 文档用 `docs:check`;工具链用包边界与类型检查。明确哪些问题仍需生产预览或全量检查 |
| 是否能区分同名入口与真正实现? | 用 TablePro 搜索、动态路由、请求取消、偏好导入、旧文档重定向和部署产物逐条走查,索引写明主实现和宿主适配 |
验收:静态入口可到达所有主题;原命令和报告契约兼容;断链、缺失主题和失效回归路径会使检查失败;代表任务能从索引到达实现和验证;最后执行 `pnpm harness verify`。

View File

@ -8,7 +8,7 @@ import {
statSync,
writeFileSync,
} from 'node:fs'
import { join, relative } from 'node:path'
import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path'
import { fileURLToPath } from 'node:url'
const root = fileURLToPath(new URL('../', import.meta.url))
@ -17,23 +17,59 @@ const scopes = JSON.parse(
)
const [action = '--help', scope, ...extra] = process.argv.slice(2)
const testPattern = /^__test__\/(?:[\w-]+\/)+(?:[\w.-]+\.spec\.tsx?)?$/
const scopePattern = /^[a-z][a-z\d]*(?:-[a-z\d]+)*$/
const allowedChecks = new Set(['docs:check', 'packages:check', 'typecheck'])
const indexFiles = [
'AGENTS.md',
'llms.txt',
'docs/architecture.md',
'docs/docs-handoff.md',
'harness/README.md',
'harness/plan.md',
]
function contextPath(name) {
return `harness/context/${name}.md`
}
function checkScopes() {
const problems = []
const { scripts } = JSON.parse(
readFileSync(join(root, 'package.json'), 'utf8'),
)
for (const [name, { paths, tests }] of Object.entries(scopes)) {
for (const path of paths) {
if (!existsSync(join(root, path))) {
problems.push(`${name} 的上下文路径不存在:${path}`)
for (const [name, { description, tests = [], checks = [] }] of Object.entries(
scopes,
)) {
if (!scopePattern.test(name) || name === 'all') {
problems.push(`无效任务域:${name}`)
}
if (typeof description !== 'string' || !description.trim()) {
problems.push(`${name} 需要任务描述`)
}
if (!Array.isArray(tests) || !Array.isArray(checks)) {
problems.push(`${name} 的 tests 和 checks 必须为数组`)
continue
}
if (tests.length === 0 && checks.length === 0) {
problems.push(`${name} 需要至少一个回归测试路径或检查命令`)
}
for (const script of checks) {
if (!allowedChecks.has(script) || typeof scripts?.[script] !== 'string') {
problems.push(`${name} 的检查命令未注册:${script}`)
}
}
if (tests.length === 0) {
problems.push(`${name} 需要至少一个回归测试路径`)
}
for (const path of tests) {
if (!testPattern.test(path) || !existsSync(join(root, path))) {
if (
typeof path !== 'string' ||
!testPattern.test(path) ||
!existsSync(join(root, path))
) {
problems.push(`${name} 的回归测试路径无效:${path}`)
continue
}
@ -55,6 +91,71 @@ function checkScopes() {
}
}
function checkIndexes() {
const problems = []
const cards = Object.keys(scopes).map(contextPath)
const entryLinks = new Set()
for (const path of [...indexFiles, ...cards]) {
const file = join(root, path)
if (!existsSync(file) || !statSync(file).isFile()) {
problems.push(`索引文档不存在:${path}`)
continue
}
// 索引统一使用行内相对链接;只检查文件目标,不请求外链或解析标题。
const markdown = readFileSync(file, 'utf8')
for (const [, href] of markdown.matchAll(/\[[^\]\n]+\]\(([^)\s]+)\)/g)) {
const [target] = href.split('#', 1)
if (!target || /^(?:[\w+.-]+:|\/\/)/.test(target)) continue
const destination = resolve(dirname(file), target)
const fromRoot = relative(root, destination)
if (
isAbsolute(target) ||
isAbsolute(fromRoot) ||
fromRoot === '..' ||
fromRoot.startsWith(`..${sep}`) ||
!existsSync(destination)
) {
problems.push(`${path} 的相对链接无效:${href}`)
} else if (path === 'llms.txt') {
entryLinks.add(destination)
}
}
}
for (const path of cards) {
if (!entryLinks.has(join(root, path))) {
problems.push(`llms.txt 缺少可用的主题链接:${path}`)
}
}
for (const file of globSync('harness/context/*.md', { cwd: root })) {
if (!cards.includes(file.split(sep).join('/'))) {
problems.push(`主题索引尚未注册:${file}`)
}
}
if (problems.length > 0) {
throw new Error(problems.join('\n'))
}
}
function scopeCommands(name) {
const { tests = [], checks = [] } = scopes[name]
return [
['env:check'],
...checks.map((script) => [script]),
...(tests.length ? [['test:run', ...tests]] : []),
]
}
function showContext(name) {
if (!name) {
for (const [id, { description }] of Object.entries(scopes)) {
@ -64,12 +165,15 @@ function showContext(name) {
return
}
const { description, paths, tests } = scopes[name]
const path = contextPath(name)
console.log(`${name} ${description}`)
console.log(paths.map((path) => ` ${path}`).join('\n'))
console.log(`定向验证:pnpm harness verify ${name}`)
console.log(`回归用例:pnpm test:run ${tests.join(' ')}`)
console.log(`阅读入口:${path}(正文链接相对此文件)\n`)
console.log(readFileSync(join(root, path), 'utf8').trimEnd())
console.log(`\npnpm harness verify ${name} 执行:`)
for (const args of scopeCommands(name)) {
console.log(` pnpm ${args.join(' ')}`)
}
}
function verify(name) {
@ -77,10 +181,7 @@ function verify(name) {
checkScopes()
}
const commands =
name === 'all'
? [['check']]
: [['env:check'], ['test:run', ...scopes[name].tests]]
const commands = name === 'all' ? [['check']] : scopeCommands(name)
const reports = join(root, '.harness-local', 'runs')
const startedAt = new Date().toISOString()
const steps = []
@ -96,7 +197,7 @@ function verify(name) {
console.log(`\n> ${command}`)
// Windows 需要 shell 启动 pnpm.cmd,参数来自固定命令与已校验的测试路径。
// Windows 需要 shell 启动 pnpm.cmd,只传入允许的脚本名与已校验的测试路径。
const options = { cwd: root, stdio: 'inherit' }
const result =
process.platform === 'win32'
@ -138,12 +239,16 @@ function verify(name) {
}
try {
const knownScope = scope && Object.hasOwn(scopes, scope)
const knownScope =
scope &&
scope !== 'all' &&
scopePattern.test(scope) &&
Object.hasOwn(scopes, scope)
if (action === '--help' && !scope) {
console.log(`pnpm harness context [scope] 查看任务上下文
pnpm harness verify [scope] 定向验证,省略 scope 时执行全量检查
pnpm harness check 检查上下文与回归路径`)
pnpm harness check 检查主题索引、相对链接和验证目标`)
} else if (
action === 'context' &&
extra.length === 0 &&
@ -158,7 +263,8 @@ pnpm harness check 检查上下文与回归路径`)
verify(scope ?? 'all')
} else if (action === 'check' && !scope) {
checkScopes()
console.log('✓ Harness 上下文与回归路径有效')
checkIndexes()
console.log('✓ Harness 索引、相对链接和验证目标有效')
} else {
throw new Error(
'无效命令或任务域。使用 pnpm harness --help 或 pnpm harness context。',

View File

@ -1,16 +1,6 @@
{
"routing": {
"description": "路由、菜单、权限与持久化",
"paths": [
"apps/admin/src/router",
"apps/admin/src/router/README.md",
"apps/admin/src/store",
"apps/admin/src/store/README.md",
"apps/admin/src/router/config/schema.ts",
"apps/admin/src/router/config/views.ts",
"apps/admin/src/views/route-management",
"packages/routing"
],
"description": "页面注册、菜单、动态路由 JSON、角色与守卫",
"tests": [
"__test__/router/",
"__test__/hooks/useVueRouter.spec.ts",
@ -19,26 +9,20 @@
"__test__/cache/"
]
},
"layout": {
"description": "启动、Provider、布局、KeepAlive、Pinia 与偏好文件",
"tests": [
"__test__/app/",
"__test__/layout/",
"__test__/hooks/useAppNavigation.spec.ts",
"__test__/hooks/useLayoutScroll.spec.ts",
"__test__/hooks/useSiderBar.spec.ts",
"__test__/hooks/useTheme.spec.ts",
"__test__/cache/"
]
},
"ui": {
"description": "页面、组件、布局、主题与国际化",
"paths": [
"apps/admin/src/views",
"apps/admin/src/components/README.md",
"apps/admin/src/app-components/README.md",
"apps/admin/src/layout/README.md",
"apps/admin/src/locales/README.md",
"apps/admin/src/hooks/README.md",
"docs/ui-design.md",
"apps/docs/examples",
"apps/admin/src/views/login",
"apps/admin/src/views/demo/components/DemoPage.tsx",
"apps/admin/src/components/RSegment/README.md",
"apps/admin/src/app-components/provider/AppAutocompleteDefaults",
"packages/ui",
"packages/admin-shell",
"packages/composables",
"packages/directives"
],
"description": "页面、公共组件、主题、国际化、Hooks 与指令",
"tests": [
"__test__/app/",
"__test__/components/",
@ -47,51 +31,25 @@
"__test__/workspace/consumer.spec.tsx"
]
},
"table-pro": {
"description": "RTablePro、useTablePro、搜索、分页、选列、导出与打印",
"tests": [
"__test__/components/table-pro.spec.ts",
"__test__/components/table-pro-search.spec.ts",
"__test__/components/table-pro-columns.spec.ts",
"__test__/components/table-pro-exports.spec.ts"
]
},
"api": {
"description": "API、Axios 拦截器与演示 Mock",
"paths": [
"apps/admin/src/api",
"apps/admin/src/axios/README.md",
"apps/admin/mock/demo",
"apps/admin/src/demo-data",
"packages/http"
],
"description": "业务 API、Axios、请求取消、拦截器与演示 Mock",
"tests": [
"__test__/axios/",
"__test__/mock/",
"__test__/workspace/http-client.spec.ts"
]
},
"icons": {
"description": "图标分包、类型清单与热更新",
"paths": [
"packages/icons/src/A_README.md",
"scripts/icons.mjs",
"vite.plugin.config.ts",
"packages/icons/scripts/icons.mjs"
],
"tests": ["__test__/icons/"]
},
"harness": {
"description": "工程协作入口、回归范围与验收报告",
"paths": [
"harness/README.md",
"harness/run.mjs",
"harness/scopes.json",
"llms.txt",
".github/workflows/ci.yaml",
"scripts/check-package-boundaries.mjs",
"scripts/assemble-pages.mjs"
],
"tests": ["__test__/harness/"]
},
"utils": {
"description": "公共工具、兼容入口与数据契约",
"paths": [
"apps/admin/src/utils/README.md",
"apps/admin/src/utils/index.ts",
"packages/utils"
],
"description": "公共工具、缓存、历史密文和兼容入口",
"tests": [
"__test__/basic/",
"__test__/cache/",
@ -101,5 +59,21 @@
"__test__/utils-contracts/",
"__test__/vue/"
]
},
"icons": {
"description": "SVG 分包、图标名、清单生成和热更新",
"tests": ["__test__/icons/"]
},
"docs": {
"description": "VitePress、API 参考、内嵌示例、侧栏与旧页跳转",
"checks": ["docs:check"]
},
"toolchain": {
"description": "工作区、公开导出、类型检查、Vite、构建与 CI",
"checks": ["packages:check", "typecheck"]
},
"harness": {
"description": "索引、回归范围、验证命令和本地报告",
"tests": ["__test__/harness/"]
}
}

View File

@ -1,29 +1,23 @@
# Ray Template
> Vue 3 + TypeScript/TSX + Vite + Pinia + Vue Router 中后台模板。应用入口在 apps/admin/src,工程验收由 AI Harness 管理。
> Vue 3 + TypeScript/TSX 中后台模板。pnpm workspace 包含后台应用、VitePress 文档站和共享包。
先读 AGENTS.md,再按任务执行 pnpm harness context <scope>。构建和检查以 package.json、pnpm-lock.yaml、.nvmrc 与 CI 为准。
遵循 [AGENTS.md](AGENTS.md),按任务选择下列入口。索引可直接阅读,也可用 `pnpm harness context <scope>` 查看同一份内容和定向验证命令。
## 任务入口
## 任务索引
- [协作约定](AGENTS.md): 工作区保护、验证、交付范围
- [AI Harness](harness/README.md): 定向上下文、测试、浏览器验收
- [架构地图](docs/architecture.md): 应用启动、跨模块调用与部署
- [读者文档](apps/docs/README.md): VitePress 本地开发、API 参考和页内示例
- [路由与动态配置](apps/admin/src/router/README.md): 来源切换、后端 JSON、字段与权限
- [路由 JSON Schema](apps/admin/src/router/config/schema.ts): 配置结构和 TypeScript 类型的唯一来源
- [页面 ID 注册表](apps/admin/src/router/config/views.ts): 路由配置可引用的页面及 KeepAlive 名称
- [路由管理页](apps/admin/src/views/route-management/index.tsx): 配置录入、校验、导入和导出
- [Pinia](apps/admin/src/store/README.md): 菜单、会话、布局和持久化边界
- [组件入口](apps/admin/src/components/index.ts): 公开组件与 hooks 导出
- [TablePro](packages/ui/src/RTablePro/README.md): 列表、数据源、分页、缓存与打印
- [页面样式](docs/ui-design.md): 主题变量、示例布局和 UI 验收
- [请求与取消](apps/admin/src/axios/README.md): 请求实例、拦截器及接口契约
- [图标](packages/icons/src/A_README.md): 图标资源、生成和类型清单
- [routing](harness/context/routing.md):新增页面和菜单、动态路由 JSON、页面 ID、角色与守卫。
- [layout](harness/context/layout.md):启动、Provider、导航栏、KeepAlive、Pinia、偏好导入导出。
- [ui](harness/context/ui.md):公共组件、页面与登录、主题和双语文案、Hooks、指令。
- [table-pro](harness/context/table-pro.md):RTablePro、useTablePro、搜索、请求、选列、导出与打印。
- [api](harness/context/api.md):业务 API、Axios、AbortSignal、拦截器、Mock 与静态数据。
- [utils](harness/context/utils.md):精度、文件、存储、历史 AES 格式和应用兼容入口。
- [icons](harness/context/icons.md):SVG 分包、图标名、清单生成和热更新。
- [docs](harness/context/docs.md):VitePress、API 参考、内嵌示例、侧栏与旧页跳转。
- [toolchain](harness/context/toolchain.md):工作区依赖、公开导出、TypeScript、Vite、产物与 CI。
- [harness](harness/context/harness.md):索引维护、回归目标、验证命令与报告。
## 按任务验证
## 按需背景
- 路由、权限、菜单、持久化使用 pnpm harness verify routing
- 组件、登录、示例页面使用 pnpm harness verify ui
- 接口和 Mock 使用 pnpm harness verify api
- 全量验收使用 pnpm harness verify
- [架构地图](docs/architecture.md):工作区边界、运行链路、类型检查和部署。
- [AI Harness](harness/README.md):验证流程、浏览器验收和本地证据。