Add the Project navigation group alongside Market, Production and Quality. Preserve existing leaf IDs and role grants while migrating the menu hierarchy, keep legacy URLs redirecting, and align frontend/backend menus.
70 lines
4.6 KiB
Markdown
70 lines
4.6 KiB
Markdown
# 中科兴皖后端
|
||
|
||
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 工具可能写库,先读用途和数据范围,不批量执行。
|
||
|
||
|
||
## 项目归属启用
|
||
|
||
项目组的区域、医院仅作资料记录;不参与细胞存储和科研捐赠的业务地点、权限校验。
|
||
切换到项目统计版本前,先在已授权数据库执行增量结构脚本
|
||
[2026-11-02-project_management.sql](../docs/sql/migrations/2026-11-02-project_management.sql),
|
||
再依次执行[菜单种子](../docs/sql/migrations/2026-11-02-project_management_menu_seed.sql)与
|
||
[项目一级菜单迁移](../docs/sql/migrations/2026-11-02-project_top_menu.sql)。
|
||
“项目”与“市场、生产、质检”平级,包含项目组管理、项目管理、业务统计、历史归属维护。
|
||
菜单种子不会给角色新增业务权限,应在现有角色管理分配项目管理权限及祖先菜单;
|
||
一级菜单迁移保留已有叶子 ID/授权,仅给已授权项目子菜单的角色补齐新祖先。
|
||
脚本不回填历史业务,不代表空库初始化;执行前备份并在隔离 MySQL 环境验证。
|
||
|
||
`PROJECT_ASSIGNMENT_REQUIRED` 默认 `false`,便于先配置项目组和项目、兼容历史客户端。
|
||
人员和启用项目配置齐全后由运维将其设为 `true`;新建预签约及四类正式业务必须选择项目。
|
||
普通编辑保留历史归属,历史补录/调整须通过归属维护并填写原因;受控业务转换继承原归属。
|
||
该开关同时返回给 Web 和移动表单,调整配置后的服务重启由用户执行。
|