feat(api): 新增小程序用户端与后台管理端 v1 业务接口(62 端点)
一、基础设施
- route.php:58 条路由覆盖 /api/v1/**;:id 用 \d+ 约束、长路径优先
- api/controller/V1.php:响应适配为 {code,message,data}(FastAdmin 原生 {code,msg,time,data} 不兼容);
Authorization Bearer 鉴权;统一分页;业务公共 userInfo/ext/flow/notify/adminLog
- admin/command/FcInstall.php:19 张 fa_fc_* 表 + 种子数据,幂等可重跑
二、控制器 17 个
- 用户端 Auth/Home/Post/Member/Distribution/Message/Setting
- 后台端 AdminDashboard/AdminMerchant/AdminMember/AdminPost/AdminComment/
AdminDist/AdminOrder/AdminFinance/AdminRbac/AdminSetting
三、契约一致性
- 字段与小程序 common/mock/data.js 逐字段对齐,Mock 与真实接口可对拍
- 实现 BR-01~BR-12,错误文案与前端 mock 完全一致
- 详情联系方式强制脱敏,付费/会员方可解锁
四、验证
- tools/verify-api.mjs:63 端点契约 + 12 条业务规则 + 8 步双端闭环
- docs/05-后端实现规范.md
这个提交包含在:
229
application/api/controller/Home.php
普通文件
229
application/api/controller/Home.php
普通文件
@@ -0,0 +1,229 @@
|
||||
<?php
|
||||
|
||||
namespace app\api\controller;
|
||||
|
||||
use think\Db;
|
||||
|
||||
/**
|
||||
* 用户端 · 首页与展示(Module-HOME)
|
||||
* 路由:
|
||||
* GET /api/v1/home/banners H1 轮播广告位
|
||||
* GET /api/v1/home/categories H2 分类导航
|
||||
* GET /api/v1/home/search/hot H3 热门搜索
|
||||
* GET /api/v1/home/feed H4 信息流
|
||||
*/
|
||||
class Home extends V1
|
||||
{
|
||||
/**
|
||||
* H1 首页轮播广告位
|
||||
* GET /api/v1/home/banners → [{id,title,image,link,color}]
|
||||
* 规则:仅 enabled=1,按 sort asc;image 为空返回 ''
|
||||
*/
|
||||
public function banners()
|
||||
{
|
||||
$rows = Db::name('fc_banner')
|
||||
->where('enabled', 1)
|
||||
->order('sort asc')
|
||||
->select();
|
||||
|
||||
$list = [];
|
||||
foreach ($rows as $row) {
|
||||
$list[] = [
|
||||
'id' => (int)$row['id'],
|
||||
'title' => (string)$row['title'],
|
||||
'image' => (string)$row['image'],
|
||||
'link' => (string)$row['link'],
|
||||
'color' => (string)$row['color'],
|
||||
];
|
||||
}
|
||||
$this->ok($list);
|
||||
}
|
||||
|
||||
/**
|
||||
* H2 分类导航
|
||||
* GET /api/v1/home/categories → [{id,name,iconKey,icon,color,count}]
|
||||
* 规则:仅 enabled=1,按 sort asc;icon 为固定 /static/icons/ 文件名(按 id 映射)
|
||||
*/
|
||||
public function categories()
|
||||
{
|
||||
$rows = Db::name('fc_category')
|
||||
->where('enabled', 1)
|
||||
->order('sort asc')
|
||||
->select();
|
||||
|
||||
$list = [];
|
||||
foreach ($rows as $row) {
|
||||
$id = (int)$row['id'];
|
||||
$list[] = [
|
||||
'id' => $id,
|
||||
'name' => (string)$row['name'],
|
||||
'iconKey' => (string)$row['icon_key'],
|
||||
'icon' => '/static/icons/' . $this->iconFile($id),
|
||||
'color' => (string)$row['color'],
|
||||
'count' => (int)$row['post_count'],
|
||||
];
|
||||
}
|
||||
$this->ok($list);
|
||||
}
|
||||
|
||||
/**
|
||||
* H3 热门搜索
|
||||
* GET /api/v1/home/search/hot → [string]
|
||||
* 规则:读配置 home.hotKeywords,未配置则返回默认
|
||||
*/
|
||||
public function hotKeywords()
|
||||
{
|
||||
$default = ['租房 一室一厅', '二手电动车', '急招快递员', '钢琴家教', '空调维修'];
|
||||
$keywords = $this->cfg('home.hotKeywords', $default);
|
||||
if (!is_array($keywords) || !$keywords) {
|
||||
$keywords = $default;
|
||||
}
|
||||
$this->ok(array_values($keywords));
|
||||
}
|
||||
|
||||
/**
|
||||
* H4 信息流
|
||||
* GET /api/v1/home/feed {categoryId?,keyword?,area?,sort?,page,size}
|
||||
* → {list,page,size,total,hasMore}
|
||||
* 规则:仅 audit_status=1 AND status=1 AND deletetime IS NULL
|
||||
*/
|
||||
public function feed()
|
||||
{
|
||||
list($page, $size) = $this->pager();
|
||||
|
||||
$categoryId = (int)$this->input('categoryId', 0);
|
||||
$keyword = trim((string)$this->input('keyword', ''));
|
||||
$area = trim((string)$this->input('area', ''));
|
||||
$sort = (string)$this->input('sort', '');
|
||||
|
||||
$query = Db::name('fc_post')
|
||||
->where('audit_status', 1)
|
||||
->where('status', 1)
|
||||
->whereNull('deletetime');
|
||||
if ($categoryId > 0) {
|
||||
$query->where('category_id', $categoryId);
|
||||
}
|
||||
if ($keyword !== '') {
|
||||
$query->where('title', 'like', '%' . $keyword . '%');
|
||||
}
|
||||
if ($area !== '') {
|
||||
$query->where('area', $area);
|
||||
}
|
||||
if ($sort === 'price') {
|
||||
$query->order('price asc');
|
||||
} elseif ($sort === 'hot') {
|
||||
$query->order('views desc');
|
||||
} else {
|
||||
$query->order('createtime desc');
|
||||
}
|
||||
|
||||
$counter = Db::name('fc_post')
|
||||
->where('audit_status', 1)
|
||||
->where('status', 1)
|
||||
->whereNull('deletetime');
|
||||
if ($categoryId > 0) {
|
||||
$counter->where('category_id', $categoryId);
|
||||
}
|
||||
if ($keyword !== '') {
|
||||
$counter->where('title', 'like', '%' . $keyword . '%');
|
||||
}
|
||||
if ($area !== '') {
|
||||
$counter->where('area', $area);
|
||||
}
|
||||
$total = $counter->count();
|
||||
|
||||
$rows = $query->page($page, $size)->select();
|
||||
|
||||
$list = [];
|
||||
foreach ($rows as $row) {
|
||||
$list[] = $this->buildPost($row);
|
||||
}
|
||||
|
||||
$this->ok($this->paginate($list, $total, $page, $size));
|
||||
}
|
||||
|
||||
/**
|
||||
* 组装 Post 结构(与前端 mock 数据字段严格对齐)
|
||||
* @param array $row fc_post 行
|
||||
* @return array
|
||||
*/
|
||||
protected function buildPost($row)
|
||||
{
|
||||
$categoryName = '';
|
||||
if (!empty($row['category_id'])) {
|
||||
$cat = Db::name('fc_category')->where('id', $row['category_id'])->find();
|
||||
if ($cat) {
|
||||
$categoryName = (string)$cat['name'];
|
||||
}
|
||||
}
|
||||
|
||||
$publisher = ['id' => 0, 'name' => '', 'avatar' => '', 'isMerchant' => false, 'verified' => false];
|
||||
if (!empty($row['user_id'])) {
|
||||
$pub = Db::name('user')->where('id', $row['user_id'])->find();
|
||||
if ($pub) {
|
||||
$pubExt = Db::name('fc_user_ext')->where('user_id', $pub['id'])->find();
|
||||
$isMerchant = $pubExt && (int)$pubExt['user_type'] === 2;
|
||||
$publisher = [
|
||||
'id' => (int)$pub['id'],
|
||||
'name' => (string)$pub['nickname'],
|
||||
'avatar' => (string)$pub['avatar'],
|
||||
'isMerchant' => (bool)$isMerchant,
|
||||
'verified' => (bool)$isMerchant,
|
||||
];
|
||||
}
|
||||
}
|
||||
|
||||
$tags = [];
|
||||
if (!empty($row['tags'])) {
|
||||
foreach (explode(',', (string)$row['tags']) as $tag) {
|
||||
$tag = trim($tag);
|
||||
if ($tag !== '') {
|
||||
$tags[] = $tag;
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
return [
|
||||
'id' => (int)$row['id'],
|
||||
'categoryId' => (int)$row['category_id'],
|
||||
'categoryName' => $categoryName,
|
||||
'title' => (string)$row['title'],
|
||||
'content' => (string)$row['content'],
|
||||
'cover' => (string)$row['cover'],
|
||||
'price' => (float)$row['price'],
|
||||
'priceUnit' => (string)$row['price_unit'],
|
||||
'area' => (string)$row['area'],
|
||||
'address' => (string)$row['address'],
|
||||
'contact' => $this->maskPhone($row['phone']),
|
||||
'views' => (int)$row['views'],
|
||||
'likes' => (int)$row['likes'],
|
||||
'isPaid' => (int)$row['is_paid'] === 1,
|
||||
'auditStatus' => (int)$row['audit_status'],
|
||||
'createdAt' => $this->iso($row['createtime']),
|
||||
'tags' => $tags,
|
||||
'publisher' => $publisher,
|
||||
'commentCount' => (int)$row['comment_count'],
|
||||
'distance' => (int)$row['distance'],
|
||||
];
|
||||
}
|
||||
|
||||
/**
|
||||
* 分类 id → 固定图标文件名
|
||||
* @param int $id
|
||||
* @return string
|
||||
*/
|
||||
protected function iconFile($id)
|
||||
{
|
||||
$map = [
|
||||
1 => 'cat-job.png',
|
||||
2 => 'cat-house.png',
|
||||
3 => 'cat-goods.png',
|
||||
4 => 'cat-car.png',
|
||||
5 => 'cat-service.png',
|
||||
6 => 'cat-education.png',
|
||||
7 => 'cat-clean.png',
|
||||
8 => 'cat-friend.png',
|
||||
];
|
||||
return isset($map[$id]) ? $map[$id] : 'cat-job.png';
|
||||
}
|
||||
}
|
||||
在新工单中引用
屏蔽一个用户