Home Esplora Aiuto
Registrati Accedi
liaoxg
/
cfc
1
1
Forka 0
File Problemi 0 Pull Requests 0 Wiki
Albero (Tree): aafc8d5748
Rami (Branch) Tag
cfc
/
cfc-frontend
/
AGENTS.md

AGENTS.md 8.1 KB
Cronologia Originale

zxyj-frontend

uni-app 微信小程序前端，Vue 2 语法，家庭教育任务管理。

WHERE TO LOOK

Task Location Notes
页面组件 pages/*/ login, index, tasks, rewards, profile, guide, games等
页面注册 pages.json TabBar配置和页面路径
应用配置 manifest.json AppID: wx5ba8038ef16fb245
全局样式 uni.scss SCSS变量和全局样式
应用入口 App.vue 全局生命周期和配置
组件库 components/ 地址选择器、任务卡片等可复用组件
API配置 config/ baseUrl和请求封装

STRUCTURE

主包（主包 = pages.json 的 pages 数组）

仅含 5 个 TabBar 页面，主包大小已压缩至 ~1MB 以下：

路径 说明
pages/index/index 首页（未登录态引流页 + 角色路由跳转）
pages/mind/index 心维度首页
pages/body/index 身维度首页
pages/wisdom/index 智维度首页
pages/wealth/index 富维度首页

登录用户路由：pages/index/index 中 parent-index 和 child-index 已从静态组件改为 redirectTo 跳转到分包页面，不再计入主包体积。

分包（pages.json 的 subPackages 数组，共 45 个）

主要分包（按 root）：

Root 内容
pages/teacher 成长规划师中心（7 页）
pages/guide 任务模板、邀请、绑定等（11 页）
pages/parent 家长端市场、孩子详情（3 页）
pages/child 孩子端任务、心愿（2 页）
pages/tasks 任务列表/创建/审核（4 页）
pages/wishes 心愿管理（3 页）
pages/rewards 心愿单/勋章墙（2 页）
pages/games 小游戏（5 页）
pages/assessment 测评申请/报告（5 页）
pages/dan-assessment DAN 测评上传（1 页）
pages/growth 成长档案（6 页）
pages/shop 商城（15 页）
pages/vendor 服务商入驻/管理（5 页）
pages/health 健康功能（18 页）
pages/mind-detail 心智详情（11 页）
pages/body-detail 身体详情（6 页）
pages/wisdom-detail 智慧详情（4 页）
pages/action-detail 行动详情（4 页）
pages/tianpan 家庭天盘（6 页）
pages/article-center 文章中心（4 页）
pages/activity 活动（3 页）
pages/promotion 财富中心/推广（6 页）
pages/membership 会员（3 页）
pages/index 原主包页面（parent-index, child-index, member-home-detail）
pages/login 登录页
pages/share 健康足迹
pages/profile 个人中心（profile + index）
pages/profile-extra 孩子管理/优惠券（6 页）
... 共 45 个分包 详见 pages.json

注意：分包页面在首次访问时异步下载，主包只加载必要的 TabBar 页面，确保主包 < 1.5MB。

TabBar 配置

pages.json 中定义 5 个 TabBar 页面（TabBar 文案，非五维维度名）：

  • 首页: pages/index/index - 角色分流入口
  • 身: pages/body/index - 身体健康维度
  • 智: pages/wisdom/index - 智慧维度（心智测评）
  • 心: pages/mind/index - 心理/情感维度
  • 我的: pages/profile/profile - 个人设置和积分

CONVENTIONS

  • Vue 2: 使用 Options API，生命周期 onLoad、onShow
  • 页面注册: 新页面必须在 pages.json 中注册
  • 导航: 使用 uni.navigateTo、uni.redirectTo
  • API 调用: 使用 uni.request，统一在 config.baseUrl
  • 地址选择: 使用 components/address-picker.vue 四级联动组件
  • 角色切换: 页面根据用户角色显示不同内容

ANTI-PATTERNS

  • DO NOT 创建页面后忘记在 pages.json 注册
  • DO NOT 硬编码 API 地址，使用 config.baseUrl
  • DO NOT 在前端存储敏感信息 (密码、密钥)
  • NEVER 跳过 JWT 认证直接调用需登录接口
  • NEVER 在本地存储中保存敏感用户信息
  • NEVER 在 WXML/Vue 模板中使用可选链 ?.，微信小程序不支持 → 使用 && 代替（如 currentWish?.title 改为 currentWish && currentWish.title）
  • NEVER 在 :class 绑定中调用方法（如 :class="getStatusClass(item)"），微信小程序模板编译器不支持带参数的方法调用 → 改用内联表达式（如 :class="'status-' + item._cssClass"）或计算属性
  • NEVER 在 CSS 类名、选择器中使用中文（如 .val-偏高、.badge-低风险），微信小程序 wxss 编译器不支持中文类名 → 使用英文（如 .val-high、.badge-low），数据中的中文状态通过 _cssClass 字段映射
  • NEVER 在 :key 中使用表达式（如 :key="item.id || item.circleId"），微信小程序模板编译器不支持带运算符的 :key 绑定 → 改用方法调用（如 :key="getItemKey(item)"，在 methods 中定义 getItemKey(item) { return item.id || item.circleId }）

UNIQUE FEATURES

  • 地址匹配页面: pages/match/street-match.vue - 街道地址匹配功能
  • 地址编辑页面: pages/family/address-edit.vue - 家庭地址管理
  • 四级地址选择: components/address-picker.vue - 省市区街道联动
  • 双角色界面: 根据用户角色(parent/child)显示不同UI

BUILD SYSTEM

依赖约束（2026-07-23 修复后锁定）

包 版本 原因
@vue/cli-service ~4.5.0 v5 使用 webpack 5，@dcloudio/uni-mp-weixin 依赖 webpack/lib/GraphHelpers（webpack 4 特有）
@vue/cli-plugin-babel ~4.5.0 与 cli-service v4 匹配
postcss (override + dependency) 7.0.39 remove-scoped.js 在 PostCSS 8 下会走 v8 插件路径，但 spaces 属性访问有兼容问题
node-sass (devDependency) @dcloudio/vue-cli-plugin-uni 内置的 sass-loader 需要
copy-webpack-plugin ^5.1.2 与 cli-service v4 的 webpack 4 兼容

postinstall 自动补丁

npm install 后会自动运行 postinstall-fix.js，修补 remove-scoped.js 中的 spaces 崩溃：

// 问题: selector.first 可能为 undefined
// 修改前: selector.first.spaces.before = '';
// 修改后: if (selector.first) { selector.first.spaces.before = ''; }

已知编译错误处理

错误 原因 处理
Cannot read properties of undefined (reading 'spaces') in remove-scoped.js PostCSS 节点没有 spaces 属性 postinstall-fix.js 自动补丁
Cannot find module 'webpack/lib/GraphHelpers' @vue/cli-service v5 的 webpack 5 不支持 保持 @vue/cli-service ~4.5.0
Cannot find module 'node-sass' uni-app sass-loader 需要 npm install node-sass --save-dev
getPreCompileOptions DevTools 内部错误 dist/dev/mp-weixin/ 缺少 project.config.json 先 npm run build:mp-weixin 生成 dist
Unexpected token in .vue JS 语法错误，常见于方法被截断/拼接错误 检查 v-on:click/方法调用是否正确闭合

修改 remove-scoped.js 的风险

该文件在 node_modules/@dcloudio/vue-cli-plugin-uni/ 内，每次 npm install 会通过 postinstall-fix.js 自动恢复补丁。如需手动执行：

node postinstall-fix.js

不要将 @vue/cli-service 升级到 v5，除非：

  • @dcloudio/uni-mp-weixin 确认移除了 webpack/lib/GraphHelpers 依赖
  • 或者找到替代方法处理独立分包插件

COMMANDS

npm install             # 安装依赖（自动运行 postinstall-fix.js）
npm run dev:mp-weixin   # 开发模式 (微信小程序)
npm run build:mp-weixin # 构建生产版本（仅生成 dist，不在 DevTools 里编译）

NOTES

  • 小程序AppID: wx5ba8038ef16fb245
  • 后端API地址: 配置在 config/index.js 的 baseUrl
  • 地址数据: 使用后端街道API获取四级地址数据
  • 调试工具: 微信开发者工具需配置合法域名
  • 不要在 WeChat DevTools 里直接编译源码，先 npm run build:mp-weixin 生成 dist/dev/mp-weixin/，然后在 DevTools 中导入该目录