diff --git a/AGENTS.md b/AGENTS.md index f237e8ba..7bd02a44 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -16,20 +16,25 @@ ## 目录与职责 -- `src/views/`:路由级页面和业务编排;复杂、可复用的展示或交互下沉到组件。 -- `src/components/`:无路由依赖的复用组件,输入输出应有明确类型。 -- `src/layouts/`:应用壳层、导航和全局页面结构。 -- `src/router/`:路由、标题、登录保护和权限元数据;新增模块时同步维护导航与路由配置。 -- `src/stores/`:跨页面状态和业务动作;仅页面局部使用的状态留在组件内。 -- `src/api/`:HTTP 客户端和接口适配;页面与组件不得散落创建 Axios 实例。 +- `src/app/`:应用装配层,包含布局、根路由、全局守卫和启动入口;不承载具体业务或被业务模块反向依赖。 +- `src/core/`:认证会话、访问控制、导航配置、未保存工作保护和路由安全工具等全应用基础能力;可以被 `app` 和业务模块使用,但不得依赖业务模块。 +- `src/modules/`:按客户、仓库、头程订单、主数据、下载中心、IAM 等稳定业务领域组织页面、API、类型、组件和路由。新增业务页面必须进入对应模块,不再建立根级 `views/`。 +- `src/shared/`:与具体业务无关的后台公共 HTTP、组件和工具。模块专属能力先留在模块内部,只有被无关模块真实复用时才上移。 +- `src/prototype/`:未纳入当前迭代的原型页面和原型路由;正式模块不得依赖原型代码。 +- `src/modules/*/pages/`:路由级页面和业务编排;复杂展示、表单、抽屉和交互下沉到同模块组件或 composable。 +- `src/modules/*/routes.ts`:模块路由片段;由 `src/app/router/index.ts` 统一装配。新增模块时同步维护 `src/core/navigation/adminNavigation.ts`。 +- `src/core/*/` 与 `src/modules/*/stores/`:前者只放全应用基础状态,后者放领域状态;仅页面局部使用的状态留在页面或 composable。 +- `src/modules/*/api/`:领域接口适配;公共 Axios 客户端位于 `src/shared/api/http.ts`,页面与组件不得散落创建 Axios 实例。 - `VITE_API_BASE_URL` 控制浏览器请求前缀,`API_PROXY_TARGET` 控制 Vite 开发代理上游;后者只由开发服务器读取,不进入客户端构建。新增或变更环境变量时同步更新 `.env.example`,不得提交真实密钥或环境专属凭据。 -- `src/types/`:后台专属类型;跨应用共享的稳定契约放到 `packages/shared`。 +- 模块专属类型放在对应模块;跨应用共享的稳定契约放到 `packages/shared`。 - `src/styles/`:设计令牌和全局样式;优先复用现有 `--cc-*` 变量和组件样式。 +依赖方向保持为 `app -> modules/core/shared`、`modules -> core/shared`、`core -> shared`、`shared -> 无上层依赖`。模块间确需调用时只能引用对方根入口公开的 API 或契约,不得引用其他模块的页面、内部组件或内部目录。 + ## 业务与安全约束 - 菜单隐藏和前端路由守卫只改善体验,不能替代服务端鉴权。新增操作必须使用稳定的权限编码,并与 API 权限保持一致。 -- 认证统一经过 `src/stores/auth.ts` 和 `src/api/http.ts`;不要在页面中复制令牌读写或手工拼装 `Authorization`。 +- 认证统一经过 `src/core/auth/auth.ts` 和 `src/shared/api/http.ts`;不要在页面中复制令牌读写或手工拼装 `Authorization`。 - 当前登录和部分数据仍可能是模拟实现。接入 `services/api` 时删除对应模拟路径,不允许让生产逻辑静默回退到假数据。 - 删除、停用、改权限等高风险操作必须有明确确认、处理中、成功和失败反馈;失败时保留用户上下文,避免误以为已生效。 - 日志、提示和示例数据不得包含真实账号、令牌、客户隐私或生产数据。 diff --git a/README.md b/README.md index cc56a4f7..37f481a2 100644 --- a/README.md +++ b/README.md @@ -23,9 +23,19 @@ pnpm build pnpm test ``` +## 源码结构 + +- `src/app/`:应用壳层、根路由和启动装配。 +- `src/core/`:认证、权限、导航、未保存工作保护等全应用基础能力。 +- `src/modules/`:按业务领域组织页面、接口、组件、类型和模块路由。 +- `src/shared/`:不依赖具体业务的 HTTP、基础组件和工具。 +- `src/prototype/`:尚未进入当前迭代的原型页面与路由,和正式业务代码隔离。 + +新增业务页面时,在对应 `src/modules//` 中就近放置页面、测试和领域能力,并从模块 `routes.ts` 导出路由片段;根路由只负责装配,菜单仍由 `src/core/navigation/adminNavigation.ts` 集中维护。跨模块调用必须经过模块根入口公开的 API,不能引用对方内部目录。 + 依赖和 `pnpm-lock.yaml` 均保存在当前前端项目中,不需要在仓库根目录安装 Node 依赖。 -工作台已从一期路由与菜单移除;登录后按当前角色进入第一个有权限的业务页面。一期 Admin 路由聚焦登录、客户及注册审核、平台收货仓、快递公司、往来单位、头程订单、内部用户、角色管理和菜单权限。 +工作台已从一期菜单和默认入口移除;登录后按当前角色进入第一个有权限的业务页面。历史工作台仍保留为不展示菜单的原型路由。一期 Admin 正式路由聚焦登录、客户及注册审核、平台收货仓、快递公司、往来单位、头程订单、内部用户、角色管理和菜单权限。 后台菜单仅展示已接入的一期模块;其余平台原型菜单保留为导航配置中的注释,待对应业务契约接入后再恢复展示。企业审核、仓库、头程订单、平台角色、菜单及按钮权限资源均接入真实接口;用户管理通过 IAM 统一维护平台账号和企业租户账号。运行时不再提供本地演示业务数据或静态角色预览。 diff --git a/src/components/AdminSidebarMenu.test.ts b/src/app/components/AdminSidebarMenu.test.ts similarity index 98% rename from src/components/AdminSidebarMenu.test.ts rename to src/app/components/AdminSidebarMenu.test.ts index def2ca02..b399c382 100644 --- a/src/components/AdminSidebarMenu.test.ts +++ b/src/app/components/AdminSidebarMenu.test.ts @@ -1,6 +1,6 @@ import { mount } from '@vue/test-utils' import { describe, expect, it } from 'vitest' -import { adminNavigation, filterAdminNavigation, type AdminNavigationNode } from '@/navigation/adminNavigation' +import { adminNavigation, filterAdminNavigation, type AdminNavigationNode } from '@/core/navigation/adminNavigation' import AdminSidebarMenu from './AdminSidebarMenu.vue' const stubs = { diff --git a/src/components/AdminSidebarMenu.vue b/src/app/components/AdminSidebarMenu.vue similarity index 90% rename from src/components/AdminSidebarMenu.vue rename to src/app/components/AdminSidebarMenu.vue index bf254295..9e2737dc 100644 --- a/src/components/AdminSidebarMenu.vue +++ b/src/app/components/AdminSidebarMenu.vue @@ -1,6 +1,6 @@