Skip to content

SPEC.md

Latest commit

 

History

History
333 lines (279 loc) · 12.2 KB

SPEC.md

File metadata and controls

333 lines (279 loc) · 12.2 KB
Raw
AIGC
Label ContentProducer ProduceID ReservedCode1 ContentPropagator PropagateID ReservedCode2
1
001191440300708461136T1XGW3
98adaa6f98486df4666888a6691e7607_68c138dc89f411f1a093525400287e28
212qEXj8VI0xeeJu3np9zmGrkkXIu+BtfebCeVZnNT0pI7MWeFIchhxiZXDJX0qNafrqOoaxrFTLEsn+qDnpdl0MRbfM3Fg5Xl+sg9nS+G97KhMxWBg15kVGfu9biMQ9zdIjVlaPWBOrOvqQOQXMJvwkRw2I+CjK5A/qBupyUBoElDmr0wANTqr35vU=
001191440300708461136T1XGW3
98adaa6f98486df4666888a6691e7607_68c138dc89f411f1a093525400287e28
212qEXj8VI0xeeJu3np9zmGrkkXIu+BtfebCeVZnNT0pI7MWeFIchhxiZXDJX0qNafrqOoaxrFTLEsn+qDnpdl0MRbfM3Fg5Xl+sg9nS+G97KhMxWBg15kVGfu9biMQ9zdIjVlaPWBOrOvqQOQXMJvwkRw2I+CjK5A/qBupyUBoElDmr0wANTqr35vU=

Echo 技术规范

本文档描述 Echo 项目的架构设计、代码规范和技术约束。版本：v0.4.0。

一、项目定位

Echo 是一个命运印证引擎——不是算命软件，而是假设验证工具。

核心循环：设节点 → 等回响 → 复盘

用户用命理工具排盘得到预测结果 → 设定印证时间节点 → 到期后回来复盘应验情况 → 命格可信度随时间积累。

二、技术栈

技术 版本 用途
Vue 3 ≥3.5 框架（JSX + Composition API）
Pinia ≥4.0 状态管理
Vue Router ≥5.2 路由（Hash 模式）
Vite ≥8.1 构建工具
ECharts ≥6.1 数据可视化（雷达图 / 柱状图 / 折线图 / 饼图）
vue-echarts ≥8.0 ECharts Vue 3 集成

自实现模块：Markdown 渲染器、SVG 关系网络图、Toast / Modal / Progress UI 组件。

三、架构概览

src/
├── main.js                    # 应用入口
├── router/index.js            # 路由（Hash 模式）
├── stores/                    # Pinia 状态管理
│   ├── echo.js                # 命格/历史/档案/工具注册
│   └── chat.js                # AI 对话/模型配置
├── services/                  # 业务服务层
│   ├── ai.js                  # 多模型 AI 对话（SSE 流式）
│   ├── tools.js               # 工具调度与执行
│   ├── sandbox.js             # 安全沙箱（校验/超时/注入检测）
│   ├── webSearch.js           # Tavily 联网搜索
│   ├── fortune.js             # 运势计算服务
│   └── notifications.js       # 提醒与通知服务
├── prompts/
│   └── system.js              # 系统提示词/Few-shot/知识库
├── utils/
│   ├── engines.js             # 18 个命理引擎（纯函数）
│   └── shareUtils.js          # 分享卡片海报生成
├── composables/
│   └── useShake.js            # 摇卦检测 Composable
├── components/                # 基础组件库
│   ├── EchoUI.jsx             # Button/Card/Tag/Modal/Toast/Progress/Gauge
│   ├── TabBar.jsx             # 导航栏（响应式底部/侧边）
│   ├── ChatFab.jsx            # 悬浮 AI 入口
│   ├── BaziChartECharts.jsx   # 五行雷达图 + 十神柱状图（ECharts）
│   ├── YunshiChart.jsx        # 七日运势折线 + 吉凶饼图（ECharts）
│   ├── Timeline.jsx           # 大运流年时间线
│   ├── Onboarding.jsx         # 新手引导弹窗
│   ├── ParticleBackground.jsx # 粒子星空背景（Canvas）
│   ├── ShakeDiviner.jsx       # 摇钱起卦交互组件
│   ├── ShareButton.jsx        # 分享卡片生成
│   └── ToolIcons.jsx          # 18 个自定义 SVG 工具图标
├── pages/
│   ├── Home.jsx               # 首页（五行命盘主界面）
│   ├── Tools.jsx              # 工具列表（4 类 18 种）
│   ├── ToolDetail.jsx         # 工具推演（表单 + 结果渲染）
│   ├── Profile.jsx            # 个人档案
│   ├── Daily.jsx              # 今日运势
│   ├── Dashboard.jsx          # 命格面板（五行雷达 + 建议）
│   ├── Compatibility.jsx      # 合婚匹配
│   ├── EchoCenter.jsx         # 印证中心
│   ├── Graph.jsx              # 命运图谱（SVG 关系网络）
│   ├── Chat.jsx               # AI 对话
│   ├── Me.jsx                 # 个人中心
│   ├── Settings.jsx           # 设置（主题/字号/AI 配置）
│   ├── Admin.jsx              # 管理后台
│   ├── Compass.jsx            # 风水罗盘（实时方位）
│   ├── WelcomePage.jsx        # 欢迎页
│   └── TransitionPage.jsx     # 路由过渡页
├── designs/                   # 设计系统
│   ├── tokens.css             # 设计令牌 v5（颜色/间距/字号/圆角/阴影/动效）
│   ├── base.css               # 全局重置与排版
│   ├── responsive.css         # 响应式断点
│   ├── transition.css         # 路由过渡动画
│   ├── home-wuxing.css        # 首页五行命盘样式
│   ├── animations.css         # 全局动画关键帧
│   ├── extended.css           # 扩展工具类
│   ├── tool-results.css       # 工具结果样式
│   ├── welcome.css            # 欢迎页样式
│   ├── chat.css               # AI 对话样式
│   ├── dashboard.css          # 命格面板样式
│   ├── graph.css              # 命运图谱样式
│   ├── compass.css            # 风水罗盘样式
│   └── admin.css              # 管理后台样式
└── composables/
    └── useShake.js            # 摇卦检测

四、数据流

用户输入 → Profile.jsx → echoStore.setProfile()
                                ↓
                    computeProfileBazi() → profileBazi (getter)
                                ↓
                    Daily/Dashboard/Me 等页面读取

工具推演 → ToolDetail.jsx → toolsService.execute()
                                ↓
                    engines[key].calc(args) → result
                                ↓
                    echoStore.pushHistory() → 持久化到 localStorage

AI 对话 → Chat.jsx → chatStore.send()
                         ↓
              aiService.chatCompletion() → SSE 流式
                         ↓
              onToken → 更新消息 → 渲染
              onToolCall → toolsService.execute() → 工具结果注入

五、命理引擎规范

每个引擎导出 { inputConfig, calc } 结构：

export const myEngine = {
  meta: {
    name: '工具名',
    description: '工具描述',
    inputConfig: [
      { key: 'param1', label: '参数1', type: 'text', required: true },
      { key: 'param2', label: '参数2', type: 'select', options: [...] }
    ]
  },
  calc(args) {
    // 纯函数，无副作用
    // 返回结构化结果对象
    return { summary: '...', /* ... */ }
  }
}

注册流程：

  1. 在 engines.js 实现引擎
  2. 在 echo.js 的 TOOLS 数组注册元信息
  3. 在 tools.js 的 ENGINES 映射关联引擎

六、设计系统

设计令牌 v5

所有视觉属性通过 CSS 自定义属性定义在 tokens.css 的 :root。设计系统已迭代至 v5，采用 rem 字号、WCAG AA 深色规范、完整字体栈与动效变量。

:root {
  /* 字体栈 */
  --font-sans: "PingFang SC", "Microsoft YaHei", "Noto Sans SC", sans-serif;
  --font-serif: "Noto Serif SC", "Source Han Serif SC", "SimSun", serif;

  /* 画布层 — 暖黑系 */
  --bg: #0F0F0F;
  --bg-2: #1A1A1A;
  --bg-3: #242424;
  --bg-4: #2E2E2E;

  /* 文字 — 暖白墨迹（WCAG AA） */
  --ink: #E8E6E3;
  --ink-2: #989491;
  --ink-3: #6B6560;

  /* 主色 — 鎏金 */
  --accent: #D4AF37;
  --accent-2: #A68A2E;
  --accent-soft: rgba(212, 175, 55, 0.10);
  --accent-glow: rgba(212, 175, 55, 0.20);

  /* 副色 — 朱砂赤 */
  --vermilion: #C24034;
  --vermilion-soft: rgba(156, 58, 46, 0.10);

  /* 五行色 */
  --wuxing-fire: #C44536;
  --wuxing-metal: #C4B998;
  --wuxing-water: #4A6FA5;
  --wuxing-wood: #4A7C59;
  --wuxing-earth: #9B8568;

  /* 字号（rem，1rem = 16px） */
  --fs-xs: 0.75rem;    /* 12px — 最小关键文字不低于此值 */
  --fs-sm: 0.875rem;   /* 14px */
  --fs-base: 1rem;     /* 16px — 正文字号，移动端不触发缩放 */
  --fs-lg: 1.25rem;    /* 20px */
  --fs-xl: 1.5rem;     /* 24px */
  --fs-2xl: 2rem;      /* 32px */
  --fs-3xl: 2.5rem;    /* 40px */

  /* 字重 */
  --fw-light: 300;
  --fw-regular: 400;
  --fw-medium: 500;
  --fw-bold: 600;

  /* 间距（4pt 基准） */
  --sp-1: 4px;  --sp-2: 8px;  --sp-3: 12px;
  --sp-4: 16px; --sp-5: 24px; --sp-6: 32px;
  --sp-7: 48px; --sp-8: 64px;

  /* 圆角 */
  --radius-sm: 4px;
  --radius-base: 8px;
  --radius-lg: 12px;
  --radius-xl: 16px;
  --radius-full: 9999px;

  /* 阴影 */
  --shadow-sm: 0 1px 3px rgba(0, 0, 0, 0.3);
  --shadow-base: 0 4px 12px rgba(0, 0, 0, 0.4);
  --shadow-lg: 0 8px 32px rgba(0, 0, 0, 0.5);

  /* 动效 */
  --ease-out: cubic-bezier(0.16, 1, 0.3, 1);
  --ease-in-out: cubic-bezier(0.65, 0, 0.35, 1);
  --duration-fast: 150ms;
  --duration-base: 300ms;
  --duration-slow: 600ms;
}

暗色为默认主题。浅色模式通过 [data-theme="light"] 覆盖令牌值。字号缩放通过 [data-font-scale] 控制。

响应式断点

断点 场景 策略
≤480px 手机 底部 TabBar、单列布局
481-767px 大屏手机 双列网格、紧凑间距
768-1023px 平板 侧边栏导航、双列面板
1024-1279px 小桌面 侧边栏、三列工具网格
1280-1439px 标准桌面 五列工具网格、更大间距
≥1440px 宽屏 / 4K 限制最大宽度、充裕留白

按钮规范

  • 默认 fit-content + min-width: 120px，仅 block 型或底部固定栏全宽
  • 金色按钮使用差异化渐变（linear-gradient + shadow）
  • 禁用状态统一透明度 0.4 + cursor not-allowed

代码规范

  • 2 空格缩进
  • 组件使用 defineComponent + setup() 模式
  • CSS 遵循 BEM 命名，使用设计令牌 var(--token)
  • 列表渲染必须设置 key prop
  • 不使用 TypeScript（纯 JavaScript + JSX）
  • 颜色/字号禁止硬编码

七、动画系统

动画 名称 说明
中央回响 mandalaBreathe 3s 呼吸动画，命盘核心脉动
命盘旋转 mandalaSpin 120s 极缓旋转
扇区脉冲 sectorGlow hover 时金色光晕脉冲
交错入场 staggerFadeIn 工具结果交错渐入
吉凶印章 sealStamp 判语徽章印章 + 光晕入场
路由过渡 pageTransition blur + scale 电影感转场

八、安全机制

沙箱

用户输入 → sanitizeInput → detectInjection → AI
                                    ↓
工具调用 → validateArgs → executeWithTimeout → sanitizeToolResult → AI
                                    ↓
AI 输出 → validateOutput → 追加安全提示

安全护栏

类型 触发条件 处理方式
医疗 涉及疾病、用药 仅五行养生角度，建议就医
法律 涉及纠纷、官司 不预测输赢，建议咨询律师
财务 涉及投资、理财 不做收益保证，强调风险
危机 检测到自残倾向 优先安全，提供援助热线
绝对化 要求确定预测 软性表述，说明局限

详见 SECURITY.md。

九、命格等级系统

等级 称号 经验阈值
1 初悟 0
2 渐悟 50
3 开悟 200
4 通玄 500
5 明机 1,000
6 知命 2,000
7 洞微 3,500
8 见性 5,000
9 达理 6,500
10 圆融 8,000
11 天启 10,000

经验值 = Math.round(匹配度 × 30) + 10（每次复盘印证）。签到 +5，引导完成 +20。

十、交付标准

  1. npm install && npm run dev 可正常启动
  2. npm run build 构建无错误
  3. 所有页面可访问，所有按钮有响应
  4. 响应式布局在 320px-4K 范围内无溢出
  5. 设计令牌指标达标（无硬编码色值/字号）
  6. 安全沙箱和护栏正常工作
  7. ECharts 图表正确渲染，数据与引擎一致 （内容由AI生成，仅供参考）