ftdl/docs/plans/2026-03-05-download-page-readability.md

Download Page 可读性优化 实现计划

For Claude: REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.

Goal: 提高 download page 的可读性：修复 SearchForm 文字颜色、在 commit id 列显示环境标签

Architecture: 直接修改现有组件，为表单控件添加文字颜色类，为 ApkTable 添加环境标签显示

Tech Stack: Next.js, React, Tailwind CSS, TypeScript

---

Task 1: 修复 SearchForm 文字颜色

Files:

• Modify: app/download/SearchForm.tsx:61,86,112

Step 1: 为项目下拉框添加文字颜色

修改 app/download/SearchForm.tsx 第 61 行，为项目 select 添加 text-gray-900：

className="w-full px-3 py-2 border border-gray-300 rounded-md focus:outline-none focus:ring-2 focus:ring-blue-500 text-gray-900"

Step 2: 为版本下拉框添加文字颜色

修改第 86 行，为版本 select 添加 text-gray-900：

className="w-full px-3 py-2 border border-gray-300 rounded-md focus:outline-none focus:ring-2 focus:ring-blue-500 disabled:bg-gray-100 disabled:cursor-not-allowed text-gray-900"

Step 3: 为 Commit ID 输入框添加文字颜色

修改第 112 行，为 input 添加 text-gray-900：

className="w-full px-3 py-2 border border-gray-300 rounded-md focus:outline-none focus:ring-2 focus:ring-blue-500 text-gray-900"

Step 4: 验证修改

Run: npm run build Expected: Build succeeds without errors

Step 5: 提交

git add app/download/SearchForm.tsx
git commit -m "fix: improve SearchForm text visibility with darker color

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>"

---

Task 2: ApkTable 添加环境标签显示

Files:

• Modify: app/download/ApkTable.tsx

Step 1: 更新 Apk interface 添加 environment 字段

修改 app/download/ApkTable.tsx 的 Apk interface (约第 5-11 行)：

import { formatFileSize, formatDateTime } from '@/lib/utils';
import { type ApkEnvironment } from '@/lib/apk-parser';

interface Apk {
  name: string;
  environment: ApkEnvironment;
  commit: string | null;
  size: number;
  modifiedAt: string;
  downloadUrl: string;
}

Step 2: 添加环境标签渲染辅助函数

在 interface 后、组件前添加：

function getEnvironmentBadgeClass(env: ApkEnvironment): string {
  switch (env) {
    case 'product':
      return 'bg-blue-100 text-blue-800';
    case 'dev':
    case 'sandbox':
      return 'bg-green-100 text-green-800';
    default:
      return 'bg-gray-100 text-gray-800';
  }
}

function formatEnvironment(env: ApkEnvironment): string {
  return env;
}

Step 3: 修改 commit id 列显示环境标签

修改约第 48-52 行的 commit id 单元格：

<td className="px-6 py-4 whitespace-nowrap">
  <div className="flex items-center gap-2">
    <span className="font-mono text-sm text-gray-900">
      {apk.commit || '-'}
    </span>
    <span className={`px-2 py-0.5 text-xs font-medium rounded ${getEnvironmentBadgeClass(apk.environment)}`}>
      {formatEnvironment(apk.environment)}
    </span>
  </div>
</td>

Step 4: 验证修改

Run: npm run build Expected: Build succeeds without errors

Step 5: 提交

git add app/download/ApkTable.tsx
git commit -m "feat: add environment badge to commit id column in ApkTable

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>"

---

Task 3: 验证 ApkList 传递 environment

Files:

• Verify: app/download/ApkList.tsx

Step 1: 检查 ApkList 是否已正确传递 environment

查看 app/download/ApkList.tsx：

• Apk interface 已包含 environment: ApkEnvironment (第 12 行)
• ApkList 传给 ApkTable 的 apks 来自 groupedApks[activeTab] (第 101 行)
• 这些 apks 已包含 environment 字段

结论: 无需修改，environment 已正确传递。

Step 2: 最终验证

Run: npm run build && npm test Expected: Build succeeds, all tests pass

Step 3: 最终提交（如有未提交的更改）

git status
# If clean, no action needed

---

验收标准

1. SearchForm 中选择项目/版本后，文字清晰可见（深灰色）
2. ApkTable 的 commit id 列显示环境标签，如 abc1234 [product]
3. 不同环境有不同颜色：product=蓝色, dev/sandbox=绿色, other=灰色
4. npm run build 成功
5. npm test 全部通过