gstgcogrbgmgpgpfglgrh目标不是“背命令”，而是让你真的知道：
| 缩写 | 原命令 | 核心动作 | 危险等级 | 常用指数 |
|---|---|---|---|---|
gst |
git status |
看状态 | 低 | ★★★★★ |
gco |
git checkout |
切分支 / 恢复文件（旧方式） | 中 | ★★★★☆ |
grb |
git rebase |
变基、整理历史 | 中高 | ★★★☆☆ |
gm |
git merge |
合并分支 | 中 | ★★★★☆ |
gl |
git pull |
拉取并合并远程更新 | 中 | ★★★★★ |
gp |
git push |
推送到远程 | 中 | ★★★★★ |
gpf |
git push --force-with-lease |
更安全的强推 | 高 | ★★☆☆☆ |
grh |
git reset |
重置提交/暂存状态 | 中高 | ★★★☆☆ |
这是按日常团队开发里的主观实用度打的，不是官方排名。
在看这些命令前，你先记住下面四个位置：
你正在编辑的文件。
你打算放进下一次提交的改动。
你本地已经提交过的历史记录。
GitHub / GitLab 上的仓库内容。
很多 Git 命令，本质上就是在这四个位置之间“搬东西”或者“对齐状态”。
gst —— 看当前到底是什么状态git status
这是 Git 里最重要的查看命令之一。
它不会改任何东西，只负责告诉你：
★★★★★
低
典型输出会包括：
On branch feat/loginYour branch is ahead of 'origin/feat/login' by 1 commitChanges to be committedChanges not staged for commitUntracked files你改完代码之后，不要急着提交，先 gst 看一眼。
切分支、rebase、merge 前，先看有没有没处理的改动。
你以为自己都提交完了，gst 一看还有没 add 的东西。
gst
gco main
gst
gl
gst
gst
你看到：
modified: src/login.tsmodified: src/api.ts说明你改了两个文件，但还没暂存。
gst
看到：
Your branch is ahead of 'origin/feat/login' by 2 commits这就说明你本地有 2 个提交还没推上去。
gst 不会修任何问题它只负责“告诉你发生了什么”。
gst尤其是：
grbgmglgpfgrh很多人“以为自己知道当前状态”，结果其实不知道。gst 就是防止这种自信翻车的第一道保险。
gco —— 切分支，或者恢复文件（旧时代万能刀）git checkout
checkout 是 Git 早期特别常用的一个命令，功能很多，主要两大类：
也正因为它功能太多，所以后来 Git 才拆出了更清晰的：
git switch：专门切分支git restore：专门恢复文件★★★★☆
中
gco main
意思：切到 main 分支。
gco -- src/login.ts
意思：把这个文件恢复成当前提交里的版本，丢掉你在工作区的改动。
这第二种用法很危险。
gco <branch>切换到某个已存在分支。
例子：
gco develop
gco -b <new-branch>创建并切换到新分支。
例子：
gco -b feat/user-center
不过在 oh-my-zsh 里通常更常写成：
gcb feat/user-center
gco -- <file>恢复单个文件到当前提交版本。
例子：
gco -- package.json
gco <commit> -- <file>从某个历史提交里拿回一个文件版本。
例子：
gco a1b2c3d -- src/config.ts
gco main
gl
gco feat/login-refactor
gco -- src/login.ts
gco main
gl
gco -b feat/payment-page
意思是：
gst
gco -- src/mock.ts
gst
恢复后再看状态，就会发现这个文件不再显示修改。
gco -- 文件名 会直接丢掉你没提交的修改如果你还想留着，就别直接用。
git switch 和 git restore因为语义更清楚，不容易混。
大概率是：
grb —— 变基，把你的提交“重新排队”git rebase
rebase 的核心是：
把当前分支上的提交，重新接到另一个基底后面。
你可以把它理解成：
“我这条分支原来是从旧的主分支上长出来的，现在我想把它挪到最新的主分支后面。”
★★★☆☆
中高
主要两个原因：
你的功能分支开发了一半，主分支已经前进了。你可以把自己的分支 rebase 到最新主分支上。
把历史弄得更直、更干净，方便 review。
grb main
grb origin/main
grbi HEAD~3
意思：整理最近 3 个提交。
grb <branch>把当前分支变基到某个分支上。
grbi对应：
git rebase --interactive
作用：交互式编辑提交历史。
grba对应：
git rebase --abort
作用：rebase 出问题了，放弃本次 rebase。
grbc对应：
git rebase --continue
作用：解决冲突后继续。
grbs对应：
git rebase --skip
作用：跳过当前这个冲突提交。
gco main
gl
gco feat/login
grb main
你做了 5 个零碎提交，准备合并前用交互式 rebase 整理。
很多团队会有这种规范。
你在 feat/login 分支上开发两天了，这两天 main 又进了很多提交。
你做：
gco main
gl
gco feat/login
grb main
结果：
main 开始写的grb main
报冲突了。
你需要：
git add 把冲突解决结果标记好grbc
如果你不想继续了：
grba
这意味着同一段改动会生成新的提交 ID。
否则别人会很痛苦。
它只是另一种整合历史的方法，没有绝对谁更高级。
gm —— 合并分支，把另一条线并进来git merge
merge 是把别的分支改动并入当前分支。
你可以理解成：
“把那条开发线的成果接进我现在站的这条线上。”
★★★★☆
中
gm main
gco main
gm feat/login
gm <branch>合并指定分支到当前分支。
gma对应：
git merge --abort
合并冲突时，放弃这次 merge。
gmc对应：
git merge --continue
解决冲突后继续。
gms对应：
git merge --squash
把对方分支的多个提交压成一个待提交改动。
gmff对应：
git merge --ff-only
只允许快进合并，不允许产生 merge commit。
那就用 merge。
merge 很正常。
main 合进功能分支解决兼容问题gco feat/order
gm main
gco main
gl
gco feat/payment
gm main
这样做完后，你的功能分支就包含主分支最新改动。
gm main
冲突了。
你需要：
git add 标记冲突已解决gmc
不想继续：
gma
它虽然不改历史，但照样会产生冲突。
gm xxx 的意思是：把 xxx 合进当前分支。
很多人会把方向搞反。
先 gst，再看自己站在哪个分支，再 merge。
gl —— 拉远程更新到本地git pull
pull 本质上约等于：
git fetch默认整合方式通常是 merge。
所以你可以把 gl 理解成：
“从远程把最新东西拿下来，并试着和我当前分支合到一起。”
★★★★★
中
gco main
gl
gco feat/login
gl
gl默认 pull。
gpr对应：
git pull --rebase
作用：拉取后用 rebase 方式整合，而不是 merge。
gpra对应：
git pull --rebase --autostash
作用：有未提交改动时，先自动 stash，再 pull rebase，最后恢复改动。
ggpull对应：
git pull origin 当前分支
更明确地拉当前分支的远程对应分支。
gco main
gl
gco feat/profile
gl
gco main
gl
gco feat/order
grb main
gco main
gl
这是很典型的日常动作。
说明远程更新和你本地提交/改动发生了冲突，需要你手动解决。
gl 不是“只下载”它是下载 + 整合。
如果你只想下载不合并，用的是：
gf
gl，更容易冲突先 gst。
gpr也就是 pull 后 rebase。
gp —— 把本地提交推上远程git push
把你本地分支的提交上传到远程仓库。
这是“让别人看见你改动”的关键动作之一。
★★★★★
中
gp
前提是当前分支已经有 upstream（上游分支）配置。
通常你会用：
gpsup
意思是第一次推送并建立跟踪关系。
gp普通推送。
gpd对应：
git push --dry-run
先演练，不真正推。
gpv对应：
git push --verbose
更详细输出。
ggp对应：
git push origin 当前分支
显式推当前分支到 origin。
gp
很多团队 push 后自动触发构建、测试、部署检查。
推送是开 PR 前的前置动作。
gst
gp
gco -b feat/refactor-header
# 开发、提交以后
gpsup
gp 只能推“提交”，不能推你还没 commit 的工作区改动很多小白以为 push 会把所有改动一起传上去，不会。
常见原因：
gst确认没有一堆你以为已经提交、其实还躺在工作区里的改动。
gpf —— 更安全的强制推送在较新的 Git 里通常等价于：
git push --force-with-lease --force-if-includes
在较旧的 Git 里通常等价于：
git push --force-with-lease
当你做了这些操作后，经常需要强推：
rebasecommit --amend因为这些操作改写了本地提交历史，普通 gp 往往会被拒绝。
这时你就需要“强制推送”。
★★☆☆☆
高
gpf 比 gpf! 好一些gpf!相当于：
git push --force
它比较蛮横。
gpf相当于：
git push --force-with-lease
它会先确认远程分支没有被别人偷偷推进新内容。
所以它比纯 --force 更安全。
--force-with-lease如果远程分支状态不是你以为的那个状态，就拒绝强推。
--force-if-includes在较新 Git 中进一步约束强推条件，降低误覆盖风险。
grb main
gpf
git commit --amend
gpf
grbi HEAD~5
gpf
gco feat/login
grb main
gpf
这是相对常见且合理的用法。
如果某个分支是多人一起推的，你 gpf 可能直接把别人的历史覆盖掉。
gpf 不是日常 push 替代品只有在“历史被你改写过”的时候才考虑它。
尤其不要把强推当日常习惯。
gpf 的地方gpf 的地方grh —— reset，重新摆放 HEAD / 暂存区 / 工作区git reset
reset 是 Git 里最容易让新手迷糊、也最值得学会的命令之一。
它主要是在做三件事里的某几件：
★★★☆☆
中高
grh本身不一定危险，危险的是它后面跟的参数。
grh <commit>git reset <commit>
作用：把当前分支指针移到某个提交，通常也会重置暂存区，但保留工作区改动。
grhs <commit>git reset --soft <commit>
作用：回退提交，但保留暂存区和工作区。
适合：
grh / gru <file>常用于取消暂存。
例子：
git add src/login.ts
gru src/login.ts
意思：把这个文件从暂存区拿下来。
grhh <commit>git reset --hard <commit>
作用：回退提交、重置暂存区、连工作区也一起回退。
这个非常危险。
gru src/login.ts
grhs HEAD~1
grhh HEAD
或
grhh origin/main
grhs HEAD~1
结果：
git add src/a.ts src/b.ts
gru src/b.ts
结果：
src/a.ts 还在暂存区src/b.ts 被拿回工作区grhh HEAD~1
结果：
也就是类似：
gru 文件名
--soft 比 --hard 安全很多--soft：保留改动--hard：可能直接清空改动reset：改你的本地历史指针revert：新建一个“反向提交”去抵消旧提交因为最后往往会演变成你要 gpf，然后影响别人。
gst
# 改代码
gst
# add / commit
gp
你虽然提交可能用图形化，但 gst + gp 还是很常见。
gco main
gl
gco feat/login
gco main
gl
gco feat/login
gm main
gco main
gl
gco feat/login
grb main
gco feat/login
grb main
gpf
grhs HEAD~1
# 重新整理后再提交
既然你主要是可视化提交，那命令行更多是拿来做这几件事：
gstgcoglgmgrbgpgpfgrh换句话说，你现在这一套其实已经很像“命令行做仓库控制，可视化做提交细节”的工作方式了，这很正常，而且挺实用。
如果按“你这种使用方式”的实战价值排序：
gstglgpgcogmgrbgrhgpfgst：我现在啥状态？gco：我要切去哪？或者把哪个文件撤回来？gl：把远程最新内容拉下来gm：把另一条分支合进来grb：把我的提交重新排到新基底后面gp：把本地提交推上去gpf：我改历史了，只能更安全地强推grh：我要重新摆放提交、暂存区或工作区状态gpfgrhhgco -- 文件grb 后准备推送时gst你只要把这三件事养成习惯，Git 翻车概率会明显下降。
]]>本文档用于约束项目的前端目录结构、分层边界、依赖方向、模块职责与实现方式。 本规范的目标不是描述"可以怎么写"，而是明确：
本规范适用于基于 Vue 的前端项目，默认技术前提包括：
本规范为项目的长期维护基线。新功能、新页面、迁移重构与目录调整，均应遵循本文档。
本规范基于以下目标制定：
所有路由页面统一收敛在 src/pages/*Page.vue，保持目录扁平、入口清晰、可快速定位。
与业务域强相关的模型、查询、写入、UI、编排逻辑统一收敛在 src/features/<domain> 内，避免业务逻辑散落在页面、全局 store 或共享目录中。
src/main.ts 与 src/App.vue 仅承担应用启动与根壳装配职责，不承载业务实现细节。
Layout 作为页面外壳独立存在，通过路由元信息选择，不反向依赖具体业务域。
Feature 内部 UI 按页面级、区块级、组件级进行区分，减少目录语义混乱。
读取链路、写入链路、缓存键与刷新机制统一定义，避免刷新策略分散和 UI 数据不一致。
项目采用以下分层模型：
目录：
src/main.tssrc/App.vuesrc/app/**职责：
目录：
src/router/**src/layouts/**职责：
目录：
src/pages/*Page.vue职责：
目录：
src/features/<domain>/**职责：
目录：
src/services/api/**职责：
目录：
src/components/base/**src/components/shared/**src/composables/base/**src/utils/**src/config/**src/directives/**src/types/**src/styles/**职责：
App / Router / Layout
↓
Pages
↓
Features
↓
Services
Shared 可被上层复用，但 Shared 不得反向依赖业务域
允许的导入关系：
pages -> features/<domain>pages -> features/<domain>/modelfeatures -> services/api所有层 -> sharedApp -> router / app / layouts禁止以下依赖：
pages -> services/apipages -> features/<domain>/内部实现路径features/A -> features/B/内部实现路径shared -> featureslayouts -> featuresservices -> featuresFeature 的公开接口统一通过以下入口导出：
@/features/<domain>@/features/<domain>/model外部模块不得绕过公开入口访问以下内部目录：
queries/*mutations/*composables/*ui/pages/*ui/partials/*ui/components/*该规则为本项目的基础边界规则。
为保证本文档在评审、重构与协作中的可执行性，本文档中的规则分为以下三个等级：
必须遵守。
含义：
典型场景：
pages 不得直接依赖 services/api强烈建议遵守。
含义：
典型场景：
features/*/ui/pages/*可选实践。
含义：
典型场景：
components/shared推荐项目目录结构如下：
src
├─ main.ts
├─ App.vue
│
├─ app
│ ├─ bootstrap
│ │ ├─ installApp.ts
│ │ ├─ installPlugins.ts
│ │ ├─ installDirectives.ts
│ │ └─ installErrorHandling.ts
│ ├─ providers
│ │ ├─ AppProviders.vue
│ │ ├─ ToastProvider.vue
│ │ └─ DialogProvider.vue
│ └─ shell
│ ├─ AppShell.vue
│ └─ AppRouterView.vue
│
├─ router
│ ├─ index.ts
│ ├─ routes.ts
│ └─ guards
│ ├─ auth.guard.ts
│ ├─ permission.guard.ts
│ └─ analytics.guard.ts
│
├─ layouts
│ ├─ index.ts
│ ├─ LayoutHost.vue
│ ├─ DefaultLayout.vue
│ ├─ EmptyLayout.vue
│ ├─ DashboardLayout.vue
│ └─ parts
│ ├─ AppHeader.vue
│ ├─ AppSidebar.vue
│ └─ AppBreadcrumb.vue
│
├─ pages
│ ├─ WorkspaceTasksPage.vue
│ ├─ WorkspaceOverviewPage.vue
│ ├─ ReviewListPage.vue
│ ├─ ReviewDetailPage.vue
│ ├─ InspectorProfilePage.vue
│ └─ LoginPage.vue
│
├─ features
│ ├─ workspace
│ │ ├─ index.ts
│ │ ├─ model
│ │ │ ├─ index.ts
│ │ │ ├─ types.ts
│ │ │ ├─ keys.ts
│ │ │ └─ constants.ts
│ │ ├─ queries
│ │ │ ├─ mappers.ts
│ │ │ ├─ useWorkspaceTasksQuery.ts
│ │ │ └─ useWorkspaceSummaryQuery.ts
│ │ ├─ mutations
│ │ │ ├─ useCreateTaskMutation.ts
│ │ │ └─ useUpdateTaskMutation.ts
│ │ ├─ composables
│ │ │ ├─ useWorkspaceTasksPage.ts
│ │ │ └─ useWorkspaceFilters.ts
│ │ └─ ui
│ │ ├─ pages
│ │ │ ├─ WorkspaceTasksPageView.vue
│ │ │ └─ WorkspaceOverviewPageView.vue
│ │ ├─ partials
│ │ │ ├─ WorkspaceTaskToolbar.vue
│ │ │ ├─ WorkspaceTaskFilters.vue
│ │ │ └─ WorkspaceSummaryPanel.vue
│ │ └─ components
│ │ ├─ WorkspaceTaskTable.vue
│ │ ├─ WorkspaceTaskCard.vue
│ │ └─ WorkspaceStatusTag.vue
│ ├─ review
│ │ └─ ...
│ └─ inspector
│ └─ ...
│
├─ services
│ └─ api
│ ├─ http.ts
│ ├─ auth.ts
│ ├─ workspace.tasks.ts
│ ├─ workspace.summary.ts
│ ├─ review.items.ts
│ └─ ...
│
├─ components
│ ├─ base
│ │ ├─ BaseButton.vue
│ │ ├─ BaseInput.vue
│ │ ├─ BaseModal.vue
│ │ └─ BaseTable.vue
│ └─ shared
│ ├─ ConfirmDialog.vue
│ ├─ EmptyState.vue
│ └─ LoadingBlock.vue
│
├─ composables
│ └─ base
│ ├─ useBoolean.ts
│ ├─ useDebounce.ts
│ ├─ useEventListener.ts
│ └─ usePagination.ts
│
├─ store
│ ├─ index.ts
│ ├─ app.store.ts
│ └─ auth.store.ts
│
├─ plugins
│ ├─ query.ts
│ ├─ i18n.ts
│ ├─ analytics.ts
│ └─ sentry.ts
│
├─ directives
│ ├─ v-focus.ts
│ └─ v-click-outside.ts
│
├─ utils
│ ├─ date.ts
│ ├─ format.ts
│ ├─ object.ts
│ └─ route.ts
│
├─ config
│ ├─ env.ts
│ ├─ constants.ts
│ └─ featureFlags.ts
│
├─ styles
│ ├─ index.css
│ ├─ reset.css
│ └─ tokens.css
│
├─ assets
│ ├─ icons
│ └─ images
│
└─ types
├─ env.d.ts
└─ shims-vue.d.ts
src/main.tsimport { createApp } from 'vue'
import App from './App.vue'
import { installApp } from './app/bootstrap/installApp'
const app = createApp(App)
installApp(app)
app.mount('#app')
src/App.vue<template>
<AppProviders>
<AppShell />
</AppProviders>
</template>
<script setup lang="ts">
import AppProviders from '@/app/providers/AppProviders.vue'
import AppShell from '@/app/shell/AppShell.vue'
</script>
src/app/bootstrap/**main.ts 的负载转移层import type { App } from 'vue'
import { router } from '@/router'
import { installPlugins } from './installPlugins'
import { installDirectives } from './installDirectives'
export function installApp(app: App) {
app.use(router)
installPlugins(app)
installDirectives(app)
}
src/app/providers/**src/app/shell/**meta 提供页面装配信息src/pages/*Page.vuefeatures/*/ui/pages/*{
path: '/workspace/tasks',
component: () => import('@/pages/WorkspaceTasksPage.vue'),
meta: { layout: 'dashboard', requiresAuth: true },
}
权限控制统一放在 Router Guard 层处理。
应在 router/guards/* 中处理，而不应下沉到 Layout 或具体页面中。
Layout 是页面外壳，用于控制：
统一通过 route.meta.layout 选择布局。
LayoutHost.vue：读取 meta 并选择具体 LayoutDefaultLayout.vue：通用布局EmptyLayout.vue：登录页、空白页DashboardLayout.vue：带导航和侧栏的后台布局layouts/parts/*：布局内部组成块<template>
<component :is="layoutComponent">
<router-view />
</component>
</template>
<script setup lang="ts">
import { computed } from 'vue'
import { useRoute } from 'vue-router'
import DefaultLayout from './DefaultLayout.vue'
import EmptyLayout from './EmptyLayout.vue'
import DashboardLayout from './DashboardLayout.vue'
const route = useRoute()
const layoutMap = {
default: DefaultLayout,
empty: EmptyLayout,
dashboard: DashboardLayout,
}
const layoutComponent = computed(() => {
const key = (route.meta.layout as keyof typeof layoutMap) || 'default'
return layoutMap[key] || DefaultLayout
})
</script>
src/pages 必须保持扁平化。
允许：
pages/
WorkspaceTasksPage.vue
ReviewDetailPage.vue
LoginPage.vue
不允许：
pages/
workspace/
tasks/
index.vue
每个 *Page.vue 仅承担以下职责：
services/api<template>
<WorkspaceTasksPageView />
</template>
<script setup lang="ts">
import { WorkspaceTasksPageView } from '@/features/workspace'
</script>
<template>
<ReviewDetailPageView :review-id="reviewId" />
</template>
<script setup lang="ts">
import { useRoute } from 'vue-router'
import { ReviewDetailPageView } from '@/features/review'
const route = useRoute()
const reviewId = String(route.params.reviewId)
</script>
为保证 src/pages/*Page.vue 长期保持轻量化，Pages 与 Feature Page View 的交接边界必须明确。
route.params 与 route.queryservices/apifeatures/*/ui/pages/* 作为页面主体视图，负责：
可将两者关系理解为：
pages/*Page.vue = 路由适配层features/*/ui/pages/* = 页面主体层<template>
<ReviewDetailPageView :review-id="reviewId" />
</template>
<script setup lang="ts">
import { useRoute } from 'vue-router'
import { ReviewDetailPageView } from '@/features/review'
const route = useRoute()
const reviewId = String(route.params.reviewId)
</script>
在该模式下，路由页仅完成参数适配，具体页面主体由 Feature 负责。
Feature 是业务域的完整实现单元。Feature 可以是：
当某个业务域规模较大时，允许在该域下继续按语义拆分为多个子域。此时：
shared/一级域与子域的关系应理解为：
适用于规模中等、边界清晰、无需再拆分子域的 Feature。
features/<domain>/
index.ts
model/
queries/
mutations/
composables/
ui/
适用于一级域下包含多个稳定语义模块的场景。
features/<domain>/
<subdomain-a>/
<subdomain-b>/
<subdomain-c>/
shared/
index.ts
model/
其中：
shared/ 仅承载兄弟子域之间复用的内容index.ts 与 model/ 仍作为一级域的对外公开边界子域不强制必须同时具备 model / queries / mutations / composables / ui 五类子目录。
应根据复杂度采用渐进式组织方式。
当子域规模较小、实现简单时，优先采用扁平文件结构：
<subdomain>/
model.ts
queries.ts
mutations.ts
如有少量局部 UI 或编排需求，可按需增加：
<subdomain>/
model.ts
queries.ts
mutations.ts
composables/
ui/
只有当子域明显变复杂时，才将其升级为完整分层目录，例如：
升级后可采用：
<subdomain>/
model/
queries/
mutations/
composables/
ui/
默认不设"子域自己的 shared/"。
原因如下：
shared/ 的收敛作用仅当某个子域本身已经足够复杂，且其内部再次形成明确子模块边界时，才允许在该子域内继续分模块并引入更细粒度共享目录。
shared/ 的使用边界一级域下的 shared/ 仅用于承载"跨子域复用"的内容。
允许进入一级域 shared/ 的内容包括：
禁止将以下内容放入一级域 shared/：
shared/。index.ts 规范外部模块只应从该入口使用 Feature 能力。
model/ 规范当 Feature 为大型一级域时：
model/ 负责对外稳定模型边界model/export type Task = {
id: string
title: string
status: 'todo' | 'doing' | 'done'
createdAt: Date
}
queries/ 规范services/apimutations/ 规范composables/ 规范虽然 Feature 对外统一通过 index.ts 与 model/index.ts 暴露能力，但公开入口的导出范围仍需受控。
features/<domain>/index.ts 推荐导出内容（SHOULD）features/<domain>/index.ts 禁止导出内容（MUST）queries/*mutations/*mappers/*features/<domain>/model/index.ts 推荐导出内容（SHOULD）Feature 内部 UI 统一分为三层：
ui/
pages/
partials/
components/
ui/pages/页面级业务视图。
src/pages/*Page.vue 组合使用WorkspaceTasksPageView.vueReviewDetailPageView.vueui/partials/页面中的区块级拼装单元。
WorkspaceTaskToolbar.vueWorkspaceSummaryPanel.vueReviewDetailSidebar.vueui/components/更小粒度的 Feature 内业务组件。
WorkspaceTaskTable.vueWorkspaceStatusTag.vueReviewBadge.vueui/pages/，如果该组件：src/pages/*Page.vue 使用ui/partials/，如果该组件：ui/components/，如果该组件：ui/ 目录，不强制继续拆分多层结构。pages / partials / components 继续分层。src/services/api/** 仅负责：
不得承担：
services/apifeatures/<domain>/modelfeatures/<domain>/queries/mappers.ts统一骨架：
[domain, resource, scope, params]
示例：
['workspace', 'tasks', 'list', { page: 1, pageSize: 20 }]
['workspace', 'tasks', 'detail', { taskId: '123' }]
写入成功后必须执行 invalidation。
推荐粒度：
禁止混用以下方式作为主要数据刷新手段：
Pinia 用于全局状态管理，但应保持边界明确。
上述数据优先放入：
必要时可引入 Colada，用于增强请求数据管理能力。
即使引入 Colada，其使用边界仍应保持不变：
features/<domain>/queriesfeatures/<domain>/mutations换言之，Colada 改变的是实现工具，不改变分层归属。
为避免状态落点混乱，项目中的状态按来源与生命周期分为三类，并分别归属不同层管理。
适用于跨页面、跨业务域共享，且具有明显应用级意义的状态。
典型示例：
适用于来源于服务端、需要缓存、刷新、失效管理的数据。
典型示例：
此类数据必须通过 Feature 内 queries/ 管理，而不应直接进入页面或全局 store。
适用于生命周期较短、仅影响当前页面或局部交互的状态。
典型示例：
为统一页面与区块的异步交互表现，Feature 的读取与写入逻辑应显式处理以下状态：
当页面主体首次加载时，应提供明确的加载态，而不是空白页面或结构闪烁。
局部刷新或局部区块数据加载时，应优先使用区块级 loading，而非阻断整个页面。
当请求成功但无数据时，应提供明确 empty state，而非仅显示空白区域。
当请求失败时，应至少提供：
写入过程中应显式暴露 submitting / pending 状态，用于控制：
仅当业务一致性与回滚逻辑清晰时，允许采用乐观更新。若采用，必须明确失败回滚策略。
components/base/*纯基础组件，无业务语义。
BaseButton.vueBaseInput.vueBaseModal.vueBaseTable.vue基础组件命名不得出现业务词汇，如：
components/shared/*跨多个 Feature 复用的轻业务或中性 UI 壳组件。
ConfirmDialog.vueEmptyState.vueLoadingBlock.vue若组件已带明显业务语义，应回归对应 Feature，而不是继续放在 shared。
composables/base/*通用 hooks，不带业务语义。
useBoolean.tsuseDebounce.tsusePagination.tsutils/*纯工具函数。
若工具函数名称或逻辑已明显依赖业务概念，应放回 Feature。
config/*环境配置、系统常量、功能开关。
业务规则不应伪装成全局配置。
若某项常量属于领域规则，应放入 features/<domain>/model/constants.ts。
本项目建议通过 ESLint 建立基础防线，不追求过细，但应覆盖关键越界场景。
禁止：
src/pages/** -> @/services/api/*禁止：
@/features/*/queries/*@/features/*/mutations/*@/features/*/composables/*@/features/*/ui/*禁止：
components/base -> featurescomponents/shared -> featurescomposables/base -> featuresutils -> features这些规则用于保障：
'no-restricted-imports': [
'error',
{
patterns: [
{
group: ['@/services/api/*'],
message: '页面层禁止直接访问 services/api，请通过 feature 公开能力使用。',
},
{
group: [
'@/features/*/queries/*',
'@/features/*/mutations/*',
'@/features/*/composables/*',
'@/features/*/ui/*',
],
message: '禁止直接依赖 feature 内部实现，请通过公开入口导入。',
},
],
},
]
所有路由页统一命名为：
XxxPage.vue示例：
WorkspaceTasksPage.vueReviewDetailPage.vueLoginPage.vue页面级业务视图统一命名为：
XxxPageView.vue示例：
WorkspaceTasksPageView.vueReviewDetailPageView.vue区块级组件建议使用能够体现区块语义的后缀：
ToolbarPanelSectionSidebarFiltersSummary示例：
WorkspaceTaskToolbar.vueReviewDetailSidebar.vueWorkspaceSummaryPanel.vue组件级单元建议使用能够体现组件角色的后缀：
TableCardItemRowTagBadgeForm示例：
WorkspaceTaskTable.vueWorkspaceTaskCard.vueReviewStatusBadge.vueuseXxxQuery.tsuseXxxMutation.tsuse<Domain><UseCase>Page.tsuse<Domain><UseCase>.ts示例：
useWorkspaceTasksQuery.tsuseCreateTaskMutation.tsuseWorkspaceTasksPage.ts以 WorkspaceTasksPage 为例：
src/pages/ 创建 WorkspaceTasksPage.vuefeatures/workspace/ui/pages/ 创建 WorkspaceTasksPageView.vuefeatures/workspace/composables/ 创建 useWorkspaceTasksPage.tsui/partials/ 拆分工具栏、筛选区、摘要区等页面区块ui/components/ 放表格、卡片、标签等组件级单元features/workspace/index.ts 统一导出 WorkspaceTasksPageViewrouter/routes.ts 注册该 pages/*Page.vueui/pages/ui/partials/ui/components/model / queries / mutations / composables / uiqueries / mutationscomposablesui/pagespages/*Page.vue 壳以下情况视为明显越界或反模式：
表现：
表现：
queries/*ui/pages/*composables/*表现：
表现：
components/shared 下出现大量业务词组件utils 中出现明显业务规则工具base 目录依赖 Feature表现：
表现：
main.ts 中堆积大量安装逻辑App.vue 中开始出现业务页面逻辑pages/ 是否保持扁平，仅保留 *Page.vuepages/*Page.vuefeatures/<domain> 或 features/<domain>/model 暴露公开接口ui/pages/ui/partials/ui/components/main.ts 是否仅负责启动与安装App.vue 是否仅负责根壳装配base 是否无业务语义shared 是否未演变为业务组件仓库utils 与 config 是否未承载领域规则测试规范单独列出，用于明确不同层级的测试落点与职责范围。
测试的目标不是覆盖所有文件，而是覆盖最有价值的行为边界：
utils/*（SHOULD）优先编写单元测试。
适合验证：
composables/base/*（SHOULD）优先编写单元测试。
适合验证：
features/*/queries/*（SHOULD）建议编写逻辑测试或集成测试。
适合验证：
features/*/mutations/*（SHOULD）建议编写逻辑测试或集成测试。
适合验证：
features/*/composables/*（MUST，关键页面场景）页面级编排逻辑应优先测试。
适合验证：
features/*/ui/components/* 与 ui/partials/*（SHOULD）建议进行组件交互测试。
适合验证：
features/*/ui/pages/*（SHOULD）建议进行页面主体视图测试。
适合验证：
pages/*Page.vue（MAY）页面层通常较薄，测试优先级低于 Feature page view。
适合验证：
router/* 与 layouts/*（SHOULD）建议覆盖关键路径测试。
适合验证：
pages/*Page.vue 的重复测试，转而测试 Feature page view 与 composables。以下内容不作为当前版本的强制主规范，但建议在后续版本逐步补充，用于完善工程一致性。
建议后续补充：
建议后续补充：
建议后续补充：
本规范的核心结构可概括为：
所有新代码均应在此框架下组织。若需例外，应明确说明原因、范围与后续收敛计划。
]]>#include <stdio.h>
int main() {
printf("Hello, World!\n");
return 0;
}
print("Hello, World!")
一级引言段落1 一级引言段落2
嵌套二级引言
回到一级引言，支持嵌套列表：
- 引言内有序列表
- 列表项2
引言内标题
引言内代码
::github{repo="sty20030818/StoneHub"}
:::note 这是一个note提示框 :::
:::tip 这是一个tip提示框 :::
:::important 这是一个important提示框 :::
:::warning 这是一个warning提示框 :::
:::caution 这是一个caution提示框 :::
这是普通文本,剧透内容 :spoiler[剧透内容]
]]>