ocean/backend/README.md

项目管理系统后端

依据《产品文档》与《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 中执行：

   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', '<上面输出的哈希>', '市场部', '市场部');

启动服务

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

或进入 src 再启动：

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。