docs: T40 UI 审计报告 + wiki 更新 + Docker 配置

- T40 UI 审计计划和结果文档（docs/qa/） - wiki 更新：miniprogram 设计系统合规审计记录 + index 关键数字更新 - 审计 V2 完整报告（docs/audits/v2/） - 讨论记录文档（docs/discussions/） - 设计规格和实施计划（docs/superpowers/） - 角色测试计划和结果（docs/qa/role-test-*） - Docker 生产部署配置
2026-05-13 23:29:42 +08:00
parent 212c08b7ae
commit df1d85bfde
78 changed files with 10345 additions and 39 deletions
--- a/wiki/architecture.md
+++ b/wiki/architecture.md
@@ -1,6 +1,6 @@
 ---
 title: 架构决策记录
-updated: 2026-04-28
+updated: 2026-05-07
 status: stable
 tags: [architecture, decisions, design-principles]
 ---
@@ -22,8 +22,8 @@ HMS 继承 ERP 底座的所有基础模块，`erp-health` 作为原生 Rust 模
 ```
 HMS 平台
 ├── 基础模块（继承 ERP）: auth, config, workflow, message, plugin
-├── 核心业务模块: erp-health（原生 Rust，46 实体/39 权限/25+ 页面）★ 已实现
-├── AI 模块: erp-ai（6 实体，SSE 流式分析，Phase 1 MVP）
+├── 核心业务模块: erp-health（原生 Rust，46 实体/39 权限/179 文件/31 事件）★ 已实现
+├── AI 模块: erp-ai（6 实体/45 文件/22 路由，SSE 流式分析，4 AI Provider，Phase 1 MVP）
 ├── 透析模块: erp-dialysis（已拆分为独立 crate）
 └── 可选插件: crm, inventory, freelance, itops, assessment（WASM）
 ```
--- a/wiki/frontend.md
+++ b/wiki/frontend.md
@@ -1,6 +1,6 @@
 ---
 title: Web 前端
-updated: 2026-04-28
+updated: 2026-05-10
 status: stable
 tags: [frontend, react, antd, vite, spa]
 ---
@@ -12,7 +12,7 @@ tags: [frontend, react, antd, vite, spa]
 ## 1. 设计决策

 - **组件库优先** — Ant Design 6，不自造轮子
- **状态集中** — Zustand 管理全局状态（5 个 store）
+- **状态集中** — Zustand 管理全局状态（6 个 store）
 - **API 层分离** — HTTP 调用封装到 `src/api/`（含 health/ 和 ai/ 子目录），组件不直接 fetch
 - **代理开发** — Vite 代理 `/api` 到后端 3000 端口
 - **HashRouter** — 不需要服务端 fallback 配置，部署更稳健
@@ -132,7 +132,7 @@ React 19.2.4 / Ant Design 6.3.5 / React Router 7.14.0 / Zustand 5.0.12 / Vite 8.
 | `/plugins/:pluginId/:entityName` | 插件 CRUD（动态生成） |
 | `/plugins/:pluginId/tabs|tree|graph|dashboard|kanban/:name` | 插件多视图页面 |

-**健康管理路由（22 条）**:
+**健康管理路由（25 条）**:

 | 路径 | 页面 |
 |------|------|
@@ -158,8 +158,10 @@ React 19.2.4 / Ant Design 6.3.5 / React Router 7.14.0 / Zustand 5.0.12 / Vite 8.
 | `/health/ai-analysis` | AI 分析历史 |
 | `/health/ai-prompts` | AI Prompt 管理 |
 | `/health/ai-usage` | AI 用量统计 |
+| `/health/media-library` | 媒体库管理（上传/文件夹/网格浏览） |
+| `/health/banners` | 轮播图管理（表格+Drawer 表单+排序） |

-### 健康模块共享组件（11 个）
+### 健康模块共享组件（13 个）

 | 组件 | 用途 |
 |------|------|
@@ -174,6 +176,8 @@ React 19.2.4 / Ant Design 6.3.5 / React Router 7.14.0 / Zustand 5.0.12 / Vite 8.
 | `HealthRecordsTab` | 患者详情-健康档案标签页 |
 | `FollowUpTab` | 患者详情-随访标签页 |
 | `ImagePreview` | 图片预览组件 |
+| `MediaPicker` | 媒体库选图组件（复用于轮播图选图、文章封面选图） |
+| `resolveMediaUrl()` | 媒体 URL 工具函数（`src/utils/media.ts`）：自动处理路径前缀 + JWT token 拼接 |

 ### 集成契约

@@ -196,7 +200,7 @@ React 19.2.4 / Ant Design 6.3.5 / React Router 7.14.0 / Zustand 5.0.12 / Vite 8.
 | `message.ts` | unreadCount, recentMessages, SSE 实时推送连接, 请求去重 |
 | `plugin.ts` | plugins 列表, 动态菜单, schema 缓存, 请求去重 |

-### 健康模块 API 文件（10 个）
+### 健康模块 API 文件（12 个）

 | 文件 | 覆盖端点 |
 |------|---------|
@@ -207,6 +211,8 @@ React 19.2.4 / Ant Design 6.3.5 / React Router 7.14.0 / Zustand 5.0.12 / Vite 8.
 | `followUp.ts` | 随访任务 + 记录 |
 | `consultations.ts` | 咨询会话 + 消息 + 导出 |
 | `articles.ts` | 健康文章 |
+| `media.ts` | 媒体库 CRUD + 文件夹管理 + 批量操作 |
+| `banners.ts` | 轮播图 CRUD + 排序 |
 | `points.ts` | 积分系统 |
 | `deviceReadings.ts` | 设备数据采集 |
 | `alerts.ts` | 健康预警 |
@@ -250,8 +256,9 @@ React 19.2.4 / Ant Design 6.3.5 / React Router 7.14.0 / Zustand 5.0.12 / Vite 8.
 ### 代理配置

 ```
-http://localhost:5174/api/* → http://localhost:3000/*  (API)
-ws://localhost:5174/ws/*   → ws://localhost:3000/*    (WebSocket)
+http://localhost:5174/api/*      → http://localhost:3000/*  (API)
+http://localhost:5174/uploads/*  → http://localhost:3000/*  (媒体文件，需 JWT)
+ws://localhost:5174/ws/*         → ws://localhost:3000/*    (WebSocket)
 ```

 ## 5. 活跃问题 + 陷阱
@@ -271,6 +278,7 @@ ws://localhost:5174/ws/*   → ws://localhost:3000/*    (WebSocket)

 | 日期 | 变更 |
 |------|------|
+| 2026-05-10 | **媒体库 + 轮播图管理**：新增 MediaLibrary 页面（上传/文件夹/网格浏览）、BannerManage 页面（表格+Drawer+排序）、MediaPicker 组件（复用于轮播图和文章封面选图）；新增 `resolveMediaUrl()` 工具函数统一处理媒体 URL；Vite 代理新增 `/uploads`；健康路由 22→25 条，共享组件 11→13 个，API 文件 10→12 个 |
 | 2026-05-01 | 审计发现更新：CRITICAL 权限码拼写错误（alert→alerts）、前端测试极低、AI SSE 无入口 |
 | 2026-04-28 | UI/UX 重构 Phase 5（小程序端 8 项优化）：首页健康资讯+空状态引导、Hub sparkline bar+打卡合并、日常监测 3 分组折叠+异常高亮、预约时段灰显、咨询消息日期分组+图片预览、医护异常横幅+搜索、趋势图骨架屏 |
 | 2026-04-28 | UI/UX 重构 Phase 4：4 个表单 Modal→DrawerForm（患者 4 分组/预约 3 分组+排班校验/随访 2 分组/积分商品 2 分组） |
--- a/wiki/index.md
+++ b/wiki/index.md
@@ -4,7 +4,7 @@

 ## 关键数字

-> 最后更新: 2026-05-11 | 数据截止: commit c716cc0 (feat/media-library-banner 分支)
+> 最后更新: 2026-05-13 | 数据截止: feat/media-library-banner 分支

 | 指标 | 值 |
 |------|-----|
@@ -31,8 +31,9 @@
 | 系统分析评分 | **6.9/10 (B)**（六维度全面均衡分析，2026-05-11） |
 | 审计状态 | V1: 83% → V2: 85%，P0 安全修复已完成，V2 CRITICAL 全清零 |
 | 角色测试 | R01-R05 全角色验证完成，86.5% 通过率，5 个 BUG 已修复；小程序 MP 多角色 96.2% 通过率 |
-| Design Token | 10 级字号 + 4 结构 token，68 SCSS 文件全面接入，关怀模式 CSS 变量级联自动生效 |
+| Design Token | 11 级字号（含 `--tk-font-display`）+ 4 结构 token，68 SCSS 文件全面接入，关怀模式 CSS 变量级联自动生效 |
 | 长者模式 | 58/58 页面 100% 覆盖 |
+| UI 合规审计 | T40: 60 页面全覆盖（PASS 31 / PASS_WITH_ISSUES 27 / NEEDS_WORK 2），HIGH×2 + MEDIUM×6 + LOW×67 全部修复 |
 | 项目阶段 | **功能完善**（媒体库+轮播图+文章编辑器上线，6 模块冻结待解冻） |

 ## 症状导航
--- a/wiki/miniprogram.md
+++ b/wiki/miniprogram.md
@@ -1,6 +1,6 @@
 ---
 title: 微信小程序（患者端）
-updated: 2026-05-08
+updated: 2026-05-10
 status: active
 tags: [miniprogram, taro, wechat, patient]
 ---
@@ -308,6 +308,10 @@ POST /auth/wechat/login { code }
 | 调用 → | [[erp-server]] | `POST /auth/wechat/bind-phone` | 手机号绑定 |
 | 调用 → | [[erp-health]] | `/api/v1/health/*` | 健康数据查询 |
 | 调用 → | [[erp-server]] | `/api/v1/auth/refresh` | Token 刷新 |
+| 调用 → | [[erp-health]] | `GET /public/banners` | 访客首页轮播图（无需认证） |
+| 调用 → | [[erp-health]] | `GET /public/banner-image/{id}` | 轮播图图片下载（`wx.downloadFile`，无需认证） |
+| 调用 → | [[erp-health]] | `GET /public/articles` | 访客首页文章列表（无需认证） |
+| 调用 → | [[erp-health]] | `GET /public/articles/{id}` | 访客文章详情（无需认证） |

 ## 3. 代码逻辑

@@ -320,6 +324,7 @@ defineConstants: {
  'process.env.NODE_ENV': JSON.stringify(process.env.NODE_ENV || 'development'),
  'process.env.TARO_APP_API_URL': JSON.stringify(process.env.TARO_APP_API_URL || 'http://localhost:3000/api/v1'),
  'process.env.TARO_APP_ENCRYPTION_KEY': JSON.stringify(process.env.TARO_APP_ENCRYPTION_KEY || ''),
+  'process.env.TARO_APP_DEFAULT_TENANT_ID': JSON.stringify(process.env.TARO_APP_DEFAULT_TENANT_ID || ''),
 },
 ```

@@ -444,6 +449,7 @@ secret = "<通过环境变量 ERP__WECHAT__SECRET 设置>"
   ```bash
   cd apps/miniprogram
   echo 'TARO_APP_API_URL=http://localhost:3000/api/v1
+TARO_APP_DEFAULT_TENANT_ID=019d80da-7a2c-7820-b0a3-3d5266a3a324
 TARO_APP_ENCRYPTION_KEY=' > .env
   NODE_ENV=development npx taro build --type weapp
   ```
@@ -591,6 +597,37 @@ curl -X POST http://localhost:3000/api/v1/auth/login \
 | **require() 在 evaluate 不可用** | webpack 用数字 ID 注册模块 | 直接用 `wx.setStorageSync` / `wx.getStorageSync` |
 | **auth 重定向** | request interceptor 检测 401 后跳转 login 并清空 storage | 确保 token 有效，reLaunch 后等待 2-3 秒 |
 | **生产构建 decrypt 抛异常** | 空密钥 + `NODE_ENV=production` 时 `decrypt()` 直接 throw | 使用 `NODE_ENV=development` 构建 |
+| **DevTools 频繁卡死** | Electron 多进程累积文件描述符泄漏，14+ 进程 3.5GB+ 内存 | 见下方 §6.9 DevTools 性能优化 |
+
+### 6.9 DevTools 性能优化
+
+微信开发者工具基于 Electron，多进程架构（主进程 + 渲染进程 + GPU + 插件）在长时间运行后会出现 `EMFILE: too many open files` 导致卡死。
+
+**常见触发场景：**
+- 频繁 MCP 调用（evaluate/reLaunch）导致 fd 累积
+- Taro 热重载文件监视器与 DevTools 自带监视器重叠
+- 长时间（>2 小时）不重启 DevTools
+
+**优化措施：**
+
+```powershell
+# 1. 定期清理 DevTools 进程（推荐每 30 分钟或卡顿时执行）
+taskkill /F /IM wechatdevtools.exe
+# 然后重新打开项目
+
+# 2. 检查进程资源占用
+Get-Process wechatdevtools | Measure-Object WorkingSet64 -Sum | Select Count, @{N='MB';E={[math]::Round($_.Sum/1MB)}}
+# 正常：< 1500MB | 需要重启：> 3000MB
+
+# 3. 关闭不必要的 DevTools 功能
+# 设置 → 编辑器设置 → 取消勾选「文件保存时自动编译」
+# 设置 → 代理 → 关闭（不用代理时）
+```
+
+**MCP 联调最佳实践：**
+- 每轮 MCP 测试结束后 `disconnect` 断开连接
+- 批量测试分批执行，每批 ≤ 10 页后重启 DevTools
+- 避免在 DevTools 编辑器中同时打开多个文件

 ### 6.7 MCP 服务器架构

@@ -655,6 +692,40 @@ node scripts/audit-pages.mjs --role doctor --batch-size 8

 ### 6.9 审计结果

+#### 2026-05-13 T40 UI 设计系统合规审计（60 页面）
+
+基于 `docs/qa/T40-miniprogram-ui-audit-plan.md` 对全部 60 个页面进行设计系统合规审计，覆盖 Design Token、SCSS 变量、色彩/圆角/字号/组件规范。
+
+**审计结果汇总：**
+
+| 级别 | 页面数 | 占比 |
+|------|--------|------|
+| PASS | 31 | 52% |
+| PASS_WITH_ISSUES | 27 | 45% |
+| NEEDS_WORK | 2 | 3% |
+
+**发现并修复的问题（全部已修复）：**
+
+| 类别 | 数量 | 修复内容 |
+|------|------|----------|
+| HIGH | 2 | 趋势页缺 Loading/EmptyState；文章列表缺 mixins 导入 |
+| MEDIUM | 6 | 硬编码字号(72px→`--tk-font-display`)；ErrorState 图标字号；AI报告离调色板颜色(#7c3aed/#f0e6ff→`$pri`/`$pri-l`)；医生患者列表 inline style；咨询页 GuestGuard 统一；3处 TSX inline 颜色提取为 SCSS 类 |
+| LOW — `#fff` 统一 | 44 | 新增 `$white` 变量，所有 `color: #fff` → `$white`，`background: #fff` → `$card` |
+| LOW — 圆角统一 | 14 | `8px` → `$r-xs`（7文件）；`20px` → `$r-lg`（2文件）；`16px` → `$r`（1文件） |
+| LOW — 静默 catch | 2 | article/health 的空 catch 块添加状态清理 |
+| LOW — ErrorBoundary 重构 | 1 | 6 个 inline style 硬编码提取为 SCSS 类 + Design Token |
+| LOW — 离调色板颜色 | 2 | `#0284C7`(冷蓝) → `$tx2`；`#94A3B8`(冷灰) → `$tx3` |
+| LOW — `#FFFFFF` 统一 | 4 | index/exchange/mixins/variables 中 `#FFFFFF` → `$white` |
+
+**设计系统新增：**
+- `variables.scss`: 新增 `$white: #FFFFFF` 语义变量
+- `tokens.scss`: 新增 `--tk-font-display` Token（72px/80px，大数字装饰用）
+- `ErrorBoundary`: 新增 SCSS 文件，从 inline style 迁移到设计系统
+
+**影响文件：** 25 个 SCSS + 10 个 TSX + 1 个新增 SCSS + 2 个样式系统文件
+
+报告文件：`docs/qa/role-test-results/T40-ui-audit-results.md`
+
 #### 2026-05-08 多角色自动化审计（59 页面 × 4 角色）

 使用分批审计脚本对全部 59 个页面进行 4 角色全面审计（236 次页面探测）：
@@ -692,7 +763,9 @@ node scripts/audit-pages.mjs --role doctor --batch-size 8

 | 日期 | 变更 |
 |------|------|
-| 2026-05-09 | **Design Token 全面接入**：68 SCSS 文件（59 页面 + 9 组件）全面迁移 `font-size: Npx` → `var(--tk-*)`；重写 `tokens.scss` 校准 10 级字号 + 4 结构 token 匹配实际设计值；更新 `mixins.scss` 4 个 mixin 引用 token；清理 12 个页面的本地 mixin 重复定义；`elder-mode.scss` 从 530 行缩减至 ~120 行（删除所有字号/颜色覆写，仅保留结构布局）；634 token 引用 / 3 个特殊硬编码；新增 §1.1 Design Token 系统文档 |
+| 2026-05-13 | **T40 UI 设计系统合规审计+修复**：60 页面全覆盖审计（PASS 31 / PASS_WITH_ISSUES 27 / NEEDS_WORK 2）；修复 HIGH×2 + MEDIUM×6 + LOW×67；新增 `$white` 变量 + `--tk-font-display` Token；44 处 `#fff` 统一为 `$white`；14 处圆角硬编码统一为变量；3 处 TSX inline 颜色提取为 SCSS 类；ErrorBoundary 重构为 SCSS；2 处静默 catch 修复；2 处离调色板颜色修正 |
+| 2026-05-10 | **访客首页改造**：轮播图接入 `/public/banners` API + `wx.downloadFile` 下载图片到本地临时路径；文章列表接入 `/public/articles` API；文章详情页根据登录状态选择认证/公开 API（`getPublicArticleDetail`）；`.env` 新增 `TARO_APP_DEFAULT_TENANT_ID`；集成契约新增 4 个公开端点 |
+| 2026-05-09 | **Design Token 全面接入**：68 SCSS 文件全面迁移 `font-size: Npx` → `var(--tk-*)`；634 token 引用 / 3 个特殊硬编码；新增 §1.1 Design Token 系统文档 |
 | 2026-05-08 | **多角色自动化审计**：4 角色（admin/doctor/nurse/operator）× 59 页面 = 236 次探测，综合通过率 96.2%；更新 §2 页面结构为 59 页面完整列表（含医生端 dialysis/prescription/action-inbox + 患者端 dialysis-records/prescriptions/consents/health-records/diagnoses）；更新 §5 审计发现（透析/知情同意/诊断/健康记录标记为已修复）；更新 §6.5 TabBar 为 3 个；新增 §6.8 分批审计脚本；更新 §6.9 多角色审计结果 |
 | 2026-05-08 | **MCP 联调全面重写**：自建 MCP 服务器 `@hms/weapp-mcp` 替代 `@yfme/weapp-dev-mcp`；基于 `@weapp-vite/miniprogram-automator@1.1.0`；新增 §6.2 启动步骤（登录+单实例铁律）；更新工具列表为 weapp-local 25 个工具；新增 inject_auth 一键注入；新增 §6.7 MCP 服务器架构说明；多实例冲突、CLI 登录、SummerCompiler 等已知限制 |
 | 2026-05-01 | 审计发现更新：CRITICAL 晚间血压丢失 / HIGH 透析+知情同意完全空白 / 功能域完成度矩阵 |