# Miniwater 

**Repository Path**: ycl52you/miniwater

## Basic Information

- **Project Name**: Miniwater 
- **Description**: 123
那就是我们33后
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-15
- **Last Updated**: 2026-07-24

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 桶装水批发零售小程序

技术栈：微信小程序原生端、PHP 8.3 API、MySQL 8、Nginx、Docker。

## 包含内容

- 小程序端：桶装水、商品、购物车、地址、下单、订单、我的、退款、发票
- 管理端：登录、概览、订单、商品、分类、配送配置、支付配置、退款、发票
- API：登录、商品列表、购物车、地址、报价、下单、支付、订单、后台配置
- MySQL：角色、价格组、水票、配送支付矩阵、配送费、时间段、退款、发票等业务表

## 启动

```bash
docker compose up -d --build
```

访问地址：

- 管理端：`http://localhost:9097/admin/`
- API 健康检查：`http://localhost:9097/categories`
- MySQL：容器内服务名 `mysql:3306`

后台默认账号：

- 账号：`admin`
- 密码：`admin123`

本地 Docker 默认启用 `ALLOW_LOCAL_TEST_FEATURES=true`，仅用于接口验收和微信/短信/支付本地闭环模拟。生产环境必须显式设置
`ALLOW_LOCAL_TEST_FEATURES=false`，并关闭 `APP_DEBUG`、替换后台默认账号密码、留空 `DELIVERY_DEV_CODE`。

## 小程序开发

使用微信开发者工具导入 `miniprogram` 目录。

本地开发时，`miniprogram/config.js` 默认 API 地址为：

```js
apiBase: "http://localhost:9097";
```

微信开发者工具需要勾选“不校验合法域名”。正式环境请改为 HTTPS 域名，并在微信后台配置合法 request 域名。

小程序登录分为两种情况：

- `develop`：走本地 `apiBase`，适合微信开发者工具联调
- `trial/release`：走 `trialApiBase/releaseApiBase`，必须填写真实 HTTPS 域名，手机真机不能访问 `localhost`

如果要让“微信快捷登录”在真机/体验版可用，至少需要：

- `miniprogram/config.js` 中配置可公网访问的 HTTPS 接口域名
- `.env` 中填写真实 `WECHAT_MINIAPP_APPID` 和 `WECHAT_MINIAPP_SECRET`
- 微信公众平台后台配置合法 request 域名

## 关键业务配置

当前项目的大部分业务规则都在数据库和后台配置中维护：

- 角色与价格组：`roles`、`price_groups`、`sku_prices`
- 水票适用范围：`water_ticket_packages`、`water_ticket_scope_rules`
- 配送与支付矩阵：`delivery_payment_rules`
- 货到付款收款角色：`payment_methods.config`
- 配送范围、配送费、时间段：`delivery_areas`、`delivery_fee_rules`、`delivery_time_slots`
- 分销佣金规则：`sales_commission_rules`
- 退款冲回规则：`commission_reversal_rules`
- 发票开关：`settings.invoice.enabled`
- 销售渠道：`sales_channels`

订单创建时会保存快照，后续修改规则不会影响历史订单。

## 正式接入前仍需完成

- 微信小程序 `wx.login` 换取真实 `openid/session_key`
- 微信支付 JSAPI 下单、支付回调、退款回调
- 企业微信或其他通知渠道接入
- OSS 图片上传
- HTTPS 域名、备案、微信合法域名配置

## 短信宝接入说明

当前项目的验证码短信已支持短信宝。

- 后端接口：`POST /auth/send-code`
- 运行逻辑：生产环境下真实调用短信宝；本地开启 `ALLOW_LOCAL_TEST_FEATURES=true` 时仍返回 `debug_code` 便于联调
- 环境变量：

```bash
SMS_PROVIDER=smsbao
SMS_USERNAME=你的短信宝账号
SMS_API_KEY=你的短信宝 API Key
SMS_SIGN_NAME=你的短信签名
SMS_LOGIN_TEMPLATE_CONTENT=【你的签名】您的验证码是{code}。如非本人操作，请忽略本短信
```

说明：

- `SMS_LOGIN_TEMPLATE_CONTENT` 里必须包含 `{code}` 占位符
- 若历史环境仍在使用 `SMS_ACCESS_KEY_ID` / `SMS_ACCESS_KEY_SECRET`，本项目也会兼容读取
- 数据库 `settings.sms.provider` 若仍是旧值，可直接用 `.env` 的 `SMS_PROVIDER=smsbao` 覆盖

## 上线资料

- 环境变量示例：`.env.example`
- 上线检查清单：`LAUNCH_CHECKLIST.md`
- 上线增强 migration：`database/migrations-20260513-launch-readiness.sql`

建议先执行完整接口级验收：

```bash
npm run acceptance:full
```

`acceptance:full` 会依次执行 smoke、全角色闭环、水票抵扣恢复和商品导入检查。说明文档见 `docs/SMOKE_ACCEPTANCE.md`。