From e617e303d477be14b53c13b77ffef99404c09b37 Mon Sep 17 00:00:00 2001 From: DEV_DSW <562304744@qq.com> Date: Tue, 2 Jun 2026 11:42:01 +0800 Subject: [PATCH] docs: update project docs and add git commit message guidelines - add .trae/rules/git-commit-message.md with official commit rules - update AGENTS.md to add Chinese commit message requirement - overhaul README.md: update tech stack, directory structure, env vars, routing, i18n and request lib docs --- AGENTS.md | 1 + README.md | 80 +++++++++++++++++++++++++++++-------------------------- 2 files changed, 43 insertions(+), 38 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index c4c49d1..e6a7d91 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -76,3 +76,4 @@ - 需要编译时就提醒用户手动确定 - 需要测试时就提醒用户手动执行 - 有滚动条的区域，需要添加scrollbar-none [-ms-overflow-style:none] [&::-webkit-scrollbar]:hidden 类名 +- git 提交时，必须使用中文提交信息 diff --git a/README.md b/README.md index 0e5d594..7c79199 100644 --- a/README.md +++ b/README.md @@ -4,22 +4,26 @@ ## 技术栈 -- Vite 5 +- Vite（见 `package.json`，本仓库使用 ESM：`"type": "module"`） - Vue 3 + TypeScript - vue-router 4 - Pinia -- Vant 4 +- Vant 4（配合 `unplugin-auto-import` / `unplugin-vue-components` 自动导入） - Tailwind CSS v4（通过 `@tailwindcss/vite`） -- vue-i18n -- axios（统一请求库封装见下文） +- vue-i18n（支持：`zh-CN` / `en-US` / `th-TH`） +- axios（统一请求库：`src/utils/request.ts`） +- mitt（事件总线） ## 目录约定 - 入口：`src/main.ts` +- 根组件：`src/App.vue` - 路由：`src/router/index.ts` - 页面：`src/pages/` -- 组件：`src/components/` +- 公共组件：`src/components/` +- 首页模块组件：`src/pages/home/components/` - 国际化：`src/i18n/` +- 状态管理：`src/store/` - 全局样式：`src/styles/main.css` - 工具：`src/utils/` - 共享类型：`src/shared/` @@ -35,7 +39,7 @@ yarn dev 常用命令： -- `yarn dev`：启动开发服务器（端口 5174） +- `yarn dev`：启动开发服务器（端口 5174，配置见 `vite.config.ts`） - `yarn typecheck`：`vue-tsc --noEmit` - `yarn build`：类型检查 + 构建 - `yarn preview`：预览构建产物 @@ -43,51 +47,51 @@ yarn dev 需要编译/测试时请手动确认执行。 +## 环境变量 + +本项目使用 Vite 环境变量（`import.meta.env.*`）。 + +必须配置： + +- `VITE_API_BASE_URL`：接口基础地址（请求库会校验，缺失会直接抛错） + +常用配置： + +- `VITE_CLIENT_ID`：请求 header 注入的 `clientId` +- `VITE_API_TIMEOUT_MS`：请求超时毫秒数（默认 15000） +- `VITE_TOKEN`：临时 token（当前请求库会在请求前写入上下文，属于临时逻辑） + ## 路由 -当前已在 [router/index.ts](file:///d:/www/znkj/nianxx-h5/src/router/index.ts) 配置页面路由（按 `src/pages/` 目录落地）： +当前路由配置见 `src/router/index.ts`（按 `src/pages/` 目录落地）： - `/`、`/home`：首页 - `/login`：登录 - `/booking`：预定 -- `/goods`、`/goods/album`：商品详情/相册 -- `/quick`、`/quick/list`：快速预定 -- `/order`、`/order/detail`：订单列表/详情 -- `/service/order`：工单列表 +- `/goods`：商品详情 +- `/album`：相册 +- `/quick`：快速预定 +- `/order`、`/order/detail`：订单列表 / 订单详情 +- `/service`：工单列表 + +## 国际化（i18n） + +- i18n 实例：`src/i18n/index.ts` +- 语言包：`src/i18n/modules/**/{zh-CN,en-US,th-TH}.ts` +- 切换语言：`setLocale(locale)`（同时会同步 Vant 语言与 `document.lang`） ## 统一请求库 统一请求库实现： -- [request.ts](file:///d:/www/znkj/nianxx-h5/src/utils/request.ts) -- 类型定义：[request-types.ts](file:///d:/www/znkj/nianxx-h5/src/shared/request-types.ts) -- 使用文档：[docs/request.md](file:///d:/www/znkj/nianxx-h5/docs/request.md) +- `src/utils/request.ts` +- 类型定义：`src/shared/request-types.ts` +- 使用文档：`docs/request.md` -必须配置环境变量： +## 特殊说明（uni-\* 痕迹） -- `VITE_API_BASE_URL` - -可选配置： - -- `VITE_API_TIMEOUT_MS`（默认 15000） - -## 特殊说明（uni-* 痕迹） - -代码中存在 `uni.*` API、`` 等用法。若最终运行环境为纯 H5 Web，需要确认这些能力的提供方式（注入/替换/降级）。 - -## 历史遗留问题清单（待逐个替换） - -以下为当前仓库可证实的缺失/不一致点，建议按优先级逐步处理： - -- `@/request/api/*` 在多个页面/组件被引用，但仓库内暂无对应实现 -- `@/utils` 存在目录级导入，但暂无 `src/utils/index.*` -- `@/store` 被引用但实际目录为 `src/stores/` -- `@/hooks/*`、`@/constant/*` 被引用但当前仓库未找到对应目录 -- `src/utils/requets.ts` 为空文件且命名疑似拼写遗留 - -更详细的引用点列表见：`.trae/documents/统一请求库封装计划.md`。 +代码中仍存在部分 `uni.*` API（例如 `uni.navigateTo` / `uni.requestSubscribeMessage`）。如果最终运行环境为纯 H5 Web，需要确认这些能力的提供方式（注入 / 替换 / 降级）。 ## 协作规范 -仓库协作约定见 [AGENTS.md](file:///d:/www/znkj/nianxx-h5/AGENTS.md)。 - +仓库协作约定见 `AGENTS.md`。