mirror of
https://github.com/XiaoDaiGua-Ray/ray-template.git
synced 2026-11-17 16:13:36 +08:00
chore(harness): scope verification and standardize English guidance
This commit is contained in:
parent
969f764c21
commit
a7ffb862a2
14
.github/pull_request_template.md
vendored
14
.github/pull_request_template.md
vendored
@ -1,11 +1,11 @@
|
||||
## 变化与原因
|
||||
## Changes and rationale
|
||||
|
||||
<!-- 描述用户能观察到的变化,以及需要这次改动的原因。 -->
|
||||
<!-- Describe the observable change and the problem it addresses. -->
|
||||
|
||||
## 验证
|
||||
## Verification
|
||||
|
||||
- [ ] `pnpm harness verify` 或 CI 的 `pnpm check`
|
||||
- [ ] 涉及页面时,验证对应路由、中文/英文与明暗主题
|
||||
- [ ] 涉及持久化、权限或公共组件时,检查已有数据与调用方兼容性
|
||||
- [ ] Run relevant tests or `pnpm harness verify <scope>` for the affected area. Use `pnpm harness verify all` for integration risk or releases; CI runs `pnpm check`.
|
||||
- [ ] For visible behavior changes, verify only affected pages, actions, and language/theme/viewport dimensions. Explain when this does not apply.
|
||||
- [ ] For persistence, permissions, or shared components, check compatibility with existing data and callers.
|
||||
|
||||
<!-- 写明实际命令、结果、回归用例和未验证部分。浏览器验收附上操作与观察结果。 -->
|
||||
<!-- Select the verification scope using harness/README.md. Record actual commands, results, regression cases, and unverified areas. For browser verification, include actions and observations; mark it as not applicable when there is no UI impact. -->
|
||||
|
||||
15
AGENTS.md
15
AGENTS.md
@ -1,10 +1,11 @@
|
||||
# Ray Template
|
||||
|
||||
Vue 3 + TSX 中后台模板,包含后台应用、文档站与共享包。
|
||||
A Vue 3 + TSX admin template with an admin application, a documentation site, and shared packages.
|
||||
|
||||
- 需要定位实现时,从 [任务索引](llms.txt) 或 `pnpm harness context <scope>` 选相关主题。跨模块变更再查 [架构地图](docs/architecture.md)。
|
||||
- 先看 `git status`,保留已有改动。变更路由、持久化、请求或公共组件时,追踪调用方和现有数据契约。
|
||||
- 复杂任务中,宿主支持且当前权限允许时,主模型可按[分工约定](harness/README.md#按需使用-subagent)自行决定是否启用 subagent,无需为分工单独请示。主模型负责整合与最终验收。
|
||||
- 新增或修改注释时遵循 [注释规范](docs/comment-style.md)。页面文案同时维护中英文,页面改动按 [Harness 指南](harness/README.md#浏览器验收) 验收。
|
||||
- 完成实现后运行 `pnpm harness verify`,执行全量检查并留存报告。交付说明实际验证及未验证项。
|
||||
- 使用当前源码、清单和锁文件核对工程事实。敏感数据不进入源码、提示词或证据。提交、推送与部署遵循用户授权。
|
||||
- To locate an implementation, choose a topic from the [task index](llms.txt) or `pnpm harness context <scope>`. Consult the [architecture map](docs/architecture.md) for changes that cross module boundaries.
|
||||
- Check `git status` first and preserve existing changes. Trace callers and existing data contracts before changing routing, persistence, requests, or shared components.
|
||||
- For complex tasks, the lead agent may choose to use subagents under the [delegation guidelines](harness/README.md#using-subagents-when-useful), when the host supports them and current permissions allow it. Delegation needs no separate approval. The lead agent owns integration and final verification.
|
||||
- Write agent guidance and internal engineering documentation in English. Preserve the intended languages of product copy and reader-facing documentation.
|
||||
- Follow the [comment style](docs/comment-style.md) when adding or editing comments. Maintain both Chinese and English product copy. For visible behavior changes, use [browser verification](harness/README.md#browser-verification) only for affected pages, actions, and dimensions.
|
||||
- Select relevant tests or `pnpm harness verify <scope>` using the [verification scope](harness/README.md#choosing-the-verification-scope). Small changes do not default to full checks or a UI/UX sweep. Use full checks for integration risk, releases, or an explicit request; CI keeps `pnpm check`. Within one task, rerun only checks affected by subsequent changes. Report what was and was not verified.
|
||||
- Establish engineering facts from current source, manifests, and the lockfile. Keep sensitive data out of source, prompts, and evidence. Commits, pushes, and deployments require user authorization.
|
||||
|
||||
@ -1,22 +1,22 @@
|
||||
# commit 规范
|
||||
# Commit conventions
|
||||
|
||||
## commit message 格式
|
||||
## Commit message format
|
||||
|
||||
在提交代码时,`commit message` 遵循以下格式:
|
||||
Use the following `commit message` types:
|
||||
|
||||
- feat: 新功能`(feature)`
|
||||
- fix: 修补 `bug`
|
||||
- update: 更新代码
|
||||
- docs: 文档(documentation)
|
||||
- style: 格式(不影响代码运行的变动)
|
||||
- refactor: 重构(即不是新增功能,也不是修改bug的代码变动)
|
||||
- test: 增加测试
|
||||
- chore: 构建过程或辅助工具的变动
|
||||
- revert: 撤销
|
||||
- merge: 合并分支
|
||||
- perf: 优化相关,比如提升性能、体验
|
||||
- build: 构建
|
||||
- plugin: 插件更新
|
||||
- publish: 发布
|
||||
- feat: New feature
|
||||
- fix: Bug fix
|
||||
- update: Code update
|
||||
- docs: Documentation
|
||||
- style: Formatting changes that do not affect runtime behavior
|
||||
- refactor: Code restructuring that neither adds a feature nor fixes a bug
|
||||
- test: Additional tests
|
||||
- chore: Changes to the build process or supporting tools
|
||||
- revert: Revert a change
|
||||
- merge: Merge branches
|
||||
- perf: Optimization, such as performance or user experience improvements
|
||||
- build: Build changes
|
||||
- plugin: Plugin updates
|
||||
- publish: Publication
|
||||
|
||||
当你需要定制化自己的`commit message`格式时,可以在`commitlint.config.cjs`文件中进行配置。
|
||||
Customize the `commit message` format in `commitlint.config.cjs` when needed.
|
||||
|
||||
14
README.md
14
README.md
@ -120,13 +120,13 @@ export default defineComponent({
|
||||
|
||||
## Checks, builds, and deployment
|
||||
|
||||
| Command | What it does |
|
||||
| ----------------------------- | ------------------------------------------------------------------------------------------- |
|
||||
| `pnpm test:run` | Run the Vitest suite |
|
||||
| `pnpm check` | Run the same checks as CI, including types, lint, formatting, tests, and a production build |
|
||||
| `pnpm harness context` | Find entry points and checks for areas such as routing, UI, and APIs |
|
||||
| `pnpm harness verify` | Run the full check and save a local report, or pass a scope to run targeted checks |
|
||||
| `pnpm build` / `pnpm preview` | Build into `dist/production` or serve the build locally |
|
||||
| Command | What it does |
|
||||
| ----------------------------- | --------------------------------------------------------------------------------------------- |
|
||||
| `pnpm test:run` | Run the Vitest suite |
|
||||
| `pnpm check` | Run the same checks as CI, including types, lint, formatting, tests, and a production build |
|
||||
| `pnpm harness context` | Find entry points and checks for areas such as routing, UI, and APIs |
|
||||
| `pnpm harness verify <scope>` | Run targeted checks and save a local report; use `all` for full integration or release checks |
|
||||
| `pnpm build` / `pnpm preview` | Build into `dist/production` or serve the build locally |
|
||||
|
||||
`pnpm docs:build` builds the documentation separately. `pnpm pages:build` assembles both builds under `dist/pages` for `/ray-template/` and `/ray-template/docs/`.
|
||||
|
||||
|
||||
@ -120,13 +120,13 @@ export default defineComponent({
|
||||
|
||||
## 检查、构建与部署
|
||||
|
||||
| 命令 | 用途 |
|
||||
| ----------------------------- | -------------------------------------------------------- |
|
||||
| `pnpm test:run` | 运行 Vitest 测试 |
|
||||
| `pnpm check` | 执行 CI 同款检查,包含类型、Lint、格式、测试和生产构建 |
|
||||
| `pnpm harness context` | 按路由、UI、API 等任务域查找源码入口和验证命令 |
|
||||
| `pnpm harness verify` | 执行全量检查并保存本地报告,也可以指定任务域进行定向验证 |
|
||||
| `pnpm build` / `pnpm preview` | 输出到 `dist/production`,或在本机预览构建 |
|
||||
| 命令 | 用途 |
|
||||
| ----------------------------- | ------------------------------------------------------------- |
|
||||
| `pnpm test:run` | 运行 Vitest 测试 |
|
||||
| `pnpm check` | 执行 CI 同款检查,包含类型、Lint、格式、测试和生产构建 |
|
||||
| `pnpm harness context` | 按路由、UI、API 等任务域查找源码入口和验证命令 |
|
||||
| `pnpm harness verify <scope>` | 执行定向检查并保存本地报告;集成风险或发布使用 `all` 全量检查 |
|
||||
| `pnpm build` / `pnpm preview` | 输出到 `dist/production`,或在本机预览构建 |
|
||||
|
||||
`pnpm docs:build` 单独构建文档。`pnpm pages:build` 组装后台与文档到 `dist/pages`,分别服务于 `/ray-template/` 和 `/ray-template/docs/`。
|
||||
|
||||
|
||||
10
TODO.md
10
TODO.md
@ -1,8 +1,8 @@
|
||||
需求:
|
||||
Requirements:
|
||||
|
||||
- 检查
|
||||
- Review
|
||||
|
||||
其他:
|
||||
Additional notes:
|
||||
|
||||
1. 请分批次去完成以上任务
|
||||
2. 以上所有的改动都请放心大胆的去做!做你认为合理准确的事情,我把所有权限都交给你!放心去做!
|
||||
1. Complete the tasks above in batches.
|
||||
2. Proceed confidently with all the changes above. Do what you judge to be reasonable and accurate; you have full authorization for those tasks.
|
||||
|
||||
@ -38,7 +38,7 @@ beforeEach(() => {
|
||||
writeFileSync(join(fixture, 'llms.txt'), '[Demo](harness/context/demo.md)\n')
|
||||
writeFileSync(
|
||||
join(fixture, 'harness/context/demo.md'),
|
||||
'# Demo\n\n先读 [架构](../../docs/architecture.md#fixture)。\n',
|
||||
'# Demo\n\nRead [architecture](../../docs/architecture.md#fixture)。\n',
|
||||
)
|
||||
writeScope({ tests: ['__test__/demo/'] })
|
||||
writeScripts({ 'env:check': 'node -e "process.exit(23)"' })
|
||||
@ -75,14 +75,16 @@ function readReport() {
|
||||
)
|
||||
}
|
||||
|
||||
it('拒绝没有回归用例的目录', () => {
|
||||
it('rejects directories without regression tests', () => {
|
||||
const result = run('check')
|
||||
|
||||
expect(result.status).toBe(1)
|
||||
expect(result.stderr).toContain('回归测试路径没有用例:__test__/demo/')
|
||||
expect(result.stderr).toContain(
|
||||
'regression test path contains no tests: __test__/demo/',
|
||||
)
|
||||
})
|
||||
|
||||
it('移动索引引用的实现后,检查会报告来源与断链', () => {
|
||||
it('reports the source and broken link when an indexed implementation moves', () => {
|
||||
writeFileSync(join(fixture, '__test__/demo/example.spec.ts'), '')
|
||||
expect(run('check').status).toBe(0)
|
||||
|
||||
@ -91,20 +93,20 @@ it('移动索引引用的实现后,检查会报告来源与断链', () => {
|
||||
|
||||
expect(result.status).toBe(1)
|
||||
expect(result.stderr).toContain(
|
||||
'harness/context/demo.md 的相对链接无效:../../docs/architecture.md#fixture',
|
||||
'harness/context/demo.md: invalid relative link: ../../docs/architecture.md#fixture',
|
||||
)
|
||||
})
|
||||
|
||||
it('拒绝未从静态入口链接的已注册主题', () => {
|
||||
it('rejects registered topics missing from the static entry point', () => {
|
||||
writeFileSync(join(fixture, '__test__/demo/example.spec.ts'), '')
|
||||
writeFileSync(join(fixture, 'llms.txt'), '# 空入口\n')
|
||||
writeFileSync(join(fixture, 'llms.txt'), '# Empty index\n')
|
||||
const result = run('check')
|
||||
|
||||
expect(result.status).toBe(1)
|
||||
expect(result.stderr).toContain('llms.txt 缺少可用的主题链接')
|
||||
expect(result.stderr).toContain('llms.txt is missing a valid topic link')
|
||||
})
|
||||
|
||||
it('无 Vitest 的任务域能展示索引并执行现有项目检查', () => {
|
||||
it('shows context and runs project checks for scopes without Vitest', () => {
|
||||
writeScope({ checks: ['docs:check'] })
|
||||
writeScripts({
|
||||
'env:check': 'node --version',
|
||||
@ -116,7 +118,7 @@ it('无 Vitest 的任务域能展示索引并执行现有项目检查', () => {
|
||||
|
||||
expect(context.status).toBe(0)
|
||||
expect(context.stdout).toContain(
|
||||
'先读 [架构](../../docs/architecture.md#fixture)',
|
||||
'Read [architecture](../../docs/architecture.md#fixture)',
|
||||
)
|
||||
expect(context.stdout).toContain('pnpm docs:check')
|
||||
|
||||
@ -131,17 +133,17 @@ it('无 Vitest 的任务域能展示索引并执行现有项目检查', () => {
|
||||
})
|
||||
})
|
||||
|
||||
it('拒绝把全量检查登记为定向检查,避免递归调用', () => {
|
||||
it('rejects registering full checks as targeted checks to prevent recursion', () => {
|
||||
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')
|
||||
expect(result.stderr).toContain('demo: unregistered check command: check')
|
||||
})
|
||||
|
||||
it('子命令失败时停止后续验证,并记录失败状态', () => {
|
||||
it('stops subsequent checks and records failure when a child command fails', () => {
|
||||
writeFileSync(join(fixture, '__test__/demo/example.spec.ts'), '')
|
||||
|
||||
const result = run('verify', 'demo')
|
||||
@ -153,3 +155,59 @@ it('子命令失败时停止后续验证,并记录失败状态', () => {
|
||||
steps: [{ command: 'pnpm env:check', exitCode: 23 }],
|
||||
})
|
||||
})
|
||||
|
||||
it('runs only registered tests without appending full checks', () => {
|
||||
writeFileSync(join(fixture, '__test__/demo/example.spec.ts'), '')
|
||||
writeScripts({
|
||||
'env:check': 'node --version',
|
||||
'test:run': 'node -e "process.exit(0)"',
|
||||
check: 'node -e "process.exit(97)"',
|
||||
})
|
||||
|
||||
expect(run('verify', 'demo').status).toBe(0)
|
||||
expect(readReport()).toMatchObject({
|
||||
scope: 'demo',
|
||||
status: 'passed',
|
||||
steps: [
|
||||
{ command: 'pnpm env:check', exitCode: 0 },
|
||||
{ command: 'pnpm test:run __test__/demo/', exitCode: 0 },
|
||||
],
|
||||
})
|
||||
})
|
||||
|
||||
it.each(['api:check', 'icons:check'])(
|
||||
'stops regressions and records failure when targeted %s finds stale artifacts',
|
||||
(script) => {
|
||||
writeFileSync(join(fixture, '__test__/demo/example.spec.ts'), '')
|
||||
writeScope({ checks: [script], tests: ['__test__/demo/'] })
|
||||
writeScripts({
|
||||
'env:check': 'node --version',
|
||||
[script]: 'node -e "process.exit(23)"',
|
||||
'test:run': 'node -e "process.exit(97)"',
|
||||
})
|
||||
|
||||
expect(run('verify', 'demo').status).toBe(23)
|
||||
expect(readReport()).toMatchObject({
|
||||
scope: 'demo',
|
||||
status: 'failed',
|
||||
steps: [
|
||||
{ command: 'pnpm env:check', exitCode: 0 },
|
||||
{ command: `pnpm ${script}`, exitCode: 23 },
|
||||
],
|
||||
})
|
||||
},
|
||||
)
|
||||
|
||||
it.each([{ args: [] }, { args: ['all'] }])(
|
||||
'preserves pnpm check compatibility for the full-check entry point $args',
|
||||
({ args }) => {
|
||||
writeScripts({ check: 'node --version' })
|
||||
|
||||
expect(run('verify', ...args).status).toBe(0)
|
||||
expect(readReport()).toMatchObject({
|
||||
scope: 'all',
|
||||
status: 'passed',
|
||||
steps: [{ command: 'pnpm check', exitCode: 0 }],
|
||||
})
|
||||
},
|
||||
)
|
||||
|
||||
@ -1,14 +1,12 @@
|
||||
# \_\_ray-template
|
||||
|
||||
该包用于管理一些模板的管理,例如:
|
||||
This module owns template management checks, including:
|
||||
|
||||
- validAppRootPath: 检查模板 `appRootPath` 是否配置正确
|
||||
- validLocal: 检查模板 `localConfig` 是否配置正确
|
||||
- validAppRootPath: Validate the template's `appRootPath` configuration.
|
||||
- validLocal: Validate the template's `localConfig` configuration.
|
||||
|
||||
## 拓展
|
||||
## Extension
|
||||
|
||||
当你需要在做一些定制化操作的时候,可以尝试在这个包里做一些事情。
|
||||
Add custom template-management operations here when appropriate, then import and call them in `main.ts`.
|
||||
|
||||
最后在 `main.ts` 中导入并且调用即可。
|
||||
|
||||
> 出于一些考虑,并没有做自动化导入调用,所以需要自己手动来。(好吧,其实就是我懒-,-)
|
||||
Imports and invocation are explicit; this module does not provide automatic discovery or execution.
|
||||
|
||||
@ -1,17 +1,17 @@
|
||||
## 描述
|
||||
## Purpose
|
||||
|
||||
该包存放与模板深度绑定的组件:
|
||||
This directory contains components closely coupled to the template:
|
||||
|
||||
- app:存放与模板数据绑定的组件
|
||||
- provider:存放模板注入类组件
|
||||
- app: Components bound to template data.
|
||||
- provider: Components that provide template services through injection.
|
||||
|
||||
## 页面与 Provider
|
||||
## Pages and providers
|
||||
|
||||
- `AppPageHeader` 统一页面眉题、主标题、说明与右侧操作区;页面正文保留各自布局,不在此封装业务内容。
|
||||
- `AppShareLink` 默认使用紧凑入口,工作台通过 `variant="cards"` 显示具名链接卡片,保留登录页的空间约束。
|
||||
- `AppAvatar` 从 signing Store 读取头像与名称;保留 Naive UI Avatar 相关 props。
|
||||
- `AppNaiveGlobalProvider` 提供 Naive UI 上下文以及 `window.$message`、`$notification`、`$dialog`、`$loadingBar`。离散提示实例随 Provider 初始化与卸载,并实时同步主题和语言;只在 Provider 挂载期间调用这些对象。
|
||||
- `AppWatermarkProvider` 为全局水印提供入口,显示与内容通过 `useWatermark` 调整。需要限制水印覆盖范围时,调整 Provider 的挂载位置。
|
||||
- `AppRequestCancelerProvider` 在路由更新前取消旧请求;默认布局内容负责挂载。自定义内容插槽时需保留所需的请求取消行为。
|
||||
- `AppPageHeader` standardizes the eyebrow, main title, description, and right-side actions. Pages retain their own body layouts; do not wrap business content here.
|
||||
- `AppShareLink` defaults to a compact entry point. The dashboard uses `variant="cards"` for named link cards while preserving the login page's space constraints.
|
||||
- `AppAvatar` reads the avatar and name from the signing store and retains relevant Naive UI Avatar props.
|
||||
- `AppNaiveGlobalProvider` supplies Naive UI context and `window.$message`, `$notification`, `$dialog`, and `$loadingBar`. Discrete notification instances initialize and dispose with the provider and track theme/locale changes. Use them only while the provider is mounted.
|
||||
- `AppWatermarkProvider` provides the global watermark entry point; `useWatermark` controls visibility and content. Change the provider's mount location to limit its coverage.
|
||||
- `AppRequestCancelerProvider` cancels old requests before route updates. Default layout content mounts it; custom content slots must retain the required cancellation behavior.
|
||||
|
||||
组件介绍放在此类文档中,声明前不再保留大段说明;注释位置与格式遵循 [统一注释规范](../../../../docs/comment-style.md)。
|
||||
Keep component introductions in documents like this one rather than large blocks before declarations. Follow the [shared comment style](../../../../docs/comment-style.md) for comment placement and formatting.
|
||||
|
||||
@ -1,12 +1,12 @@
|
||||
# 请求与拦截器
|
||||
# Requests and interceptors
|
||||
|
||||
业务接口放在 `src/api`,使用 `@/axios` 导出的 `request`。成功拦截器返回响应体,`request<T>()` 解析为 `T`;失败仍拒绝。需要响应头或 HTTP 状态时,使用保留完整响应的 Axios 实例。
|
||||
Put business endpoints in `src/api` and use `request` exported by `@/axios`. Success interceptors return the response body, so `request<T>()` resolves to `T`; failures still reject. Use an Axios instance that retains the full response when headers or HTTP status are needed.
|
||||
|
||||
默认请求配置位于 `src/app-config/request-config.ts`。通用请求和响应逻辑分别放入 `axios-interceptor/request/plugins` 与 `axios-interceptor/response/plugins`,在各自的 `provider.ts` 中登记。成功队列使用 `AxiosRequestInterceptor` 或 `AxiosResponseInterceptor`,失败队列使用 `FetchErrorFunction`;调整队列顺序时核对前置逻辑。
|
||||
Default request configuration is in `src/app-config/request-config.ts`. Put reusable request/response logic in `axios-interceptor/request/plugins` and `axios-interceptor/response/plugins`, registering each in its `provider.ts`. Success queues use `AxiosRequestInterceptor` or `AxiosResponseInterceptor`; failure queues use `FetchErrorFunction`. Check prerequisite logic when reordering queues.
|
||||
|
||||
## 取消请求
|
||||
## Request cancellation
|
||||
|
||||
默认取消器按 URL、方法、序列化参数与请求体识别重复请求,并为当前请求注入 signal。默认布局中的 `AppRequestCancelerProvider` 会在路由更新前取消受它管理的待处理请求。
|
||||
The default canceller identifies duplicates by URL, method, serialized params, and body, then injects a signal into the current request. In the default layout, `AppRequestCancelerProvider` cancels the pending requests it manages before route updates.
|
||||
|
||||
```ts
|
||||
import { request } from '@/axios'
|
||||
@ -20,4 +20,4 @@ const loadOrders = (signal: AbortSignal) =>
|
||||
})
|
||||
```
|
||||
|
||||
调用方提供 signal 时,将 `cancelConfig.cancel` 设为 `false`,避免被默认取消器覆盖,并由调用方负责中止。人员列表展示了 [TablePro 传递 signal 的方式](../api/demo/mock/person.ts)。`useRequest` 包装同一实例,需在有效的 Vue effect 作用域中调用。
|
||||
When supplying a signal, set `cancelConfig.cancel` to `false` to avoid default-canceller replacement, and own the abort lifecycle. The person list demonstrates [forwarding TablePro's signal](../api/demo/mock/person.ts). `useRequest` wraps the same instance and must run within an active Vue effect scope.
|
||||
|
||||
@ -1,15 +1,15 @@
|
||||
# 组件使用约定
|
||||
# Component conventions
|
||||
|
||||
可复用组件按名称放在 `src/components` 下;通过 `@/components` 导入组件和类型。优先复用 Naive UI 与现有组件,不把组件介绍复制到 `defineComponent` 前。
|
||||
Organize reusable components by name under `src/components`. Import components and types through `@/components`. Prefer Naive UI and existing project components. Do not duplicate component introductions before `defineComponent`.
|
||||
|
||||
## 非显然的调用约束
|
||||
## Non-obvious usage constraints
|
||||
|
||||
- `RCollapseGrid` 基于 Naive UI Grid,子项需要使用 `NGridItem`。不要用普通容器替代 Grid 子项。
|
||||
- `RChart` 与 `useChart` 负责实例初始化、销毁、尺寸与主题同步;调用方维护 ECharts options,需要的图表与组件按现有 ECharts 注册方式引入。
|
||||
- `PageResult` 基于 Naive UI Result,可作为组件或错误页面使用,保留继承的 props 与 slots。
|
||||
- [TablePro](RTablePro/README.md) 统一支持纯表格、搜索与分页及自适应高度。列顺序配置以第一层列为单位,深层子列跟随根列。
|
||||
- `RIcon.name` 为生成的完整分包路径类型,图标改动会在开发、HMR 和构建时同步;不要手工修改生成清单。
|
||||
- `RCollapseGrid` uses Naive UI Grid; its children must be `NGridItem`. Do not substitute ordinary containers for grid items.
|
||||
- `RChart` and `useChart` own instance initialization, disposal, sizing, and theme synchronization. Callers own ECharts options and register required chart types/components through the established ECharts mechanism.
|
||||
- `PageResult` uses Naive UI Result and can serve as a component or error page. Preserve inherited props and slots.
|
||||
- [TablePro](RTablePro/README.md) supports plain tables, search, pagination, and auto-height. Column ordering operates on first-level columns; nested columns follow their root column.
|
||||
- `RIcon.name` uses generated full group-path types. Development, HMR, and builds synchronize icon changes; do not edit generated manifests manually.
|
||||
|
||||
组件样式随组件入口加载。调整 Naive UI 内部元素时,使用当前组件的类名限定作用范围;组件需填满容器时由调用处或组件自身声明尺寸。全屏 `RModal` 的卡片正文仅在溢出时滚动,`RBarcode` 的加载区域随条码尺寸或响应式容器伸缩。
|
||||
Component styles load with their entry points. Scope changes to Naive UI internals using the current component's class. When a component must fill its container, declare dimensions at the call site or within the component. Fullscreen `RModal` card content scrolls only on overflow; `RBarcode` loading regions follow barcode dimensions or responsive containers.
|
||||
|
||||
示例见 `src/views/demo`;Hooks 的独立交互示例与生命周期约定见 [Hooks 文档](../hooks/README.md)。新增或修改注释遵循 [注释规范](../../../../docs/comment-style.md),完整教程放在 README 与示例页。
|
||||
Examples are in `src/views/demo`. Independent hook interactions and lifecycle conventions are in the [hook guide](../hooks/README.md). Follow the [comment style](../../../../docs/comment-style.md) when adding/editing comments; put complete tutorials in READMEs and demo pages.
|
||||
|
||||
@ -1,17 +1,17 @@
|
||||
## 说明
|
||||
## Purpose
|
||||
|
||||
> 全局自定义指令入口。
|
||||
> Entry point for global custom directives.
|
||||
|
||||
## 规范
|
||||
## Conventions
|
||||
|
||||
- 指令应该为全局的通用性指令
|
||||
- 如果指令需要与系统的数据进行关联,应该注意数据的管理与指令注册使用时机
|
||||
- Directives should provide reusable, application-wide behavior.
|
||||
- When a directive depends on application data, account for data ownership and the timing of registration and usage.
|
||||
|
||||
## 新增指令说明
|
||||
## Adding a directive
|
||||
|
||||
- 模板视 modules 中每一个文件包为一个模板的指令(全局),并且每个文件包的名称,也被视为该指令名称
|
||||
- 添加文件包后,`强制要求 index.ts 为指令的输出文件名`
|
||||
- modules 包中所有指令都会被自动合并到模板中
|
||||
- Each directory in modules is treated as one global directive; its directory name is also the directive name.
|
||||
- Every directive directory must export through a file named `index.ts`.
|
||||
- All directives in modules are automatically incorporated into the template.
|
||||
|
||||
```ts
|
||||
/**
|
||||
@ -40,8 +40,8 @@ export default demoDirective
|
||||
// 4. 按照上述步骤执行后,会自动在模板中创建一个 v-demo 的指令供全局使用
|
||||
```
|
||||
|
||||
## 说明与来源
|
||||
## Usage and attribution
|
||||
|
||||
指令用法与绑定值示例统一维护在 [使用说明](README.DIR.md),不在指令工厂前重复整段教程。`disabled` 仅限制 CSS 交互,业务权限和提交校验仍需独立处理。
|
||||
Keep directive usage and binding examples in the [usage guide](README.DIR.md), rather than repeating full tutorials before directive factories. `disabled` restricts CSS interaction only; business permissions and submission validation still require separate handling.
|
||||
|
||||
水波纹辅助实现保留原有 [Pure Admin 来源标注](https://github.dev/pure-admin/vue-pure-admin/blob/main/src/components/ReCol/index.ts)。新增注释遵循 [仓库注释规范](../../../../docs/comment-style.md)。
|
||||
Retain the existing [Pure Admin attribution](https://github.dev/pure-admin/vue-pure-admin/blob/main/src/components/ReCol/index.ts) for the ripple helper. Follow the [repository comment style](../../../../docs/comment-style.md) for new comments.
|
||||
|
||||
@ -1,42 +1,42 @@
|
||||
# Hooks 示例与约定
|
||||
# Hook examples and conventions
|
||||
|
||||
共享 Hook 从 `@/hooks` 导出。内部调用优先按职责导入:`template` 依赖模板运行时,`components` 与组件契约配套,`web` 处理窗口、日期、截图和打印等能力。旧的 `web/useI18n`、`web/useVueRouter`、`web/usePagination` 入口继续转发。页面使用 Vue 3 Composition API + TSX;每个演示包含实际交互、响应式结果和可展开复制的用法代码。
|
||||
Shared hooks are exported through `@/hooks`. Internal callers should import by responsibility: `template` depends on the template runtime, `components` complements component contracts, and `web` handles windows, dates, screenshots, printing, and related capabilities. Legacy `web/useI18n`, `web/useVueRouter`, and `web/usePagination` entry points still re-export their implementations. Pages use Vue 3 Composition API + TSX. Each demo includes real interaction, reactive results, and expandable, copyable usage code.
|
||||
|
||||
| 分包 | Hook | 示例页面与操作 | 回归测试 |
|
||||
| ---------- | -------------------------- | ------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
|
||||
| template | `useTheme` | `/template-hooks`:明暗、切换、跟随系统 | [useTheme](../../../../__test__/hooks/useTheme.spec.ts) |
|
||||
| template | `useSpinning` | `/template-hooks`:加载动画、重新挂载页面 | [useSpinning](../../../../__test__/hooks/useSpinning.spec.ts) |
|
||||
| template | `useMaximize` | `/template-hooks`:内容最大化、共享退出按钮、Esc | [useMaximize](../../../../__test__/hooks/useMaximize.spec.ts) |
|
||||
| template | `useBadge` | `/template-hooks`:菜单标记文本、图标与显隐 | [useBadge](../../../../__test__/hooks/useBadge.spec.ts) |
|
||||
| template | `useWatermark` | `/template-hooks`:文本、显示、隐藏与切换 | [useWatermark](../../../../__test__/hooks/useWatermark.spec.ts) |
|
||||
| template | `useAppNavigation` | `/template-hooks`:完整路径、索引、嵌套菜单与 query | [useAppNavigation](../../../../__test__/hooks/useAppNavigation.spec.ts) |
|
||||
| template | `useAppRoot` | `/template-hooks`:读取首页、设置本页与恢复仪表盘 | [useAppRoot](../../../../__test__/hooks/useAppRoot.spec.ts) |
|
||||
| template | `useSiderBar` | `/template-hooks`:按路径关闭标签与左右/其他/全部标签 | [useSiderBar](../../../../__test__/hooks/useSiderBar.spec.ts) |
|
||||
| template | `useContentScroll` | `/template-hooks`:内容滚动到顶部或指定坐标 | [useLayoutScroll](../../../../__test__/hooks/useLayoutScroll.spec.ts) |
|
||||
| template | `useSiderScroll` | `/template-hooks`:侧栏滚动到顶部或指定坐标 | [useLayoutScroll](../../../../__test__/hooks/useLayoutScroll.spec.ts) |
|
||||
| web | `useDevice` | `/web-hooks`:随窗口尺寸更新断点判断 | [useDevice](../../../../__test__/hooks/useDevice.spec.ts) |
|
||||
| components | `usePagination` | `/web-hooks`:实际分页数据、页码、每页条数与重置 | [usePagination](../../../../__test__/hooks/usePagination.spec.ts) |
|
||||
| web | `useDayjs` | `/web-hooks`:日期格式化、天数差、开区间和日界限 | [useDayjs](../../../../__test__/hooks/useDayjs.spec.ts) |
|
||||
| template | `useI18n` | `/web-hooks`:命名空间、完整键和语言切换 | [useI18n](../../../../__test__/hooks/useI18n.spec.ts) |
|
||||
| template | `useVueRouter` | `/web-hooks`:当前路由、查询参数与页面导航 | [useVueRouter](../../../../__test__/hooks/useVueRouter.spec.ts) |
|
||||
| web | `useElementFullscreen` | `/web-hooks`:指定元素 CSS 全屏与恢复 | [useElementFullscreen](../../../../__test__/hooks/useElementFullscreen.spec.ts) |
|
||||
| web | `useDomToImage` | `/web-hooks`:PNG 生成、预览和失败提示 | [useDomToImage](../../../../__test__/hooks/useDomToImage.spec.ts) |
|
||||
| web | `usePrint` | `/web-hooks`:元素打印预览 | [usePrint](../../../../__test__/hooks/usePrint.spec.ts) |
|
||||
| components | `useContextmenuCoordinate` | `/web-hooks`:右键坐标、选择、外部关闭和停止监听;原 `/context-menu` 页面也保留 | [useContextmenuCoordinate](../../../../__test__/hooks/useContextmenuCoordinate.spec.tsx) |
|
||||
| Group | Hook | Example page and actions | Regression |
|
||||
| ---------- | -------------------------- | ---------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
|
||||
| template | `useTheme` | `/template-hooks`: light/dark, toggle, follow system | [useTheme](../../../../__test__/hooks/useTheme.spec.ts) |
|
||||
| template | `useSpinning` | `/template-hooks`: loading indicators and page remount | [useSpinning](../../../../__test__/hooks/useSpinning.spec.ts) |
|
||||
| template | `useMaximize` | `/template-hooks`: maximize content, shared exit button, Esc | [useMaximize](../../../../__test__/hooks/useMaximize.spec.ts) |
|
||||
| template | `useBadge` | `/template-hooks`: menu badge text, icons, and visibility | [useBadge](../../../../__test__/hooks/useBadge.spec.ts) |
|
||||
| template | `useWatermark` | `/template-hooks`: text, show, hide, and toggle | [useWatermark](../../../../__test__/hooks/useWatermark.spec.ts) |
|
||||
| template | `useAppNavigation` | `/template-hooks`: full paths, indexes, nested menus, and query | [useAppNavigation](../../../../__test__/hooks/useAppNavigation.spec.ts) |
|
||||
| template | `useAppRoot` | `/template-hooks`: read home, use the current page, restore dashboard | [useAppRoot](../../../../__test__/hooks/useAppRoot.spec.ts) |
|
||||
| template | `useSiderBar` | `/template-hooks`: close tabs by path or close left/right/other/all tabs | [useSiderBar](../../../../__test__/hooks/useSiderBar.spec.ts) |
|
||||
| template | `useContentScroll` | `/template-hooks`: scroll content to top or coordinates | [useLayoutScroll](../../../../__test__/hooks/useLayoutScroll.spec.ts) |
|
||||
| template | `useSiderScroll` | `/template-hooks`: scroll sidebar to top or coordinates | [useLayoutScroll](../../../../__test__/hooks/useLayoutScroll.spec.ts) |
|
||||
| web | `useDevice` | `/web-hooks`: update breakpoint checks with window size | [useDevice](../../../../__test__/hooks/useDevice.spec.ts) |
|
||||
| components | `usePagination` | `/web-hooks`: paginated data, page, page size, and reset | [usePagination](../../../../__test__/hooks/usePagination.spec.ts) |
|
||||
| web | `useDayjs` | `/web-hooks`: date formatting, day differences, open intervals, and day boundaries | [useDayjs](../../../../__test__/hooks/useDayjs.spec.ts) |
|
||||
| template | `useI18n` | `/web-hooks`: namespaces, full keys, and locale switching | [useI18n](../../../../__test__/hooks/useI18n.spec.ts) |
|
||||
| template | `useVueRouter` | `/web-hooks`: current route, query parameters, and navigation | [useVueRouter](../../../../__test__/hooks/useVueRouter.spec.ts) |
|
||||
| web | `useElementFullscreen` | `/web-hooks`: CSS fullscreen and restoration for a chosen element | [useElementFullscreen](../../../../__test__/hooks/useElementFullscreen.spec.ts) |
|
||||
| web | `useDomToImage` | `/web-hooks`: PNG generation, preview, and failure messages | [useDomToImage](../../../../__test__/hooks/useDomToImage.spec.ts) |
|
||||
| web | `usePrint` | `/web-hooks`: element print preview | [usePrint](../../../../__test__/hooks/usePrint.spec.ts) |
|
||||
| components | `useContextmenuCoordinate` | `/web-hooks`: context-menu coordinates, selection, outside close, and listener removal; legacy `/context-menu` remains | [useContextmenuCoordinate](../../../../__test__/hooks/useContextmenuCoordinate.spec.tsx) |
|
||||
|
||||
## 生命周期与状态
|
||||
## Lifecycle and state
|
||||
|
||||
- 组合式函数在 `setup` 或有效 effect scope 内创建,DOM 操作由用户事件或挂载后的回调触发。事件、订阅、动画帧随作用域清理。
|
||||
- 全局 UI 状态由 Pinia `runtime` 管理,通过 `useRuntimeGetters` / `useRuntimeActions` 访问,不写入持久化缓存。
|
||||
- `useSpinning().reload(wait)` 会卸载页面,恢复计时器由 runtime Store 持有;多个调用以最后一次刷新为准。
|
||||
- 默认布局中的加载提示始终位于可见内容区中央,支持长页面与内容最大化。`reload` 立即显示提示,`openSpin` 持续超过 120ms 时显示,`closeSpin` 立即关闭手动加载提示。
|
||||
- 两个滚动 Hook 可以在 setup 阶段创建,调用时才读取布局实例。无侧栏或未挂载时安全忽略。
|
||||
- `useMaximize` 操作布局内容,多个调用方共享状态;`useElementFullscreen` 操作任意单个元素,其状态属于当前实例。二者均不调用浏览器 Fullscreen API。
|
||||
- `navigationTo` 的索引从 0 开始;负数、小数、非有限数和越界索引不会导航。完整 URL 支持动态参数、query 和 hash;额外 query 参数可覆盖 URL 中的同名参数。成功调用返回 Router 导航 Promise。
|
||||
- `useDomToImage` 的返回类型跟随默认格式或本次 `create(format)`;失败通过 Error 拒绝,`finally` 在目标缺失时也会执行,此时参数可能为空。`created` 回调也会接收到运行时覆盖格式的结果,因此其参数为所有实际输出类型的联合,需先判断类型。
|
||||
- `useI18n('hooks').t('code')` 和 `.t('hooks.code')` 指向同一个翻译键。切换应用语言使用 `useSettingActions().updateLocale`,保持日期与组件库同步。
|
||||
- 国际化实例在开发热更新期间复用;初始化前创建的翻译方法会在调用时读取当前实例,不会永久停留在返回原始键的回退函数上。
|
||||
- `usePagination` 重置时使用首个 pageSizes 选项的数值,兼容 Naive UI 的对象选项。调用 `setCallback()` 可移除默认回调。
|
||||
- `usePrint` 在调用时解包目标。DOM 默认以 HTML 打印;Blob 图片与二进制 PDF 会先转换,调用方可以等待返回的 Promise。
|
||||
- Create composables in `setup` or an active effect scope. Trigger DOM operations from user events or post-mount callbacks. Clean up events, subscriptions, and animation frames with the scope.
|
||||
- Pinia `runtime` owns global UI state, accessed through `useRuntimeGetters` / `useRuntimeActions`. It is not persisted.
|
||||
- `useSpinning().reload(wait)` unmounts the page. The runtime store owns the restoration timer; the latest refresh wins across repeated calls.
|
||||
- In the default layout, loading indicators stay centered in the visible content area, including long pages and maximized content. `reload` shows immediately; `openSpin` shows after lasting more than 120ms; `closeSpin` immediately closes manual loading indicators.
|
||||
- Both scroll hooks can be created during setup and read the layout instance only when invoked. Missing sidebars or unmounted instances are safely ignored.
|
||||
- `useMaximize` acts on layout content and shares state across callers. `useElementFullscreen` acts on one arbitrary element and owns per-instance state. Neither calls the browser Fullscreen API.
|
||||
- `navigationTo` indexes start at 0. Negative, fractional, non-finite, or out-of-range indexes do not navigate. Full URLs support dynamic parameters, query, and hash; additional query parameters override matching URL parameters. Successful calls return the Router navigation Promise.
|
||||
- `useDomToImage` return types follow the default format or the current `create(format)` call. Failures reject with Error. `finally` also runs when the target is missing, so its argument may be empty. The `created` callback receives results from runtime format overrides as well; its argument is a union of actual output types and must be narrowed first.
|
||||
- `useI18n('hooks').t('code')` and `.t('hooks.code')` address the same translation key. Switch application locales with `useSettingActions().updateLocale` to keep dates and component-library locales synchronized.
|
||||
- Development HMR reuses the internationalization instance. Translation methods created before initialization read the current instance at invocation rather than permanently retaining the fallback that returns raw keys.
|
||||
- `usePagination` resets to the value of the first pageSizes option and supports Naive UI object options. Calling `setCallback()` removes the default callback.
|
||||
- `usePrint` unwraps its target when called. DOM targets print as HTML by default. Blob images and binary PDFs are converted first; callers can await the returned Promise.
|
||||
|
||||
截图和打印依赖实际浏览器。Happy DOM 测试验证状态与异常处理,不能替代原生打印界面或实际纸张输出验收。
|
||||
Screenshots and printing depend on real browsers. Happy DOM tests verify state and error handling; they do not replace native print-dialog or physical-output acceptance.
|
||||
|
||||
@ -1,24 +1,24 @@
|
||||
# 布局与自定义
|
||||
# Layout and customization
|
||||
|
||||
`RLayout` 保留现有 Vue 3 + TSX 结构、路由权限、菜单转换和页面缓存。访问 `/layout-demo` 或顶部设置抽屉的“布局”页签可即时预览配置。
|
||||
`RLayout` retains the existing Vue 3 + TSX structure, route permissions, menu conversion, and page caching. Preview configuration immediately at `/layout-demo` or the “布局” (Layout) tab in the top settings drawer.
|
||||
|
||||
## 导航与内容
|
||||
## Navigation and content
|
||||
|
||||
- `side`:完整侧边菜单。
|
||||
- `top`:完整顶部导航,Naive UI 处理横向溢出与子菜单。
|
||||
- `mixed`:顶部一级导航,侧栏显示当前一级菜单的可见子菜单;单页菜单不占侧栏空间。
|
||||
- `right`:完整侧边菜单放在内容右侧。
|
||||
- `split`:固定顶栏横跨全宽,左侧只显示当前分组的子菜单。关闭固定顶栏时,顶部导航随内容滚动。
|
||||
- ≤768px 自动使用完整菜单抽屉,不覆盖已保存的桌面模式。抽屉选中菜单后自动收起。
|
||||
- 侧栏与抽屉的 Logo 固定在菜单上方;滚动条从菜单区域开始。菜单设置中的原生滚动条开关只作用于菜单列表。
|
||||
- 内容支持流式铺满或定宽居中、640–2560px 最大宽度、0–48px 间距,以及顶栏/页脚固定或随内容滚动。标签和版权显隐沿用原设置。
|
||||
- 最大化内容区与页面、标签菜单共享 Pinia 状态。退出按钮浮在右上角,按 Esc 也可恢复。
|
||||
- 内容加载以可见滚动视口为基准。重新挂载立即显示提示,短时手动加载延迟 120ms 后显示。顶栏、标签栏和页脚固定时不被遮罩覆盖。
|
||||
- 「外观 → 页面切换动画」保留旧选项,并增加向上浮入和向左滑入。切换只动画化内容,系统启用减少动态效果时直接切换。
|
||||
- `side`: Complete sidebar menu.
|
||||
- `top`: Complete top navigation; Naive UI handles horizontal overflow and submenus.
|
||||
- `mixed`: First-level top navigation with visible children of the active group in the sidebar. Single-page menus do not occupy sidebar space.
|
||||
- `right`: Complete sidebar menu to the right of the content.
|
||||
- `split`: A fixed full-width top bar, with only the active group's children on the left. When the fixed top bar is disabled, top navigation scrolls with content.
|
||||
- At ≤768px, use the complete-menu drawer without overwriting saved desktop mode. Selecting a drawer item closes it automatically.
|
||||
- Sidebar/drawer logos remain fixed above the menu; scrolling begins at the menu region. The native-scrollbar option affects only the menu list.
|
||||
- Content supports fluid fill or centered fixed width, maximum widths of 640–2560px, spacing of 0–48px, and fixed or scrolling headers/footers. Tab and copyright visibility retain existing settings.
|
||||
- Maximized content shares Pinia state with pages and tab menus. An exit button floats at the top right; Esc restores the layout too.
|
||||
- Content loading uses the visible scrolling viewport. Remounting shows the indicator immediately; brief manual loading waits 120ms. Fixed headers, tabs, and footers are not covered by the overlay.
|
||||
- “外观 → 页面切换动画” (Appearance → Page transition) retains previous options and adds upward fade-in and leftward slide-in. Only content animates; reduced-motion system settings use immediate transitions.
|
||||
|
||||
交互借鉴 [Vben 的布局偏好设置](https://doc.vben.pro/en/guide/essentials/settings.html),复用现有 Naive UI 组件,不引入第二套布局框架。
|
||||
Interactions draw on [Vben layout preferences](https://doc.vben.pro/en/guide/essentials/settings.html), reusing existing Naive UI components without a second layout framework.
|
||||
|
||||
## 配置与扩展
|
||||
## Configuration and extension
|
||||
|
||||
```tsx
|
||||
import { useSettingActions } from '@/store'
|
||||
@ -32,11 +32,11 @@ updateSettingState('layoutConfig', {
|
||||
})
|
||||
```
|
||||
|
||||
配置属于 `setting` Store,沿用原有持久化 key;旧缓存自动补默认值并规范化范围,不清空用户偏好。`src/store/modules/setting/constant.ts` 管理默认值。恢复默认布局只重置 `layoutConfig`。
|
||||
Configuration belongs to the `setting` store and retains its persistence key. Historical caches receive defaults and normalized ranges without clearing user preferences. `src/store/modules/setting/constant.ts` owns defaults. Restoring the default layout resets only `layoutConfig`.
|
||||
|
||||
设置抽屉的五种布局预览固定一行,空间不足时可横向滚动。底部可将布局、外观、菜单、水印和通用偏好导出为 `ray-template-preferences.json`,或导入同格式文件。文件须通过版本和字段校验才会应用到当前浏览器,导入无需刷新。不包含登录、锁屏、路由配置或页面缓存数据。
|
||||
The settings drawer keeps its five layout previews in one row, scrolling horizontally if needed. Bottom controls export layout, appearance, menu, watermark, and general preferences as `ray-template-preferences.json`, or import the same format. Files must pass version/field validation before applying in the current browser; no reload is required. Login, lock-screen, route configuration, and page-cache data are excluded.
|
||||
|
||||
需要替换区域时使用具名插槽:
|
||||
Use named slots to replace regions:
|
||||
|
||||
```tsx
|
||||
<RLayout>
|
||||
@ -50,10 +50,10 @@ updateSettingState('layoutConfig', {
|
||||
</RLayout>
|
||||
```
|
||||
|
||||
插槽替换遵循当前模式与显隐设置:顶部导航模式无 sidebar,关闭标签/版权后不渲染相应区域。自定义内容需要自行处理请求取消与路由内容;未替换时沿用默认 Provider 和路由缓存。
|
||||
Replaced slots honor the current mode and visibility settings: top-navigation mode has no sidebar; disabled tabs/copyright do not render their regions. Custom content must handle request cancellation and routed content. Without replacement, the default providers and route cache remain active.
|
||||
|
||||
布局的内容滚动引用仍为 `LAYOUT_CONTENT_REF`,侧栏引用为 `LAYOUT_SIDER_REF`;`useContentScroll` / `useSiderScroll` 在执行时读取当前引用,支持模式切换与组件重新挂载。
|
||||
Layout scroll references remain `LAYOUT_CONTENT_REF` for content and `LAYOUT_SIDER_REF` for the sidebar. `useContentScroll` / `useSiderScroll` read the current reference when invoked, supporting mode changes and remounts.
|
||||
|
||||
## 样式归属
|
||||
## Style ownership
|
||||
|
||||
`index.scss` 负责布局外壳、内容滚动与最大化。顶部导航、菜单、标签栏和内容加载状态的样式随各自组件维护。设置抽屉与布局实验室共用 `LayoutSettings` 和 `LayoutSettings.scss`。方形选项卡片内的缩略图标出导航位置,卡片下方说明当前模式的菜单行为。卡片组为键盘焦点外框留出空间,选中状态由 `aria-pressed` 表示。
|
||||
`index.scss` owns the shell, content scrolling, and maximization. Top navigation, menus, tabs, and loading-state styles stay with their components. The settings drawer and layout lab share `LayoutSettings` and `LayoutSettings.scss`. Thumbnails within square option cards indicate navigation placement; text below explains menu behavior. Card groups reserve space for keyboard focus outlines, and `aria-pressed` represents selection.
|
||||
|
||||
@ -1,34 +1,34 @@
|
||||
## 国际化入口
|
||||
## Internationalization entry point
|
||||
|
||||
### 说明
|
||||
### Purpose
|
||||
|
||||
- 该文件入口为整个项目的入口文件
|
||||
- 二次封装 useI18n 方法、国际化文件入口、辅助方法等
|
||||
- 国际化配置文件格式都应该按照当前已约定格式进行拓展与使用
|
||||
- This entry point owns internationalization for the project.
|
||||
- It includes the wrapped useI18n API, locale-resource entry points, and helpers.
|
||||
- Extend and use locale configuration according to the established format.
|
||||
|
||||
### lang 文件入口说明
|
||||
### lang resource entry points
|
||||
|
||||
> 项目默认包含英文包与中文包,如果需要拓展应该按照当前格式进行拓展。每个文件识别为一个国际包语言包(会自动导入所有 json 文件作为语言包)。
|
||||
The project includes English and Chinese resources. Add languages using the same format. Each resource file identifies a locale; JSON resources are imported automatically.
|
||||
|
||||
#### 注意
|
||||
#### Format
|
||||
|
||||
> 该项目语言包使用 json 格式作为语言包管理格式,为了配合 `@intlify/unplugin-vue-i18n/vite` 插件,故而采用 json。
|
||||
Locale resources use JSON to work with `@intlify/unplugin-vue-i18n/vite`.
|
||||
|
||||
#### 拓展方法
|
||||
#### Adding a locale
|
||||
|
||||
- 配置语言包文件(文件名为语言包名称)
|
||||
- 配置文件入口(使用 `combineI18nMessages` 方法进行自动合并处理)
|
||||
- 语言包名称应该全局唯一
|
||||
- Add the resource file, named after the locale.
|
||||
- Configure its entry point using `combineI18nMessages` for automatic merging.
|
||||
- Keep locale names globally unique.
|
||||
|
||||
### helper 文件说明
|
||||
### Helpers
|
||||
|
||||
- `getAppLocalMessages` 获取系统所有语言包(该方法强制依赖 LOCAL_OPTIONS key 配置,意味着你在配置语言包的时候,key 必须与 `src/locales/lang/xxx.ts` 一一对应匹配)
|
||||
- `naiveLocales` 获取 `naive-ui` 组件库对应语言包文件
|
||||
- `getAppDefaultLanguage` 获取系统当前默认语言包
|
||||
- `getAppLocalMessages` returns all application locales. It depends on LOCAL_OPTIONS keys, which must correspond one-to-one with `src/locales/lang/xxx.ts` entries.
|
||||
- `naiveLocales` returns matching `naive-ui` locale resources.
|
||||
- `getAppDefaultLanguage` returns the application's current default locale.
|
||||
|
||||
### useI18n 文件说明
|
||||
### useI18n
|
||||
|
||||
> 二次封装 `i18n`,应该避免使用自带 `useI18n` 方法,使用系统提供方法。
|
||||
The application wraps `i18n`. Use that wrapper rather than the library's unwrapped `useI18n`.
|
||||
|
||||
- 支持 setup 环境外使用 `t`、`value` 方法
|
||||
- 其行为与官方方法一致
|
||||
- It supports `t` and `value` outside setup.
|
||||
- Its behavior otherwise follows the official API.
|
||||
|
||||
@ -1,23 +1,23 @@
|
||||
# 路由、菜单与权限
|
||||
# Routing, menus, and permissions
|
||||
|
||||
## 切换路由来源
|
||||
## Switching route sources
|
||||
|
||||
登录后,打开 **路由管理**。两个子页面均由应用外壳注册,使用相同的 `admin` 角色守卫。
|
||||
After login, open **路由管理** (Route management). Both child pages are registered by the application shell and use the same `admin` role guard.
|
||||
|
||||
- **可视化配置**(`/#/route-management/visual`):从当前生效的菜单树编辑页面、分组、重定向与外链,调整顺序、角色、显隐与缓存。可校验或导出草稿,也可应用并重新加载;通过标准接口保存并重新加载;Mock 数据库的修改仅在当前浏览器生效。已有别名、页面参数等高级字段会随草稿保留。
|
||||
- **JSON 配置**(`/#/route-management/json`):管理静态、本机或后端来源,编辑或导入完整 JSON、校验和预览配置树,并导出 JSON、标准 JSON Schema 和可用页面清单。旧地址 `/#/route-management` 会跳转到这里。
|
||||
- **可视化配置** (Visual configuration, `/#/route-management/visual`): Edit pages, groups, redirects, and external links from the active menu tree. Adjust order, roles, visibility, and caching. Validate/export drafts or apply and reload. Saving and reloading use the standard API; mock-database changes apply only to the current browser. Drafts preserve advanced fields such as existing aliases and page props.
|
||||
- **JSON 配置** (JSON configuration, `/#/route-management/json`): Manage static, browser-local, or backend sources. Edit/import full JSON, validate and preview the tree, and export JSON, standard JSON Schema, and available view IDs. The old `/#/route-management` URL redirects here.
|
||||
|
||||
| 来源 | 读取行为 | 应用方式 |
|
||||
| --------- | -------------------------------------------- | ------------------------------------------ |
|
||||
| 静态路由 | 读取 [modules](modules) 下的 TypeScript 模块 | 选择静态路由并应用 |
|
||||
| 本机 JSON | 读取当前浏览器保存的配置 | 导入文件或编辑 JSON,校验后应用 |
|
||||
| 后端接口 | 启动时请求部署配置 `VITE_ROUTE_CONFIG_URL` | 选择后端接口并应用。接口地址随前端部署配置 |
|
||||
| Source | Read behavior | Applying changes |
|
||||
| ------------- | ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
|
||||
| Static routes | Read TypeScript files under [modules](modules) | Select static routes and apply |
|
||||
| Local JSON | Read configuration saved in the current browser | Import a file or edit JSON, validate, then apply |
|
||||
| Backend API | Request deployment-configured `VITE_ROUTE_CONFIG_URL` at startup | Select the backend source and apply. The URL comes from frontend deployment configuration. |
|
||||
|
||||
应用时重新加载页面,重新生成路由匹配、菜单和标签页。设置接口地址时,新浏览器默认选择后端接口。显式选择的来源保存在当前浏览器。接口异常、超时或配置校验失败时恢复静态路由,管理页显示失败原因。登录、管理页、404 由外壳保留。未配置 `/dashboard` 时补充内置首页。
|
||||
Applying reloads the page and rebuilds route matching, menus, and tabs. With an API URL configured, a new browser defaults to the backend source. Explicit source choices are stored in the current browser. API errors, timeouts, or validation failures fall back to static routes and display the reason on the management page. The shell retains login, management, and 404 pages. An internal home page is added when `/dashboard` is absent.
|
||||
|
||||
## 后端与 AI 契约
|
||||
## Backend and AI contract
|
||||
|
||||
部署时提供 `VITE_ROUTE_CONFIG_URL=/api/route-config`,或使用启用 CORS 的 HTTPS 地址。客户端请求 `GET`,接受 `application/json`,超时 5 秒。同源请求可用会话 Cookie。标准接口把下方路由 JSON 放在 `{ code: 200, msg: "OK", data }` 的 `data` 中;导入和导出直接使用路由 JSON。旧的 `VITE_ROUTE_CONFIG_URL` 继续接受原始 JSON。完整读写接口见[服务端契约](../../../docs/guide/backend.md)。
|
||||
Set `VITE_ROUTE_CONFIG_URL=/api/route-config` at deployment, or use an HTTPS URL with CORS enabled. The client sends `GET`, accepts `application/json`, and times out after 5 seconds. Same-origin requests can use session cookies. Standard APIs place the route JSON below in `data` within `{ code: 200, msg: "OK", data }`; import/export uses route JSON directly. Legacy `VITE_ROUTE_CONFIG_URL` also accepts raw JSON. See the [backend contract](../../../docs/guide/backend.md) for the complete read/write API.
|
||||
|
||||
```json
|
||||
{
|
||||
@ -44,25 +44,26 @@
|
||||
}
|
||||
```
|
||||
|
||||
| 字段 | 规则 |
|
||||
| ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
|
||||
| `path`、`children` | 相对路径拼接到父组,绝对路径从根匹配。支持普通命名参数及可选参数,参数路由需设置 `hidden` 或 `sameLevel`。分组只参与菜单与权限 |
|
||||
| `name`、`component` | 名称唯一。页面只能引用 [注册表](config/views.ts) 中的 ID。开启 `keepAlive` 时名称与该页面组件名一致 |
|
||||
| `alias`、`redirect` | 支持叶子页的绝对别名和指向已配置页面的站内重定向。重定向的直接访问使用目标页权限 |
|
||||
| `props` | `true` 将路由参数传给页面,也可传入 JSON 对象 |
|
||||
| `meta.i18nKey`、`meta.noLocalTitle`、`meta.icon`、`meta.extra` | 翻译键优先于字面标题。图标使用 [IconName](../icons/manifest.ts)。标签可配置文案、翻译键、颜色、显隐及图标 |
|
||||
| `meta.role`、`meta.hidden`、`meta.env`、`meta.sameLevel` | 父组和叶子的角色限制同时生效。隐藏、环境和平级模式影响菜单。平级模式在当前标签下追加面包屑 |
|
||||
| `meta.keepAlive`、`meta.ignoreAutoResetScroll`、`meta.order`、`meta.windowOpen` | 控制叶子页缓存、滚动复位、顶层排序和 HTTP(S) 外部链接 |
|
||||
| Field | Rule |
|
||||
| ------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `path`, `children` | Relative paths append to the parent group; absolute paths match from the root. Ordinary named and optional parameters are supported. Parameterized routes need `hidden` or `sameLevel`. Groups participate only in menus and permissions. |
|
||||
| `name`, `component` | Names are unique. Pages may reference only IDs in the [registry](config/views.ts). With `keepAlive`, the route name must match the page component name. |
|
||||
| `alias`, `redirect` | Support absolute leaf-page aliases and internal redirects to configured pages. Direct access through redirects uses the target page's permissions. |
|
||||
| `props` | `true` forwards route params to the page; a JSON object is also supported. |
|
||||
| `meta.i18nKey`, `meta.noLocalTitle`, `meta.icon`, `meta.extra` | Translation keys take precedence over literal titles. Icons use [IconName](../icons/manifest.ts). Badges can configure text, translation keys, colors, visibility, and icons. |
|
||||
| `meta.role`, `meta.hidden`, `meta.env`, `meta.sameLevel` | Parent-group and leaf role restrictions both apply. Hidden, environment, and same-level settings affect menus. Same-level mode appends breadcrumbs under the current tab. |
|
||||
| `meta.keepAlive`, `meta.ignoreAutoResetScroll`, `meta.order`, `meta.windowOpen` | Control leaf caching, scroll reset, top-level order, and HTTP(S) external links. |
|
||||
|
||||
[JSON Schema](config/schema.ts) 描述字段,Valibot 从同一份定义推导类型并校验结构,导出时使用官方转换器生成 JSON Schema。[校验与转换](config/contract.ts) 额外验证页面 ID、图标、参数冲突、保留地址和重定向环。最多 300 个记录、8 层、256 KiB。函数、VNode、路由钩子等代码能力使用 TypeScript 模块。路由角色控制前端菜单与导航,后端仍需验证业务 API 权限。
|
||||
[JSON Schema](config/schema.ts) describes the fields. Valibot derives types and validates structure from the same definition; export uses the official JSON Schema converter. [Validation and conversion](config/contract.ts) additionally check view IDs, icons, parameter conflicts, reserved paths, and redirect loops. Limits are 300 records, 8 levels, and 256 KiB. Use TypeScript modules for executable features such as functions, VNodes, and route hooks. Roles control frontend menus/navigation; the backend must still authorize business APIs.
|
||||
|
||||
仓库内可直接导出 Schema 给后端或 AI 使用。
|
||||
Export the schema directly from the repository for backends or AI tools:
|
||||
|
||||
```sh
|
||||
node --input-type=module -e "import {getRouteJsonSchema} from './src/router/config/json-schema.ts'; console.log(JSON.stringify(getRouteJsonSchema(), null, 2))"
|
||||
```
|
||||
|
||||
## 扩展静态页面
|
||||
## Adding static pages
|
||||
|
||||
新增页面时先在 [页面注册表](config/views.ts) 注册稳定 ID 和组件名,再在 [Mock 初始 JSON](../mocks/data/routes.json) 或路由接口返回的数据里使用该 `component` ID。`name` 与缓存页面组件名保持一致。前端不再递归读取 TypeScript 菜单模块;初始 JSON 同时作为显式离线恢复来源。正常启动与编辑保存分别请求标准 GET/PUT 接口,简体中文和英文菜单文案仍放在两份 `menu.json`。
|
||||
系统配置和白名单见 [router-config.ts](../app-config/router-config.ts)。在 Vue setup 之外读取路由器时使用 `useVueRouter()`。变更后运行 `pnpm harness verify routing`,并核对菜单跳转、直达、刷新、切换来源、角色和缓存。
|
||||
Register a stable ID and component name in the [view registry](config/views.ts), then use that `component` ID in [initial mock JSON](../mocks/data/routes.json) or route API responses. Match `name` to the component name for cached views. The frontend no longer recursively reads TypeScript menu modules; initial JSON is also the explicit offline-recovery source. Normal startup and edited saves use standard GET/PUT endpoints respectively. Keep Simplified Chinese and English menu copy in the two `menu.json` files.
|
||||
|
||||
Application settings and allowlists are in [router-config.ts](../app-config/router-config.ts). Use `useVueRouter()` to read the router outside Vue setup. After changes, run `pnpm harness verify routing` and check menu navigation, direct access, reload, source switching, roles, and caching.
|
||||
|
||||
@ -1,16 +1,15 @@
|
||||
## 描述
|
||||
## Purpose
|
||||
|
||||
> 所有全局可变 UI 状态统一由 Pinia 管理,按用途分包,通过 `src/store/hooks` 暴露响应式 getters 和 actions。
|
||||
> Pinia owns all globally mutable UI state, grouped by responsibility. `src/store/hooks` exposes reactive getters and actions.
|
||||
|
||||
## 约束
|
||||
## Constraints
|
||||
|
||||
- 状态管理器应该按照其用途进行分包(见名知意)
|
||||
- 包名以用途名命名
|
||||
- 默认以 index.ts 作为入口,其余的辅助函数、类型,分别在该文件夹下进行补充(type.ts、helper.ts。。。)
|
||||
- 仓库使用 `piniaPluginPersistedstate` 作为中间件,用于缓存仓库数据避免刷新丢失(但是该方法有缺陷,不能缓存函数)
|
||||
- 默认不全部缓存参数,如果需要缓存参数,需要在 `defineStore` 第三个参数配置 `persist` 属性
|
||||
- `defineStore` 第一个参数必须全局唯一
|
||||
- 缓存插件 key 应该按照 `piniaXXXStore` 格式命名(XXX 表示该包名称)
|
||||
- Group stores by responsibility, using names that make their purpose clear.
|
||||
- Name each directory after its responsibility. Use index.ts as the default entry point and keep helpers/types in the same directory, such as type.ts and helper.ts.
|
||||
- The repository uses `piniaPluginPersistedstate` to retain store data across reloads; it cannot persist functions.
|
||||
- State is not persisted wholesale by default. Enable the needed fields through `persist` in the third `defineStore` argument.
|
||||
- The first `defineStore` argument must be globally unique.
|
||||
- Name persistence keys `piniaXXXStore`, where XXX is the store name.
|
||||
|
||||
```ts
|
||||
export const piniaDemoStore = defineStore(
|
||||
@ -35,7 +34,7 @@ export const piniaDemoStore = defineStore(
|
||||
)
|
||||
```
|
||||
|
||||
- 注册对应的 getters actions
|
||||
Register corresponding getters and actions:
|
||||
|
||||
```ts
|
||||
// piniaDemoStore
|
||||
@ -60,24 +59,24 @@ export const useMenuActions = () => {
|
||||
}
|
||||
```
|
||||
|
||||
- 最后在 index.ts 中暴露
|
||||
Expose them from index.ts:
|
||||
|
||||
```ts
|
||||
export { useDemoGetters, useMenuActions } from './modules/demo'
|
||||
```
|
||||
|
||||
- 使用
|
||||
Usage:
|
||||
|
||||
```ts
|
||||
import { useDemoGetters, useMenuActions } from '@/store'
|
||||
```
|
||||
|
||||
## 运行时状态与布局偏好
|
||||
## Runtime state and layout preferences
|
||||
|
||||
- `runtime`:全局加载、移动抽屉、页面刷新、内容最大化和内容加载动画。通过 `useRuntimeGetters` / `useRuntimeActions` 读取和修改;不持久化,应用卸载时释放 Store 与计时器。
|
||||
- `lock-screen`:锁屏状态也归入 Pinia,保留历史布尔值格式、缓存 key 与跨标签页同步。
|
||||
- `setting.layoutConfig`:布局模式、内容宽度与间距、顶栏和页脚固定方式。通过现有 `useSettingGetters` / `useSettingActions` 操作,使用原有设置缓存 key。旧缓存补默认值,不清空历史偏好。
|
||||
- 删除了独立的 `global-variable` 包;原五个状态名保留在 runtime 中,调用方改为 Store hooks。新增全局状态继续按用途放入 `src/store/modules`,不在普通模块创建共享 reactive 单例。
|
||||
- `runtime`: Global loading, mobile drawers, page refresh, content maximization, and content loading animations. Read/write through `useRuntimeGetters` / `useRuntimeActions`. Do not persist it; release the store and timers on application unmount.
|
||||
- `lock-screen`: Lock-screen state also belongs to Pinia. Preserve its historical boolean format, cache key, and cross-tab synchronization.
|
||||
- `setting.layoutConfig`: Layout mode, content width/spacing, and header/footer positioning. Use existing `useSettingGetters` / `useSettingActions` and the existing settings cache key. Add defaults to old caches without clearing historical preferences.
|
||||
- The separate `global-variable` module was removed. Its original five state names remain in runtime; callers use store hooks. Add global state by responsibility in `src/store/modules`, rather than creating shared reactive singletons in ordinary modules.
|
||||
|
||||
```ts
|
||||
import { useRuntimeActions, useRuntimeGetters } from '@/store'
|
||||
@ -89,14 +88,14 @@ setRuntimeState('globalSpinning', true)
|
||||
setRuntimeState('globalSpinning', false)
|
||||
```
|
||||
|
||||
布局用法和插槽见 [布局说明](../layout/README.md)。
|
||||
See the [layout guide](../layout/README.md) for usage and slots.
|
||||
|
||||
## 菜单同步
|
||||
## Menu synchronization
|
||||
|
||||
- 菜单树和路径索引在角色变化或显式刷新时构建,不修改模块中的原始路由。路由完成后用 Vue Router 已匹配的记录同步标签页和面包屑。
|
||||
- 保留原有缓存键和标签列表结构。恢复时按已注册路由和角色重建旧标签,忽略已经删除或不可访问的路由。只有标签列表变化时才写会话缓存。
|
||||
- KeepAlive 按最近访问顺序更新,去重并按上限裁剪。主题合并仅由生效主题驱动,色弱模式和文档标题独立监听。
|
||||
- Build menu trees and path indexes when roles change or during explicit refresh. Do not mutate original module routes. After navigation, synchronize tabs and breadcrumbs from Vue Router's matched records.
|
||||
- Preserve existing cache keys and tab-list structure. Restore historical tabs using registered routes and roles, ignoring deleted or inaccessible routes. Write the session cache only when the tab list changes.
|
||||
- Update KeepAlive in recent-access order, deduplicate, and trim to its limit. Merge themes only when the effective theme changes; observe color-weakness mode and document titles independently.
|
||||
|
||||
## 最近访问与收藏
|
||||
## Recent navigation and favorites
|
||||
|
||||
`navigation-history` 经 `useNavigationHistoryGetters` / `useNavigationHistoryActions` 暴露。按会话用户 id 隔离 Local Storage,只保存最多 10 个去重的最近菜单路径与收藏路径,不保存搜索词、标题、URL 查询参数或页面数据。显示和导航时从当前可见菜单重新解析,已撤权、隐藏或删除的路径不显示。切换账号即时清空内存视图并读取对应缓存;清空历史不删除收藏。
|
||||
Expose `navigation-history` through `useNavigationHistoryGetters` / `useNavigationHistoryActions`. Isolate Local Storage by session user id. Store up to 10 deduplicated recent menu paths and favorite paths, without search terms, titles, URL query parameters, or page data. Resolve display/navigation against currently visible menus; omit revoked, hidden, or deleted paths. Account switching immediately clears the in-memory view and reads the matching cache. Clearing history does not remove favorites.
|
||||
|
||||
@ -1,26 +1,26 @@
|
||||
# 公共工具
|
||||
# Shared utilities
|
||||
|
||||
`@/utils` 保留原有公开导出。实现和初始化链路应从所属子模块导入,避免加载无关依赖。
|
||||
`@/utils` preserves existing public exports. Implementations and initialization paths should import from the owning submodule to avoid loading unrelated dependencies.
|
||||
|
||||
| 入口 | 职责 | 代表性回归测试 |
|
||||
| ----------------------------- | --------------------------------------------------- | ----------------------------------------------------------------------------------------- |
|
||||
| `core` | 类型标签、PromiseLike、同步/异步错误处理、随机标识 | `__test__/basic` |
|
||||
| `files` | Data URL、文件读取、Blob/ArrayBuffer 下载与资源清理 | `__test__/basic/downloadAnyFile.spec.ts`、`__test__/utils-contracts/fileToBase64.spec.ts` |
|
||||
| `app`、`equal-router-path.ts` | 环境、操作系统、缓存键前缀、路由路径比较 | `__test__/app`、`__test__/basic` |
|
||||
| `cache.ts` | Web Storage 的 JSON 读写、命名空间和失败回退 | `__test__/cache` |
|
||||
| `element.ts` | DOM 类名、行内样式、查询、颜色和 CSS 尺寸 | `__test__/element` |
|
||||
| `dom.ts` | 截图后打开打印预览 | `__test__/dom` |
|
||||
| `vue` | 解包元素和组件根节点、渲染函数、回调与作用域清理 | `__test__/vue`、`__test__/utils-contracts/vue-target.spec.ts` |
|
||||
| `precision.ts` | 定点小数运算、分配与格式化 | `__test__/precision` |
|
||||
| `legacy-crypto` | 历史本地缓存的 AES JSON 格式 | `__test__/utils-contracts/legacy-crypto.spec.ts` |
|
||||
| 对象与日期选择器辅助方法 | 自有属性更新、浅拷贝、范围清空值 | `__test__/utils-contracts/object-date.spec.ts` |
|
||||
| Entry point | Responsibility | Representative regressions |
|
||||
| ------------------------------ | ------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------- |
|
||||
| `core` | Type tags, PromiseLike values, synchronous/asynchronous error handling, random identifiers | `__test__/basic` |
|
||||
| `files` | Data URLs, file reading, Blob/ArrayBuffer downloads, and resource cleanup | `__test__/basic/downloadAnyFile.spec.ts`, `__test__/utils-contracts/fileToBase64.spec.ts` |
|
||||
| `app`, `equal-router-path.ts` | Environment, operating system, cache-key prefixes, and route-path comparison | `__test__/app`, `__test__/basic` |
|
||||
| `cache.ts` | Web Storage JSON access, namespaces, and failure fallback | `__test__/cache` |
|
||||
| `element.ts` | DOM classes, inline styles, queries, colors, and CSS sizes | `__test__/element` |
|
||||
| `dom.ts` | Open print preview after capturing an image | `__test__/dom` |
|
||||
| `vue` | Unwrap elements/component roots, rendering functions, callbacks, and scope cleanup | `__test__/vue`, `__test__/utils-contracts/vue-target.spec.ts` |
|
||||
| `precision.ts` | Fixed-point decimal arithmetic, allocation, and formatting | `__test__/precision` |
|
||||
| `legacy-crypto` | Historical AES JSON format for local caches | `__test__/utils-contracts/legacy-crypto.spec.ts` |
|
||||
| Object and date-picker helpers | Own-property updates, shallow copying, and range-clearing values | `__test__/utils-contracts/object-date.spec.ts` |
|
||||
|
||||
`basic.ts` 和 `c/` 是旧导入路径的兼容入口。`@/utils/precision` 转发 `@ray-template/utils/precision`,实现位于 [packages/utils](../../../../packages/utils/src/precision.ts),供应用和文档共用。选中菜单定位实现在 `src/layout/utils`,由布局调用,历史工具入口继续转发。组件、Router 和 Store 自己的内部工具跟随所属模块维护。
|
||||
`basic.ts` and `c/` are compatibility entry points for old imports. `@/utils/precision` re-exports `@ray-template/utils/precision`, implemented in [packages/utils](../../../../packages/utils/src/precision.ts) and shared by the application/documentation. Selected-menu positioning lives in `src/layout/utils` and is called by layout; historical utility entry points still re-export it. Component, Router, and Store internal helpers stay with their owning modules.
|
||||
|
||||
- `isPromise` 判断值是否可等待;要判断函数是否声明为 `async`,使用 `isAsyncFunction`。错误包装会等待任意函数返回的 PromiseLike。
|
||||
- `uuid(length, radix)` 生成自定义标识,长度须为非负安全整数,基数须在 1 到 62。它不是 RFC UUID 格式。
|
||||
- 下载 Promise 表示已请求浏览器下载,无法感知磁盘写入是否完成。打印返回是否成功发起预览;纸张输出由浏览器负责。
|
||||
- `setStorage` 保留现有 JSON 和缓存键格式;读取失败返回指定的回退值,显式存入的 JSON `null` 仍是 `null`。配置前缀时,批量删除只作用于该前缀下的键。
|
||||
- `setClass`、`removeClass`、`hasClass`、`setStyle`、`removeStyle` 随元素引用更新;使用响应式目标时应在 Vue 作用域内创建。原生 `class` 属性变化本身不会触发 `hasClass` 重新计算。
|
||||
- `removeDuplicateKeys` 保留历史名称,返回对象自有可枚举属性的浅拷贝;同名键在创建 JavaScript 对象时已由最后一次赋值决定。 `updateObjectValue` 只更新自有属性,仅当新旧值均是普通对象时浅合并。
|
||||
- `legacy-crypto` 的字符串口令保留 OpenSSL 格式;原始密钥密文包含随机 IV。它是兼容层,模板的默认口令对客户端可见。
|
||||
- `isPromise` checks whether a value is awaitable. Use `isAsyncFunction` to check whether a function is declared `async`. Error wrappers await any PromiseLike returned by a function.
|
||||
- `uuid(length, radix)` creates custom identifiers. Length must be a nonnegative safe integer; radix must be from 1 to 62. This is not the RFC UUID format.
|
||||
- A download Promise means a browser download was requested; it cannot detect completion of disk writes. Printing reports whether preview was initiated successfully; the browser owns physical output.
|
||||
- `setStorage` preserves existing JSON and cache-key formats. Read failures return the specified fallback; an explicitly stored JSON `null` remains `null`. With a configured prefix, bulk deletion affects only keys with that prefix.
|
||||
- `setClass`, `removeClass`, `hasClass`, `setStyle`, and `removeStyle` follow element-reference updates. Create them within a Vue scope for reactive targets. Native `class` attribute changes alone do not recompute `hasClass`.
|
||||
- `removeDuplicateKeys` retains its historical name and returns a shallow copy of an object's own enumerable properties. Duplicate keys are already resolved by the last assignment when a JavaScript object is created. `updateObjectValue` updates only own properties and shallow-merges only when both old/new values are plain objects.
|
||||
- `legacy-crypto` string passphrases retain the OpenSSL format; raw-key ciphertext includes a random IV. This is a compatibility layer, and the template's default passphrase is visible to clients.
|
||||
|
||||
@ -1,10 +1,10 @@
|
||||
## 异常
|
||||
## Error pages
|
||||
|
||||
### 说明
|
||||
### Purpose
|
||||
|
||||
- 当前系统使用 Error404 作为系统的默认异常页重定向页面(可自行替换或者更改)
|
||||
- 提供公共的入口组件,虽然没啥大用,强迫症患者典型
|
||||
- The application uses Error404 as its default error redirect page. It can be replaced or changed.
|
||||
- A shared entry component is provided.
|
||||
|
||||
### 更改与替换
|
||||
### Changing or replacing pages
|
||||
|
||||
> 如果需要自己更改,或者补充更多的异常页面,可以在当前文件的 views 下补充(建议这么做哈)。也可以直接摒弃现有的东西,全部重新折腾一次,因为这个东西,一般不会太复杂。
|
||||
Add custom or additional error pages under this directory's views. The existing implementation may also be replaced if the application needs a different error-page design.
|
||||
|
||||
@ -1,12 +1,12 @@
|
||||
# Ray Template 文档
|
||||
# Ray Template documentation
|
||||
|
||||
[旧站](https://xiaodaigua-ray.github.io/ray-template-doc/) · [模板源码](https://github.com/XiaoDaiGua-Ray/ray-template) · [在线演示](https://xiaodaigua-ray.github.io/ray-template/)
|
||||
[Legacy site](https://xiaodaigua-ray.github.io/ray-template-doc/) · [Template source](https://github.com/XiaoDaiGua-Ray/ray-template) · [Live demo](https://xiaodaigua-ray.github.io/ray-template/)
|
||||
|
||||
从同级文档仓库的本地提交 `e01751223cc91f9288484f6e7f50481b9482261d` 导入站点。旧正文可在[历史版本](https://github.com/XiaoDaiGua-Ray/ray-template-doc/tree/0cae0e4334b16df22d491401c190360af4819025)查阅。
|
||||
Imported from local commit `e01751223cc91f9288484f6e7f50481b9482261d` in the sibling documentation repository. The previous content remains available in the [historical version](https://github.com/XiaoDaiGua-Ray/ray-template-doc/tree/0cae0e4334b16df22d491401c190360af4819025).
|
||||
|
||||
## 本地开发
|
||||
## Local development
|
||||
|
||||
在 Ray Template 仓库根目录执行。Node 和 pnpm 以 `.nvmrc` 和根 `package.json` 为准。
|
||||
Run these commands from the Ray Template repository root. Use the Node and pnpm versions specified in `.nvmrc` and the root `package.json`.
|
||||
|
||||
```sh
|
||||
pnpm install --frozen-lockfile
|
||||
@ -15,16 +15,16 @@ pnpm docs:check
|
||||
pnpm docs:preview
|
||||
```
|
||||
|
||||
按终端地址访问 `/ray-template/docs/`。`pnpm docs:check` 验证示例类型、站内链接和生产构建,产物位于 `apps/docs/.vitepress/dist`。`pnpm check` 包含此检查。生产部署使用根目录的 `pnpm pages:build`,在 `dist/pages/docs` 生成文档。指定 `RAY_TEMPLATE_SITE_ORIGIN` 后还会生成 `dist/legacy-docs`,作为原文档站的跳转产物。
|
||||
Open `/ray-template/docs/` at the address printed in the terminal. `pnpm docs:check` checks example types, internal links, and the production build. Output goes to `apps/docs/.vitepress/dist`. `pnpm check` includes this check. For production deployment, run `pnpm pages:build` from the root; it generates documentation under `dist/pages/docs`. Setting `RAY_TEMPLATE_SITE_ORIGIN` also generates `dist/legacy-docs` for redirects from the previous documentation site.
|
||||
|
||||
- `guide/`:上手、开发和部署任务。
|
||||
- `migration.md`:旧写法、新写法、兼容边界和验证方法。
|
||||
- `reference/`:组件、Hooks、Store、指令、工具和配置的 API 参考。
|
||||
- `examples/`:页内交互使用的 Vue 源文件,Markdown 直接引用同一文件展示代码。
|
||||
- `.vitepress/`:主题、导航和旧路径映射。迁址保留的相对路径会在生产构建生成跳转页。
|
||||
- `guide/`: Getting started, development, and deployment tasks.
|
||||
- `migration.md`: Previous and current usage, compatibility boundaries, and verification methods.
|
||||
- `reference/`: API references for components, hooks, stores, directives, utilities, and configuration.
|
||||
- `examples/`: Vue source for interactive examples; Markdown displays code from those same files.
|
||||
- `.vitepress/`: Theme, navigation, and legacy path mappings. Production builds generate redirect pages for preserved legacy relative paths.
|
||||
|
||||
应用变更影响公开 API 时,同步更新对应文档和示例。示例直接使用 workspace 包的公开入口。外壳预览使用文档自己的内存路由和示例菜单。预览生产构建,检查导航、搜索、主题、窄屏、旧路径和受影响示例。
|
||||
When application changes affect public APIs, update the corresponding documentation and examples. Examples use public workspace package entry points. Shell previews have their own in-memory router and example menus. Follow the [documentation workflow](../../docs/docs-handoff.md#update-workflow) to check affected content. Verify navigation, search, themes, narrow layouts, legacy paths, and interactions only when they change; use production previews for production paths and release verification.
|
||||
|
||||
轻量示例直接在文档中运行。依赖后台上下文的示例嵌入同一版本的 `example.html`,只注册演示路由,普通缓存和 Store 状态留在该示例实例;TablePro 列显隐缓存使用独立的会话命名空间,允许在同一标签页刷新验证。Markdown 从实际运行的文件引用源码。开发时同时运行 `pnpm dev` 和 `pnpm docs:dev`;后台端口不是 9527 时,为文档开发服务器设置 `VITE_RAY_EXAMPLE_ORIGIN`(例如 `http://127.0.0.1:9528`)。
|
||||
Lightweight examples run directly in the documentation. Examples that need the admin application context embed `example.html` from the same version, register only demo routes, and keep ordinary cache and store state within the example instance. TablePro column visibility uses a separate session namespace so it can be checked across reloads in the same tab. Markdown includes source from the file actually running. During development, run both `pnpm dev` and `pnpm docs:dev`. If the admin server uses a port other than 9527, set `VITE_RAY_EXAMPLE_ORIGIN` for the documentation server, for example `http://127.0.0.1:9528`.
|
||||
|
||||
验收全部示例请运行 `pnpm pages:build`,然后用 `pnpm preview --outDir ../../dist/pages` 在同一地址预览后台和文档,打开 `/ray-template/docs/`。只运行 `pnpm docs:preview` 时,可预览文档和直接运行的轻量示例。
|
||||
To verify embedded admin examples or the combined deployment, run `pnpm pages:build`, then `pnpm preview --outDir ../../dist/pages`. Open `/ray-template/docs/` at that shared address and exercise only affected examples. Expand to all examples for a release or an explicit request. `pnpm docs:preview` alone previews the documentation and its directly hosted lightweight examples.
|
||||
|
||||
@ -8,7 +8,7 @@
|
||||
| `pnpm dev` | 同步图标清单并启动 Vite |
|
||||
| `pnpm harness context` | 查任务域;追加 `routing`、`table-pro`、`docs` 等查看实现与验证 |
|
||||
| `pnpm harness verify table-pro` | 按域运行定向测试或项目检查 |
|
||||
| `pnpm harness verify` | 运行全量检查并生成本地报告 |
|
||||
| `pnpm harness verify all` | 集成风险或发布时运行全量检查并生成本地报告 |
|
||||
| `pnpm typecheck` | 验证图标清单,检查应用、Node 配置和测试类型 |
|
||||
| `pnpm dev-build` / `pnpm report` | 构建开发版,或输出静态打包报告 |
|
||||
| `pnpm build` / `pnpm preview` | 构建并在本机验收产物 |
|
||||
@ -18,7 +18,11 @@
|
||||
| `pnpm docs:check` | 验证文档示例类型、站内链接与生产构建 |
|
||||
| `pnpm docs:preview` | 预览已构建的文档站 |
|
||||
|
||||
全量检查包含环境、Harness、图标同步、类型、ESLint、Prettier、Vitest 和生产构建。Harness 在 `.harness-local/runs/` 写结果;Chrome 验收单独记录。改动交互或布局时,额外验收中英文、明暗主题和窄屏。
|
||||
日常修改先运行相关测试文件或 `pnpm harness verify <scope>`,再根据改动补充格式、ESLint 和类型检查。纯措辞、注释或维护文档修正可只检查内容和格式;索引变化加 `pnpm harness check`。依赖、公共导出、构建配置等集成风险、发布或明确要求时,才在任务收尾运行一次全量检查。CI 保持 `pnpm check`。
|
||||
|
||||
全量检查包含环境、Harness、API 与包边界、图标同步、类型、ESLint、Prettier、Vitest,以及后台和文档构建。`pnpm harness verify` 省略 scope 时仍执行全量,日常使用应显式指定 scope。Harness 在 `.harness-local/runs/` 写命令结果,所有命令均不启动浏览器。
|
||||
|
||||
浏览器验收按影响范围单独记录:交互变化只操作对应页面,布局变化增加桌面和窄屏,颜色变化增加明暗主题,文案或国际化变化核对中英文。共享能力选择有差异的代表调用方;纯逻辑、维护文档和读者文档纯措辞修正无需浏览器。检查通过后,只重跑受后续修改影响的部分,无需遍历页面、语言、主题和视口的所有组合。
|
||||
|
||||
## 部署到子路径
|
||||
|
||||
|
||||
@ -1,64 +1,64 @@
|
||||
# 架构地图
|
||||
# Architecture map
|
||||
|
||||
Ray Template 是一个 pnpm workspace:后台负责宿主集成,文档站解释公开用法,共享包拥有可复用实现。按功能定位文件从[任务索引](../llms.txt)进入;本页用于判断代码归属和追踪跨模块调用。
|
||||
Ray Template is a pnpm workspace. The admin application owns host integration, the documentation site explains public usage, and shared packages own reusable implementations. Use the [task index](../llms.txt) to locate features. Use this page to identify ownership and trace calls across modules.
|
||||
|
||||
## 工作区
|
||||
## Workspaces
|
||||
|
||||
| 目录 | 职责与权威入口 |
|
||||
| ----------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
|
||||
| [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 配置。 |
|
||||
| Directory | Responsibility and authoritative entry point |
|
||||
| ----------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| [apps/admin](../apps/admin) | Ray Admin: application configuration, route registration, Pinia, providers, pages, demo data, and development mocks. This is Vite's application root. |
|
||||
| [apps/docs](../apps/docs/README.md) | VitePress site: reader guides, APIs, migration instructions, and interactive examples consuming public shared-package entry points. |
|
||||
| [packages](../packages) | Shared packages listed below. Each package's `package.json#exports` defines its root entry point and importable subpaths. |
|
||||
| [Tests](../__test__) | Vitest regressions grouped by behavior rather than mirroring the source tree. Use [Harness scopes](../harness/scopes.json) to locate coverage. |
|
||||
| [docs](./), [harness](../harness/README.md) | Maintainer conventions and cross-module explanations. Harness owns task navigation, targeted checks, and evidence. Reader-facing documentation belongs in `apps/docs`. |
|
||||
| [scripts](../scripts), [vite-helper](../vite-helper), [unplugin](../unplugin) | Repository checks, Vite plugin helpers, and generated auto-import declarations. Build, type, and CI configuration remains at the root. |
|
||||
|
||||
| 共享包 | 实现归属 | 宿主边界 |
|
||||
| --------------------------------------------------------------------- | ---------------------------------------------- | --------------------------------------------------------------- |
|
||||
| [@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/api-contracts](../packages/api-contracts/package.json) | 业务与演示接口的类型、运行时 Schema、OpenAPI | 不依赖浏览器或 Mock;应用、Mock 与接入方服务端共享协议。 |
|
||||
| [@ray-template/routing](../packages/routing/package.json) | 路由配置校验、路由展开和菜单遍历 | 应用持有页面注册表、配置来源、角色、会话和守卫。 |
|
||||
| [@ray-template/admin-shell](../packages/admin-shell/package.json) | 布局外壳、布局设置、过渡与页面缓存渲染 | 宿主提供路由状态、偏好、导航和内容插槽。 |
|
||||
| Shared package | Implementation ownership | Host boundary |
|
||||
| --------------------------------------------------------------------- | --------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| [@ray-template/utils](../packages/utils/package.json) | Precision, type checks, data/file utilities, and generic JSON storage | Callers supply Storage. Application keys, cache backends, and legacy AES formats stay in the application. |
|
||||
| [@ray-template/composables](../packages/composables/package.json) | Vue composables and DOM, element, and scope utilities | Application-specific navigation, theme, and content-area hooks stay in the application. |
|
||||
| [@ray-template/directives](../packages/directives/package.json) | Vue directives and registration | The host supplies copy notifications and decides when to register. |
|
||||
| [@ray-template/icons](../packages/icons/package.json) | SVG files, manifests, icon-name types, and lookups | The build generates spritemaps. The host supplies icon-resolution services. |
|
||||
| [@ray-template/ui](../packages/ui/package.json) | Shared components, themes, and UI service interfaces | The admin application injects translation, theme, storage, and other services. Application component entry points re-export shared components. |
|
||||
| [@ray-template/http](../packages/http/package.json) | Independent HTTP clients, interceptors, and cancellation | The application supplies request configuration and interceptors, and wraps business APIs. |
|
||||
| [@ray-template/api-contracts](../packages/api-contracts/package.json) | Business/demo API types, runtime schemas, and OpenAPI | Independent of browsers and mocks. The application, mocks, and integrating backends share the protocol. |
|
||||
| [@ray-template/routing](../packages/routing/package.json) | Route configuration validation, expansion, and menu traversal | The application owns the view registry, configuration sources, roles, sessions, and guards. |
|
||||
| [@ray-template/admin-shell](../packages/admin-shell/package.json) | Layout shell, settings, transitions, and cached-page rendering | The host supplies route state, preferences, navigation, and content slots. |
|
||||
|
||||
应用侧 `@/components`、`@/hooks`、`@/utils` 有兼容入口。跟随实际导出判断实现归属。共享包不可依赖后台别名或跨 workspace 相对导入;[包边界检查](../scripts/check-package-boundaries.mjs)校验依赖声明、公开入口和循环依赖。
|
||||
Application `@/components`, `@/hooks`, and `@/utils` include compatibility entry points. Follow actual exports to determine ownership. Shared packages must not depend on application aliases or relative imports across workspaces. The [package-boundary check](../scripts/check-package-boundaries.mjs) validates dependency declarations, public entry points, and cycles.
|
||||
|
||||
## 关键运行链路
|
||||
## Key runtime flows
|
||||
|
||||
| 链路 | 调用顺序与边界 | 继续阅读 |
|
||||
| -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
|
||||
| 后台启动 | [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)。开发与静态在线演示共用 HTTP Mock,用户、会话与路由由接口读写;真实会话和资源授权由接入方后端负责。 | [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) |
|
||||
| Flow | Call order and boundaries | Continue with |
|
||||
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------- |
|
||||
| Admin bootstrap | [index.html](../apps/admin/index.html) → [main.ts](../apps/admin/src/main.ts) → Pinia → internationalization → Router → Day.js → directives and autocomplete settings → mount [App.tsx](../apps/admin/src/App.tsx). Standalone and Wujie modes share plugin registration order. | [Layout and bootstrap](../harness/context/layout.md) |
|
||||
| Navigation and caching | [Router initialization](../apps/admin/src/router/index.ts) loads the source → [application route modules](../apps/admin/src/router/app-route-modules.ts) expand configuration → guards and pages are registered → application menu stores and layouts consume routes. The application maintains the cache allowlist; the shared shell renders transitions and KeepAlive. | [Routing](../harness/context/routing.md), [layout](../harness/context/layout.md) |
|
||||
| Requests and demo data | [API](../apps/admin/src/api) → [application Axios instance](../apps/admin/src/axios/instance.ts) → [shared client](../packages/http/src/client.ts). Development and static online demos share HTTP mocks. Users, sessions, and routes are read/written through APIs; integrating backends own real sessions and resource authorization. | [API](../harness/context/api.md) |
|
||||
| Documentation examples | Documentation can consume shared packages directly. When application context is required, [AdminExample.vue](../apps/docs/examples/AdminExample.vue) embeds [example.html](../apps/admin/example.html) with isolated bootstrap, restricted routes, and in-memory caching. | [Documentation and examples](../harness/context/docs.md) |
|
||||
| Application configuration | [Vite](../vite.config.ts) injects `__APP_CFG__` and `__DEV__`; [application configuration](../apps/admin/src/app-config) is grouped by design, requests, routing, and caching. | [Build and toolchain](../harness/context/toolchain.md) |
|
||||
|
||||
公开行为变更按[应用与文档联动](docs-handoff.md)维护指南和可运行示例。页面排版见[视觉与排版](ui-design.md);代码注释见[注释规范](comment-style.md)。
|
||||
Maintain guides and runnable examples for public behavior changes through [application/documentation coordination](docs-handoff.md). See [visual and layout guidance](ui-design.md) for page design and [comment style](comment-style.md) for code comments.
|
||||
|
||||
## TypeScript 项目配置
|
||||
## TypeScript project configuration
|
||||
|
||||
[根配置](../tsconfig.json)引用四个项目。严格模式、模块解析和类型检查别名集中在[共享配置](../tsconfig.base.json)。调整路径别名时同步核对 [Vite](../vite.custom.config.ts) 和 [Vitest](../vitest.config.ts)。
|
||||
The [root configuration](../tsconfig.json) references four projects. Strict mode, module resolution, and type-checking aliases live in the [shared configuration](../tsconfig.base.json). When changing aliases, check [Vite](../vite.custom.config.ts) and [Vitest](../vitest.config.ts) as well.
|
||||
|
||||
| 配置 | 检查范围 |
|
||||
| ------------------------------------ | ----------------------------------------------------------------------------------------- |
|
||||
| [应用](../tsconfig.app.json) | 后台 `apps/admin/src`、Vue JSX 和生成声明。 |
|
||||
| [Node](../tsconfig.node.json) | 根构建与测试配置、`vite-helper`、构建辅助。 |
|
||||
| [测试](../tsconfig.test.json) | `__test__` 与引用源码,加载 Vitest 和 Node 类型。运行时环境由 Vitest 配置及测试文件决定。 |
|
||||
| [共享包](../tsconfig.packages.json) | `packages/*/src`,不继承应用别名或自动导入声明。 |
|
||||
| [文档站](../apps/docs/tsconfig.json) | 独立检查文档示例,由 `pnpm docs:check` 执行。 |
|
||||
| Configuration | Coverage |
|
||||
| ------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| [Application](../tsconfig.app.json) | Admin `apps/admin/src`, Vue JSX, and generated declarations. |
|
||||
| [Node](../tsconfig.node.json) | Root build/test configuration, `vite-helper`, and build helpers. |
|
||||
| [Tests](../tsconfig.test.json) | `__test__` and referenced source, loading Vitest and Node types. Vitest configuration and individual test files determine the runtime environment. |
|
||||
| [Shared packages](../tsconfig.packages.json) | `packages/*/src`, without inheriting application aliases or auto-import declarations. |
|
||||
| [Documentation site](../apps/docs/tsconfig.json) | Independent documentation-example checks, run by `pnpm docs:check`. |
|
||||
|
||||
`pnpm typecheck` 先检查图标同步,再通过 `vue-tsc --build` 检查根配置引用的四个项目;增量缓存位于 `node_modules/.cache/ray-template/`。单独检查可使用 `pnpm exec vue-tsc -p <配置文件>`。
|
||||
`pnpm typecheck` first validates icon synchronization, then runs `vue-tsc --build` for the four projects referenced by the root configuration. Incremental caches live in `node_modules/.cache/ray-template/`. Use `pnpm exec vue-tsc -p <configuration-file>` for an individual project.
|
||||
|
||||
## Deployment and search discovery
|
||||
|
||||
`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)。
|
||||
`pnpm build` produces admin output in `dist/production`; `pnpm docs:build` produces `apps/docs/.vitepress/dist`. `pnpm pages:build` combines them in `dist/pages`, with documentation under `docs/`. The default admin base is `/ray-template/`; the documentation base is `/ray-template/docs/`. For root hosting or another subpath, align the [admin base](../vite.custom.config.ts), [documentation base](../apps/docs/.vitepress/config.mts), and [legacy redirect targets](../scripts/assemble-pages.mjs).
|
||||
|
||||
[CI](../.github/workflows/ci.yaml)在主分支检查通过后将组合产物发布到 `dist` 分支。[后台 public 中的 .nojekyll](../apps/admin/public/.nojekyll)会随产物复制;手动部署到 Pages 时保留它,以便加载带下划线前缀的资源。
|
||||
After main-branch checks pass, [CI](../.github/workflows/ci.yaml) publishes the combined output to the `dist` branch. The [admin public .nojekyll file](../apps/admin/public/.nojekyll) is copied into the output. Preserve it when deploying manually to Pages so assets with underscore prefixes can load.
|
||||
|
||||
公开构建用 `RAY_TEMPLATE_SITE_ORIGIN` 配置实际站点源地址,路径由 base 提供。未设置时,后台生产构建输出 `noindex`。公开后台首页生成 canonical、分享预览和 `sitemap.xml`,不把登录后的 hash 路由列为公开页面。域名级抓取规则由站点根目录的 `/robots.txt` 管理。站内旧链接由 [VitePress 映射](../apps/docs/.vitepress/legacy.mts)生成;配置站点源地址时,合并脚本另生成 `dist/legacy-docs`,供旧站迁移使用。
|
||||
For public builds, set `RAY_TEMPLATE_SITE_ORIGIN` to the actual site origin; the base supplies the path. Without it, admin production builds emit `noindex`. The public admin landing page generates canonical metadata, sharing previews, and `sitemap.xml`; authenticated hash routes are not listed as public pages. Domain-level crawling rules belong in `/robots.txt` at the site root. [VitePress mappings](../apps/docs/.vitepress/legacy.mts) generate legacy in-site links. When a site origin is configured, the assembly script also generates `dist/legacy-docs` for migrating the old site.
|
||||
|
||||
只阅读已跟踪的源码和配置来判断实现。生成产物、依赖、缓存和 `.harness-local/` 报告适合查构建与验证结果。
|
||||
Establish implementation behavior from tracked source and configuration. Generated artifacts, dependencies, caches, and `.harness-local/` reports are useful for inspecting build and verification results.
|
||||
|
||||
@ -1,23 +1,23 @@
|
||||
# 注释规范
|
||||
# Comment style
|
||||
|
||||
本规范适用于本仓库的 TypeScript、JavaScript、TSX/JSX、脚本与配置。新增或修改注释时必须遵循;不为自解释代码机械补注释。参考用户指定的统一注释风格,按 Ray Template 的组件与模块边界调整。
|
||||
These conventions apply to TypeScript, JavaScript, TSX/JSX, scripts, and configuration in this repository. Follow them when adding or editing comments; do not mechanically annotate self-explanatory code. They adapt the user's requested common style to Ray Template's component and module boundaries.
|
||||
|
||||
## 组件与文件说明
|
||||
## Component and file descriptions
|
||||
|
||||
- 不在文件顶部、`defineComponent` 前或函数组件声明前添加多行介绍性注释。组件职责、继承关系、用法与示例放在相应 README;非显然约束放在实际受影响的位置。
|
||||
- 不把文件介绍移动到第一个函数、常量或导出对象前。注释必须描述紧邻声明的真实契约,不能借换位置保留整段文件说明。
|
||||
- 同一个声明只保留一份契约说明,禁止连续堆叠多个 JSDoc 块。
|
||||
- Do not add multi-line introductory comments at the top of a file, before `defineComponent`, or before a function-component declaration. Put component responsibilities, inheritance, usage, and examples in the corresponding README. Place non-obvious constraints next to the affected code.
|
||||
- Do not move a file introduction in front of the first function, constant, or exported object. A comment must describe the actual contract of the adjacent declaration; changing its location does not justify keeping an unrelated file overview.
|
||||
- Keep one contract description per declaration. Do not stack consecutive JSDoc blocks for the same declaration.
|
||||
|
||||
## 函数与方法契约
|
||||
## Function and method contracts
|
||||
|
||||
确有需要说明参数、资源所有权、副作用、异步归属或失败语义时,使用多行 JSDoc。参数、返回值以实际签名与实现为准。
|
||||
Use multi-line JSDoc when parameters, resource ownership, side effects, asynchronous ownership, or failure semantics need explanation. Parameters and return values must match the actual signature and implementation.
|
||||
|
||||
1. 使用独立的 `/**` 和 ` */`,内部每行以 ` *` 开头,并与被说明的声明对齐。
|
||||
2. 开头先放一行仅含 ` *` 的空白注释行;区段之间也使用这样的空白行,不保留行尾空格。
|
||||
3. 标签按 `@param` → `@description` → `@returns` → `@throws` 排列,仅保留需要的区段。
|
||||
4. 有参数时按签名顺序列出真实参数名与含义;多个 `@param` 连续排列。无参数时省略参数区。
|
||||
5. `@description` 独占一行,正文从下一行开始,不在标签前重复写一段函数介绍。
|
||||
6. `void`、`Promise<void>` 和构造函数不写 `@returns`;副作用放在描述区。`@throws` 只描述调用方可观察的抛出或 Promise 拒绝。
|
||||
1. Put `/**` and ` */` on separate lines. Begin each interior line with ` *` and align the block with its declaration.
|
||||
2. Start with a blank comment line containing only ` *`. Use the same blank line between sections; do not leave trailing spaces.
|
||||
3. Order tags as `@param` → `@description` → `@returns` → `@throws`. Include only necessary sections.
|
||||
4. List actual parameter names and meanings in signature order. Keep consecutive `@param` entries together; omit the section when there are no parameters.
|
||||
5. Put `@description` on its own line and start its text on the next line. Do not repeat a summary before the tags.
|
||||
6. Do not add `@returns` for `void`, `Promise<void>`, or constructors. Describe side effects in the description. `@throws` covers only exceptions or Promise rejections observable by callers.
|
||||
|
||||
```ts
|
||||
/**
|
||||
@ -32,14 +32,14 @@ const reload = (wait = 800) => {
|
||||
}
|
||||
```
|
||||
|
||||
公开 Hook 的完整示例优先放在 README 与可运行示例页,不在函数前堆放长篇教程。历史 `@example` 不应在无关任务中机械删除;本次修改契约时应同步核对它是否仍准确。
|
||||
Put complete public-hook examples in READMEs and runnable demo pages rather than lengthy tutorials before functions. Do not mechanically remove historical `@example` blocks during unrelated work. When changing a contract, check that its existing examples remain accurate.
|
||||
|
||||
## 声明与逻辑说明
|
||||
## Declaration and implementation notes
|
||||
|
||||
- 模块级常量、变量、类字段和类型属性的简短说明使用单行 JSDoc `/** 说明 */`,不加标签。
|
||||
- 类、接口或类型确需说明整体职责时,使用带开头空白行的多行 JSDoc,正文放在独占一行的 `@description` 后,不虚构参数或返回值。
|
||||
- 函数内部的分支、局部变量、执行顺序和原因说明使用 `//`;多行逻辑说明逐行写 `//`,不套用函数契约格式。
|
||||
- 注释用中文解释非显然的原因与约束,技术标识符保留原名。避免逐行复述、作者闲谈、过时行为和没有实现依据的保证。
|
||||
- Use single-line JSDoc, such as `/** 说明 */`, for short descriptions of module constants, variables, class fields, and type properties. Do not add tags.
|
||||
- When a class, interface, or type needs an overall description, use multi-line JSDoc with an initial blank comment line. Put the description after a standalone `@description` tag. Do not invent parameters or return values.
|
||||
- Use `//` inside functions for branches, local variables, ordering, and rationale. Prefix each line of a multi-line implementation note with `//`; do not use a function-contract block.
|
||||
- Write code comments in Chinese to explain non-obvious reasons and constraints, retaining technical identifiers. Avoid line-by-line narration, author chatter, obsolete claims, and guarantees unsupported by the implementation.
|
||||
|
||||
```ts
|
||||
/** 内容区恢复前的默认等待时间,单位为毫秒 */
|
||||
@ -51,6 +51,6 @@ const update = () => {
|
||||
}
|
||||
```
|
||||
|
||||
许可证、来源归属、生成标记和工具指令保留其必要语法,例如 `// @ts-expect-error`、`/// <reference ... />`、`/* @__PURE__ */`。JSX 子节点使用 `{/* 说明 */}`;HTML、CSS 使用各自合法的定界符。
|
||||
Preserve required syntax for licenses, attribution, generated markers, and tool directives, such as `// @ts-expect-error`, `/// <reference ... />`, and `/* @__PURE__ */`. Use `{/* 说明 */}` in JSX children and valid comment delimiters for HTML and CSS.
|
||||
|
||||
交付前检查注释位置、是否堆叠、参数名、标签顺序和内容真实性。注释规范不替代 ESLint、Prettier、类型检查或浏览器验收。
|
||||
Before delivery, check placement, duplicate blocks, parameter names, tag order, and factual accuracy. These conventions do not replace applicable ESLint, Prettier, type, or browser checks.
|
||||
|
||||
@ -1,28 +1,30 @@
|
||||
# 应用与文档联动
|
||||
# Application and documentation coordination
|
||||
|
||||
读者指南、迁移步骤和 API 参考在 [apps/docs](../apps/docs/README.md) 维护。VitePress 与应用共用 workspace 锁文件,从同一工作区加载交互示例。旧站内容和历史保留在 [ray-template-doc](https://github.com/XiaoDaiGua-Ray/ray-template-doc)。
|
||||
Maintain reader guides, migration instructions, and API references in [apps/docs](../apps/docs/README.md). VitePress and the application share the workspace lockfile and load interactive examples from the same workspace. Previous site content and history remain in [ray-template-doc](https://github.com/XiaoDaiGua-Ray/ray-template-doc).
|
||||
|
||||
官网当前面向 v6,源码链接使用 Monorepo 路径,发布构建时用 `RAY_TEMPLATE_SOURCE_REF` 固定到发布提交。页内示例随工作区源码构建。v5 的源码与发布标签见[版本分界](../apps/docs/migration.md)。
|
||||
The site targets v6. Source links use monorepo paths, and release builds use `RAY_TEMPLATE_SOURCE_REF` to pin links to the release commit. Inline examples build against workspace source. See the [version boundary](../apps/docs/migration.md) for v5 source and release tags.
|
||||
|
||||
| 领域 | 应用侧证据 | 必须交代的边界 |
|
||||
| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| 组件入口与 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)、[标准业务 API](../apps/admin/src/api/admin/index.ts) | 实例成功返回 body,失败拒绝;调用方传 signal 时关闭模板的默认 signal 注入。开发与静态在线演示共用 MSW HTTP Mock;关闭 Mock 后直接连接标准服务端接口。 |
|
||||
| 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/`。 |
|
||||
| Area | Application evidence | Boundaries to explain |
|
||||
| ----------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| Component entry points and TablePro | [Public exports](../apps/admin/src/components/index.ts), [TablePro contract](../packages/ui/src/RTablePro/README.md), [table examples](../apps/admin/src/views/demo/tables) | Deep `base/` and `pro/` paths are obsolete; `RTable` and `useTable` were removed. `useTablePro` retains registration-style usage and exposes `isReady` and current-page data access. Remote `total` counts filtered records. Cancellation depends on forwarding signal. Export and print default to visible data columns on the current page. |
|
||||
| Routing and permissions | [Routing guide](../apps/admin/src/router/README.md), [route types](../apps/admin/src/router/types.ts), [permission guards](../apps/admin/src/router/utils/permission.ts) | Menu visibility is not access authorization. Backends validate sessions and API permissions. Caching requires route names to match component names. Verify menu entry, direct access, and reload. |
|
||||
| Layout and Pinia | [Layout slots and preferences](../apps/admin/src/layout/README.md), [store conventions](../apps/admin/src/store/README.md) | Global UI singletons moved to `runtime` and are not persisted. Preserve historical settings and lock-screen formats. Custom content-slot integrations must retain request cancellation and route caching. |
|
||||
| Requests and mocks | [Axios implementation](../apps/admin/src/axios/instance.ts), [canceller](../packages/http/src/RequestCanceler.ts), [standard business API](../apps/admin/src/api/admin/index.ts) | Instances return the body on success and reject on failure. A caller-supplied signal disables default template signal injection. Development and static online demos share MSW HTTP mocks; disabling mocks connects directly to standard backend endpoints. |
|
||||
| Hooks, utilities, and icons | [Hook behavior](../apps/admin/src/hooks/README.md), [utility compatibility entry points](../apps/admin/src/utils/README.md), [icon generation](../packages/icons/src/A_README.md) | Keep public `@/hooks` and `@/utils` entry points. Migrate legacy bare icon names only at cache-read boundaries when the name is unique. Screenshot and print tests do not establish native browser acceptance. |
|
||||
| Toolchain and deployment | [Toolchain record](toolchain-upgrade.md), [architecture map](architecture.md), [Vite configuration](../vite.custom.config.ts) | Node/pnpm requirements come from manifests. The admin base is `/ray-template/`; bundled documentation uses `/ray-template/docs/`. The previously published site still uses `/ray-template-doc/`. |
|
||||
|
||||
## 联动流程
|
||||
## Update workflow
|
||||
|
||||
1. 应用改动影响公开导入、配置、缓存或行为时,在同一变更更新模块说明及 `apps/docs` 中受影响的文档和示例。破坏性改动进入迁移清单。
|
||||
2. 展示正在运行的示例源码。轻量示例位于 `apps/docs/examples`,使用共享包的公开入口;需要后台上下文的示例嵌入 `example.html`,源码引用指向实际的后台演示页。定位入口见[文档主题索引](../harness/context/docs.md)。
|
||||
3. 运行 `pnpm harness verify`,再用 `pnpm docs:preview` 在 `/ray-template/docs/` 检查导航、搜索、旧路径、明暗主题、窄屏和交互。线上迁址另行验证新旧地址。
|
||||
1. When application changes affect public imports, configuration, caching, or behavior, update the module notes and affected `apps/docs` pages/examples in the same change. Add breaking changes to the migration guide.
|
||||
2. Display source from the running example. Lightweight examples live in `apps/docs/examples` and use public shared-package entry points. Examples needing application context embed `example.html`, with source references pointing to the actual admin demo page. Use the [documentation topic index](../harness/context/docs.md) to locate them.
|
||||
3. Run relevant tests or scope checks for application changes. For documentation structure, links, code examples, or theme changes, run `pnpm harness verify docs`. Wording-only corrections need source and formatting checks. Reuse a completed check that includes `docs:check` if its relevant files have not changed since.
|
||||
4. Select browser coverage using the [Harness impact dimensions](../harness/README.md#browser-verification). View the changed page when rendering structure or layout is at risk; exercise only the affected interactive example. Add navigation, search, legacy paths, themes, and narrow widths only when each is affected. For site themes, global navigation, or release acceptance, select representative pages for shared behavior. Maintainer documentation and wording-only reader-documentation corrections do not trigger browser checks.
|
||||
5. Use `pnpm docs:preview` for documentation pages and lightweight examples. For changes to embedded admin examples, deployment bases, or combined output, use `pnpm pages:build` and the combined preview. Verify old and new live URLs separately for a site migration.
|
||||
|
||||
## 待同步到读者指南的内容
|
||||
## Pending reader-guide updates
|
||||
|
||||
应用侧已准备好 [路由接入文档](../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` 的选中态与过渡规则。截图使用更新后的登录页与管理页,并核对部署子路径。
|
||||
Application evidence is available in the [routing integration guide](../apps/admin/src/router/README.md), [schema](../packages/routing/src/schema.ts), [Segment notes](../packages/ui/src/RSegment/README.md), and [page design guide](ui-design.md). Add source switching, API examples, and version validation to `apps/docs/guide/routing.md`; document `fitContent` selection states and transitions in the component reference. Use updated login and management-page screenshots and check deployment subpaths.
|
||||
|
||||
`guide/layout.md` 补充减少动态效果和浮动退出按钮;`guide/routing.md` 增加可视化与 JSON 两个入口,明确可视化应用仅保存在当前浏览器;`reference/hooks/layout.md` 说明加载提示以可见内容区为基准。
|
||||
Update `guide/layout.md` for reduced motion and the floating exit button. Add visual and JSON entry points to `guide/routing.md`, making clear that applying visual configuration stores it only in the current browser. Explain in `reference/hooks/layout.md` that loading indicators are positioned relative to the visible content area.
|
||||
|
||||
`guide/layout.md` 同步设置抽屉的偏好导入导出:JSON 只包含抽屉内偏好,校验通过后即时保存,独立于路由管理的 JSON 配置。
|
||||
Update `guide/layout.md` for preference import/export in the settings drawer: JSON contains only drawer preferences, saves immediately after successful validation, and is independent of route-management JSON configuration.
|
||||
|
||||
@ -1,45 +1,45 @@
|
||||
# TablePro 代码审查 · 2026-11-05
|
||||
# TablePro code review · 2026-11-05
|
||||
|
||||
基线:`d15966cf`。覆盖 RTablePro、TablePanel、useTablePro、搜索控件和状态、列设置、CSV/打印、样式、公开类型、应用与文档示例。下文保留基线发现,修复结果见文末。
|
||||
Baseline: `d15966cf`. Scope: RTablePro, TablePanel, useTablePro, search controls and state, column settings, CSV/printing, styles, public types, and application/documentation examples. The findings below describe the baseline; remediation results are recorded at the end.
|
||||
|
||||
P1 表示应在继续扩展前处理;P2 表示有明确的功能或使用限制;P3 表示可随相关改动处理。以下“复现”表示本地 Vitest 重现了现有行为,其余为源码推导。
|
||||
P1 means address before further expansion; P2 means a concrete functional or usage limitation; P3 can be handled alongside related work. “Reproduced” below means local Vitest tests reproduced the existing behavior. Other findings are inferred from source.
|
||||
|
||||
## P1
|
||||
|
||||
1. **切换查询范围后仍能操作旧范围数据(复现)。** [TablePro.tsx](https://github.com/XiaoDaiGua-Ray/ray-template/blob/d15966cf637fe8bb6d488c45945a56c26b52e158/packages/ui/src/RTablePro/src/TablePro.tsx#L191-L257) 在 request、params 或分页条件改变时启动查询,但仅在成功时替换 result。先加载 `scope=a`,再切到返回错误的 `scope=b`,表格、total、`getCurrentPageData()` 和导出仍取 A。保留同范围刷新结果符合文档;如果范围代表账号、租户或订单,保留其他范围的结果会误导批量操作。建议把成功结果与查询快照绑定,至少在业务范围或数据源切换时清空或禁用操作;单独保留同范围失败时的旧数据。
|
||||
1. **Data from the previous query scope remains actionable after switching scopes (reproduced).** [TablePro.tsx](https://github.com/XiaoDaiGua-Ray/ray-template/blob/d15966cf637fe8bb6d488c45945a56c26b52e158/packages/ui/src/RTablePro/src/TablePro.tsx#L191-L257) starts a query when request, params, or pagination changes, but replaces result only on success. Load `scope=a`, then switch to a failing `scope=b`: the table, total, `getCurrentPageData()`, and export still use A. Preserving results during a same-scope refresh matches the documentation; retaining another scope's results can mislead bulk operations when scope represents an account, tenant, or order. Bind successful results to a query snapshot. At minimum, clear results or disable operations when the business scope or data source changes, while separately preserving old data for same-scope failures.
|
||||
|
||||
## P2
|
||||
|
||||
2. **本地受控分页时,提交搜索和实例跳页无法落实(复现)。** [TablePro.tsx](https://github.com/XiaoDaiGua-Ray/ray-template/blob/d15966cf637fe8bb6d488c45945a56c26b52e158/packages/ui/src/RTablePro/src/TablePro.tsx#L266-L308) 只写内部 page;[渲染](https://github.com/XiaoDaiGua-Ray/ray-template/blob/d15966cf637fe8bb6d488c45945a56c26b52e158/packages/ui/src/RTablePro/src/TablePro.tsx#L423-L459) 优先用外部 `pagination.page`,而回调只由表格分页器动作触发。给定 `pagination.page=2`,提交搜索后传给 DataTable 的仍为 2。统一用户点击、搜索重置与实例操作的受控写入语义;文档区分 request 模式、手动远端与本地模式。
|
||||
3. **相同字段类型换搜索规则,已生效的规则仍旧(复现)。** [search.ts](https://github.com/XiaoDaiGua-Ray/ray-template/blob/d15966cf637fe8bb6d488c45945a56c26b52e158/packages/ui/src/RTablePro/src/search.ts#L218-L231) 只按类型和 multiple 判断字段能否保留;[TablePro.tsx](https://github.com/XiaoDaiGua-Ray/ray-template/blob/d15966cf637fe8bb6d488c45945a56c26b52e158/packages/ui/src/RTablePro/src/TablePro.tsx#L324-L352) 把“能保留值”当成“无需重建快照”。把同一个字段的 `matches` 从恒真改为恒假,表中依然显示旧行。更新 `getValue`、`transform` 或 `visible` 也可能保留旧条件。值兼容检查和查询语义变更应分开,后者重建 predicate/params。
|
||||
4. **搜索可见性或匹配函数异常绕过错误边界。** [useTableSearch.ts](https://github.com/XiaoDaiGua-Ray/ray-template/blob/d15966cf637fe8bb6d488c45945a56c26b52e158/packages/ui/src/RTablePro/src/useTableSearch.ts#L44-L56) 在调用 commit 前归一化,`visible` 抛错会让 submit Promise reject(复现);[模板](https://github.com/XiaoDaiGua-Ray/ray-template/blob/d15966cf637fe8bb6d488c45945a56c26b52e158/packages/ui/src/RTablePro/src/components/Search.tsx#L255-L258) 未处理 rejection。另有 [TablePro.tsx](https://github.com/XiaoDaiGua-Ray/ray-template/blob/d15966cf637fe8bb6d488c45945a56c26b52e158/packages/ui/src/RTablePro/src/TablePro.tsx#L182-L187) 在 render 依赖的 computed 执行 `getValue/matches`,异常同样进不了 search-error。定义回调异常是开发者错误还是可恢复错误;如选择后者,在提交与执行谓词两处都保留上次有效结果并报告。
|
||||
5. **本地列字段的读取规则与 Naive UI 和导出不一致。** [search.ts](https://github.com/XiaoDaiGua-Ray/ray-template/blob/d15966cf637fe8bb6d488c45945a56c26b52e158/packages/ui/src/RTablePro/src/search.ts#L289-L291) 用 `row[key]`,而 [CSV](https://github.com/XiaoDaiGua-Ray/ray-template/blob/d15966cf637fe8bb6d488c45945a56c26b52e158/packages/ui/src/RTablePro/src/csv.ts#L33-L40) 和 [打印](https://github.com/XiaoDaiGua-Ray/ray-template/blob/d15966cf637fe8bb6d488c45945a56c26b52e158/packages/ui/src/RTablePro/src/printing.ts#L89-L96) 用 lodash `get`。给嵌套对象配置 `key: 'customer.name'` 时,搜索不到界面上展示的值;当前需为字段显式提供 getValue。建议共享默认取值语义,保留显式 getValue 优先级。
|
||||
6. **行右键菜单回调拿不到触发的行。** [TablePanel.tsx](https://github.com/XiaoDaiGua-Ray/ray-template/blob/d15966cf637fe8bb6d488c45945a56c26b52e158/packages/ui/src/RTablePro/src/TablePanel.tsx#L149-L168) 已拿到 row 和 index,但仅存坐标;[选择菜单项](https://github.com/XiaoDaiGua-Ray/ray-template/blob/d15966cf637fe8bb6d488c45945a56c26b52e158/packages/ui/src/RTablePro/src/TablePanel.tsx#L293-L299) 只发 key/option,无法安全用于行级编辑或删除,也没有键盘等价入口。将行上下文随回调提供并在关闭时清理,或明确该功能是表级菜单。
|
||||
7. **自定义打印区域会丢失宿主样式及部分实时控件状态。** [printing.ts](https://github.com/XiaoDaiGua-Ray/ray-template/blob/d15966cf637fe8bb6d488c45945a56c26b52e158/packages/ui/src/RTablePro/src/printing.ts#L103-L116) 克隆 DOM,再放进仅有打印样式的 [独立 iframe](https://github.com/XiaoDaiGua-Ray/ray-template/blob/d15966cf637fe8bb6d488c45945a56c26b52e158/packages/ui/src/RTablePro/src/printing.ts#L155-L169)。如区域依赖应用 CSS、异步字体、canvas 像素或不可克隆的状态,预览与屏幕不一致。文档已有专用 `style` 选项,应补充其边界,并在 Chrome/Safari 验收报表和取消打印后的清理。
|
||||
2. **Search submission and instance page changes do not take effect with controlled local pagination (reproduced).** [TablePro.tsx](https://github.com/XiaoDaiGua-Ray/ray-template/blob/d15966cf637fe8bb6d488c45945a56c26b52e158/packages/ui/src/RTablePro/src/TablePro.tsx#L266-L308) writes only its internal page. [Rendering](https://github.com/XiaoDaiGua-Ray/ray-template/blob/d15966cf637fe8bb6d488c45945a56c26b52e158/packages/ui/src/RTablePro/src/TablePro.tsx#L423-L459) prefers external `pagination.page`, while callbacks run only for paginator actions. With `pagination.page=2`, submitting search still passes 2 to DataTable. Unify controlled updates for user clicks, search resets, and instance operations. Distinguish request mode, manually managed remote mode, and local mode in the documentation.
|
||||
3. **Changing search rules without changing field type retains the old applied rules (reproduced).** [search.ts](https://github.com/XiaoDaiGua-Ray/ray-template/blob/d15966cf637fe8bb6d488c45945a56c26b52e158/packages/ui/src/RTablePro/src/search.ts#L218-L231) determines field retention only from type and multiple. [TablePro.tsx](https://github.com/XiaoDaiGua-Ray/ray-template/blob/d15966cf637fe8bb6d488c45945a56c26b52e158/packages/ui/src/RTablePro/src/TablePro.tsx#L324-L352) treats value compatibility as permission to keep the snapshot. Changing a field's `matches` from always true to always false still leaves old rows visible. Updates to `getValue`, `transform`, or `visible` can also retain old conditions. Separate value compatibility from query-semantic changes; rebuild predicate/params for the latter.
|
||||
4. **Exceptions in search visibility or matching callbacks bypass the error boundary.** [useTableSearch.ts](https://github.com/XiaoDaiGua-Ray/ray-template/blob/d15966cf637fe8bb6d488c45945a56c26b52e158/packages/ui/src/RTablePro/src/useTableSearch.ts#L44-L56) normalizes before commit. A throwing `visible` callback rejects the submit Promise (reproduced), and the [template](https://github.com/XiaoDaiGua-Ray/ray-template/blob/d15966cf637fe8bb6d488c45945a56c26b52e158/packages/ui/src/RTablePro/src/components/Search.tsx#L255-L258) does not handle the rejection. [TablePro.tsx](https://github.com/XiaoDaiGua-Ray/ray-template/blob/d15966cf637fe8bb6d488c45945a56c26b52e158/packages/ui/src/RTablePro/src/TablePro.tsx#L182-L187) also executes `getValue/matches` in a computed value used by rendering; those exceptions bypass search-error as well. Decide whether callback exceptions are developer errors or recoverable errors. If recoverable, report them and retain the last valid result both during submission and predicate execution.
|
||||
5. **Local column-value lookup differs from Naive UI and export behavior.** [search.ts](https://github.com/XiaoDaiGua-Ray/ray-template/blob/d15966cf637fe8bb6d488c45945a56c26b52e158/packages/ui/src/RTablePro/src/search.ts#L289-L291) uses `row[key]`; [CSV](https://github.com/XiaoDaiGua-Ray/ray-template/blob/d15966cf637fe8bb6d488c45945a56c26b52e158/packages/ui/src/RTablePro/src/csv.ts#L33-L40) and [printing](https://github.com/XiaoDaiGua-Ray/ray-template/blob/d15966cf637fe8bb6d488c45945a56c26b52e158/packages/ui/src/RTablePro/src/printing.ts#L89-L96) use lodash `get`. With nested data and `key: 'customer.name'`, search cannot find the displayed value; the field currently needs an explicit getValue. Share default lookup semantics while retaining explicit getValue precedence.
|
||||
6. **Row context-menu callbacks do not receive the triggering row.** [TablePanel.tsx](https://github.com/XiaoDaiGua-Ray/ray-template/blob/d15966cf637fe8bb6d488c45945a56c26b52e158/packages/ui/src/RTablePro/src/TablePanel.tsx#L149-L168) has row and index but stores only coordinates. [Menu selection](https://github.com/XiaoDaiGua-Ray/ray-template/blob/d15966cf637fe8bb6d488c45945a56c26b52e158/packages/ui/src/RTablePro/src/TablePanel.tsx#L293-L299) emits only key/option, making row-level editing or deletion unsafe. There is no keyboard equivalent. Include row context in the callback and clear it on close, or explicitly define the feature as a table-level menu.
|
||||
7. **Custom print regions lose host styles and some live control state.** [printing.ts](https://github.com/XiaoDaiGua-Ray/ray-template/blob/d15966cf637fe8bb6d488c45945a56c26b52e158/packages/ui/src/RTablePro/src/printing.ts#L103-L116) clones DOM into a [separate iframe](https://github.com/XiaoDaiGua-Ray/ray-template/blob/d15966cf637fe8bb6d488c45945a56c26b52e158/packages/ui/src/RTablePro/src/printing.ts#L155-L169) containing only print styles. Regions dependent on application CSS, asynchronous fonts, canvas pixels, or non-clonable state can differ from the screen. The documented dedicated `style` option needs explicit limits. Verify reports and cleanup after print cancellation in Chrome/Safari.
|
||||
|
||||
## P3
|
||||
|
||||
8. **本地搜索的热点可以减少分配与重复计算。** [search.ts](https://github.com/XiaoDaiGua-Ray/ray-template/blob/d15966cf637fe8bb6d488c45945a56c26b52e158/packages/ui/src/RTablePro/src/search.ts#L294-L330) 对每行重复计算搜索文本的小写,多选条件对数组使用嵌套线性查找;[联动](https://github.com/XiaoDaiGua-Ray/ray-template/blob/d15966cf637fe8bb6d488c45945a56c26b52e158/packages/ui/src/RTablePro/src/search.ts#L184-L213) 每改一个依赖再次扫描全部字段。预编译小写查询与 Set,字段量大时再为依赖建立反向索引;虚拟滚动只限制 DOM,不能降低过滤成本。这里未做大数据基准。
|
||||
9. **分页宽度触发不必要更新,字典反复浅拷贝。** [TablePanel.tsx](https://github.com/XiaoDaiGua-Ray/ray-template/blob/d15966cf637fe8bb6d488c45945a56c26b52e158/packages/ui/src/RTablePro/src/TablePanel.tsx#L42-L46) 的 ResizeObserver 将连续宽度带入 [render](https://github.com/XiaoDaiGua-Ray/ray-template/blob/d15966cf637fe8bb6d488c45945a56c26b52e158/packages/ui/src/RTablePro/src/TablePanel.tsx#L210-L213);只在跨过 600px 时改变分页模式即可。[locale.ts](https://github.com/XiaoDaiGua-Ray/ray-template/blob/d15966cf637fe8bb6d488c45945a56c26b52e158/packages/ui/src/RTablePro/src/locale.ts#L9-L17) 每次翻译先克隆整份字典,即使宿主翻译已命中。预建固定字典,宿主翻译优先。此项未做性能量化。
|
||||
10. **公开 Props 的透传边界不易核对。** [props.ts](https://github.com/XiaoDaiGua-Ray/ray-template/blob/d15966cf637fe8bb6d488c45945a56c26b52e158/packages/ui/src/RTablePro/src/props.ts#L6-L23) 全量继承 Naive UI,再在 [TablePro](https://github.com/XiaoDaiGua-Ray/ray-template/blob/d15966cf637fe8bb6d488c45945a56c26b52e158/packages/ui/src/RTablePro/src/TablePro.tsx#L407-L440) 与 [TablePanel](https://github.com/XiaoDaiGua-Ray/ray-template/blob/d15966cf637fe8bb6d488c45945a56c26b52e158/packages/ui/src/RTablePro/src/TablePanel.tsx#L176-L199) 两次拆分。新增包装层字段或升级 Naive UI 时容易把不适用的选项暴露给调用方。优先明确哪些字段由包装层控制;补对受控分页、受控列及 slots 的契约用例。内部 `C.tsx`、`Props.tsx` 可按实际职责命名,减少检索成本。
|
||||
11. **列工具只能拖拽排序,显示状态与布局恢复是两套语义。** [C.tsx](https://github.com/XiaoDaiGua-Ray/ray-template/blob/d15966cf637fe8bb6d488c45945a56c26b52e158/packages/ui/src/RTablePro/src/components/C.tsx#L136-L177) 提供鼠标拖拽和键盘勾选,没有键盘排序动作;“显示全部”仅清除隐藏状态,[顺序与固定列补丁](https://github.com/XiaoDaiGua-Ray/ray-template/blob/d15966cf637fe8bb6d488c45945a56c26b52e158/packages/ui/src/RTablePro/src/columns.ts#L44-L93) 仍保留。若需要完整恢复和键盘可操作,可添加显式上移/下移与独立的布局重置;目前仅持久化显隐符合文档。
|
||||
8. **Local search can reduce allocations and repeated computation.** [search.ts](https://github.com/XiaoDaiGua-Ray/ray-template/blob/d15966cf637fe8bb6d488c45945a56c26b52e158/packages/ui/src/RTablePro/src/search.ts#L294-L330) lowercases search text for every row and uses nested linear searches for multi-select arrays. [Dependencies](https://github.com/XiaoDaiGua-Ray/ray-template/blob/d15966cf637fe8bb6d488c45945a56c26b52e158/packages/ui/src/RTablePro/src/search.ts#L184-L213) rescan all fields for each changed dependency. Precompute lowercase queries and Sets; add reverse dependency indexes for large field counts if needed. Virtual scrolling limits DOM work, not filtering costs. No large-dataset benchmark was run.
|
||||
9. **Pagination width causes unnecessary updates, and locale dictionaries are repeatedly shallow-copied.** The ResizeObserver in [TablePanel.tsx](https://github.com/XiaoDaiGua-Ray/ray-template/blob/d15966cf637fe8bb6d488c45945a56c26b52e158/packages/ui/src/RTablePro/src/TablePanel.tsx#L42-L46) feeds continuously changing width into [rendering](https://github.com/XiaoDaiGua-Ray/ray-template/blob/d15966cf637fe8bb6d488c45945a56c26b52e158/packages/ui/src/RTablePro/src/TablePanel.tsx#L210-L213); pagination mode only needs to change when crossing 600px. [locale.ts](https://github.com/XiaoDaiGua-Ray/ray-template/blob/d15966cf637fe8bb6d488c45945a56c26b52e158/packages/ui/src/RTablePro/src/locale.ts#L9-L17) clones the entire dictionary before every translation, even when host translation succeeds. Prebuild fixed dictionaries and prefer host translations. Performance impact was not quantified.
|
||||
10. **Public prop forwarding boundaries are difficult to verify.** [props.ts](https://github.com/XiaoDaiGua-Ray/ray-template/blob/d15966cf637fe8bb6d488c45945a56c26b52e158/packages/ui/src/RTablePro/src/props.ts#L6-L23) inherits the full Naive UI set, then splits it in both [TablePro](https://github.com/XiaoDaiGua-Ray/ray-template/blob/d15966cf637fe8bb6d488c45945a56c26b52e158/packages/ui/src/RTablePro/src/TablePro.tsx#L407-L440) and [TablePanel](https://github.com/XiaoDaiGua-Ray/ray-template/blob/d15966cf637fe8bb6d488c45945a56c26b52e158/packages/ui/src/RTablePro/src/TablePanel.tsx#L176-L199). New wrapper fields or Naive UI upgrades can expose inapplicable options. Clarify wrapper-controlled fields and add contract cases for controlled pagination, controlled columns, and slots. Name internal `C.tsx` and `Props.tsx` by responsibility to improve discovery.
|
||||
11. **Column ordering is drag-only, and visibility reset differs from layout reset.** [C.tsx](https://github.com/XiaoDaiGua-Ray/ray-template/blob/d15966cf637fe8bb6d488c45945a56c26b52e158/packages/ui/src/RTablePro/src/components/C.tsx#L136-L177) supports pointer dragging and keyboard checkbox selection but not keyboard ordering. “Show all” clears only hidden state; [order and fixed-column patches](https://github.com/XiaoDaiGua-Ray/ray-template/blob/d15966cf637fe8bb6d488c45945a56c26b52e158/packages/ui/src/RTablePro/src/columns.ts#L44-L93) remain. For complete reset and keyboard operation, add explicit move-up/down actions and a separate layout reset. Persisting visibility alone matches the current documentation.
|
||||
|
||||
## 保留的设计
|
||||
## Designs to preserve
|
||||
|
||||
请求成功前校验 `total` 和数据形状,AbortSignal 既透传给调用方又用于拦截过期结果。搜索草稿和生效快照分开,过期异步校验有版本号;列显隐不会直接修改 props,CSV 单元格做公式前缀防护,默认打印使用 textContent 和隔离 iframe。建议在修复中保留这些边界。
|
||||
Validate `total` and data shape before accepting a successful request. Forward AbortSignal to callers and use it to reject stale results. Keep search drafts separate from applied snapshots and version asynchronous validation. Column visibility must not mutate props directly. Retain CSV formula-prefix protection and default printing through textContent and an isolated iframe.
|
||||
|
||||
四个标注“复现”的路径使用 Vue Test Utils / Vitest 独立验证。复现用例与输出保存在本机 `.harness-local/table-pro-review-repro.local.spec.ts` 和 `.harness-local/table-pro-review-repro.log`;未将已知缺陷写成仓库的长期断言。真实性能、原生打印对话框及读屏软件不在本次运行验证范围。
|
||||
Four paths marked “reproduced” were independently verified with Vue Test Utils / Vitest. Reproduction tests and output were saved locally as `.harness-local/table-pro-review-repro.local.spec.ts` and `.harness-local/table-pro-review-repro.log`; known defects were not encoded as permanent repository expectations. Real performance, native print dialogs, and screen readers were outside runtime verification scope.
|
||||
|
||||
## 修复批次
|
||||
## Remediation batches
|
||||
|
||||
| 批次 | 项目 | 结果 |
|
||||
| ---- | ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| 1 | 1 | 以请求函数、有效筛选条件和分页绑定成功结果。范围切换立即失效,切页只保留同范围总数,请求失败后清空行和总数,展示空态并由宿主 Toast 提醒。结果不匹配时拦截取数、底层实例、CSV 和打印。 |
|
||||
| 2 | 2–5 | 分页操作和搜索重置复用受控回调;兼容字段采用最新规则;回调失败统一报告并保留已生效条件;字段读取与 Naive UI、打印、CSV 一致。 |
|
||||
| 2 | 6–7 | 行菜单回传行和索引,支持键盘,换数据后关闭。自定义打印复制页面样式、根节点主题、普通表单状态和可复制的画布,等待资源有上限;允许关闭样式继承。 |
|
||||
| 3 | 8–9 | 搜索预计算小写查询、集合和反向依赖;分页只在跨越容器宽度阈值时改变模式;语言回退字典固定复用。 |
|
||||
| 3 | 10–11 | 集中声明 Naive UI 与包装层的透传边界,命名列及外观设置组件;列排序增加键盘按钮,显隐和布局可分别恢复。 |
|
||||
| Batch | Items | Result |
|
||||
| ----- | ----- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| 1 | 1 | Bind successful results to the request function, applied filters, and pagination. Scope changes invalidate immediately. Page changes retain only same-scope totals. Request failures clear rows and totals, show an empty state, and notify through the host toast. Block data access, underlying-instance access, CSV, and printing when results do not match. |
|
||||
| 2 | 2–5 | Pagination and search resets share controlled callbacks. Compatible fields use current rules. Callback failures are reported consistently while preserving applied conditions. Field lookup matches Naive UI, printing, and CSV. |
|
||||
| 2 | 6–7 | Row menus return row/index, support keyboards, and close when data changes. Custom printing copies page styles, root theme, ordinary form state, and copyable canvases, with bounded resource waits. Style inheritance can be disabled. |
|
||||
| 3 | 8–9 | Precompute lowercase queries, sets, and reverse dependencies. Change pagination mode only when container width crosses its threshold. Reuse fixed fallback locale dictionaries. |
|
||||
| 3 | 10–11 | Centralize Naive UI and wrapper forwarding boundaries and name column/appearance settings components. Add keyboard ordering buttons and separate visibility/layout resets. |
|
||||
|
||||
回归见 [查询、分页和行菜单](../__test__/components/table-pro.spec.ts)、[搜索](../__test__/components/table-pro-search.spec.ts)、[打印和导出](../__test__/components/table-pro-exports.spec.ts)及[列设置](../__test__/components/table-pro-columns.spec.ts)。受控表格与打印定制方式见 [TablePro 契约](../packages/ui/src/RTablePro/README.md)。手动远端由调用方管理其数据范围;原生打印对话框和页面性能的验证边界见交付记录。
|
||||
Regressions: [queries, pagination, and row menus](../__test__/components/table-pro.spec.ts), [search](../__test__/components/table-pro-search.spec.ts), [printing and export](../__test__/components/table-pro-exports.spec.ts), and [column settings](../__test__/components/table-pro-columns.spec.ts). See the [TablePro contract](../packages/ui/src/RTablePro/README.md) for controlled tables and custom printing. Callers own data scope in manually managed remote mode. See delivery records for native print-dialog and page-performance verification limits.
|
||||
|
||||
追补:TablePanel 复用 Naive UI 卡片的表面、描边、圆角和内边距层次,`bare` 不带卡片外观。表格密度、斑马纹和边框以计算值合成,不镜像 props;保留的侦听负责重查、同步搜索配置、上报错误、取消打印及关闭行菜单。
|
||||
Follow-up: TablePanel reuses Naive UI card surfaces, borders, radii, and padding layers; `bare` removes the card appearance. Table density, striping, and borders are computed rather than mirrored from props. Remaining watchers handle refetching, search-configuration synchronization, error reporting, print cancellation, and row-menu closure.
|
||||
|
||||
@ -1,217 +1,239 @@
|
||||
# 工具链升级记录(2026-11-02)
|
||||
# Toolchain upgrade record (2026-11-02)
|
||||
|
||||
## 版本基线
|
||||
## Version baseline
|
||||
|
||||
版本通过 npm 官方注册表的 `latest` 标签核实,锁文件包含对应的完整解析结果。只使用稳定版,不引入 beta/RC。Node.js 使用当前 LTS 26.13.0,pnpm 固定为 12.16.1;本机验证使用校验 SHA-256 后下载到临时目录的 Node,未替换全局 Node。
|
||||
Versions were verified against the official npm registry's `latest` tags; the lockfile contains the complete resolutions. Only stable releases were used, without beta/RC versions. The upgrade selected Node.js LTS 26.13.0 and pinned pnpm to 12.16.1. Local verification used Node downloaded to a temporary directory after SHA-256 verification; the global Node installation was not replaced.
|
||||
|
||||
| 核心依赖 | 升级前 | 当前 |
|
||||
| ------------------- | --------------------------- | ---------------------------------------- |
|
||||
| Node.js(`.nvmrc`) | 22.12.0 | 26.13.0 LTS |
|
||||
| pnpm | 未固定,CI 使用 9 | 12.16.1 |
|
||||
| Vite | 7.2.6 | 8.3.5 |
|
||||
| Vue | 3.5.25 | 3.5.44 |
|
||||
| Vue Router | 4.6.3 | 5.4.0 |
|
||||
| Pinia | 3.0.3 | 4.1.0 |
|
||||
| Naive UI | 2.43.2 | 2.45.3 |
|
||||
| VueUse | 13.1.0 | 15.0.0 |
|
||||
| ECharts | 6.0.0 | 6.1.0 |
|
||||
| Axios | 1.10.0 | 1.21.0 |
|
||||
| TypeScript | 5.9.3 | 6.0.3(兼容上限) |
|
||||
| vue-tsc | 2.2.8 | 3.3.14 |
|
||||
| Vitest / UI | 4.0.12 | 5.0.5 |
|
||||
| ESLint | 9.39.1 | 10.14.0 |
|
||||
| typescript-eslint | 8.47.0(拆包) | 8.72.1 |
|
||||
| Prettier | 3.6.2 | 3.9.10 |
|
||||
| Husky | 8.0.3 | 9.1.7 |
|
||||
| lint-staged | 15.4.3 | 17.6.0 |
|
||||
| Mock 数据生成 | Mock.js 1.1.0 | Faker 10.6.0,中文 locale |
|
||||
| SVG 雪碧图 | vite-plugin-svg-icons 2.0.1 | @spiriit/vite-plugin-svg-spritemap 7.2.0 |
|
||||
| Core dependency | Before upgrade | Recorded version |
|
||||
| -------------------- | --------------------------- | ---------------------------------------- |
|
||||
| Node.js (`.nvmrc`) | 22.12.0 | 26.13.0 LTS |
|
||||
| pnpm | Unpinned; CI used 9 | 12.16.1 |
|
||||
| Vite | 7.2.6 | 8.3.5 |
|
||||
| Vue | 3.5.25 | 3.5.44 |
|
||||
| Vue Router | 4.6.3 | 5.4.0 |
|
||||
| Pinia | 3.0.3 | 4.1.0 |
|
||||
| Naive UI | 2.43.2 | 2.45.3 |
|
||||
| VueUse | 13.1.0 | 15.0.0 |
|
||||
| ECharts | 6.0.0 | 6.1.0 |
|
||||
| Axios | 1.10.0 | 1.21.0 |
|
||||
| TypeScript | 5.9.3 | 6.0.3 (compatibility ceiling) |
|
||||
| vue-tsc | 2.2.8 | 3.3.14 |
|
||||
| Vitest / UI | 4.0.12 | 5.0.5 |
|
||||
| ESLint | 9.39.1 | 10.14.0 |
|
||||
| typescript-eslint | 8.47.0 (separate packages) | 8.72.1 |
|
||||
| Prettier | 3.6.2 | 3.9.10 |
|
||||
| Husky | 8.0.3 | 9.1.7 |
|
||||
| lint-staged | 15.4.3 | 17.6.0 |
|
||||
| Mock data generation | Mock.js 1.1.0 | Faker 10.6.0, Chinese locale |
|
||||
| SVG spritemaps | vite-plugin-svg-icons 2.0.1 | @spiriit/vite-plugin-svg-spritemap 7.2.0 |
|
||||
|
||||
其余保留的直接依赖也更新为核实到的稳定版并使用精确版本,完整列表见 `package.json`。没有新版本的依赖保留其已有最新版本。
|
||||
Other retained direct dependencies were also updated to verified stable releases and pinned exactly; see `package.json` for the full list. Dependencies with no newer release kept their existing latest version.
|
||||
|
||||
## 必要适配
|
||||
## Required adaptations
|
||||
|
||||
- 可选 CDN 改为 jsDelivr 的 npm 精确版本路径,使用发布包中实际存在的生产文件;移除已经不在依赖中的 dom-to-image 条目。默认仍使用本地 bundle。
|
||||
- Vite 8 使用 Rolldown/Oxc:移除无效 `build.transpile`,使用 `rolldownOptions` 和 Oxc 压缩参数,交由原生依赖图拆包;保留路由懒加载、压缩文件、部署 base 与各模式输出目录。
|
||||
- Node 配置使用 ESM 路径解析、显式 `.ts` 扩展名和 JSON import attributes,为 native config loader 做好适配。别名 `@api` 统一指向实际的 `src/api`,修正 TS `@images/*` 映射。
|
||||
- 替换旧 SVG 插件的缺失依赖和旧依赖树。`RIcon` 仍按 `prefix + name` 访问图标,新插件生成独立带 hash 的雪碧图并跟随部署 base;`<use>` 使用标准 `href`。
|
||||
- 移除会在开发/构建时自动修改源码的 `vite-plugin-eslint`;ESLint 10 使用原生 flat config。保留有价值的既有规则,格式交给 Prettier,lint/check 默认只读。
|
||||
- 更新 Husky 9 hook,移除 Husky 8 的初始化与旧 package.json hooks。暂存检查使用 `--no-warn-ignored`,只抑制显式传入已排除声明文件时的提示,真实 lint warning 仍会失败。移除实际未使用的 Webpack sprite loader、depcheck 和重复 ESLint 预设。
|
||||
- VueUse 的 `MaybeRef`/`MaybeRefOrGetter` 改从 Vue 导入;Axios 仅在已安装解包响应拦截器的边界公开返回 `data` 的原有接口,补充适配器回归用例。
|
||||
- 修复 TSX 演示中对解构 `const` 使用 `v-model` 产生的非法赋值,改为绑定组件实例属性。
|
||||
- Router 5 的权限守卫改为返回路由结果,保留未登录、角色与白名单判断;首页本身无权限时取消导航以免重定向循环,增加真实内存路由测试。
|
||||
- 开发依赖扫描限定 `index.html`,避免误扫旧构建目录;SVG 预览页的 glob 移到独立 `.ts` 模块,绕过 Vite 8 扫描器将保留 JSX 当作 JS 的限制。待上游支持后可重新评估该拆分。
|
||||
- Vitest 测试只复用 Vue/TSX 与自动导入转换,不启动 Mock 服务、HTML 注入、图标扫描或压缩插件。修复遗漏 `await` 的断言,更新水印/全屏用例中的过期预期,保留行为断言。
|
||||
- 既有颜色转换回归暴露 rgba 空格不一致与八位 hex 透明度丢失,已修正;图表异常保留原始 `cause`。
|
||||
- Mock.js 存在未修复的原型污染公告,且包含直接 `eval`;替换为 Faker 的中文实例,保持人员字段、分页接口和表格示例能力。新版 Mock 插件的 include 相对 `dir` 匹配,修正原先重复的 `mock/` 前缀并等待首次加载,实际验证了 API 响应。
|
||||
- 开发时打开 `#/tables/remote`,在 Network 的 Fetch/XHR 分类查看 `GET /api/list?page=1&pageSize=10`。接口使用站点根路径 `/api/list`,不带 `/ray-template/`。Vite 按启动日志中的实际端口访问;静态构建的页面使用同一套本地示例生成逻辑,不依赖 Mock 服务器。
|
||||
- 浏览器构建和 Autoprefixer 统一到 Vite 8 Baseline Widely Available。开发服务默认 loopback,局域网访问需显式 `--host`。监听排除全部构建目录和 `.ai-local`,避免构建报告时触发页面重复重载。
|
||||
- CI 与 Docker 使用同一 Node/pnpm,冻结锁文件安装。CI 合并重复流程并覆盖类型、lint、格式、测试、构建;保留检查通过后部署 `main` 到 `dist` 分支的行为。
|
||||
- Optional CDN loading uses exact npm-version paths on jsDelivr and production files that actually exist in published packages. Removed the dom-to-image entry, which was no longer a dependency. Local bundling remains the default.
|
||||
- Vite 8 uses Rolldown/Oxc. Removed ineffective `build.transpile`, adopted `rolldownOptions` and Oxc minification settings, and delegated chunking to the native dependency graph. Preserved lazy routes, compressed files, deployment bases, and per-mode output directories.
|
||||
- Node configuration uses ESM path resolution, explicit `.ts` extensions, and JSON import attributes for the native config loader. Unified `@api` with the actual `src/api` directory and fixed TypeScript's `@images/*` mapping.
|
||||
- Replaced the old SVG plugin's missing dependencies and obsolete dependency tree. `RIcon` still addressed icons through `prefix + name`; the new plugin generated separate hashed spritemaps respecting the deployment base. `<use>` uses standard `href`.
|
||||
- Removed `vite-plugin-eslint`, which rewrote source during development/builds. ESLint 10 uses native flat config. Retained useful existing rules, delegated formatting to Prettier, and kept lint/check behavior read-only by default.
|
||||
- Updated hooks for Husky 9, removing Husky 8 initialization and old package.json hooks. Staged checks use `--no-warn-ignored` only to suppress notices for explicitly supplied ignored declaration files; real lint warnings still fail. Removed unused Webpack sprite loaders, depcheck, and duplicate ESLint presets.
|
||||
- Import VueUse's `MaybeRef`/`MaybeRefOrGetter` from Vue. Axios exposes its existing API that returns `data` only at boundaries with installed response-unwrapping interceptors; adapter regressions were added.
|
||||
- Fixed invalid assignments generated by TSX demo `v-model` bindings to destructured `const` variables, using component-instance properties instead.
|
||||
- Router 5 permission guards return route results while retaining authentication, role, and allowlist checks. Cancel navigation when the home route is itself unauthorized to avoid redirect loops. Added real in-memory-router tests.
|
||||
- Limited development dependency scanning to `index.html` to avoid old build directories. Moved the SVG preview glob into a separate `.ts` module to work around Vite 8 scanning preserved JSX as JavaScript. Reassess the split when upstream supports that case.
|
||||
- Vitest reuses only Vue/TSX and auto-import transforms; it does not start mock services, HTML injection, icon scanning, or compression plugins. Fixed missing `await` assertions and stale watermark/fullscreen expectations while retaining behavioral assertions.
|
||||
- Existing color-conversion regressions exposed inconsistent rgba spacing and lost alpha in eight-digit hex colors; both were fixed. Chart errors retain their original `cause`.
|
||||
- Mock.js had an unresolved prototype-pollution advisory and direct `eval` usage. Replaced it with a Chinese Faker instance while retaining person fields, pagination endpoints, and table demos. The updated mock plugin matches include paths relative to `dir`; removed the duplicated `mock/` prefix, waited for initial loading, and verified API responses.
|
||||
- During development, open `#/tables/remote` and inspect `GET /api/list?page=1&pageSize=10` under Network's Fetch/XHR filter. The endpoint uses the site-root path `/api/list`, without `/ray-template/`. Use the actual Vite port in startup logs. At this stage, static builds used the same local example-generation logic without depending on a mock server.
|
||||
- Aligned browser builds and Autoprefixer with Vite 8's Baseline Widely Available target. The development server defaults to loopback; LAN access requires explicit `--host`. Excluded all build directories and `.ai-local` from watching to prevent repeated reloads during report builds.
|
||||
- CI and Docker use the same Node/pnpm versions and frozen-lockfile installs. Consolidated duplicate CI workflows to cover types, lint, formatting, tests, and builds. Preserved deployment from `main` to the `dist` branch after checks pass.
|
||||
|
||||
## 兼容性限制与复查条件
|
||||
## Compatibility limits and reassessment conditions
|
||||
|
||||
### TypeScript 7
|
||||
|
||||
npm 最新为 7.0.2,但 `vue-tsc` 的编译器包装机制尚未完整支持原生 TypeScript 7,`typescript-eslint@8.72.1` 的 peer 范围也明确为 `<6.1.0`。因此采用 6.0.3,而不关闭类型检查或制造 peer 冲突。待这两个上游均明确支持后,再解除 Dependabot 对 TypeScript 7 的限制并运行完整验证。
|
||||
The latest npm release at verification was 7.0.2, but `vue-tsc`'s compiler wrapper did not fully support native TypeScript 7, and `typescript-eslint@8.72.1` explicitly required `<6.1.0`. Retained 6.0.3 without disabling type checking or introducing peer conflicts. Once both upstream projects explicitly support TypeScript 7, remove the Dependabot restriction and run complete verification.
|
||||
|
||||
### 兼容的间接依赖覆盖
|
||||
### Compatible transitive dependency overrides
|
||||
|
||||
`pnpm-workspace.yaml` 中有三个有限范围的覆盖,避免升级后的上游依赖继续锁定有已知公告的旧大版本:
|
||||
Three narrowly scoped overrides in `pnpm-workspace.yaml` prevent upgraded dependencies from retaining older major versions with known advisories:
|
||||
|
||||
| 覆盖 | 已核实的调用契约 | 移除条件 |
|
||||
| --------------------------------- | ----------------------------------------------- | ------------------------------------------------ |
|
||||
| `@logicflow/core>uuid` → 14.0.3 | LogicFlow 只使用无参数 `v4()` 生成 ID | LogicFlow 自身升级到已修复版本,且流程图验证通过 |
|
||||
| `minimatch@>=10 <11.0.1` → 11.0.4 | ESLint 的匹配函数与类接口仍可用,完整 lint 验证 | 上游依赖允许 11+,移除覆盖后审计与 lint 通过 |
|
||||
| `glob@>=9 <14.0.2` → 14.0.3 | js-beautify CLI 使用 `hasMagic`、`globSync` | 上游依赖允许已修复版本,移除覆盖后验证通过 |
|
||||
| Override | Verified usage contract | Removal condition |
|
||||
| --------------------------------- | --------------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
|
||||
| `@logicflow/core>uuid` → 14.0.3 | LogicFlow uses only argument-free `v4()` for IDs | LogicFlow adopts a fixed version and flowchart verification passes |
|
||||
| `minimatch@>=10 <11.0.1` → 11.0.4 | ESLint matching functions and class interfaces still work; full lint passed | Upstream permits 11+; audit and lint pass after removing the override |
|
||||
| `glob@>=9 <14.0.2` → 14.0.3 | The js-beautify CLI uses `hasMagic` and `globSync` | Upstream permits a fixed version; verification passes after removing the override |
|
||||
|
||||
依赖构建脚本采用 pnpm `allowBuilds` 列表。LogicFlow 的 AI 提示 postinstall 不参与运行时构建,明确禁用;其余仅保留已有原生依赖所需脚本。pnpm 自动记录的 `minimumReleaseAgeExclude` 是本次明确更新到最新稳定版产生的精确版本例外,不是关闭所有供应链检查。
|
||||
Dependency build scripts use pnpm's `allowBuilds` list. LogicFlow's AI-notice postinstall is unrelated to runtime builds and is explicitly disabled; other entries retain only scripts required by existing native dependencies. The exact-version `minimumReleaseAgeExclude` entries recorded by pnpm resulted from this explicit upgrade to the latest stable versions, not from disabling all supply-chain checks.
|
||||
|
||||
### CryptoJS
|
||||
|
||||
CryptoJS 4.2.0 已停止维护,但仍是最后一个发布版本。现有同步 AES 接口和密文格式继续保留;只有在同时设计旧密文迁移、异步接口与调用方适配时,才可替换为 Web Crypto。客户端内置密钥不能视为服务端保密边界。
|
||||
CryptoJS 4.2.0 was unmaintained but remained the final published release. Preserve existing synchronous AES APIs and ciphertext formats. Replace them with Web Crypto only alongside a design for legacy-ciphertext migration, asynchronous APIs, and caller adaptation. Client-embedded keys are not a server-side confidentiality boundary.
|
||||
|
||||
## 验证记录
|
||||
## Verification record
|
||||
|
||||
在 macOS 本机使用 Node.js 26.13.0 / pnpm 12.16.1 验证:
|
||||
Verified locally on macOS with Node.js 26.13.0 / pnpm 12.16.1:
|
||||
|
||||
| 检查 | 结果 |
|
||||
| ----------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
|
||||
| `pnpm env:check` | 通过;避免与 pnpm 自带 `doctor` 子命令冲突 |
|
||||
| 冻结锁文件安装、`pnpm peers check` | 通过,无 peer 冲突 |
|
||||
| 全新临时目录 `CI=true HUSKY=0 pnpm install --frozen-lockfile --offline` | 通过,从缓存重建依赖,无需原有 node_modules |
|
||||
| `pnpm check` | 类型、ESLint(零 warning)、Prettier、42 个测试文件 / 146 条测试、生产构建通过 |
|
||||
| `pnpm dev-build` | 通过,输出 `dist/development` 与 sourcemap |
|
||||
| `pnpm report` | 通过,静态报告为 `dist/report/stats.html`,不打开浏览器或保持报告服务器 |
|
||||
| `vite build --configLoader native` | 通过,配置不依赖旧加载器的扩展名猜测 |
|
||||
| 可选 CDN 构建 | 通过;实际引用的 9 个精确版本脚本 URL 全部 HTTP 200,Chrome 登录、首页与 SVG 预览无控制台 error |
|
||||
| `pnpm audit` | 0 info / low / moderate / high / critical;无忽略公告配置 |
|
||||
| `pnpm outdated` | 仅报告 TypeScript 7 的兼容例外与最后版本 CryptoJS 的弃用标记 |
|
||||
| 三个间接依赖覆盖的 API | `uuid.v4/validate`、`globSync/hasMagic`、`minimatch/Minimatch` 调用通过 |
|
||||
| commitlint | 合规消息通过,错误格式消息被拒绝 |
|
||||
| Mock HTTP API | `/api/list?page=2&pageSize=10` 返回 10 条 / total 100;无分页返回 100 条,字段与年龄范围通过 |
|
||||
| Chrome 开发页面 | 演示登录、首页、SVG 菜单图标、ECharts 图表、LogicFlow 节点和二维码渲染通过 |
|
||||
| Chrome 生产预览 | 登录、首页显示真实依赖版本、高级表格中文数据、10→20 条切换、中英文菜单和明暗主题通过,检查时控制台无 error |
|
||||
| Check | Result |
|
||||
| ----------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
||||
| `pnpm env:check` | Passed; avoids colliding with pnpm's built-in `doctor` subcommand |
|
||||
| Frozen-lockfile install, `pnpm peers check` | Passed without peer conflicts |
|
||||
| `CI=true HUSKY=0 pnpm install --frozen-lockfile --offline` in a fresh temporary directory | Passed; reconstructed dependencies from cache without the original node_modules |
|
||||
| `pnpm check` | Types, ESLint (zero warnings), Prettier, 42 test files / 146 tests, and production build passed |
|
||||
| `pnpm dev-build` | Passed; produced `dist/development` and sourcemaps |
|
||||
| `pnpm report` | Passed; static report at `dist/report/stats.html`, without opening a browser or retaining a report server |
|
||||
| `vite build --configLoader native` | Passed; configuration does not depend on legacy extension guessing |
|
||||
| Optional CDN build | Passed; all 9 referenced exact-version script URLs returned HTTP 200. Chrome login, home, and SVG preview had no console errors. |
|
||||
| `pnpm audit` | 0 info / low / moderate / high / critical; no ignored-advisory configuration |
|
||||
| `pnpm outdated` | Reported only the TypeScript 7 compatibility exception and final-release CryptoJS deprecation |
|
||||
| APIs of the three transitive overrides | `uuid.v4/validate`, `globSync/hasMagic`, and `minimatch/Minimatch` calls passed |
|
||||
| commitlint | Accepted valid messages and rejected invalid formats |
|
||||
| Mock HTTP API | `/api/list?page=2&pageSize=10` returned 10 records / total 100; no pagination returned 100. Field and age-range checks passed. |
|
||||
| Chrome development pages | Demo login, home, SVG menu icons, ECharts, LogicFlow nodes, and QR rendering passed |
|
||||
| Chrome production preview | Login, real dependency versions on home, Chinese advanced-table data, 10→20 page-size changes, Chinese/English menus, and light/dark themes passed. No console errors were observed. |
|
||||
|
||||
截图等本机证据位于忽略目录 `.ai-local/evidence/`。`production-home.png` 为生产首页,`production-table-dark.png` 为英文菜单和深色表格,`cdn-svg-icons.png` 为 CDN 构建的图标预览。临时安装、CDN 验证配置和产物不进入提交。
|
||||
Local evidence, including screenshots, is in ignored `.ai-local/evidence/`. `production-home.png` shows the production home page; `production-table-dark.png` shows English menus and a dark table; `cdn-svg-icons.png` shows CDN-build icons. Temporary installs, CDN verification configuration, and outputs are not committed.
|
||||
|
||||
CI 工作流仅完成配置和官方 Action 输入核对,尚未在远端执行。当前机器未安装 Docker,因此 Dockerfile 未做实际镜像构建;也未验证真实后端、无界宿主、其他浏览器、最低版本设备和完整打印/下载链路。
|
||||
At this stage, CI configuration and official Action inputs had been checked, but remote CI had not run. Docker was not installed, so no image build was performed. Real backends, Wujie hosts, other browsers, minimum-version devices, and complete print/download flows were not verified.
|
||||
|
||||
生产构建仍提示一个约 2 MB 的公共 chunk(包含模板公共组件依赖)及 ContentWrapper 同时静态/动态导入;功能检查通过,未提高告警阈值来隐藏问题。后续若做性能专项,应基于静态报告拆解组件导出与加载边界,并重新验证路由缓存及初始化顺序。
|
||||
The production build still reported a shared chunk of about 2 MB, including shared component dependencies, and mixed static/dynamic ContentWrapper imports. Functional checks passed; warning thresholds were not raised to hide these issues. A future performance effort should use the static report to examine component exports and loading boundaries, then reverify route caching and initialization order.
|
||||
|
||||
## 2026-11-03:Hooks、布局和图标改造验证
|
||||
## 2026-11-03: Hook, layout, and icon refactor verification
|
||||
|
||||
未升级依赖或改动锁文件。新增 `icons:generate` / `icons:check`,生成脚本使用项目现有 Prettier 配置输出代码,并保留 ESLint 所需的声明空行。Vite 按顶层分包生成独立雪碧图,名称与类型来自同一目录清单。
|
||||
No dependencies or lockfile entries changed. Added `icons:generate` / `icons:check`. The generator uses the project's existing Prettier configuration and preserves declaration spacing required by ESLint. Vite generates a separate spritemap per top-level group; names and types come from the same directory manifest.
|
||||
|
||||
| 检查 | 实际结果 |
|
||||
| --------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| Node.js 26.13.0、pnpm 12.16.1、冻结锁文件安装、`pnpm env:check` | 通过;本机原有 Node 26.12.1 低于项目要求,本轮使用临时 26.13.0 运行时 |
|
||||
| `pnpm typecheck`(包含 `icons:check`)、`pnpm lint` | 通过,未降低规则或增加全局忽略 |
|
||||
| `pnpm format:check` / `pnpm check` | 格式检查报本地 `TODO.md` 与 `.vscode/settings.json`,保留这两项非本任务变更;`pnpm check` 在格式阶段停止,未声称全绿 |
|
||||
| 本任务修改与新增文件的 Prettier 检查 | 通过;生成清单也由项目 Prettier 配置直接格式化 |
|
||||
| `pnpm test:run` | 单独继续执行,50 个测试文件 / 173 条测试全部通过 |
|
||||
| `pnpm exec vite build` | 单独继续执行并通过;44 个图标输出为 7 个带 hash 的独立包,各包 symbol ID 无重复 |
|
||||
| Chrome 开发版 | 侧边、顶部、混合导航;嵌套页面菜单匹配;定宽 1200px 居中;390px 抽屉打开、选中自动收起且无页面横向溢出;刷新后保留桌面偏好;PNG 截图与元素全屏/恢复 |
|
||||
| Chrome 生产预览 | 演示登录、44 个图标渲染、7 个带 base 的图标资源路径、完整图标复制操作、深色主题、中英文新页面文本、内容最大化及 Esc、页面卸载后刷新恢复、内容滚动到 300px、滚动页脚与既有自适应表格渲染 |
|
||||
| Check | Observed result |
|
||||
| ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| Node.js 26.13.0, pnpm 12.16.1, frozen-lockfile install, `pnpm env:check` | Passed. Existing local Node 26.12.1 was below the requirement, so this run used a temporary 26.13.0 runtime. |
|
||||
| `pnpm typecheck` (including `icons:check`), `pnpm lint` | Passed without weaker rules or new global ignores |
|
||||
| `pnpm format:check` / `pnpm check` | Formatting flagged local `TODO.md` and `.vscode/settings.json`. Preserved those unrelated changes. `pnpm check` stopped at formatting; full success was not claimed. |
|
||||
| Prettier on files added/changed by this task | Passed; generated manifests were also formatted directly with project configuration |
|
||||
| `pnpm test:run` | Run separately; all 50 test files / 173 tests passed |
|
||||
| `pnpm exec vite build` | Run separately and passed; 44 icons produced 7 separate hashed groups with no duplicate symbol IDs within a group |
|
||||
| Chrome development build | Side/top/mixed navigation; nested-page menu matching; centered fixed width at 1200px; opening the drawer at 390px, collapsing after selection, and no page-level horizontal overflow; desktop preferences retained after reload; PNG screenshots and element fullscreen/restore |
|
||||
| Chrome production preview | Demo login; 44 rendered icons; 7 icon asset paths respecting base; complete icon-copy operations; dark theme; Chinese/English new-page copy; content maximization and Esc; restoration after unmount/reload; content scrolled to 300px; scrolling footer and existing auto-height table rendering |
|
||||
|
||||
Pinia 设置沿用原持久化 key,旧裸 Logo 名称在读取时迁移;锁屏仍使用历史布尔值格式。对应迁移、并发刷新、滚动实例替换、导航越界、右键异步关闭、全屏帧清理及截图失败处理均有回归用例。
|
||||
Pinia settings retained existing persistence keys. Legacy bare logo names migrate on read; lock screens still use the historical boolean format. Regressions cover the migration, concurrent refreshes, scroll-instance replacement, out-of-bounds navigation, asynchronous context-menu closure, fullscreen frame cleanup, and screenshot failures.
|
||||
|
||||
本机截图位于 `.ai-local/evidence/2026-11-03/`。文件监听首次触发 EMFILE,本轮开发服务使用 `CHOKIDAR_USEPOLLING=1` 进行验收,未将该环境绕行写入默认开发配置。保留公共 chunk 大小、ContentWrapper 静态/动态导入及 Mock CORS 序列化提示;未调整告警阈值。本轮未验证实际纸张打印、最低版本浏览器或无界宿主。
|
||||
Local screenshots are in `.ai-local/evidence/2026-11-03/`. File watching initially hit EMFILE, so this development verification used `CHOKIDAR_USEPOLLING=1`; the workaround was not added to default development configuration. Shared-chunk size, mixed ContentWrapper imports, and mock CORS serialization warnings remain, without threshold changes. Physical printing, minimum-version browsers, and Wujie hosts were not verified.
|
||||
|
||||
## 2026-11-03:自动同步、注释规范与视觉整理
|
||||
## 2026-11-03: Automatic synchronization, comment conventions, and visual cleanup
|
||||
|
||||
本轮未升级依赖、未改动锁文件。图标生成已接入 `dev`、`build`、`dev-build`、`report`、`check` 与 Vite 构建入口;独立 `typecheck` 和 `icons:check` 保持只读。`AGENTS.md` 引入 [统一注释规范](comment-style.md),页面排版与主题入口见 [视觉约定](ui-design.md)。
|
||||
No dependencies or lockfile entries changed. Icon generation is connected to `dev`, `build`, `dev-build`, `report`, `check`, and the Vite build entry point; standalone `typecheck` and `icons:check` remain read-only. `AGENTS.md` introduced the [shared comment style](comment-style.md). Page layout and theme entry points are in the [visual conventions](ui-design.md).
|
||||
|
||||
| 检查 | 实际结果 |
|
||||
| --------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| 冻结锁文件安装与 `pnpm env:check` | 通过,使用 Node.js 26.13.0 / pnpm 12.16.1 |
|
||||
| `pnpm check` | 图标同步、类型和 ESLint 通过;格式阶段仅报未改动的 `.vscode/settings.json`,未声称全量检查通过 |
|
||||
| `pnpm test:run` | 单独执行,52 个测试文件 / 181 条测试全部通过 |
|
||||
| `pnpm build` | 通过,包含自动生成、类型检查和生产构建;最终为 44 个图标、7 个独立雪碧图 |
|
||||
| 无开发服务参与的构建 | 临时新增 SVG 后先确认 `icons:check` 报清单过期,再直接执行 `pnpm build`,自动生成成功;删除临时 SVG 后再次构建恢复最终产物 |
|
||||
| 实际图标 HMR | 新增、改名、删除自动同步清单;修改内容后资源 hash 改变且保留搜索状态;新增/删除整个分包自动重建插件配置并通知浏览器重载;带连字符的分包名与符号链接路径的 CLI 执行有回归覆盖 |
|
||||
| 注释位置 | 移除组件介绍块和重复堆叠;类型、Store 与常量说明按相邻声明重新核对,修正原登录状态说明中错误的存储介质描述 |
|
||||
| Chrome 排版 | 工作台、Hooks、布局实验室、图标库;1440/1280px 桌面与 390px 单列,无页面横向溢出;保留登录页紧凑资源入口 |
|
||||
| 主题与语言 | 生产页明暗切换、暗色选中态前景、中英文标题;修复热更新后国际化实例被替换导致显示原始键的边界,并覆盖初始化前创建 Hook 后恢复翻译的场景 |
|
||||
| Check | Observed result |
|
||||
| -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| Frozen-lockfile install and `pnpm env:check` | Passed with Node.js 26.13.0 / pnpm 12.16.1 |
|
||||
| `pnpm check` | Icon synchronization, types, and ESLint passed. Formatting flagged only unchanged `.vscode/settings.json`; full-check success was not claimed. |
|
||||
| `pnpm test:run` | Run separately; all 52 test files / 181 tests passed |
|
||||
| `pnpm build` | Passed, including generation, types, and production build; final output contained 44 icons and 7 separate spritemaps |
|
||||
| Build without a development server | After adding a temporary SVG, confirmed `icons:check` reported a stale manifest, then ran `pnpm build` directly and verified automatic generation. Removed the temporary SVG and rebuilt final output. |
|
||||
| Actual icon HMR | Add/rename/delete synchronized the manifest. Content edits changed asset hashes and retained search state. Adding/removing whole groups rebuilt plugin configuration and requested browser reloads. Regressions cover hyphenated group names and CLI execution through symlink paths. |
|
||||
| Comment placement | Removed component introductions and stacked duplicates. Rechecked type, store, and constant descriptions against adjacent declarations; corrected the login-state description's storage medium. |
|
||||
| Chrome layout | Dashboard, hooks, layout lab, and icon library at 1440/1280px desktop and 390px single-column widths, without page-level horizontal overflow. Retained compact login-page resource links. |
|
||||
| Themes and languages | Production light/dark switching, dark selected-state foregrounds, and Chinese/English headings. Fixed raw translation keys after HMR replaced the i18n instance; covered translation recovery for hooks created before initialization. |
|
||||
|
||||
开发验收仍使用本机 `CHOKIDAR_USEPOLLING=1`,未改动默认监听方式。浏览器控制连接在还原视口时中断,后续通过 Chrome 开发者工具的独立上下文核对最终生产产物;最终截图与阶段记录放在 `.ai-local/evidence/2026-11-03/polish/`。复杂基础组件自身的 Vue JSX 热替换场景未穷尽,生产验收基于最终完整加载的产物;没有把这些检查写成真实后端、最低版本设备或实体打印验收。
|
||||
Development verification still used local `CHOKIDAR_USEPOLLING=1` without changing the default watcher. The browser-control connection broke while restoring the viewport. A separate Chrome DevTools context then checked the final production artifacts. Final screenshots and phase records are in `.ai-local/evidence/2026-11-03/polish/`. Vue JSX hot replacement inside complex base components was not exhaustively tested. Production acceptance used freshly loaded final artifacts; these checks were not presented as real-backend, minimum-device, or physical-printing verification.
|
||||
|
||||
公共 chunk 大小、ContentWrapper 静态/动态导入与 Mock CORS 序列化提示仍保留,未降低检查严格度或调高告警门槛。
|
||||
Shared-chunk size, mixed static/dynamic ContentWrapper imports, and mock CORS serialization warnings remain. Neither check strictness nor warning thresholds were relaxed.
|
||||
|
||||
## 2026-11-03 TypeScript 项目配置拆分
|
||||
## 2026-11-03: TypeScript project configuration split
|
||||
|
||||
旧配置只在 `vue-tsc` 命令行传入 `--noEmit`。直接读取项目配置时,`allowImportingTsExtensions` 会触发 TS5096。现在共享配置声明 `noEmit`,由根项目分别引用应用、Node 与测试配置。Vue JSX 和自动导入声明由应用及测试配置加载。TypeScript 6 的 `DOM` 已包含可迭代声明,Vite 继续通过 `build.sourcemap` 控制开发和生产的 sourcemap。
|
||||
The previous setup passed `--noEmit` only to the `vue-tsc` command. Reading project configuration directly caused `allowImportingTsExtensions` to trigger TS5096. Shared configuration now declares `noEmit`; the root references application, Node, and test configurations separately. Application/test configurations load Vue JSX and auto-import declarations. TypeScript 6's `DOM` includes iterable declarations. Vite still controls development/production sourcemaps through `build.sourcemap`.
|
||||
|
||||
依赖与锁文件沿用当前版本。完整命令和项目归属见 [TypeScript 项目配置](architecture.md#typescript-项目配置)。
|
||||
Dependencies and the lockfile retained their existing versions. Commands and project ownership are in [TypeScript project configuration](architecture.md#typescript-project-configuration).
|
||||
|
||||
在 Node.js 26.13.0 与 pnpm 12.16.1 下,`pnpm check` 通过类型、ESLint、Prettier、59 个测试文件的 240 个用例和生产构建。`pnpm dev-build` 通过,并生成开发版 JS sourcemap。通过 TypeScript 服务核对了应用入口、Vite 配置、Mock 文件和测试文件各自使用的项目。
|
||||
With Node.js 26.13.0 and pnpm 12.16.1, `pnpm check` passed types, ESLint, Prettier, 59 test files / 240 cases, and the production build. `pnpm dev-build` passed and produced development JS sourcemaps. The TypeScript service confirmed project ownership for the application entry point, Vite configuration, mock files, and tests.
|
||||
|
||||
## 2026-11-03 AI Harness 迁移
|
||||
## 2026-11-03: AI Harness migration
|
||||
|
||||
任务入口、范围清单和验收命令集中在 [AI Harness](../harness/README.md)。GitHub Actions 通过 `pnpm check` 校验上下文与回归路径。旧工具配置和旧开发指南已移除,TypeScript 增量缓存迁至 `node_modules/.cache/ray-template/`。依赖与锁文件沿用当前版本。
|
||||
Task entry points, scope registration, and verification commands were consolidated in the [AI Harness](../harness/README.md). GitHub Actions validates context and regression paths through `pnpm check`. Removed old tool configuration and developer guides. TypeScript incremental caches moved to `node_modules/.cache/ray-template/`. Dependencies and lockfile versions stayed unchanged.
|
||||
|
||||
本机 macOS 使用 Node.js 26.13.0 和 pnpm 12.16.1。六个任务域的定向验证均通过。新增回归覆盖空测试目录,以及子命令失败时的退出码、停止执行和 JSON 报告。`pnpm harness verify` 通过 Harness 校验、类型、ESLint、Prettier、60 个测试文件的 242 个用例和生产构建。
|
||||
Local macOS verification used Node.js 26.13.0 and pnpm 12.16.1. Targeted checks passed for all six task scopes. New regressions cover empty test directories and exit codes, fail-fast behavior, and JSON reports when child commands fail. `pnpm harness verify` passed Harness validation, types, ESLint, Prettier, 60 test files / 242 cases, and the production build.
|
||||
|
||||
本机报告保存在 `.harness-local/runs/`,`npm pack --dry-run --ignore-scripts` 确认本机证据目录不进入发布包。Windows 和 Linux 的执行结果待远端 CI 验证,浏览器验收按 Harness 中的独立步骤执行。
|
||||
Reports are saved in `.harness-local/runs/`. `npm pack --dry-run --ignore-scripts` confirmed that local evidence directories were excluded from the package. Windows/Linux results awaited remote CI. Browser verification follows the separate Harness steps.
|
||||
|
||||
## 2026-11-03 组件目录与公开演示的检索配置
|
||||
## 2026-11-03: Component directories and public demo discovery
|
||||
|
||||
通用组件统一放在 `src/components`,保留 `@/components` 入口并删除没有调用方的 `RCollapse`。双语 README 补充实际工作台截图、快速开始和二次开发入口。公开构建的 canonical、分享图和 sitemap 按 Vite base 生成,配置方式见[部署指南](architecture.md#deployment-and-search-discovery)。
|
||||
Shared components were consolidated in `src/components`, retaining `@/components` and removing the unused `RCollapse`. Bilingual READMEs gained actual dashboard screenshots, quick-start instructions, and customization entry points. Public-build canonical metadata, sharing images, and sitemaps follow the Vite base; see the [deployment guide](architecture.md#deployment-and-search-discovery).
|
||||
|
||||
- `pnpm harness verify` 通过类型、ESLint、Prettier、63 个测试文件的 265 个用例和生产构建。
|
||||
- 检查了官方路径、自定义子路径与未设置站点源地址的构建。公开版本的首页、sitemap 和资源 URL 一致;普通构建输出 `noindex`。
|
||||
- Chrome 生产预览验证了桌面双列、390px 单列、中英文与明暗切换、预填演示登录,以及关闭 JavaScript 时的项目介绍和链接。GitHub About 描述、演示地址和主题已回读确认;未部署网站构建或验证搜索引擎收录。
|
||||
- `pnpm harness verify` passed types, ESLint, Prettier, 63 test files / 265 cases, and the production build.
|
||||
- Checked builds for the official path, a custom subpath, and an unset site origin. Public home, sitemap, and resource URLs were consistent; ordinary builds emitted `noindex`.
|
||||
- Chrome production previews verified desktop two-column and 390px single-column layouts, Chinese/English and light/dark switching, prefilled demo login, and project information/links with JavaScript disabled. GitHub About description, demo URL, and topics were read back and confirmed. Site builds were not deployed, and search-engine indexing was not verified.
|
||||
|
||||
## 2026-11-04 GitHub Pages 静态发布
|
||||
## 2026-11-04: Static GitHub Pages deployment
|
||||
|
||||
线上首页与 `dist` 分支的 `index.html` 一致,引用的 `js/_toKey-BqfG5Sv9.js` 在分支中存在,Pages 却返回 404。发布根目录缺少 `.nojekyll`,Jekyll 默认过滤下划线开头的文件。Vite 现在将 `public/.nojekyll` 复制到发布根目录,部署约定见[架构地图](architecture.md#deployment-and-search-discovery)。
|
||||
The live home page matched `index.html` on the `dist` branch, and the referenced `js/_toKey-BqfG5Sv9.js` existed on that branch, yet Pages returned 404. The deployment root lacked `.nojekyll`, so Jekyll filtered underscore-prefixed files. Vite now copies `public/.nojekyll` to the deployment root. See the [architecture map](architecture.md#deployment-and-search-discovery) for deployment conventions.
|
||||
|
||||
- 干净的 `HEAD` 加本次修复复用本机已安装依赖执行 `pnpm harness verify`,66 个测试文件的 285 个用例与生产构建通过。原工作区的全量检查在 `__test__/router/config.spec.ts` 初始化时失败,独立执行 `pnpm build` 通过。
|
||||
- 构建产物包含 `.nojekyll`。生产预览首页引用的 12 个 JS 和 CSS 资源均返回 HTTP 200,内容与产物一致。Chrome 使用演示账号进入首页,控制台无错误。GitHub Pages 待部署后回查。
|
||||
- A clean `HEAD` plus this fix reused installed local dependencies to run `pnpm harness verify`; 66 test files / 285 cases and the production build passed. Full checks in the original worktree failed while initializing `__test__/router/config.spec.ts`; standalone `pnpm build` passed.
|
||||
- Build output contained `.nojekyll`. All 12 JS/CSS assets referenced by the production-preview home page returned HTTP 200 with content matching the output. Chrome entered home using the demo account without console errors. GitHub Pages required a post-deployment recheck.
|
||||
|
||||
## 2026-11-04 文档工作区与页内示例
|
||||
## 2026-11-04: Documentation workspace and inline examples
|
||||
|
||||
文档迁入 `apps/docs`,与后台和 `packages/utils` 共用根锁文件。VitePress `1.6.4` 使用 Vite `6.4.5`,覆盖只作用于 VitePress;后台保留 Vite `8.3.5`。`@/utils/precision` 转发共享包,RBarcode 仍由应用维护,文档按需加载原组件。
|
||||
Documentation moved into `apps/docs`, sharing the root lockfile with the admin application and `packages/utils`. VitePress `1.6.4` uses Vite `6.4.5`; the override applies only to VitePress, while the admin application retains Vite `8.3.5`. `@/utils/precision` re-exports the shared package. RBarcode was still maintained by the application and loaded on demand by documentation.
|
||||
|
||||
- 本机 macOS(Node.js 26.13.0、pnpm 12.16.1)通过 `pnpm harness verify`,含 66 个测试文件、291 个用例,以及应用和文档生产构建。报告:`.harness-local/runs/all-ukYffY/report.json`。
|
||||
- 检查了 93 个旧路径的目标页和锚点。Chrome 在生产子路径验证了精度输入、条码重绘与非法输入恢复、示例代码、搜索、旧路径跳转、明暗切换和 390px 布局。
|
||||
- 当前只验证了本地构建。Docker 镜像、远端 CI 和 GitHub Pages 迁址未验证。
|
||||
- Local macOS verification with Node.js 26.13.0 and pnpm 12.16.1 passed `pnpm harness verify`: 66 test files, 291 cases, and application/documentation production builds. Report: `.harness-local/runs/all-ukYffY/report.json`.
|
||||
- Checked target pages and anchors for 93 legacy paths. Chrome verified precision input, barcode redraw and invalid-input recovery, example code, search, legacy redirects, light/dark switching, and 390px layouts under the production subpath.
|
||||
- Only local builds were verified. Docker images, remote CI, and the GitHub Pages site migration were not verified.
|
||||
|
||||
## 2026-11-04 Ray Admin 与共享能力拆分
|
||||
## 2026-11-04: Separating Ray Admin and shared capabilities
|
||||
|
||||
Ray Admin 的应用入口迁到 `apps/admin`,文档和应用经公开入口使用八个共享包。根目录保留开发、构建和 Harness 命令,应用与文档的 Vite 版本分别锁定。`pnpm pages:build` 生成组合产物,配置站点源地址后另生成旧文档跳转产物。
|
||||
Ray Admin's application entry point moved to `apps/admin`. Documentation and the application consume eight shared packages through public entry points. Development, build, and Harness commands remain at the root; application/documentation Vite versions are pinned separately. `pnpm pages:build` produces combined output and, when a site origin is configured, separate legacy-documentation redirects.
|
||||
|
||||
- Node.js 26.13.0、pnpm 12.16.1 下冻结锁文件安装及 `pnpm harness verify` 通过。含包边界检查、独立类型检查、68 个测试文件的 293 个用例,以及后台和文档生产构建。报告位于 `.harness-local/runs/all-GPS5No/report.json`。
|
||||
- 开发服务器的 `/api/list` 返回 HTTP 200。Chrome 生产预览验证了演示登录、导航偏好刷新恢复、图标和文档交互,覆盖 TablePro 取消及失败重试、外壳导航和主题、精度工具、条码、路由校验、防抖和全屏。检查了 93 个旧路径的目标和锚点,并生成 138 个旧站跳转页。
|
||||
- Docker、无界宿主和远端 CI 未运行。旧站迁址需在 GitHub Pages 发布时另行验收。
|
||||
- Frozen-lockfile installation and `pnpm harness verify` passed with Node.js 26.13.0 and pnpm 12.16.1, including package boundaries, independent type checks, 68 test files / 293 cases, and admin/documentation production builds. Report: `.harness-local/runs/all-GPS5No/report.json`.
|
||||
- Development `/api/list` returned HTTP 200. Chrome production previews verified demo login, navigation-preference restoration after reload, icons, and documentation interactions: TablePro cancellation/failure retry, shell navigation/themes, precision utilities, barcodes, route validation, debounce, and fullscreen. Checked targets/anchors for 93 legacy paths and generated 138 legacy-site redirects.
|
||||
- Docker, Wujie hosts, and remote CI were not run. The legacy-site migration required separate verification when published to GitHub Pages.
|
||||
|
||||
## 2026-11-04 文档示例与后台主题联动
|
||||
## 2026-11-04: Documentation examples and admin theme integration
|
||||
|
||||
文档的组件预览复用后台的 Naive UI 明暗主题和语言配置。页内示例隔离 VitePress 正文样式,依赖后台上下文的示例由 Pages 同一次构建中的 `example.html` 运行。示例宿主只注册演示路由,使用内存缓存和独立 Store,文档直接引用运行的源码。
|
||||
Documentation component previews reuse the admin application's Naive UI light/dark themes and locale configuration. Inline examples isolate VitePress article styles. Examples requiring application context run through `example.html` from the same Pages build. The example host registers only demo routes, uses in-memory caching and an independent store, and documentation includes the source actually running.
|
||||
|
||||
`pnpm harness verify` 通过 69 个测试文件的 294 个用例。合并产物核对了 22 个文档页中的 26 处内嵌入口和源码。Chrome 生产预览验证了 TablePro 样式、明暗主题、中文分页及失败重试,抽测了组件、指令、Hooks、工具交互和正常后台登录入口。桌面和 390px 预览中的边框内边距均为 12px。
|
||||
`pnpm harness verify` passed 69 test files / 294 cases. Checked 26 embedded entry points and source references across 22 documentation pages in the combined output. Chrome production previews verified TablePro styling, light/dark themes, Chinese pagination, and failure retry; sampled component, directive, hook, and utility interactions and the normal admin login entry point. Border padding was 12px in desktop and 390px previews.
|
||||
|
||||
## 2026-11-05 HTTP Mock 与服务端契约
|
||||
## 2026-11-05: HTTP mocks and backend contracts
|
||||
|
||||
演示已统一为 MSW 2.11.6:启动时等待 Service Worker 就绪,开发、生产预览与 GitHub Pages 复用同一套处理器。移除了仅开发可用的旧 Vite Mock 插件和生产直接调用本地人员数据的分支。初始路由迁入 Mock JSON,在线读写使用标准 GET/PUT 接口;组件白名单和外壳路由仍由前端持有。
|
||||
Demos now use MSW 2.11.6 consistently. Startup waits for Service Worker readiness; development, production previews, and GitHub Pages share handlers. Removed the development-only Vite mock plugin and the production branch that called local person data directly. Initial routes moved to mock JSON; online reads/writes use standard GET/PUT APIs. The frontend still owns the component allowlist and shell routes.
|
||||
|
||||
浏览器验收复现了 MSW 3.x 约五分钟后失去拦截的[已知问题](https://github.com/mswjs/msw/issues/2801),因此固定使用 2.11.6。业务请求前探测 Mock 标记,丢失时通过公开 stop/start API 恢复;恢复失败时阻止业务请求穿透。上游修复并通过长时运行与后台恢复验收后再评估升级。官方 worker 保持原样,不手工修改库的消息协议。
|
||||
Browser verification reproduced the [known MSW 3.x issue](https://github.com/mswjs/msw/issues/2801) in which interception stops after about five minutes, so the dependency was pinned to 2.11.6. Before business requests, probe the mock marker; if missing, recover through public stop/start APIs. Block business requests from falling through if recovery fails. Reassess the upgrade after an upstream fix passes long-running and background-resume verification. Keep the official worker unchanged; do not modify library message protocols manually.
|
||||
|
||||
`pnpm api:generate` 从运行时 Schema 生成可下载的 OpenAPI 3.1;`pnpm api:check` 校验契约和 MSW 官方 worker 同步,并纳入全量检查。递归路由 Schema 的引用定位到所属 OpenAPI 组件,回归测试检查全部引用可解析。Node/pnpm 版本保持清单要求。接入与部署边界见[服务端指南](../apps/docs/guide/backend.md)。
|
||||
`pnpm api:generate` creates downloadable OpenAPI 3.1 from runtime schemas. `pnpm api:check` checks contract/official MSW worker synchronization and is included in full checks. Recursive route-schema references point to their owning OpenAPI components, and regressions verify that all references resolve. Node/pnpm requirements remain as specified by manifests. Integration/deployment boundaries are in the [backend guide](../apps/docs/guide/backend.md).
|
||||
|
||||
- Node.js 26.13.0、pnpm 12.16.1 下,`pnpm harness verify` 通过类型、Lint、格式、包边界、79 个测试文件的 357 个用例,以及后台和文档生产构建。报告:`.harness-local/runs/all-z0kewW/report.json`。
|
||||
- 浏览器完成用户增删改查、重复输入与取消、批量操作、只读账号、收藏与历史隔离、键盘搜索、接口路由保存和刷新读回。1280px 桌面与 390px 窄屏验证两个区域独立滚动、中英文及明暗主题;文档契约入口返回最终 JSON。证据:`.harness-local/browser/admin-2026-11-05/report.json`。
|
||||
- Chrome 自动化连接中断后,完整生产验收使用独立的内置 Chromium 预览。长时间操作后 Mock 请求仍由 Service Worker 返回;当前浏览器工具不支持强制终止 worker,恢复并发与失败阻断由回归测试覆盖。未连接真实后端,未部署或运行远端 CI。
|
||||
- With Node.js 26.13.0 and pnpm 12.16.1, `pnpm harness verify` passed types, lint, formatting, package boundaries, 79 test files / 357 cases, and admin/documentation production builds. Report: `.harness-local/runs/all-z0kewW/report.json`.
|
||||
- Browser verification covered user CRUD, repeated input and cancellation, bulk operations, read-only accounts, favorite/history isolation, keyboard search, API-route saving, and reload readback. Verified independent scrolling in both regions, Chinese/English, and light/dark themes at 1280px desktop and 390px narrow widths. The documentation contract endpoint returned final JSON. Evidence: `.harness-local/browser/admin-2026-11-05/report.json`.
|
||||
- After the Chrome automation connection failed, full production acceptance used an independent embedded Chromium preview. Mock requests still came from the Service Worker after extended operation. The available browser tools could not forcibly terminate the worker; regressions covered concurrent recovery and failure blocking. No real backend was connected, and neither deployment nor remote CI ran.
|
||||
|
||||
## 参考资料
|
||||
## 2026-11-06: Harness review and scoped verification
|
||||
|
||||
Official-guidance comparisons, structural assessment, and findings are in the [Harness review record](../harness/plan.md#2026-11-06-structure-review-and-verification-scope). Root guidance, the PR template, topic indexes, visual conventions, and reader guides now select verification by impact: local fixes use relevant tests or scopes, visible behavior uses affected pages/dimensions, and integration risk, releases, or explicit requests trigger full checks. Targeted `api` and `icons` entry points now include existing generated-artifact synchronization checks.
|
||||
|
||||
Local macOS verification used Node.js 26.13.0 and pnpm 12.16.1:
|
||||
|
||||
- `pnpm harness check` passed. All 10 topics are reachable; all 81 test files are registered in at least one scope.
|
||||
- `pnpm harness verify harness` passed 11 cases covering targeted scope, fail-fast behavior, and full-check compatibility. Report: `.harness-local/runs/harness-MadWUc/report.json`.
|
||||
- Ran `pnpm harness verify all` once to verify this change to verification entry points. Types, ESLint, formatting, API/package boundaries, 81 test files / 371 cases, and admin/documentation builds passed. Report: `.harness-local/runs/all-3iyfPu/report.json`; complete output: `.harness-local/harness-review-2026-11-06.log`.
|
||||
- After updating remaining old rules in the public tooling guide, reran only affected `pnpm harness verify docs` and changed-file format/index checks. Documentation types, links, and build passed. Report: `.harness-local/runs/docs-Uge4Sg/report.json`.
|
||||
|
||||
No page behavior changed, so no UI/UX browser matrix was run. Remote CI and deployment were not run. Large-chunk and mixed static/dynamic import warnings remain, as do Node's experimental localStorage notices; these existing issues were outside this task. Passing commands does not establish browser or real-backend acceptance.
|
||||
|
||||
## 2026-11-06: English agent and maintainer guidance
|
||||
|
||||
Translated agent entry points, Harness topics and workflow, internal architecture/convention/history records, source-adjacent maintenance guides, CLI messages, and matching regression assertions into English. Root guidance now records this language convention. Product copy, public reader documentation, code examples, and the existing Chinese code-comment policy retain their intended languages. Commands, scope IDs, report fields, and verification triggers are unchanged by this translation pass.
|
||||
|
||||
- The translation covers 41 internal files. Hash comparisons confirmed that 99 protected product/reader files were unchanged from the start of this pass.
|
||||
- Static review confirmed unchanged link destinations and fenced code examples, valid local links and translated heading anchors, and unchanged scope commands. Remaining Chinese text consists of literal UI/brand names and code-comment examples.
|
||||
- `pnpm harness check`, targeted ESLint, and formatting checks passed. `pnpm harness verify harness` passed all 11 cases; report: `.harness-local/runs/harness-MVuum9/report.json`.
|
||||
- Local translation evidence is in `.harness-local/english-guidance/`. This pass did not rerun full application checks or browser acceptance because no application behavior or rendering changed.
|
||||
|
||||
## References
|
||||
|
||||
- [Node.js 26.13.0 LTS](https://nodejs.org/en/blog/release/v26.13.0)
|
||||
- [Vite 8 迁移说明](https://vite.dev/guide/migration)
|
||||
- [Vitest 5 迁移说明](https://vitest.dev/guide/migration/)
|
||||
- [Vue Router 5 迁移说明](https://router.vuejs.org/guide/migration/v4-to-v5)
|
||||
- [Vue Language Tools 的 TypeScript 7 支持进度](https://github.com/vuejs/language-tools/issues/5381)
|
||||
- [SVG Spritemap 子路径部署](https://spiriitlabs.github.io/vite-plugin-svg-spritemap/guide/deployment.html)
|
||||
- [Faker 本地化](https://fakerjs.dev/guide/localization.html)
|
||||
- [Vite 8 migration guide](https://vite.dev/guide/migration)
|
||||
- [Vitest 5 migration guide](https://vitest.dev/guide/migration/)
|
||||
- [Vue Router 5 migration guide](https://router.vuejs.org/guide/migration/v4-to-v5)
|
||||
- [Vue Language Tools TypeScript 7 support](https://github.com/vuejs/language-tools/issues/5381)
|
||||
- [SVG Spritemap subpath deployment](https://spiriitlabs.github.io/vite-plugin-svg-spritemap/guide/deployment.html)
|
||||
- [Faker localization](https://fakerjs.dev/guide/localization.html)
|
||||
|
||||
### 远端 CI 回查
|
||||
### Remote CI follow-up
|
||||
|
||||
[历史 Ubuntu 失败](https://github.com/XiaoDaiGua-Ray/ray-template/actions/runs/41588971650) 的失败项为 `detectOperatingSystem.spec.ts`。测试读取 Linux 运行器的真实 user agent,断言固定期待 `Unknown`。提交 `83bada95` 使用模拟 user agent 和触点数量覆盖各系统。当前基线 `80e80775` 的 [CI](https://github.com/XiaoDaiGua-Ray/ray-template/actions/runs/41612553267) 已通过 Ubuntu、macOS、Windows 和部署。现有矩阵继续运行同一条 `pnpm check`。
|
||||
The [historical Ubuntu failure](https://github.com/XiaoDaiGua-Ray/ray-template/actions/runs/41588971650) was in `detectOperatingSystem.spec.ts`: the test read the Linux runner's actual user agent but always expected `Unknown`. Commit `83bada95` covers systems with mocked user agents and touch-point counts. [CI](https://github.com/XiaoDaiGua-Ray/ray-template/actions/runs/41612553267) for recorded baseline `80e80775` passed Ubuntu, macOS, Windows, and deployment. The matrix continues to run the same `pnpm check`.
|
||||
|
||||
@ -1,30 +1,30 @@
|
||||
# 页面视觉与排版
|
||||
# Visual design and page layout
|
||||
|
||||
模板采用克制的蓝色与中性色。精致感来自一致的层级、间距与密度,而非给每个区域增加阴影或装饰。
|
||||
The template uses restrained blues and neutral colors. Refinement comes from consistent hierarchy, spacing, and density rather than adding shadows or decoration to every region.
|
||||
|
||||
## 主题与尺度
|
||||
## Themes and dimensions
|
||||
|
||||
- 页面背景、卡片、分割线与文字优先使用 `src/styles/design-system.scss` 中的语义变量。Naive UI 的主题覆盖集中在 `src/app-config/design-config.ts`,保持同一色阶,避免页面单独拼出另一套主题。
|
||||
- `src/styles/base.scss` 是全局样式入口,`design-system.scss` 管理主题变量与基础焦点样式,`setting.scss` 管理布局尺度。`naive.scss` 仅维护模板通用的控件默认值;布局与组件内部规则放在对应组件目录,避免影响嵌套的 Naive UI 实例。
|
||||
- 控件通常为 8px 圆角、卡片为 12px;页面区块间距使用 20–28px。强调色用于选择与主要操作,正文、说明、眉题使用不同文字层级。
|
||||
- 顶栏、标签栏和侧栏使用轻分割线,不叠加区域阴影;少量内容卡片使用两层轻阴影。
|
||||
- 页面标签平时只显示名称。可关闭的标签在悬停或聚焦时展开关闭按钮,触屏设备可在当前标签直接关闭。
|
||||
- 偏好抽屉按可用宽度使用双列或单列字段。分类导航和恢复默认操作放在统一位置。
|
||||
- 内容最大化时,布局提供置顶的退出操作,使用按钮或 Esc 恢复。
|
||||
- 页面标题复用 `AppPageHeader`:眉题、一个主标题、简短说明与可选操作区。不要以大段说明或同等权重的卡片标题代替页面层级。
|
||||
- Prefer semantic variables in `apps/admin/src/styles/design-system.scss` for page backgrounds, cards, dividers, and text. Naive UI theme overrides live in `apps/admin/src/app-config/design-config.ts`. Keep a consistent color scale instead of inventing a separate theme for each page.
|
||||
- `apps/admin/src/styles/base.scss` is the global style entry point. `design-system.scss` owns theme variables and basic focus styles; `setting.scss` owns layout dimensions. Keep `naive.scss` limited to shared control defaults. Put layout/component-specific rules in the owning directory to avoid affecting nested Naive UI instances.
|
||||
- Controls generally use 8px radii, cards 12px, and page sections 20–28px spacing. Use accent colors for selection and primary actions; distinguish body text, descriptions, and eyebrow labels by color hierarchy.
|
||||
- Use subtle dividers between top bars, tab bars, and sidebars rather than layered shadows. A small number of content cards may use two-layer shadows.
|
||||
- Page tabs normally show only their names. Reveal the close button on hover or focus; touch users can close the active tab directly.
|
||||
- The preference drawer uses one or two field columns according to available width. Keep section navigation and reset actions in consistent positions.
|
||||
- When content is maximized, provide an exit control above the content, accessible by button or Esc.
|
||||
- Reuse `AppPageHeader` for page headings: an eyebrow, one main title, a short description, and optional actions. Do not replace page hierarchy with long descriptions or equally prominent card headings.
|
||||
|
||||
## 页面组织
|
||||
## Page composition
|
||||
|
||||
- 工作台与说明型示例限制到 1360px 并居中;业务表格仍遵循用户的流式/定宽布局设置,不全局强行收窄。
|
||||
- 示例使用 `DemoPage` 和 `HookExample`,按功能分组;将交互区域和可展开的代码区域分开。代码展开使用原生 details,支持键盘操作,并保留复制入口。
|
||||
- Hooks 在内容容器达到 900px 后显示双列;布局实验室在 760px 后使用设置/预览双栏。容器不足时按默认单列堆叠,判断可用内容宽度,不只看整个浏览器窗口。
|
||||
- 先复用现有 Naive UI 与模板组件,再补少量排版结构。不为展示效果编造统计数据;工作台版本号读取实际 package 配置,快捷入口跟随可见菜单。
|
||||
- 共用组件的不同调用场景分别保留:例如资源链接在登录页保持 compact,在工作台使用 cards,不以统一排版破坏原有页面约束。
|
||||
- Limit dashboard and explanatory demo content to 1360px and center it. Business tables continue to honor fluid/fixed-width layout preferences; do not narrow them globally.
|
||||
- Use `DemoPage` and `HookExample`, grouped by function. Separate interactive content from expandable code. Use native details elements for code, retain keyboard operation, and provide copying.
|
||||
- Hook examples use two columns when the content container reaches 900px. The layout lab uses settings/preview columns at 760px. Default to a single stacked column below those thresholds. Base decisions on available content width, not only browser-window width.
|
||||
- Reuse Naive UI and template components before adding small layout structures. Do not invent statistics for visual effect. Read the dashboard version from the actual package configuration and derive shortcuts from visible menus.
|
||||
- Preserve distinct uses of shared components. For example, resource links remain compact on login pages and cards on the dashboard; visual consistency must not break existing page constraints.
|
||||
|
||||
## 验证
|
||||
## Verification
|
||||
|
||||
检查桌面与 390px 窄屏、明暗主题、中英文、长代码和操作按钮换行。默认正文用色按至少 4.5:1、输入框等控件边界按至少 3:1 选取;用户自定义主色仍需按实际组合确认。
|
||||
Choose affected pages and dimensions using [Harness browser verification](../harness/README.md#browser-verification): desktop and 390px widths for layout changes, light/dark themes for color changes, Chinese/English for copy changes, and wrapping for changes to long code or button layouts. Local changes do not trigger a site-wide or all-dimensions matrix. Choose default body-text colors for at least 4.5:1 contrast and control boundaries such as inputs for at least 3:1. User-selected primary colors still need checking in their actual combinations.
|
||||
|
||||
保留 `forced-colors` 系统颜色回退、可见键盘焦点与减少动态效果设置。截图、颜色数值与浏览器检查不能互相替代,也不代表已验证全部最低版本设备。
|
||||
Preserve system-color fallbacks for `forced-colors`, visible keyboard focus, and reduced-motion settings. Screenshots, color measurements, and browser checks do not substitute for one another and do not establish coverage of all minimum-version devices.
|
||||
|
||||
登录页在宽屏并排显示品牌区和登录区,窄屏按文档顺序堆叠。Ray 标识用带两颗瓜籽的青瓜切面表现「呆瓜」,资源见 [SVG](../packages/icons/src/logo/ray.svg)。示例应用默认关闭 HTML 自动填充,含延迟渲染和 Teleport 控件。需要允许时,在目标控件显式提供 `autocomplete`,Naive UI 的输入组件使用 `inputProps`。
|
||||
On wide screens, the login page places branding and login content side by side; narrow screens stack them in document order. The Ray mark is a cucumber cross-section with two seeds representing “呆瓜”; see the [SVG](../packages/icons/src/logo/ray.svg). The example application disables HTML autofill by default, including delayed and Teleport controls. To allow it, supply `autocomplete` explicitly on the target control; use `inputProps` for Naive UI inputs.
|
||||
|
||||
@ -1,65 +1,90 @@
|
||||
# Ray Template AI Harness
|
||||
|
||||
从 [AGENTS.md](../AGENTS.md) 进入。需要查实现时,从 [任务索引](../llms.txt) 打开相关主题;跨模块关系见 [架构地图](../docs/architecture.md)。只阅读索引无需安装依赖。
|
||||
Start with [AGENTS.md](../AGENTS.md). Use the [task index](../llms.txt) to locate implementations and the [architecture map](../docs/architecture.md) for relationships across modules. Reading the indexes does not require installing dependencies.
|
||||
|
||||
## 开始任务
|
||||
## Starting a task
|
||||
|
||||
1. 查看 `git status`。用静态入口或 `pnpm harness context` 选择任务域;`pnpm harness context <scope>` 显示对应索引及验证命令。跨域变更分别查看受影响的任务域。
|
||||
2. 需要运行验证时,根据 `.nvmrc` 和 `package.json#packageManager` 选择运行时,首次执行 `pnpm install --frozen-lockfile` 和 `pnpm env:check`。
|
||||
3. 明确可观察的验收条件,按需决定是否使用 subagent,追踪调用方和数据流后实施。多步迁移或跨会话接续时,记录范围、分阶段验收、关键决策与剩余项。可参考 [建设计划](plan.md)。
|
||||
4. 先运行定向验证,最后运行全量验收。
|
||||
1. Check `git status`. Choose a task area from the static index or `pnpm harness context`; `pnpm harness context <scope>` shows its index and verification commands. For changes across areas, consult each affected scope.
|
||||
2. When verification is needed, select the runtime from `.nvmrc` and `package.json#packageManager`. On initial setup, run `pnpm install --frozen-lockfile` and `pnpm env:check`.
|
||||
3. Define observable acceptance criteria, decide whether subagents would help, and trace callers and data flow before implementation. For multi-step migrations or work continued across sessions, record scope, staged acceptance criteria, key decisions, and remaining work. See the [development plan](plan.md) as a reference.
|
||||
4. Choose checks using the [verification scope](#choosing-the-verification-scope). Run relevant tests during development and confirm coverage at task completion. Run full checks only when a full-check condition applies. After checks pass, rerun only those affected by subsequent changes.
|
||||
|
||||
```sh
|
||||
pnpm harness context table-pro
|
||||
pnpm harness verify table-pro
|
||||
pnpm harness verify
|
||||
```
|
||||
|
||||
## 按需使用 subagent
|
||||
## Using subagents when useful
|
||||
|
||||
- **决定是否委派。** 子任务边界清楚、结果可独立验收,且并行调查、分头实现或独立复核的收益大于沟通与合并成本时,可以启用 subagent。简单任务、步骤相互依赖或需要频繁协调共享文件的任务,通常由主模型直接处理。宿主没有提供 subagent 或当前任务不允许委派时,主模型继续执行。
|
||||
- **划清任务边界。** 交代目标、相关任务域、验收条件及只读或可写范围。并行实现时,每个文件只交给一方修改;边界未定时可先委派只读调查。委派沿用用户授权和仓库规则。
|
||||
- **核对并整合结果。** 子代理回传发现、改动、实际验证及未验证项。主模型复核并整合结果;有实现改动时,由主模型执行全量验收。
|
||||
- **Decide whether to delegate.** Use subagents when tasks have clear boundaries, results can be verified independently, and parallel investigation, implementation, or review is worth the coordination and integration cost. Handle simple tasks, dependent steps, or frequent edits to shared files directly. If the host does not provide subagents or the current task prohibits delegation, the lead agent continues the work.
|
||||
- **Define ownership.** Specify the objective, relevant scopes, acceptance criteria, and read-only or writable boundaries. Assign each file to one writer during parallel implementation. Start with read-only investigation if boundaries are unclear. Delegation inherits user authorization and repository rules.
|
||||
- **Review and integrate.** Subagents report findings, changes, actual verification, and unverified areas. The lead agent reviews the combined impact and completes integration checks. Delegation itself does not trigger full verification; select scope using the rules below.
|
||||
|
||||
## 工程约定
|
||||
## Engineering conventions
|
||||
|
||||
- 新增能力或组件前,先检索并查看项目现有组件、Hooks 与已安装组件库的 API 和调用示例,确认是否能通过既有 Props、插槽或布局 CSS 组合实现。已有能力足够时直接复用;只有确认存在能力缺口时才新增组件,并在现有任务记录或交付说明中交代缺口与选择。不要仅因需要撑满高度、滚动容器或一层样式包装就创建新组件。
|
||||
- UI 沿用 Vue 3 Composition API、`defineComponent` + TSX 与现有 SFC 的 `<script setup lang="ts">`,优先复用 Naive UI 和项目组件。图表使用 ECharts。
|
||||
- Vue、Router 和 Pinia API 由 `unplugin-auto-import` 管理。类型使用 `import type`,生成声明通过生成器更新。
|
||||
- 路由维持名称唯一、权限 meta、缓存和翻译键。变更权限时同时验证菜单可见性和直接导航。
|
||||
- Store 对外复用 `apps/admin/src/store/hooks`。持久化 key 和序列化格式属于已有数据契约,变更前检查历史数据。
|
||||
- 请求从 `apps/admin/src/api` 进入 `apps/admin/src/axios`。Mock 只用于演示与本地验证。服务端密钥不能放入会打包到浏览器的 `VITE_*`。
|
||||
- 维护公共 API 时检查调用方、导出与已有回归测试。涉及工程配置时更新对应文档和 [验证记录](../docs/toolchain-upgrade.md)。
|
||||
- Before adding a capability or component, inspect existing project components, hooks, and installed component-library APIs and examples. Determine whether existing props, slots, or layout CSS can meet the requirement. Reuse sufficient existing capabilities. Add a component only for an established capability gap, and record the gap and choice in an existing task record or delivery note. Do not create a component solely for full-height sizing, a scroll container, or a styling wrapper.
|
||||
- Follow existing Vue 3 Composition API patterns: `defineComponent` with TSX and `<script setup lang="ts">` for SFCs. Prefer Naive UI and project components. Use ECharts for charts.
|
||||
- `unplugin-auto-import` manages Vue, Router, and Pinia APIs. Use `import type` for types and update generated declarations through their generators.
|
||||
- Preserve unique route names, permission metadata, caching, and translation keys. When permissions change, verify both menu visibility and direct navigation.
|
||||
- Access stores through `apps/admin/src/store/hooks`. Persistence keys and serialization formats are existing data contracts; inspect historical data before changing them.
|
||||
- Requests flow from `apps/admin/src/api` into `apps/admin/src/axios`. Mocks are for demos and local verification. Never place server secrets in `VITE_*` variables that are bundled into the browser.
|
||||
- When maintaining public APIs, inspect callers, exports, and existing regression tests. For engineering configuration changes, update the corresponding documentation and [verification record](../docs/toolchain-upgrade.md).
|
||||
|
||||
## 验收与证据
|
||||
## Verification and evidence
|
||||
|
||||
| 命令 | 验证范围 |
|
||||
| ----------------------------- | --------------------------------------------------------------- |
|
||||
| `pnpm harness check` | 主题已登记并可从入口到达;相对链接、回归路径和检查命令有效 |
|
||||
| `pnpm harness verify <scope>` | 环境检查和该任务域登记的 Vitest 回归或项目检查 |
|
||||
| `pnpm harness verify` | `pnpm check` 的全部检查 |
|
||||
| `pnpm check` | 环境、Harness、图标同步、类型、规范、格式、单测、应用与文档构建 |
|
||||
### Choosing the verification scope
|
||||
|
||||
`verify` 逐步执行,首个失败即停止并返回非零退出码。运行结束时打印 `.harness-local/runs/<run>/report.json` 的位置,其中记录命令、结果、耗时、运行时和信号。每次执行独立留档。全量报告以 `pnpm check` 作为一个步骤,阶段详情查看当次终端输出。参数或上下文校验失败,以及被强制中断的运行,可能没有报告。
|
||||
Determine impact from the actual diff, callers, and data contracts before selecting commands. Line count does not measure risk: one permission condition, persistence key, or public export can affect multiple modules. Selecting verification scope does not require a separate approval step.
|
||||
|
||||
GitHub Actions 在 Linux、Windows 和 macOS 运行同一份 `pnpm check`。单独执行 `pnpm lint`、`pnpm format:check` 和 `pnpm typecheck` 可定位问题。`pnpm lint:fix` 与 `pnpm format` 会改写文件。`pnpm check` 会同步图标清单并生成 `dist/production`,交付前检查生成差异。
|
||||
| Change | Local verification |
|
||||
| --------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| Maintainer documentation, wording, comments, or formatting with no runtime change | Check content and formatting of changed files. Run `pnpm harness check` when indexes, links, or Harness rules change. No browser is needed. |
|
||||
| A single function, hook, or small fix with existing regression coverage | Run the relevant test file and add a regression case if needed. Lint changed code; add type checking when types or exports are affected. |
|
||||
| One task area or multiple affected callers | Run `pnpm harness verify <scope>`. Select each affected scope for cross-area work, or run the relevant test files together. Add static checks appropriate to the change. |
|
||||
| Documentation structure, links, code examples, or theme | Run `pnpm harness verify docs` for types, links, and the build. Use focused browser checks only when rendering or interaction is affected; see the [documentation workflow](../docs/docs-handoff.md#update-workflow). |
|
||||
| Integration risk, a release, or an explicit request for complete checks | Run `pnpm harness verify all` once at task completion. Select browser coverage separately using the table below. |
|
||||
|
||||
### 浏览器验收
|
||||
Full command checks are required for changes to dependencies or the lockfile, workspace boundaries or public exports, TypeScript/Vite/build/CI configuration, or full-check orchestration; for cross-module impact that cannot be reliably bounded; for release preparation; or when explicitly requested. A local shared-component implementation, page, style, or copy change does not escalate solely because of its directory. Follow any user-specified verification scope and report its coverage limits.
|
||||
|
||||
页面行为变化时使用 `pnpm dev`,打开 `http://127.0.0.1:9527/ray-template/`。涉及构建或部署子路径时,运行 `pnpm build` 和 `pnpm preview`,使用终端给出的地址和部署 base。用本地演示数据复现,核对受影响的路由、动作和控制台错误。
|
||||
For example, a CSV escaping fix can use `pnpm test:run __test__/components/table-pro-exports.spec.ts` and checks on the modified files. A page spacing change calls for that page and the affected widths. A global theme variable change calls for light/dark checks on representative consumers. Once relevant checks pass, verification is complete for that iteration. Do not repeatedly expand scope without a new change, failure, or evidence gap.
|
||||
|
||||
| 变更 | 检查 |
|
||||
| ---------------------- | -------------------------------------------------------- |
|
||||
| 页面、主题或文案 | 对应页面、简体中文和英文、明暗主题。布局改动增加窄屏检查 |
|
||||
| 路由、权限或缓存 | 从菜单进入、直接访问、刷新,核对守卫和恢复行为 |
|
||||
| 图标、部署 base 或构建 | 检查生产预览、资源 URL 和控制台 |
|
||||
`pnpm harness verify <scope>` runs only its registered commands; it does not automatically include ESLint, formatting, or every type check. For small fixes, run `pnpm exec eslint <changed-code-files> --max-warnings=0`, `pnpm exec prettier --check <changed-files>`, and relevant tests directly, then record commands and results in the delivery note. Existing scope suites are broad. A clearly isolated behavior does not need broader tests merely to obtain a JSON report.
|
||||
|
||||
在交付或 PR 中记录复现步骤、实际结果及未验证项。临时报告、日志和截图放入 `.harness-local/`。浏览器结果单独记录,CLI 报告仅覆盖其中列出的命令。
|
||||
| Command | Coverage |
|
||||
| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
|
||||
| `pnpm harness check` | Registered and reachable topics; valid relative links, regression paths, and check commands |
|
||||
| `pnpm harness verify <scope>` | Environment check plus the scope's registered Vitest regressions or project checks |
|
||||
| `pnpm harness verify all` | Explicitly runs all of `pnpm check`; the legacy command without a scope retains this behavior |
|
||||
| `pnpm check` | Environment, Harness, API/package boundaries, icon synchronization, types, lint, formatting, tests, and both site builds |
|
||||
|
||||
## 维护
|
||||
`verify` runs steps sequentially, stops at the first failure, and returns a nonzero exit code. It prints the path to `.harness-local/runs/<run>/report.json` on completion. Reports contain commands, outcomes, durations, runtime, and signals; each invocation has a separate record. Full reports represent `pnpm check` as one step; consult that run's terminal output for phase details. Invalid arguments or context, and forcibly interrupted runs, may produce no report. None of these CLI commands launches a browser. Passing command checks does not establish UI/UX acceptance.
|
||||
|
||||
影响外部读者的功能或兼容性改动,按 [文档联动说明](../docs/docs-handoff.md) 在同一变更中更新 `apps/docs`。单独用 `pnpm docs:check` 检查示例类型、文档链接和构建;用 `pnpm docs:preview` 验收生产子路径下的交互。
|
||||
GitHub Actions runs the same `pnpm check` on Linux, Windows, and macOS. Use `pnpm lint`, `pnpm format:check`, or `pnpm typecheck` separately to diagnose failures. `pnpm lint:fix` and `pnpm format` rewrite files. `pnpm check` synchronizes icon manifests and generates `dist/production`; review generated diffs before delivery.
|
||||
|
||||
- 移动实现、适配层或示例时,更新 `harness/context/` 中受影响的索引。每个主题说明何时使用、先读哪些文件、谁拥有实现及如何验证。API 细节留在源码、模块 README 或读者文档。
|
||||
- 新增任务域时,在 [scopes.json](scopes.json) 注册简介和 `tests` 或 `checks`,添加同名 `harness/context/<scope>.md`,并从 [llms.txt](../llms.txt) 链入。测试目录以 `/` 结尾;项目检查复用 CLI 允许的根脚本。原有任务域可保留为较宽的验证入口。
|
||||
- 索引用普通行内相对链接指向仓库文件或目录。`pnpm harness check` 检查主题及其入口文档的文件目标,不请求外部链接或验证标题锚点。调整内容后再从一个真实任务出发走查实现和测试归属。
|
||||
### Browser verification
|
||||
|
||||
Use browser verification only for changes to visible effects, user actions, or browser-specific capabilities. Maintainer documentation, comments, tests, Harness changes, and logic changes with no page impact do not trigger UI/UX verification. Reader-documentation wording corrections can be checked in source and with formatting tools; open the relevant page when rendering structure, example interaction, or layout is at risk. Report missing required browser evidence accurately; screenshots do not replace functional regressions.
|
||||
|
||||
By default, use `pnpm dev` and open `http://127.0.0.1:9527/ray-template/`. Reproduce the affected page and action flow with local demo data, and inspect relevant console errors. Add dimensions below only when their corresponding behavior changes. Do not exhaustively combine pages, languages, themes, and viewports.
|
||||
|
||||
| Change | Additional checks |
|
||||
| --------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| Local interaction, validation, or state | Affected action and relevant success, failure, or recovery paths. Check keyboard operation when keyboard/focus behavior changes. |
|
||||
| Copy or internationalization | Chinese and English on the affected page, interpolation, and fallback behavior. Check wrapping when text length affects layout. |
|
||||
| Layout, sizing, scrolling, or responsiveness | The affected area at desktop and narrow widths, such as 390px. Check only affected layout modes and long content. |
|
||||
| Themes, colors, or shared visual variables | Light/dark themes and relevant readability. Select representative actual consumers of shared styles. |
|
||||
| Routing, permissions, or cache behavior | Menu entry, direct navigation, reload, and restoration for relevant roles/sources. Do not recheck unrelated pages. |
|
||||
| Browser capabilities such as downloads, printing, or fullscreen | Actual browser behavior in the corresponding example. Unit tests establish only what they cover. |
|
||||
| Resource loading, deployment base, or build artifacts | Build and use a production preview. Check affected entry points, resource URLs, and the console. Verify related admin iframes in the combined output. |
|
||||
|
||||
For shared layout or global style changes, choose representative pages with different usage patterns, such as a table and a form, plus affected documentation examples. Define a cross-page matrix only for a site-wide redesign, release acceptance, or an explicit request. After acceptance, small follow-up fixes need only the relevant steps. Reuse results from the same task for pages and dimensions unaffected by the new changes.
|
||||
|
||||
Record reproduction steps, actual observations, and unverified areas in the delivery note or PR. Put temporary reports, logs, and screenshots in `.harness-local/`. Record browser results separately; CLI reports cover only their listed commands.
|
||||
|
||||
## Maintenance
|
||||
|
||||
For behavior or compatibility changes that affect external readers, update `apps/docs` in the same change following the [documentation handoff](../docs/docs-handoff.md). `pnpm docs:check` separately checks example types, documentation links, and the build. Preview affected entry points when production subpaths or interactions are involved.
|
||||
|
||||
- When moving implementations, adapters, or examples, update affected indexes in `harness/context/`. Each topic explains when to use it, which files to read first, implementation ownership, and verification. Keep API details in source, module READMEs, or reader documentation.
|
||||
- To add a task area, register its description and `tests` or `checks` in [scopes.json](scopes.json), add `harness/context/<scope>.md`, and link it from [llms.txt](../llms.txt). Test directories end with `/`; project checks reuse root scripts allowed by the CLI. Existing areas may remain as broader verification entry points.
|
||||
- Use ordinary inline relative links to repository files or directories. `pnpm harness check` checks file targets in topic indexes and their entry documents; it does not request external links or validate heading anchors. After editing, walk through a real task to confirm implementation and test ownership.
|
||||
|
||||
@ -1,16 +1,16 @@
|
||||
# API、请求与 Mock
|
||||
# APIs, requests, and mocks
|
||||
|
||||
用于新增接口、调试 Axios 响应和拦截器、定位重复请求或切页取消、修改演示数据。先看[请求契约](../../apps/admin/src/axios/README.md)。
|
||||
Use this topic to add endpoints, debug Axios responses and interceptors, investigate duplicate requests or cancellation on navigation, or change demo data. Start with the [request contract](../../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) |
|
||||
| 开发与在线演示共用 HTTP Mock | [Mock 处理器](../../apps/admin/src/mocks/handlers.ts)、[共用演示数据](../../apps/admin/src/demo-data/people.ts) | [统一业务 API](../../apps/admin/src/api/admin/index.ts)、[Mock 启动](../../apps/admin/src/mocks/browser.ts) |
|
||||
| Question | Read first | Follow through |
|
||||
| --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| Business endpoints, paginated data, and request configuration | [Application APIs](../../apps/admin/src/api), [application request instance](../../apps/admin/src/axios/instance.ts), [request configuration](../../apps/admin/src/app-config/request-config.ts) | [Person endpoint caller](../../apps/admin/src/api/demo/mock/person.ts), [integration guide](../../apps/docs/guide/requests.md) |
|
||||
| Axios interceptors, errors, and client isolation | [Shared client](../../packages/http/src/client.ts), [shared types](../../packages/http/src/types.ts) | [Application request interceptor](../../apps/admin/src/axios/axios-interceptor/request/provider.ts), [response interceptor](../../apps/admin/src/axios/axios-interceptor/response/provider.ts) |
|
||||
| Duplicate requests, AbortSignal, and cancellation on navigation | [Shared RequestCanceler](../../packages/http/src/RequestCanceler.ts), [application cancellation provider](../../apps/admin/src/app-components/provider/AppRequestCancelerProvider) | [Layout content slot](../../apps/admin/src/layout/default/ContentWrapper/index.tsx), [TablePro remote requests](table-pro.md) |
|
||||
| HTTP mocks shared by development and the online demo | [Mock handlers](../../apps/admin/src/mocks/handlers.ts), [shared demo data](../../apps/admin/src/demo-data/people.ts) | [Unified business API](../../apps/admin/src/api/admin/index.ts), [mock bootstrap](../../apps/admin/src/mocks/browser.ts) |
|
||||
|
||||
应用 `axios/utils` 中有兼容转导出。请求的默认 signal 只在调用方未传 signal、且未禁用默认取消时注入。演示数据不代表生产接口或授权;前端 `VITE_*` 配置不可用于密钥。
|
||||
Application `axios/utils` contains compatibility re-exports. The default request signal is injected only if the caller has not supplied a signal and has not disabled default cancellation. Demo data does not represent production endpoints or authorization. Frontend `VITE_*` configuration must not hold secrets.
|
||||
|
||||
定向验证:`pnpm harness verify api`,包括[应用请求](../../__test__/axios/request.spec.ts)、[客户端隔离](../../__test__/workspace/http-client.spec.ts)和 [Mock](../../__test__/mock/database.spec.ts)。生产后端接入、浏览器下载和真实链路需另验。
|
||||
Targeted verification: `pnpm harness verify api` first runs `api:check` for generated OpenAPI files and the MSW worker, then the [application request](../../__test__/axios/request.spec.ts), [client isolation](../../__test__/workspace/http-client.spec.ts), and [mock](../../__test__/mock/database.spec.ts) regressions. Verify production backend integration, browser downloads, and real end-to-end flows separately when those behaviors are affected.
|
||||
|
||||
标准服务端接入从 [共享契约包](../../packages/api-contracts/README.md)、[业务 Schema](../../packages/api-contracts/src/admin.ts)、[演示 Schema](../../packages/api-contracts/src/demo.ts)、[OpenAPI 生成](../../packages/api-contracts/src/openapi.ts) 和 [接入指南](../../apps/docs/guide/backend.md) 进入。页面只调用 API,包括搜索选项和路由示例列表/详情;Mock 数据库拥有演示写入和权限校验,生产后端模式的远端路由加载失败会中止启动。应用旧契约路径保留为兼容转导出。
|
||||
For standard backend integration, start with the [shared contract package](../../packages/api-contracts/README.md), [business schemas](../../packages/api-contracts/src/admin.ts), [demo schemas](../../packages/api-contracts/src/demo.ts), [OpenAPI generation](../../packages/api-contracts/src/openapi.ts), and [integration guide](../../apps/docs/guide/backend.md). Pages call APIs exclusively, including for search options and route-example lists/details. The mock database owns demo writes and permission checks. In production backend mode, a remote-route load failure aborts startup. Legacy application contract paths remain as compatibility re-exports.
|
||||
|
||||
@ -1,14 +1,14 @@
|
||||
# 文档站与可运行示例
|
||||
# Documentation site and runnable examples
|
||||
|
||||
用于修改指南、API 参考、导航、主题、旧链接或交互示例。站点开发和预览命令见[文档站 README](../../apps/docs/README.md)。
|
||||
Use this topic for guides, API references, navigation, themes, legacy links, and interactive examples. Development and preview commands are in the [documentation-site 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) |
|
||||
| Question | Read first | Follow through |
|
||||
| ------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| Public usage, APIs, and compatibility migrations | [Developer guides](../../apps/docs/guide), [API reference](../../apps/docs/reference/index.md), [migration guide](../../apps/docs/migration.md) | [Application/documentation coordination](../../docs/docs-handoff.md), [shared package boundaries](../../docs/architecture.md) |
|
||||
| Site theme, navigation, and source links | [VitePress configuration](../../apps/docs/.vitepress/config.mts), [sidebar](../../apps/docs/.vitepress/sidebar.mts), [theme](../../apps/docs/.vitepress/theme) | [Version and repository links](../../apps/docs/.vitepress/source.mts) |
|
||||
| Legacy documentation paths and redirects | [Legacy path mapping](../../apps/docs/.vitepress/legacy.mts) | [Combined site and legacy redirect artifacts](../../scripts/assemble-pages.mjs), [build and deployment](toolchain.md) |
|
||||
| Inline interaction and source inclusion | [Lightweight Vue examples](../../apps/docs/examples), [admin iframe wrapper](../../apps/docs/examples/AdminExample.vue) | [example.html](../../apps/admin/example.html), [isolated demo bootstrap and routes](../../apps/admin/src/documentation-example.tsx), [admin demo pages](../../apps/admin/src/views/demo) |
|
||||
|
||||
轻量示例通过共享包公开入口运行。需要后台上下文的示例走 `example.html` 的限定路由和内存缓存;使用和展示同一份运行源码。涉及公开契约时回到所属主题核实,维护指南、示例及迁移说明。
|
||||
Lightweight examples use public shared-package entry points. Examples needing application context use the restricted routes and in-memory cache in `example.html`. Display the same source that actually runs. For public contract changes, return to the owning topic and update guides, examples, and migration notes.
|
||||
|
||||
定向验证:`pnpm harness verify docs` 执行 `docs:check`,包含类型、站内链接和生产构建。嵌入后台、部署子路径和旧站跳转使用 `pnpm pages:build` 生成组合产物,再按 [README](../../apps/docs/README.md) 预览。
|
||||
Targeted verification: `pnpm harness verify docs` runs `docs:check`, covering types, internal links, and the production build. Wording-only corrections can use source review and formatting checks. Use a browser only for affected rendering or interactions, selecting the relevant page/example and dimensions through the [documentation workflow](../../docs/docs-handoff.md#update-workflow). For admin embedding, deployment subpaths, or combined redirect artifacts, generate the combined output with `pnpm pages:build` and preview it as described in the [README](../../apps/docs/README.md).
|
||||
|
||||
@ -1,14 +1,14 @@
|
||||
# Harness、索引和验证证据
|
||||
# Harness, indexes, and verification evidence
|
||||
|
||||
用于调整任务协作、索引、回归范围、命令和本地报告。执行方式见 [Harness README](../README.md)。
|
||||
Use this topic for collaboration rules, indexes, regression scope, commands, and local reports. Execution guidance is in the [Harness README](../README.md).
|
||||
|
||||
| 要查什么 | 先读 | 接着追踪 |
|
||||
| -------------------------- | ---------------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
|
||||
| 助手从哪里进入、怎么选主题 | [根约定](../../AGENTS.md)、[静态任务入口](../../llms.txt) | [主题索引](./)、[跨模块地图](../../docs/architecture.md) |
|
||||
| 复杂任务怎么分工 | [按需使用 subagent](../README.md#按需使用-subagent) | [根约定](../../AGENTS.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) |
|
||||
| Question | Read first | Follow through |
|
||||
| ---------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
|
||||
| Agent entry points and topic selection | [Root guidance](../../AGENTS.md), [static task index](../../llms.txt) | [Topic indexes](./), [cross-module map](../../docs/architecture.md) |
|
||||
| Delegation for complex tasks | [Using subagents when useful](../README.md#using-subagents-when-useful) | [Root guidance](../../AGENTS.md) |
|
||||
| CLI, context, and targeted checks | [Scope registry](../scopes.json), [CLI implementation](../run.mjs) | [CLI regressions](../../__test__/harness/cli.spec.ts), [root check commands](../../package.json) |
|
||||
| Full checks, reports, and historical decisions | [Verification and evidence](../README.md#verification-and-evidence), [CI](../../.github/workflows/ci.yaml) | [Development plan and design review](../plan.md), [toolchain record](../../docs/toolchain-upgrade.md) |
|
||||
|
||||
移动源码时更新受影响的索引链接。新增主题时同步任务注册表、同名 Markdown 和静态入口;长篇契约保留在所属模块。报告由现有 CLI 写入被忽略的 `.harness-local/runs/`;截图和其他临时证据不放进索引。
|
||||
Update affected index links when moving source. For new topics, update the scope registry, matching Markdown file, and static entry point together. Keep lengthy contracts in their owning modules. The existing CLI writes reports to ignored `.harness-local/runs/`; do not put screenshots or other temporary evidence in the indexes.
|
||||
|
||||
定向验证:先运行 `pnpm harness check` 检查索引,变更 CLI 后运行 `pnpm harness verify harness`。涉及全量流程时,用真实 `pnpm harness verify` 验证报告。
|
||||
Targeted verification: run `pnpm harness check` for index validity. After CLI or scope-registration changes, run `pnpm harness verify harness`. For full-workflow changes, use a real `pnpm harness verify all` run to verify reporting. Collaboration rules, indexes, and the CLI do not themselves change pages, so they do not need UI/UX verification.
|
||||
|
||||
@ -1,13 +1,13 @@
|
||||
# SVG 图标与生成
|
||||
# SVG icons and generation
|
||||
|
||||
用于新增或移动图标、排查图标类型、symbol ID、雪碧图 URL 或热更新。
|
||||
Use this topic when adding or moving icons, or investigating icon types, symbol IDs, spritemap URLs, or hot updates.
|
||||
|
||||
| 要查什么 | 先读 | 接着追踪 |
|
||||
| ------------------------ | ---------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
|
||||
| 资源、分包及命名 | [图标维护说明](../../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) |
|
||||
| Question | Read first | Follow through |
|
||||
| -------------------------------------------------- | ------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
|
||||
| Assets, groups, and naming | [Maintenance guide](../../packages/icons/src/A_README.md), [SVG assets](../../packages/icons/src) | [Public package entry points](../../packages/icons/package.json), [application adapter](../../apps/admin/src/icons) |
|
||||
| Manifest, types, generation, and HMR | [Generator](../../packages/icons/scripts/icons.mjs), [root script](../../scripts/icons.mjs) | [Vite adapter](../../vite-helper/icons.ts), [plugin configuration](../../vite.plugin.config.ts) |
|
||||
| Rendering, application injection, and reader usage | [RIcon](../../packages/ui/src/RIcon/index.ts), [application icon service](../../apps/admin/src/App.tsx) | [Icon demo](../../apps/admin/src/views/demo/svg-icons), [reader reference](../../apps/docs/reference/icons.md) |
|
||||
|
||||
SVG 与生成器是来源;[manifest.ts](../../packages/icons/src/manifest.ts) 由 `pnpm icons:generate` 更新。移动分包可能改变完整名称;检查菜单、路由配置、缓存中的引用及生产资源 URL。
|
||||
The SVG files and generator are authoritative; `pnpm icons:generate` updates [manifest.ts](../../packages/icons/src/manifest.ts). Moving a group can change full icon names. Check references in menus, route configuration, and caches, as well as production asset URLs.
|
||||
|
||||
定向验证:`pnpm icons:check` 与 `pnpm harness verify icons`,包括[生成](../../__test__/icons/generation.spec.ts)和[热更新](../../__test__/icons/hmr.spec.ts)回归。资源路径变更按[浏览器验收](../README.md#浏览器验收)核对生产预览。
|
||||
Targeted verification: `pnpm harness verify icons` includes `icons:check` and the [generation](../../__test__/icons/generation.spec.ts) and [HMR](../../__test__/icons/hmr.spec.ts) regressions. Do not repeat the manifest check separately. For asset path changes, check production previews using the [browser verification rules](../README.md#browser-verification).
|
||||
|
||||
@ -1,14 +1,14 @@
|
||||
# 启动、布局与应用状态
|
||||
# Bootstrap, layout, and application state
|
||||
|
||||
用于定位 Provider、导航布局、页面缓存、设置抽屉、Pinia 或持久化问题。
|
||||
Use this topic for providers, navigation layouts, page caching, the settings drawer, Pinia, or persistence issues.
|
||||
|
||||
| 要查什么 | 先读 | 接着追踪 |
|
||||
| --------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
||||
| 首屏、无界挂载、全局服务 | [应用启动](../../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) |
|
||||
| Question | Read first | Follow through |
|
||||
| ----------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| Initial rendering, Wujie mounting, and global services | [Application bootstrap](../../apps/admin/src/main.ts), [App provider composition](../../apps/admin/src/App.tsx) | [Application providers](../../apps/admin/src/app-components/provider), [shared UI service interfaces](../../packages/ui/src/services.ts), [post-startup template checks](../../apps/admin/src/__ray-template/index.ts) |
|
||||
| Sidebar, top navigation, tabs, and search | [Application layout adapter](../../apps/admin/src/layout/index.tsx), [application navigation hook](../../apps/admin/src/hooks/template/useAppNavigation.ts) | [Shared AdminShell](../../packages/admin-shell/src/AdminShell.tsx), [host layout components](../../apps/admin/src/layout/components), [slot contract](../../apps/admin/src/layout/README.md) |
|
||||
| Content area, loading, navigation, and KeepAlive | [Host content slot](../../apps/admin/src/layout/default/ContentWrapper/index.tsx), [host transition adapter](../../apps/admin/src/components/RTransitionComponent) | [Shared transitions and cached rendering](../../packages/admin-shell/src/RouteTransition.vue), [cache allowlist](../../apps/admin/src/store/modules/keep-alive/index.ts), [page request cancellation](api.md) |
|
||||
| Layout preferences, JSON import/export, and transient state | [Settings store](../../apps/admin/src/store/modules/setting/index.ts), [preference-file validation](../../apps/admin/src/store/modules/setting/preference-file.ts), [runtime store](../../apps/admin/src/store/modules/runtime/index.ts) | [Host settings drawer](../../apps/admin/src/layout/components/SiderBar/components/SettingDrawer/index.tsx), [shared layout settings](../../packages/admin-shell/src/LayoutSettings.tsx), [reader guide](../../apps/docs/guide/layout.md) |
|
||||
|
||||
布局包负责壳和渲染,应用提供导航、设置、内容及运行时状态。应用 Store 通过 [hooks](../../apps/admin/src/store/hooks) 访问;持久化范围和历史格式见 [Store 约定](../../apps/admin/src/store/README.md)。偏好文件只处理布局设置,路由来源和 JSON 归[路由](routing.md)。
|
||||
The layout package owns the shell and rendering; the application supplies navigation, settings, content, and runtime state. Access application stores through [hooks](../../apps/admin/src/store/hooks). See the [store conventions](../../apps/admin/src/store/README.md) for persistence scope and historical formats. Preference files contain layout settings only; route sources and route JSON belong to [routing](routing.md).
|
||||
|
||||
定向验证:`pnpm harness verify layout`,包括[布局回归](../../__test__/layout)、[Provider](../../__test__/app/global-provider.spec.ts)和相关 Hook。浏览器复核受影响的布局模式、窄屏、缓存恢复及偏好读回。
|
||||
Targeted verification: `pnpm harness verify layout`, including [layout regressions](../../__test__/layout), [providers](../../__test__/app/global-provider.spec.ts), and related hooks. Select affected layout modes using the [browser dimensions](../README.md#browser-verification). Check narrow widths for sizing changes, and reload restoration/readback when cache or preference behavior changes.
|
||||
|
||||
@ -1,14 +1,14 @@
|
||||
# 路由、菜单与权限
|
||||
# Routing, menus, and permissions
|
||||
|
||||
用于新增页面或菜单、调试直达和刷新、变更动态路由来源或配置。先看[路由接入与配置契约](../../apps/admin/src/router/README.md)中与任务相关的段落。
|
||||
Use this topic to add pages or menus, debug direct navigation and reloads, or change dynamic route sources and configuration. Read the relevant sections of the [routing integration and configuration contract](../../apps/admin/src/router/README.md) first.
|
||||
|
||||
| 要查什么 | 先读 | 接着追踪 |
|
||||
| ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| 静态页面注册、菜单排序 | [初始路由 JSON](../../apps/admin/src/mocks/data/routes.json)、[路由模块装配](../../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) |
|
||||
| Question | Read first | Follow through |
|
||||
| --------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| Static page registration and menu order | [Initial route JSON](../../apps/admin/src/mocks/data/routes.json), [route module assembly](../../apps/admin/src/router/app-route-modules.ts) | [Views](../../apps/admin/src/views), [menu store](../../apps/admin/src/store/modules/menu/index.ts), [shared route expansion](../../packages/routing/src/expand-routes.ts) |
|
||||
| Dynamic JSON fields, validation errors, and allowed views | [Shared schema](../../packages/routing/src/schema.ts), [JSON Schema export](../../packages/routing/src/json-schema.ts), [application view-ID registry](../../apps/admin/src/router/config/views.ts) | [Application binding](../../apps/admin/src/router/config/contract.ts), [management page](../../apps/admin/src/views/route-management), [reader guide](../../apps/docs/guide/routing.md) |
|
||||
| Static, local, and remote sources and fallback | [Source loading and saving](../../apps/admin/src/router/config/source.ts) | [Router initialization](../../apps/admin/src/router/index.ts), [registered routes](../../apps/admin/src/router/routes.ts) |
|
||||
| Menu visibility, direct access, and post-login landing | [Navigation guards](../../apps/admin/src/router/utils/permission.ts), [route and allowlist configuration](../../apps/admin/src/app-config/router-config.ts) | [Menu visibility](../../apps/admin/src/router/utils/valid-menu-item-show.ts), [session store](../../apps/admin/src/store/modules/signing/index.ts), [shared navigation traversal](../../packages/routing/src/navigation.ts) |
|
||||
|
||||
[应用 Schema](../../apps/admin/src/router/config/schema.ts) 是转导出;共享包负责通用校验,页面加载器、角色和登录状态由应用接入。保持路由名唯一;启用缓存的页面检查组件名与路由名。前端菜单和守卫都不能替代服务端授权。
|
||||
The [application schema](../../apps/admin/src/router/config/schema.ts) is a re-export. The shared package owns generic validation; the application supplies view loaders, roles, and login state. Keep route names unique. For cached views, check that component names match route names. Frontend menus and guards do not replace server-side authorization.
|
||||
|
||||
定向验证:`pnpm harness verify routing`,优先看[动态配置](../../__test__/router/config.spec.ts)和[权限回归](../../__test__/router/permission.spec.ts)。行为改动补测菜单进入、直接访问、刷新及切换来源;涉及缓存或设置再看[布局与状态](layout.md)。
|
||||
Targeted verification: `pnpm harness verify routing`. Start with [dynamic configuration](../../__test__/router/config.spec.ts) and [permission regressions](../../__test__/router/permission.spec.ts). For behavior changes, also check menu entry, direct access, reload, and source switching. Consult [layout and state](layout.md) when caching or settings are involved.
|
||||
|
||||
@ -1,16 +1,16 @@
|
||||
# TablePro
|
||||
|
||||
用于 `RTablePro`、`useTablePro`、高级搜索、远端分页、列设置、导出或打印。共享包拥有实现,后台和文档站分别消费同一公开 API。
|
||||
Use this topic for `RTablePro`, `useTablePro`, advanced search, remote pagination, column settings, export, or printing. The shared package owns the implementation; the admin application and documentation site consume the same public 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/pagination.ts)、[远端请求](../../packages/ui/src/RTablePro/src/useTableRequest.ts) | [搜索控件](../../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) |
|
||||
| Question | Read first | Follow through |
|
||||
| ------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| Exports, props, and instance methods | [Shared entry point](../../packages/ui/src/RTablePro/index.ts), [props](../../packages/ui/src/RTablePro/src/props.ts), [types](../../packages/ui/src/RTablePro/src/types.ts) | [Registration hook](../../packages/ui/src/RTablePro/src/useTablePro.ts), [package exports](../../packages/ui/package.json), [application component entry point](../../apps/admin/src/components/index.ts) |
|
||||
| Search drafts, validation, applied filters, and request races | [Search state](../../packages/ui/src/RTablePro/src/useTableSearch.ts), [value processing](../../packages/ui/src/RTablePro/src/search.ts), [pagination](../../packages/ui/src/RTablePro/src/pagination.ts), [remote requests](../../packages/ui/src/RTablePro/src/useTableRequest.ts) | [Search controls](../../packages/ui/src/RTablePro/src/components/Search.tsx), [admin search example](../../apps/admin/src/views/demo/tables/search.tsx), [search regressions](../../__test__/components/table-pro-search.spec.ts) |
|
||||
| Column visibility, layout, current-page export, and printing | [Table panel](../../packages/ui/src/RTablePro/src/TablePanel.tsx), [column settings](../../packages/ui/src/RTablePro/src/columns.ts) | [CSV](../../packages/ui/src/RTablePro/src/csv.ts), [printing](../../packages/ui/src/RTablePro/src/printing.ts), [column regressions](../../__test__/components/table-pro-columns.spec.ts) |
|
||||
| Examples, copy, and public contracts | [Component contract](../../packages/ui/src/RTablePro/README.md), [reader reference](../../apps/docs/reference/table-pro.md) | [Admin examples and fixtures](../../apps/admin/src/views/demo/tables), [lightweight documentation example](../../apps/docs/examples/TableProDemo.vue), [component locale resources](../../packages/ui/src/RTablePro/src/locale.ts) |
|
||||
|
||||
[本轮专项代码审查](../../docs/table-pro-review.md)记录已复现的问题、修复批次和验证边界。
|
||||
The [focused code review](../../docs/table-pro-review.md) records reproduced issues, remediation batches, and verification limits.
|
||||
|
||||
远端 `total` 是筛选后的总数,取消需要请求函数透传 `signal`。修改实例能力时同时检查组件暴露、Hook 和公开导出;修改示例参数时确认是文档轻量示例还是[嵌入后台示例](docs.md)。
|
||||
Remote `total` means the count after filtering. Cancellation requires the request function to forward `signal`. When changing instance capabilities, check component exposure, the hook, and public exports together. When editing example parameters, distinguish lightweight documentation examples from [embedded admin examples](docs.md).
|
||||
|
||||
定向验证:`pnpm harness verify table-pro` 覆盖表格、搜索、列和导出。真实滚动、下载、打印和窄屏布局使用对应示例在浏览器验收。
|
||||
Targeted verification: `pnpm harness verify table-pro` covers the table, search, columns, and export. Small fixes to one behavior can run its test file directly. Use the corresponding example to check actual scrolling, downloads, printing, or layout only when that behavior changes; select relevant viewports without traversing every table feature.
|
||||
|
||||
@ -1,14 +1,14 @@
|
||||
# 工作区、类型检查、构建与 CI
|
||||
# Workspaces, type checking, builds, and CI
|
||||
|
||||
用于修改依赖、公开导出、别名、自动导入、生产构建或部署配置。运行时以 [.nvmrc](../../.nvmrc) 和[根清单](../../package.json)为准。
|
||||
Use this topic for dependencies, public exports, aliases, auto-imports, production builds, or deployment configuration. Runtime requirements come from [.nvmrc](../../.nvmrc) and the [root manifest](../../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) |
|
||||
| Question | Read first | Follow through |
|
||||
| --------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| Workspace and dependency boundaries | [pnpm workspace](../../pnpm-workspace.yaml), [lockfile](../../pnpm-lock.yaml), [workspace ownership](../../docs/architecture.md#workspaces) | [Package-boundary check](../../scripts/check-package-boundaries.mjs), [environment check](../../scripts/doctor.mjs) |
|
||||
| Path aliases, type checking, and auto-imports | [TypeScript project graph](../../docs/architecture.md#typescript-project-configuration), [shared configuration](../../tsconfig.base.json), [Vite aliases](../../vite.custom.config.ts) | [Plugin configuration](../../vite.plugin.config.ts), [generated declarations](../../unplugin), [Vitest configuration](../../vitest.config.ts) |
|
||||
| Build entry points, deployment base, and SEO | [Application Vite configuration](../../vite.config.ts), [deployment configuration](../../vite.custom.config.ts), [site metadata](../../vite-helper/site-seo.ts) | [Documentation configuration](../../apps/docs/.vitepress/config.mts), [artifact assembly](../../scripts/assemble-pages.mjs), [deployment conventions](../../docs/architecture.md#deployment-and-search-discovery) |
|
||||
| CI, container images, and release artifacts | [GitHub Actions](../../.github/workflows/ci.yaml), [Dockerfile](../../Dockerfile), [Compose](../../docker-compose.yml) | [Full verification workflow](../../harness/README.md), [toolchain history](../../docs/toolchain-upgrade.md) |
|
||||
|
||||
公开导出以对应 workspace 的 `package.json#exports` 为准;改别名时比较 Vite、TypeScript 和 Vitest 的解析。生成声明通过配置更新。发布组合站点时同时核对后台和文档的 base。
|
||||
Each workspace's `package.json#exports` defines its public exports. Compare Vite, TypeScript, and Vitest resolution when changing aliases. Update generated declarations through configuration. When publishing the combined site, check both the admin and documentation bases.
|
||||
|
||||
定向验证:`pnpm harness verify toolchain` 执行包边界和类型检查。改动构建或部署时还需全量检查、生成相关产物并预览;定向通过不能证明 CI、Docker 或线上发布成功。
|
||||
Targeted verification: `pnpm harness verify toolchain` runs package-boundary and type checks. For changes to dependencies, public exports, or build configuration, run `pnpm harness verify all` once at completion using the [verification scope](../README.md#choosing-the-verification-scope). Preview affected entry points when build artifacts or deployment paths change. Toolchain prose alone does not trigger these runtime checks. Passing targeted checks does not prove CI, Docker, or production publication succeeded.
|
||||
|
||||
@ -1,17 +1,17 @@
|
||||
# 页面、公共组件、Hooks 与指令
|
||||
# Pages, shared components, hooks, and directives
|
||||
|
||||
用于新增或修改页面、公共 UI、主题、双语文案、Vue Hooks 或指令。TablePro 和布局各有更窄的入口:[表格](table-pro.md)、[布局](layout.md)。
|
||||
Use this topic when adding or changing pages, shared UI, themes, bilingual copy, Vue hooks, or directives. TablePro and layout have narrower entry points: [tables](table-pro.md) and [layout](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) |
|
||||
| Question | Read first | Follow through |
|
||||
| -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| Pages, login, and demos | [Views](../../apps/admin/src/views), [login page](../../apps/admin/src/views/login/index.tsx), [demo page structure](../../apps/admin/src/views/demo/components/DemoPage.tsx) | [Route registration](routing.md), [visual conventions](../../docs/ui-design.md) |
|
||||
| Shared components such as Modal, Segment, charts, and barcodes | [Application component entry point](../../apps/admin/src/components/index.ts), [shared UI exports](../../packages/ui/package.json) | [Implementations](../../packages/ui/src), [API reference](../../apps/docs/reference/components.md) |
|
||||
| Components and providers that depend on template state | [Application component guide](../../apps/admin/src/app-components/README.md) | [App composition](../../apps/admin/src/App.tsx), [Naive UI autocomplete defaults](../../apps/admin/src/app-components/provider/AppAutocompleteDefaults) |
|
||||
| Themes, styles, and application copy | [Design configuration](../../apps/admin/src/app-config/design-config.ts), [style entry point](../../apps/admin/src/styles/entry.ts), [locale resources](../../apps/admin/src/locales/README.md) | [Application theme hook](../../apps/admin/src/hooks/template/useTheme.ts), [shared theme](../../packages/ui/src/theme.css), [documentation-site styles](docs.md) |
|
||||
| Hooks and global directives | [Application hooks](../../apps/admin/src/hooks/index.ts), [shared composables](../../packages/composables/src/index.ts), [application directive registration](../../apps/admin/src/directives/index.ts) | [Hook guide](../../apps/admin/src/hooks/README.md), [shared directives](../../packages/directives/src/modules), [directive usage](../../apps/admin/src/directives/README.DIR.md) |
|
||||
|
||||
应用的 `@/components` 和部分 Hook/指令路径保留兼容导出;修通用行为前沿导出进入所属共享包。宿主特有服务通过注入接入,避免共享包引用应用别名。界面新增文案应补齐中英文。
|
||||
The application's `@/components` and some hook/directive paths retain compatibility exports. Follow exports into the owning shared package before fixing common behavior. Inject host-specific services instead of referencing application aliases from shared packages. Add both Chinese and English for new interface copy.
|
||||
|
||||
新增组件前先按 [Harness 复用约定](../README.md#工程约定) 核对现有能力。内容撑满与独立滚动可先看 [TablePro 高度样式](../../packages/ui/src/RTablePro/src/index.scss)、[布局高度变量](../../packages/admin-shell/src/layout-css-vars.ts) 和 [用户管理页](../../apps/admin/src/views/user-management/index.tsx):`RTablePro autoHeight` 配合 `--r-table-height` 填充宿主;Naive UI `NCard contentScrollable` 与 `NScrollbar` 负责滚动,父级通过 Flex/Grid 和 `min-block-size: 0` 提供可收缩的确定高度。
|
||||
Before adding a component, check existing capabilities using the [Harness reuse conventions](../README.md#engineering-conventions). For full-height content and independent scrolling, start with [TablePro height styles](../../packages/ui/src/RTablePro/src/index.scss), [layout height variables](../../packages/admin-shell/src/layout-css-vars.ts), and the [user management page](../../apps/admin/src/views/user-management/index.tsx). `RTablePro autoHeight` uses `--r-table-height` to fill its host. Naive UI's `NCard contentScrollable` and `NScrollbar` handle scrolling; the parent uses Flex/Grid and `min-block-size: 0` to provide a definite height that can shrink.
|
||||
|
||||
定向验证:`pnpm harness verify ui`,先按实际行为选择[组件](../../__test__/components)、[Hooks](../../__test__/hooks)或[跨包消费](../../__test__/workspace/consumer.spec.tsx)用例。涉及页面效果,按 [Harness 浏览器验收](../README.md#浏览器验收) 检查。
|
||||
Targeted verification: for small fixes, run the relevant [component](../../__test__/components), [hook](../../__test__/hooks), or [cross-package consumer](../../__test__/workspace/consumer.spec.tsx) test file. Use `pnpm harness verify ui` for scope-level regression coverage; it runs Vitest without launching a browser. For visible effects or interactions, choose pages and dimensions using [Harness browser verification](../README.md#browser-verification).
|
||||
|
||||
@ -1,14 +1,14 @@
|
||||
# 工具、缓存与数据兼容
|
||||
# Utilities, caches, and data compatibility
|
||||
|
||||
用于修改基础工具、精度、文件、缓存读写或历史密文。先通过[应用入口说明](../../apps/admin/src/utils/README.md)确认实现归属。
|
||||
Use this topic for basic utilities, precision, files, cache access, or legacy ciphertext. Confirm implementation ownership through the [application entry-point guide](../../apps/admin/src/utils/README.md) first.
|
||||
|
||||
| 要查什么 | 先读 | 接着追踪 |
|
||||
| ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| 精度、对象、文件与基础工具 | [共享包导出](../../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) |
|
||||
| Question | Read first | Follow through |
|
||||
| ----------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| Precision, objects, files, and basic utilities | [Shared exports](../../packages/utils/package.json), [shared utilities](../../packages/utils/src) | [Application compatibility entry point](../../apps/admin/src/utils/index.ts), [utility API](../../apps/docs/reference/utils.md) |
|
||||
| Application cache keys, Storage backends, and documentation-example isolation | [Application cache](../../apps/admin/src/utils/cache.ts), [cache backend](../../apps/admin/src/utils/cache-backend.ts), [key prefix](../../apps/admin/src/utils/app/prefix-cache-key.ts) | [Cache-key configuration](../../apps/admin/src/app-config/app-config.ts), [shared JSON storage](../../packages/utils/src/storage.ts), [layout and state](layout.md) |
|
||||
| Legacy synchronous AES ciphertext | [Compatibility implementation](../../apps/admin/src/utils/legacy-crypto), [legacy import entry point](../../apps/admin/src/utils/c/index.ts) | [Ciphertext regressions](../../__test__/utils-contracts/legacy-crypto.spec.ts) |
|
||||
| Vue lifecycle, DOM, and element utilities | [Shared composables and utilities](../../packages/composables/src) | [Application hooks and UI](ui.md), [Vue utility regressions](../../__test__/vue) |
|
||||
|
||||
保持调用方依赖的 key、存储类型和序列化格式。共享存储由调用方传入 Storage 实现;应用持久化和文档 iframe 的内存缓存需分别检查。同步 AES 格式或 API 若需替换,先设计历史数据迁移。
|
||||
Preserve keys, storage types, and serialization formats that callers depend on. Callers supply the Storage implementation to shared storage. Check application persistence and documentation iframe in-memory caches separately. Design historical-data migration before replacing a synchronous AES format or API.
|
||||
|
||||
定向验证:`pnpm harness verify utils`,从[缓存测试](../../__test__/cache)、[精度测试](../../__test__/precision)或[工具契约](../../__test__/utils-contracts)选择与任务相关的回归。
|
||||
Targeted verification: `pnpm harness verify utils`. Select relevant regressions from [cache tests](../../__test__/cache), [precision tests](../../__test__/precision), or [utility contracts](../../__test__/utils-contracts).
|
||||
|
||||
@ -1,41 +1,72 @@
|
||||
# AI Harness 建设计划
|
||||
# AI Harness development plan
|
||||
|
||||
目标是让接手 Ray Template 的开发者和 AI 助手,能按任务找到相关代码、独立复现验证,并把实际结果交给下一位维护者。工程入口和命令见 [AI Harness](README.md)。
|
||||
The goal is to help developers and AI agents taking over Ray Template find relevant code by task, reproduce checks independently, and pass observed results to the next maintainer. Entry points and commands are in the [AI Harness](README.md).
|
||||
|
||||
| 阶段 | 建设内容 | 验收条件 |
|
||||
| ------------- | ---------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
|
||||
| 1. 收拢上下文 | 重写根 `AGENTS.md`,移除旧工具配置和旧开发指南。保留架构、注释、视觉和工具链的各自职责 | README 指向新入口,活跃文档没有旧指南引用。TypeScript 项目说明可从架构地图找到 |
|
||||
| 2. 建立反馈 | 按路由、UI、API、图标、公共工具和 Harness 提供上下文与回归。复用 pnpm、Vitest 和构建命令 | 任务域可查询,定向验证可执行,缺失的上下文或回归路径会被拒绝 |
|
||||
| 3. 接入验收 | 将 Harness 校验纳入 `pnpm check` 和现有 CI,提供本机 JSON 报告与浏览器验收步骤 | 定向和全量运行均可追溯,失败会以非零退出码返回,报告与截图排除在源码和打包输入之外 |
|
||||
| Phase | Work | Acceptance criteria |
|
||||
| ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| 1. Consolidate context | Rewrite root `AGENTS.md`; remove obsolete tool configuration and development guides. Keep architecture, comments, visual guidance, and toolchain records in their respective roles. | The README points to the new entry point; active documents do not reference old guides. TypeScript project information is reachable from the architecture map. |
|
||||
| 2. Establish feedback | Provide context and regressions for routing, UI, APIs, icons, shared utilities, and Harness. Reuse pnpm, Vitest, and build commands. | Task areas can be queried, targeted checks run, and missing context or regression paths are rejected. |
|
||||
| 3. Integrate verification | Add Harness validation to `pnpm check` and existing CI; provide local JSON reports and browser verification guidance. | Targeted and full runs are traceable; failures return nonzero exit codes; reports and screenshots are excluded from source and package inputs. |
|
||||
|
||||
日常维护时,以实际反复出现的失败为依据扩充 Harness。优先将已有覆盖缺口补进 Vitest,待浏览器流程有稳定夹具和可重复结果时,再评估纳入自动化门禁。迁移的实测结果见 [工具链记录](../docs/toolchain-upgrade.md)。
|
||||
Expand the Harness in response to repeated observed failures. Prefer filling coverage gaps in Vitest. Consider browser automation as a required gate only after its fixtures and results are stable and reproducible. Measured migration results are in the [toolchain record](../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)。
|
||||
The design draws on [OpenAI's repository workflow practices](https://developers.openai.com/cookbook/examples/codex/iterating-development-workflows-with-codex) and [context-layering guidance](https://developers.openai.com/blog/rethinking-skills-and-prompts-for-gpt-6-astra).
|
||||
|
||||
## Monorepo 索引补全
|
||||
## Completing the monorepo index
|
||||
|
||||
审查基线为 `58fc0b63`。现有命令、回归和报告已形成反馈闭环,主要缺口在查找和判断代码归属:
|
||||
Review baseline: `58fc0b63`. Existing commands, regressions, and reports already formed a feedback loop. The main gap was locating code and determining ownership:
|
||||
|
||||
| 发现 | 影响 |
|
||||
| -------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
|
||||
| 架构地图混用旧 `src/` 路径与工作区路径,仍将路由、图标和组件实现归到应用目录 | 目录存在不等于拥有实现。例如应用侧 Schema、取消器和部分组件只是兼容入口 |
|
||||
| `ui` 同时覆盖布局、公共组件、文案、Hooks 和演示;没有 TablePro、文档站及构建的独立入口 | 查表格筛选或 VitePress 重定向时,需要自行从大目录找实现、示例和验证 |
|
||||
| `llms.txt`、架构地图与 `scopes.json` 分别列源码路径;检查只覆盖 JSON 里的路径 | 文件移动后,入口和说明可以互相矛盾而全量检查仍通过 |
|
||||
| Finding | Impact |
|
||||
| ----------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| The architecture map mixed old `src/` paths with workspace paths and still assigned routing, icons, and component implementations to the application. | An existing directory does not imply ownership. Application schemas, cancellers, and some components are compatibility entry points. |
|
||||
| `ui` covered layout, shared components, copy, hooks, and demos, without separate entry points for TablePro, the documentation site, or builds. | Table filtering and VitePress redirects required manual searches across broad directories for implementation, examples, and verification. |
|
||||
| `llms.txt`, the architecture map, and `scopes.json` maintained separate source-path lists; validation covered only the JSON paths. | After a move, entry points and descriptions could contradict each other while full checks still passed. |
|
||||
|
||||
### 设计
|
||||
### Design
|
||||
|
||||
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 执行。范围是导航文档,不追踪外链或证明描述正确;语义通过走查和回归验证。
|
||||
1. Keep repository-wide collaboration rules and entry points in `AGENTS.md`. Use `llms.txt` as a task router that needs no runtime, linking to the [architecture map](../docs/architecture.md) and individual topics as needed.
|
||||
2. Organize `harness/context/<scope>.md` around actual questions, listing first-read source, application/shared-package/example boundaries, and relevant tests. Keep behavior contracts in source, nearby READMEs, and public documentation. The architecture map covers workspaces, key runtime flows, and deployment.
|
||||
3. Keep topic descriptions and executable verification configuration in `scopes.json`. Each ID resolves to a matching index displayed by `context <scope>`. Preserve the six existing IDs and their tests; add TablePro, layout, documentation, and toolchain scopes. Documentation and toolchain scopes use existing check scripts.
|
||||
4. Validate index entry points, relative links, and test targets through the existing `harness check`, still invoked by `pnpm check` and CI. This checks navigation documents, not external links or prose correctness; verify semantics through walkthroughs and regressions.
|
||||
|
||||
### 实施前自审
|
||||
### Design review before implementation
|
||||
|
||||
| 检查 | 修订后的决定 |
|
||||
| -------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
|
||||
| 是否要在 JSON 和 Markdown 重复维护实现路径? | 用同名索引作为 CLI 输出,正文只维护一份;不生成第二份源码树 |
|
||||
| 是否让每个任务先跑命令、阅读全图? | 保留静态入口;按需求打开一张主题索引。架构图用于跨模块任务,不作为前置必读 |
|
||||
| 是否给所有任务域强行配 Vitest? | 文档用 `docs:check`;工具链用包边界与类型检查。明确哪些问题仍需生产预览或全量检查 |
|
||||
| 是否能区分同名入口与真正实现? | 用 TablePro 搜索、动态路由、请求取消、偏好导入、旧文档重定向和部署产物逐条走查,索引写明主实现和宿主适配 |
|
||||
| Question | Decision |
|
||||
| --------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| Should JSON and Markdown duplicate implementation paths? | Use the matching index as CLI output and maintain prose once; do not generate a second source tree. |
|
||||
| Should every task start with a command and a full architecture read? | Keep the static entry point and open the relevant topic. The architecture map supports cross-module tasks; it is not mandatory startup reading. |
|
||||
| Should every scope have Vitest tests? | Use `docs:check` for documentation and package/type checks for the toolchain. State which cases still need a production preview or full checks. |
|
||||
| Can compatibility entry points be distinguished from implementations? | Walk through TablePro search, dynamic routes, request cancellation, preference import, legacy documentation redirects, and deployment artifacts. Name the primary implementation and host adapter in the index. |
|
||||
|
||||
验收:静态入口可到达所有主题;原命令和报告契约兼容;断链、缺失主题和失效回归路径会使检查失败;代表任务能从索引到达实现和验证;最后执行 `pnpm harness verify`。
|
||||
Acceptance for that development batch: all topics are reachable from the static entry point; existing command and report contracts remain compatible; broken links, missing topics, and invalid regression paths fail validation; representative tasks reach the implementation and checks; finish with `pnpm harness verify`. For everyday tasks, follow the [README verification scope](README.md#choosing-the-verification-scope).
|
||||
|
||||
## 2026-11-06: Structure review and verification scope
|
||||
|
||||
Local review baseline: `969f764c`. The review covered root collaboration rules, 10 topic indexes and their registry, CLI/tests, architecture and documentation coordination, visual conventions, the PR template, Git hooks, CI, and local evidence directories. It was not a code review of every business implementation.
|
||||
|
||||
### Comparison with official guidance
|
||||
|
||||
| Official recommendation | Project assessment |
|
||||
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
||||
| [Codex Best practices](https://learn.chatgpt.com/docs/learn/best-practices): concise repository guidance, task-specific context, clear completion criteria, and relevant checks | The `AGENTS.md` → `llms.txt` → topic index → source/contracts/tests hierarchy is sound. Consult the architecture map and historical records as needed; the directory structure does not need rebuilding. |
|
||||
| [Iterating Development Workflows](https://developers.openai.com/cookbook/examples/codex/iterating-development-workflows-with-codex): example files are adaptable workflow conventions | Existing `plan.md`, toolchain records, and local reports respectively hold design, observed verification, and command evidence. Copying filenames such as `GOALS.md`, `PLANS.md`, and `PROMPTS.md` is unnecessary. |
|
||||
| [Rethinking skills and prompts](https://developers.openai.com/blog/rethinking-skills-and-prompts-for-gpt-6-astra): reduce irrelevant context and excessive testing instructions | Requiring full checks after every implementation or integration, plus fixed page/documentation matrices, inflated the cost of small fixes. Select verification by impact instead. |
|
||||
|
||||
These sources offer practices, not a uniform Harness certification or directory compliance standard. The existing structure follows the main design principles; verification granularity needed adjustment.
|
||||
|
||||
### Findings and changes
|
||||
|
||||
| Finding | Change |
|
||||
| ---------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| Root guidance and delegation rules escalated every implementation to full checks. | Default to relevant test files or scopes. Run full checks once for integration risk, releases, or explicit requests; rerun only affected checks afterward. |
|
||||
| Visual guidance, the PR template, and documentation coordination turned page changes into a fixed list of languages, themes, viewports, and site features. | Point to the Harness condition table. Add dimensions based on the actual change, choose representative shared consumers, and skip browsers for rules or maintainer documentation alone. |
|
||||
| Targeted `api` regressions omitted OpenAPI/worker synchronization; `icons` required a separate manual manifest check. | Register existing `api:check` and `icons:check` in their scopes. Retain the CLI script allowlist and stop before regressions when generated artifacts are stale. |
|
||||
| `verify ui` could be mistaken for browser verification. | Clarify in the topic and CLI help that it runs registered commands only. Its JSON report does not establish browser acceptance. |
|
||||
|
||||
### Retained behavior and verification limits
|
||||
|
||||
- All 10 topics are reachable from the static entry point. Each of the 81 enumerated `.spec.ts/.spec.tsx` files belongs to at least one scope. Index validation establishes path existence and valid targets, not accurate prose or sufficient behavior coverage.
|
||||
- `ui` covers 37 test files and is suitable for scope-level regressions. A single-behavior fix can run its test file directly and record the result in the delivery note. Reuse existing entry points without adding a second system to infer scope from Git diffs and dependencies.
|
||||
- Preserve full checks when scope is omitted for command compatibility. Everyday guidance should show an explicit scope. Keep CI's three-platform `pnpm check` and deployment dependencies unchanged.
|
||||
- Continue writing local reports to `.harness-local/`, excluded from Git, lint/format scans, and package inputs. Full-report phase details still depend on terminal output. Record browser evidence separately; static checks do not prove runtime success.
|
||||
- Regressions cover targeted commands not appending full checks, stopping on generated-artifact check failure, and compatibility of explicit/legacy full-check entry points. Actual run results are in the [toolchain record](../docs/toolchain-upgrade.md). This change has no page effect and needs no UI/UX verification.
|
||||
|
||||
@ -18,7 +18,13 @@ 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 allowedChecks = new Set([
|
||||
'api:check',
|
||||
'docs:check',
|
||||
'icons:check',
|
||||
'packages:check',
|
||||
'typecheck',
|
||||
])
|
||||
const indexFiles = [
|
||||
'AGENTS.md',
|
||||
'llms.txt',
|
||||
@ -42,25 +48,27 @@ function checkScopes() {
|
||||
scopes,
|
||||
)) {
|
||||
if (!scopePattern.test(name) || name === 'all') {
|
||||
problems.push(`无效任务域:${name}`)
|
||||
problems.push(`Invalid scope: ${name}`)
|
||||
}
|
||||
|
||||
if (typeof description !== 'string' || !description.trim()) {
|
||||
problems.push(`${name} 需要任务描述`)
|
||||
problems.push(`${name} requires a task description`)
|
||||
}
|
||||
|
||||
if (!Array.isArray(tests) || !Array.isArray(checks)) {
|
||||
problems.push(`${name} 的 tests 和 checks 必须为数组`)
|
||||
problems.push(`${name}: tests and checks must be arrays`)
|
||||
continue
|
||||
}
|
||||
|
||||
if (tests.length === 0 && checks.length === 0) {
|
||||
problems.push(`${name} 需要至少一个回归测试路径或检查命令`)
|
||||
problems.push(
|
||||
`${name} requires at least one regression test path or check command`,
|
||||
)
|
||||
}
|
||||
|
||||
for (const script of checks) {
|
||||
if (!allowedChecks.has(script) || typeof scripts?.[script] !== 'string') {
|
||||
problems.push(`${name} 的检查命令未注册:${script}`)
|
||||
problems.push(`${name}: unregistered check command: ${script}`)
|
||||
}
|
||||
}
|
||||
|
||||
@ -70,7 +78,7 @@ function checkScopes() {
|
||||
!testPattern.test(path) ||
|
||||
!existsSync(join(root, path))
|
||||
) {
|
||||
problems.push(`${name} 的回归测试路径无效:${path}`)
|
||||
problems.push(`${name}: invalid regression test path: ${path}`)
|
||||
continue
|
||||
}
|
||||
|
||||
@ -81,7 +89,9 @@ function checkScopes() {
|
||||
: stat.isFile()
|
||||
|
||||
if (!hasTests) {
|
||||
problems.push(`${name} 的回归测试路径没有用例:${path}`)
|
||||
problems.push(
|
||||
`${name}: regression test path contains no tests: ${path}`,
|
||||
)
|
||||
}
|
||||
}
|
||||
}
|
||||
@ -100,7 +110,7 @@ function checkIndexes() {
|
||||
const file = join(root, path)
|
||||
|
||||
if (!existsSync(file) || !statSync(file).isFile()) {
|
||||
problems.push(`索引文档不存在:${path}`)
|
||||
problems.push(`Index document does not exist: ${path}`)
|
||||
continue
|
||||
}
|
||||
|
||||
@ -122,7 +132,7 @@ function checkIndexes() {
|
||||
fromRoot.startsWith(`..${sep}`) ||
|
||||
!existsSync(destination)
|
||||
) {
|
||||
problems.push(`${path} 的相对链接无效:${href}`)
|
||||
problems.push(`${path}: invalid relative link: ${href}`)
|
||||
} else if (path === 'llms.txt') {
|
||||
entryLinks.add(destination)
|
||||
}
|
||||
@ -131,13 +141,13 @@ function checkIndexes() {
|
||||
|
||||
for (const path of cards) {
|
||||
if (!entryLinks.has(join(root, path))) {
|
||||
problems.push(`llms.txt 缺少可用的主题链接:${path}`)
|
||||
problems.push(`llms.txt is missing a valid topic link: ${path}`)
|
||||
}
|
||||
}
|
||||
|
||||
for (const file of globSync('harness/context/*.md', { cwd: root })) {
|
||||
if (!cards.includes(file.split(sep).join('/'))) {
|
||||
problems.push(`主题索引尚未注册:${file}`)
|
||||
problems.push(`Unregistered topic index: ${file}`)
|
||||
}
|
||||
}
|
||||
|
||||
@ -167,9 +177,9 @@ function showContext(name) {
|
||||
|
||||
const path = contextPath(name)
|
||||
|
||||
console.log(`阅读入口:${path}(正文链接相对此文件)\n`)
|
||||
console.log(`Entry point: ${path} (body links are relative to this file)\n`)
|
||||
console.log(readFileSync(join(root, path), 'utf8').trimEnd())
|
||||
console.log(`\npnpm harness verify ${name} 执行:`)
|
||||
console.log(`\npnpm harness verify ${name} runs:`)
|
||||
|
||||
for (const args of scopeCommands(name)) {
|
||||
console.log(` pnpm ${args.join(' ')}`)
|
||||
@ -216,7 +226,7 @@ function verify(name) {
|
||||
exitCode = result.status ?? 1
|
||||
console.error(
|
||||
result.error?.message ??
|
||||
`${command} 失败(${result.signal ?? exitCode})`,
|
||||
`${command} failed (${result.signal ?? exitCode})`,
|
||||
)
|
||||
break
|
||||
}
|
||||
@ -234,7 +244,7 @@ function verify(name) {
|
||||
}
|
||||
|
||||
writeFileSync(reportPath, `${JSON.stringify(report, null, 2)}\n`)
|
||||
console.log(`\n验收报告:${relative(root, reportPath)}`)
|
||||
console.log(`\nVerification report: ${relative(root, reportPath)}`)
|
||||
process.exitCode = exitCode
|
||||
}
|
||||
|
||||
@ -246,9 +256,11 @@ try {
|
||||
Object.hasOwn(scopes, scope)
|
||||
|
||||
if (action === '--help' && !scope) {
|
||||
console.log(`pnpm harness context [scope] 查看任务上下文
|
||||
pnpm harness verify [scope] 定向验证,省略 scope 时执行全量检查
|
||||
pnpm harness check 检查主题索引、相对链接和验证目标`)
|
||||
console.log(`pnpm harness context [scope] Show task context
|
||||
pnpm harness verify <scope> Run targeted commands for everyday changes
|
||||
pnpm harness verify all Run full checks (omitting scope still runs all)
|
||||
pnpm harness check Validate topic indexes, relative links, and targets
|
||||
These commands do not launch a browser. Verify UI/UX separately by impact; see harness/README.md.`)
|
||||
} else if (
|
||||
action === 'context' &&
|
||||
extra.length === 0 &&
|
||||
@ -264,10 +276,12 @@ pnpm harness check 检查主题索引、相对链接和验证目标
|
||||
} else if (action === 'check' && !scope) {
|
||||
checkScopes()
|
||||
checkIndexes()
|
||||
console.log('✓ Harness 索引、相对链接和验证目标有效')
|
||||
console.log(
|
||||
'✓ Harness indexes, relative links, and verification targets are valid',
|
||||
)
|
||||
} else {
|
||||
throw new Error(
|
||||
'无效命令或任务域。使用 pnpm harness --help 或 pnpm harness context。',
|
||||
'Invalid command or scope. Use pnpm harness --help or pnpm harness context.',
|
||||
)
|
||||
}
|
||||
} catch (error) {
|
||||
|
||||
@ -1,6 +1,6 @@
|
||||
{
|
||||
"routing": {
|
||||
"description": "页面注册、菜单、动态路由 JSON、角色与守卫",
|
||||
"description": "Page registration, menus, dynamic route JSON, roles, and guards",
|
||||
"tests": [
|
||||
"__test__/router/",
|
||||
"__test__/hooks/useVueRouter.spec.ts",
|
||||
@ -10,7 +10,7 @@
|
||||
]
|
||||
},
|
||||
"layout": {
|
||||
"description": "启动、Provider、布局、KeepAlive、Pinia 与偏好文件",
|
||||
"description": "Bootstrap, providers, layout, KeepAlive, Pinia, and preference files",
|
||||
"tests": [
|
||||
"__test__/app/",
|
||||
"__test__/layout/",
|
||||
@ -22,7 +22,7 @@
|
||||
]
|
||||
},
|
||||
"ui": {
|
||||
"description": "页面、公共组件、主题、国际化、Hooks 与指令",
|
||||
"description": "Pages, shared components, themes, internationalization, hooks, and directives",
|
||||
"tests": [
|
||||
"__test__/app/",
|
||||
"__test__/components/",
|
||||
@ -32,7 +32,7 @@
|
||||
]
|
||||
},
|
||||
"table-pro": {
|
||||
"description": "RTablePro、useTablePro、搜索、分页、选列、导出与打印",
|
||||
"description": "RTablePro, useTablePro, search, pagination, column selection, export, and printing",
|
||||
"tests": [
|
||||
"__test__/components/table-pro.spec.ts",
|
||||
"__test__/components/table-pro-search.spec.ts",
|
||||
@ -41,7 +41,8 @@
|
||||
]
|
||||
},
|
||||
"api": {
|
||||
"description": "业务 API、Axios、请求取消、拦截器与演示 Mock",
|
||||
"description": "Business APIs, Axios, request cancellation, interceptors, and demo mocks",
|
||||
"checks": ["api:check"],
|
||||
"tests": [
|
||||
"__test__/axios/",
|
||||
"__test__/mock/",
|
||||
@ -49,7 +50,7 @@
|
||||
]
|
||||
},
|
||||
"utils": {
|
||||
"description": "公共工具、缓存、历史密文和兼容入口",
|
||||
"description": "Shared utilities, caches, legacy ciphertext, and compatibility entry points",
|
||||
"tests": [
|
||||
"__test__/basic/",
|
||||
"__test__/cache/",
|
||||
@ -61,19 +62,20 @@
|
||||
]
|
||||
},
|
||||
"icons": {
|
||||
"description": "SVG 分包、图标名、清单生成和热更新",
|
||||
"description": "SVG groups, icon names, manifest generation, and hot updates",
|
||||
"checks": ["icons:check"],
|
||||
"tests": ["__test__/icons/"]
|
||||
},
|
||||
"docs": {
|
||||
"description": "VitePress、API 参考、内嵌示例、侧栏与旧页跳转",
|
||||
"description": "VitePress, API references, embedded examples, sidebars, and legacy redirects",
|
||||
"checks": ["docs:check"]
|
||||
},
|
||||
"toolchain": {
|
||||
"description": "工作区、公开导出、类型检查、Vite、构建与 CI",
|
||||
"description": "Workspaces, public exports, type checking, Vite, builds, and CI",
|
||||
"checks": ["packages:check", "typecheck"]
|
||||
},
|
||||
"harness": {
|
||||
"description": "索引、回归范围、验证命令和本地报告",
|
||||
"description": "Indexes, regression scope, verification commands, and local reports",
|
||||
"tests": ["__test__/harness/"]
|
||||
}
|
||||
}
|
||||
|
||||
32
llms.txt
32
llms.txt
@ -1,23 +1,23 @@
|
||||
# Ray Template
|
||||
|
||||
> Vue 3 + TypeScript/TSX 中后台模板。pnpm workspace 包含后台应用、VitePress 文档站和共享包。
|
||||
> A Vue 3 + TypeScript/TSX admin template. The pnpm workspace contains the admin application, the VitePress documentation site, and shared packages.
|
||||
|
||||
遵循 [AGENTS.md](AGENTS.md),按任务选择下列入口。索引可直接阅读,也可用 `pnpm harness context <scope>` 查看同一份内容和定向验证命令。
|
||||
Follow [AGENTS.md](AGENTS.md) and select the entry point for the task. Read this index directly, or use `pnpm harness context <scope>` to display the same content and targeted verification commands.
|
||||
|
||||
## 任务索引
|
||||
## Task index
|
||||
|
||||
- [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):索引维护、回归目标、验证命令与报告。
|
||||
- [routing](harness/context/routing.md): Pages and menus, dynamic route JSON, view IDs, roles, and guards.
|
||||
- [layout](harness/context/layout.md): Bootstrap, providers, navigation, KeepAlive, Pinia, and preference import/export.
|
||||
- [ui](harness/context/ui.md): Shared components, pages and login, themes and bilingual copy, hooks, and directives.
|
||||
- [table-pro](harness/context/table-pro.md): RTablePro, useTablePro, search, requests, column selection, export, and printing.
|
||||
- [api](harness/context/api.md): Business APIs, Axios, AbortSignal, interceptors, mocks, and static data.
|
||||
- [utils](harness/context/utils.md): Precision, files, storage, legacy AES formats, and application compatibility entry points.
|
||||
- [icons](harness/context/icons.md): SVG groups, icon names, manifest generation, and hot updates.
|
||||
- [docs](harness/context/docs.md): VitePress, API references, embedded examples, sidebars, and legacy redirects.
|
||||
- [toolchain](harness/context/toolchain.md): Workspace dependencies, public exports, TypeScript, Vite, build artifacts, and CI.
|
||||
- [harness](harness/context/harness.md): Index maintenance, regression targets, verification commands, and reports.
|
||||
|
||||
## 按需背景
|
||||
## Background when needed
|
||||
|
||||
- [架构地图](docs/architecture.md):工作区边界、运行链路、类型检查和部署。
|
||||
- [AI Harness](harness/README.md):验证流程、浏览器验收和本地证据。
|
||||
- [Architecture map](docs/architecture.md): Workspace boundaries, runtime flows, type checking, and deployment.
|
||||
- [AI Harness](harness/README.md): Verification workflow, browser verification, and local evidence.
|
||||
|
||||
@ -1,6 +1,6 @@
|
||||
# SVG 图标
|
||||
# SVG icons
|
||||
|
||||
图标使用相对目录作为完整名称,不再依赖全局唯一的文件名:
|
||||
Icon names include their relative directory instead of relying on globally unique filenames:
|
||||
|
||||
```tsx
|
||||
import { RIcon } from '@/components'
|
||||
@ -10,33 +10,33 @@ const name: IconName = 'directional/resize_h'
|
||||
<RIcon name={name} />
|
||||
```
|
||||
|
||||
`RIcon.name`、路由 `meta.icon`、侧栏 Logo 和图标包装组件共享严格的 `IconName` 联合类型。输入 `name` 时可获得完整分包路径提示,裸名称与不存在的路径会被 TypeScript 拒绝。类型来自文件生成,并非 TypeScript 自行读取文件系统。
|
||||
`RIcon.name`, route `meta.icon`, sidebar logos, and icon wrappers share the strict `IconName` union. Completion for `name` includes full group paths; TypeScript rejects bare names and nonexistent paths. Types are generated from files, not obtained by TypeScript reading the filesystem.
|
||||
|
||||
## 分包
|
||||
## Groups
|
||||
|
||||
| 目录 | 用途 |
|
||||
| --- | --- |
|
||||
| `action` | 搜索、刷新、关闭、全屏、设置、打印等操作 |
|
||||
| `directional` | 箭头、方向、行首行尾与尺寸方向 |
|
||||
| `navigation` | 页面和功能导航 |
|
||||
| `logo` | 品牌及产品标识 |
|
||||
| `status` | 错误、帮助等状态提示 |
|
||||
| `system` | 语言、明暗主题与系统偏好 |
|
||||
| Directory | Purpose |
|
||||
| ------------- | ------------------------------------------------------------------------ |
|
||||
| `action` | Search, reload, close, fullscreen, settings, printing, and other actions |
|
||||
| `directional` | Arrows, directions, row start/end, and resizing directions |
|
||||
| `navigation` | Page and feature navigation |
|
||||
| `logo` | Brand and product marks |
|
||||
| `status` | Error, help, and other status indicators |
|
||||
| `system` | Language, light/dark themes, and system preferences |
|
||||
|
||||
文件/目录使用小写字母、数字、下划线或连字符,首字符为字母;SVG 必须位于分包内。允许嵌套,例如 `business/orders/approved.svg` 对应 `business/orders/approved`。不同分包允许同名文件。
|
||||
Use lowercase letters, digits, underscores, or hyphens for filenames/directories, starting with a letter. SVGs must be inside a group. Nesting is supported: `business/orders/approved.svg` becomes `business/orders/approved`. Different groups may contain the same filename.
|
||||
|
||||
单色图标使用 `currentColor`,有意留白用 `none`。品牌保留原色,不保证 `color` 覆盖其所有颜色。避免包含内置脚本、事件处理器和外部资源。
|
||||
Monochrome icons use `currentColor`, with `none` for intentional empty areas. Brand marks retain original colors; `color` does not necessarily override every color. Avoid embedded scripts, event handlers, and external resources.
|
||||
|
||||
常规按钮使用 `<RIcon name="action/search" />` 即可,默认盒子为 20 px。菜单等组件已经定义图标尺寸时使用 `size="1em"`;紧凑的关闭按钮、行内提示或品牌标识可显式设定尺寸。新通用 SVG 要在同尺寸下比对现有线性图标:正方形视图框、主体约占 85%,箭头或省略号可多留一点空间。使用 `currentColor` 着色,并在浅色与深色背景检查小尺寸下的线条和留白。
|
||||
For ordinary buttons, `<RIcon name="action/search" />` uses the default 20 px box. Use `size="1em"` when a containing component, such as a menu, already defines icon sizing. Compact close buttons, inline hints, and brand marks can set explicit dimensions. Compare new generic SVGs with existing line icons at the same size: use a square viewBox and a subject occupying about 85%, allowing more whitespace for arrows or ellipses. Use `currentColor` and inspect small-size strokes/spacing on both light and dark backgrounds.
|
||||
|
||||
详见[来源与授权清单](../ICON-SOURCES.md)。旧版的导出 Excel、Office 和登录插画已退役;读取历史路由和菜单时会分别迁移到下载、表格和通用页面图标。
|
||||
See the [source and license inventory](../ICON-SOURCES.md). Legacy Excel export, Office, and login illustration icons were retired. Historical route/menu reads migrate them to download, table, and generic-page icons respectively.
|
||||
|
||||
## 自动生成与注入
|
||||
## Generation and injection
|
||||
|
||||
- 新增、修改、删除或移动 SVG 时,开发服务自动检查并同步 `packages/icons/src/manifest.ts`;增加或删除整个分包时自动重启开发服务。
|
||||
- `pnpm dev`、`build`、`dev-build`、`report` 和 `check` 都先自动生成清单;直接调用 Vite 时也由插件在启动/构建阶段同步。`typecheck` 与 `icons:check` 继续保持只读。也可单独运行 `pnpm icons:generate`。将更新后的清单与 SVG 一起维护。生成文件由项目 Prettier 配置格式化,模板同时遵守 ESLint 的声明空行规则。
|
||||
- `pnpm icons:check` 检查清单是否与目录一致,`pnpm typecheck` 和 `pnpm check` 会执行它。请修改生成脚本,不手工维护联合类型。
|
||||
- 每个顶层分包输出独立带 hash 的 SVG 雪碧图。生成的分包地址由 Spritemap 插件转换为随 Vite base 的开发/生产路径,`RIcon` 根据 name 的包名选择地址,再引用包含完整路径的 symbol ID。
|
||||
- `/svg-icons` 提供分包筛选和路径搜索。点击图标默认复制 TSX 用法,也可切换到 Vue 模板格式。
|
||||
- Adding, editing, deleting, or moving an SVG causes the development server to check/synchronize `packages/icons/src/manifest.ts`. Adding/removing an entire group restarts the server automatically.
|
||||
- `pnpm dev`, `build`, `dev-build`, `report`, and `check` generate the manifest first. Direct Vite calls also synchronize through the plugin at startup/build time. `typecheck` and `icons:check` remain read-only. `pnpm icons:generate` can run separately. Maintain updated manifests alongside SVG changes. Generated files use project Prettier settings and preserve ESLint declaration-spacing rules.
|
||||
- `pnpm icons:check` checks manifest/directory consistency; `pnpm typecheck` and `pnpm check` run it. Modify the generator rather than maintaining the union type manually.
|
||||
- Each top-level group produces a separate hashed SVG spritemap. The Spritemap plugin turns generated group addresses into development/production paths respecting the Vite base. `RIcon` selects the address from the name's group, then references a symbol ID containing the full path.
|
||||
- `/svg-icons` provides group filtering and path search. Clicking an icon copies TSX usage by default; Vue template format is also available.
|
||||
|
||||
旧版本缓存里的裸 Logo 或菜单图标名在读取边界通过 `resolveIconName` 迁移;仅当文件名唯一时转换。新代码必须使用完整路径,不为裸名放宽组件类型。
|
||||
At read boundaries, `resolveIconName` migrates bare logo/menu icon names from older caches only when the filename is unique. New code must use full paths; do not widen component types to accept bare names.
|
||||
|
||||
@ -1,14 +1,14 @@
|
||||
# RChart 主题
|
||||
# RChart themes
|
||||
|
||||
四套风格分别放在 `modern/`、`naive/`、`material/`、`plain/`,每套都有明、暗两份独立 JSON。文件名是 ECharts 注册名,例如 `modern/ray-modern.json` → `ray-modern`,`modern/ray-modern-dark.json` → `ray-modern-dark`。
|
||||
Four styles live in `modern/`, `naive/`, `material/`, and `plain/`. Each has separate light and dark JSON files. Filenames are ECharts registration names: for example, `modern/ray-modern.json` → `ray-modern` and `modern/ray-modern-dark.json` → `ray-modern-dark`.
|
||||
|
||||
| 风格 | 配色与绘图样式 |
|
||||
| --- | --- |
|
||||
| Modern | Ray 蓝、冷色网格、虚线分隔、轻量面积填充 |
|
||||
| Naive | 翡翠绿、实线网格、较小圆角 |
|
||||
| Material | 紫色调、加粗折线、较大圆角与柔和面积填充 |
|
||||
| Plain | 低饱和色、点线网格、直角柱和无阴影提示框 |
|
||||
| Style | Palette and rendering |
|
||||
| -------- | ------------------------------------------------------------------ |
|
||||
| Modern | Ray blue, cool grid colors, dashed dividers, and subtle area fills |
|
||||
| Naive | Emerald green, solid grids, and smaller corner radii |
|
||||
| Material | Purple tones, thicker lines, larger radii, and soft area fills |
|
||||
| Plain | Muted colors, dotted grids, square bars, and shadow-free tooltips |
|
||||
|
||||
使用 [ECharts 主题编辑器](https://echarts.apache.org/zh/theme-builder.html) 调整时,导出 JSON 放在对应目录。加载器按文件名自动注册;不同目录也不要使用相同的文件名。只有明色文件时继续使用该主题;提供 `-dark.json` 后随应用明暗切换。业务 `options` 中显式设置的颜色和样式仍优先。
|
||||
When editing with the [ECharts theme builder](https://echarts.apache.org/zh/theme-builder.html), export JSON to the appropriate directory. The loader registers themes by filename; filenames must be unique even across directories. A light-only theme remains active for both modes. Adding a `-dark.json` variant enables switching with the application theme. Explicit colors/styles in business `options` still take precedence.
|
||||
|
||||
旧版 `macarons` 与 `macarons-dark` 已移除。原先写死主题名的页面可移除 `theme` 以跟随界面风格,或改成新主题的注册名。
|
||||
Legacy `macarons` and `macarons-dark` themes were removed. Pages with hardcoded names can omit `theme` to follow the interface style or use a new theme registration name.
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user