# 后端架构深度解析与开发指南

## 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`。