# 山峡化工一体化门户

本工程由 FastAPI 共享后端、Vue 3 管理端（含移动 H5）和 uni-app 小程序组成。当前仓库已包含 CRM、地磅、运输、报销、工作流、文档库等业务；旧 CRM 与地磅系统的资料用于迁移和对照，不能据旧说明判断本仓库代码应被移除。

## 目录与入口

| 路径 | 职责 | 开发约束 |
| --- | --- | --- |
| `backend/` | 共享 API、业务服务、定时任务、测试 | [后端规则](backend/AGENTS.md) |
| `web-admin/` | 管理后台和移动 H5 | [Web 规则](web-admin/AGENTS.md) |
| `miniprogram/` | 微信小程序、业务分包、WebView | [小程序规则](miniprogram/AGENTS.md) |
| `docs/` | 规范、业务资料、迁移和验收记录 | [文档索引](docs/README.md) |
| `openspec/` | 工程规范与变更材料 | [配置](openspec/config.yaml) |
| `生产环境部署/` | 发布、代理与备份脚本和说明 | [部署说明](生产环境部署/README.md) |
| `resources/` | 保留的证件参考图片 | [资料索引](resources/README.md) |
| `local-data/` | 本机原始业务资料、快照和凭据（Git 忽略） | [路径映射](docs/development/repository-cleanup.md) |
| `doclib/` | 文档库当前说明和保留的旧集成 | [文档库说明](doclib/需求说明.md) |

实际代码保持现有目录和路径。不要将目录整理与业务重构合并执行。

## 本地开发

后端首次使用时，在 `backend/` 创建本机虚拟环境并安装 `requirements.txt`，按 `.env.example` 配置本地依赖。已有环境无需重建。项目历史规范要求兼容 Python 3.9；启动脚本的版本提示存在差异，选择运行版本时需核对依赖和实际部署环境，不据提示自动升级。

```bash
cd backend
source venv/bin/activate
./start.sh --host 127.0.0.1 --port 8000 --reload
```

后端命令说明：`./start.sh --help`。生产启动使用 `./start-prod.sh`，具体流程见部署说明；本地开发不执行生产迁移和发布脚本。

Web 使用 `web-admin/package.json` 中的 Node/pnpm 版本要求：

```bash
cd web-admin
pnpm install
pnpm dev
```

构建使用 `pnpm build`；类型检查及构建使用 `pnpm build:typecheck`。

小程序使用 HBuilderX 打开 `miniprogram/` 并运行至微信开发者工具。环境和发布步骤见 [小程序 README](miniprogram/README.md)；视觉要求以 [小程序 UI 规范](docs/miniprogram-ui-spec-sanqiang.md) 为准，旧 README 中的局部迁移配色说明不替代统一规范。发布前执行已有 `npm run release:check-api` 检查。

## 测试与资料维护

- 后端测试位于 `backend/tests/`；按改动范围执行 `venv/bin/python -m pytest tests/<目标文件>`。涉及外部服务的测试先确认测试环境。
- Web 和小程序的 `scripts/` 中包含真实测试、检查器与构建工具，不能整目录归档。按具体脚本及文档选择命令；小程序 `npm test` 当前仍是占位命令。
- 工程规则入口为 [AGENTS.md](AGENTS.md)，子数据保存要求见 [差量更新规则](docs/development/child-data-save-rules.md)。
- 规范、历史计划和验收证据的分类见 [文档索引](docs/README.md)。
- 本地依赖、缓存、PID 和凭据不纳入版本管理。它们退出跟踪不代表本机文件已删除，也不代表 Git 历史已清除。

本次治理范围及验证记录见 [工程清理记录](docs/development/repository-cleanup.md)。

资料保留与删除范围见 [清理记录](docs/development/repository-cleanup.md)；部署工具目录分类见 [部署目录说明](生产环境部署/目录说明.md)。