butubb/yuyueguahao
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
17a8027b20c771106aa95ad467e6fd5862ffa7cd
yuyueguahao/docs/superpowers/plans/2026-06-13-yuyueguahao-v2-evolution.md
T
butubb 17a8027b20 init
2026-07-05 14:43:34 +08:00

10 KiB
Raw Blame History

苏州肛泰中医院 · 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 完成后，接口版本与同步流程文档化
Reference in New Issue View Git Blame Copy Permalink