everything-is-suitable/docs/superpowers/specs/2026-04-27-pure-client-transformation-design.md

纯客户端转型设计规格

日期: 2026-04-27 状态: 已批准 作者: Zhang Xiang

1. 概述

将 Everything Is Suitable 从 C/S 架构（UniApp + Java Spring Boot + PostgreSQL）转型为纯客户端 App，通过 App Store、Google Play、华为/OPPO/小米等应用商店进行买断制付费分发，完全移除服务端。

产品定位：中国传统文化研究工具。

2. 决策记录

决策项	选择	理由
架构方案	UniApp 继续演进	复用现有 UI，跨平台覆盖最广，风险最低
目标平台	iOS + Android (Google Play) + 国内安卓商店	最大化覆盖面
付费模式	买断制付费下载	纯客户端最简变现方式
功能范围	第一版包含全部核心功能	黄历+紫微+运势全部移植
后端处理	完全删除	不再需要服务端
数据存储	纯本地存储 + 可选 iCloud 同步	无服务端，数据在设备本地
CI/CD	Jenkins	团队现有基础设施

3. 整体架构

3.1 转型后架构

┌─────────────────────────────────────────────────────┐
│              纯客户端 App (UniApp)                    │
│                                                      │
│  ┌──────────────────────────────────────────────┐   │
│  │           表现层 (Pages / Components)          │   │
│  │  黄历查询页 | 紫微排盘页 | 运势分析页 | 搜索页   │   │
│  └───────────────────┬──────────────────────────┘   │
│                      │                               │
│  ┌───────────────────▼──────────────────────────┐   │
│  │           服务层 (Local Services)              │   │
│  │  AlmanacService | ZiweiService | FortuneService│   │
│  │  SearchService  | TemplateService              │   │
│  └───────────────────┬──────────────────────────┘   │
│                      │                               │
│  ┌───────────────────▼──────────────────────────┐   │
│  │           算法层 (Core Algorithms)             │   │
│  │  lunar.ts | almanac.ts | ziwei.ts | fortune.ts│   │
│  │  sanFangSiZheng.ts | heavenlyStems.ts          │   │
│  └───────────────────┬──────────────────────────┘   │
│                      │                               │
│  ┌───────────────────▼──────────────────────────┐   │
│  │           基础设施层 (Infrastructure)           │   │
│  │  LRUCache | PerformanceMonitor | Storage       │   │
│  │  ExportImport | CloudSync(iCloud/GDrive)       │   │
│  └──────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────┘

3.2 核心模块映射 (Java → TypeScript)

Java 模块	TypeScript 目标	关键类/方法
AlmanacServiceImpl	almanac.ts	getAlmanacByDate, getAlmanacsByRange
AlmanacSearchHandler	searchService.ts (重写)	search, searchByKeyword
ZiweiChartServiceImpl	ziwei.ts	generateChart, getPalaceInfo
ZiweiAlgorithmUtil (1025行)	ziweiAlgorithm.ts	排盘核心算法
SanFangSiZhengUtil (249行)	sanFangSiZheng.ts	三方四正计算
FortuneAnalysisServiceImpl	fortune.ts	daily/monthly/yearly/overall
DailyFortuneStrategy (229行)	fortuneStrategy.ts	日运策略
MonthlyFortuneStrategy (404行)	fortuneStrategy.ts	月运策略
LunarCalendarServiceImpl	已有 lunar.ts	无需移植
CalendarServiceImpl	calendar.ts	日历相关

3.3 转型后目录结构

everything-is-suitable/
├── everything-is-suitable-uniapp/    # 唯一保留的项目
│   ├── src/
│   │   ├── algorithms/               # 新增：核心算法层
│   │   │   ├── almanac.ts
│   │   │   ├── ziwei.ts
│   │   │   ├── ziweiAlgorithm.ts
│   │   │   ├── sanFangSiZheng.ts
│   │   │   ├── fortune.ts
│   │   │   ├── fortuneStrategy.ts
│   │   │   ├── calendar.ts
│   │   │   └── types.ts              # 算法层共享类型
│   │   ├── services/                 # 重写：本地服务层
│   │   │   ├── almanacService.ts
│   │   │   ├── ziweiService.ts
│   │   │   ├── fortuneService.ts
│   │   │   ├── searchService.ts
│   │   │   └── templateService.ts
│   │   ├── utils/                    # 保留+增强
│   │   │   ├── lunar.ts              # 已有
│   │   │   ├── lruCache.ts           # 已有
│   │   │   ├── searchOptimizer.ts    # 已有
│   │   │   ├── performanceMonitor.ts # 已有
│   │   │   ├── storage.ts            # 新增：统一本地存储
│   │   │   ├── exportImport.ts       # 新增：数据导出导入
│   │   │   └── errorHandler.ts       # 已有
│   │   ├── components/               # 保留
│   │   ├── pages/                    # 保留+新增
│   │   │   ├── almanac-search/       # 已有
│   │   │   ├── ziwei/                # 新增：紫微排盘页
│   │   │   └── fortune/              # 新增：运势分析页
│   │   └── types/                    # 保留+扩展
│   ├── package.json
│   ├── Jenkinsfile                   # 新增：Jenkins CI
│   └── ...
└── (其他目录全部删除)

4. 核心算法移植策略

4.1 移植原则

1. 算法逻辑 1:1 移植：不重构算法，保持与 Java 代码逻辑一致，便于交叉验证
2. 类型先行：先移植枚举和领域模型，再移植算法
3. 测试驱动：每个算法移植后，用 Java 端的现有测试用例做交叉验证

4.2 移植分层顺序

Step 1: 枚举与常量 (Enums)

• HeavenlyStem (天干)
• EarthlyBranch (地支)
• MajorStar (主星)
• PalaceType (宫位类型)
• StarNature (星性)
• TransformationType (四化类型)
• FortuneType (运势类型)
• StarBrightness (星曜亮度)

Step 2: 领域模型 (Domain Models)

• BirthInfo (出生信息)
• ZiweiChart (命盘)
• Palace (宫位)
• StarInfo (星曜信息)
• DailyFortune (日运)
• MonthlyFortune (月运)
• Almanac (黄历)
• LunarDate (农历日期 - 已有)

Step 3: 核心算法 (Algorithms)

• ZiweiAlgorithmUtil → ziweiAlgorithm.ts (排盘核心)
• SanFangSiZhengUtil → sanFangSiZheng.ts (三方四正)
• FortuneStrategy → fortuneStrategy.ts (运势策略)
• AlmanacService → almanac.ts (黄历计算)

Step 4: 服务层 (Services)

• ZiweiChartService → ziweiService.ts
• FortuneAnalysisService → fortuneService.ts
• AlmanacService → almanacService.ts
• SearchService → searchService.ts (重写为本地搜索)

4.3 Java → TypeScript 关键差异处理

Java 特性	TypeScript 对应	注意事项
int 除法自动截断	Math.floor()	必须显式处理
enum	enum + 辅助方法	fromIndex/fromName 等
List<T>	T[]	数组操作
Map<K,V>	Map<K,V>	保持一致
Caffeine Cache	LRUCache (已有)	已有实现
Optional<T>	T | null	空值处理
record	interface	不可变用 readonly
switch 表达式	switch 语句	无表达式形式

4.4 交叉验证策略

每个算法移植后，使用 Java 端现有测试用例生成黄金数据集：

1. 从 Java 测试用例中提取输入/输出对
2. 在 TypeScript 中用相同输入执行
3. 比对输出，允许浮点误差 < 0.001
4. 100% 通过才算移植成功

5. 后端依赖移除与本地服务替换

5.1 需要删除的目录和文件

目标	处理方式
everything-is-suitable-api/	整个目录删除
everything-is-suitable-admin/	整个目录删除
everything-is-suitable-test/	整个目录删除
docker-compose.yml	删除
docker-compose.*.yml	删除
Dockerfile*	删除
.woodpecker.yml	删除，替换为 Jenkinsfile
DEPLOYMENT.md	删除
WOODPECKER_CI.md	删除
STARTUP_GUIDE.md	删除
config/ (根目录)	删除

5.2 需要从 UniApp 中移除的文件

文件	替代方案
src/utils/httpClient.ts	删除，本地服务直接调用
src/utils/tokenManager.ts	删除，无需认证
src/types/api.ts	删除，无远程 API
config/ (baseURL 等)	删除，无远程端点

5.3 本地服务替换映射

远程 API 调用	本地服务调用
httpClient.get('/almanac/{date}')	almanacService.getByDate(date)
httpClient.get('/almanac/range')	almanacService.getByRange(start, end)
httpClient.post('/almanac/search')	searchService.search(request)
httpClient.post('/fortune/daily')	fortuneService.getDaily(birthInfo, date)
httpClient.post('/fortune/monthly')	fortuneService.getMonthly(birthInfo, month)
httpClient.post('/fortune/yearly')	fortuneService.getYearly(birthInfo, year)
httpClient.post('/fortune/overall')	fortuneService.getOverall(birthInfo)
httpClient.post('/ziwei/chart')	ziweiService.generateChart(birthInfo)

5.4 统一本地存储层

新增 utils/storage.ts，封装 uni.storage：

• get<T>(key: string): T | null
• set<T>(key: string, value: T): void
• remove(key: string): void
• clear(): void
• enableCloudSync(): void (后续版本：iCloud/Google Drive)
• syncToCloud(): Promise<void> (后续版本)
• syncFromCloud(): Promise<void> (后续版本)

第一版仅实现纯本地存储，云同步功能在后续版本中添加。

6. 付费分发与商店适配

6.1 付费模式

买断制付费下载，一次性购买永久使用。

平台	实现方式	费用
App Store	Paid Application	Apple Developer $99/年
Google Play	Paid App	Google Play Developer $25 一次性
华为应用市场	付费下载	华为开发者账号
OPPO/小米	付费下载	各自开发者账号

6.2 内容合规：传统文化定位策略

所有文案和 UI 必须遵循"传统文化研究工具"定位。

禁用词替换表：

禁用词	替代词
算命	命理研究
预测	参考分析
占卜	传统卜筮文化研究
运势	时令参考
吉凶	传统宜忌参考
风水	传统堪舆文化

App 描述模板：

本应用是一款中国传统文化研究工具，基于传统历法学、紫微斗数学等传统文化体系，提供黄历查询、命盘排布、时令参考等功能。所有内容仅供传统文化学术研究参考，不构成任何决策建议。

6.3 各平台审核要点

平台	关键审核点	应对策略
App Store	2.5.2 功能完整	确保离线可用、无空白页
App Store	命理类需标注"娱乐"	描述中标注"传统文化研究，仅供学术参考"
Google Play	无特殊命理限制	正常提交
华为	对"迷信"内容敏感	强调"传统文化""学术研究"定位
OPPO/小米	类似华为	同上 + 提供免责声明

7. 测试策略与质量保障

7.1 分层测试策略

┌─────────────────────────────────────┐
│          E2E 测试 (Playwright)       │  关键用户流程
├─────────────────────────────────────┤
│        集成测试 (Vitest)             │  服务层 + 算法层联动
├─────────────────────────────────────┤
│        单元测试 (Vitest)             │  算法正确性
├─────────────────────────────────────┤
│        交叉验证测试 (Vitest)          │  Java vs TS 结果比对
└─────────────────────────────────────┘

7.2 交叉验证测试

从 Java 端测试用例中提取黄金数据，确保 TypeScript 移植结果与 Java 完全一致。

测试用例来源：

• ZiweiAlgorithmUtilTest.java (494行)
• ComprehensiveAlmanacServiceTest.java
• DailyFortuneTest.java (334行)
• AlmanacSearchHandlerTest.java (490行)

7.3 质量门禁

指标	标准
算法层单元测试覆盖率	>= 90%
服务层单元测试覆盖率	>= 80%
交叉验证通过率	100%
E2E 关键路径通过率	100%
Lint 错误	0
TypeScript 严格模式	开启

8. CI/CD (Jenkins)

pipeline {
  agent any
  environment {
    NODE_VERSION = '20'
    PROJECT_DIR = 'everything-is-suitable-uniapp'
  }
  stages {
    stage('Install') {
      steps {
        dir(env.PROJECT_DIR) { sh 'npm ci' }
      }
    }
    stage('Lint') {
      steps {
        dir(env.PROJECT_DIR) { sh 'npm run lint' }
      }
    }
    stage('Unit Test') {
      steps {
        dir(env.PROJECT_DIR) { sh 'npm run test' }
      }
      post {
        always { junit "${env.PROJECT_DIR}/test-results/*.xml" }
      }
    }
    stage('Build H5') {
      steps {
        dir(env.PROJECT_DIR) { sh 'npm run build:h5' }
      }
    }
    stage('Build Android') {
      when { branch 'main' }
      steps {
        dir(env.PROJECT_DIR) { sh 'npm run build:app-android' }
      }
    }
    stage('Build iOS') {
      when { branch 'main' }
      steps {
        dir(env.PROJECT_DIR) { sh 'npm run build:app-ios' }
      }
    }
  }
}

9. ICP 备案说明

纯客户端 App（无后端服务）不需要 ICP 备案。这不是"绕过"，而是法律上的"不适用"——ICP 备案规制的是"互联网信息服务提供者"，纯客户端 App 没有服务端，不构成信息服务提供者。

国内应用商店（华为/OPPO/小米）可能要求声明"本应用为纯客户端应用，无后端服务，不涉及互联网信息服务"。

10. 风险与缓解

风险	影响	缓解措施
算法移植正确性	高	交叉验证测试 + 黄金数据集
命理类内容审核	高	传统文化定位 + 合规文案
App 体积过大	中	按需加载 + 数据压缩
算法性能瓶颈	低	Web Worker 隔离 + LRUCache
越狱盗版	低	可接受风险，商店内购保护