# 中科兴皖一体化门户（zkxw）

面向细胞存储、科研捐赠、生产质检、中试服务及 OA 审批的多租户业务系统。四个应用共享后端与权限模型；`sanqiang`、`sqxp`、陇耘鲜达等名称是历史标识，不代表独立服务。

## 应用与入口

| 应用 | 技术与用途 | 开发说明 |
| --- | --- | --- |
| `backend/` | Python 3.9 / FastAPI，业务 API、认证、权限、工作流及 OA | [后端 README](backend/README.md) |
| `web-admin/` | Vue 3 / TypeScript / Element Plus，Web 管理端 | [Web README](web-admin/README.md) |
| `mobile-h5/` | HBuilderX uni-app Vue 3，移动工作台及 WebView 宿主 | [uni-app README](mobile-h5/README.md) |
| `mobile-oa-h5/` | Vue 3 / Vant，OA 与市场业务 H5 | [H5 README](mobile-oa-h5/README.md) |

Web 与移动端访问同一后端；移动宿主通过 WebView 打开 H5 表单和详情。Web 使用 Hash 路由，H5 使用 `/oa-h5/` 下的 History 路由。Docker 的 Web 镜像包含 Web 管理端和移动 H5，小程序由 HBuilderX 独立编译。

后端入口为 `backend/app/main.py`。默认 API 总前缀 `/api`，业务模块主要位于 `/web/...` 与 `/mini/...`；以对应路由定义为准。数据服务使用 MySQL 5.7、Redis 与 MinIO。

## 开发导航

- 开发约束：[根 AGENTS](AGENTS.md)及各应用的 AGENTS。
- UI、模式、SQL、SOP 与开发指南：[文档导航](docs/README.md)。
- 工程规范：[OpenSpec 工程标准](openspec/changes/zkxw-engineering-standards/specs/)。当前仍在变更目录，尚未完成长期基线归档。

首次开发按各应用 README 准备依赖与环境配置，不复用 Git 中的虚拟环境。启动、停止、重启服务由用户执行，Agent 仅告知需要的操作。

## 目录职责

| 路径 | 内容 |
| --- | --- |
| 四个应用目录 | 业务源码、各端测试、各端专用工具 |
| `docs/` | 当前规范、开发指南、SQL 与 SOP 模板 |
| `openspec/` | 保留工程标准，历史业务变更记录已清理 |
| `deploy/docker/` | Docker 构建、Compose、Nginx 与交付说明 |
| `scripts/` | 跨项目工具；发布脚本有外部影响，不能当作普通检查运行 |
| `deploy/test/`、`deploy/production/` | 测试部署与生产操作资料；凭据和证书在忽略的 `.local/deploy/` |
| `resources/` | SOP 原稿、图片和导入规则，见 [资源导航](resources/README.md) |
| `.local/` | 本机证书、环境配置、业务表格与备份，不进入 Git 或 Docker 上下文 |

## 部署入口与已知限制

- [Docker 交付说明](deploy/docker/README.md)、[测试环境说明](deploy/test/README.md)。
- `.drone.yml` 由 tag 触发生产交付包构建，调用 `scripts/package-docker-deploy.sh`，不是日常检查流水线。
- **当前 `docs/sql/zkxw.sql` 只包含 3 张表的建表语句，但打包和 Compose 仍引用它作为初始化文件。尚未验证空库完整部署，请勿把它视为完整可用的全库基线。** 既有部署文档中的相关说法待专项修正。
- 部分测试引用的迁移 SQL 已缺失；字段检查器的覆盖限制见[字段一致性指南](docs/dev-field-consistency.md)，移动色板差异见移动端 AGENTS。不能通过删除测试、覆盖现网数据或改变 UI 来规避这些问题。

## 版本管理

提交源码、必要模板和脱敏配置示例；依赖、构建产物、日志、本地工具状态及真实业务备份不新增入库。真实数据存放在本机 `.local/`，导入操作显式指定输入。graphify 已停用，不再生成或提交知识图谱，也不安装或运行其 hook。

本机凭据位于 `.local/deploy/`，表格与 TSV 位于 `.local/data/`，备份位于 `.local/backups/`。业务历史文档及整理报告已删除；后续优先维护现有规范和 README。