# moonshotLibrary

**Repository Path**: kugong/moonshot-library

## Basic Information

- **Project Name**: moonshotLibrary
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2025-11-14
- **Last Updated**: 2026-03-24

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Moonshot Library System

面向校园的前后端分离图书馆管理系统，覆盖图书管理、借阅流程、收藏与信用管理，并提供可选的 Microsoft 365 SSO 登录。

- 前端：Vue 3 + Vite + TypeScript（位于 `frontend/`）
- 后端：Express.js + TypeScript + SQLite（位于 `backend/`）

---

## ⚠️ 开发前必读

1. AI/自动化助手必读：`README-BEFORE-DEV-EN.md`
2. 中文开发规范：`Documentation/README-BEFORE-DEV-CN.md`
3. 英文开发速查：`Documentation/DEV-QUICK-REFERENCE-EN.md`
4. UI 交付与对齐：`Documentation/UI-HANDOFF-CN.md`

---

## 目录结构

```
moonshot-library/
├── frontend/              # 前端应用
├── backend/               # 后端 API
├── Documentation/         # 设计/复盘/交付文档
├── nginx/                 # Nginx 配置模板
├── deploy.sh              # 部署脚本
├── start-dev.sh           # 本地一键启动
├── ecosystem.config.js    # PM2 配置
└── readme.md              # 本文件
```

---

## 主要功能（现状）

- 账号与认证：注册/登录、JWT + Refresh Token、可选 M365 SSO（后端重定向）
- 图书管理：CRUD、分类、Excel/CSV 批量导入、封面上传
- 借阅流程：借阅/归还/续借、逾期检查、借阅上限
- 收藏与信用：收藏列表、信用分与恢复规则
- 管理端：图书/借阅/用户管理（公告与评论管理为前端本地数据）

> 注：社区动态、公告、评分/评论目前为前端 localStorage 模拟数据，后端暂无对应接口。

---

## 快速开始

### 环境要求
- Node.js 20+（前端引擎要求）
- npm

### 方式 A：一键启动（推荐）
```bash
./start-dev.sh
```
脚本会自动复制 `.env` 模板、安装依赖并启动前后端。

### 方式 B：手动启动
```bash
# 前端
cd frontend
npm install
npm run dev    # http://localhost:5173

# 后端（新库建议先初始化数据）
cd backend
npm install
npm run init-db
npm run dev    # http://localhost:3000
```

### 示例账号（init-db 后可用）
- student@example.com / password123
- teacher@example.com / password123
- librarian@example.com / password123

---

## 环境变量

模板文件：
```
backend/.env.example  -> backend/.env
frontend/.env.example -> frontend/.env.local
```

常用配置（后端）：
- `PORT`：后端端口（默认 3000）
- `FRONTEND_URL`：前端地址（CORS 与 M365 回调）
- `JWT_SECRET` / `REFRESH_TOKEN_SECRET` / `SESSION_SECRET`：生产环境必须设置强密钥
- `DB_PATH`：SQLite 路径（默认 `./database/library.db`）
- `MSAL_*`：M365 SSO 配置（可选）

---

## 常用命令

| 位置 | 命令 | 说明 |
|------|------|------|
| frontend/ | `npm run dev` | 启动前端开发服务器 |
| frontend/ | `npm run dev:all` | 同时启动前端 + 后端 |
| frontend/ | `npm run build` | 构建前端（含 type-check） |
| frontend/ | `npm run type-check` | 类型检查 |
| frontend/ | `npm run lint` | ESLint（自动修复） |
| backend/ | `npm run dev` | 启动后端（热重载） |
| backend/ | `npm run init-db` | 初始化数据库并填充示例数据 |
| backend/ | `npm run build` | 编译后端 |
| backend/ | `npm test` | 运行脚本化 API 测试 |
| 根目录 | `./start-dev.sh` | 一键启动前后端 |
| 根目录 | `./deploy.sh deploy` | 部署（PM2/Nginx） |

---

## API 与健康检查

- API 基础地址：`http://localhost:3000/api`
- Swagger UI：`http://localhost:3000/api-docs`
- 健康检查：`http://localhost:3000/health`

---

## 前端路由与部署说明

- 图书详情规范前端路由为 `/:id`（仅匹配 `bk-` 前缀图书 ID）。
- 为兼容旧链接，前端同时接受 `/books/:id`，进入后会重定向到 `/:id`。
- 前端生产构建使用根路径静态资源 `/assets/*`。这要求站点从域名根目录提供前端产物，并保留 Nginx 的 `try_files $uri $uri/ /index.html;` 配置，避免刷新详情页时白屏。

---

## 用户角色

| 角色 | 说明 |
|------|------|
| student | 学生 - 浏览图书、借阅 |
| teacher | 教师 - 浏览图书、借阅 |
| librarian | 图书管理员 - 管理图书、用户、借阅 |

> 说明：代码中保留 `admin` 角色的权限分支，但数据库约束与默认账号仅包含上述三类。

---

## 文档索引

- **后端 API**：`backend/API_DOCUMENTATION.md`
- **前端概览**：`Documentation/FRONTEND_OVERVIEW.md`
- **开发规范（CN）**：`Documentation/README-BEFORE-DEV-CN.md`
- **开发速查（EN）**：`Documentation/DEV-QUICK-REFERENCE-EN.md`
- **M365 SSO 配置**：`Documentation/M365_AUTH_SETUP.md`
- **收藏与信用参考**：`Documentation/FAVORITES_AND_CREDIT_REFERENCE.md`

---

## 常见问题

### 端口被占用
```bash
lsof -i :3000
lsof -i :5173
```

### CORS 错误
确保 `backend/.env` 中的 `FRONTEND_URL` 与前端实际地址一致。

### 数据库重置
```bash
cd backend
rm -f database/library.db
npm run init-db
```

---

欢迎把 Moonshot Library 部署到校园环境继续打磨！ 🚀