# 中科兴皖后端

Python 3.9 + FastAPI + SQLAlchemy + Pydantic v2。共享 MySQL 5.7、Redis、MinIO，提供认证、权限、市场协议、存储、生产、质检、中试及 OA 等 API。

## 结构

- `app/main.py`：应用入口、路由与中间件注册。
- `app/api/`：接口；`app/schemas/`：请求与响应结构（部分旧模块在 API 中定义）。
- `app/services/`：业务服务与两套现有流程引擎；`app/crud/`：数据操作。
- `app/models/`：模型；`app/core/`：认证、配置、数据库与权限。
- `app/tasks/`：定时任务；`tests/`：回归测试；`scripts/`：检查及一次性运维工具。

规则见 [AGENTS](AGENTS.md)，工程关系见[根 README](../README.md)。依赖包含 Alembic，但仓库目前没有可直接运行的 Alembic 迁移目录，不能据此假定可执行 `alembic upgrade head`。

## 准备环境

以下命令从 `backend/` 执行。已有环境无需重复创建或覆盖配置。

```bash
python3.9 -m venv venv
venv/bin/python -m pip install -r requirements.txt
venv/bin/python -m pip check
```

首次配置时复制 `.env.example` 为 `.env`，按团队提供的本地环境填写。默认读取 `backend/.env`；其他环境通过 `ENV_FILE` 指定。不要提交实际凭据或把测试环境指向生产数据。

虚拟环境由每台机器重建，不纳入 Git。测试工具不是运行依赖；需要 pytest 时安装到开发虚拟环境，再从本目录执行，例如 `venv/bin/python -m pytest tests/test_child_row_sync.py`。完整测试集需先确认配置及隔离数据环境。

## 服务命令（由用户执行）

| 环境 | 命令入口 | 默认监听／配置 |
| --- | --- | --- |
| 本地 | `./start.sh --host 127.0.0.1 --port 8000 --reload` | `.env`，脚本默认 host 原为 `0.0.0.0`，此处显式绑定本机 |
| 生产 | `./start-prod.sh start` | `0.0.0.0:8111`、`.env.production`、`venv/` |
| 测试 | `./start-test.sh start` | `127.0.0.1:10002`、`.env.test`、`.venv/` |

生产／测试脚本另支持 `status`、`stop`、`restart`、`logs`。Agent 不自行启停或重启服务。不存在 `start-local.sh`；旧测试端口 8112 不能代替当前脚本默认值。

## API 与数据

默认前缀 `/api`；Web 管理接口主要为 `/api/web/...`，移动接口主要为 `/api/mini/...`。公共登录路径以 `app/api/public.py` 为准。JWT、RSA 登录加密、API 加密和审计由现有中间件与配置控制。

`/health` 是健康检查；`/docs`、`/redoc` 仅在 DEBUG 启用时提供。

SQL 位于 [docs/sql](../docs/sql/)。当前初始化基线不完整，部分历史迁移缺失；尚未验证从空库部署。不能直接向现有业务库导入根目录备份或运行清库、重置密码、导入脚本作为验证。

## 检查

- 运行受影响测试；测试数量随代码变化，不把旧报告视为当前通过证明。
- CRUD 修改从根目录运行 `python backend/scripts/check_field_consistency.py`，同时人工核对新增或未注册实体；已知覆盖限制见[字段一致性指南](../docs/dev-field-consistency.md)。
- `scripts/` 中的 migration、seed、reset、clear、import 工具可能写库，先读用途和数据范围，不批量执行。