fenleixinxi/uniapp

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

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

---

一、交付物索引

交付物	文件	说明
① 功能模块清单（PM）	docs/01-产品功能模块清单.md	用户端 + 后台管理端模块清单、优先级、业务规则、接口映射
② UI 设计规范（UI）	docs/02-UI设计规范.md	春绿设计令牌、排版、组件、动效规范
③ 接口文档（前后端）	docs/03-接口文档.md	75 个接口（用户端 43 + 后台 32）字段级契约 + Mock 兜底机制 + 联调清单
④ 全链路测试报告（QA）	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：

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 配色/渐变）后执行

  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。
• 重新生成插画（仅在调整插画造型/配色时需要）：

  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 }）

六、执行测试

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 的「亮绿面不得配白字」回归用例。

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

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

详见 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 工具链）：

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

上传命令：

# 建议先复制到干净目录再上传：微信工具会缓存项目路径，
# 若产物目录被 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：

// '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（当前为空白模板）：

   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 统一下单 + 回调验签）用不到它们，无需处理。