山峡化工一体化门户
本工程由 FastAPI 共享后端、Vue 3 管理端（含移动 H5）和 uni-app 小程序组成。当前仓库已包含 CRM、地磅、运输、报销、工作流、文档库等业务；旧 CRM 与地磅系统的资料用于迁移和对照，不能据旧说明判断本仓库代码应被移除。
目录与入口
| 路径 | 职责 | 开发约束 |
|---|---|---|
backend/ |
共享 API、业务服务、定时任务、测试 | 后端规则 |
web-admin/ |
管理后台和移动 H5 | Web 规则 |
miniprogram/ |
微信小程序、业务分包、WebView | 小程序规则 |
docs/ |
规范、业务资料、迁移和验收记录 | 文档索引 |
openspec/ |
工程规范与变更材料 | 配置 |
生产环境部署/ |
发布、代理与备份脚本和说明 | 部署说明 |
resources/ |
保留的证件参考图片 | 资料索引 |
local-data/ |
本机原始业务资料、快照和凭据（Git 忽略） | 路径映射 |
doclib/ |
文档库当前说明和保留的旧集成 | 文档库说明 |
实际代码保持现有目录和路径。不要将目录整理与业务重构合并执行。
本地开发
后端首次使用时，在 backend/ 创建本机虚拟环境并安装 requirements.txt，按 .env.example 配置本地依赖。已有环境无需重建。项目历史规范要求兼容 Python 3.9；启动脚本的版本提示存在差异，选择运行版本时需核对依赖和实际部署环境，不据提示自动升级。
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 版本要求：
cd web-admin
pnpm install
pnpm dev
构建使用 pnpm build；类型检查及构建使用 pnpm build:typecheck。
小程序使用 HBuilderX 打开 miniprogram/ 并运行至微信开发者工具。环境和发布步骤见 小程序 README；视觉要求以 小程序 UI 规范 为准，旧 README 中的局部迁移配色说明不替代统一规范。发布前执行已有 npm run release:check-api 检查。
测试与资料维护
- 后端测试位于
backend/tests/；按改动范围执行venv/bin/python -m pytest tests/<目标文件>。涉及外部服务的测试先确认测试环境。 - Web 和小程序的
scripts/中包含真实测试、检查器与构建工具，不能整目录归档。按具体脚本及文档选择命令；小程序npm test当前仍是占位命令。 - 工程规则入口为 AGENTS.md，子数据保存要求见 差量更新规则。
- 规范、历史计划和验收证据的分类见 文档索引。
- 本地依赖、缓存、PID 和凭据不纳入版本管理。它们退出跟踪不代表本机文件已删除，也不代表 Git 历史已清除。
本次治理范围及验证记录见 工程清理记录。