From 3f75ab4ef615a30e3e436e2f2121f46d66069976 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E7=86=8A=E7=86=8A=E7=86=8A=E5=AD=90=E8=B7=AF?= Date: Fri, 31 Jul 2026 11:49:04 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E6=B7=BB=E5=8A=A0AGENTS.md=E5=92=8CCLA?= =?UTF-8?q?UDE.md=E7=94=A8=E4=BA=8E=E4=BB=A3=E7=90=86=E9=85=8D=E7=BD=AE?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 添加文档文件，为在此仓库中工作的AI编码代理提供上下文和指令。这些文件描述了项目结构、命令、架构决策和关键约定。 --- AGENTS.md | 124 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ CLAUDE.md | 1 + 2 files changed, 125 insertions(+) create mode 100644 AGENTS.md create mode 100644 CLAUDE.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..1d352d9 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,124 @@ +# CLAUDE.md + +This file provides guidance to AI Coding Agent when working with code in this repository. + +## 项目概况 + +微信小程序 TypeScript 模板 — 基于 TypeScript + SASS 的小程序开发脚手架，集成 TDesign 组件库、axios-miniprogram 网络请求、crypto-js AES 加密等。 + +## 常用命令 + +```bash +# 安装依赖（需要 pnpm） +pnpm install + +# ESLint 检查 +pnpm lint + +# ESLint 自动修复 +pnpm lint:fix + +# Prettier 格式化 +pnpm format + +# Prettier 格式检查 +pnpm format:check +``` + +**微信开发者工具操作：** + +- 修改 `package.json` 依赖后，需在微信开发者工具中执行「工具 → 构建 npm」 +- TypeScript 和 SASS 编译由微信开发者工具内置编译器完成（无独立构建命令） +- 开发时在微信开发者工具中点击「编译」即可预览 + +## 技术栈 + +| 类别 | 技术 | +| -------- | -------------------------------------------------------------------- | +| 语言 | TypeScript (ES2020 target, CommonJS module) | +| 样式 | SASS/SCSS（通过 `project.config.json` 的 `useCompilerPlugins` 启用） | +| UI 组件 | TDesign Miniprogram v1.12+ | +| HTTP | axios-miniprogram v2.7+ | +| 加密 | crypto-js v4.2+ | +| 包管理 | pnpm | +| 代码规范 | ESLint 9 + TypeScript ESLint + Prettier | + +## 项目架构 + +``` +miniprogram/ +├── app.ts # 入口：计算导航栏/安全区尺寸、初始化 platformInfo 到 globalData +├── app.json # 页面注册、自定义 TabBar、navigationStyle: "custom" +├── app.scss # 全局样式重置 +├── api/ # API 接口层（每接口一个文件 + types.ts 定义 StandardResponse） +├── components/ # 共享组件（目前仅有 page-container） +├── custom-tab-bar/ # 自定义 TabBar（基于 TDesign t-tab-bar） +├── pages/ # 页面（index, login, date, one~four） +├── utils/ +│ ├── request.ts # axios-miniprogram 封装：Token 注入、loading 管理、401 跳转 +│ ├── aes.ts # AES-256-CBC 加密/解密 + URL Safe Base64 变体 +│ ├── util.ts # 日期格式化（formatTime / formatDateTime） +│ └── platform.ts # 微信宿主平台信息检测（设备类别/操作系统/桌面or移动） +└── miniprogram_npm/ # 微信开发者工具构建的 npm 产物（已 gitignore，不直接编辑） +typings/ # 全局类型声明（IAppOption、PlatformInfoType 等）+ 微信 API 类型 +``` + +## 核心架构决策 + +### 自定义导航栏 + +`app.json` 中 `window.navigationStyle: "custom"` 全局关闭了原生导航栏。所有需要导航栏的页面必须使用 `page-container` 组件（封装 TDesign `t-navbar`），该组件自动根据页面栈深度决定是否显示返回按钮。 + +### 网络请求模式 + +所有 API 调用遵循统一模式： + +1. `api/types.ts` 定义 `StandardResponse` 结构（`{ code, data, message }`） +2. 每个 API 模块从 `utils/request` 导入 axios 实例，定义请求函数 +3. 请求拦截器自动注入 `Authorization` header（从 `app.globalData.token` 读取），白名单接口除外 +4. 响应拦截器在 `code === 200` 时自动解包返回 `result.data`，401 时 `reLaunch` 到登录页 +5. 并发请求的 loading 动画通过计数器管理（`netWorkNum`），避免闪烁 + +### GlobalData 结构 + +`app.globalData` 在 `onLaunch` 中初始化以下数据： + +- **UI 布局数据**：`navBarHeight`、`navBarContentHeight`、`statusBarHeight`、`menuRight`、`menuTop`、`menuHeight`、`safeAreaBottom`、`safeAreaInsetBottom` — 通过 `wx.getMenuButtonBoundingClientRect()` 和 `wx.getWindowInfo()` 计算 +- **平台信息**：`platformInfo` — 通过 `utils/platform.ts` 的 `getPlatformInfo()` 获取，包含 hardware、software、isMobile、isDesktop、isDevtools +- **认证**：`token`（登录成功后由业务代码设置） + +类型定义位于 `typings/index.d.ts` 的 `IAppOption` 接口。 + +### 自定义 TabBar + +- `app.json` 中 `tabBar.custom: true` 启用自定义 TabBar +- 组件位于 `miniprogram/custom-tab-bar/`，基于 TDesign `t-tab-bar` +- TabBar 页面必须在 `onShow` 中调用 `this.getTabBar().init()` 同步激活状态 +- `app.json` 的 `tabBar.list` 和 `custom-tab-bar/index.ts` 的 `data.list` 需保持配置一致 + +### SASS 全局注入 + +`project.config.json` 中通过 `sassSetting` 配置了 `sassCommonUseFilePath: "global.sass"` 和 `scssCommonUseFilePath: "global.scss"`，微信开发者工具会自动将这些全局文件注入每个 SCSS/SASS 文件。当前 miniprogram 根目录下尚无 `global.scss` / `global.sass` 文件，需手动创建后使用。 + +### 无独立构建系统 + +本项目不依赖 Webpack/Vite 等构建工具。TypeScript 和 SASS 编译由微信开发者工具的 SWC 编译器内置完成（`project.config.json` 中 `swc: true`）。ESLint/Prettier 仅用于代码质量检查，不参与编译流程。 + +## 关键约定 + +- **npm 镜像**：`.npmrc` 配置了 npmmirror.com 镜像和 node-sass 二进制镜像 +- **代码风格**：分号关闭、单引号、100 字符宽度、2 空格缩进、LF 换行 +- **ESLint**：`no-console` 为 warn 级别（仅允许 `console.warn` 和 `console.error`），`@typescript-eslint/no-explicit-any` 为 warn +- **路径别名**：无路径别名 — 所有 import 使用相对路径 +- **微信基础库版本**：`libVersion: "3.14.1"`（`project.config.json`），`3.17.0`（`project.private.config.json`） +- **npm 构建模式**：手动模式（`packNpmManually: true`），npm 包输出到 `miniprogram/` 目录 +- **Git 忽略**：`miniprogram/miniprogram_npm/`、`project.private.config.json`、`*.js.map` 等不纳入版本控制 + +## 类型系统 + +全局类型通过 `typings/index.d.ts` 的三斜线指令引入，定义了： + +- `IAppOption` — App 实例类型（含 `globalData` 完整结构） +- `PlatformInfoType` / `HardwarePlatformInfoType` / `SoftwarePlatformInfoType` — 平台信息层级类型 +- `ClientPlatformType` / `OperatingSystemType` / `HardwareDeviceClassType` — 联合类型 +- 微信小程序 API 类型位于 `typings/types/wx/` 目录 diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..43c994c --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1 @@ +@AGENTS.md