AGENTS.md 7.9 KB
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字段映射
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 中导入该目录