32 lines
3.7 KiB
Markdown
32 lines
3.7 KiB
Markdown
# 项目长期记忆（Thing / F:\AtieProject\Thing）
|
||
|
||
Tauri + Vue 3 + Pinia + Tailwind v4 + reka-ui(shadcn-vue) 的桌面工具箱，按模块组织（`src/modules/<id>/`）。
|
||
|
||
## 架构约定
|
||
|
||
- **模块挂载**：`App.vue` 的 `ModuleContainer` 用 `:key="activeModule"` 重挂载，**模块不 keep-alive**。因此任何「需要跨模块常驻」的 UI 都必须挂在 `App.vue` 层，不能放在模块内部。
|
||
- **音乐播放器**：内核在 `src/stores/feiniuStore.ts`（不是 musicStore）；UI 入口在**标题栏** `src/components/layout/TitleBarMusic.vue`（搜索框左侧：唱片图标 + 歌名，点击弹出方形控制窗，播放中图标换封面并旋转），大屏 `src/components/layout/NowPlayingDialog.vue`（歌词/队列）由控制窗的入口打开，由 `App.vue` 渲染。`musicStore` 只负责搜索/歌单解析/下载任务。
|
||
- 历史沿革：`PlayerBar/PlayerFull`（模块内）→ `GlobalPlayerBar`（App 全局坞站）→ 现为 `TitleBarMusic`（标题栏）。前者们均已删除，不要再新增底部播放条。
|
||
- **模块顶部 tabs 统一写法**：`<Tabs v-model>` → `<div ref="tabsListRef" class="shrink-0">` → `<TabsList class="grid w-full max-w-md grid-cols-N !bg-transparent !p-0 !shadow-none">` → `TabsTrigger`(带 `class="gap-1.5"` + 图标) → `TabsContent class="mt-4 min-h-0 flex-1 ... tab-animate"`；模块根节点统一 `h-full p-6 overflow-hidden flex flex-col`。
|
||
- 注意：顶部 Tabs 上那个"可见边框"是 `:focus-visible` 的 ring，并非常态样式。别处若要复刻选中态且背景也是白色，需要自己补 `ring-1 ring-border`，否则白色胶囊只靠 `shadow-sm`（5% 透明度）在白底上几乎不可见。
|
||
- **列表/导航行的对齐**：行高用固定值（`h-8` / `h-7`）+ `items-center`，不要靠 `py-x` 推算；右侧数字列始终渲染（空时显示 `0`）并加 `min-w-[3ch] text-right tabular-nums`，否则数字列会参差。
|
||
- 音乐播放走 Rust 本地流代理 `127.0.0.1:<port>/feiniu/stream`，**真流式透传 Range**（`src-tauri/src/music/feiniu/proxy.rs`），seek 依赖它，不要改成前端直连 NAS。
|
||
- 模块生命周期钩子：`src/modules/<id>/index.ts` 的 `lifecycle.onActivate/onDeactivate/onEnable/onDisable`。
|
||
- 模块内分段导航统一用 `src/components/common/SegmentedNav.vue`；进度/音量统一用 `src/components/common/ScrubBar.vue`（拖动只预览、松手才提交 seek）。
|
||
|
||
## 工程约定
|
||
|
||
- **Tailwind v4**：不识别运行时拼接的类名。动态网格用内联 `gridTemplateColumns`，或把完整字面量类名写在模板里。
|
||
- **tsconfig 开启 `noUnusedLocals` / `noUnusedParameters`**，未使用的 import 会导致构建失败。
|
||
- 主题 token 在 `src/style.css`（`--primary` / `--muted` / `--background` 等）。**禁止硬编码** `bg-white` / `border-white/10`，否则暗色主题会失效。
|
||
- 全局可复用动画类写在 `src/style.css`（如 `.music-eq`、`.tab-animate`）。
|
||
- 构建校验：`npm run build`（= `vue-tsc --noEmit && vite build`）。
|
||
|
||
## 本机环境注意事项
|
||
|
||
- Bash 工具在本机不可用（PATH 未初始化，`ls`/`find` 等均 not found）。用 PowerShell + 显式绝对路径的 node 执行命令。
|
||
- PowerShell 工具**不返回 stdout**：需 `| Out-File` 写文件后再用 Read 读取。
|
||
- `Remove-Item` 被沙箱静默拦截；删除文件用 `node -e "require('fs').unlinkSync('绝对路径')"`。
|
||
- 受管 node：`C:\Users\Administrator\.workbuddy\binaries\node\versions\22.22.2-3\node.exe`。
|
||
- 排障经验：Pinia setup store 里若返回对象引用了未定义变量，TS 会让整个 store 退化成 `any`，进而报出成片无关的 `TS7006 implicitly has an 'any' type`。先查 store 自身的错误。
|