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/
├── index/          # 首页（角色分流）
├── login/          # 登录页
├── tasks/          # 任务管理
├── rewards/        # 心愿单
├── profile/        # 个人中心
├── guide/          # 成长规划师功能
├── games/          # 小游戏
└── parent/         # 家长专属功能

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 字段映射

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 中导入该目录

AGENTS.md 5.9 KB Histórico Raw