文件
fenleixinxi/uniapp/README.md

390 行
33 KiB
Markdown

此文件含有模棱两可的 Unicode 字符

此文件含有可能会与其他字符混淆的 Unicode 字符。 如果您是想特意这样的,可以安全地忽略该警告。 使用 Escape 按钮显示他们。

# 同城分类信息小程序(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 统一下单 + 回调验签)用不到它们,无需处理。