# 小程序规则

修改前先读 [根规则](../AGENTS.md)、[工程规则](../docs/development/engineering-rules.md)；保存、导入、复制或子数据移除必须完整阅读 [子数据保存规则](../docs/development/child-data-save-rules.md)。Web 移动 H5 代码位于 web-admin，不要混淆其宿主与本应用。

## 工程入口

- uni-app 微信小程序；页面和路由以 `pages/`、`pages.json`、`manifest.json` 为准。已确认业务范围仅 CRM、地磅、运输、报销四模块，共用后端和租户模型；未获得新的需求确认不得扩大范围。
- 使用项目已有 HBuilderX / uni-app 开发流程，见 [README](README.md)。`package.json` 的 test 是失败占位，不能称为有效测试入口；按修改范围选择 `scripts/` 中实际测试。
- `npm run env:show` 查看环境提醒；`npm run release:check-api` 检查发布 API 配置。发布与静态资源同步仍按现有发布流程执行。
- UI 权威：[三墙规范](../docs/miniprogram-ui-spec-sanqiang.md)。品牌主绿 `#0a9f6d`，不得以 Web 的 `#10b981` 作主色。
- 树下拉节点只显示本级名称；选中输入框、表格、导出、查看态显示完整祖先路径，分隔符为 ` / `。
- 菜单位于小程序独立 `parent_id=0` 虚拟根，不能放到 Web 根下；数据权限取多角色并集。

## 媒体与上传强制约束

- **Miniprogram photo evidence upload** (`miniprogram`, baseline): Photo/album images only — `uni.chooseImage` + `uni.uploadFile` (`name: file`, `formData.folder`, Bearer header) → collect `data.url` → business API submits `imageUrls`. SHALL NOT use Web `el-upload`/`FormData`+`request`, Base64-in-JSON, or document pickers (`chooseMessageFile`). Upload path SHALL be in `API_ENCRYPT_EXCLUDE_PATHS`. Authority: `openspec/changes/zkxw-engineering-standards/specs/ui-conventions/spec.md` §「小程序拍照凭证上传（基线）」+ `openspec/changes/zkxw-engineering-standards/specs/api-conventions/spec.md` §「小程序拍照凭证上传接口」; reference pattern from `sqxp-wx` delivery/supplier evidence upload.

### Token 与适配

- 品牌绿：`#0a9f6d` / `#087f57` / `#e9f9f2`；大麦黄辅助：`#d6a343` / `#fff7e8`；中性背景与边框见规范第 2.1 节。
- 主基线宽度 **375px**，兼容 **414px**；间距节奏 8–16；卡片圆角 12–16px，大容器 18–22px。

### 三端统一骨架

- 顺序一般为：Header（绿渐变）→ 统计/提示（可选）→ 功能宫格 → 主列表/任务 → 底部固定区（客户端：结算条 + TabBar）。
- Header：绿色渐变、标题左对齐、操作右对齐、下缘大圆角（约 20–24px）。

### 组件与媒体（强约束）

- 列表缩略图：**1:1**，`aspectFill`；轮播：**4:3**，`aspectFill`；详情图：**widthFix**；视频建议 720p 内、尽量短（见规范第 7.0 节）。
- 状态标签语义：`warning` 琥珀待处理、`success` 绿色进行中或完成、`danger` 红色异常；避免同屏过多高饱和色。
- 底部结算条：数量 → 总价 → 主按钮；主按钮视觉优先级最高。
- 触达区域不小于 **44×44**；注意横滑与纵向滚动冲突（尤其一级分类横滑）。

### 从 Demo 到页面

- 规范第 11 节给出 Demo class 到 `pages/**/*.vue` 的建议类名；优先统一 Token 与骨架，再收敛公共样式到 `src/styles` 或公共组件。
- 新增页面类型应先在 `docs/miniprogram-ui-spec-sanqiang.md` 补充结构说明再落代码（见规范第 10 节）。