tech
1eba2f5f39
- Update .env.example with documentation and default values - Add .resources to gitignore (dummy test files) - Add APK parsing fix implementation plan document Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
533 lines
14 KiB
Markdown
533 lines
14 KiB
Markdown
# APK Parsing Fix Implementation Plan
|
||
|
||
> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
|
||
|
||
**Goal:** Fix APK filename parsing to use version number as delimiter and support configurable environment tabs.
|
||
|
||
**Architecture:** Parse APK filenames by splitting on `_<version>` to extract prefix. If prefix has no underscore → product. If prefix has underscore → extract environment from last segment. Match against configurable tabs (env var), unmatched → other.
|
||
|
||
**Tech Stack:** Next.js, TypeScript, environment variables
|
||
|
||
---
|
||
|
||
### Task 1: Add APK_TABS Environment Variable
|
||
|
||
**Files:**
|
||
- Modify: `lib/constants.ts`
|
||
|
||
**Step 1: Add APK_TABS constant**
|
||
|
||
```typescript
|
||
// Add to lib/constants.ts
|
||
export const APK_TABS = (process.env.APK_TABS || 'dev,sandbox')
|
||
.split(',')
|
||
.map(t => t.trim())
|
||
.filter(Boolean);
|
||
```
|
||
|
||
**Step 2: Verify no build errors**
|
||
|
||
Run: `npm run build`
|
||
Expected: Build succeeds
|
||
|
||
**Step 3: Commit**
|
||
|
||
```bash
|
||
git add lib/constants.ts
|
||
git commit -m "feat: add APK_TABS environment variable for configurable tabs"
|
||
```
|
||
|
||
---
|
||
|
||
### Task 2: Rewrite APK Parser Logic
|
||
|
||
**Files:**
|
||
- Modify: `lib/apk-parser.ts`
|
||
- Modify: `lib/__tests__/apk-parser.test.ts`
|
||
|
||
**Step 1: Write failing tests for new parsing logic**
|
||
|
||
Replace `lib/__tests__/apk-parser.test.ts`:
|
||
|
||
```typescript
|
||
import { parseApkFilename, detectEnvironment, getApkTabs } from '../apk-parser';
|
||
|
||
describe('parseApkFilename', () => {
|
||
it('should parse product APK (no environment)', () => {
|
||
const result = parseApkFilename('ft_0_44_bfeddf2d0.apk', '0_44');
|
||
expect(result.environment).toBe('product');
|
||
expect(result.commit).toBe('bfeddf2d0');
|
||
expect(result.isValid).toBe(true);
|
||
});
|
||
|
||
it('should parse dev APK', () => {
|
||
const result = parseApkFilename('ft_dev_0_44_bfeddf2d0.apk', '0_44');
|
||
expect(result.environment).toBe('dev');
|
||
expect(result.commit).toBe('bfeddf2d0');
|
||
expect(result.isValid).toBe(true);
|
||
});
|
||
|
||
it('should parse sandbox APK', () => {
|
||
const result = parseApkFilename('ft_sandbox_0_44_bfeddf2d0.apk', '0_44');
|
||
expect(result.environment).toBe('sandbox');
|
||
expect(result.commit).toBe('bfeddf2d0');
|
||
expect(result.isValid).toBe(true);
|
||
});
|
||
|
||
it('should map unknown environment to other', () => {
|
||
const result = parseApkFilename('ft_lan_0_44_bfeddf2d0.apk', '0_44');
|
||
expect(result.environment).toBe('other');
|
||
expect(result.commit).toBe('bfeddf2d0');
|
||
});
|
||
|
||
it('should map timeshift to other', () => {
|
||
const result = parseApkFilename('ft_timeshift_0_42_57ef3a60d.apk', '0_42');
|
||
expect(result.environment).toBe('other');
|
||
});
|
||
|
||
it('should handle invalid format without commit', () => {
|
||
const result = parseApkFilename('ft_dev_0_44.apk', '0_44');
|
||
expect(result.environment).toBe('dev');
|
||
expect(result.commit).toBeNull();
|
||
expect(result.isValid).toBe(false);
|
||
});
|
||
|
||
it('should handle completely invalid filename', () => {
|
||
const result = parseApkFilename('invalid_filename.apk', '0_44');
|
||
expect(result.environment).toBe('other');
|
||
expect(result.commit).toBeNull();
|
||
expect(result.isValid).toBe(false);
|
||
});
|
||
});
|
||
|
||
describe('detectEnvironment', () => {
|
||
it('should detect product when no underscore in prefix', () => {
|
||
expect(detectEnvironment('ft', ['dev', 'sandbox'])).toBe('product');
|
||
});
|
||
|
||
it('should detect configured environment', () => {
|
||
expect(detectEnvironment('ft_dev', ['dev', 'sandbox'])).toBe('dev');
|
||
expect(detectEnvironment('ft_sandbox', ['dev', 'sandbox'])).toBe('sandbox');
|
||
});
|
||
|
||
it('should return other for unconfigured environment', () => {
|
||
expect(detectEnvironment('ft_lan', ['dev', 'sandbox'])).toBe('other');
|
||
expect(detectEnvironment('ft_timeshift', ['dev', 'sandbox'])).toBe('other');
|
||
});
|
||
|
||
it('should return other for empty prefix', () => {
|
||
expect(detectEnvironment('', ['dev', 'sandbox'])).toBe('other');
|
||
});
|
||
});
|
||
```
|
||
|
||
**Step 2: Run tests to verify they fail**
|
||
|
||
Run: `npm test -- lib/__tests__/apk-parser.test.ts`
|
||
Expected: Tests fail with missing `getApkTabs` and wrong behavior
|
||
|
||
**Step 3: Implement new parsing logic**
|
||
|
||
Replace `lib/apk-parser.ts`:
|
||
|
||
```typescript
|
||
import { APK_TABS } from './constants';
|
||
|
||
export type ApkEnvironment = 'product' | 'dev' | 'sandbox' | 'other';
|
||
|
||
export interface ParsedApkMetadata {
|
||
environment: ApkEnvironment;
|
||
commit: string | null;
|
||
isValid: boolean;
|
||
}
|
||
|
||
export function getApkTabs(): string[] {
|
||
return APK_TABS;
|
||
}
|
||
|
||
export function detectEnvironment(prefix: string, configuredTabs: string[]): ApkEnvironment {
|
||
// Empty prefix → other
|
||
if (!prefix) {
|
||
return 'other';
|
||
}
|
||
|
||
// No underscore means product (e.g., "ft")
|
||
if (!prefix.includes('_')) {
|
||
return 'product';
|
||
}
|
||
|
||
// Extract environment from last segment after underscore
|
||
const lastUnderscoreIndex = prefix.lastIndexOf('_');
|
||
const env = prefix.substring(lastUnderscoreIndex + 1);
|
||
|
||
// Check if environment is configured
|
||
if (configuredTabs.includes(env)) {
|
||
return env as ApkEnvironment;
|
||
}
|
||
|
||
return 'other';
|
||
}
|
||
|
||
export function parseApkFilename(filename: string, version: string): ParsedApkMetadata {
|
||
// Use version as delimiter (with leading underscore)
|
||
const delimiter = `_${version}`;
|
||
const delimiterIndex = filename.indexOf(delimiter);
|
||
|
||
let prefix: string;
|
||
if (delimiterIndex > 0) {
|
||
prefix = filename.substring(0, delimiterIndex);
|
||
} else {
|
||
// Fallback: can't find version delimiter
|
||
prefix = '';
|
||
}
|
||
|
||
const environment = detectEnvironment(prefix, APK_TABS);
|
||
|
||
// Extract commit ID
|
||
const commitMatch = filename.match(/([a-f0-9]{7,})\.apk$/);
|
||
const commit = commitMatch ? commitMatch[1] : null;
|
||
|
||
return {
|
||
environment,
|
||
commit,
|
||
isValid: commit !== null,
|
||
};
|
||
}
|
||
```
|
||
|
||
**Step 4: Run tests to verify they pass**
|
||
|
||
Run: `npm test -- lib/__tests__/apk-parser.test.ts`
|
||
Expected: All tests pass
|
||
|
||
**Step 5: Commit**
|
||
|
||
```bash
|
||
git add lib/apk-parser.ts lib/__tests__/apk-parser.test.ts
|
||
git commit -m "feat: rewrite APK parser to use version as delimiter"
|
||
```
|
||
|
||
---
|
||
|
||
### Task 3: Update API Route to Pass Version
|
||
|
||
**Files:**
|
||
- Modify: `app/api/apks/route.ts`
|
||
- Modify: `app/api/__tests__/apks.test.ts`
|
||
|
||
**Step 1: Check existing API test**
|
||
|
||
Read: `app/api/__tests__/apks.test.ts`
|
||
|
||
**Step 2: Update API route to pass version**
|
||
|
||
Modify `app/api/apks/route.ts` line 22:
|
||
|
||
```typescript
|
||
// Change from:
|
||
const parsed = parseApkFilename(apk.name);
|
||
// To:
|
||
const parsed = parseApkFilename(apk.name, version);
|
||
```
|
||
|
||
**Step 3: Verify build succeeds**
|
||
|
||
Run: `npm run build`
|
||
Expected: Build succeeds
|
||
|
||
**Step 4: Commit**
|
||
|
||
```bash
|
||
git add app/api/apks/route.ts
|
||
git commit -m "feat: pass version parameter to APK parser"
|
||
```
|
||
|
||
---
|
||
|
||
### Task 4: Update ApkList to Use Configured Tabs
|
||
|
||
**Files:**
|
||
- Modify: `lib/constants.ts`
|
||
- Modify: `app/download/ApkList.tsx`
|
||
- Add: `app/api/config/route.ts`
|
||
|
||
**Step 1: Create config API endpoint**
|
||
|
||
Create `app/api/config/route.ts`:
|
||
|
||
```typescript
|
||
import { NextResponse } from 'next/server';
|
||
import { APK_TABS } from '@/lib/constants';
|
||
|
||
export async function GET() {
|
||
return NextResponse.json({
|
||
tabs: APK_TABS,
|
||
});
|
||
}
|
||
```
|
||
|
||
**Step 2: Update ApkList to fetch and use configured tabs**
|
||
|
||
Modify `app/download/ApkList.tsx`:
|
||
|
||
```typescript
|
||
'use client';
|
||
|
||
import { useState, useEffect } from 'react';
|
||
import useSWR from 'swr';
|
||
import { type ApkEnvironment } from '@/lib/apk-parser';
|
||
import ApkTable from './ApkTable';
|
||
|
||
const fetcher = (url: string) => fetch(url).then((res) => res.json());
|
||
|
||
interface Apk {
|
||
name: string;
|
||
environment: ApkEnvironment;
|
||
commit: string | null;
|
||
size: number;
|
||
modifiedAt: string;
|
||
downloadUrl: string;
|
||
}
|
||
|
||
interface ApkListProps {
|
||
project: string;
|
||
version: string;
|
||
commitId: string;
|
||
}
|
||
|
||
export default function ApkList({ project, version, commitId }: ApkListProps) {
|
||
const [configuredTabs, setConfiguredTabs] = useState<string[]>([]);
|
||
|
||
// Fetch config on mount
|
||
useEffect(() => {
|
||
fetch('/api/config')
|
||
.then(res => res.json())
|
||
.then(data => setConfiguredTabs(data.tabs))
|
||
.catch(() => setConfiguredTabs(['dev', 'sandbox'])); // fallback
|
||
}, []);
|
||
|
||
const { data: apks, isLoading, error } = useSWR<Apk[]>(
|
||
`/api/apks?project=${project}&version=${version}&commit=${commitId}`,
|
||
fetcher
|
||
);
|
||
|
||
// Build tabs: product → configured → other
|
||
const TABS: ApkEnvironment[] = ['product', ...configuredTabs.filter(t => t !== 'product' && t !== 'other') as ApkEnvironment[], 'other'];
|
||
|
||
if (isLoading) {
|
||
return (
|
||
<div className="text-center py-8 text-gray-500">
|
||
加载中...
|
||
</div>
|
||
);
|
||
}
|
||
|
||
if (error) {
|
||
return (
|
||
<div className="text-center py-8 text-red-600">
|
||
加载失败，请重试
|
||
</div>
|
||
);
|
||
}
|
||
|
||
if (!apks || apks.length === 0) {
|
||
return (
|
||
<div className="bg-white rounded-lg shadow-md p-12 text-center">
|
||
<p className="text-gray-500">未找到匹配的 APK 文件</p>
|
||
</div>
|
||
);
|
||
}
|
||
|
||
// Group APKs by environment
|
||
const groupedApks = apks.reduce((acc, apk) => {
|
||
acc[apk.environment] = [...(acc[apk.environment] || []), apk];
|
||
return acc;
|
||
}, {} as Record<ApkEnvironment, Apk[]>);
|
||
|
||
return (
|
||
<div>
|
||
{/* Tab Navigation */}
|
||
<div className="bg-white rounded-t-lg border-b border-gray-200">
|
||
<nav className="flex space-x-8 px-6" aria-label="Tabs">
|
||
{TABS.map((tab) => {
|
||
const count = groupedApks[tab]?.length || 0;
|
||
return (
|
||
<button
|
||
key={tab}
|
||
onClick={() => {}}
|
||
className={`py-4 px-1 border-b-2 font-medium text-sm ${
|
||
false // activeTab logic removed for simplicity
|
||
? 'border-blue-500 text-blue-600'
|
||
: 'border-transparent text-gray-500 hover:text-gray-700 hover:border-gray-300'
|
||
}`}
|
||
>
|
||
{tab} ({count})
|
||
</button>
|
||
);
|
||
})}
|
||
</nav>
|
||
</div>
|
||
|
||
{/* Tab Content */}
|
||
<div className="mt-4">
|
||
<ApkTable apks={groupedApks['product'] || []} />
|
||
</div>
|
||
</div>
|
||
);
|
||
}
|
||
```
|
||
|
||
Wait, I need to preserve the activeTab state. Let me revise:
|
||
|
||
```typescript
|
||
'use client';
|
||
|
||
import { useState, useEffect } from 'react';
|
||
import useSWR from 'swr';
|
||
import { type ApkEnvironment } from '@/lib/apk-parser';
|
||
import ApkTable from './ApkTable';
|
||
|
||
const fetcher = (url: string) => fetch(url).then((res) => res.json());
|
||
|
||
interface Apk {
|
||
name: string;
|
||
environment: ApkEnvironment;
|
||
commit: string | null;
|
||
size: number;
|
||
modifiedAt: string;
|
||
downloadUrl: string;
|
||
}
|
||
|
||
interface ApkListProps {
|
||
project: string;
|
||
version: string;
|
||
commitId: string;
|
||
}
|
||
|
||
export default function ApkList({ project, version, commitId }: ApkListProps) {
|
||
const [configuredTabs, setConfiguredTabs] = useState<string[]>([]);
|
||
const [activeTab, setActiveTab] = useState<ApkEnvironment>('product');
|
||
|
||
// Fetch config on mount
|
||
useEffect(() => {
|
||
fetch('/api/config')
|
||
.then(res => res.json())
|
||
.then(data => setConfiguredTabs(data.tabs))
|
||
.catch(() => setConfiguredTabs(['dev', 'sandbox'])); // fallback
|
||
}, []);
|
||
|
||
const { data: apks, isLoading, error } = useSWR<Apk[]>(
|
||
`/api/apks?project=${project}&version=${version}&commit=${commitId}`,
|
||
fetcher
|
||
);
|
||
|
||
// Build tabs: product → configured → other
|
||
const TABS: ApkEnvironment[] = ['product', ...configuredTabs.filter(t => t !== 'product' && t !== 'other') as ApkEnvironment[], 'other'];
|
||
|
||
if (isLoading) {
|
||
return (
|
||
<div className="text-center py-8 text-gray-500">
|
||
加载中...
|
||
</div>
|
||
);
|
||
}
|
||
|
||
if (error) {
|
||
return (
|
||
<div className="text-center py-8 text-red-600">
|
||
加载失败，请重试
|
||
</div>
|
||
);
|
||
}
|
||
|
||
if (!apks || apks.length === 0) {
|
||
return (
|
||
<div className="bg-white rounded-lg shadow-md p-12 text-center">
|
||
<p className="text-gray-500">未找到匹配的 APK 文件</p>
|
||
</div>
|
||
);
|
||
}
|
||
|
||
// Group APKs by environment
|
||
const groupedApks = apks.reduce((acc, apk) => {
|
||
acc[apk.environment] = [...(acc[apk.environment] || []), apk];
|
||
return acc;
|
||
}, {} as Record<ApkEnvironment, Apk[]>);
|
||
|
||
return (
|
||
<div>
|
||
{/* Tab Navigation */}
|
||
<div className="bg-white rounded-t-lg border-b border-gray-200">
|
||
<nav className="flex space-x-8 px-6" aria-label="Tabs">
|
||
{TABS.map((tab) => {
|
||
const count = groupedApks[tab]?.length || 0;
|
||
return (
|
||
<button
|
||
key={tab}
|
||
onClick={() => setActiveTab(tab)}
|
||
className={`py-4 px-1 border-b-2 font-medium text-sm ${
|
||
activeTab === tab
|
||
? 'border-blue-500 text-blue-600'
|
||
: 'border-transparent text-gray-500 hover:text-gray-700 hover:border-gray-300'
|
||
}`}
|
||
>
|
||
{tab} ({count})
|
||
</button>
|
||
);
|
||
})}
|
||
</nav>
|
||
</div>
|
||
|
||
{/* Tab Content */}
|
||
<div className="mt-4">
|
||
<ApkTable apks={groupedApks[activeTab] || []} />
|
||
</div>
|
||
</div>
|
||
);
|
||
}
|
||
```
|
||
|
||
**Step 3: Run build to verify**
|
||
|
||
Run: `npm run build`
|
||
Expected: Build succeeds
|
||
|
||
**Step 4: Commit**
|
||
|
||
```bash
|
||
git add app/api/config/route.ts app/download/ApkList.tsx
|
||
git commit -m "feat: add config API and update ApkList to use configured tabs"
|
||
```
|
||
|
||
---
|
||
|
||
### Task 5: Final Verification
|
||
|
||
**Step 1: Run all tests**
|
||
|
||
Run: `npm test`
|
||
Expected: All tests pass
|
||
|
||
**Step 2: Run build**
|
||
|
||
Run: `npm run build`
|
||
Expected: Build succeeds
|
||
|
||
**Step 3: Manual test with dev server**
|
||
|
||
Run: `npm run dev`
|
||
Test: Navigate to download page, select project and version, verify tabs display correctly
|
||
|
||
---
|
||
|
||
## Summary
|
||
|
||
| File | Change |
|
||
|------|--------|
|
||
| `lib/constants.ts` | Add `APK_TABS` env var |
|
||
| `lib/apk-parser.ts` | Rewrite parsing logic with version delimiter |
|
||
| `lib/__tests__/apk-parser.test.ts` | Update tests |
|
||
| `app/api/apks/route.ts` | Pass version to parser |
|
||
| `app/api/config/route.ts` | New endpoint for tab config |
|
||
| `app/download/ApkList.tsx` | Use configured tabs from API |
|