@teamix-evo/skills 0.12.1 → 0.13.0

package/README.md

@@ -39,7 +39,7 @@ pnpm --filter @teamix-evo/skills scaffold:skill
 
 ## 消费态命令（CLI）
 
-由 `teamix-evo skills` 子命令族管理（source-mirror 模型见 [ADR 0013](../../docs/adr/0013-skills-source-mirror.md)）：
+由 `teamix-evo skills` 子命令族管理（npm 包直接渲染到 IDE 镜像，见 [ADR 0013](../../docs/adr/0013-skills-source-mirror.md)）：
 
 ```bash
 teamix-evo skills init               # 自举：按 variant + scope 全装符合条件的 skill（ADR 0034）

package/manifest.json

@@ -2,7 +2,7 @@
   "$schema": "https://teamix-evo.dev/schema/skills-package/v1.json",
   "schemaVersion": 1,
   "package": "skills",
-  "version": "0.5.0",
+  "version": "0.13.0",
   "engines": {
     "teamix-evo": ">=0.1.0"
   },
@@ -10,8 +10,8 @@
     {
       "id": "teamix-evo-manage",
       "name": "teamix-evo-manage",
-      "description": "Single entry point for the teamix-evo lifecycle: scaffold a new project skeleton, install the AI coding system into an existing repo via `teamix-evo init`, inspect / remove any teamix-evo package, manage component-source upgrades, and drive old-project migration/rebuild.\nTRIGGER when: (CLI) user runs or asks about `teamix-evo init` / `teamix-evo tokens ...` / `teamix-evo skills ...` / `teamix-evo ui ...` / `teamix-evo biz-ui ...` / `teamix-evo blocks ...` / `teamix-evo lint ...` / `teamix-evo logs ...` / `teamix-evo restore ...` / `teamix-evo switch ...`, or `npm create teamix-evo` / `pnpm create teamix-evo`; (模糊初始化) \"初始化一个项目\"、\"初始化一个工程\"、\"初始化一个 teamix-evo 工程\"、\"初始化一个 Teamix Evo 项目\"、\"create a teamix-evo project\"、\"set up teamix-evo from scratch\"、\"new teamix-evo app\"; (具名变体初始化) \"初始化一个 opentrek 工程 / op 工程 / OpenTrek 项目 / 探索者项目\"、\"初始化一个云管 / 云管控制台 / 云管项目 / uni-manager 工程 / 云管工程\"、\"new opentrek/uni-manager project\"; (AI coding 接入) \"给现有仓库装 teamix-evo\"、\"现有项目装一下 skills + ui\"、\"接入 AI coding 体系\"、\"装 teamix-evo 进这个项目\"、\"add teamix-evo to existing repo\"、\"install AI coding system\"、\"接入 opentrek 研发体系\"、\"接入 op 研发体系\"、\"接入 OpenTrek 研发体系\"、\"接入 opentrek 研发系统\"、\"接入 op 研发系统\"、\"接入云管研发体系\"、\"接入云管研发系统\"、\"接入 uni-manager 研发体系\"、\"接入 uni-manager 研发系统\"、\"接入统一管理研发体系\"; (组件源码升级 — ADR 0040) \"升级 ui\"、\"升级业务组件\"、\"升级 button\"、\"生成 ui staging\"、\"生成 biz-ui staging\"、\"upgrade ui\"、\"upgrade biz-ui\"、\"upgrade ui component\"、\"stage ui upgrade\"、\"teamix-evo ui upgrade\"、\"teamix-evo biz-ui upgrade\"; (卸载 / 清单) \"卸载 teamix-evo\"、\"看看装了哪些 teamix-evo 资源\"、\"remove the design system\"、\"list installed\"; (旧工程迁移) \"迁移旧项目\"、\"重建老工程\"、\"把旧项目搬过来\"、\"旧项目分析\"、\"旧系统翻新\"、\"legacy migration\"、\"migrate old project\"、\"rebuild from existing\"、\"refactor from old codebase\"、\"从旧项目迁移过来\"、\"用旧项目做参考重建\"、\"分析旧项目并迁移\"、\"代码迁移\"、\"执行代码迁移\"、\"执行迁移\"、\"开始迁移\"、\"项目迁移\"、\"code migration\"、\"run migration\"、\"start migration\"、\"迁移代码\"、\"迁移项目\"; (状态文件) user touches `.teamix-evo/config.json`、`.teamix-evo/manifest.json`.\nSKIP: any content task — generating components, pages, services, or reviewing screens; changes to `src/` files outside the component upgrade flow, design tokens, or business logic. Those go to teamix-evo-code-opentrek or teamix-evo-design-opentrek. SKIP if the user is mid-flow inside an already-initialized project asking to \"新增页面 / 加按钮 / 调接口\" — that's coding work, not lifecycle. SKIP pure styling / token tweaks — those go to ESLint + `tokens.overrides.css`.\nCoordinates with: teamix-evo-design-opentrek (visual side after a screen is generated)、teamix-evo-code-opentrek (file placement / reuse rules) — manage is the entry point and precedes content skills, never co-triggers.",
-      "version": "0.4.0",
+      "description": "Single entry point for the teamix-evo lifecycle: init, update, migrate, switch, restore, uninstall.\nTRIGGER when: user runs or asks about `teamix-evo init` / `teamix-evo tokens ...` / `teamix-evo skills ...` / `teamix-evo ui ...` / `teamix-evo biz-ui ...` / `teamix-evo blocks ...` / `teamix-evo lint ...` / `teamix-evo migrate` / `teamix-evo restore ...` / `teamix-evo switch ...`; mentions 初始化/接入/更新/升级/迁移/卸载/staging/codemod/token 治理/baseline; touches `.teamix-evo/config.json` or `manifest.json`.\nSKIP: content tasks — components, pages, services (→ code-*); visual design review (→ design-*); pure styling / token tweaks (→ ESLint).\nCoordinates with: teamix-evo-design-* / teamix-evo-code-* — manage precedes content skills, never co-triggers.",
+      "version": "0.13.0",
       "source": "src/teamix-evo-manage",
       "ides": [
         "qoder",
@@ -27,8 +27,8 @@
     {
       "id": "teamix-evo-design-opentrek",
       "name": "teamix-evo-design-opentrek",
-      "description": "Apply OpenTrek design system rules (philosophy, patterns, page-types, brand tone/voice, visual foundations) when AI generates or reviews a full UI screen / page in an OpenTrek-variant project.\nTRIGGER when: user asks to \"新建 / 优化 / 重构 一个页面\"、\"做一个列表页 / 详情页 / 表单页 / 仪表盘\"、\"create / review / refactor a page、screen、dashboard、template\"; intent involves layout structure, page-level information density, or multi-component composition; file write under `src/pages/**` or `src/templates/**`.\nSKIP: single-component edits like \"加个按钮\"、\"改 input 的 label\"; pure tokens/theme overrides; pure code refactor with no visual change; teamix-evo lifecycle commands (defer to teamix-evo-manage).\nCoordinates with: teamix-evo-code-opentrek (run alongside when the screen also creates new files).",
-      "version": "0.2.0",
+      "description": "Apply OpenTrek design system rules when AI generates or reviews a full UI screen / page.\nTRIGGER when: user asks to 新建/优化/重构 页面, create/review/refactor a page/screen/dashboard; intent involves layout structure or multi-component composition; file write under `src/pages/**`.\nSKIP: single-component edits (加按钮, 改 label); pure tokens/theme overrides; pure code refactor with no visual change; lifecycle commands (→ teamix-evo-manage).\nCoordinates with: teamix-evo-code-opentrek (run alongside when the screen also creates new files).",
+      "version": "0.13.0",
       "source": "src/teamix-evo-design-opentrek",
       "variant": "opentrek",
       "ides": [
@@ -44,8 +44,8 @@
     {
       "id": "teamix-evo-code-opentrek",
       "name": "teamix-evo-code-opentrek",
-      "description": "Enforce teamix-evo coding conventions in OpenTrek-variant consumer apps — reuse-first against `@teamix-evo/ui` registry, API code under `src/services/`, `src/` layering and import boundaries.\nTRIGGER when: user asks to \"新增 / 重构 / 写一个\" 组件 / 页面 / 接口 / 钩子 / 工具 / hook; phrases like \"create a CRUD page\"、\"add an API call\"、\"extract a hook\"、\"refactor this fetch\"、\"调一下接口\"、\"加个组件\"、\"加个按钮\"; file write under `src/pages/**`、`src/components/**`、`src/services/**`、`src/hooks/**`; AI is about to write any new `.tsx` / `.ts` file in a teamix-evo-installed project.\nSKIP: pure visual / layout design questions about an already-existing screen with no code change (defer to teamix-evo-design-opentrek); teamix-evo lifecycle (init / update / uninstall) — those go to teamix-evo-manage; changes only to design tokens / styles / theme — those go to ESLint and `tokens.overrides.css`.\nCoordinates with: teamix-evo-design-opentrek (run alongside when the change also creates a UI screen — design handles the visual side, this skill handles file placement and reuse).",
-      "version": "0.2.0",
+      "description": "Enforce teamix-evo coding conventions in OpenTrek apps — reuse-first, `src/` layering, import boundaries.\nTRIGGER when: user asks to 新增/重构/写 组件/页面/接口/hook; phrases like \"create a CRUD page\" / \"add an API call\" / \"调接口\" / \"加组件\"; file write under `src/pages/**`, `src/components/**`, `src/features/**`.\nSKIP: pure visual/layout design with no code change (→ design-opentrek); lifecycle commands (→ manage); token/style-only changes (→ ESLint).\nCoordinates with: teamix-evo-design-opentrek (design handles visual side, this skill handles file placement and reuse).",
+      "version": "0.13.0",
       "source": "src/teamix-evo-code-opentrek",
       "variant": "opentrek",
       "ides": [
@@ -61,8 +61,8 @@
     {
       "id": "teamix-evo-design-uni-manager",
       "name": "teamix-evo-design-uni-manager",
-      "description": "Apply Uni-Manager design system rules (philosophy, patterns, page-types, brand tone/voice, visual foundations) when AI generates or reviews a full UI screen / page in a Uni-Manager-variant project (专有云 / 混合云 / 云管平台 / hybrid cloud console).\nTRIGGER when: user asks to \"新建 / 优化 / 重构 一个页面\"、\"做一个列表页 / 详情页 / 表单页 / 仪表盘 / 控制台首页\"、\"create / review / refactor a page、screen、dashboard、console、admin template\"; intent involves layout structure, page-level information density, or multi-component composition for hybrid-cloud / multi-tenant / multi-region scenarios; file write under `src/pages/**` or `src/templates/**`.\nSKIP: single-component edits like \"加个按钮\"、\"改 input 的 label\"; pure tokens/theme overrides; pure code refactor with no visual change; teamix-evo lifecycle commands (defer to teamix-evo-manage).\nCoordinates with: teamix-evo-code-uni-manager (run alongside when the screen also creates new files).",
-      "version": "0.2.0",
+      "description": "Apply Uni-Manager design system rules when AI generates or reviews a UI screen / page (专有云/混合云/云管).\nTRIGGER when: user asks to 新建/优化/重构 页面/控制台/仪表盘, create/review/refactor a page/dashboard/console; intent involves layout or multi-component composition; file write under `src/pages/**`.\nSKIP: single-component edits; pure tokens/theme overrides; pure code refactor with no visual change; lifecycle commands (→ teamix-evo-manage).\nCoordinates with: teamix-evo-code-uni-manager (run alongside when the screen also creates new files).",
+      "version": "0.13.0",
       "source": "src/teamix-evo-design-uni-manager",
       "variant": "uni-manager",
       "ides": [
@@ -78,8 +78,8 @@
     {
       "id": "teamix-evo-code-uni-manager",
       "name": "teamix-evo-code-uni-manager",
-      "description": "Enforce teamix-evo coding conventions in uni-manager (hybrid-cloud / multi-tenant console) consumer apps — reuse-first against `@teamix-evo/ui` registry + `biz-ui/uni-manager` (um-topbar / CloudBadge), API code under `src/services/` with tenant / region context propagation, `src/` layering and import boundaries.\nTRIGGER when: user asks to \"新增 / 重构 / 写一个\" 组件 / 页面 / 接口 / 钩子 / 工具 / hook in a hybrid-cloud / 专有云 / 多租户 / 多区域 console; phrases like \"create a CRUD page\"、\"add an API call\"、\"extract a hook\"、\"refactor this fetch\"、\"调一下接口\"、\"加个组件\"、\"加个按钮\"; file write under `src/pages/**`、`src/components/**`、`src/services/**`、`src/hooks/**`; AI is about to write any new `.tsx` / `.ts` file in a teamix-evo-installed uni-manager-variant project.\nSKIP: pure visual / layout design questions about an already-existing screen with no code change (defer to teamix-evo-design-uni-manager); teamix-evo lifecycle (init / update / uninstall) — those go to teamix-evo-manage; changes only to design tokens / styles / theme — those go to ESLint and `tokens.overrides.css`.\nCoordinates with: teamix-evo-design-uni-manager (run alongside when the change also creates a UI screen — design handles the visual side, this skill handles file placement and reuse).",
-      "version": "0.2.0",
+      "description": "Enforce teamix-evo coding conventions in uni-manager apps — reuse-first, tenant/region context propagation, `src/` layering.\nTRIGGER when: user asks to 新增/重构/写 组件/页面/接口/hook in a 云管/专有云/多租户 console; phrases like \"create a CRUD page\" / \"add an API call\" / \"调接口\"; file write under `src/pages/**`, `src/components/**`, `src/features/**`.\nSKIP: pure visual/layout design with no code change (→ design-uni-manager); lifecycle commands (→ manage); token/style-only changes (→ ESLint).\nCoordinates with: teamix-evo-design-uni-manager (design handles visual side, this skill handles file placement and reuse).",
+      "version": "0.13.0",
       "source": "src/teamix-evo-code-uni-manager",
       "variant": "uni-manager",
       "ides": [
@@ -91,23 +91,6 @@
         "core"
       ],
       "template": false
-    },
-    {
-      "id": "teamix-evo-upgrade",
-      "name": "teamix-evo-upgrade",
-      "description": "Help the user adopt token renames in `.teamix-evo/.upgrade-hints/tokens-<ts>.json` AND component source upgrades in `.teamix-evo/.upgrade-staging/{ui,biz-ui}-<ts>/` after `teamix-evo update` / `teamix-evo tokens update` / `teamix-evo switch` / `teamix-evo ui upgrade` / `teamix-evo biz-ui upgrade`. Read each hint or staging manifest, scan the project for usages or compare current vs incoming source, propose codemod / file-replace diffs, apply only after explicit user approval, then archive processed inputs.\nTRIGGER when: user references `.teamix-evo/.upgrade-hints/`、`.teamix-evo/.upgrade-staging/`、`tokens-*.json` hint files、`ui-*` or `biz-ui-*` staging directories、phrases like \"处理 token 改名\"、\"应用 codemod\"、\"扫一下 legacy token\"、\"升级 token 引用\"、\"更新 token 名\"、\"组件升级\"、\"ui-staging\"、\"biz-ui staging\"、\"apply ui staging\"、\"apply biz-ui staging\"、\"应用组件升级\"、\"apply token rename codemod\"、\"adopt token rename hints\"、\"scan for legacy tokens\"、\"token rename upgrade\"、\"component source upgrade\"、\"review ui staging diff\"、\"token 治理\"、\"tokens diagnose\"、\"tokens treat\"、\"治理计划\"、\".treatment-plan.md\"、\"baseline 锁定\"、\"token 反哺\"、\"清理 token 违规\"、\"token cleanup\"、\"lint baseline\"、\"降违规\"、\"全部治理\"; AI sees output of `teamix-evo update` / `teamix-evo tokens update` / `teamix-evo switch --apply` / `teamix-evo ui upgrade` / `teamix-evo biz-ui upgrade` mentioning `💡 token rename hint:` or `staging at .teamix-evo/.upgrade-staging/...` and the user wants to follow up; AI sees output of `teamix-evo init` showing token-discipline ESLint warnings and the user wants to clean up; user opens any `.teamix-evo/.upgrade-hints/tokens-*.json` or any file under `.teamix-evo/.upgrade-staging/{ui,biz-ui}-*/` or `.teamix-evo/.treatment-plan.md`.\nSKIP: any other lifecycle work — `init` / `update` orchestration / variant switch itself / install / uninstall / generating staging (defer to teamix-evo-manage); pure visual or design changes (defer to teamix-evo-design-<variant>); any code authoring unrelated to the rename / staging window (defer to teamix-evo-code-<variant>); refuse to auto-apply — never write source code without explicit per-file user confirmation.\nCoordinates with: teamix-evo-manage (manage drives the upgrade flow that emits hints + staging; this skill consumes the resulting files).",
-      "version": "0.2.0",
-      "source": "src/teamix-evo-upgrade",
-      "ides": [
-        "qoder",
-        "claude"
-      ],
-      "updateStrategy": "managed",
-      "managedRegions": [
-        "core"
-      ],
-      "template": false,
-      "scope": "global"
     }
   ]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@teamix-evo/skills",
-  "version": "0.12.1",
+  "version": "0.13.0",
   "description": "Skills (AI IDE capabilities) for Teamix Evo",
   "type": "module",
   "files": [
@@ -12,7 +12,7 @@
   "devDependencies": {
     "@clack/prompts": "^0.8.0",
     "tsx": "^4.0.0",
-    "@teamix-evo/registry": "0.12.0"
+    "@teamix-evo/registry": "0.14.0"
   },
   "publishConfig": {
     "access": "public",

package/src/teamix-evo-code-opentrek/SKILL.md

@@ -1,10 +1,10 @@
 ---
 name: teamix-evo-code-opentrek
 description: |
-  Enforce teamix-evo coding conventions in OpenTrek-variant consumer apps — reuse-first against `@teamix-evo/ui` registry, API code under `src/services/`, `src/` layering and import boundaries.
-  TRIGGER when: user asks to "新增 / 重构 / 写一个" 组件 / 页面 / 接口 / 钩子 / 工具 / hook; phrases like "create a CRUD page"、"add an API call"、"extract a hook"、"refactor this fetch"、"调一下接口"、"加个组件"、"加个按钮"; file write under `src/pages/**`、`src/components/**`、`src/services/**`、`src/hooks/**`; AI is about to write any new `.tsx` / `.ts` file in a teamix-evo-installed project.
-  SKIP: pure visual / layout design questions about an already-existing screen with no code change (defer to teamix-evo-design-opentrek); teamix-evo lifecycle (init / update / uninstall) — those go to teamix-evo-manage; changes only to design tokens / styles / theme — those go to ESLint and `tokens.overrides.css`.
-  Coordinates with: teamix-evo-design-opentrek (run alongside when the change also creates a UI screen — design handles the visual side, this skill handles file placement and reuse).
+  Enforce teamix-evo coding conventions in OpenTrek apps — reuse-first, `src/` layering, import boundaries.
+  TRIGGER when: user asks to 新增/重构/写 组件/页面/接口/hook; phrases like "create a CRUD page" / "add an API call" / "调接口" / "加组件"; file write under `src/pages/**`, `src/components/**`, `src/features/**`.
+  SKIP: pure visual/layout design with no code change (→ design-opentrek); lifecycle commands (→ manage); token/style-only changes (→ ESLint).
+  Coordinates with: teamix-evo-design-opentrek (design handles visual side, this skill handles file placement and reuse).
 ---
 
 # teamix-evo-code-opentrek
@@ -23,7 +23,7 @@ Activate this skill whenever AI is about to **write or refactor code** inside a
 - "把这段重构一下"
 - "create a CRUD page for orders"
 - "add an API call to fetch users"
-- Any time AI is about to create a new file under `src/pages/`、`src/components/`、`src/services/`、`src/hooks/`
+- Any time AI is about to create a new file under `src/pages/`、`src/components/`、`src/features/`
 
 If the task is purely about _visual design_ of a screen (layout / colors / spacing), use [`teamix-evo-design`](../teamix-evo-design/SKILL.md) instead — or run both in tandem.
 
@@ -31,10 +31,10 @@ If the task is purely about _visual design_ of a screen (layout / colors / spaci
 
 Before AI writes or commits code, it performs an **8-step gated flow**. Steps 1-4 are baseline (**必须执行，不得跳过**); steps 5-7 are topic gates (run when the task touches that topic); step 8 is the final self-review (**必须执行，不得跳过**).
 
-1. **🚧 Reuse-first check** — **MUST READ** [`reuse-first.md`](reuse-first.md). Before creating any new component, query the `@teamix-evo/ui` registry (via MCP `list_components` / `find_components`) and grep the local project. Only write new code when no reuse path exists.
-2. **🚧 Layering check** — **MUST READ** [`api-layering.md`](api-layering.md). Any code that talks to a backend goes under `src/services/<domain>.ts`. Components never call `fetch` / `axios` directly. Data hooks live in `src/hooks/` and consume services.
-3. **🚧 Directory check** — **MUST READ** [`file-structure.md`](file-structure.md). Place the new file under the right top-level folder (pages / components / services / hooks / types / utils / lib / stores / contexts). Each folder has a single responsibility and an import boundary.
-4. **🚧 Forms gate** — if the task involves a form, **MUST READ** [`forms-and-validation.md`](forms-and-validation.md). `react-hook-form` + `zod`; schema lives at `src/services/<domain>.schema.ts`. Never wire forms with raw `useState`.
+1. **🚧 Reuse-first check** — **MUST READ** [`reuse-first.md`](reuse-first.md). Before creating any new component, query the `@teamix-evo/ui` registry (via `.teamix-evo/meta/ui/manifest.json` + `<id>.md`) and grep the local project. Only write new code when no reuse path exists.
+2. **🚧 Layering check** — **MUST READ** [`api-layering.md`](api-layering.md). Any code that talks to a backend goes under `src/features/<domain>/api.ts`. Components never call `fetch` / `axios` directly. Data hooks live in `src/features/<domain>/hooks.ts` and consume api functions.
+3. **🚧 Directory check** — **MUST READ** [`file-structure.md`](file-structure.md). Place the new file under the right top-level folder (pages / components / features / utils / lib / stores / contexts). Each folder has a single responsibility and an import boundary.
+4. **🚧 Forms gate** — if the task involves a form, **MUST READ** [`forms-and-validation.md`](forms-and-validation.md). `react-hook-form` + `zod`; schema lives at `src/features/<domain>/schema.ts`. Never wire forms with raw `useState`.
 5. **Error/loading gate** — if the task adds a page or data hook, **MUST READ** [`error-and-loading.md`](error-and-loading.md). Ensure global ErrorBoundary, page-level fallback, and three-state handling (`isPending` / `isError` / data) are in place; mutations report success/error via `toast`.
 6. **Routing gate** — if the task adds a route or page-entry, **MUST READ** [`routing-and-codesplit.md`](routing-and-codesplit.md). Pages use `React.lazy`; auth/role guards live in `src/routes/guards.tsx`; 404 / 403 / 500 fallbacks exist.
 7. **Testing gate** — **MUST READ** [`testing.md`](testing.md). Pure functions and zod schemas are **mandatory** to test; hooks and reusable components are recommended. Test files sit next to the source as `*.test.ts(x)`; `vitest` + `@testing-library/react` + `msw`.
@@ -50,14 +50,14 @@ Before AI writes or commits code, it performs an **8-step gated flow**. Steps 1-
 
 ## Outputs
 
-- Code placed under the conventional path (`src/pages/<id>/`、`src/services/<domain>.ts`、…)
+- Code placed under the conventional path (`src/pages/<id>/`、`src/features/<domain>/api.ts`、…)
 - Reuse decisions explicitly logged ("reused `Button` from `@teamix-evo/ui`" / "no match found, wrote a new `OrderCard` under `src/components/`")
 - Pass / fail status against [`checklist.md`](checklist.md)
 
 ## How to invoke (typical flow)
 
 1. Parse user intent → identify which artifact is being created (page / component / service / hook / util / form / route)
-2. Read [`reuse-first.md`](reuse-first.md) and run the reuse query (MCP first, then local grep)
+2. Read [`reuse-first.md`](reuse-first.md) and run the reuse query (读 `.teamix-evo/meta/` 本地文件, then local grep)
 3. Read [`file-structure.md`](file-structure.md) to pick the destination directory
 4. If the change touches network / backend, read [`api-layering.md`](api-layering.md)
 5. If the change involves a form, read [`forms-and-validation.md`](forms-and-validation.md)
@@ -73,7 +73,7 @@ Before AI writes or commits code, it performs an **8-step gated flow**. Steps 1-
 | ------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------- |
 | [`reuse-first.md`](reuse-first.md)                     | Decision flow for reusing existing components / utilities before writing new ones                                    |
 | [`file-structure.md`](file-structure.md)               | Top-level `src/` folder layout、ownership、import boundaries、naming、global-state tier (useState → Context → store) |
-| [`api-layering.md`](api-layering.md)                   | Where API code lives (`src/services/`)、how data flows from service → hook → component                               |
+| [`api-layering.md`](api-layering.md)                   | Where API code lives (`src/features/<domain>/`)、how data flows from api → hook → component                          |
 | [`forms-and-validation.md`](forms-and-validation.md)   | `react-hook-form` + `zod` patterns、schema location、submit/error wiring                                             |
 | [`error-and-loading.md`](error-and-loading.md)         | Global / page ErrorBoundary、react-query three-state、Suspense、toast、reportError                                   |
 | [`routing-and-codesplit.md`](routing-and-codesplit.md) | `React.lazy` per page、guards、404/403/500 fallback、search-params state、Suspense placement                         |
@@ -88,7 +88,7 @@ Before AI writes or commits code, it performs an **8-step gated flow**. Steps 1-
 ## Why these conventions
 
 - **Single source for UI** — `@teamix-evo/ui` is a source-injected component library (89 entries). Re-implementing `Button`、`Dialog`、`DataTable` etc. inside the consumer app fragments the design system and breaks token discipline.
-- **Stable seams for change** — keeping API calls in `src/services/` means a backend rename only edits one file; keeping components free of fetch logic means they stay easy to test and reuse.
+- **Stable seams for change** — keeping API calls in `src/features/<domain>/api.ts` means a backend rename only edits one file; keeping components free of fetch logic means they stay easy to test and reuse.
 - **Predictable file location** — when AI (or a new teammate) opens an unfamiliar consumer app, the directory shape is the same across all teamix-evo-bootstrapped projects.
 
 <!-- teamix-evo:managed:end -->

package/src/teamix-evo-code-opentrek/api-layering.md

@@ -2,11 +2,11 @@
 
 > ⚠️ **Prerequisites**: 本文件是 [SKILL.md](./SKILL.md) Step 2 的强制读取项。任何涉及后端通信的代码必须先读本文件。
 
-> **核心原则**:组件不直接 fetch。所有与后端通信的代码都落在 `src/services/`,通过 `src/hooks/` 暴露给组件。
+> **核心原则**:组件不直接 fetch。每个业务领域的代码聚合在 `src/features/<domain>/`，通过 hooks 暴露给组件。
 
 ---
 
-## 三层结构
+## Feature-based 三层结构
 
 ```
 ┌────────────────────────────────────┐
@@ -18,7 +18,7 @@
                │ 仅通过 hook
                ▼
 ┌────────────────────────────────────┐
-│  src/hooks/use<Domain>*.ts         │  Hook 层:状态管理 + 缓存(react-query 等)
+│  src/features/<domain>/hooks.ts    │  Hook 层:状态管理 + 缓存(react-query 等)
 │  - 包装请求生命周期(loading/error) │
 │  - 处理缓存 / 重试 / 失效           │
 │  - 不写具体的 URL / payload 拼装    │
@@ -26,7 +26,7 @@
                │ 调用纯函数
                ▼
 ┌────────────────────────────────────┐
-│  src/services/<domain>.ts          │  Service 层:请求纯函数
+│  src/features/<domain>/api.ts      │  API 层:请求纯函数
 │  - 输入参数 → 输出 Promise<T>      │
 │  - 拼 URL / 序列化 / 反序列化       │
 │  - 不依赖 React                    │
@@ -40,30 +40,43 @@
 └────────────────────────────────────┘
 ```
 
+### 目录结构
+
+```
+src/features/
+├── order/            # 订单领域
+│   ├── api.ts        # 请求纯函数(listOrders, createOrder, ...)
+│   ├── hooks.ts      # react-query 封装(useOrderList, useCreateOrder, ...)
+│   ├── types.ts      # 领域类型(Order, OrderStatus, OrderListParams, ...)
+│   ├── mocks.ts      # 本地 mock 数据(开发阶段)
+│   └── schema.ts     # zod schema(CreateOrderInputSchema, ...)
+├── user/             # 用户领域
+│   ├── api.ts
+│   ├── hooks.ts
+│   ├── types.ts
+│   └── mocks.ts
+└── tenant/           # 租户领域
+    └── ...
+```
+
+新增一个业务领域 = 新增一个 `features/<domain>/` 文件夹,不会让任何一个目录膨胀。
+
 ---
 
-## §1 · `src/services/` 约定
+## §1 · `features/<domain>/api.ts` 约定
 
 ### 文件组织
 
-按**领域**(domain)拆,**不**按 HTTP 动词拆。
-
-```
-src/services/
-├── order.ts          # 订单领域:list / get / create / update / cancel
-├── user.ts           # 用户领域
-├── tenant.ts         # 租户领域
-└── index.ts          # 统一 re-export(可选)
-```
+按**领域**(domain)拆为独立文件夹,每个领域的请求函数放 `api.ts`。
 
 ❌ 不要按动词拆:`getOrders.ts` / `createOrder.ts` / `updateOrder.ts` —— 会爆文件数。
 
 ### 函数签名约定
 
 ```ts
-// src/services/order.ts
+// src/features/order/api.ts
 import { http } from '@/lib/http';
-import type { Order, OrderListParams, CreateOrderInput } from '@/types/order';
+import type { Order, OrderListParams, CreateOrderInput } from './types';
 
 export async function listOrders(params: OrderListParams): Promise<Order[]> {
   const { data } = await http.get('/api/orders', { params });
@@ -84,33 +97,35 @@ export async function createOrder(input: CreateOrderInput): Promise<Order> {
 要点:
 
 - **纯函数**(不依赖 React 上下文,可以在 SSR / Node 测试中单独跑)
-- **类型来自 `src/types/`**,不要在 service 文件里就地定义 domain 类型
-- **错误不在 service 层处理** —— 抛出去给 hook / 全局 interceptor 处理(归一化在 `src/lib/http.ts`)
+- **类型来自同目录 `./types`**,同一领域内用相对路径引用
+- **错误不在 api 层处理** —— 抛出去给 hook / 全局 interceptor 处理(归一化在 `src/lib/http.ts`)
 - **不写 console.log / 业务弹窗** —— 是数据通道,不是 UI 通道
 
 ### 反模式
 
 - ❌ `fetch('https://api.example.com/...')` 写死 host(应该用 `http` wrapper)
-- ❌ service 函数返回 `{ loading, data, error }`(那是 hook 该做的)
-- ❌ 在 service 里 `import { toast } from 'sonner'` 弹通知(归到 hook 或全局 interceptor)
-- ❌ 一个 service 函数同时拼 URL、做业务计算、改全局 store
+- ❌ api 函数返回 `{ loading, data, error }`(那是 hook 该做的)
+- ❌ 在 api 里 `import { toast } from 'sonner'` 弹通知(归到 hook 或全局 interceptor)
+- ❌ 一个 api 函数同时拼 URL、做业务计算、改全局 store
 
 ---
 
-## §2 · `src/hooks/` 约定
+## §2 · `features/<domain>/hooks.ts` 约定
 
 ### 命名
 
 - Query 类:`useOrderList`、`useOrder(id)`、`useUserProfile`
 - Mutation 类:`useCreateOrder`、`useCancelOrder`、`useUpdateUser`
 
+同一领域的 query + mutation hooks 聚合在一个 `hooks.ts` 里。
+
 ### 实现(以 `@tanstack/react-query` 为例)
 
 ```ts
-// src/hooks/useOrderList.ts
-import { useQuery } from '@tanstack/react-query';
-import { listOrders } from '@/services/order';
-import type { OrderListParams } from '@/types/order';
+// src/features/order/hooks.ts
+import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query';
+import { listOrders, createOrder } from './api';
+import type { OrderListParams } from './types';
 
 export function useOrderList(params: OrderListParams) {
   return useQuery({
@@ -119,12 +134,6 @@ export function useOrderList(params: OrderListParams) {
     staleTime: 30_000,
   });
 }
-```
-
-```ts
-// src/hooks/useCreateOrder.ts
-import { useMutation, useQueryClient } from '@tanstack/react-query';
-import { createOrder } from '@/services/order';
 
 export function useCreateOrder() {
   const qc = useQueryClient();
@@ -137,8 +146,8 @@ export function useCreateOrder() {
 
 ### 反模式
 
-- ❌ Hook 里再次拼 URL(违反"service 拼 URL"边界)
-- ❌ 一个 hook 调多个 service 把数据缝合 —— 缝合应该在 service 层(返回组合好的 DTO)
+- ❌ Hook 里再次拼 URL(违反"api 拼 URL"边界)
+- ❌ 一个 hook 调多个领域的 api 把数据缝合 —— 缝合应该在 api 层(返回组合好的 DTO)
 - ❌ Hook 里写业务跳转 / 路由切换 —— 由组件接 `mutation.onSuccess` callback 处理
 
 ---
@@ -188,15 +197,15 @@ http.interceptors.response.use(
 ## §4 · 类型分层
 
 ```
-src/types/
-├── order.ts          # Order、OrderStatus、OrderListParams、CreateOrderInput
-├── user.ts
-└── api.ts            # 通用 ApiResponse<T>、Pagination<T>
+src/features/order/types.ts    # Order、OrderStatus、OrderListParams、CreateOrderInput
+src/features/user/types.ts     # User、UserRole、...
+src/types/api.ts               # 通用 ApiResponse<T>、Pagination<T>(跨领域共享)
 ```
 
-- **Domain 类型**(如 `Order`)放 `src/types/<domain>.ts`,被 service / hook / component 共享
-- **API 入参 / 出参类型**:与 domain 类型分开命名(`OrderListParams` vs `Order`)
-- **不要**让组件 props 类型直接 `import` service 的内部类型 —— 走 `src/types/` 中转
+- **Domain 类型**(如 `Order`)放 `src/features/<domain>/types.ts`,同领域内用相对路径 `./types` 引用
+- 组件消费时用 `@/features/order/types` 引入
+- **跨领域通用类型**（如 `ApiResponse<T>`、`Pagination<T>`）放 `src/types/api.ts`
+- **API 入参 / 出参类型**:与 domain 类型分开命名(`OrderListParams` vs `Order`），但放同一个 `types.ts`
 
 ---
 
@@ -219,9 +228,9 @@ src/types/
 ```
 ## 数据层改动
 
-- src/types/order.ts: 新增 `OrderListParams`、`OrderStatus`
-- src/services/order.ts: 新增 `listOrders`、`cancelOrder`(纯函数,使用 `@/lib/http`)
-- src/hooks/useOrderList.ts: 包 `useQuery`,key=['orders', params]
+- src/features/order/types.ts: 新增 `OrderListParams`、`OrderStatus`
+- src/features/order/api.ts: 新增 `listOrders`、`cancelOrder`(纯函数,使用 `@/lib/http`)
+- src/features/order/hooks.ts: 新增 `useOrderList`(useQuery, key=['orders', params])
 - src/pages/orders/index.tsx: 仅消费 `useOrderList`,不直接 fetch
 ```
 

package/src/teamix-evo-code-opentrek/checklist.md

@@ -8,9 +8,9 @@
 
 ## 1. 复用判定 ✓
 
-- [ ] 新建 UI 组件前,查过 `@teamix-evo/ui` 注册表(MCP `list_components` / `find_components`)
+- [ ] 新建 UI 组件前,查过 `@teamix-evo/ui` 注册表(`.teamix-evo/meta/ui/manifest.json` + `<id>.md`)
 - [ ] 新建 UI 组件前,grep 过本项目 `src/components/`
-- [ ] 新建工具函数前,grep 过 `src/utils/` `src/lib/` `src/hooks/`
+- [ ] 新建工具函数前,grep 过 `src/utils/` `src/lib/` `src/features/`
 - [ ] 没有重复实现 ui 包已经提供的能力(Button、Input、Dialog、DataTable 等)
 - [ ] 没有 fork ui 包源码改样式(改样式应当走 design token)
 - [ ] 响应里**显式列出**复用决策日志(✅ 复用了哪些 / 🆕 新写了哪些及原因)
@@ -19,19 +19,19 @@
 
 - [ ] 组件**没有**直接调 `fetch` / `axios`
 - [ ] 组件**没有**直接读 `import.meta.env` / `process.env`(env 走 `src/lib/env.ts`)
-- [ ] 所有后端调用都落在 `src/services/<domain>.ts`,且是纯函数
-- [ ] Service 函数**不依赖 React**(没有 `useXxx`、没有 `useState`)
-- [ ] Service 函数**不弹通知 / 不跳路由**
-- [ ] 数据 hook 在 `src/hooks/`,使用统一的数据库(react-query / swr,不混用)
+- [ ] 所有后端调用都落在 `src/features/<domain>/api.ts`,且是纯函数
+- [ ] API 函数**不依赖 React**(没有 `useXxx`、没有 `useState`)
+- [ ] API 函数**不弹通知 / 不跳路由**
+- [ ] 数据 hook 在 `src/features/<domain>/hooks.ts`,使用统一的数据库(react-query / swr,不混用)
 - [ ] 全局只有一份 http 实例,在 `src/lib/http.ts`
 
 ## 3. 目录归位 ✓
 
-- [ ] 新文件位于约定的顶层目录(`pages/`、`components/`、`services/`、`hooks/`、`stores/`、`types/`、`utils/`、`lib/`)
-- [ ] **没有**新增同义层(如 `views/`、`api/`、`helpers/` 与现有目录并存)
+- [ ] 业务领域代码(api/hooks/types/mocks)放在 `src/features/<domain>/`
+- [ ] 新文件位于约定的顶层目录(`pages/`、`components/`、`features/`、`stores/`、`utils/`、`lib/`)
+- [ ] **没有**新增同义层(如 `views/`、`services/`、`helpers/` 与现有目录并存)
 - [ ] 仅在单个页面使用的组件 / hook 放在 `src/pages/<id>/_components/` 或 `_hooks/`(下划线前缀)
-- [ ] 跨页面复用的组件 / hook 才升到 `src/components/` `src/hooks/`
-- [ ] React Hook 在 `hooks/`,不在 `utils/`(`utils/` 不依赖 React)
+- [ ] 跨页面复用的组件升到 `src/components/`；跨领域共享的 hook 放 `src/hooks/`（极少数）
 - [ ] 类型声明文件没有运行时代码(纯类型)
 
 ## 4. 命名 ✓
@@ -47,15 +47,15 @@
 - [ ] 跨目录 import 走 `@/*` 别名,**未使用** `../../../` 相对路径上跳超过 2 层
 - [ ] **未发生反向依赖**:
   - `components/` 没有 import `pages/`
-  - `services/` 没有 import `hooks/` `components/` `pages/`
-  - `hooks/` 没有 import `pages/`
-  - `utils/` `lib/` `types/` 没有 import 业务层
+  - `features/<domain>/api.ts` 没有 import `hooks` `components/` `pages/`
+  - `features/<domain>/hooks.ts` 没有 import `pages/`
+  - `utils/` `lib/` 没有 import 业务层
 - [ ] 页面私有目录(`_components/` `_hooks/`)**没有**被其他页面 import
 
 ## 6. 类型 ✓
 
-- [ ] Domain 类型放 `src/types/<domain>.ts`,不在 service / component 文件就地定义
-- [ ] Service 函数有显式的入参 / 返回 `Promise<T>` 类型
+- [ ] Domain 类型放 `src/features/<domain>/types.ts`,不在 api / component 文件就地定义
+- [ ] API 函数有显式的入参 / 返回 `Promise<T>` 类型
 - [ ] 没有 `any`(必要的转义类型用 `unknown` 配合 narrowing,或加注释说明原因)
 - [ ] Hook 的返回类型由 `react-query` / `swr` 自动推断,无需手写
 
@@ -77,7 +77,7 @@
 (若改动涉及表单 — 详见 [`forms-and-validation.md`](forms-and-validation.md))
 
 - [ ] 表单状态用 `react-hook-form`,**未用** `useState` 拼字段
-- [ ] 校验用 `zod` schema,schema 落 `src/services/<domain>.schema.ts`
+- [ ] 校验用 `zod` schema,schema 落 `src/features/<domain>/schema.ts`
 - [ ] 类型从 schema 推导(`z.infer<...>`),**未手写**重复 interface
 - [ ] 错误信息写在 schema 里,UI 只读取,**未在组件里硬编码**校验文案
 - [ ] 提交走 mutation hook,**未在** `<form onSubmit>` 里直接 fetch
@@ -113,7 +113,7 @@
 
 (详见 [`testing.md`](testing.md))
 
-- [ ] 新增纯函数(`src/utils/`、`src/services/`)有同名 `*.test.ts`(**必测**)
+- [ ] 新增纯函数(`src/utils/`、`src/features/*/api.ts`)有同名 `*.test.ts`(**必测**)
 - [ ] 新增 zod schema 有 `parse` 成功 / 失败用例(**必测**)
 - [ ] 关键业务路径(下单 / 支付 / 鉴权)有组件 / hook 测试(**必测**)
 - [ ] 测试文件就近放在 `<source>.test.ts(x)`,**未**集中到顶层 `tests/`
@@ -137,10 +137,10 @@
 
 1. **组件直接 fetch / axios** —— 数据层未分层
 2. **新建 Button / Input / Dialog 等基础组件** —— 重造 ui 包能力
-3. **services 函数依赖 React** —— 边界穿透
-4. **`src/views/` 与 `src/pages/` 并存(或 `src/api/` 与 `src/services/`)** —— 同义层污染
+3. **features/*/api.ts 函数依赖 React** —— 边界穿透
+4. **`src/views/` 与 `src/pages/` 并存(或 `src/services/` 与 `src/features/`)** —— 同义层污染
 5. **响应里没有复用决策日志** —— 流程未跑通
-6. **反向依赖**(service 引 hook、component 引 page) —— 依赖图破坏
+6. **反向依赖**(api 引 hook、component 引 page) —— 依赖图破坏
 7. **多份 http 实例** —— 鉴权 / 错误处理无法统一
 8. **没有全局 ErrorBoundary** —— 异常直接白屏给用户
 9. **表单用 `useState` 拼字段、用 onChange 手写校验** —— 弃 react-hook-form + zod
@@ -158,12 +158,12 @@
 ## 编码合规自检
 
 - 复用判定: ✅ 复用 ui 包 Button / DataTable;🆕 新写 OrderStatusBadge(原因:业务状态映射)
-- 数据层: ✅ services/order.ts 纯函数;✅ hooks/useOrderList.ts 包 react-query;✅ 组件未 fetch
-- 目录: ✅ 页面在 pages/orders/;✅ 跨页面组件在 components/
+- 数据层: ✅ features/order/api.ts 纯函数;✅ features/order/hooks.ts 包 react-query;✅ 组件未 fetch
+- 目录: ✅ 页面在 pages/orders/;✅ 领域代码在 features/order/;✅ 跨页面组件在 components/
 - 命名: ✅ kebab 目录 / Pascal 组件 / camel hook
 - 边界: ✅ 全部走 @/\*;✅ 无反向依赖
-- 类型: ✅ types/order.ts 集中声明
-- 表单(若涉及): ✅ useForm + zodResolver;✅ schema 在 services/order.schema.ts
+- 类型: ✅ features/order/types.ts 集中声明
+- 表单(若涉及): ✅ useForm + zodResolver;✅ schema 在 features/order/schema.ts
 - 错误/加载(若涉及): ✅ 三态全处理;✅ ErrorBoundary 已在 App 根;✅ mutation toast
 - 路由(若涉及): ✅ React.lazy + Suspense;✅ 守卫已复用;✅ 404 兜底已存在
 - 测试: ✅ 新增 formatXxx → formatXxx.test.ts(5 case);✅ schema parse 失败用例已加