# 墨石记服务端 (Moshiji Service)

一个基于 Cool Admin Midway 框架开发的现代化后端服务系统，提供完整的权限管理、用户管理、任务调度等功能。

## 🚀 技术栈

- **框架**: [Midway.js](https://midwayjs.org/) + [Koa.js](https://koajs.com/)
- **数据库**: MySQL + TypeORM (0.3.20版本)
- **语言**: TypeScript + JavaScript
- **权限管理**: Cool Admin 权限系统
- **任务调度**: Cron + Bull Queue
- **文件上传**: Midway Upload
- **API文档**: Swagger
- **缓存**: Cache Manager

## 📋 系统要求

- Node.js >= 18.0.0
- MySQL 5.7+
- TypeScript 5.8+

## 🏗️ 项目结构

```
moshiji_service/
├── src/
│   ├── comm/                    # 通用工具库
│   ├── config/                  # 配置文件
│   │   ├── config.default.ts    # 默认配置
│   │   ├── config.local.ts      # 本地开发配置
│   │   └── config.prod.ts       # 生产环境配置
│   ├── modules/                 # 业务模块
│   │   ├── base/                # 基础权限管理模块
│   │   │   ├── controller/      # 控制器
│   │   │   ├── entity/          # 实体类
│   │   │   ├── service/         # 服务层
│   │   │   ├── middleware/      # 中间件
│   │   │   └── dto/            # 数据传输对象
│   │   ├── user/                # 用户管理模块
│   │   ├── dict/                # 字典管理模块
│   │   ├── task/                # 任务调度模块
│   │   ├── plugin/              # 插件管理模块
│   │   ├── space/               # 空间管理模块
│   │   ├── recycle/             # 回收站模块
│   │   ├── demo/                # 示例模块
│   │   └── swagger/             # API文档模块
│   ├── configuration.ts         # Midway配置
│   └── interface.ts             # 类型声明
├── public/                      # 静态资源
├── test/                        # 测试文件
├── typings/                     # 类型定义
├── bootstrap.js                 # 生产环境启动文件
└── package.json                 # 项目依赖
```

## 🛠️ 安装与运行

### 1. 安装依赖

```bash
npm install
```

### 2. 环境配置

复制并修改配置文件：

```bash
# 本地开发环境
cp src/config/config.local.ts.example src/config/config.local.ts

# 生产环境
cp src/config/config.prod.ts.example src/config/config.prod.ts
```

### 3. 数据库配置

在配置文件中设置数据库连接信息：

```typescript
// src/config/config.local.ts
export default {
  typeorm: {
    dataSource: {
      default: {
        type: 'mysql',
        host: 'localhost',
        port: 3306,
        username: 'root',
        password: 'password',
        database: 'moshiji_service',
        synchronize: true,
        logging: true,
      },
    },
  },
};
```

### 4. 运行项目

```bash
# 开发环境
npm run dev

# 生产环境
npm run start

# 构建项目
npm run build

# 运行测试
npm run test
```

## 📚 主要功能模块

### 基础权限管理 (base)
- 用户管理
- 角色管理
- 部门管理
- 菜单管理
- 权限控制
- 系统参数配置

### 用户管理 (user)
- 用户信息管理
- 地址管理
- 微信集成
- 短信服务

### 字典管理 (dict)
- 字典类型管理
- 字典数据管理

### 任务调度 (task)
- 定时任务管理
- 任务队列
- 任务日志

### 插件管理 (plugin)
- 插件中心
- 文件上传
- 插件钩子

### 空间管理 (space)
- 空间信息管理
- 空间类型管理

## 🔧 开发规范

### 代码规范
- 使用 TypeScript 进行开发
- 遵循 ESLint 代码规范
- 使用 Prettier 格式化代码

### 命名规范
- 文件名使用下划线命名法：`user_info.entity.ts`
- 类名使用大驼峰命名法：`UserInfo`
- 变量和函数使用小驼峰命名法：`userName`
- API 接口使用驼峰命名法：`/userInfo` 而不是 `/user/info`

### 数据库规范
- 使用 TypeORM 进行数据库操作
- 不使用外键关系（@ManyToOne、@OneToMany等）
- Entity 字段使用驼峰命名
- 统计查询可考虑使用原生 SQL

## 🚀 部署

### Docker 部署

```bash
# 构建镜像
docker build -t moshiji-service .

# 运行容器
docker run -d -p 7001:7001 --name moshiji-service moshiji-service
```

### PM2 部署

```bash
# 启动服务
npm run pm2:start

# 停止服务
npm run pm2:stop
```

## 📖 API 文档

启动项目后，访问以下地址查看 API 文档：

- Swagger UI: `http://localhost:7001/swagger-ui/index.html`
- API 文档: `http://localhost:7001/api-docs`

## 🤝 贡献指南

1. Fork 本仓库
2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 打开 Pull Request

## 📄 许可证

本项目采用 MIT 许可证 - 查看 [LICENSE](LICENSE) 文件了解详情。

## 📞 联系方式

- 项目主页: [https://cool-js.com](https://cool-js.com)
- 问题反馈: [Issues](https://github.com/your-repo/issues)

---

**注意**: 本项目基于 Cool Admin Midway 框架开发，版本 8.x。请确保按照框架规范进行开发。
