# snake-web

**Repository Path**: rambox/snake-web

## Basic Information

- **Project Name**: snake-web
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-14
- **Last Updated**: 2026-09-14

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# snake-web

雪球首页业务骨架（Vue 3 + TypeScript + Vite）。当前阶段为**前端业务骨架 + 静态数据**，用于跑通页面结构、模块划分与数据流，后续接入真实 REST 接口。

## 技术栈

| 项 | 选型 |
| --- | --- |
| 框架 | Vue 3（`<script setup>` + TS） |
| 构建 | Vite 8 |
| 状态 | Pinia |
| 路由 | Vue Router 5 |
| 样式 | 原生 CSS + CSS 变量（无预处理器、无 UI 库） |

## 架构原则

**按业务切分，而非按技术切分。** 每个业务模块自包含 `api` / `store` / `components`，横向只把真正跨业务复用的东西放进 `shared`。

```
src/
├── main.ts · App.vue · router/         入口与路由表
├── views/                              页面「薄壳」，只负责装配，不写业务逻辑
│   ├── layout/                         AppLayout（三栏骨架）
│   └── home/ · watchlist/ · market/ · fund/ · messages/ ...
├── modules/                            业务模块（高内聚）
│   ├── home/          顶部 Banner · 三大指数 · 主动优选
│   ├── watchlist/     自选股票 / 基金 / 组合
│   ├── hot-topics/    热门话题榜
│   ├── hot-stocks/    热股榜
│   ├── message-center/消息中心与子 Tab
│   └── navigation/    TopBar · SideNav · RightAside
├── shared/                             跨业务复用层
│   ├── api/           mock HTTP 客户端 + endpoint 注册表
│   ├── types/         全局类型
│   ├── components/    ChangeTag · AppIcon · SectionCard · EmptyState ...
│   ├── styles/        reset.css + variables.css（设计 token）
│   └── utils/         格式化工具
└── mock/              *.json 静态数据 + 注册入口
```

### 数据流

```
组件 → store（Pinia） → 模块 api.ts → shared/api/http.ts → mock JSON
```

关键点：**路由层与组件都不直接 import JSON**，只通过 `api.ts` 取数。后期对接后端时，只需替换 `shared/api/http.ts` 的实现并移除 `main.ts` 里的 `setupMock()` 调用，业务代码零改动。

## 常用命令

```sh
npm install
npm run dev          # 本地开发
npm run type-check   # 类型检查
npm run build        # 生产构建
npm run test:unit    # 单元测试
npm run lint         # 代码检查
```

## 接入真实接口

1. 修改 `src/shared/api/http.ts`：把 `get()` / `post()` 内部换成 `fetch` 或 `axios` 请求。
2. `src/shared/api/endpoints.ts` 中的路径改为后端真实路径。
3. 删除 `main.ts` 中的 `setupMock()` 调用及 `src/mock` 目录。

## 仓库卫生（提交前须知）

`.gitignore` 已排除三类文件，遇到"这个文件该不该提交"时对照即可：

| 类别 | 内容 | 原因 |
| --- | --- | --- |
| 可再生产 | `node_modules/`、`dist/`、`coverage/`、`test-results/`、`playwright-report/`、`*.tsbuildinfo`、`.eslintcache`、`.vite/` | 一条命令即可重建，入库只会污染 diff |
| 含私密信息 | `.env*`、`.npmrc`、`*.pem` / `*.key` 等 | 一旦入库即永久留在历史里，删除文件也抹不掉 |
| 本机专属 | `.idea/`、`.vscode/*`、`.workbuddy/`、`__pycache__/` | 个人配置，共享会造成冲突 |

补充约定：

- **环境变量**：只提交 `.env.example` 模板，实际值写进 `.env.local`（已忽略）。只有 `VITE_` 前缀的变量会暴露给前端，真实密钥一律放后端。
- **mock 账号**：`src/mock/users.json` 里的 `demo / 123456`、`admin / admin888` 是本地演示用的假账号，仅用于跑通登录流程，接入真实接口时会连同 `src/mock` 一起删除；不要把它当作任何真实凭据，也不要改成自己的常用密码。
- **截图资产**：`doc/screenshots/` 下的 PNG 会被文档引用，属于可提交资产；若后续体积显著增长，再考虑 Git LFS。

首次提交前建议自检：

```sh
git add -A --dry-run          # 预览将入库的文件，确认无 node_modules / dist / .env
git status --porcelain        # 确认 .workbuddy/ 等本地目录已不被列出
git check-ignore -v .env.local
```

## 涨跌配色约定

遵循 A 股 / 雪球惯例：**涨 = 红，跌 = 绿**（与欧美相反）。色值统一在 `src/shared/styles/variables.css` 的 `--color-up` / `--color-down`，由 `shared/components/ChangeTag.vue` 统一渲染，勿在业务组件里各写一套。