g3fo-recurring-investment/README.md

# 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/recurring-investment/`（由 `.env.development` 的 `VITE_BASE_URL` 决定，对应 Vite `base` 与 Vue Router `history`）。`vite.config.ts` 已设置 `server.host: true`，启动后终端会打印 **Network** 地址，同网段设备可用本机 IP 访问（如 `http://192.168.x.x:5173/recurring-investment/`）；经内网穿透或自定义域名访问时依赖 `allowedHosts: true`。

未带查询参数时，语言为繁体（`lang=tw`）、主题为深色（`theme=dark`）。

## 构建

```bash
npm run build    # vue-tsc + vite build
npm run preview  # 预览生产构建
```

## 环境变量

| 文件 | 变量 | 说明 |
|------|------|------|
| `.env.development` / `.env.production` | `VITE_API_BASE_URL` | 接口基础路径，默认 `/api` |
| 同上 | `VITE_BASE_URL` | 应用部署子路径，默认 `/recurring-investment`（写入 Vite `base`） |

## 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 写法）。