Harmony Admin

Harmony Admin 是一个纯前端系统管理台示例项目，基于 React、TypeScript、Vite、Tailwind CSS 和 shadcn/ui 构建。仓库不包含后端服务，默认提供本地演示数据，方便直接预览权限、租户、菜单、审计日志等后台管理界面。

注意：本仓库包含本地演示账号。生产使用前请关闭演示 Mock、接入自己的 API，并完成安全审查。

功能概览

• 用户、角色、权限、租户、菜单、部门、岗位、用户组等管理台页面
• 登录、租户选择、权限守卫、动态菜单等前端流程
• 审计日志、登录日志、文件管理、系统配置、消息中心等界面模块
• 内置演示账号和 mock 数据，开箱可预览主要界面
• API Client 与服务层已集中封装，便于替换为真实 API 服务

技术栈

• Vite
• React 18
• TypeScript
• Tailwind CSS
• shadcn/ui
• TanStack Query
• Vitest + React Testing Library

目录结构

.
├── src/                         # 前端源码
├── public/                      # 静态资源
├── docs/                        # 项目文档
├── .github/                     # GitHub 协作模板与 CI
├── .env.example                 # 本地环境变量示例
├── .env.docker.example          # Docker 环境变量示例
└── README.md

环境要求

• Node.js 22 LTS（CI 标准版本；本地至少使用 Node.js 20+）
• npm 10+（默认使用随 Node 22 提供的 npm 10/11）

当前仓库以 package-lock.json 和 npm 作为唯一默认依赖管理方式，本地和 CI 均使用 npm ci。当前不维护 Bun、pnpm 或 Yarn 工作流。

开始开发前建议确认工具链版本：

node -v
npm -v

快速开始

1. 安装依赖

npm ci

2. 配置环境变量

cp .env.example .env.development

默认启用演示 Mock：

VITE_API_BASE_URL=http://localhost:9080
VITE_ENABLE_DEMO_MOCKS=true

3. 启动前端

npm run dev

默认访问地址为 http://localhost:8080。演示账号：

账号	密码	默认角色	预览重点
admin@example.com	local-demo-admin	租户管理员	用户、角色、菜单、配置、租户设置等管理入口
manager@example.com	local-demo-manager	经理	项目、文件、用户/岗位/用户组只读等协作入口
viewer@example.com	local-demo-viewer	查看者	只读菜单和低权限按钮隐藏效果

这些账号只属于 Demo Mock，本地预览权限由 src/data/mock-data.ts 提供。关闭 VITE_ENABLE_DEMO_MOCKS 后，登录、租户、菜单和权限均依赖接入方提供的外部 API。

接入真实 API

本仓库不提供后端实现。接入真实 API 服务时，关闭演示 Mock 并配置 API 地址：

VITE_API_BASE_URL=https://your-api.example.com
VITE_ENABLE_DEMO_MOCKS=false

前端请求统一从 src/services/apiClient.ts 发起，业务服务位于 src/services/。接口契约参考 docs/FRONTEND_API_CONTRACT.md 和 docs/API_CONTRACT.md。

常用命令

npm ci
npm run lint
npm run typecheck
npm run test
npm run build
npm run preview
npm run security:audit

Docker 本地预览

仓库提供仅包含前端静态站点的 Docker Compose 配置。首次启动前可复制环境变量示例：

cp .env.docker.example .env
docker compose up --build

默认访问地址：

• 前端：http://localhost:8080

Docker 默认开启演示 Mock。若要连接真实 API，请在 .env 中设置 VITE_API_BASE_URL 并把 VITE_ENABLE_DEMO_MOCKS 设为 false。

配置说明

• 本地配置示例：.env.example
• Docker 配置示例：.env.docker.example
• 演示边界：docs/DEMO_BOUNDARY.md
• 前端 API 契约：docs/FRONTEND_API_CONTRACT.md
• 业务模块接入：docs/BUSINESS_MODULE_ONBOARDING.md
• 可观测性边界：docs/OBSERVABILITY.md

不要把真实密钥、真实账号、真实内部地址写入配置文件或文档。新增配置示例时统一使用占位值。

贡献

请阅读 CONTRIBUTING.md。提交前至少运行：

npm ci
npm run lint
npm run typecheck
npm run test
npm run build
npm run security:audit

发布

v1.0 发布版本建议为 v1.0.0。发布流程见 docs/release-process.md。

安全

如果发现安全问题，请不要公开提交 Issue，按 SECURITY.md 的流程报告。

License

Apache License 2.0。详情见 LICENSE。

支持与致谢 / Support

这个项目主要利用业余时间维护，个人精力确实有限，文档和代码如有疏漏还请包涵。

如果你觉得它还不错，或者刚好解决了你的问题，欢迎点个 Star、帮忙转发一下。感谢支持。

This project is mainly maintained in spare time, so documentation and code may occasionally have omissions. Thanks for your understanding.

If you find it useful, or if it happens to solve your problem, a Star or a share would be greatly appreciated. Thank you for your support.