# 同城分类信息小程序（fenleixinxi）

春绿（Spring Green，品牌亮绿取自设计稿 `#00E070`）主题同城分类信息平台：**招聘 / 房产 / 二手 / 车辆 / 本地服务** 信息发布与检索。
技术栈：uni-app（Vue 3）+ 统一请求层 + 本地 Mock 兜底 + 零依赖全链路测试。

---

## 一、交付物索引

| 交付物 | 文件 | 说明 |
| --- | --- | --- |
| **① 功能模块清单（PM）** | [`docs/01-产品功能模块清单.md`](docs/01-产品功能模块清单.md) | 用户端 + 后台管理端模块清单、优先级、业务规则、接口映射 |
| **② UI 设计规范（UI）** | [`docs/02-UI设计规范.md`](docs/02-UI设计规范.md) | 春绿设计令牌、排版、组件、动效规范 |
| **③ 接口文档（前后端）** | [`docs/03-接口文档.md`](docs/03-接口文档.md) | 75 个接口（用户端 43 + 后台 32）字段级契约 + Mock 兜底机制 + 联调清单 |
| **④ 全链路测试报告（QA）** | [`docs/04-全链路测试用例与报告.md`](docs/04-全链路测试用例与报告.md) | 179 条用例、15 步 E2E、15 个缺陷记录与修复 |

## 二、目录结构

```
fenleixinxi/
├── App.vue                     # 全局主题样式（春绿 CSS 变量 + 原子类）
├── uni.scss                    # 设计令牌（$fc-* 自动注入所有 scss）
├── pages.json                  # 15 个页面路由
├── pages/                      # 用户端页面
│   ├── index/index.vue         # 首页：定位/搜索/轮播/分类/会员条/筛选/信息流
│   ├── search/index.vue        # 智能搜索：历史 + 热门
│   ├── post/list.vue           # 分类列表：多维筛选 + 分页
│   ├── post/create.vue         # 发布：表单/真上传/定位/发布方式（免费·单条·套餐）/草稿箱
│   ├── post/mine.vue           # 我的发布：审核状态筛选 + 驳回原因 + 删除（v1.0.7 新增）
│   ├── detail/detail.vue       # 详情：图文/真实坐标地图/付费查看/评价/海报/收藏关注/举报
│   ├── member/index.vue        # 会员：权益/开通/资产/优惠券领取
│   ├── member/orders.vue       # 订单管理
│   ├── member/recharge.vue     # 余额充值（v1.1.0 新增）
│   ├── favorite/index.vue      # 我的收藏（v1.1.0 新增）
│   ├── distribution/index.vue  # 分销：佣金/邀请/团队/提现
│   ├── message/index.vue       # 消息中心
│   ├── mine/index.vue          # 我的
│   └── auth/login.vue          # 认证与登录（身份切换 + 资质）
├── components/                 # fc-navbar / fc-tabbar / fc-post-card / fc-empty
├── common/
│   ├── config/index.js         # 网关地址、开关、常量
│   ├── utils/request.js        # 统一请求层（鉴权/解包/401/降级）
│   ├── utils/{storage,format,pay}.js
│   ├── api/                    # auth/home/post/member/distribution/message/favorite/report/order/pay/coupon/setting/admin
│   ├── constants/report.js     # 举报原因字典（report.js，v1.1.0）
│   ├── assets/                 # 图标注册表（icons.js）+ 轮播取图与主题护栏（banners.js）
│   ├── mock/                   # 79 条 mock 路由 + 数据集（离线可跑）
│   ├── constants/ui.js         # 状态/图标映射
│   └── store/index.js          # 轻量全局状态
├── static/                     # 74 枚图标 + 3 张轮播插画（banners/）+ LOGO
├── docs/                       # 4 份交付文档
└── tests/                      # 零依赖测试与结构校验
```

## 三、快速开始

### 3.1 运行小程序（HBuilderX）

1. 用 **HBuilderX** 打开本目录（项目名为 `fenleixinxi`）。
2. 运行 → 运行到小程序模拟器 → 微信开发者工具（或运行到浏览器 H5）。
3. `manifest.json` 中 `mp-weixin.appid` 已配置为本项目小程序账号 `wxbfcb778f3019cff8`，
   如需换成自己的小程序，请同步修改（并保证后端 `fa_fc_config.wx.appid` 一致，见 README 8.2）。

> 未联调后端时无需任何配置：请求层会在网络不可用时自动降级到本地 Mock，**首页、发布、详情、会员、分销、消息、我的全链路均可离线体验**。

### 3.2 切换真实后端

编辑 `common/config/index.js`：

```js
forceMock: false,          // 关闭强制 mock
enableMockFallback: false, // 生产建议关闭降级，暴露真实问题
```

网关默认：`https://fenleixinxi.gzyakj.com.cn/api`（与后台同域）。

## 五、图标与 LOGO 与轮播配图（全部为图片，可后台自定义）

### 5.1 图标体系（配图 v2 · 全图片，真实透明）

- **不使用任何矢量线条图标 / emoji**：全站图标均为 `static/icons/` 下的 **填充插画 PNG**（74 个，192×192，**真实透明通道**）。
- **插画造型**：纯填充色块，形体饱满、笔画厚重；`主色 + 第二色 + 纯白高光` 三档配方，画面干净统一。
- **配图与文字一一对应**：招聘求职→公文包、房产租售→房子、二手闲置→立体包裹箱、车辆买卖→汽车、本地服务→八齿齿轮、教育培训→学士帽、家政保洁→三重闪光、同城交友→爱心。
- **徽章底**：浅色**垂直渐变**圆角块（如 `#E9F7F2 → #D2EFE5`），圆角 31%，与插画形成质感层次。
- **统一注册表**：`common/assets/icons.js` 定义每个图标的 `key / 中文名 / 默认文件`，分 8 组。
- **解析优先级**：后端下发的自定义地址 > `static/icons/` 内置默认图
  - 纯函数层：`common/utils/icon.js`（`iconUrl / logoUrl / categoryIconUrl`）
  - 响应式层：`common/store/ui.js`（模板里直接调用即为响应式，后台改完立即生效）
- **重新生成配图**：修改 `tools/icon-svg.mjs`（`ART` 图形 + `OUTPUTS` 配色/渐变）后执行
  ```bash
  node tools/gen-icons.mjs      # 白底/黑底两遍渲染 + alpha 反解 + 降采样
  node tools/preview-theme.mjs --render   # 出预览图并扫描旧色残留（改主题后必跑）
  ```
  > 品牌色只集中在 `tools/icon-svg.mjs` 的 `OUTPUTS` 与 `uni.scss` 两处：**改主题 = 改这两处 + 重跑上面两条命令**。

### 5.2 首页轮播配图（Banner v2 · 绿底 + 白色插画）

首页轮播由 **1 层后台底色 + 4 层页面绘制的装饰/文字** 叠加而成，**不使用整幅位图 banner**：

```
① 后台渐变底色 color          ② 光晕 + 叶脉斜纹 + 双层远山（仅用中性半透明色）
③ 双圆环 + 白色插画大徽章      ④ 左侧压暗罩（保白字对比度）    ⑤ 文字浮层（标签/标题/CTA）
```

- **白色插画**：`static/banners/banner-art-{1,2,3}.png`（192×192，真实透明，合计 6.0KB），按轮播位置循环：
  ① 立体包裹箱（二手）② 公文包（招聘）③ 屋顶 + 门的小家（本地服务/上门）。
- **主题护栏**：`common/assets/banners.js` 的 `bannerBg(banner, i)` **只认结构完整的渐变**（`linear-gradient(...)` 且含≥2 个色标、以 `)` 收尾）；
  后台若仍是历史暖色纯色（`#FF8A5B` 等）、空值、或被字段宽度截断的半截值，都会自动回落内置春绿渐变 —— 换主题时即使线上数据没同步，
  首页也不会再冒出旧配色（后端可执行 `php think fc:install` 幂等对齐线上库）。
- **金只给价值**：`bannerHasValue()` 为真（「直降 / 免费」）时，圆环右上嵌一颗金色宝石点；平台服务类不带金色。
- **白字对比度实测**：4.93:1（banner 1）、7.09:1（banner 2）、5.86:1（banner 3），均 ≥ WCAG AA 4.5:1。
- **重新生成插画**（仅在调整插画造型/配色时需要）：
  ```bash
  node tools/gen-banner-art.mjs   # SVG → 白底/黑底两遍渲染 + alpha 反解 → 192×192 透明 PNG
  ```
- **后台换整幅位图**：在「轮播管理」填 `image` 后铺满卡面并自动隐藏装饰层（该条轮播无需再用内置插画）。
- **数据库字段**：`fc_banner.color` 已由 `varchar(16)` 扩到 `varchar(255)`（渐变串约 70 字符，16 会被截断成半截值）；
  老库在服务器执行 `php think fc:install` 会自动扩容并把内置 3 条轮播回填为春绿渐变（亮绿 `#00E070` → 深绿 `#046B3B`）。

### 5.3 LOGO

`static/logo.png`（512×512，春绿渐变 `#00E070→#00A855→#046B3B` 圆角方块 + 白色定位针 + 金色分类列表三条），统一用于：
- 小程序**首页左上角**（60rpx）
- **登录页**品牌区（140rpx）
- 后台设置页预览

### 5.4 后台自定义（可替换任意配图与 LOGO）

打开 **我的 → LOGO 与图标设置**（`pages/admin/setting.vue`），或直接访问 `pages/admin/setting`：

| 能力 | 说明 |
| --- | --- |
| 更换 LOGO | 上传图片 → 预览 → 保存，用户端首页/登录页同步生效 |
| 逐个替换配图 | 按分组列出全部 74 个图标，每个可「替换 / 默认」，已改动的显示「已改」角标 |
| 修改小程序名称 | 同步用于登录页标题 |
| 一键恢复 | 单个恢复默认 / 全部恢复默认 |

对应接口（详见 `docs/03-接口文档.md`）：

| 方法 | 路径 | 说明 |
| --- | --- | --- |
| GET | `/setting/ui` | 用户端读取 `{ appName, siteName, logo, servicePhone, aboutUs, shareTitle, icons }` |
| GET | `/admin/setting/ui` | 后台读取（同上 + `updatedAt`） |
| POST | `/admin/setting/ui` | 后台保存 `{ siteName, logo, icons }`（名称/LOGO 写入 `base.*`） |
| POST | `/admin/setting/ui/reset` | 全部恢复默认 |
| POST | `/admin/upload` | 图片上传（multipart，返回 `{ url }`） |

## 六、执行测试

```bash
sh tests/run.sh
# 等价于依次执行：
#   1) node tests/validate.mjs   项目结构校验（路由/.vue 标签/SCSS 括号/import 依赖）
#   2) node tools/check-scss.cjs 用 dart-sass 编译全部 SCSS
#   3) node tests/run.mjs        全链路接口测试（179 例）
```

## 七、设计主色调（春绿 · Spring Green）

| Token | 色值 | 用途 |
| --- | --- | --- |
| 品牌亮绿（主色） | `#00E070` | **面**：主按钮底、徽章、胶囊、选中态、轮播底（= 后台登录页同一品牌色号） |
| 亮绿上的字 | `#04301E` | 亮绿面上的文字（**8.2:1**；白字压亮绿只有 1.8:1，故一律不用白字） |
| 白字安全绿 | `#04874A` | 白字区（头部 / Hero / 渐变收尾，**4.6:1**）；也是白底绿字、描边按钮用色 |
| 主色渐变（亮绿面） | `#00E070 → #00C860 → #00B85C` | 主按钮、选中态、指示条（配墨绿字） |
| Hero 渐变（深绿面） | `#04874A → #046B3B → #023A21` | 首页头部、我的 / 会员 / 分销头部、渐变导航条（配白字） |
| 深绿 / 极深绿 | `#046B3B` / `#023A21` | 会员资产卡、白字区收尾 |
| 辅助色（金） | `#F5A623` | 会员、热度、价格（只给「值得关注」的信息） |
| 页面底色 | `#F2FEF7` | 薄荷白底 |
| 主文字 | `#04291C` | 墨绿黑（替代纯黑） |

> 设计立意：**春绿立品牌、收获金点价值** —— 亮绿只做「面」（按钮 / 徽章 / 胶囊 / 轮播底）并统一配墨绿字，
> 白字只落在 `#04874A` 及更深的绿面上；「绿=平台与内容、金=价值与特权」仍是品牌记忆点。
> 90 分钟可复核：`node tools/preview-theme.mjs --render` 出图 + `node tools/run.mjs` 的「亮绿面不得配白字」回归用例。

配色自检 / 预览出图（改配色后必跑）：

```bash
node tools/preview-theme.mjs --render   # 首页仿真 + 全量令牌色板；并自动扫描旧色残留
```

详见 [`docs/02-UI设计规范.md`](docs/02-UI设计规范.md)。

## 八、当前验证状态

```
[1/3] 项目结构校验    : 错误 0，警告 0
[2/3] SCSS 编译校验   : 通过 19 个，失败 0（dart-sass）
[3/3] 全链路接口测试  : 用例总数 179   通过 179   失败 0   （通过率 100%）
      —— 含 配图完整性与后台自定义闭环 16 例 + 轮播配图与主题护栏 17 例
      —— 含 v1.0.7 新增：我的发布 / 发布配置与计费 / 后台置顶闭环 14 例
      —— 含 v1.1.0 新增：支付 / 上传 / LBS / 收藏关注 / 举报 / 充值 / 优惠券 28 例
      —— 含 v1.1.1 新增：真实数据对接回归 12 例（区域/未读/详情评价/最低提现/去 mock_code 等）
```

| 视觉资源 | 状态 |
| --- | --- |
| 配图数量 | 74 / 74（192×192，真实透明，尺寸统一） |
| 轮播插画 | 3 / 3（192×192 白色插画，合计 6.0KB） |
| 静态资源体积 | `static/` 616K（`icons/` 492K + `banners/` 12K[实际 6.0KB] + LOGO） |
| 小程序包体积 | 约 1.3M（主包上限 2M，余量充足） |
| 字号体系 | 24 / 26 / 28 / 32 / 36 / 42rpx（六档，跨度 1.75×） |

### 8.1 后端接口（线上真实环境）

后端 v1 业务接口已实现并部署到 `https://fenleixinxi.gzyakj.com.cn/api/v1`，
与本前端 `common/api/*.js` 的端点**逐一对应**（`application/route.php` 共 73 条：用户端 41 + 后台 32），契约见 `docs/03-接口文档.md`。

```
后端接口端到端验证（tools/verify-api.mjs）
用例总数: 226   通过: 226   失败: 0
  —— 端点契约 + 业务规则文案比对 + 8 步双端业务闭环
     （用户发布 → 后台待审 → 后台审核 → 前台可见 → 消息通知 → 操作留痕）
  —— v1.1.0 新增 39 例：媒体上传 / LBS / 收藏关注 / 举报 / 充值 / prepay / 回调 / 优惠券 / 发布回读
```

**后端种子数据与本前端 `common/mock/data.js` 逐字段对齐**，因此把
`common/config/index.js` 的 `forceMock` 关闭后，页面数据与离线演示完全一致。

> 切真实后端：将 `common/config/index.js` 的 `enableMockFallback` 置为 `false`
> （生产建议关闭降级，以便暴露真实问题）。

### 8.2 小程序线上发布记录

| 项 | 值 |
| --- | --- |
| AppID（前端 `manifest.json`） | `wxbfcb778f3019cff8` |
| AppSecret（仅后端持有） | `fa_fc_config.wx.secret`（**不下发前端**，仅服务端 `jscode2session` 调用） |
| 上传包体积 | **788.0 KB**（v1.0.7 上传实测，CLI 输出 806,887 字节；本地 173 文件 `wc -c` 合计 751,376 字节；v1.0.4 738,797 字节；主包上限 2MB，余量充足） |
| 待上传 | **v1.0.9**（173 文件 / 755,921 字节）已本地构建完成，正在等待开发者工具登录（本轮上传时登录态过期，报 `code 10 需要重新登录`）；v1.0.8 构建完成但未上传，其改动已全部包含在 1.0.9 中，随 1.0.9 一并上传 |
| 上传状态 | v1.0.7 已于 2026-10-15 上传成功（`✔ Using AppID: wxbfcb778f3019cff8` → `✔ upload`，TOTAL 788.0 KB / 806,887 字节）；v1.0.6 同日上传成功：`✔ Using AppID: wxbfcb778f3019cff8` → `✔ upload`（待人工在 mp 平台设为体验版 / 提交审核，并确认请求合法域名 `https://fenleixinxi.gzyakj.com.cn`） |
| 构建方式 | 生产构建（`unpackage/dist/build/mp-weixin`，无 sourcemap） |
| 接口指向 | `https://fenleixinxi.gzyakj.com.cn/api`（线上真实后端） |
| 产物校验 | 13 页面（含 `pages/post/mine`）· 74 配图 + 3 轮播插画 + LOGO · 春绿令牌已编译（`--fc-primary:#00e070`、主按钮 `linear-gradient(135deg,#00e070,…)`、头部 `linear-gradient(150deg,#04874a,#046b3b 55%,#023a21)`）· appid 正确 |

| 版本 | 时间 | 内容 |
| --- | --- | --- |
| **1.0.0** | 2026-10-15 | 首个完整版本：用户端 9 大模块 + 后台管理端 10 大模块 |
| **1.0.1** | 2026-10-15 | 修复「后台改完前端不变」：关闭 mock 静默降级、首页 `onShow` 强制刷新后台配置 |
| **1.0.2** | 2026-10-15 | 打通余额支付：详情页新增「余额支付/微信支付」选择器；默认支付方式可配置 |
| **1.0.3** | 2026-10-15 | 修复发布页分类图标：原先把图标地址当文本显示（8 条路径重叠），改为 `image` 正常渲染 |
| **1.0.4** | 2026-10-15 | 小程序账号同步：AppID 由 `wxf611d31accda42e8` 更新为 `wxbfcb778f3019cff8`；前端 `manifest.json` 与后端 `fa_fc_config.wx.appid/wx.secret` 双端一致 |
| **1.0.5** | 2026-10-15 | 生态绿主题收尾 · **首页轮播配图重做**：后台底色 + 光晕/叶脉/远山装饰 + 双圆环白色插画大徽章 + 左侧压暗罩 + 文字浮层五层结构；白字对比度实测 ≥ 4.93:1；前端新增 `bannerBg()` 主题护栏（旧暖色纯色自动回落生态绿），后端 `FcInstall::BANNERS` 统一种子并新增幂等底色升级；新增 14 条轮播自动化用例（总用例 116，全绿） |
| **1.0.6** | 2026-10-15 | **春绿主题 v4（全站换色）**：品牌主色改为设计稿亮绿 `#00E070`（只做「面」，面上统一墨绿字 `#04301E` 8.2:1）；新增 `$fc-primary-ink` / `$fc-primary-text` / `$fc-gradient-hero` 三枚令牌，白字只保留在深绿 Hero 与深绿渐变上；**74 枚图标 + LOGO + 3 张轮播插画全量重配春绿**；轮播卡由「绿底白字」改为「亮绿底 + 墨绿字 + 右侧深绿白插画」（105deg），实测最差对比度 4.71:1；页面底色 `#F2FEF7`、正文 `#04291C`；新增 3 条主题回归用例（总用例 119，全绿） |
| **1.0.7** | 2026-10-15 | **发布侧三件事（缺陷 + 两个新功能）**：① **「我的发布」页上线**——原先「我的」页入口指向 `/pages/post/list`（分类信息列表，只显示别人审核通过的信息），用户发完**看不到自己的发布记录**，现新增 `GET /post/mine`（按 全部/待审核/已通过/已驳回/已下架 筛选 + 各类计数 + 驳回原因）与 `pages/post/mine.vue`，发布成功后直接跳转该页；② **后台手动置顶**——`fc_post.is_top` 正式接入用户端：后台「信息管理」新增「置顶/取消置顶」（工具栏批量 + 行内按钮 + 状态徽章，附站内消息通知），`Home::feed` 与 `/post/mine` 均按 `is_top desc` 排序，卡片显示「置顶」角标；③ **免费/付费发布开关**——后台新增「发布与费用配置」页（同城业务 → 基础数据）：发布模式（免费发布 / 付费发布）+ 会员单条发布价格 + 按月（价格 + 含条数）+ 按年（价格 + 含条数），保存后同步会员套餐（月卡 M1 / 年卡 M12）；`fc_user_ext` 新增发布额度 `post_quota_left`，开通月/年卡自动发放额度、额度内免费发布（付费模式下仍保留「每日免费条数」避免硬付费墙）；④ **计费改为服务端定价**（BUG-012）：原先发布金额由前端 `amount` 传入并被后端直接采信，客户端可改价（0.01 元发帖），现金额一律按后台配置在服务端计算；新增 15 条用例（总用例 134，全绿） |
| **1.0.8** | 2026-10-16 | **会员手机号真绑定 + 后台会员列表字段调整**：① **修复「手机号授权绑定」假实现**（BUG-013）——原先登录页点击绑定只在前端拼 `138 + 时间戳` 的假号、从不落库，导致微信注册会员 `fa_user.mobile` 恒为空、后台会员列表手机号大面积为空；现改为 `<button open-type="getPhoneNumber">` 调用新增的 `POST /auth/wx-phone`（后端用小程序 access_token 调微信 `phonenumber.getPhoneNumber` 真实取号并写入 `fa_user.mobile`，access_token 带缓存），微信侧不可用时自动回落手动输入 `bind-phone`；② **后台会员列表**按要求去掉「角色组 / 电子邮箱 / 等级」三列，手机号列前置并**全量展示**：未绑定号时回落显示该会员最近一条发布信息里的联系电话并标注「来自发布信息」（`mobile_source=post`），两者都无显示「未绑定」；③ 后台 JS 变更后 bump `site.version` 强制刷新浏览器静态资源缓存；新增 2 条用例（总用例 136，全绿） |
| **1.0.9** | 2026-10-16 | **采集会员微信昵称与头像**（BUG-014）：微信自 2022 年已回收主动拉取资料接口，登录页改用官方 `open-type="chooseAvatar"` + `<input type="nickname">` 由用户授权采集，登录时随 `wx-login` 提交；新增 `POST /auth/avatar`（用户端 multipart 上传头像，落盘并写 `fa_user.avatar`）与 `POST /auth/profile`（随时补填资料）；后台「会员列表」昵称/头像列由此显示真实微信资料（无头像仍显示字母头像）；另含 v1.0.8 的会员手机号真绑定与列表字段调整。新增 3 条用例（总用例 139，全绿） |
| **1.1.0** | 2026-10-17 | **支付闭环 + 媒体上传 + LBS + 互动 + 优惠券 + 后台看板/设置**：① **微信支付改用 epay 插件承载（插件下单 + 插件验签，本地业务编排在 `api/Pay`）**——新增 `POST /pay/prepay`、`POST /pay/notify`：下单走 `\addons\epay\library\Service::submitOrder(..., 'miniapp', $openid)`，验签与应答由插件 `checkNotify()` / `$pay->success()` 生成；商户号/密钥真源为**插件配置**（`addons/epay/config.php`，后台「插件管理 → 微信支付宝整合插件 → 配置」），回调地址按当前请求域名动态生成、回调新增金额核对；`/post/{id}/pay-view`、`/member/open`、`/order/recharge` 微信支付统一改为**只落 `pending` 订单**、由回调置 `paid` 并分派后续动作（会员发放 / 余额入账 / 付费解锁），回调幂等；修复 **BUG-015**（`Pay::notify()` 与基类站内信 `notify()` 同名签名不兼容导致 `/pay/*` 全 500，动作改名 `notifyCallback()`）；② **发布媒体真上传**——新增 `POST /post/upload`（图片 ≤10MB / 视频 ≤50MB），发布页 `uni.uploadFile` 真上传并提交 URL 数组；③ **LBS**——`fc_post` 增 `lat`/`lng`，首页 `uni.getLocation` + `sort=nearby`（按距离升序、无坐标排最后）、卡片显示 `distance`，详情页真实坐标地图；④ **举报**——新增 `POST /report` + 详情页入口（原因字典 `report.reasons`）；⑤ **收藏 / 关注**——新增 `fc_favorite`/`fc_follow` 与 `/favorite/*`、`/follow/toggle`，新增「我的收藏」页；⑥ **余额充值**——新增 `POST /order/recharge` 与 `pages/member/recharge`（**只允许微信支付**：`payType=balance` 等于用余额给余额加钱、余额只增不减，会凭空增发余额，属资损漏洞，已禁止并加用例守护）；⑦ **优惠券**——新增 `fc_coupon`/`fc_user_coupon`、后台 CRUD（`fc/coupon`）、用户领取（`/coupon/*`）与资产展示（**不含下单抵扣**）；⑧ **发布折扣**——单条付费按 `member.benefit.postDiscount` 折扣计价（BR-16）；⑨ **后台 PC**新增「数据总览」`fc/dashboard`（核心看板 + 近 14 天趋势，置首）、「系统设置」`fc/setting`（仅基础配置 `base.*`，支付配置改由插件页维护）、「优惠券管理」`fc/coupon`，商家表单增店铺头图/公告/推荐位；`site.version` → `1.7.0.20261017`。新增 28 条用例（**总用例 167，全绿**），后端端到端 226/226，后台 6 页面 HTTP 200 |
| **1.8.0** | 2026-10-22 | **服务区域改为平铺结构 + 后台级联/地图选点**：① `fc_area` 每条记录直接保存 `province` / `city` / `district`（区县为最终服务区域），不再有 `parent_id` / `level` 层级记录；`fc_post` / `fc_draft` 用 `district_id` 关联服务区域；`fc:install` 幂等补列并把历史层级数据压平（区县保留原 ID）；② 后台「服务区域」改为省 / 市 / 区县三列维护，校验必填与「省+市+区县」唯一；③ **后台行政区采用省→市→区县级联下拉**（可下拉选择或直接输入新增），中心经纬度支持**腾讯地图选点**（复用 address 插件）；④ 新增 `GET /home/locate` 按定位匹配最近服务区域；⑤ 新增 `FcAreaPicker` 三级级联下拉组件，首页/分类页筛选与发布页统一使用；信息流只按 `areaId` 筛选，定位默认匹配区县；⑥ 新增/更新区域相关用例 |

> **升级到 1.8.0**：在项目根目录执行 `php think fc:install`（幂等），会自动把 `fc_area` 压平为「省 / 市 / 区县」三列、把 `fc_post` / `fc_draft` 关联到 `district_id`，历史区县保留原 ID；随后到后台「系统设置 → 服务区域」维护各省 / 市 / 区县。

**生产构建命令**（无需 HBuilderX GUI，复用同级项目的 uni-app 工具链）：

```bash
OLD="/Users/linda/Desktop/project/uni-preset-vue-vite-ts  shanchan/uni-preset-vue-vite-ts  shanchan"
NEW="/Users/linda/Desktop/project/uni-preset-vue-vite-ts  shanchan/fenleixinxi"
cd "$OLD" && \
UNI_INPUT_DIR="$NEW" \
UNI_OUTPUT_DIR="$NEW/unpackage/dist/build/mp-weixin" \
NODE_ENV=production node_modules/.bin/uni build -p mp-weixin
```

**上传命令**：

```bash
# 建议先复制到干净目录再上传：微信工具会缓存项目路径，
# 若产物目录被 rm -rf 重建过，直接用原路径会报「未找到 app.json」
rm -rf /tmp/fcmp && cp -R "$OUTPUT_DIR" /tmp/fcmp
/Applications/wechatwebdevtools.app/Contents/MacOS/cli upload \
  --project /tmp/fcmp -v 1.0.4 -d "版本描述"
# 端口无需指定：CLI 会自动探测本机运行中的微信开发者工具（本项目实测 127.0.0.1:63622）；
# 但开发者工具必须用「拥有该 AppID 的微信号」登录，否则会上传失败。
# 日志出现 `✔ Using AppID: xxx` + `✔ upload` 即成功。
```

**后续需在 mp.weixin.qq.com 手动完成（CLI 无法代劳）**

> ⚠️ `wxbfcb778f3019cff8` 是**新账号**，以下两项都要在新账号后台重新配置，旧账号的配置不会迁移过来。

1. `开发 → 开发设置 → 服务器域名 → request 合法域名` 添加 **`https://fenleixinxi.gzyakj.com.cn`**
   （否则真机请求会被拦截；开发者工具勾选「不校验合法域名」可临时绕过）
2. `管理 → 版本管理` → 找到对应版本 → **设为体验版**（内测）或 **提交审核** → 审核通过后 **发布**

### 8.3 后台与前端的数据同步机制

> 曾出现「后台改了，前端不变」，原因是 3 处，已全部修复。

| # | 原因 | 修复 |
| --- | --- | --- |
| 1 | **`enableMockFallback: true`**：真实请求失败时请求层静默降级到本地 mock，页面照常显示**假数据**，后台怎么改都不变（最具迷惑性） | 默认改为 `false`；生产压缩时该分支会被常量折叠为死代码并消除 |
| 2 | **UI 配置只在首页 `onLoad` 拉一次**：`loadUiConfig()` 内部 `if (loaded && !force) return`，后台改完必须**重启小程序**才生效 | 首页新增 `onShow` 与下拉刷新强制 `loadUiConfig(true)`；store 是 `reactive` 的，配置一变所有页面即时重渲染 |
| 3 | **后台管理界面缺失**：35 个 `/api/v1/admin/**` 接口无任何界面可操作 | 已在 FastAdmin PC 后台补齐 17 个业务模块（见 `docs/05-后端实现规范.md`） |

> 底部导航为自定义组件 `components/fc-tabbar/`（每页 `<fc-tabbar :current="n" />`），
> 因此 `app.json` 中没有原生 `tabBar` 字段，属设计如此。

### 8.4 余额支付测试指引（微信支付未配置时的替代方案）

微信支付尚未配置：商户号/密钥的真源是 **epay 插件配置**（`wechat.miniapp_id`/`wechat.mch_id`/`wechat.key`），当前为空，因此**测试阶段统一走余额支付**。

**① 支付方式由一处开关控制**

`common/config/index.js`：

```js
// 'balance' 余额支付 / 'wxpay' 微信支付
defaultPayType: 'wxpay',
```

配置好真实商户参数后改回 `'wxpay'` 即可，**各页面无需改动**（三个支付点都读这个值）。

**② 三个支付点均已支持余额**

| 场景 | 页面 | 说明 |
| --- | --- | --- |
| 会员开通 | `pages/member/index.vue` | 微信/余额选择器 |
| 付费发布 | `pages/post/create.vue` | 微信/余额选择器 |
| 付费查看联系方式 | `pages/detail/detail.vue` | **1.0.2 新增**选择器（原先硬编码微信支付） |

**③ 给用户充值余额（后台操作）**

`FastAdmin 后台 (/s.php) → 同城业务 → 用户与商家 → 会员管理`

1. 列表已直接显示 **昵称 / 手机号 / 账户余额**（关联 `fa_user`）
2. 勾选用户 → 点工具栏 **「余额充值」** → 输入金额 → 确定
3. 系统自动：加余额 + 写资金流水（`fa_fc_finance_flow`）+ 发站内通知（`fa_fc_message`）

> 单次金额需 `>0` 且 `≤100000`。

**④ 余额支付的两种即时性语义**

| 支付方式 | 下单后订单状态 | 说明 |
| --- | --- | --- |
| `balance` | **立即 `paid`** + 记录 `paytime` | 下单即扣款，无需收银台 |
| `wxpay` | `pending` | 由微信支付回调置为 `paid` |

**⑤ 已验证的完整链路**

```
后台充值 ¥200  →  余额 12.00 → 212.00（流水 + 站内信）
会员开通 余额   →  212.00 → 192.10，订单 MO… 月卡 ¥19.90 paid balance
付费发布 余额   →  192.10 → 187.10，订单 PO… ¥5.00 paid balance
付费查看 余额   →   10.00 →   8.00，付费记录 ¥2.00 balance（重复查看不再扣款）
余额不足        →  「余额不足」，余额不变，且**不产生假订单**
```

### 8.5 部署说明（v1.1.0 上线步骤）

1. **推送/部署后端代码**后，在**服务器执行一次**（幂等，可重复执行）：

   > **首次拉取本批改动的特别注意**：`addons/epay`、`addons/wechat`、`public/assets/addons/*` 此前被 `.gitignore` 忽略，
   > 服务器上早就有这些文件却不在 Git 里 → 直接 `git pull` 会报 `untracked working tree files would be overwritten by merge`。
   > 若**已在服务器配置过插件密钥**，先备份 `addons/epay/config.php`（当前为空白模板）：

   ```bash
   cd /www/wwwroot/fenleixinxi.gzyakj.com.cn
   cp addons/epay/config.php /root/epay-config.bak           # 只有已配置过才需要
   rm -rf addons/epay addons/wechat public/assets/addons/epay public/assets/addons/wechat
   git pull
   cp /root/epay-config.bak addons/epay/config.php           # 上面备份过的才需要复原
   git update-index --skip-worktree addons/epay/config.php   # 之后服务器改插件配置不再污染 git 状态
   php think fc:install          # 不带 --reset，常规上线勿带
   ```

   该命令会**幂等补齐**本轮新增结构：建 4 张新表（`fa_fc_favorite` / `fa_fc_follow` / `fa_fc_coupon` / `fa_fc_user_coupon`）、
   补列（`fa_fc_post.lat` / `lng`，`fa_fc_merchant.banner` / `notice` / `recommend`）、
   补配置（`coupon.enabled` / `report.reasons`；**支付配置不在其中**，改由 epay 插件配置维护）、
   补后台菜单与权限节点（业务总览 / 系统配置 / 优惠券）。小程序、发布、分销配置作为「系统配置」页的分组 Tab，不再单列菜单；
   **已存在的列 / 配置一律跳过，不覆盖运营已改的值**；
   菜单与权限节点按 `name` **对齐标题/上级/排序**（若在后台改过菜单名，会被重置回默认名；只重建菜单可单独执行 `php think fc:menu`）。
   从 v1.1.0 起它还会**清理插件钩子缓存 `hooks`**：`application/extra/addons.php` 的钩子会被 File 缓存，
   若该缓存是在「插件目录还不存在」时生成的，插件启用后也不会被加载（症状：微信支付报 `Class 'Yansongda\Pay\Pay' not found`）。
   同时清理后台左侧菜单缓存 `__menu__`（`Auth::getSidebar()` 依赖它，否则新菜单要等缓存过期才显示）。
   手工兜底：删除 `runtime/cache` 目录即可重建。

2. 后台 JS/视图/CSS 变更已通过 bump `site.version`（`1.7.0.20261017`）强制刷新浏览器静态资源缓存。

3. **微信支付真机联调前置**：在后台「插件管理 → 微信支付宝整合插件 → 配置」填写 `wechat.miniapp_id`（**小程序 AppID，必须填这一项**）、`wechat.mch_id`（商户号）、`wechat.key`（v2 密钥）；
   未配置时 `/pay/prepay` 会返回「微信支付未配置」，`/pay/notify` 返回 SUCCESS 但不处理（余额支付不受影响）。

4. 小程序侧为 **1.1.0**（`manifest.json` `versionName=1.1.0` / `versionCode=110`），新增页面 `pages/favorite/index`、`pages/member/recharge` 已注册进 `pages.json`。

5. **插件已入库**：`.gitignore` 已移除 `/addons/*` 与 `/public/assets/addons/*`，`addons/epay`、`addons/wechat` 与 `public/assets/addons/{epay,wechat}` 现由 git 跟踪（`addons/epay` 即微信支付宝整合插件源码，无需在服务器另行放置插件包）。

6. **重要提示（插件密钥防冲突）**：插件的商户号/密钥保存在 `addons/epay/config.php`，该文件已入库（当前为**空白模板**）；在服务器上通过后台配置后该文件会被改写，为避免 `git pull` 冲突，请在服务器上执行 `git update-index --skip-worktree addons/epay/config.php`；**切勿把填了真实密钥的该文件提交到仓库**。

7. **插件 API 版本必须保持 `v2`**：站点与服务器均为 PHP 7.4，插件配置里的 `version` 只能用 `v2`（V3 版本要求 PHP 8.0+ 且需上传 API 证书）；
   `addons/epay/certs/*.pem` 是插件自带的**空白占位文件**，V2 支付（JSAPI 统一下单 + 回调验签）用不到它们，无需处理。