first commit

2026-06-10 19:59:27 +08:00
commit d141623070
813 changed files with 61301 additions and 0 deletions
@@ -0,0 +1,458 @@
+# 知命阁（zhimingge）Ubuntu 部署文档
+
+> 仓库：[https://git.bz121.com/dekun/zhimingge.git](https://git.bz121.com/dekun/zhimingge.git)
+
+本文档说明在 **Ubuntu 服务器**上使用 **root 用户**、**PM2** 将知命阁部署到 **`/opt/zhimingge`** 的完整流程。
+
+---
+
+## 1. 部署架构
+
+```
+                    ┌─────────────────┐
+   用户浏览器  ──→  │  Nginx (可选)   │  :80 / :443
+                    │  反向代理        │
+                    └────────┬────────┘
+                             │
+                    ┌────────▼────────┐
+                    │  PM2            │
+                    │  zhimingge      │  :3000
+                    └────────┬────────┘
+                             │
+                    ┌────────▼────────┐
+                    │  Next.js        │
+                    │  standalone     │
+                    │  /opt/zhimingge │
+                    └─────────────────┘
+                             │
+                    ┌────────▼────────┐
+                    │  op.bz121.com   │  AI API
+                    │  /v1            │
+                    └─────────────────┘
+```
+
+| 组件 | 说明 |
+|------|------|
+| 操作系统 | Ubuntu 20.04 / 22.04 / 24.04 LTS |
+| 运行用户 | root（按需求） |
+| 安装目录 | `/opt/zhimingge` |
+| 进程管理 | PM2 |
+| 构建模式 | Next.js `output: "standalone"` |
+| 默认端口 | 3000 |
+
+---
+
+## 2. 服务器要求
+
+| 项目 | 最低配置 | 推荐配置 |
+|------|----------|----------|
+| CPU | 1 核 | 2 核 |
+| 内存 | 1 GB | 2 GB+ |
+| 磁盘 | 2 GB | 10 GB |
+| 网络 | 可访问 git.bz121.com、op.bz121.com | — |
+
+---
+
+## 3. 一次性环境准备
+
+以 **root** 登录服务器后执行：
+
+### 3.1 更新系统
+
+```bash
+apt update && apt upgrade -y
+```
+
+### 3.2 安装 Node.js 20（推荐 LTS）
+
+```bash
+curl -fsSL https://deb.nodesource.com/setup_20.x | bash -
+apt install -y nodejs
+node -v   # 应 >= v20
+npm -v
+```
+
+### 3.3 安装 pnpm 与 PM2
+
+```bash
+npm install -g pnpm pm2
+pnpm -v
+pm2 -v
+```
+
+### 3.4 安装 Git
+
+```bash
+apt install -y git
+```
+
+### 3.5（可选）安装 Nginx 反向代理
+
+若需域名 + HTTPS，建议安装 Nginx 与 Certbot：
+
+```bash
+apt install -y nginx certbot python3-certbot-nginx
+```
+
+---
+
+## 4. 克隆与目录
+
+```bash
+mkdir -p /opt
+cd /opt
+
+# 首次克隆（私有仓库需配置凭据，见第 5 节）
+git clone https://git.bz121.com/dekun/zhimingge.git zhimingge
+
+cd /opt/zhimingge
+```
+
+最终目录：
+
+```
+/opt/zhimingge/
+├── app/
+├── content/
+├── ecosystem.config.cjs
+├── .env.local          ← 生产环境变量（勿提交 Git）
+├── package.json
+└── ...
+```
+
+---
+
+## 5. Git 凭据（私有仓库）
+
+仓库 [dekun/zhimingge](https://git.bz121.com/dekun/zhimingge.git) 为私有仓库，克隆前需配置认证。
+
+### 方式 A：HTTPS + 访问令牌（推荐）
+
+```bash
+git config --global credential.helper store
+git clone https://git.bz121.com/dekun/zhimingge.git /opt/zhimingge
+# 按提示输入 Gitea 用户名与 Personal Access Token
+```
+
+在 Gitea 生成 Token：用户设置 → Applications → Generate New Token（勾选 `repo` 权限）。
+
+### 方式 B：SSH
+
+```bash
+ssh-keygen -t ed25519 -C "zhimingge-deploy" -f /root/.ssh/zhimingge -N ""
+cat /root/.ssh/zhimingge.pub
+# 将公钥添加到 Gitea → Settings → SSH Keys
+
+cat >> /root/.ssh/config << 'EOF'
+Host git.bz121.com
+  IdentityFile /root/.ssh/zhimingge
+  StrictHostKeyChecking accept-new
+EOF
+
+git clone git@git.bz121.com:dekun/zhimingge.git /opt/zhimingge
+```
+
+---
+
+## 6. 环境变量
+
+```bash
+cd /opt/zhimingge
+cp .env.example .env.local
+nano .env.local
+```
+
+**`.env.local` 示例：**
+
+```env
+# AI 接口（必填）
+OPENAI_API_KEY=你的密钥
+
+# AI 地址与模型（已有默认值，可按需覆盖）
+OPENAI_BASE_URL=https://op.bz121.com/v1
+OPENAI_MODEL=huihui_ai/gemma-4-abliterated:e4b
+
+# 服务端口
+PORT=3000
+NODE_ENV=production
+```
+
+保存后限制权限：
+
+```bash
+chmod 600 .env.local
+```
+
+---
+
+## 7. 构建与启动
+
+### 7.1 安装依赖
+
+```bash
+cd /opt/zhimingge
+pnpm install --frozen-lockfile
+```
+
+### 7.2 生产构建
+
+```bash
+pnpm run build
+```
+
+构建成功后生成 `.next/standalone/` 独立运行包。
+
+### 7.3 复制静态资源（standalone 必需）
+
+Next.js standalone 模式需手动链接静态文件：
+
+```bash
+cd /opt/zhimingge
+
+# 复制 static 与 public 到 standalone 目录
+cp -r .next/static .next/standalone/.next/static
+cp -r public .next/standalone/public
+
+# 复制内容库（服务端读取卦辞 Markdown）
+cp -r content .next/standalone/content
+```
+
+> **说明**：若应用从项目根目录读取 `content/`，PM2 的 `cwd` 应设为 `/opt/zhimingge` 而非 standalone 子目录。当前 `ecosystem.config.cjs` 使用项目根目录 + `pnpm start`，构建后也可改用 standalone 的 `server.js`（见 7.5 备选方案）。
+
+### 7.4 使用 PM2 启动（推荐方式）
+
+项目根目录已包含 `ecosystem.config.cjs`：
+
+```bash
+cd /opt/zhimingge
+pm2 start ecosystem.config.cjs
+pm2 save
+pm2 startup
+# 按 PM2 提示执行生成的命令，确保开机自启
+```
+
+常用 PM2 命令：
+
+```bash
+pm2 status                  # 查看状态
+pm2 logs zhimingge          # 查看日志
+pm2 restart zhimingge       # 重启
+pm2 stop zhimingge          # 停止
+pm2 delete zhimingge        # 删除进程
+```
+
+### 7.5 备选：standalone 直接运行
+
+若希望仅运行 standalone 产物（体积更小）：
+
+```bash
+cd /opt/zhimingge/.next/standalone
+PORT=3000 node server.js
+```
+
+对应 PM2 配置片段：
+
+```javascript
+{
+  name: "zhimingge",
+  cwd: "/opt/zhimingge/.next/standalone",
+  script: "server.js",
+  env: {
+    PORT: 3000,
+    NODE_ENV: "production",
+  },
+}
+```
+
+此时需确保 `content/`、`public/` 路径在代码中相对于 `cwd` 可访问。
+
+### 7.6 验证
+
+```bash
+curl -I http://127.0.0.1:3000
+# 应返回 HTTP/1.1 200
+```
+
+浏览器访问：`http://服务器IP:3000`
+
+---
+
+## 8. Nginx 反向代理（可选）
+
+假设域名为 `zhimingge.example.com`：
+
+```bash
+nano /etc/nginx/sites-available/zhimingge
+```
+
+```nginx
+server {
+    listen 80;
+    server_name zhimingge.example.com;
+
+    location / {
+        proxy_pass http://127.0.0.1:3000;
+        proxy_http_version 1.1;
+        proxy_set_header Upgrade $http_upgrade;
+        proxy_set_header Connection 'upgrade';
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+        proxy_cache_bypass $http_upgrade;
+
+        # AI 流式响应需禁用缓冲
+        proxy_buffering off;
+        proxy_read_timeout 300s;
+    }
+}
+```
+
+```bash
+ln -s /etc/nginx/sites-available/zhimingge /etc/nginx/sites-enabled/
+nginx -t
+systemctl reload nginx
+
+# HTTPS（Let's Encrypt）
+certbot --nginx -d zhimingge.example.com
+```
+
+---
+
+## 9. 更新部署流程
+
+代码推送至 Gitea 后，在服务器执行：
+
+```bash
+cd /opt/zhimingge
+
+# 拉取最新代码
+git pull origin main
+
+# 安装新依赖（如有变更）
+pnpm install --frozen-lockfile
+
+# 重新构建
+pnpm run build
+
+# 若使用 standalone 复制方式，重新复制 static/public/content
+cp -r .next/static .next/standalone/.next/static
+cp -r public .next/standalone/public
+cp -r content .next/standalone/content
+
+# 重启
+pm2 restart zhimingge
+```
+
+可写入脚本 `/opt/zhimingge/scripts/deploy.sh` 一键执行（见项目内脚本）。
+
+---
+
+## 10. 防火墙
+
+若使用 UFW：
+
+```bash
+# 仅 Nginx 对外（推荐）
+ufw allow 22
+ufw allow 80
+ufw allow 443
+ufw enable
+
+# 若不用 Nginx，直接暴露 3000
+ufw allow 3000
+```
+
+---
+
+## 11. 日志与排错
+
+### PM2 日志
+
+```bash
+pm2 logs zhimingge --lines 100
+```
+
+日志文件位置（默认）：
+
+```
+/root/.pm2/logs/zhimingge-out.log
+/root/.pm2/logs/zhimingge-error.log
+```
+
+### 常见问题
+
+| 现象 | 可能原因 | 处理 |
+|------|----------|------|
+| 502 Bad Gateway | PM2 进程未运行 | `pm2 restart zhimingge` |
+| AI 解读失败 | API Key 错误或模型名不对 | 检查 `.env.local` |
+| 卦辞读取失败 | `content/` 路径不存在 | 确认 `content/zhouyi/docs/` 存在 |
+| 构建 OOM | 内存不足 | 增加 swap 或升级内存 |
+| 流式输出中断 | Nginx 缓冲 | 设置 `proxy_buffering off` |
+| Git pull 失败 | 凭据过期 | 重新配置 Token 或 SSH |
+
+### 构建内存不足时增加 Swap
+
+```bash
+fallocate -l 2G /swapfile
+chmod 600 /swapfile
+mkswap /swapfile
+swapon /swapfile
+echo '/swapfile none swap sw 0 0' >> /etc/fstab
+```
+
+### 测试 AI 接口
+
+```bash
+curl https://op.bz121.com/v1/models \
+  -H "Authorization: Bearer 你的OPENAI_API_KEY"
+```
+
+确认返回列表中包含 `huihui_ai/gemma-4-abliterated:e4b`。
+
+---
+
+## 12. 安全建议
+
+虽然当前按 **root** 部署，仍建议：
+
+1. **`.env.local` 权限** 设为 `600`，勿提交 Git
+2. **API Key** 仅保存在服务器，不要写入前端代码
+3. 生产环境使用 **Nginx + HTTPS**
+4. 定期 `apt update` 与 `pnpm update`
+5. 若后续改为非 root 运行，创建专用用户：
+
+```bash
+useradd -r -s /bin/false zhimingge
+chown -R zhimingge:zhimingge /opt/zhimingge
+# PM2 中以 zhimingge 用户启动
+```
+
+---
+
+## 13. 快速命令参考
+
+```bash
+# 完整首次部署
+cd /opt && git clone https://git.bz121.com/dekun/zhimingge.git zhimingge
+cd /opt/zhimingge
+cp .env.example .env.local && nano .env.local
+pnpm install --frozen-lockfile
+pnpm run build
+pm2 start ecosystem.config.cjs
+pm2 save && pm2 startup
+
+# 日常更新
+cd /opt/zhimingge && git pull && pnpm install && pnpm run build && pm2 restart zhimingge
+
+# 查看状态
+pm2 status && curl -I http://127.0.0.1:3000
+```
+
+---
+
+## 14. 相关文档
+
+- 产品说明：[docs/SPEC.md](./SPEC.md)
+- 环境变量示例：[../.env.example](../.env.example)
+- PM2 配置：[../ecosystem.config.cjs](../ecosystem.config.cjs)
@@ -0,0 +1,357 @@
+# 知命阁（zhimingge）产品说明文档
+
+> 仓库地址：[https://git.bz121.com/dekun/zhimingge.git](https://git.bz121.com/dekun/zhimingge.git)
+
+## 1. 项目概述
+
+**知命阁（zhimingge）** 是一个融合《周易》原文学习与 AI 智能解读的 Web 应用。项目合并了原「AI 算卦（divination）」应用与「周易 64 卦详解（zhouyi）」内容库，统一在一个 Next.js 应用中运行。
+
+### 核心能力
+
+| 模块 | 路由 | 说明 |
+|------|------|------|
+| 易经学习 | `/learn` | 64 卦原文阅读（繁体精简版 / 简体图文版） |
+| 六爻算卦 | `/liuyao` | 纯六爻起卦 + AI 解读 |
+| 生辰八字 | `/bazi` | 四柱排盘 + AI 命理解读 |
+| 综合测算 | `/combined` | 天时 + 地利 + 人和（六爻可选） |
+
+### 技术栈
+
+- **框架**：Next.js 15（App Router、Server Actions、RSC）
+- **UI**：React 18、Tailwind CSS、shadcn/ui
+- **AI**：Vercel AI SDK + OpenAI 兼容接口
+- **内容**：本地 Markdown（`content/zhouyi/`）
+- **运维**：PM2 + Ubuntu（`/opt/zhimingge`）
+
+---
+
+## 2. 已确认的产品决策
+
+| 项 | 决策 |
+|----|------|
+| 项目名称 | **zhimingge（知命阁）** |
+| 代码仓库 | `https://git.bz121.com/dekun/zhimingge.git` |
+| 模式三六爻 | **可选**，用户可只做天时地利人和，也可附加六爻 |
+| 八字精度 | **四柱、十神、大运、流年、神煞** 全部包含 |
+| 地域粒度 | **省 / 市 / 县（区）** 三级，用于真太阳时与地利分析 |
+| AI 模型 | `huihui_ai/gemma-4-abliterated:e4b` |
+| AI 接口 | `https://op.bz121.com/v1` |
+| 部署方式 | Ubuntu + root + PM2，目录 `/opt/zhimingge` |
+
+---
+
+## 3. 目录结构
+
+```
+zhimingge/
+├── app/                          # Next.js 应用
+│   ├── page.tsx                  # 首页 / 功能入口
+│   ├── layout.tsx
+│   ├── liuyao/                   # 六爻算卦（规划）
+│   ├── bazi/                     # 生辰八字（规划）
+│   ├── combined/                 # 综合测算（规划）
+│   ├── learn/                    # 易经学习（规划）
+│   │   ├── page.tsx              # 64 卦总览
+│   │   └── [guaMark]/page.tsx    # 单卦详情
+│   └── actions/                  # Server Actions（规划）
+│       ├── liuyao.ts
+│       ├── bazi.ts
+│       └── combined.ts
+├── components/
+│   ├── modes/                    # 各模式 UI（规划）
+│   ├── learn/                    # 学习模块（规划）
+│   └── shared/                   # 共用组件
+├── content/
+│   └── zhouyi/
+│       ├── docs/                 # 繁体精简版（AI 解读主用）
+│       │   ├── index.md
+│       │   ├── 01.乾为天/index.md
+│       │   └── ...（64 卦）
+│       └── other/                # 简体图文版（学习页主用）
+│           ├── index.md
+│           └── ...（64 卦）
+├── lib/
+│   ├── calc/                     # 八字、真太阳时、节气（规划）
+│   │   ├── bazi.ts
+│   │   └── time.ts
+│   ├── content/
+│   │   └── zhouyi.ts             # 本地卦辞读取
+│   ├── data/
+│   │   ├── gua-index.json        # 64 卦索引矩阵
+│   │   ├── gua-list.json         # 64 卦名称
+│   │   ├── regions.json          # 省市区 + 经度（规划）
+│   │   └── today.json            # 预设问题
+│   ├── prompts/                  # AI 提示词模板（规划）
+│   └── constant.ts
+├── docs/
+│   ├── SPEC.md                   # 本文档
+│   └── DEPLOY.md                 # 部署文档
+├── public/
+├── ecosystem.config.cjs          # PM2 配置
+├── .env.example                  # 环境变量示例
+├── next.config.js
+└── package.json
+```
+
+---
+
+## 4. 功能模块详细说明
+
+### 4.1 易经学习（/learn）
+
+**目的**：提供 64 卦完整原文阅读，不调 AI。
+
+| 页面 | 内容来源 | 说明 |
+|------|----------|------|
+| `/learn` | `content/zhouyi/docs/index.md` | 64 卦总览表 |
+| `/learn/[guaMark]` | `content/zhouyi/docs/{guaMark}/index.md` | 单卦繁体详解 |
+| `/learn/other` | `content/zhouyi/other/index.md` | 简体图文版入口 |
+| `/learn/other/[guaMark]` | `content/zhouyi/other/{guaMark}/index.md` | 单卦简体详解 |
+
+**内容包含**（因版本而异）：
+
+- 卦辞、爻辞、白话解释
+- 邵雍河洛理数、傅佩荣解卦
+- 台湾张铭仁解卦（AI 六爻解读的主要素材来源）
+- 简体版额外：互卦/错卦/综卦、断易天机、哲学含义
+
+**交互**：学习页底部可跳转「以此卦起卦」→ `/liuyao`。
+
+---
+
+### 4.2 六爻算卦（/liuyao）
+
+**目的**：传统三钱法六爻，结合卦辞 AI 解读。
+
+#### 起卦方式
+
+| 方式 | 说明 |
+|------|------|
+| **线上** | 应用内 3 枚硬币动画，自动随机 6 次 |
+| **线下** | 人工抛铜钱后，手动录入 6 爻结果，再点「测算」 |
+
+#### 爻象规则
+
+| 3 枚正面数 | 名称 | 阴阳 | 变爻 |
+|------------|------|------|------|
+| 3 | 老阳 | 阳 | 是（○） |
+| 2 | 少阳 | 阳 | 否 |
+| 1 | 少阴 | 阴 | 否 |
+| 0 | 老阴 | 阴 | 是（✕） |
+
+#### 输入字段
+
+- **问题**（必填）
+- **起卦时辰**（默认当前时间，可修改）
+- **六爻结果**（线下模式手动录入）
+
+#### 输出
+
+- 卦名、上下卦、变爻列表
+- 链接至 `/learn/{guaMark}` 查看原文
+- AI 流式解读（张铭仁注解 + 变卦说明 + 用户问题）
+
+---
+
+### 4.3 生辰八字（/bazi）
+
+**目的**：根据出生信息排盘，AI 命理解读。
+
+#### 输入字段
+
+| 字段 | 必填 | 说明 |
+|------|------|------|
+| 出生日期 | 是 | 公历，支持农历切换 |
+| 出生时间 | 是 | 精确到分钟；未知时辰可选「时辰不详」 |
+| 性别 | 是 | 决定大运顺逆 |
+| 出生地域 | 是 | 省 / 市 / 县（区）→ 经度 → 真太阳时 |
+| 问题 | 是 | 事业、婚姻、健康等 |
+
+#### 排盘输出（完整精度）
+
+| 项目 | 说明 |
+|------|------|
+| **四柱** | 年柱、月柱、日柱、时柱（天干地支） |
+| **十神** | 比肩、劫财、食神、伤官、偏财、正财、七杀、正官、偏印、正印 |
+| **藏干** | 地支藏干及十神 |
+| **纳音** | 各柱纳音五行 |
+| **大运** | 起运年龄、各步大运干支（顺/逆） |
+| **流年** | 当前及前后若干年流年干支 |
+| **神煞** | 天乙贵人、文昌、驿马、桃花、华盖等常用神煞 |
+| **真太阳时** | 根据出生地经度校正后的时辰 |
+
+#### AI 解读维度
+
+- 命局格局与五行喜忌
+- 十神组合含义
+- 大运流年趋势
+- 神煞吉凶提示
+- 针对用户问题的具体建议
+
+---
+
+### 4.4 综合测算（/combined）
+
+**目的**：融合「天时、地利、人和」，六爻可选。
+
+#### 输入字段
+
+| 维度 | 字段 | 说明 |
+|------|------|------|
+| **人和** | 生辰八字 + 性别 | 同 `/bazi` 排盘 |
+| **地利** | 当前所在省 / 市 / 县 | 经度、方位 |
+| **天时** | 测算时刻 | 默认当前时间；含节气、农历日、时辰、日柱 |
+| **问事** | 问题 | 具体所求 |
+| **卦象** | 可选 | 可接 `/liuyao` 线上/线下六爻，或本页内起卦 |
+
+#### 解读逻辑
+
+```
+天时（节气、日柱、时辰、农历）
+  + 地利（地域经度、方位五行）
+  + 人和（八字命局、十神、大运、流年、神煞）
+  + 卦象（若用户选择起卦）
+  → AI 综合解读
+```
+
+#### 六爻可选行为
+
+- **不起卦**：仅基于八字 + 时空做解读
+- **起卦**：额外带入卦象、变爻及卦辞原文
+
+---
+
+## 5. AI 配置
+
+### 环境变量
+
+```env
+OPENAI_API_KEY=你的密钥
+OPENAI_BASE_URL=https://op.bz121.com/v1
+OPENAI_MODEL=huihui_ai/gemma-4-abliterated:e4b
+```
+
+### 接口说明
+
+- 使用 OpenAI 兼容 API（`/v1/chat/completions`）
+- 通过 `@ai-sdk/openai` 的 `createOpenAI({ baseURL })` 接入
+- 所有模式共用同一模型，通过不同 System Prompt 区分角色
+
+### Prompt 角色
+
+| 模式 | System 角色 |
+|------|-------------|
+| 六爻 | 精通《周易》六爻的 AI 助手 |
+| 八字 | 精通子平八字的命理分析师 |
+| 综合 | 融合天时地利人和的综合顾问 |
+
+### 卦辞来源
+
+- **不再从外部 GitHub 拉取**
+- 统一从 `content/zhouyi/docs/{guaMark}/index.md` 本地读取
+- 提取张铭仁注解、变卦段落注入 Prompt
+
+---
+
+## 6. 地域数据
+
+### 数据结构（规划）
+
+```json
+{
+  "110000": {
+    "name": "北京市",
+    "longitude": 116.4074,
+    "children": {
+      "110101": { "name": "东城区", "longitude": 116.4164 }
+    }
+  }
+}
+```
+
+### 用途
+
+1. **八字真太阳时**：`出生时间 + 出生地经度` → 校正时辰
+2. **综合地利**：当前所在地经度、方位参与解读
+3. **可选扩展**：地域五行、方位卦象（后续版本）
+
+---
+
+## 7. 数据流示意
+
+```
+用户输入
+  │
+  ├─ /learn ──────────→ 读 content/zhouyi/*.md ──→ 页面渲染（无 AI）
+  │
+  ├─ /liuyao ─────────→ 六爻计算 ──→ 读本地卦辞 ──→ AI 流式输出
+  │
+  ├─ /bazi ───────────→ 八字排盘 ──────────────────→ AI 流式输出
+  │
+  └─ /combined ───────→ 八字 + 时空 + [可选六爻] ──→ AI 流式输出
+                              │
+                              ▼
+                    https://op.bz121.com/v1
+                    huihui_ai/gemma-4-abliterated:e4b
+```
+
+---
+
+## 8. 实施分期
+
+### Phase 1 — 合并与基础（当前阶段）
+
+- [x] 内容库迁入 `content/zhouyi/`
+- [x] 项目文档（SPEC、DEPLOY）
+- [x] PM2 部署配置
+- [x] 移除 GitHub / 外部仓库引用
+- [ ] 本地读取卦辞（替换 GitHub fetch）
+- [ ] Header 导航与 `/learn` 学习入口
+- [ ] 六爻线下录入模式
+- [ ] 起卦时辰记录
+- [ ] AI 环境变量默认值更新
+
+### Phase 2 — 八字模式
+
+- [ ] `lib/calc/bazi.ts` 完整排盘（十神、大运、流年、神煞）
+- [ ] `lib/data/regions.json` 省市区数据
+- [ ] 真太阳时计算
+- [ ] `/bazi` 页面与 AI 解读
+
+### Phase 3 — 综合模式
+
+- [ ] `/combined` 页面
+- [ ] 天时（节气、日柱）计算
+- [ ] 六爻可选联动
+- [ ] 综合 Prompt
+
+### Phase 4 — 体验优化
+
+- [ ] 农历日期选择器
+- [ ] 测算历史（localStorage）
+- [ ] 简体/繁体学习版切换优化
+- [ ] 补全 `other/` 版缺失图片
+
+---
+
+## 9. 环境变量完整列表
+
+| 变量 | 必填 | 默认值 | 说明 |
+|------|------|--------|------|
+| `OPENAI_API_KEY` | 是 | — | AI 接口密钥 |
+| `OPENAI_BASE_URL` | 否 | `https://op.bz121.com/v1` | API 地址 |
+| `OPENAI_MODEL` | 否 | `huihui_ai/gemma-4-abliterated:e4b` | 模型名 |
+| `PORT` | 否 | `3000` | 服务端口 |
+| `NODE_ENV` | 否 | `production` | 运行环境 |
+| `UMAMI_ID` | 否 | — | 访问统计（可选，可不用） |
+| `UMAMI_URL` | 否 | — | 统计脚本地址（可选） |
+| `UMAMI_DOMAINS` | 否 | — | 统计域名（可选） |
+
+---
+
+## 10. 版本与许可
+
+- 项目名：**zhimingge**
+- 仓库：`https://git.bz121.com/dekun/zhimingge.git`
+- 周易原文内容遵循原 zhouyi 项目许可
+- 应用代码私有部署，不依赖任何外部公开代码托管服务