# begin-pms

**Repository Path**: yangsj/begin-pms

## Basic Information

- **Project Name**: begin-pms
- **Description**: 项目管理
- **Primary Language**: Python
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-10
- **Last Updated**: 2026-10-19

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Begin PMS（第一期 M0+M1 已落地）

Django 5 + DRF + MySQL（begin_pms）+ 连接池，模块化 `apps/` 结构，暂无 Redis；前端 Vue3 + Vite（`frontend/`）。

## 本地启动

后端：

```bash
python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements/dev.txt
# MySQL：直接用系统已有实例（127.0.0.1:3306，库名 begin_pms），无需 Docker 起库
# 设置 DB_USER（用户名）和 DB_PWD（密码）；旧变量 BEGIN_DB / DB_PASSWORD / BEGIN_DB_PWD 仍兼容
python manage.py migrate
python manage.py createsuperuser
python manage.py runserver
```

前端（另开终端）：

```bash
cd frontend
npm install
npm run dev      # 开发热更新，http://localhost:5173，/api 自动代理到 127.0.0.1:8000
npm run build    # vue-tsc 类型检查 + 生产构建，产出 frontend/dist/
```

### 编译模式：只启动后端

前端 `npm run build` 后，产物由 whitenoise 挂在站点根路径，**只跑后端即可同时服务页面与 API**：

```bash
python manage.py runserver   # 打开 http://127.0.0.1:8000/pms/ 即是前端页面
```

- 页面路由（/pms/login、/pms/projects…）由 pms_spa 视图返回 `dist/index.html`；旧根路径（/login）302 到 /pms/ 等价地址
- 静态资源（/pms/assets/*）由同一视图从 dist 提供（带 MIME/Etag）
- 改前端代码后需重新 `npm run build`；开发时想热更新仍用 `npm run dev`
- ⚠️ 生产部署（DEBUG=False）时 admin/DRF 静态文件需先 `python manage.py collectstatic`

## 测试与检查

```bash
pytest          # 测试跑在同引擎 MySQL（自动创建 test_begin_pms，无需手动准备）
ruff check .
```

## API 一览（/api/v1/）

| 端点 | 说明 |
|---|---|
| `POST /api/v1/auth/token/` | 登录获取 JWT（access/refresh） |
| `POST /api/v1/auth/token/refresh/` | 刷新 access token |
| `/api/v1/projects/` | 项目 CRUD（负责人/参与项目可见；支持 `?status=&search=&ordering=`） |
| `/api/v1/applications/` | 应用登记（`?project=&is_active=`） |
| `/api/v1/project-members/` | 项目成员管理（`?project=&role=`） |
| `GET /api/health/` | 健康检查（含 DB 连通性） |

通用参数：`page`、`page_size`（≤100）。

## 前端结构（frontend/）

```text
frontend/src/
├── api/        # http.ts（axios 实例：Bearer 注入 + 401 自动刷新重放）+ 按领域拆分的接口模块
├── stores/     # Pinia：auth（登录态/用户名）
├── router/     # 路由 + 登录守卫（未登录重定向 /login，带 redirect 回跳）
├── layouts/    # MainLayout（侧边导航，M2/M3 入口占位）
├── views/      # Login / Dashboard / Projects / Applications / 404
├── types/      # 与 DRF 序列化器对齐的 TS 类型
└── styles/     # 全局样式（无重型 UI 库，gzip 总计约 66KB）
```

## 架构约定

```mermaid
flowchart TD
    A[config/ 工程配置<br/>settings: base/dev/prod/test] --> B[apps/users<br/>自定义用户 + JWT]
    A --> C[apps/projects<br/>Project / Application / ProjectMember]
    B --> D[apps/common<br/>TimeStamped / 分页 / 健康检查]
    C --> D
    A --> E[(MySQL begin_pms<br/>连接池 dj-db-conn-pool)]
```

- **模块化**：`apps/<领域>/`（models/serializers/views/permissions/tests），新增领域复制该结构即可。
- **扩展性**：settings 按 base/dev/prod/test 拆分 + 环境变量注入；API 版本化 `/api/v1/`；自定义 User 从第一天启用。
- **高性能**：MySQL 连接池（POOL_SIZE/MAX_OVERFLOW/RECYCLE 可配）+ `CONN_MAX_AGE`；列表 `select_related` + 聚合注解避免 N+1；统一分页上限；常用过滤字段建索引。
- **权限**：平台角色（User.role）与项目内角色（ProjectMember.role）解耦；写操作限负责人/项目管理员/平台管理员。