# 项目管理系统后端

依据《产品文档》与《API 文档》，Python + FastAPI 实现，数据持久化到 MySQL（ocean 库）。

## 目录结构

```
backend/
├── src/                  # 后端源码
│   ├── __init__.py
│   ├── app.py            # FastAPI 应用与路由
│   ├── config.py         # 配置（环境变量）
│   ├── database.py       # MySQL 连接
│   ├── auth.py           # 登录、Token 校验
│   └── projects_repo.py  # 项目与操作日志数据层
├── tests/                # 测试（由测试工程师维护）
├── schema.sql            # 数据库表结构
├── .env.example          # 环境变量示例
├── requirements.txt
└── API.md
```

## 环境与数据库

1. 复制 `.env.example` 为 `.env`，按本地 MySQL 填写 `MYSQL_*`。
2. 执行 `schema.sql` 创建数据库 `ocean` 及表（users、projects、operation_logs）。**若已有 projects 表**，需补加四个日期原文列：见下方「数据库迁移」。
3. **首次使用**：在 `users` 表中插入至少一个用户；`password_hash` 需用 bcrypt 哈希。可在 Python 中执行：
   ```python
   from app.auth import hash_password
   print(hash_password("你的密码"))  # 将输出写入 INSERT 语句
   ```
   示例 SQL：`INSERT INTO users (id, username, password_hash, role, display_name) VALUES ('user-1', 'market', '<上面输出的哈希>', '市场部', '市场部');`

## 启动服务

```bash
cd backend
source .venv/bin/activate
PYTHONPATH=src uvicorn app:app --reload --host 0.0.0.0 --port 8000
```

或进入 `src` 再启动：

```bash
cd backend/src
uvicorn app:app --reload --host 0.0.0.0 --port 8000
```

## 功能说明

- **认证**：`POST /api/auth/login` 校验 users 表账号密码，签发 token（内存存储）；后续请求头 `Authorization: Bearer <token>`。
- **项目列表**：分页，支持按项目名称/合同编号搜索（searchType + keyword）、按进度/费用筛选（progress、cost）、时间筛选（dateFilterType + dateFrom/dateTo，仅对「日期正常」项目）、日期异常筛选（dateAbnormal 为 true 时只返回日期异常项目）。
- **项目详情/新建/更新**：与 API 文档一致；新建仅市场部；更新时写入 operation_logs。
- **操作日志**：按项目 id 分页查询，含操作人、时间、修改摘要。

## 数据库迁移（已有 projects 表时）

1. **日期原文列**（若无）：执行 `PYTHONPATH=src python scripts/migrate_add_date_str_columns.py`，或执行 README 中「增加四个 _str 列」的 SQL。
2. **三列改为字符串**（质保期截止日、中标合同金额、工程款拨付方式）：执行 `PYTHONPATH=src python scripts/migrate_string_columns.py`。