zhangxiang
810081ac0a
- 移除微信订阅推送功能（云函数/订阅管理页），回归纯客户端零后端架构 - 新增今日黄历默认展示卡片 TodayAlmanacCard（9 语言翻译） - i18n 修复：启用 globalInjection 修复 $t 未注入，插值消息全部改为 Messages Functions 适配小程序端（63 处） - 修复底部导航切换失效与运势页数据不刷新 - 统一设计令牌（深褐主色 + 印红强调色），组件 UI 规范重构 - 图标 iconfont 化（FontAwesome 子集化，修复 Android 豆腐块） - 新增 postcss-px2rpx 机型自适应（仅 mp-weixin 构建生效） - 新增 5 个用户旅程 E2E 测试（31 用例）与验收报告 - 补充微信小程序项目配置（appid）
232 lines
11 KiB
Markdown
232 lines
11 KiB
Markdown
# 万事宜 (Everything Is Suitable)
|
||
|
||
中国传统文化研究工具 — 紫微斗数排盘 / 黄历查询 / 运势分析
|
||
|
||
## 项目概述
|
||
|
||
**万事宜**是一款纯客户端 UniApp 应用，所有计算和数据存储均在本地完成，无需网络连接、无需后端服务、无需注册账号。支持 H5、微信小程序、App 多端发布。
|
||
|
||
## 项目结构
|
||
|
||
```
|
||
everything-is-suitable/
|
||
├── everything-is-suitable-uniapp/ # UniApp 主应用
|
||
│ ├── src/
|
||
│ │ ├── algorithms/ # 核心算法（紫微斗数、黄历、运势）
|
||
│ │ ├── components/ # 通用组件
|
||
│ │ ├── locales/ # 国际化（9种语言）
|
||
│ │ ├── pages/ # 页面
|
||
│ │ │ ├── almanac-search/ # 黄历搜索
|
||
│ │ │ ├── ziwei/ # 紫微斗数排盘
|
||
│ │ │ └── fortune/ # 运势分析
|
||
│ │ ├── services/ # 业务服务层（纯本地计算）
|
||
│ │ ├── types/ # TypeScript 类型定义
|
||
│ │ ├── utils/ # 工具函数（存储、缓存、导出等）
|
||
│ │ ├── App.vue
|
||
│ │ ├── main.ts
|
||
│ │ ├── manifest.json
|
||
│ │ └── pages.json
|
||
│ ├── e2e/ # E2E 测试（Playwright）
|
||
│ ├── Jenkinsfile # Jenkins CI/CD 配置
|
||
│ ├── Dockerfile # H5 部署 Docker 配置
|
||
│ ├── nginx.conf # Nginx 配置（纯静态，无后端代理）
|
||
│ ├── package.json
|
||
│ ├── vite.config.ts
|
||
│ └── vitest.config.ts
|
||
├── assets/ # 落地页素材
|
||
├── docs/ # 项目文档
|
||
│ ├── plans/ # 历史规划文档
|
||
│ ├── baselines/ # 测试基线
|
||
│ ├── reports/ # 测试报告
|
||
│ └── superpowers/ # Superpowers 工作流计划
|
||
├── index.html # 落地页
|
||
├── i18n.js # 落地页国际化
|
||
└── README.md
|
||
```
|
||
|
||
## 技术栈
|
||
|
||
| 类别 | 技术 |
|
||
|------|------|
|
||
| 框架 | UniApp (Vue 3 + TypeScript) |
|
||
| 构建 | Vite |
|
||
| 测试 | Vitest (单元) + Playwright (E2E) |
|
||
| 国际化 | vue-i18n (9种语言) |
|
||
| 存储 | uni.getStorageSync/setStorageSync |
|
||
| CI/CD | Jenkins |
|
||
| 部署 | Docker + Nginx (H5) |
|
||
|
||
## 快速开始
|
||
|
||
### 前置要求
|
||
|
||
- Node.js >= 20.0.0
|
||
- npm >= 9.0.0
|
||
|
||
### 安装与运行
|
||
|
||
```bash
|
||
cd everything-is-suitable-uniapp
|
||
npm install
|
||
|
||
# H5 开发模式
|
||
npm run dev:h5
|
||
|
||
# 微信小程序开发模式
|
||
npm run dev:mp-weixin
|
||
```
|
||
|
||
### 构建
|
||
|
||
```bash
|
||
# 构建 H5
|
||
npm run build:h5
|
||
|
||
# 构建微信小程序
|
||
npm run build:mp-weixin
|
||
```
|
||
|
||
### 测试
|
||
|
||
```bash
|
||
# 单元测试
|
||
npm run test
|
||
|
||
# 单元测试 + 覆盖率
|
||
npm run test:coverage
|
||
|
||
# E2E 测试
|
||
npm run test:e2e
|
||
```
|
||
|
||
## 纯客户端架构说明
|
||
|
||
本应用采用纯客户端架构，核心特征：
|
||
|
||
- **零网络请求**：所有算法（紫微斗数排盘、黄历计算、运势推演）均在客户端本地执行
|
||
- **零后端依赖**：无 API 调用、无数据库、无服务器（含云函数）
|
||
- **本地存储**：用户数据通过 `uni.getStorageSync/setStorageSync` 存储在设备本地
|
||
- **无订阅推送**：纯客户端版本不依赖微信订阅消息 / 云函数，订阅管理功能已在纯客户端迁移中移除
|
||
- **离线可用**：manifest.json 中 INTERNET 权限设为 false，无需网络即可使用全部功能
|
||
- **隐私安全**：用户数据不离开设备，无需注册账号
|
||
|
||
## 规划
|
||
|
||
### 总体目标
|
||
|
||
构建一款纯客户端、离线可用的中国传统文化研究工具，支持紫微斗数排盘、黄历查询、运势分析三大核心功能，覆盖 H5、微信小程序、App 多端。
|
||
|
||
### 里程碑
|
||
|
||
| 阶段 | 状态 | 说明 |
|
||
|------|------|------|
|
||
| **M1: 核心算法实现** | ✅ | 紫微斗数排盘、黄历计算、运势推演算法完成 |
|
||
| **M2: 页面与交互开发** | ✅ | 三大核心页面（ziwei / almanac-search / fortune）开发完成 |
|
||
| **M3: 国际化 & 多端适配** | ✅ | 9 种语言支持，UniApp 多端构建验证通过 |
|
||
| **M4: 测试与质量保障** | ✅ | 单元测试 685 通过，E2E 测试 156 通过，覆盖率 90.24% |
|
||
| **M5: 封版发布** | ✅ | 封版确认，通过最终验收 |
|
||
|
||
## 进度
|
||
|
||
### 当前状态：v1.0.0 封版完成 ✅ (最终验收测试通过)
|
||
|
||
> 更新日期: 2026-08-18 (用户旅程测试补充，封版依据强化)
|
||
|
||
### 用户旅程测试（本次新增）
|
||
|
||
基于真实用户使用流程新增 **5 个用户旅程、31 个旅程用例**（`e2e/journeys/`），作为封版依据：
|
||
|
||
| 旅程 | 优先级 | 覆盖步骤 | 用例数 |
|
||
|------|--------|----------|--------|
|
||
| J-ZIWEI 紫微排盘完整旅程 | Critical | 表单→日期/时辰→性别→出生地识别→排盘→宫位→三方四正→总结 | 7 |
|
||
| J-ALMANAC 黄历吉日搜索旅程 | Critical | 模板搜索→手动条件→天数→结果→排序 | 6 |
|
||
| J-FORTUNE 运势分析旅程 | Common | 排盘持久化→跨页→日运→日期切换→月运 | 6 |
|
||
| J-SUBSCRIBE 订阅管理旅程 | Common | 状态→时间选择→保存→取消订阅弹窗 | 6 |
|
||
| J-NAV 跨页导航与状态保持 | Edge | 底部导航切换→往返→数据跨页保持 | 6 |
|
||
|
||
**旅程测试发现并修复 2 个真实缺陷（P1）：**
|
||
1. **底部导航切换失效**：`BottomNavigation` 中 `tabs.find` 应为 `tabs.value.find`（computed ref 未解包），导致三大功能页无法通过底部导航切换
|
||
2. **运势页排盘数据不刷新**：`fortune` 页仅用 `onMounted` 加载排盘数据，用户"先看运势→排盘→返回"时页面实例被缓存、数据不更新，已改为 `onShow` 刷新
|
||
|
||
**小程序端验收发现并修复 1 个 P0 缺陷：**
|
||
3. **全部页面异常（$t is not a function）**：`createI18n` 使用 `legacy: false` 但缺少 `globalInjection: true`，导致小程序端模板 `$t` 未注入、所有页面渲染中断（报 `TypeError: a.$t is not a function`）。已在 `src/locales/index.ts` 显式启用 `globalInjection: true`（vue-i18n v9 官方要求），并新增防回归测试（TC-I18N-010）
|
||
|
||
**小程序端验收发现并修复 1 个 P0 缺陷（插值失效）：**
|
||
4. **全部插值文案失效（{count} 字面量）**：uni-app 平台限制——小程序/App 端不支持 `{variable}` 字符串插值。已将 9 种语言共 63 处插值消息全部改为 **Messages Functions**（`({ named }) => ...`），并新增插值行为防回归测试
|
||
|
||
**新增功能：今日黄历默认展示（2026-08-18）**
|
||
- 进入黄历搜索页默认展示**今日黄历**卡片（公历/农历/值神/吉神/宜忌/冲煞/纳音/胎神/彭祖百忌），组件：`src/components/TodayAlmanacCard/`
|
||
- 新增 9 种语言 `almanac.*` 翻译 key（todayTitle/lunarDate/jianChu 等 10 项）
|
||
|
||
**UI 层级验收发现并修复 1 个 P1 UI 缺陷（2026-08-19）：**
|
||
5. **排盘页/运势页缺失底部导航**：三个 tab 页中仅黄历页有 `BottomNavigation`，用户切换到排盘/运势页后无法再通过底部导航切换。已在 `pages/ziwei/index.vue`、`pages/fortune/index.vue` 补上，并在 `navigation-journey.spec.ts` 增加目标页底部导航回归断言
|
||
|
||
**小程序端体验优化（2026-08-19）：**
|
||
6. **px→rpx 机型自适应**：源码 97% 样式用 px（小程序端固定像素、不随机型缩放）。已通过 `postcss-px2rpx`（仅 mp-weixin 构建生效，H5 保持 px）将构建产物 px 占比降至 4.3%，布局/字体随机型等比缩放
|
||
7. **图标 iconfont 化（修复豆腐块）**：原 Icon 用 Unicode 冷门符号（⌕ ◷ ⏱ 等），Android 微信可能显示为豆腐块。已改为 FontAwesome 子集化图标字体（`scripts/iconfont-build.py` 生成，仅 3KB/36 图标，@font-face base64 内联），跨端可靠渲染
|
||
|
||
运行命令：`npm run test:journeys`（chromium 基线，跨浏览器兼容由既有 E2E 覆盖）
|
||
|
||
### 验收标准对照
|
||
|
||
| 标准 | 阈值 | 实际值 | 状态 |
|
||
|------|------|--------|------|
|
||
| 单元测试通过率 | ≥ 90% | **100%** (692/692) | ✅ |
|
||
| 代码覆盖率 (指令) | ≥ 70% | **90.36%** | ✅ |
|
||
| 代码覆盖率 (函数) | ≥ 70% | **94.18%** | ✅ |
|
||
| 代码覆盖率 (分支) | ≥ 60% | **77.82%** | ✅ |
|
||
| E2E 核心流程通过率 | ≥ 80% | **100%** (160/160) | ✅ |
|
||
| 算法交叉验证 | 100% | **100%** | ✅ |
|
||
| 算法执行时间 | < 500ms | **全部 < 200ms** | ✅ |
|
||
| 页面加载时间 | < 3s | **~1.7s** | ✅ |
|
||
| 国际化覆盖 | 9/9 语言 | **全部完整** | ✅ |
|
||
| 浏览器兼容性 | 4/4 浏览器 | **全部通过** | ✅ |
|
||
| 安全验证 | 全部通过 | **12/12 通过** | ✅ |
|
||
| 无 P0 缺陷 | 0 | **0** | ✅ |
|
||
|
||
### 测试结果
|
||
|
||
- **单元测试**: 692/692 通过 (100%)，35 个测试文件，执行时间 7.6s
|
||
- **专项测试**: 55/55 通过 (性能测试 15 + 并发负载 4 + 安全测试 12 + 国际化验证 9 + 稳定性 4 + E2E 性能 5 + E2E 安全 4 + E2E 兼容 3)
|
||
- **E2E 测试**: 160/160 通过 (100%)，覆盖 Chromium/WebKit/Mobile Chrome/Mobile Safari 4 种浏览器 × 40 个用例
|
||
- **覆盖率**: 整体 90.36%，其中算法层 94.19%，服务层 92.68%，工具层 90.35%
|
||
- **性能**: 算法执行均 < 200ms，页面加载均 < 2s，长时间使用无退化
|
||
- **安全**: 12 项安全验证全部通过，无 XSS 风险，网络权限严格受限
|
||
- **国际化**: 9 种语言键值完整一致
|
||
- **缺陷**: 0 个 P0 遗留，0 个 P1 遗留
|
||
|
||
### 已知待办
|
||
|
||
- [ ] 补充组件层单元测试覆盖（BottomNavigation, Button, Card 等 11 个组件）
|
||
- [ ] 补充 `lunar.ts` 分支覆盖（当前 64.13%）
|
||
- [ ] 补充 `fortuneService.ts` 覆盖（当前 72%）
|
||
- [ ] 逐步消除代码中 `as any` 类型断言
|
||
- [ ] 在 CI 标准环境中启用 Firefox 浏览器测试 (当前沙箱环境兼容性限制)
|
||
- [ ] 修复微信小程序构建问题 (`@dcloudio/vite-plugin-uni` v3 alpha 兼容性限制) — **已修复，当前构建成功**
|
||
- [ ] 修复 Ziwei 页面测试 i18n locale 配置 (zh → zh-CN)
|
||
|
||
> 详细测试报告见: [docs/reports/v1.0.0-FINAL-ACCEPTANCE-REPORT.md](docs/reports/v1.0.0-FINAL-ACCEPTANCE-REPORT.md)
|
||
> 测试计划文档见: [docs/plans/v1.0.0-RELEASE-TEST-PLAN.md](docs/plans/v1.0.0-RELEASE-TEST-PLAN.md)
|
||
|
||
## 功能模块
|
||
|
||
### 黄历搜索 (almanac-search)
|
||
- 每日宜忌查询
|
||
- 条件搜索（嫁娶、搬家、开市等）
|
||
- 搜索历史与模板
|
||
|
||
### 紫微斗数 (ziwei)
|
||
- 自动排盘（支持公历输入）
|
||
- 十二宫位完整展示
|
||
- 十四主星 + 辅星体系
|
||
- 三方四正分析
|
||
|
||
### 运势分析 (fortune)
|
||
- 每日/每月/每年运势
|
||
- 事业、财运、感情、健康多维度
|
||
- 幸运色、幸运数字、幸运方位
|
||
|
||
## 许可证
|
||
|
||
MIT License
|