shanxia2.0

山峡化工一体化门户

本工程由 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 历史已清除。

本次治理范围及验证记录见 工程清理记录。

资料保留与删除范围见 清理记录；部署工具目录分类见 部署目录说明。