outsource/huangye-parking
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
7e08a12d29
huangye-parking/.kiro/specs/huangyan-parking-points/tasks.md
18631081161 7e08a12d29 1
2026-02-28 17:35:49 +08:00

15 KiB
Raw Blame History

实现计划：黄岩停车积分兑换

概述

基于需求文档和设计文档，将实现分为三大部分：后台API服务（.NET 10）、微信小程序前端（uni-app Vue 3）、管理后台（Vue 3 + Element Plus）。任务按增量方式组织，每个任务在前一个任务基础上构建。

任务

  • 1. 后台项目初始化与基础设施

    • 1.1 创建 .NET 10 ASP.NET Core Web API 项目结构

      • 在 server/ 目录下创建解决方案，包含 API 主项目、Domain 领域层、Infrastructure 基础设施层、Tests 测试项目
      • 配置 MySQL 数据库连接（Entity Framework Core + Pomelo.EntityFrameworkCore.MySql）
      • 配置 Redis 缓存连接（StackExchange.Redis）
      • 配置 JWT 认证中间件
      • 配置 FluentValidation 参数校验
      • 配置 Serilog 日志
      • Requirements: 17.14

    • 1.2 创建数据库实体模型和 DbContext

      • 创建所有实体类：User、Store、CouponTemplate、Coupon、PointsRecord、VerifyRecord、Banner、PopupContent、Agreement、PointsRule、Admin
      • 配置 Entity Framework Core DbContext 和实体映射关系
      • 创建数据库迁移脚本
      • Requirements: 17.1-17.13, 18.1-18.12

    • 1.3 编写券码和UID生成的属性测试

      • Property 1: 券码格式正确性 — 对于任意生成的券码，长度为9位，由字母+数字组成，首字符不为'0'
      • Property 2: 券码唯一性 — 对于任意批量生成的N个券码，所有券码互不相同
      • Property 3: UID格式正确性 — 对于任意生成的UID，长度为6位，纯数字，首位不为0
      • Validates: Requirements 16.1, 16.2, 16.3, 1.3

    • 1.4 实现券码生成工具类和UID生成工具类

      • 实现 CouponCodeGenerator.Generate() 方法：9位随机字母+数字，不以0开头
      • 实现 UidGenerator.Generate() 方法：6位随机数字，不以0开头
      • 实现唯一性校验逻辑（数据库查重）
      • Requirements: 16.1, 16.2, 16.3, 1.3

  • 2. 检查点 - 确保所有测试通过

    • 确保所有测试通过，如有问题请向用户确认。

  • 3. 用户认证与第三方加解密模块

    • 3.1 实现微信登录服务

      • 实现 WechatService：调用微信 code2Session 和手机号获取接口
      • 实现 AuthController：POST /api/auth/login（微信手机号登录）、POST /api/auth/logout、GET /api/auth/check-merchant
      • 实现 JWT Token 生成和校验逻辑
      • Requirements: 1.1, 1.2, 1.3, 1.4, 10.1

    • 3.2 编写特来电加解密属性测试

      • Property 4: 特来电数据加解密 Round-Trip — 对于任意有效JSON数据，AES-128-CBC加密后解密应得到原始数据
      • Property 5: 特来电签名验签一致性 — 对于任意消息数据，HMAC-MD5签名后验签应通过；篡改数据后验签应失败
      • Validates: Requirements 14.2, 14.4, 14.5

    • 3.3 实现特来电对接服务

      • 实现 TldService：AES-128-CBC 加解密、HMAC-MD5 签名验签
      • 实现 TldCallbackController：POST /api/callback/tld/charge-order（充电订单推送回调）
      • 实现平台认证 Token 获取和缓存逻辑
      • Requirements: 14.1, 14.2, 14.3, 14.4, 14.5

    • 3.4 编写驿公里加解密属性测试

      • Property 6: 驿公里数据加解密 Round-Trip — 对于任意有效JSON数据，DES加密后解密应得到原始数据；RSA签名后验签应通过
      • Validates: Requirements 15.4

    • 3.5 实现驿公里对接服务

      • 实现 YglService：DES 加解密、RSA 签名验签、请求封装和响应解析
      • 实现优惠券查询、发放、取消接口调用
      • 实现 YglCallbackController：POST /api/callback/ygl/verify（核销回调）、POST /api/callback/ygl/refund（退回回调）
      • Requirements: 15.1, 15.2, 15.3, 15.4, 15.5, 15.6

  • 4. 检查点 - 确保所有测试通过

    • 确保所有测试通过，如有问题请向用户确认。

  • 5. 积分与优惠券核心业务

    • 5.1 编写积分计算和兑换属性测试

      • Property 7: 积分计算正确性 — 对于任意充电金额和积分规则，计算结果应等于 floor(充电金额/规则金额)*规则积分值
      • Property 8: 积分兑换校验正确性 — 余额>=所需积分时兑换成功且余额减少，余额<所需积分时拒绝且余额不变
      • Property 9: 优惠券兑换不变量 — 兑换后模板剩余数量减1，用户持有数量加1
      • Validates: Requirements 14.3, 6.2, 6.3, 6.4

    • 5.2 实现积分服务

      • 实现 PointsService：积分余额查询、积分明细查询（支持类型和门店筛选）、积分发放（充电订单触发）、积分扣减（兑换触发）
      • 实现 PointsController：GET /api/points/balance、GET /api/points/records
      • 实现积分计算规则引擎
      • Requirements: 5.1, 5.2, 5.3, 5.4, 5.5, 5.6, 14.3

    • 5.3 编写核销验证属性测试

      • Property 10: 券码验证正确性 — 券码存在且未使用且属于当前门店则通过，否则失败并返回错误原因
      • Property 11: 核销操作正确性 — 核销后券状态变为已使用，用户端查询反映已使用状态
      • Validates: Requirements 11.3, 11.5, 12.2, 11.4, 11.6

    • 5.4 实现优惠券服务

      • 实现 CouponService：可兑换列表查询、兑换操作（积分校验+扣减+券码生成+驿公里API调用）、用户优惠券查询（支持状态/门店/类型筛选）、门店可用优惠券查询
      • 实现 CouponController：GET /api/coupons/available、POST /api/coupons/exchange、GET /api/coupons/my、GET /api/coupons/store/:storeId
      • 驿公里券兑换后直接标记为已使用状态
      • Requirements: 6.1, 6.2, 6.3, 6.4, 6.5, 6.6, 6.7, 7.1, 7.2, 7.3, 4.2

    • 5.5 实现核销服务

      • 实现 VerifyService：扫码核销、券码核销、核销记录查询（用户端和商户端）
      • 实现 VerifyController：POST /api/verify/scan、POST /api/verify/code、GET /api/verify/records、GET /api/verify/merchant-records
      • Requirements: 11.1-11.6, 12.1-12.4, 9.1, 13.1

  • 6. 门店与配置API

    • 6.1 实现门店服务和用户信息服务

      • 实现 StoreService：门店列表查询、门店详情查询
      • 实现 StoreController：GET /api/stores、GET /api/stores/:id
      • 实现 UserService：用户信息查询和更新
      • 实现 UserController：GET /api/user/profile、PUT /api/user/profile
      • Requirements: 3.4, 2.1, 2.2, 2.3, 2.4

    • 6.2 实现配置服务

      • 实现 ConfigService：Banner列表查询、弹窗内容查询、协议内容查询
      • 实现 ConfigController：GET /api/config/banners、GET /api/config/popups/:type、GET /api/config/agreement/:type
      • Requirements: 3.1, 3.2, 3.3, 8.8

    • 6.3 编写筛选逻辑和API认证属性测试

      • Property 13: 积分明细筛选正确性 — 筛选后每条记录匹配所选类型和门店
      • Property 14: 优惠券列表筛选正确性 — 筛选后每张券匹配所有筛选条件
      • Property 15: 门店可用优惠券筛选正确性 — 返回的券全部属于该用户、该门店、状态为未使用
      • Property 16: 商户身份识别正确性 — 手机号在商户员工表中存在则识别为商户
      • Property 21: API认证保护 — 无效令牌请求返回401
      • Validates: Requirements 5.4, 5.6, 7.2, 7.3, 4.2, 10.1, 17.14

  • 7. 检查点 - 确保所有后台测试通过

    • 确保所有测试通过，如有问题请向用户确认。

  • 8. 管理后台API

    • 8.1 实现管理员认证

      • 实现 AdminAuthService：管理员登录、JWT Token 生成
      • 实现 AdminAuthController：POST /api/admin/login
      • Requirements: 18.1

    • 8.2 实现管理后台CRUD接口

      • 实现 Banner 管理：GET/POST/PUT/DELETE /api/admin/banners
      • 实现弹窗内容管理：GET/PUT /api/admin/popups/:type
      • 实现门店管理：GET/POST/PUT/DELETE /api/admin/stores
      • 实现商户员工管理：GET/POST/DELETE /api/admin/merchants
      • 实现优惠券模板管理：GET/POST/PUT/DELETE /api/admin/coupon-templates
      • 实现协议内容管理：GET/PUT /api/admin/agreements/:type
      • 实现积分规则配置：GET/PUT /api/admin/points-rule
      • Requirements: 18.2, 18.3, 18.4, 18.5, 18.6, 18.10, 18.11

    • 8.3 编写管理后台CRUD属性测试

      • Property 20: 管理后台CRUD Round-Trip — 创建/更新后查询应得到与输入一致的结果
      • Validates: Requirements 18.2, 18.3, 18.4, 18.5, 18.6, 18.10, 18.11

    • 8.4 实现管理后台查询和统计接口

      • 实现优惠券发放记录查询：GET /api/admin/coupons
      • 实现核销记录查询：GET /api/admin/verify-records
      • 实现用户列表查询：GET /api/admin/users
      • 实现数据统计概览：GET /api/admin/dashboard
      • Requirements: 18.7, 18.8, 18.9, 18.12

  • 9. 检查点 - 确保所有后台API测试通过

    • 确保所有测试通过，如有问题请向用户确认。

  • 10. 小程序基础框架搭建

    • 10.1 配置小程序项目结构和路由

      • 更新 pages.json 配置所有页面路由和 TabBar（首页/积分页/我的页）
      • 创建所有页面目录和空白页面文件
      • 配置全局样式 uni.scss
      • 配置 manifest.json 微信小程序 appid 和权限
      • Requirements: 3.1-3.6, 5.1-5.6, 8.1-8.8

    • 10.2 实现公共工具模块

      • 实现 utils/request.js：封装 uni.request，统一处理 Token 注入、错误提示、401 自动跳转登录
      • 实现 utils/auth.js：登录状态管理、Token 本地存储、登录态检查
      • 实现 API 接口定义文件 api/*.js：按模块封装所有后台 API 调用
      • Requirements: 1.1, 17.14

    • 10.3 实现公共组件

      • 实现 CouponCard 组件：支持平台券（显示二维码按钮）和驿公里券（显示跳转按钮）两种样式
      • 实现 QrcodePopup 组件：优惠券二维码弹窗，支持核销成功/失败回调
      • 实现 ConfirmDialog 组件：通用二次确认弹窗
      • 实现 StoreCard 组件：门店信息卡片（照片/名称/位置/联系方式/可用券数/类型）
      • 实现 FilterBar 组件：筛选栏（门店/类型/状态下拉选择）
      • 实现 RichContentPopup 组件：富文本内容弹窗
      • Requirements: 4.3, 7.4, 7.5, 3.4

  • 11. 小程序用户端页面实现

    • 11.1 实现登录页和身份选择页

      • 实现 pages/login/index：微信手机号授权登录按钮
      • 实现 pages/login/role-select：商户员工身份选择（我是用户/我是商户）
      • 实现路由守卫：未登录访问需登录页面时自动跳转登录页
      • Requirements: 1.1, 1.2, 10.1, 10.2, 10.3

    • 11.2 实现首页

      • 实现 pages/home/index：Banner 轮播图、核销流程弹窗入口、积分说明弹窗入口、洗车店列表、导航按钮
      • 调用门店列表 API 和 Banner API 加载数据
      • Requirements: 3.1, 3.2, 3.3, 3.4, 3.5, 3.6

    • 11.3 实现门店可用优惠券页

      • 实现 pages/coupon/store-coupons：门店名称、优惠券列表、二维码弹窗、核销成功/失败提示
      • Requirements: 4.1, 4.2, 4.3, 4.4, 4.5, 4.6, 4.7

    • 11.4 实现积分页

      • 实现 pages/points/index：积分余额展示、积分说明弹窗、积分明细入口、可兑换优惠券列表、兑换流程（积分校验+二次确认+驿公里券提示）
      • 实现 pages/points/detail：积分明细列表、全部/收入/支出标签、门店筛选下拉
      • Requirements: 5.1, 5.2, 5.3, 5.4, 5.5, 5.6, 6.1, 6.2, 6.3, 6.4, 6.5, 6.6, 6.7

    • 11.5 实现我的页及子页面

      • 实现 pages/mine/index：用户信息展示、积分/优惠券数量、功能入口列表、退出登录
      • 实现 pages/mine/profile：头像/昵称编辑、UID只读展示
      • 实现 pages/mine/verify-records：核销记录列表
      • 实现 pages/mine/agreement：用户协议/隐私政策内容展示
      • Requirements: 8.1-8.8, 2.1-2.4, 9.1, 1.4, 1.5

    • 11.6 实现我的优惠券页

      • 实现 pages/coupon/my-coupons：未使用/已使用/已过期标签页、门店和类型筛选、平台券二维码按钮、驿公里券跳转按钮、核销后强制刷新
      • Requirements: 7.1, 7.2, 7.3, 7.4, 7.5, 7.6, 7.7

  • 12. 小程序商户端页面实现

    • 12.1 实现门店管理页（商户端）

      • 实现 pages/merchant/index：门店名称展示、扫码核销按钮（相机权限申请+扫码+核销确认）、券码核销按钮（输入弹窗+验证+核销确认）、核销记录入口
      • Requirements: 11.1-11.6, 12.1-12.4

    • 12.2 实现商户核销记录页

      • 实现 pages/merchant/records：核销记录列表（优惠券名称/核销时间/核销类型/券码/优惠券类型/手机号）
      • Requirements: 13.1

  • 13. 检查点 - 确保小程序所有页面功能正常

    • 确保所有测试通过，如有问题请向用户确认。

  • 14. 管理后台前端实现

    • 14.1 创建管理后台项目结构

      • 在 admin/ 目录下创建 Vue 3 + Vite + Element Plus 项目
      • 配置路由（Vue Router）、状态管理（Pinia）、HTTP 请求封装（Axios）
      • 实现管理员登录页和布局框架（侧边栏导航+顶部栏+内容区）
      • Requirements: 18.1

    • 14.2 实现管理后台业务页面

      • 实现数据统计概览页（Dashboard）：用户总数、优惠券发放总量、核销总量、积分发放总量
      • 实现 Banner 管理页：列表、新增/编辑弹窗、删除确认、排序拖拽
      • 实现弹窗内容管理页：核销流程说明和积分说明的富文本编辑器
      • 实现门店管理页：列表、新增/编辑表单（照片上传/名称/地址/联系方式/类型）、删除确认
      • 实现商户员工管理页：列表、绑定/解绑手机号
      • 实现优惠券模板管理页：列表、新增/编辑表单（名称/适用门店/有效期/数量/类型/积分/来源/驿公里券包码）
      • 实现优惠券发放记录页：列表、按用户/门店/状态筛选
      • 实现核销记录页：列表、按门店/时间/类型筛选
      • 实现用户管理页：列表、查看积分和优惠券详情
      • 实现积分规则配置页：充电金额与积分兑换比例设置
      • 实现协议内容管理页：用户协议和隐私政策富文本编辑
      • Requirements: 18.2-18.12

  • 15. 最终检查点 - 全部功能集成验证

    • 确保所有测试通过，如有问题请向用户确认。

备注

  • 每个任务引用了具体的需求编号以便追溯
  • 检查点确保增量验证
  • 属性测试验证通用正确性属性
  • 单元测试验证具体示例和边界情况