# 纯客户端转型设计规格

> 日期: 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)

```groovy
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 |
| 越狱盗版 | 低 | 可接受风险，商店内购保护 |