113 lines
4.8 KiB
Markdown
113 lines
4.8 KiB
Markdown
# Schedule Invest Plan
|
||
|
||
Vue 3 + TypeScript 前端：定期投资计划页面。技术栈包括 Vite、Vue Router、Pinia、Axios、vue-i18n、Sass、ECharts、Element Plus（按需自动导入）。
|
||
|
||
## 环境要求
|
||
|
||
- Node.js 18+（建议与团队 CI 一致）
|
||
- npm
|
||
|
||
## 开发
|
||
|
||
```bash
|
||
npm install
|
||
npm run dev
|
||
```
|
||
|
||
默认开发地址：`http://localhost:5173/`。`vite.config.ts` 已设置 `server.host: true`，启动后终端会打印 **Network** 地址，同网段设备可用本机 IP 访问（如 `http://192.168.x.x:5173/`）；经内网穿透或自定义域名访问时依赖 `allowedHosts: true`。
|
||
|
||
未带查询参数时，语言为繁体（`lang=tw`）、主题为深色（`theme=dark`）。
|
||
|
||
## 构建
|
||
|
||
```bash
|
||
npm run build # vue-tsc + vite build
|
||
npm run preview # 预览生产构建
|
||
```
|
||
|
||
## 环境变量
|
||
|
||
| 文件 | 变量 | 说明 |
|
||
|------|------|------|
|
||
| `.env.development` | `VITE_API_BASE_URL` | 接口基础路径，默认 `/api` |
|
||
|
||
## URL 查询参数
|
||
|
||
宿主 App 打开 H5 时，查询参数与 `token`、`lang`、`theme` 同级挂在入口 URL 上。路由跳转请用 `useRouteWithPreferences().linkTo(path)`，会**保留当前整条 query**（含 `clientId`、`accountId`、`token` 等）。
|
||
|
||
| 参数 | 必填 | 说明 |
|
||
|------|------|------|
|
||
| `token` | 是（调接口） | 登录态；URL 带入后会写入 `localStorage` 供请求头使用（见 `src/utils/token.ts`） |
|
||
| `clientId` | 是（交易相关接口） | 客户 ID；**仅自 URL 解析**，不入 `localStorage`，存 Pinia（`src/config/urlContext.ts`） |
|
||
| `accountId` | 是（交易相关接口） | 账户 ID；规则同 `clientId` |
|
||
| `lang` | 否 | 界面语言，见下表；缺省 `tw` |
|
||
| `theme` | 否 | 深浅色，见下表；缺省 `dark` |
|
||
|
||
`clientId` / `accountId` 在 `App.vue` 监听 `route.query` 时同步到 `useAuthStore`；`src/api/http.ts` 对 **POST** 请求体会自动合并二者（与 Order-H5 交易接口一致）。创建定期投资等操作需同时具备 `token` 与账户上下文。
|
||
|
||
语言与主题**仅通过 URL** 控制（不写 `localStorage`）。解析与写入见 `src/config/urlPreferences.ts`；切换语言/主题请使用 `useUrlPreferences()`（`router.replace` 更新 query）。
|
||
|
||
### 语言 `lang`（别名 `locale`）
|
||
|
||
| URL 取值 | 界面语言 | 内部 i18n |
|
||
|----------|----------|-----------|
|
||
| `zh` | 简体中文 | `zh-CN` |
|
||
| `tw` | 繁体中文 | `zh-TW` |
|
||
| `en` | English | `en-US` |
|
||
|
||
- **缺省**：`tw`（繁体）
|
||
- 仍兼容旧式 BCP 47 写法（如 `zh-TW`、`zh-CN`、`en-US`），但地址栏写入统一为 `zh` / `tw` / `en`。
|
||
- Element Plus 文案随当前语言同步（`src/element-plus/locale.ts` + 根节点 `el-config-provider`）。
|
||
|
||
### 主题 `theme`
|
||
|
||
| 取值 | 说明 |
|
||
|------|------|
|
||
| `dark` / `night` | 深色（缺省） |
|
||
| `light` / `day` | 浅色 |
|
||
|
||
深色模式下为 `html` 增加 `dark` 类，并应用 Element Plus 深色 CSS 变量（`applyTheme` 设置 `data-theme`）。
|
||
|
||
### 示例
|
||
|
||
完整入口（本地开发请将 `token` 换成有效值）：
|
||
|
||
```
|
||
http://localhost:5173/?token=xxx&clientId=2016410736418492416&accountId=2016410907965526016&lang=tw&theme=dark
|
||
```
|
||
|
||
仅调整语言 / 主题时，仍须保留 `token`、`clientId`、`accountId`：
|
||
|
||
```
|
||
http://localhost:5173/?token=xxx&clientId=2016410736418492416&accountId=2016410907965526016&lang=zh&theme=light
|
||
http://localhost:5173/?token=xxx&clientId=2016410736418492416&accountId=2016410907965526016&lang=en&theme=dark
|
||
```
|
||
|
||
## 目录说明
|
||
|
||
| 路径 | 说明 |
|
||
|------|------|
|
||
| `src/api/` | Axios 实例、拦截器 |
|
||
| `src/config/` | URL 偏好（`urlPreferences.ts`）、账户上下文（`urlContext.ts`）、`appLocale` 等 |
|
||
| `src/stores/auth.ts` | `token`、`clientId`、`accountId`（后两者仅来自 URL） |
|
||
| `src/composables/` | `useUrlPreferences`、`useRouteWithPreferences`、`useBreakpoint` 等 |
|
||
| `src/i18n/` | vue-i18n 与简体 / 繁体 / 英文文案 |
|
||
| `src/router/` | 路由 |
|
||
| `src/stores/` | Pinia 状态 |
|
||
| `src/styles/` | 全局 Sass、断点 mixin、主题变量 |
|
||
| `src/views/RecurringInvestmentView.vue` | 定期投资首页 |
|
||
| `src/element-plus/locale.ts` | Element Plus 与 `AppLocale` 映射 |
|
||
| `src/types/components.d.ts` | 组件自动导入类型（构建生成） |
|
||
| `docs/RESPONSIVE_SPEC.md` | PC / 移动端响应式规范 |
|
||
|
||
### Element Plus
|
||
|
||
- `unplugin-vue-components` + `unplugin-auto-import` 按需引入组件与 API。
|
||
- 勿在业务中绕过 store 直接改 `i18n.global.locale` 或主题；应走 URL query 同步链路（见 `.cursor/rules/vue-sfc-patterns.mdc`）。
|
||
|
||
## PC / 移动端适配
|
||
|
||
开发与评审须遵循 **[docs/RESPONSIVE_SPEC.md](./docs/RESPONSIVE_SPEC.md)**（断点、布局壳层、Sass mixin、`useBreakpoint`、Element Plus 栅格与表单约定）。
|
||
|
||
Cursor 项目规则：`.cursor/rules/`（核心约定、响应式、Vue SFC 写法）。
|