miniprogame-new

Imported from Yiattitude/miniprogame-new (AGENTS.md). Install upstream with npx skills add Yiattitude/miniprogame-new. Copyright stays with the author.

AGENTS.md

项目概述

本项目为基于 uni-app 框架开发的微信小程序，核心功能为「志愿服务积分申报」与「荣誉获奖积分申报」，面向普通用户（老同志）和管理员双角色，严格遵循微信小程序平台运营规范、《个人信息保护法》，适配老同志操作习惯，确保上线零驳回。

核心目标

1. 实现老同志便捷申报志愿服务、荣誉获奖并查看积分；
2. 实现管理员批量导入数据、审核申报、一键导出全量数据；
3. 100% 符合微信官方授权、内容安全、隐私保护等合规要求。

AI编程 核心规则

2. 每一项编程任务完成后，必须用通俗简明的语言，向你完整说明任务的实现逻辑、核心流程与关键细节，确保你能清晰理解代码的运行原理与使用方式。
3. 中文回答
4. 所有操作始终以你的需求为核心，严格遵循你指定的技术栈、编码规范与业务边界，不擅自偏离需求、新增冗余功能。
5. 接到编程需求后，第一时间拆解需求边界，先向你确认 3 项核心信息：最终业务目标、代码运行环境、技术栈 / 版本限制，确认无误后再启动代码开发，禁止无确认直接生成代码。
6. 若需求存在歧义、模糊地带，或有多种可行实现方案，必须先列出 2-3 种主流方案，同步说明各方案的优劣、适用场景、开发成本，征得你选定方案的明确意见后，再推进开发。
7. 坚持最小可用原则，优先实现核心需求，不擅自添加你未提及的冗余功能、额外第三方依赖；若必须引入依赖，必须提前向你说明依赖名称、版本、核心用途，征得同意后再使用。
8. 注释要求(中文注释)：
   • 每个页面、组件、函数必须添加 /** 注释 */ 说明用途。
   • 复杂逻辑、表单校验、权限判断、接口请求必须添加行内注释。
   • 数据来源、状态更新、页面跳转必须标注注释。
   • 表单字段、积分规则、权限判断必须注释说明规则。

技术栈

表格

开发规范

1. 代码规范

• 严格遵循 ESLint + Prettier 配置，提交前自动格式化；
• Vue 3 组件使用 <script setup> 语法，组合式 API 编写逻辑；
• 变量命名清晰，避免缩写，如 userInfo 而非 uInfo；
• 函数注释明确输入输出、功能说明，复杂逻辑添加行内注释。

2. 组件与页面规范

• 组件命名：大驼峰式，如 VolunteerCard.vue、AuditList.vue；
• 页面命名：小写 + 连字符，如 volunteer-service.vue、my-page.vue；

4. 样式规范

• 全局样式在 App.vue 中引入，页面样式使用 scoped 避免污染；
• 优先使用 uView Plus 组件样式，自定义样式通过深度选择器 /deep/ 或 ::v-deep 修改。

核心功能模块开发指南

1. 首页（home.vue）

• 页面结构：

  • 顶部：自定义标题；
  • 中部：两个功能入口卡片（志愿服务、荣誉获奖），点击跳转对应模块；
  • 底部：全局导航栏（首页、我的）。

• 交互逻辑：

  • 导航栏切换使用 uni-app switchTab（需在 pages.json 中配置 tabBar）；
  • 页面加载时通过 Pinia 获取用户总积分，展示在首页顶部（可选增强体验）。

2. 志愿服务模块（volunteer-service/）

（1）子模块列表页（volunteer-list.vue）

• 展示 5 个子模块：传承红色文化（关心下一代）、参与基层治理、服务企业发展、实施以老助老、其他服务；
• 每个子模块点击跳转「积分说明 + 打卡 / 打卡记录」页，携带模块标识（如 moduleId: 'red-culture'）。

（2）积分说明与功能选择页（volunteer-detail.vue）

• 顶部：根据模块标识展示对应积分说明（从积分规则表读取，见下文「积分规则嵌入」）；
• 中部：两个按钮（打卡、打卡记录），点击跳转对应页面。

（3）打卡页面（volunteer-checkin.vue）

• 表单字段（全部必填，带 * 标注）：

  • 活动时间（uView Plus u-datetime-picker 组件）；
  • 活动地点（输入框）；
  • 活动名称（输入框）；
  • 参与内容（多行输入框）；
  • 申报积分（输入框，根据模块限制数值范围：如传承红色文化限制 3-10 分，参与基层治理限制 1-5 分，超出范围提示「请输入符合规则的积分」）；
  • 上传佐证材料（uView Plus u-upload 组件，单张≤10M，最多 9 张）。

• 微信合规逻辑：

  • 上传佐证材料仅在用户点击上传按钮时申请相册 / 相机权限；
  • 提交前先调用后端接口，后端触发微信 msgSecCheck（文本）和 imgSecCheck（图片）校验；
  • 校验通过后进入待审核列表，校验不通过弹窗提示修改。

• 提交后逻辑：引导用户订阅审核结果通知（调用 uni.requestSubscribeMessage）。

（4）打卡记录页面（volunteer-records.vue）

• 顶部：年度切换器（uView Plus u-picker 组件）；
• 中部：列表展示（uView Plus u-list 组件），按年度倒序展示「活动名称 + 审核通过积分」；
• 点击单条记录跳转详情页，展示活动时间、地点、内容、审核状态、佐证材料。

3. 荣誉获奖模块（honor-award/）

（1）子模块列表页（honor-list.vue）

• 展示 4 个子模块：国家级荣誉、省部级荣誉、厅局级荣誉、厂处级荣誉；
• 点击跳转「荣誉申报页」，携带荣誉级别标识（如 level: 'national'）。

（2）荣誉申报页（honor-apply.vue）

• 表单字段（全部必填，带 * 标注）：

  • 荣誉获奖名称（输入框）；
  • 获取时间（uView Plus u-datetime-picker 组件）；
  • 授奖单位（输入框）；
  • 荣誉积分（自动填充，不可修改：国家级 20 分、省部级 16 分、厅局级 12 分、厂处级 10 分）；
  • 上传佐证材料（同志愿服务打卡）。

• 提交逻辑：同志愿服务打卡，先经内容安全校验，再进入审核流程，引导订阅通知。

4. 我的页面（my-page.vue）

• 顶部积分展示：

  • 大字展示「总积分」；
  • 分项展示「志愿服务积分」「荣誉获奖积分」（从 Pinia 读取）。

• 年度积分柱状图：

  • 使用 uView Plus u-charts 或 ECharts 适配版，按年度展示总积分趋势；
  • 支持年度切换，数据从后端接口获取。

• 功能入口列表（uView Plus u-cell-group 组件）：

  1. 我的申请：跳转申请列表页，展示待审核、已通过、已驳回记录，驳回记录可修改重提；
  2. 个人信息：展示姓名、身份证号（脱敏显示，如 张* 310***********1234），修改需提交管理员审核；
  3. 退出登录

5. 管理员功能（admin/）

• 权限隔离：仅后端白名单内的微信 openid 可看到管理员入口，普通用户无感知；
• 入口位置：【底部导航栏】增加「管理后台」入口（仅管理员可见）。

（0）账号与角色管理（高风险操作）

• 用户新增：不提供管理员新增用户能力，用户仅通过首次登录自动建档。
• 用户删除：默认采用逻辑删除（禁用账号），不直接物理删除历史业绩与审核日志；仅在合规审批通过后执行物理删除。
• 角色层级：建立 super-admin / admin / member 三级角色，仅上级可修改下级角色。
• 系统约束：全系统仅保留 1 个 super-admin。
• 权限边界：仅 super-admin 具备「设置管理员（member -> admin）」与「回收管理员（admin -> member）」权限。
• 风险控制：禁止任何角色自改权限；super-admin 不可被降级。

（1）管理后台首页（admin-home.vue）

• 功能卡片：账号与角色管理、批量数据导入、数据审核、全量数据导出、操作日志。

（2）批量数据导入（admin-import.vue）

• 提供「Excel 模板下载」按钮，模板字段：

  • 志愿服务：用户姓名、身份证号、模块标识、活动名称、时间、地点、参与内容、积分、佐证材料链接；
  • 荣誉获奖：用户姓名、身份证号、荣誉级别、荣誉名称、获取时间、授奖单位、佐证材料链接。

• 「上传 Excel」按钮：选择文件后调用后端接口，后端解析并匹配用户 openid，匹配成功后自动录入，默认审核通过，生成操作日志。

（3）数据审核（admin-audit.vue）

• 顶部标签页：待审核志愿服务、待审核荣誉获奖、已审核、已驳回；

• 列表展示：用户姓名、申报内容、申报积分 / 荣誉级别、提交时间；

• 审核操作：

  • 单条审核：点击进入详情页，可「通过」「驳回（填写原因）」「修改积分」「调整荣誉级别」；
  • 批量审核：勾选多条记录，批量通过 / 驳回；

• 审核完成后，后端调用微信 sendSubscribeMessage 推送通知（用户已订阅的前提下），生成操作日志。

（4）全量数据导出（admin-export.vue）

• 筛选条件：年度、模块 / 荣誉级别、审核状态、用户姓名 / 身份证号；
• 「导出 Excel」按钮：调用后端接口，后端生成 Excel 文件并返回下载链接，生成操作日志。
• 导出字段至少包含：用户姓名、志愿服务总分、荣誉获奖总分、总积分、总排名、业绩明细（含佐证材料链接）。

（5）操作日志（admin-logs.vue）

• 列表展示：操作人、操作时间、操作内容、操作 IP，不可篡改。

积分规则嵌入

将以下积分规则硬编码至前端（或从后端接口获取，便于后续调整），用于表单校验和积分自动填充：

表格

微信官方接口与权限集成

1. 接口集成清单

表格

2. 权限申请铁律

• 禁止页面加载时提前申请权限；
• 用户拒绝权限后，仅在再次触发功能时可重新申请；
• 申请权限前弹窗说明用途，如「需要使用您的相册上传佐证材料，是否允许？」。

安全与合规

1. 数据安全

• 用户敏感信息（姓名、身份证号）前端脱敏展示，后端 AES 加密存储；
• 所有接口请求携带 token，后端校验用户身份；
• 管理员操作日志不可篡改。

2. 隐私保护

• 仅收集「最小必要」信息：姓名、身份证号（实名认证）、申报数据。

测试与上线

1. 测试计划

表格

2. 上线准备

• 提审自检：按照「微信小程序提审自检清单」逐一检查，确保无违规项。

项目交付物

1. 完整的 uni-app 前端代码（含 Git 提交记录）；
2. 后端接口文档（含接口地址、参数、返回值）；
3. Excel 导入模板（志愿服务、荣誉获奖）；
4. 《用户隐私保护指引》文档；
5. 微信小程序提审自检清单；
6. 项目操作手册（面向用户、管理员）。