# pythonstyle-vue

**Repository Path**: chinacsj123/pythonstyle-vue

## Basic Information

- **Project Name**: pythonstyle-vue
- **Description**: PythonStyle是一个企业级开发框架，采用MVC架构，统一入口，自动实现访问路由。内置模块包含：用户管理、部门管理、角色管理、菜单及按钮授权、日志管理、登录模块等。
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 13
- **Forks**: 3
- **Created**: 2025-01-16
- **Last Updated**: 2026-07-21

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# PyCodev Vue3 v2.0

PyCodev 是一个面向企业后台场景的 Python 全栈开发框架，当前版本由 `ASGI + Uvicorn` 后端和 `Vue 3 + Element Plus` 管理端组成。

项目默认聚焦四类框架能力：
- 系统管理
- 系统监控
- 流程管理
- 表单管理

## 核心特性

- 保留 `m/c/a` 开发组织方式，便于继续扩展后台业务模块
- 后端统一返回结构、统一配置加载、统一权限控制链路
- 内置登录认证、菜单权限、验证码、操作日志、登录日志、定时任务
- 提供流程定义、流程运行时、表单设计、表单数据管理基础能力
- 支持 MySQL、Redis、任务调度、多环境配置与迁移脚本管理

## 相关文档

- 错误码说明：[doc/error-codes.md](D:\python_workspace\pycodev-vue3-v2.0\doc\error-codes.md)
- 商业化路线图：[doc/商业化路线图.md](D:\python_workspace\pycodev-vue3-v2.0\doc\商业化路线图.md)

## 目录结构

```text
.
├── main.py
├── scheduler_main.py
├── pycodev/
├── resources/
├── vue/
├── doc/
├── tools/
├── static/
├── logs/
├── artifacts/
├── requirements.txt
└── gunicorn_run.sh
```

后端主目录说明：

```text
pycodev/
├── app.py
├── core/
├── libs/
├── common/
├── model/
├── config/
└── modules/
    ├── flow/
    ├── form/
    ├── monitor/
    ├── system/
    └── test/
```

前端主目录说明：

```text
vue/src/
├── api/
├── assets/
├── components/
├── directive/
├── layout/
├── router/
├── stores/
├── utils/
└── views/
    ├── flow/
    ├── form/
    ├── monitor/
    ├── system/
    ├── login.vue
    ├── register.vue
    └── index.vue
```

## 环境要求

- Python 3.10+
- Node.js 18+
- MySQL 8+
- Redis 6+（推荐）

## 后端启动

安装依赖：

```bash
pip install -r requirements.txt
```

直接启动：

```bash
python main.py
```

或使用 Uvicorn：

```bash
python -m uvicorn main:app --host 127.0.0.1 --port 8081
```

独立启动调度器：

```bash
python scheduler_main.py
```

## 前端启动

```bash
cd vue
npm install
npm run dev
```

生产构建：

```bash
cd vue
npm run build
```

## 配置说明

主要配置文件位于 `resources/`：

- `application.yml`
- `application-dev.yml`
- `application-ci.yml`
- `application-loadtest.yml`
- `application-pro.yml`
- `application-pro.example.yml`

默认开发库配置位于 [resources/application-dev.yml](D:\python_workspace\pycodev-vue3-v2.0\resources\application-dev.yml)。

## 数据迁移

查看待执行迁移：

```bash
python tools/run_migrations.py --profile dev --dry-run
```

执行迁移：

```bash
python tools/run_migrations.py --profile dev
```

## 常用检查

语法检查：

```bash
python -m py_compile main.py scheduler_main.py
```

乱码与编码检查：

```bash
python tools/check_mojibake.py
python tools/check_text_encoding.py
python tools/check_business_exception_usage.py
```

## 开发约束

- Python 使用 4 空格缩进
- 文件名、模块名使用 `snake_case`
- 后端接口统一通过 `Result.success()` / `Result.error()` 返回
- 简单 CRUD 可以继续放在 `pycodev/modules/<domain>/controller` + `entity`
- 模块可按需增加 `service` 层，默认仍以 `controller` + `entity` 为主，复杂业务再引入 `service`
- 跨模块复用的通用能力优先沉淀到 `pycodev/libs/`，不要把某个页面或模块的专属业务硬塞进 `libs/`
- 当前前端接口目录保留 `vue/src/api/sysetm/` 这一既有拼写以兼容旧代码

## 后端分层约定

- `controller`：负责收参、登录态/权限入口校验、调用业务层、返回 `Result`
- `entity`：负责 ORM、基础 CRUD、分页查询、简单数据映射
- `service`：负责业务编排、复杂校验、状态流转、事务控制、跨实体聚合
- `error_codes.py`：按模块维护业务错误码常量，供 `controller` / `service` 引用，避免在业务代码里散写数字错误码
- 单表分页、单表详情、单表增删改、简单状态切换等场景，可以不强制新增 `service`
- 涉及多表写入、缓存/Redis、上传、调度器、日志、权限上下文、发布/审核/统计等流程时，应优先引入 `service`
- `service` 不能只是对 `entity` 的空转发；没有实际业务编排价值时不要为分层而分层

### 推荐模式

- 简单场景：`controller -> entity`
- 复杂业务场景：`controller -> service -> entity`
- 跨模块基础能力场景：`controller/service -> libs`

### 必须进入 `service` 的场景

- 一次操作需要同时写入多个实体或多张表
- 一次操作涉及 Redis、上传、定时任务、权限缓存、登录态、日志等协同处理
- 存在发布、审核、启停、撤回、归档、统计、同步等状态流转
- 同一段业务后续需要被接口、定时任务、内部任务或其他模块复用
- 控制器中已经出现明显的多段校验、分支编排、异常处理、数据聚合

### `service` 编写示例

```python
from pony.orm import db_session

from pycodev.libs.business_exception import BusinessException
from pycodev.modules.system.entity.user import UserEntity
from pycodev.modules.system.entity.user_role import UserRoleEntity


class UserService:
    @staticmethod
    @db_session
    def add_user(params):
        if not params.get("role_ids"):
            raise BusinessException(code=202, msg="请选择用户角色")

        user_id = UserEntity.add_data(params)
        if not user_id:
            raise BusinessException(code=201, msg="操作失败")

        UserRoleEntity.replace_user_roles(user_id, params["role_ids"])
```

事务边界约定：
- 推荐把 `db_session` 放在 `service` 方法上，由 `service` 统一控制多表写入事务。
- `entity` 继续负责 ORM 和基础读写，不承担完整业务编排。
- 上传、HTTP 调用、远程代理、长时间计算不要整段包进同一个 `db_session`；这类操作应先完成外部动作，再进入必要的数据库写入阶段。
- 为兼容旧接口，控制器方法名可以保留历史拼写；新增内部实现和新增入口优先使用规范命名，例如 `run_once_task` 优于 `run_onece_task`。

### 禁止事项

- 不要把复杂业务流程继续堆在 `controller`
- 不要让 `entity` 同时承担 ORM、查询组装和完整业务规则
- 不要把 `service` 写成仅一行调用 `entity` 的空转发层
- 不要把某个模块专属的页面业务逻辑下沉到 `libs/`

## 异常约定

- `BusinessException` 是后端可预期业务错误的统一异常类型，至少包含 `code`、`msg`、`data`
- `controller` 和 `service` 中遇到参数缺失、登录态失效、权限不足、业务状态不满足等可预期错误时，优先 `raise BusinessException(...)`
- 全局入口会统一把 `BusinessException` 转成 `Result.error(...)`，控制器里不要重复包一层相同的错误返回
- 成功响应仍然使用 `Result.success(...)`
- 底层未知异常、系统异常、第三方异常不要强行伪装成业务成功，继续交给全局兜底处理
- 错误码采用“通用框架码 + 模块业务码号段”两级体系，`1xxx` 认证域已正式启用，独立说明见 [doc/error-codes.md](D:\python_workspace\pycodev-vue3-v2.0\doc\error-codes.md)
- 模块业务码优先定义在各模块自己的 `error_codes.py` 中，例如 `pycodev/modules/system/error_codes.py`，不要继续在业务代码里散写 `3101/4102/5108` 这类数字
- 模块内引用业务码时，优先使用 `from pycodev.modules.<module> import codes as <module>_codes` 这一统一导入方式
- 新增业务异常时优先使用 `BusinessException` 工厂方法；提交前建议执行 `python tools/check_business_exception_usage.py`，校验业务异常写法、`error_codes.py` 常量声明、错误码文档登记与模块号段归属

## 部署建议

推荐使用：

- `Nginx`
- `Gunicorn + UvicornWorker`
- `MySQL`
- `Redis`

相关部署模板位于 `tools/deploy/`。