# sc-payroll

**Repository Path**: ericlyr/sc-payroll

## Basic Information

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

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-23
- **Last Updated**: 2026-06-23

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 算薪系统 (Payroll System)

面向汽车经销商集团的自建薪资核算系统，替代手工 Excel，支持多品牌、多区域、复杂提成规则、多周期发放、多银行打款的全链路管理。

## 技术栈

| 层级 | 技术 |
|------|------|
| 后端 | FastAPI (Python 3.11+) + SQLAlchemy 2.0 |
| 数据库 | PostgreSQL 15 |
| 缓存/队列 | Redis 7 + Celery |
| 前端 | Vue 3 + Element Plus |
| 部署 | Docker Compose |

## 快速开始

```bash
# 1. 复制环境变量
cp .env.example .env

# 2. 启动基础设施
docker-compose up -d

# 3. 安装依赖
pip install -r requirements.txt

# 4. 创建数据库表
alembic upgrade head

# 5. 启动开发服务器
uvicorn app.main:app --reload
```

访问 `http://localhost:8000/docs` 查看 API 文档。

## 项目结构

```
payroll-system/
├── app/
│   ├── api/v1/          # API 路由
│   ├── core/            # 基础设施（配置/数据库/认证/任务队列）
│   ├── domain/
│   │   ├── enums.py     # 所有枚举定义
│   │   └── models/      # SQLAlchemy 模型（35个实体）
│   ├── engine/          # 业务引擎（核算/审批/发放/报盘/报表/工资单）
│   ├── schemas/         # Pydantic 请求/响应模型
│   ├── services/        # 领域服务（方案匹配/个税社保/外部集成客户端）
│   └── utils/           # 工具函数
├── docs/                # 设计文档
│   ├── 01_er_diagram.puml         # ER 图（PlantUML）
│   ├── 02_architecture.md         # 架构设计
│   ├── 03_api_design.md           # API 设计
│   ├── 04_cursor_implementation.md # Cursor 实现指引（核心）
│   ├── 05_startup_prompt.md       # 启动提示
│   └── 06_user_and_auth.md        # 用户认证

## 实现顺序

按 Phase 1→5 依次实现，详见 `docs/04_cursor_implementation.md`：

1. **Phase 1** — 基础设施 + 领域模型 + CRUD
2. **Phase 2** — 核心业务引擎（方案匹配/提成核算/KPI/发放策略）
3. **Phase 3** — 流程引擎（审批/发放状态机/报盘）
4. **Phase 4** — 外部集成（工资单/考勤/银行/金蝶/企微）
5. **Phase 5** — 报表 + Vue 3 前端

## 核心业务能力

- **复杂提成规则** — 7步执行流程（防护→基数→量调→多维→KPI→扣罚→限界），结构化 IR 中间表示
- **审批流引擎** — 可配置审批链、触发规则、部分驳回、催办转审
- **发放状态机** — 6个 Phase 全生命周期管理
- **多银行报盘** — 按银行分组、文件导出、API 打款、换卡重发
- **一人多薪** — 多任职/多发薪关系/多岗位
- **多周期发放** — 月/季/半年/年度及中间值策略

## 编码规范

见 `.cursorrules` 文件。关键约束：

- 金额一律使用 `decimal.Decimal` + SQL `Numeric(12, 2)`
- ORM 使用 SQLAlchemy 2.0 Mapped 注解风格
- 所有模型 UUID 主键 + `created_at`/`updated_at` 时间戳
- API 路由在 `app/api/v1/` 下按模块拆分
- 业务逻辑在 `app/engine/` 和 `app/services/`，禁止写在路由中