init

docs/superpowers/plans/2026-06-13-yuyueguahao-v2-evolution.md

@@ -0,0 +1,165 @@
+# 苏州肛泰中医院 · v2 平台化升级实施计划
+
+> **For agentic workers:** 按 Phase 顺序执行，每个 Phase 都是可独立交付的 milestone，用户可在任意 Phase 完成后暂停/调整方向。
+> **执行策略**：Phase 内逐步交付，每个 bite-sized 任务完成后等待用户确认再继续。
+
+**Goal**：把当前"医院小程序 + 后端 + 管理后台"从"能跑"升级到"企业级可维护"，覆盖 4 大需求：API 标准化、视觉重塑、问卷增强、模块化重构。
+
+**Architecture**：
+- 后端：Express + MySQL，新增 Swagger/OpenAPI 自动文档 + Markdown 接口规范 + `/api/leads` 新表 + 业务域 service 拆分
+- 前端：Taro 4 + React 18 + TS 5，新增 `modules/lead` 业务域模块 + 全局 design tokens 重塑（低饱和度专业色系）
+- 管理后台：原生 SPA 风格不变，新增 leads 客户列表 + 接口版本号展示
+
+**Tech Stack**：
+- 后端：Express 4 / mysql2 / dayjs / **新增** swagger-ui-express + swagger-jsdoc + apidoc
+- 前端：Taro 4.1 / React 18 / TypeScript 5 / Sass / Zustand / **新增** modules/lead 域
+- 数据库：MariaDB 10.x，新增 `leads` 表
+
+---
+
+## Phase 总览
+
+| Phase | 主题 | 涉及文件数 | 估时 | 依赖 |
+|---|---|---|---|---|
+| **P1** | 业务域 service 拆分（模块化基础） | 14 改 + 6 新增 | 1.5h | 无 |
+| **P2** | Swagger + Markdown 接口文档 | 4 改 + 3 新增 | 1h | P1 |
+| **P3** | 问卷 / 自主测试 + 用户信息采集 + leads 表 | 1 改 + 2 新增 | 1.5h | P1, P2 |
+| **P4** | 全局设计 tokens 重塑 + 主流程 6 页视觉升级 | 1 改 + 6 改 | 1.5h | P1 |
+| **P5** | 接口版本控制 / 同步机制 | 2 改 + 1 新增 | 0.5h | P2 |
+
+**总估时**：~6h（4 个 milestone 验收点，可分多次完成）
+
+---
+
+## Phase 1：业务域 service 拆分（高内聚低耦合）
+
+**目标**：把 `server/src/routes/*` 按业务域重组，添加 README，建立模块化骨架。
+
+### 任务清单
+
+- [ ] **Task 1.1** 新建 `server/src/modules/hospital/` 目录，迁移 `routes/hospital.js` → `modules/hospital/route.js` + 新增 `modules/hospital/service.js`（查询逻辑）+ `modules/hospital/README.md`
+- [ ] **Task 1.2** 同样模式处理 `department` / `doctor` / `appointment` / `expert` / `banner` / `config` 6 个域
+- [ ] **Task 1.3** 新建 `server/src/modules/index.js` 统一注册 router
+- [ ] **Task 1.4** 修改 `server/src/index.js`：把 `app.use('/api/...', router)` 改为 `app.use('/api/v1/...', router)`（**v1 是版本号起点**）
+- [ ] **Task 1.5** 写 `server/src/modules/README.md`：描述每个模块的 `route.js`（HTTP 层）/`service.js`（业务逻辑）/`dto.js`（数据转换）`README.md`（接口说明）规范
+- [ ] **Task 1.6** 验证：PM2 重启后 `curl /api/v1/hospitals` 仍返回 `code:0, data:[...]`
+
+**验收标准**：
+- 每个业务域目录包含 route/service/dto/README 四件套
+- 服务启动日志接口列表全部以 `/api/v1` 开头
+- 前端 services/*.ts 调用的 URL 由 `/api/...` 改为 `/api/v1/...`（同时**前端 BASE_URL 配置新增版本号**）
+- 数据库交互全部经过 service.js，route.js 不再直接写 SQL
+
+---
+
+## Phase 2：Swagger UI + Markdown 接口文档
+
+**目标**：自动生成 OpenAPI 3.0 规范 + Markdown 业务说明，浏览器可访问 `/api/docs`。
+
+### 任务清单
+
+- [ ] **Task 2.1** 安装依赖：`cd server && npm i swagger-ui-express swagger-jsdoc`
+- [ ] **Task 2.2** 新建 `server/src/swagger/spec.js`：配置 swagger-jsdoc，扫描 `modules/*/route.js` 的 JSDoc 注释，生成 OpenAPI 3.0 spec
+- [ ] **Task 2.3** 在 `server/src/index.js` 注册 `app.use('/api/docs', swaggerUi.serve, swaggerUi.setup(spec))` + `app.get('/api/docs.json', ...)` 输出原始 spec
+- [ ] **Task 2.4** 给 7 个 module 的 route.js 关键接口加 JSDoc：`@swagger` 路径，包含 path/method/parameters/responses
+- [ ] **Task 2.5** 新建 `docs/api/README.md`：API 总览（基地址、版本、认证、错误码约定）
+- [ ] **Task 2.6** 新建 `docs/api/v1/hospital.md`、`department.md`、`doctor.md`、`appointment.md`、`expert.md`、`banner.md`、`config.md`、`admin-auth.md`、`lead.md`（lead 是 P3 的）
+- [ ] **Task 2.7** 新建 `docs/api/CHANGELOG.md`：版本变更记录
+
+**验收标准**：
+- 浏览器访问 `http://124.221.67.199:3000/api/docs/` 显示完整 API 文档
+- 8 个 markdown 文档，每个包含：接口路径 / 方法 / 请求参数表 / 响应示例 / 错误码 / 业务说明
+- CHANGELOG 记录 v1.0.0 → v1.1.0 的接口变更
+
+---
+
+## Phase 3：自主问卷用户信息采集 + leads 表
+
+**目标**：问卷底部新增姓名/手机号/症状采集区，前后端校验，提交到 `/api/v1/leads`。
+
+### 任务清单
+
+- [ ] **Task 3.1** 数据库：在 `server/src/schema.sql` 末尾追加 `CREATE TABLE leads (...)`：id / name / phone / symptom / questionnaire JSON / source / created_at，加唯一索引 `(phone, source)`
+- [ ] **Task 3.2** 后端：新建 `server/src/modules/lead/route.js`（POST 提交 / GET 列表 / GET 详情）
+- [ ] **Task 3.3** 后端：新建 `server/src/modules/lead/service.js`：手机号正则、问卷 JSON 解析、source 枚举校验
+- [ ] **Task 3.4** 后端：新建 `server/src/modules/lead/dto.js` + `README.md`
+- [ ] **Task 3.5** 前端：新建 `src/modules/lead/types.ts`（Lead / LeadForm TS 类型）
+- [ ] **Task 3.6** 前端：新建 `src/modules/lead/api.ts`（submitLead / fetchLeads）
+- [ ] **Task 3.7** 前端：修改 `src/pages/self-test/index.tsx`：底部加 `<View className={styles.userInfoSection}>`，包含姓名 Input / 手机 Input / 症状 Textarea，"提交问卷结果"按钮
+- [ ] **Task 3.8** 前端：表单校验（姓名 1-20 字符 / 手机 `^1[3-9]\d{9}$` / 症状 ≤500 字 / 必填），错误内联展示
+- [ ] **Task 3.9** 前端：成功后调 `submitLead`，后端返回 leadId，跳 `/pages/success/index?type=lead&id=...`
+- [ ] **Task 3.10** 管理后台：在 `admin/index.html` 加 `/admin/leads` 标签页，列表展示姓名/手机/来源/时间/问卷结果 JSON 折叠
+- [ ] **Task 3.11** 后端：新增 `GET /api/v1/admin/leads`（authRequired）给管理后台用
+
+**验收标准**：
+- `curl -X POST /api/v1/leads -d '{"name":"...","phone":"...","questionnaire":{...}}'` 返回 200 + leadId
+- 手机号不合法 → 后端 400 `{code:400, message:"手机号格式不正确"}`
+- 数据库 `SELECT * FROM leads` 看到刚提交的行
+- 小程序端提交 → 管理后台 `/admin/leads` 立即看到
+
+---
+
+## Phase 4：设计 tokens 重塑 + 主流程 6 页视觉升级
+
+**目标**：低饱和度专业色系（去掉原 #1f7ae0 高饱蓝），升级 6 个主流程页视觉。
+
+### 任务清单
+
+- [ ] **Task 4.1** 重构 `src/styles/theme.scss`：主色改为 `#0f766e`（低饱和度医绿）或 `#475569`（深石板蓝），辅色 `border-radius` 提升到 12-16rpx，阴影由硬阴影改为柔阴影 `0 2px 8px rgba(15,23,42,.04) → 0 1px 3px rgba(15,23,42,.06), 0 4px 16px rgba(15,23,42,.04)`
+- [ ] **Task 4.2** 重构 `src/styles/variables.scss`：间距 8pt 网格（`$spacing-1: 4rpx; $spacing-2: 8rpx; ...`），字号阶梯
+- [ ] **Task 4.3** 新建 `src/styles/mixins.scss`：`@mixin card` / `@mixin btn-primary` / `@mixin section-title`，统一卡片/按钮/章节头样式
+- [ ] **Task 4.4** 首页：使用 mixins 重写 `home/index.module.scss`，增大 Hero 留白，专家头像由 64rpx → 80rpx
+- [ ] **Task 4.5** 医院页：科室网格由 4 列 → 3 列，卡片高度 220rpx → 240rpx，加 hover 状态
+- [ ] **Task 4.6** 预约页：表单分组由密集 → 留白充足，提交按钮加 24rpx 圆角
+- [ ] **Task 4.7** 问卷页：题目卡片加大内边距，选项 hover 加 border 高亮
+- [ ] **Task 4.8** 成功页：成功图标由 emoji → SVG，结果列表用左侧色条
+- [ ] **Task 4.9** 我的页：菜单项由 2 列 → 1 列 + 右侧箭头，更接近企业级
+- [ ] **Task 4.10** 全站 6 个页面 `pages.config.json` 标题统一"苏州肛泰中医院 - X"
+
+**验收标准**：
+- 全站色系用 `<kbd>ColorPick</kbd>` 取色，所有页面主色都从 tokens 派生（无硬编码颜色）
+- 阴影统一两层：近阴影（按钮/输入框） + 远阴影（卡片/弹层）
+- 6 个页面对比之前截图，整体更"沉稳专业"（非"活泼可爱"）
+
+---
+
+## Phase 5：接口版本控制与同步机制
+
+**目标**：建立 `/api/v1` 之后到 `/api/v2` 的兼容/弃用/移除规范。
+
+### 任务清单
+
+- [ ] **Task 5.1** 后端：新增 `server/src/middleware/apiVersion.js`：响应头加 `X-API-Version: v1` 和 `Sunset` 头（如果 deprecated）
+- [ ] **Task 5.2** 后端：新增 `server/src/middleware/changelogBroadcast.js`：每次启动时把当前版本号 + CHANGELOG.md 摘要写入 `server_runtime.log`
+- [ ] **Task 5.3** 前端：新增 `src/services/apiVersion.ts`：请求时带 `X-Client-Version` 头，响应时检查 `Sunset` 头并 toast 提示
+- [ ] **Task 5.4** 新建 `docs/api/SYNC.md`：描述后端接口变更 → 前端同步流程
+  1. 后端开发改 route.js + swagger JSDoc
+  2. `npm run docs:gen` 自动更新 markdown
+  3. 在 `docs/api/CHANGELOG.md` 加一行
+  4. 前端 `pnpm sync-api` 拉取 `/api/docs.json` 生成 `types/api/*.d.ts`
+  5. 前端 IDE 报类型错误 → 定位 + 修改
+- [ ] **Task 5.5** 新建 `docs/superpowers/plans/2026-06-13-api-sync-workflow.md`：详细描述开发者日常流程
+
+**验收标准**：
+- `curl -I /api/v1/hospitals` 响应头包含 `X-API-Version: v1`
+- 前端 `apiVersion.ts` 在收到 Sunset 头时 `Taro.showToast({ title: '接口即将停用，请更新 APP', icon: 'none' })`
+- docs/api/SYNC.md 描述的工作流可被新开发者 5 分钟内理解
+
+---
+
+## 风险与回滚
+
+| 风险 | 缓解 |
+|---|---|
+| Phase 4 视觉改坏既有页面 | 保留 theme 旧版 v1 注释，可在 1 行切换 |
+| Phase 1 改 URL 前缀 `/api/v1` 影响前端联调 | 同步修改 `src/services/request.ts` 的 BASE_URL 拼接逻辑 |
+| Phase 3 leads 表字段缺索引 | `(phone, source)` 加唯一索引 + `created_at` 加普通索引 |
+| Phase 5 Sunset 头跨域被浏览器剥 | Nginx/proxy 不应剥自定义响应头，标注到部署文档 |
+
+## 验收里程碑（用户暂停点）
+
+- **M1**：Phase 1 完成后，前端 `pnpm dev` + 后端 `npm start` 全栈联通，业务不变
+- **M2**：Phase 2 完成后，`/api/docs` 可访问，8 个 markdown 文档齐全
+- **M3**：Phase 3 完成后，问卷可提交 + 管理后台可见
+- **M4**：Phase 4 完成后，6 页视觉一致、设计 tokens 单点控制
+- **M5**：Phase 5 完成后，接口版本与同步流程文档化

docs/superpowers/plans/2026-06-14-phase4-design-refresh.md

@@ -0,0 +1,154 @@
+# Phase 4 · 设计 tokens 重塑 + 主流程 6 页视觉升级
+
+## 范围
+
+- 6 个核心页面: home / hospital / appointment / phone-consult / self-test / success
+- 目标: 整洁美观、提升品质感
+- 手段: 设计 token 优化 + 6 页视觉重构
+
+## 设计 Thesis(一句话)
+
+> 用 **医疗级克制美学** + **人文摄影** + **精准排版层级**,告别卡片堆叠,改为分栏 + divider + 全宽背景区,让用户在一屏内完成 "我该做什么" 的判断。
+
+## Visual Thesis
+
+- **氛围**: 医疗专业 × 苏州江南温润(降低饱和、加微暖)
+- **材质**: 大面积白 + 极浅米灰背景(#fafbfc),用品牌蓝绿做局部强调
+- **能量**: 安静、稳定、可信赖——> 留白 + 排版权重做主节奏
+
+## Content Plan(6 页)
+
+| # | 页面 | 主任务 | 主导视觉 |
+|---|---|---|---|
+| 1 | home 首页 | 引导用户进入预约/咨询/自测 | 真实医院外景 hero + 3 个分栏入口 + 科室速选 |
+| 2 | hospital 医院详情 | 了解医院+选科室 | 医院环境图 + 实力数据 + 科室列表(无卡片) |
+| 3 | appointment 预约 | 提交预约信息 | 单一表单焦点 + 步骤条 |
+| 4 | phone-consult 电话咨询 | 选专家并拨号 | 专家横向滚动(行) + 拨号区 |
+| 5 | self-test 自测 | 答题+留资 | 进度条主导 + 题卡 + 底部信息采集 |
+| 6 | success 成功 | 确认+下一步 | 大号 ✓ 符号 + 信息行(无卡) |
+
+## Interaction Thesis(2-3 个核心动效)
+
+1. **入场 fadeInUp**: 首屏内容从下方 16rpx 渐入,延迟 0/80/160ms 形成节奏
+2. **按下反馈**: 按钮 active 状态 `scale(0.97)` + 透明度 0.85(已有 mixin)
+3. **scroll reveal**: ScrollView 内区块在视口出现时 fadeIn(用 IntersectionObserver,小程序内用 onScroll)
+
+## Token 优化清单
+
+### A. 颜色: 收敛与精致
+
+- **主品牌色**: `#1f7ae0` → `#0a6dff`(更精炼的"医蓝"),加 50/100/200/300/500/600/700 完整色阶
+- **辅色**: 青绿 `#15b9a3` 保留,但使用率≤15%
+- **新增"米杏"色系**: `#fafbfc` 背景 / `#f4f1ec` 卡片底 / `#f0e6d6` 强调区(降低冷感、提升温度)
+- **价格色**: `#ff5e3a` → `#e85a3c`(更稳重)
+- 删:`$color-text-disabled` 浅灰改为 `$color-text-tertiary` 的 60% opacity
+
+### B. 排版: 增强层级
+
+- 引入"两套字重"原则: 标题用 $font-weight-bold,正文用 regular,**不混用 medium 太多**
+- 新增 `$letter-spacing-tight: -0.01em`(标题字距)
+- 新增 `$letter-spacing-loose: 0.04em`(小标签字距)
+
+### C. 阴影: 收为 3 级
+
+- 现有 5 级 → 3 级: `$shadow-1` (xs) / `$shadow-2` (md) / `$shadow-3` (lg)
+- 删除 `$shadow-xs`、合并 `$shadow-sm` → 1
+
+### D. 圆角: 收敛
+
+- 主要用 8/12/16,删除 20/24(过圆损失专业感)
+- 按钮仍用全圆角(`$radius-button: 999rpx`)
+
+### E. 间距: 加 `$page-gutter`
+
+- 现有 `$page-spacing: 32rpx` → 改为 `$page-gutter: 24rpx`(更紧凑、更易扫读)
+
+### F. 新增 Z-index 标准化
+
+- 现有 ok,不动
+
+## 6 页视觉重做
+
+### home 首页
+- **删除**: 顶部 banner 条、三个并列卡片式入口、医生推荐卡
+- **改为**:
+  - 全宽 hero: 医院外景图 + 品牌名 + 一句承诺
+  - 3 个入口: divider 分隔的 3 行(不用卡片),左 icon + 标题 + 副文 + 箭头
+  - 科室速选: 横向滚动 chip(去卡片)
+  - 专家推荐: 1 个真实人物照 + 文案段(无卡)
+  - 底部信息采集卡(自测入口): 全宽背景图 + 居中标题 + 1 按钮
+
+### hospital 医院详情
+- **删除**: 顶部图、卡式信息块
+- **改为**:
+  - 医院环境照(全宽,16:9)
+  - 医院简介: 段落式,首字下沉
+  - 实力数据: 4 列数字 + 标签(无卡,divider 隔开)
+  - 科室列表: 折叠面板(可展开),不用卡片
+  - 底部固定: 立即预约 CTA
+
+### appointment 预约
+- **删除**: 多步向导里的"步骤卡"
+- **改为**:
+  - 步骤指示器: 4 个圆点 + 连线
+  - 单一表单焦点: 当前步骤内容居中,信息密度大
+  - 字段: 大输入框(高 96rpx),label 在上方
+  - 提交按钮: 底部固定主色渐变按钮(高 96rpx)
+
+### phone-consult 电话咨询
+- **删除**: 9 宫格、卡片式专家列表
+- **改为**:
+  - 顶部 hero: "24h 健康热线" + 大号电话号(可点击拨号)
+  - 专家列表: 横向滚动,每个专家是一行(头像 + 姓名 + 简介 + 拨号按钮)
+  - 底部说明: 2-3 段文字,无卡
+
+### self-test 自测
+- 已 Phase 3 改造完成,本阶段只做视觉微调
+- 优化: 进度条改用更细的 4rpx,圆角降低
+- 题卡从阴影改为分隔线
+- 用户信息区改为无阴影背景
+
+### success 成功
+- **删除**: 卡片包裹
+- **改为**:
+  - 顶部 1/3 高度: 大号 ✓ 居中(无背景)
+  - 中部信息行: divider 分隔的列表(医院/患者/电话/科室/时间)
+  - 底部双按钮: 圆角胶囊,主次分明
+
+## 实施步骤
+
+1. **Task 4.1**: 重写 [src/styles/theme.scss](file:///Users/skn/Desktop/yuyueguahao/src/styles/theme.scss),新增色阶/排版变量,精简阴影圆角
+2. **Task 4.2**: 同步更新 [src/styles/variables.scss](file:///Users/skn/Desktop/yuyueguahao/src/styles/variables.scss) 转发关系(避免变量重复定义)
+3. **Task 4.3**: home 页重做
+4. **Task 4.4**: hospital 页重做
+5. **Task 4.5**: appointment 页重做
+6. **Task 4.6**: phone-consult 页重做
+7. **Task 4.7**: self-test 页视觉微调
+8. **Task 4.8**: success 页重做
+9. **Task 4.9**: 部署 + 视觉验证(上传 taro dist 或仅改 SCSS)
+
+## 设计原则硬约束
+
+- ✅ 严格 1 个主品牌色 + 1 个辅色
+- ✅ 卡片只在 card-as-interaction 时使用(如自测题卡、日期选择)
+- ✅ 所有 hero 区是全宽,不留左右页边距
+- ✅ 标题用 bold,正文用 regular,不混用 medium 太多
+- ✅ 留白 ≥ 32rpx(区块之间)
+- ✅ 字距: 标题 -0.01em,小标签 0.04em
+
+## 暂缓(避免范围蔓延)
+
+- 不做 Framer Motion 等大型动效库(小程序不友好)
+- 不换字体(用系统字体)
+- 不做国际化
+
+## 风险
+
+- 小程序 SCSS 变量是编译期,改 theme 后需要 `npm run build:weapp`
+- 后端与本次重做无关,只改前端 + theme
+
+## 验收
+
+- 6 页均可 `npm run dev:weapp` 编译通过
+- 在微信开发者工具中,6 页布局正常,无样式丢失
+- 后端 API 调用与 Phase 3 保持一致(无破坏)