197 lines
8.7 KiB
Markdown
197 lines
8.7 KiB
Markdown
# 后端架构深度解析与开发指南
|
||
|
||
## 1. 引言
|
||
|
||
本文档旨在为开发人员提供一份关于本项目（智慧农场系统）后端架构的深度技术解析。不同于基础的架构介绍，本文档聚焦于**代码实现细节**、**数据库设计范式**以及**核心业务流程**的底层逻辑。它将帮助你在接手项目后，快速理解现有代码模式（Patterns），并安全、高效地扩展新功能。
|
||
|
||
---
|
||
|
||
## 2. 核心架构与技术实现
|
||
|
||
本项目基于 **ThinkPHP 6** 框架开发，采用了典型的 **MVC** 架构，并结合了多应用（Multi-app）模式。
|
||
|
||
### 2.1 C层（Controller）技术实现
|
||
|
||
控制器层主要负责请求接收、参数校验和业务调度。项目在控制器层有以下显著的实现模式：
|
||
|
||
#### 2.1.1 基类封装 (`app/ApiRest.php`)
|
||
所有 API 控制器均继承自 `app\ApiRest`，该基类提供了以下核心能力：
|
||
|
||
- **统一响应格式**：通过 `success($data)` 和 `error($msg)` 方法，强制统一 API 返回结构：
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"data": { ... },
|
||
"sign": "..." // 签名（可选）
|
||
}
|
||
```
|
||
- **多租户隔离**：在构造函数中自动解析 `uniacid`（商户/租户ID），并赋值给 `$this->_uniacid`。这是系统支持多商户SaaS模式的核心。
|
||
- **鉴权机制**：
|
||
- 检查 HTTP Header 中的 `autograph`（小程序用户标识）。
|
||
- 维护一个 `$noNeedLogin` 白名单。
|
||
- **注意**：`shareChangeData` 方法中硬编码了大量白名单路由，这种实现方式维护成本较高，建议后续改为中间件或注解配置。
|
||
|
||
#### 2.1.2 胖模型，瘦控制器
|
||
控制器（如 `app/farm/controller/IndexLand.php`）通常比较轻量，不包含复杂的计算逻辑。
|
||
- **示例**：在“土地下单”流程中，价格计算、优惠券抵扣等逻辑全部下沉到了 Model 层 (`LandOrder::payOrderInfo`)。
|
||
- **优点**：业务逻辑可复用，控制器代码整洁。
|
||
|
||
### 2.2 M层（Model）技术实现
|
||
|
||
模型层不仅负责数据库交互，还承担了大部分业务逻辑。
|
||
|
||
#### 2.2.1 基类扩展 (`app/BaseModel.php`)
|
||
- 实现了基础的 CRUD 方法（`getRow`, `listRow`, `createRow` 等）。
|
||
- **软删除机制**：手动实现了基于 `deleted` 字段和 `delete_time` 的软删除，未使用 TP 自带的 `SoftDelete` Trait。
|
||
- **代码现状**：核心业务 Model（如 `LandOrder`）往往重写了 `dataAdd`/`dataUpdate` 方法，直接调用 TP 的 `insert`/`update`，并未完全依赖 `BaseModel` 的封装。这导致项目中存在两种 CRUD 风格。
|
||
|
||
#### 2.2.2 高级特性应用
|
||
- **获取器 (Getters)**：大量使用 TP 的获取器处理字段格式化。例如 `LandList::getImgsAttr` 将数据库存储的逗号分隔字符串自动转换为数组。
|
||
- **动态追加字段**：使用 `$append` 属性在 JSON 序列化时追加计算字段（如 `min_price`）。
|
||
- **观察者模式**：在 `LandList::updateSome` 中，手动实现了观察者模式 (`app\farm\server\Land`) 来同步更新关联表数据。这是项目中少见的设计模式应用，值得保留和参考。
|
||
|
||
---
|
||
|
||
## 3. 数据库深度解析
|
||
|
||
### 3.1 数据库概览
|
||
- **引擎**：大部分表使用 `MyISAM`。
|
||
- **风险**：MyISAM 不支持事务，且在并发写入时是表级锁。对于涉及资金交易的表（如 `balance_water`, `land_order`），强烈建议迁移到 `InnoDB`。
|
||
- **字符集**：`utf8` / `utf8mb4`。
|
||
- **多租户设计**：几乎所有表都包含 `uniacid` 字段，用于物理隔离不同商户的数据。
|
||
|
||
### 3.2 核心业务实体关系 (ER图)
|
||
|
||
以下是“土地认养”核心业务的实体关系推导：
|
||
|
||
```mermaid
|
||
erDiagram
|
||
User ||--o{ LandOrder : "下单"
|
||
User ||--o{ Address : "拥有"
|
||
Farmer ||--o{ LandList : "管理"
|
||
LandList ||--|{ LandSpe : "包含规格"
|
||
LandList ||--o{ LandMassif : "包含地块"
|
||
LandOrder }|--|| LandList : "关联土地"
|
||
LandOrder }|--|| LandSpe : "关联规格"
|
||
LandOrder }|--|| LandMassif : "关联地块"
|
||
LandOrder ||--|{ LandOrderSeed : "包含种子"
|
||
|
||
User {
|
||
int id PK
|
||
int uniacid
|
||
string openid
|
||
string nickName
|
||
}
|
||
|
||
LandList {
|
||
int id PK
|
||
int farmer_id FK "农场主"
|
||
string title "土地名称"
|
||
int status
|
||
}
|
||
|
||
LandOrder {
|
||
int id PK
|
||
string order_code "订单号"
|
||
decimal pay_price "支付金额"
|
||
int pay_type "1:未支付 2:已支付"
|
||
int status
|
||
}
|
||
```
|
||
|
||
### 3.3 关键表结构解析
|
||
|
||
#### 1. `ims_lbfarm_land_list` (土地表)
|
||
- 核心商品表，存储土地的基本信息。
|
||
- 关联表：`ims_lbfarm_land_spe` (规格), `ims_lbfarm_land_massif` (地块/位置)。
|
||
|
||
#### 2. `ims_lbfarm_land_order` (土地订单表)
|
||
- **核心字段**：
|
||
- `order_code`: 业务订单号。
|
||
- `transaction_id`: 微信支付流水号。
|
||
- `pay_type`: 支付状态 (1=未支付, 2=微信支付, 3=余额支付)。
|
||
- `seed_data`: 种子信息的 JSON 快照（反范式设计，避免关联查询）。
|
||
|
||
---
|
||
|
||
## 4. 核心业务流程剖析
|
||
|
||
### 4.1 土地认养下单与支付流程
|
||
|
||
这是一个跨越 Controller、Model 和 Service 的复杂流程：
|
||
|
||
1. **预下单 (计价)**
|
||
- **入口**：`IndexLand::landPayOrderInfo`
|
||
- **逻辑**：调用 `LandOrder::payOrderInfo`。
|
||
- **计算公式**：`总价 = 土地规格单价 + (地块单价 * 认养周期) + ∑(种子单价 * 数量) - 优惠券金额`。
|
||
|
||
2. **创建订单**
|
||
- **入口**：`IndexLand::landPayOrder`
|
||
- **逻辑**：再次调用 `payOrderInfo` 校验价格，然后写入 `land_order` 表，同时写入 `land_order_seed` 表。
|
||
|
||
3. **支付回调 (核心)**
|
||
- **逻辑位置**：`LandOrder::orderResult`
|
||
- **事务处理**：
|
||
1. 开启事务 (`Db::startTrans()`)。
|
||
2. 更新订单状态 (`pay_type=2`, `pay_time`)。
|
||
3. **余额扣除**：如果使用了余额抵扣，调用 `BalanceWater::addWater`。
|
||
4. **资金流水**：记录 `FinanceWater`。
|
||
5. **分销结算**：调用 `DistributionCash::addUserCash` 计算分销佣金。
|
||
6. 提交事务 (`Db::commit()`)。
|
||
- **后续动作**：发送微信订阅消息 (`paySendService`)，这是异步或非事务性的操作，放在 commit 之后执行是正确的。
|
||
|
||
---
|
||
|
||
## 5. 开发实战指南
|
||
|
||
### 5.1 如何新增一个 API 接口？
|
||
|
||
假设你需要新增一个“获取最近的农场列表”接口：
|
||
|
||
1. **创建控制器**：
|
||
在 `app/farm/controller` 下创建 `IndexFarm.php`，继承 `ApiRest`。
|
||
```php
|
||
class IndexFarm extends ApiRest {
|
||
public function nearby() {
|
||
$lat = $this->_param['lat'];
|
||
$lng = $this->_param['lng'];
|
||
// 调用 Model 获取数据
|
||
$data = (new Farmer())->getNearby($lat, $lng);
|
||
return $this->success($data);
|
||
}
|
||
}
|
||
```
|
||
|
||
2. **实现 Model 逻辑**：
|
||
在 `app/farm/model/Farmer.php` 中实现 `getNearby` 方法。建议参考 `LandList::indexDataList` 中的距离计算 SQL。
|
||
|
||
3. **配置路由**：
|
||
在 `app/farm/route/route.php` 中注册路由（如果项目未开启自动路由）。目前看项目启用了自动路由，直接访问 `farm/index_farm/nearby` 即可。
|
||
|
||
4. **配置鉴权**：
|
||
如果该接口不需要登录，需要在 `ApiRest::shareChangeData` 或控制器的构造函数中将其加入 `$noNeedLogin` 数组。
|
||
|
||
### 5.2 常见坑与规避
|
||
|
||
1. **数据库事务**：
|
||
由于大量表使用 `MyISAM`，在涉及多表更新时（如订单状态+库存扣减），事务可能不会生效。
|
||
- **建议**：在开发新功能涉及核心交易表时，务必检查表引擎，必要时手动 `ALTER TABLE ... ENGINE=InnoDB`。
|
||
|
||
2. **参数获取**：
|
||
尽量使用 `$this->_param` 获取参数，它合并了 GET 和 POST 数据。避免直接使用 `$_GET` 或 `$_POST`。
|
||
|
||
3. **浮点数计算**：
|
||
项目中存在直接使用浮点数计算金额的情况（如 `round($price, 2)`）。在涉及金额比对时，建议使用 `bccomp` 等高精度函数，避免精度丢失导致的 0.01 元误差。
|
||
|
||
4. **SQL 注入风险**：
|
||
虽然 TP 的 ORM 有防注入机制，但在拼接原生 SQL（如距离计算）时，务必使用参数绑定，严禁直接拼接变量。
|
||
|
||
---
|
||
|
||
## 6. 附录：推荐的重构方向
|
||
|
||
1. **引入 .env 配置**：将 `config/database.php` 中的硬编码配置移至环境变量。
|
||
2. **统一 Model 规范**：废弃 `dataAdd` 等自定义方法，统一使用 TP 标准的 `save/create`，或完善 `BaseModel` 并强制继承。
|
||
3. **中间件鉴权**：将 `ApiRest` 中的硬编码鉴权逻辑重构为 TP 中间件。
|
||
4. **数据库迁移**：编写脚本将所有 `MyISAM` 表迁移至 `InnoDB`。
|