# Repository Guidelines

## 项目结构与模块组织

- `src/` 存放核心前端代码：`pages/` 管理业务页面（登录、用户管理、个人信息），`components/` 复用组件，`api/` 与后端交互封装，`store/` 保存全局设置与标签页状态，`utils/` 管理工具函数，`mock/` 仅在本地调试启用。
- `docs/` 收录 API 对接与集成报告，提交前务必同步更新。
- `dist/` 为 `pnpm run build` 产物，禁止手动修改；`.env.*` 提供环境变量，请按需复制调整。

## 构建与开发命令

| 命令                                     | 说明                                                      |
| ---------------------------------------- | --------------------------------------------------------- |
| `pnpm install`                           | 安装依赖，项目首选 pnpm（若使用 npm，需同步更新锁文件）。 |
| `pnpm run dev`                           | 启动 Vite 开发服务器，默认走 `/api` 代理到本地 8080。     |
| `pnpm run build`                         | 生成产物到 `dist/`，用于联调或上线前校验。                |
| `pnpm run preview`                       | 以本地静态服务验证构建结果。                              |
| `pnpm run eslint` / `pnpm run stylelint` | 校验并自动修复 TS/TSX 与 Less。                           |
| `pnpm run pre-commit`                    | 执行 pretty-quick、ESLint、Stylelint，PR 前必跑。         |

## 编码风格与命名

- 语法统一使用 TypeScript + React 17 Hooks，目录与文件采用小写连字符（示例：`user-management`）。
- ESLint 继承 `plugin:@typescript-eslint/recommended` 与 `plugin:react-hooks/recommended`；Prettier 约定 2 空格缩进、单引号、强制分号。
- 样式使用 Less + CSS Modules，遵循 `.module.less` 命名，Stylelint 规则在 `.stylelintrc` 中定义。

## 测试指引

- 当前仓库尚未集成自动化测试；提交复杂功能时，需给出手工测试步骤，并优先在 `src/__tests__`（或相应页面目录）补充 `*.spec.tsx`。
- 覆盖重点：核心表单（登录、用户管理）与 API 适配层，可借助 Jest + @testing-library/react；命名遵循 `模块名.行为.spec.tsx`。

## 提交与 PR 规范

- Commit 信息遵循 `type(scope): 描述`，与现有记录（如 `feat(布局): ...`、`style(导航栏): ...`）保持一致，描述使用简体中文。
- Pull Request 需包含：变更摘要、关联 Issue/需求编号、截图或命令输出、测试与 lint 结果；若改动 API 或配置，同步更新 `docs/` 与 `.env.*` 示例。

## 安全与配置提示

- `.env.development` 默认将 `VITE_API_BASE_URL` 指向 `/api`，生产环境务必更新为真实网关地址，避免调试代理泄漏。
- Mock 入口在 `src/main.tsx` 引入，如需生产构建剔除，可通过环境变量包装 `import './mock'`，防止将虚拟数据发布到线上。