# 技术框架的搭建步骤
## 第一步，明确技术栈：将下面的技术栈要求写入 specs/tech-specs.md
```
## 技术栈与依赖
### 可行性结论
本规格在下列约束下**可实现**（版本已核对可安装；通义千问 / 高德 / Open-Meteo / Pandorium 均有对应官方接口）。实现时必须遵守本节与「实现陷阱」，否则本地参考图、地图浮层、本命盘调用会失败。
| 原规格风险 | 可行做法 |
| --- | --- |
| 参考图要求「公网 URL、禁止 base64」 | 百炼文档**同时支持**公网 URL 与 `data:{mime};base64,{data}`。本地 `localhost` 对 DashScope 不可达，**有照片时用 Base64**（缩小后，单图 ≤10MB）。禁止 `http://localhost` URL，禁止无图改走纯文生图。 |
| 内嵌高德地图 vs「Key 禁止 `NEXT_PUBLIC_*`」 | REST（地理编码 / 周边搜 / POI 详情）只走服务端。浮层地图用官方 **URI H5**（`https://uri.amap.com/marker`、`/navigation`），**不加载 JS API，不把 Key 送到浏览器**。 |
| 档案只有出生日期，MCP 禁止只传日期 | 太阳星座本地计算。`calculate_natal_chart` / `get_current_transits` 补全 `birthData`：`time=12:00` + **当前有效定位**（或手动城市地理编码）+ IANA 时区。精度有限，不扩档案字段。 |
| `QWEN_CHAT_MODEL_FALLBACK=qwen-flash / qwen-turbo` | 环境变量只能是**一个**模型名。本项目回退为 `qwen-flash`。 |
| 需求文案「10 秒生成完毕」vs 本文件 20s 目标 | **以本文件为准**：约 10s 软提示，目标 ≤20s；不要 10s 硬切降级。需求文档已对齐。 |
### 技术栈
| 类别 | 技术 | 版本 |
| --- | --- | --- |
| 框架 | Next.js（App Router） | 16.3.0 |
| UI / 语言 | React · TypeScript | 19.2.8 · 7.0.2 |
| 样式 | Tailwind CSS | 4.3.1 |
| 状态 / 表单 | React Query · Zustand · RHF + Zod + `@hookform/resolvers` | 5.101.4 · 5.0.15 · 7.85.0 + 4.4.3 + 5.7.1 |
| 存储 | 本地 JSON（`data/`）--- 无数据库 | --- |
| AI | `openai` SDK → 通义千问 DashScope compatible-mode | 6.39.0 |
| 测试 | Vitest · RTL · Playwright | 4.1.9 · 16.3.2 · 1.61.1 |
规则：尽量少依赖；优先平台与标准库；**禁止数据库**（除非项目规格另有说明，否则仅使用 `data/` 下本地 JSON）。只接入产品实际需要的第三方能力------不要默认把下文所有服务都接上。
不要新增：Prisma / 数据库、MCP SDK、高德 JS API、OSS SDK、`NEXT_PUBLIC_*` 密钥。图像缩小使用 Next 已带的 `sharp`。坐标转换、WMO→中文、太阳星座、MCP JSON-RPC 用标准库 / `fetch` 自写。
### 最小依赖策略
- 尽量少用依赖------优先平台能力、标准库与现有技术栈，再考虑新增包。
- 保持架构干净：不为「以防万一」引入可选库。
### npm 安装
在**中国大陆**与**香港**，请通过阿里云 npmmirror 安装包：
```bash
npm config set registry https://registry.npmmirror.com
# 或单次：
npm install --registry=https://registry.npmmirror.com
# 若报 edgesOut 空指针，加 --legacy-peer-deps，不要改锁定版本
```
其他地区可用默认 npm 注册源。
## 第三方能力与 API (大陆地区和香港地区通用)
### DashScope（通义千问）对话能力：`QWEN_CHAT_MODEL`
- API 配置
- Model-name=`QWEN_CHAT_MODEL`（失败可降级 `QWEN_CHAT_MODEL_FALLBACK`，必须是单一模型 id）
- Host=`QWEN_HOST`
- API-Key=`QWEN_API_KEY`
- Base_URL=`QWEN_BASE_URL`
- Workspace=`QWEN_WORKSPACE` · Region=`QWEN_REGION`
- 技术要点
- 端点：经 `openai` SDK 调用 OpenAI 兼容 `/chat/completions`；`baseURL` 用工作空间专属域名 `QWEN_BASE_URL`（`https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1`）
- 请求头：若出现 `Model.AccessDenied`，在 SDK `defaultHeaders` 加 `X-DashScope-Workspace: $QWEN_WORKSPACE`
- 参数：OpenAI 兼容面**优先** `max_completion_tokens`。百炼文档写明该字段支持 Qwen3.5-Plus / Flash 及更新模型；本项目默认 `qwen-plus` **不在该名单**。实现：先发 `max_completion_tokens`；若上游 400 / 明确拒收该字段，**同请求语义改发 `max_tokens`**，不要因此让整次对话失败。
- 用途：星座建议、穿搭文字（JSON 结构化输出）。不要用该 SDK 调图像。
- **中国大陆 / 香港优先选用**
- 失败时：向调用方返回错误，供组件展示错误并重试------禁止静默空成功
- 产品行为：见项目需求文档
### DashScope（通义千问）图像能力：`QWEN_IMAGE_MODEL`
- API 配置
- Model-name=`QWEN_IMAGE_MODEL`（`qwen-image-2.0`）
- Host=`QWEN_HOST`
- API-Key=`QWEN_API_KEY`
- Base_URL（原生）=`QWEN_NATIVE_BASE_URL`（`https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1`）
- 技术要点
- 端点：原生 `POST {QWEN_NATIVE_BASE_URL}/services/aigc/multimodal-generation/generation`（对话用 compatible-mode，不要混用；不要假设与 OpenAI `/images` 一一对应）
- 请求体：`input.messages` 仅一轮；`role=user`；`content` 是对象数组，每项 `{ text }` 或 `{ image }`，不要用字符串 content；有且仅有一个 `{ text }`
- 参数（仅文档已记载）：`n: 1`、`size: "1024*1536"`（2:3 竖图，总像素在 512×512～2048×2048）、`watermark: false`、**`prompt_extend: false`**（默认 `true` 会拉长耗时，无法稳定压进 20s）。不要自造 quality / 用 `x` 连接宽高。
- 用途：文生图（无档案照片）/ 图像编辑（有档案照片）
- **有档案照片时必须走带参考图的图像编辑**，禁止静默改走纯文生图：
- `photoPath` 只存文件名；从 `data/uploads/` 读取（`uploadsDir()`，不要 `cwd + photoPath`）
- 服务端用 `sharp` 缩小参考图（长边约 1024px，JPEG/WebP，≤10MB）
- `{ image }` 取值（按优先级）：文档记载的公网 HTTPS URL → **Base64 `data:image/jpeg;base64,...`**（本地默认走这条）。**禁止** `http://127.0.0.1` / `localhost` URL（DashScope 拉不到）。不要为了「必须公网 URL」去接 OSS 或 ngrok。
- 请求 content 须同时含 `{ image }` 与 `{ text }`
- 读失败须报错/可重试；有照片却不像本人：先确认读到了文件，再确认 content 带了 `{ image }`
- 成功响应：`output.choices[0].message.content[0].image` 为图片 URL（约 24h 有效）------**立刻下载到 `data/uploads/`**，页面只引用本地文件，不要长期直链上游
- **性能调优（组件目标 ≤20s；软提示约 10s------见「性能」）：**
- 使用任务可接受的**最低**文档尺寸------不要为「更好效果」擅自升高；不支持的参数会失败或浪费时间
- **每个逻辑请求一张图**（`n: 1`）；禁止对同一输出并行重复调用
- **短而结构化的提示词**------只写任务摘要；避免重复界面上已展示的长上下文
- 文本已可用时，**不要**把依赖的文本 LLM 与图像生成串在同一关键路径上------先返回文本，再尽快返回图像
- 服务端路由：复用单一 HTTP 客户端；出站 **HTTP 超时约 25s**（高于 20s 目标的缓冲）------**不要**另做一套 **10s 硬中止**，在 UI 仍显示进度时把请求掐掉
- 上游较慢时：保持请求直至超时/错误；客户端约 10s 后提示「还需要更多时间」（见「性能」）------禁止把服务端切断映射成「Timeout」字样
- 重试：每条尝试路径最多 **一次** 由用户显式触发的重试；禁止在 20s 内自动循环重试
- 失败时：向调用方返回错误------禁止静默空图
- 产品行为：见项目需求文档
### 高德地图（AMap）能力：高德开放平台
- API 配置
- Platform=`AMap (Gaode / 高德地图)`
- Host=`AMAP_HOST`
- API-Key=`AMAP_API_KEY`（**Web 服务** Key，仅服务端）
- Base_URL=`AMAP_BASE_URL`
- 技术要点
- **中国本地图**------大陆应用默认优先于直连 Google
- **服务端 REST（Key 不出浏览器）**
- 地理编码：`GET /v3/geocode/geo`------手动城市/商圈 → GCJ-02
- 周边搜索：`GET /v5/place/around`（或 v3 等价），`location=lng,lat`（经度在前），`radius=3000`，`sortrule=distance`
- POI 详情：有 `id` 时再查详情，取评分 / 简短评价；无评价则不展示高德评价块，不要编造
- **浏览器地图：URI H5，不用 JS API**
- 标注：`https://uri.amap.com/marker?position={lng},{lat}&name={name}&src=myday&coordinate=gaode`
- 导航：`https://uri.amap.com/navigation?to={lng},{lat},{name}&mode=walk&src=myday&callnative=1`
- 浮层内用 `` 或跳转；Escape / 点击背景关闭。不要引入 `webapi.amap.com` 脚本，不要 `NEXT_PUBLIC_AMAP_*`
- **坐标系**
- 浏览器 `geolocation` 与 Open-Meteo：**WGS-84**
- 高德 REST / URI 默认：**GCJ-02**
- 浏览器定位：保留 WGS-84 查天气；转 GCJ-02 后再调高德。转换用本地公式，不新增包
- 手动城市：地理编码结果已是 GCJ-02，**不要再转**再去搜餐厅；查天气时 **GCJ-02 → WGS-84**
- 坐标约 `35.86, 104.20`（中国国家质心，容差约 0.05°）或 `accuracy > 8000m` 视为无效定位
- 周边搜固定 3 公里，有结果即停，禁止扩半径。检索阶梯：
1. `keywords=` + `types=050000`
2. 仅 `keywords=`
3. 仅 `types=050000`
- 菜系关键词（可微调，须覆盖需求示例）：日式→`日本料理`；西班牙式→`西班牙菜`；意式→`意大利菜`；快餐→`快餐`；粤菜→`粤菜`
- `infocode != 10000` 或空列表：向调用方返回错误或「换菜系 / 改地点」文案------禁止空白列表、禁止静默空成功
- 产品行为：见项目需求文档
### Open-Meteo 能力：天气预报
- API 配置
- Service=`Open-Meteo`
- Host=`OPEN_METEO_HOST`
- API-Key=无
- Base_URL=`OPEN_METEO_BASE_URL`
- 技术要点
- 端点：`GET {OPEN_METEO_BASE_URL}/forecast`
- 参数：`latitude` `longitude`（**WGS-84**）+ `current=temperature_2m,relative_humidity_2m,weather_code,wind_speed_10m` + `timezone=auto`
- 用途：气温、湿度、天气现象、风力
- `weather_code` 为 WMO 代码，**必须映射为中文**后再展示（如 0 晴、61 小雨、95 雷暴）。不要把英文 `weather` 字符串或裸代码直接给用户
- 文档：`OPEN_METEO_DOCS`
- 失败时：向调用方返回错误------禁止静默空成功
- 产品行为：见项目需求文档
### Pandorium MCP 能力：Streamable HTTP MCP
- API 配置
- Service=`Pandorium MCP`
- Host=`PANDORIUM_HOST`
- API-Key=无
- Base_URL=`PANDORIUM_MCP_URL`
- 技术要点
- 传输：Streamable HTTP（JSON-RPC POST，SSE `data:` 响应）。用 `fetch` 解析 `data:` 行，**不要**加 MCP SDK
- 工具：`get_planet_positions`、`calculate_natal_chart`、`get_current_transits`（先 `tools/list` 确认）
- `birthData` 形状（禁止只传出生日期）：
```json
{
"date": "1990-03-15",
"time": "12:00",
"location": {
"latitude": 31.2304,
"longitude": 121.4737,
"timezone": "Asia/Shanghai",
"city": "上海"
}
}
```
- `date`：档案出生日期
- `time`：需求无出生时刻 → 固定 `12:00`
- `location`：当前有效定位（WGS-84 即可；MCP 不走高德）。无效定位时不要调用 MCP，返回定位错误
- 太阳星座、年龄：本地按出生日期计算，不打 MCP
- 用途：本命盘 / 行运给通义千问做「今日宜/不宜」等建议
- 失败时：向调用方返回错误------禁止静默空成功
- 产品行为：见项目需求文档
## 天气与星座：限流与解耦
Pandorium MCP 限流严格。超限返回 HTTP 429，响应体**不是** JSON-RPC，而是 `{"success":false,"error":"Too many requests","retryAfter":132}`。窗口常以分钟计。既有项目曾在测试中连打 live MCP，开发结束时上游已限流，成品无法使用。
**链路**
- 天气（Open-Meteo）与星座（Pandorium）并行、互不等待；穿搭可在天气未返回时先生成
- 前端星座请求禁止把 `weather` 放进 `useEffect` 依赖------天气晚到会二次触发 MCP→LLM，直接打满配额
- 同一档案同一日，本命盘 / 行运各最多请求一次；禁止对 429 自动重试（须等 `retryAfter` 过后再由用户触发）
**错误**
- 限流体先认 `success === false`，取出 `retryAfter` 展示给用户
- 不要按 JSON-RPC `error.message` 解析（该字段为 `undefined`，会变成空的「MCP 错误」）
**测试**
- 单元 / 集成 / CI 用夹具，禁止出网打 Pandorium
- live 冒烟两次间隔至少 30 秒；开发过程不要把 live MCP 当日常回归
## 数据与路由（无数据库）
| 路径 | 职责 |
| --- | --- |
| `data/profiles.json` | 档案数组（id、姓名、性别、出生日期、身高、体重、职业、`photoPath` 文件名或空） |
| `data/uploads/` | 用户照片与下载后的穿搭图 |
| 测试 | `DATA_DIR` 指向临时目录；默认 `data/` |
服务端 Route Handler（均不把密钥返回客户端）：档案 CRUD 与上传；规划页提交状态（心情、在做什么、有效坐标）；今日计划分块接口------天气、星座洞察、穿搭文字、穿搭图、餐厅列表 / 详情。各块独立、可并行，失败只影响本块。
## 环境变量
将密钥复制到 `.env.local`（已 gitignore；勿提交）。不要在源码中硬编码。规格仅列出**环境变量代码**------本地自行填值。权威清单见 [`keys.cn.md`](./keys.cn.md)。
```env
# QWEN DashScope（通义千问）
QWEN_API_KEY=
QWEN_HOST=
QWEN_BASE_URL=
QWEN_NATIVE_BASE_URL=
QWEN_WORKSPACE=
QWEN_REGION=
QWEN_CHAT_MODEL=
QWEN_CHAT_MODEL_FALLBACK=
QWEN_IMAGE_MODEL=
QWEN_KEY_MGMT_SITE=
# 地图（Web 服务 Key，仅服务端）
AMAP_API_KEY=
AMAP_HOST=
AMAP_BASE_URL=
AMAP_KEY_MGMT_SITE=
# 天气（无需密钥）
OPEN_METEO_HOST=
OPEN_METEO_BASE_URL=
OPEN_METEO_DOCS=
# 星座 MCP（无需密钥）
PANDORIUM_HOST=
PANDORIUM_MCP_URL=
# 可选：测试用临时数据目录
DATA_DIR=
```
`QWEN_KEY_MGMT_SITE`、`AMAP_KEY_MGMT_SITE`、`OPEN_METEO_DOCS` 仅文档 / 排障，运行时不要依赖。
## 性能
图像生成另有调优约定------见「DashScope（通义千问）图像能力」下的性能调优。
**延迟（所有组件------仅此一套约定）：**
- 软提示：约 **10s** 后展示「还需要更多时间」，同时继续等待（禁止使用「Timeout」字样）
- 目标：每个组件在 **≤20s** 内就绪
- **不要**另做一套冲突的 10s 硬超时，在无用户可见状态时提前放弃组件
**加载策略（所有组件）：**
- 独立组件之间**并行**请求
- 各块完成后即**流式 / 渲染**------不要因最慢的一块卡住整页
- 等待期间展示**按组件**的提示与进度
**降级：**
- 仅在上游失败，或用户可见等待路径结束后组件仍为空时，使用**本地降级**
- **不要**在约 10s 时静默切到降级，而 UI 仍暗示正在实时生成
## 实现陷阱（必须遵守）
实现时对照项目需求文档核对：
| 领域 | 约定 |
| --- | --- |
| **地区 / LLM** | 中国大陆 / 香港 OpenAI 不可用或不稳定------使用工作空间专属 DashScope 域名；不要假设全球统一 LLM 主机 |
| **对话** | 优先 `max_completion_tokens`；`qwen-plus` 拒收时回退 `max_tokens`。`QWEN_CHAT_MODEL_FALLBACK` 只能是一个模型 id |
| **图像（DashScope）** | 原生多模态端点；`content` 为 `{ text }` / `{ image }`；`size=1024*1536`；`prompt_extend: false`；有照片必须带参考图（本地用 Base64）；禁止 localhost URL；禁止静默文生图；生成 URL 立刻落盘 |
| **地图** | 高德 Key 仅服务端------禁止 `NEXT_PUBLIC_*`；餐厅 REST + URI iframe，不用 JS API；WGS-84↔GCJ-02；拒绝国家质心/`accuracy>8km`；3km 内三阶检索，不扩半径；空列表要有文案 |
| **坐标** | 天气用 WGS-84；高德用 GCJ-02。手动城市编码结果不要再转去搜餐厅 |
| **Pandorium** | 限流严格；天气与星座并行；`birthData` 必须含 time + location；测试勿连打 live MCP |
| **延迟** | 软提示约 10s · 就绪目标 ≤20s------**仅此一套约定** |
| **密钥** | 仅通过 `.env.local`------切勿在规格或仓库中提交真实密钥 |
| **存储 / 参考图** | `photoPath` 是 `data/uploads/` 下的文件名；读失败须报错，禁止静默文生图 |
| **npm** | npmmirror 遇 `edgesOut` 时用 `--legacy-peer-deps`，不要改规格版本 |
## 本地化说明（i18n）
本技术栈**不受** always-on 规则中 i18n 默认需求的约束。用户可见文案允许硬编码中文；项目的本地化策略由需求文档决定（本项目仅中文）。
## 质量门槛与测试
本技术栈每个项目必须满足的最低门槛（依据 `common-test-strategy` 基线，而非其完整默认清单）：
- 业务逻辑必须配单元测试；变更关键路径 **100%** 覆盖（含：无效定位判定、WGS-84↔GCJ-02、WMO→中文、太阳星座、菜系关键词、有照片必须带 `{ image }`）
- API / 数据边界路径配集成测试（夹具，默认不出网）
- 至少一条关键用户旅程用真实浏览器 E2E 覆盖（档案 → 规划 → 今日计划分块渲染）
- 测试使用临时数据目录------绝不用生产数据
- 无数据库：持久化仅用 `data/` 下本地 JSON；照片等上传文件在 `data/uploads/`，JSON 只存文件名
**豁免：** 本技术栈不受 `common-test-strategy` 完整默认清单的约束；更严格的项目级测试策略可在各项目需求文档 / 测试策略文档中定义。
```
## 安装开发依赖项，接入 AI 模型能力和MCP能力
### 安装过程中，尽可能自动操作：
- 需要做任何操作，或者执行脚本的时候，不要问我要不要执行，默认按照需要执行自动操作
- 只要在实在无法执行的时候才中断，并向我确认
- 遇到问题首先尝试自己解决问题，实在解决不了的时候才中断，并向我确认
### 操作步骤
1. 执行以下命令，完成 specs/stack.md 文件中的 "开发依赖项" 部分的依赖项安装
```
# 安装开发依赖项
1. 切换到aliyun的 npm 镜像：https://registry.npmmirror.com
2. 按照 specs/stack.md 中的"开发依赖项"部分的定义，完成开发依赖项的安装
```
2. 执行以下命令来配置需要的AI能力、外接API能力和MCP能力
```
# 按照 specs/tech-specs.md 中的"API 和 MCP 服务"部分的定义， 测试AI API Key, 高德地图 API Key，以及MCP服务
# 成功以后写入 .env:
```
## 依赖项、AI、地图、MCP服务安装完成后，验证上述能力都已经安装完成
### 开发一个最简单的页面验证通用AI、图形AI、A-MAP地图API、天气MCP
#### 用户画像（非功能性需求） Jade Xu:
- 出生日期详情： 2002年1月17日上午6:27AM
- 性别男
- 身高183
- 体重80KG
- 籍贯：江苏南通
- 饮食偏好：淮扬菜
#### 页面功能打开后自动加载以下功能：
##### 功能1：用户介绍（页面左上）
- 列出Jade个人信息
- 根据功能4的结果，为Jade生成肖像并展示
##### 功能2：根据当前日期为Jade生成一天星座分析（页面右上）
##### 功能3：一周天气预报（页面左下）
- 根据浏览器获取的当前位置的经纬度数据，获得后一周的天气预报
- 结果翻译成中文
- 文字展示天气摘要
- 图形展示天气趋势
##### 功能4：穿搭推荐（展示部分体现在功能1）
- 根据当天、浏览器获取的当前位置的天气，和Jade的星座分析，推荐穿搭
- 不用形成文字，用图片处理AI生成图片，展示在功能1的肖像中
##### 功能5：晚餐餐厅推荐（页面右下）
- 根据Jade的饮食偏好、当天、浏览器获取的当前位置的天气和Jade的星座分析，推荐5家晚餐的餐厅
- 默认列表显示
- 也可地图展示