161 lines
5.1 KiB
Markdown
161 lines
5.1 KiB
Markdown
# AI Assistant Instructions for qiming-file-server Project
|
||
|
||
## Project Overview
|
||
|
||
qiming-file-server 是一个跨平台的文件服务部署工具，支持 Windows、Linux、macOS 操作系统，提供 start/stop/restart 命令行操作。
|
||
|
||
## Core Commands
|
||
|
||
```bash
|
||
qiming-file-server start # 启动服务 (默认 env.production)
|
||
qiming-file-server start --env dev # 启动服务 (开发环境)
|
||
qiming-file-server stop # 停止服务
|
||
qiming-file-server restart # 重启服务
|
||
qiming-file-server status # 查看服务状态
|
||
```
|
||
|
||
## Project Structure
|
||
|
||
```
|
||
qiming-file-server/
|
||
├── src/
|
||
│ ├── cli.js # CLI 入口 (跨平台兼容)
|
||
│ ├── server.js # 主服务器
|
||
│ ├── routes/
|
||
│ │ └── router.js # 路由定义 (含 /health 端点)
|
||
│ ├── utils/
|
||
│ │ ├── serviceManager.js # 服务管理 (跨平台)
|
||
│ │ ├── envUtils.js # 环境变量工具
|
||
│ │ ├── build/ # 构建相关工具
|
||
│ │ ├── buildArg/ # 构建参数工具
|
||
│ │ ├── buildDependency/ # 依赖管理
|
||
│ │ ├── buildJudge/ # 构建判断工具
|
||
│ │ ├── buildPermission/ # 权限管理
|
||
│ │ ├── common/ # 公共工具
|
||
│ │ ├── computer/ # 计算机工具
|
||
│ │ ├── error/ # 错误处理
|
||
│ │ └── log/ # 日志工具
|
||
│ ├── appConfig/ # 应用配置 (环境变量等)
|
||
│ ├── config/
|
||
│ │ └── swagger/ # Swagger 文档配置
|
||
│ ├── env.development # 开发环境配置
|
||
│ ├── env.production # 生产环境配置
|
||
│ └── env.test # 测试环境配置
|
||
├── scripts/
|
||
│ ├── start-prod.js # 生产环境启动脚本
|
||
│ ├── start-dev.js # 开发环境启动脚本
|
||
│ └── pnpm-check.sh # pnpm 检查脚本
|
||
├── tests/ # 测试文件
|
||
└── package.json # 项目配置
|
||
```
|
||
|
||
## Key Implementation Details
|
||
|
||
### 1. Cross-Platform Compatibility
|
||
|
||
所有代码必须支持 Windows、Linux、macOS：
|
||
|
||
- **路径处理**: 使用 `path.join()`, `path.resolve()`, `os.tmpdir()`, `os.homedir()`
|
||
- **进程管理**: 使用 `tree-kill` 杀进程组，Windows 使用 `taskkill`，Linux/macOS 使用 `kill` 信号
|
||
- **命令执行**: 使用 `cross-spawn` 执行 shell 命令
|
||
- **文件操作**: 使用 `fs-extra` 增强文件系统操作
|
||
|
||
### 2. Environment Configuration
|
||
|
||
- 环境变量优先级: 命令行参数 > 环境变量文件 > 默认值
|
||
- 支持通过 `--env` 参数指定环境 (development/production/test)
|
||
- 支持通过 `--env-file` 指定自定义配置文件
|
||
- 配置通过 `src/appConfig/index.js` 统一管理，环境文件位于 `src/env.*`
|
||
|
||
### 3. CLI Design
|
||
|
||
- 使用 `commander.js` 解析命令行参数
|
||
- 命令结构: `qiming-file-server <command> [options]`
|
||
- 支持的命令: start, stop, restart, status
|
||
- 全局选项: `--env`, `--port`, `--config`, `--help`
|
||
|
||
### 4. Health Check Endpoint
|
||
|
||
健康检查端点位于 `/health`，返回格式:
|
||
|
||
```json
|
||
{
|
||
"status": "ok",
|
||
"timestamp": 1738600000000,
|
||
"uptime": 3600,
|
||
"version": "1.0.0",
|
||
"platform": "darwin"
|
||
}
|
||
```
|
||
|
||
### 5. Service Management
|
||
|
||
- PID 文件存储在临时目录 (`os.tmpdir()`)
|
||
- 启动时检查服务是否已运行
|
||
- 停止时支持优雅退出 (30秒超时)
|
||
- 重启组合 stop + start 操作
|
||
|
||
## Development Guidelines
|
||
|
||
### Code Style
|
||
|
||
- 使用中文注释（根据项目规则）
|
||
- 函数必须添加 JSDoc 注释
|
||
- 跨平台代码必须包含平台检测逻辑
|
||
- 错误处理必须包含详细日志
|
||
|
||
### Testing
|
||
|
||
- 单元测试放置在 `tests/unit/` 目录
|
||
- 测试框架使用 Jest
|
||
- 关键函数必须编写单元测试
|
||
|
||
### Logging
|
||
|
||
- 使用 `src/utils/log/logUtils.js` 中的 `log()` 函数
|
||
- 日志级别: error, warn, info, debug
|
||
- 日志文件按日期分割，存储在 `LOG_BASE_DIR`
|
||
|
||
## Common Tasks
|
||
|
||
### Adding a New Route
|
||
|
||
1. 在 `src/routes/` 目录下创建新的路由文件
|
||
2. 在 `router.js` 中挂载路由
|
||
3. 添加相应的服务逻辑到 `src/service/` 目录
|
||
|
||
### Adding a New CLI Command
|
||
|
||
1. 在 `src/cli.js` 中使用 `commander` 定义命令
|
||
2. 在 `src/utils/serviceManager.js` 中实现服务逻辑
|
||
3. 更新 `README.md` 文档
|
||
|
||
### Modifying Configuration
|
||
|
||
1. 在 `src/env.production` / `src/env.development` / `src/env.test` 中添加环境变量
|
||
2. 在 `config/index.js` 中读取配置
|
||
3. 更新 `README.md` 文档
|
||
|
||
## Build and Deploy
|
||
|
||
```bash
|
||
# 开发环境运行
|
||
npm run dev
|
||
|
||
# 生产环境运行
|
||
npm run prod
|
||
|
||
# 运行测试
|
||
npm run test
|
||
|
||
# 发布到 npm
|
||
npm publish
|
||
```
|
||
|
||
## Important Notes
|
||
|
||
- 所有平台相关代码必须使用条件判断 (`process.platform`)
|
||
- 避免使用 Unix 特定命令（grep, sed, awk 等）
|
||
- Windows 环境使用 `cross-spawn` 执行命令
|
||
- 确保日志目录有写入权限
|