docs: 添加AGENTS.md和CLAUDE.md用于代理配置
添加文档文件，为在此仓库中工作的AI编码代理提供上下文和指令。这些文件描述了项目结构、命令、架构决策和关键约定。
This commit is contained in:
熊熊熊子路 committed
1 parent
99e49ef286
commit
3f75ab4ef6
2 files changed
+125
No files matched your search
@@ -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<T>）
|
||||
├── 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<T>` 结构（`{ 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/` 目录
|
||||
Reference in new issue
Block a user