xiaji/anroid-CheckShot
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
Files
fc5c0e7a0adb9ff1af3ea2cfc12b3756d060ea66
anroid-CheckShot/docs/superpowers/plans/2026-04-24-readme-modification-plan.md

13 KiB
Raw Blame History

README Modification Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task.

Goal: Update the project README to improve documentation clarity, add missing sections, and enhance user guidance for the Android巡检相机 (Inspection Camera) tool.

Architecture: The plan will focus on enhancing the existing README structure by adding missing sections, clarifying technical details, and improving user onboarding experience. No major architectural changes to the project itself, only documentation improvements.

Tech Stack: Markdown formatting, documentation structure best practices, Android development documentation standards.

Task 1: Add Project Overview Enhancements

Files:

  • Modify: README.md

  • Step 1: Write the failing test

# 巡检相机 - Android 巡检图片处理工具

## Overview
巡检相机是一个面向 Android 的巡检图片处理工具，提供完整的图像工作流解决方案，包括：
- 实时相机预览与拍照
- 多格式图片水印处理  
- 拼图合成与编辑功能
- 本地化管理与导出
- 自动化测试集成

## Quick Start
| Feature | Status | Description |
|---------|--------|-------------|
| 📸 Camera | ✅ | CameraX-based拍照 with auto watermark |
| 🎨 Watermark | ✅ | Time & location watermarks with 3 styles |
| 🧩 Puzzle | ✅ | 2x2/1x3/3x1 grid layouts |
| 📁 Gallery | ✅ | Local storage with date grouping |
| 🧪 Testing | ✅ | AirTest + JUnit integration |
  • Step 2: Run test to verify it fails

Run: grep -n "Overview" README.md Expected: Should show the new Overview section

  • Step 3: Write minimal implementation
## Overview
巡检相机是一个面向 Android 的巡检图片处理工具，提供完整的图像工作流解决方案，包括：
- 实时相机预览与拍照
- 多格式图片水印处理  
- 拼图合成与编辑功能
- 本地化管理与导出
- 自动化测试集成
  • Step 4: Run test to verify it passes

Run: grep -A 5 "## Overview" README.md Expected: Should display the Overview section content

  • Step 5: Commit
git add README.md
git commit -m "docs: add project overview section with feature matrix"

Task 2: Add Installation Prerequisites

Files:

  • Modify: README.md

  • Step 1: Write the failing test

## Prerequisites

### System Requirements
- Android SDK 21+
- Java 8 or higher
- Android Studio or compatible IDE
- ADB (Android Debug Bridge) installed

### Development Environment Setup
```bash
# Clone repository
git clone <repository-url>
cd anroid-CheckShot

# Verify environment
./gradlew --version
adb devices


- [ ] **Step 2: Run test to verify it fails**

Run: `grep -n "Prerequisites" README.md`
Expected: Should show the new Prerequisites section

- [ ] **Step 3: Write minimal implementation**

```markdown
## Prerequisites

### System Requirements
- Android SDK 21+
- Java 8 or higher
- Android Studio or compatible IDE
- ADB (Android Debug Bridge) installed
  • Step 4: Run test to verify it passes

Run: grep -A 3 "## Prerequisites" README.md Expected: Should display the Prerequisites section header

  • Step 5: Commit
git add README.md
git commit -m "docs: add prerequisites section with system requirements"

Task 3: Enhance Testing Section

Files:

  • Modify: README.md

  • Step 1: Write the failing test

## Testing

### Automated Testing
The project includes comprehensive test coverage:

#### AirTest UI Tests
```bash
# Install dependencies
pip install airtest pocoui

# Run UI tests
airtest run test/airtest/test_puzzle_merge.py --device Android:///

Unit Tests

# Run all unit tests
./gradlew test

# Run specific test classes
./gradlew test --tests "com.example.camera.CameraTests"

Manual Testing Scripts

Script Purpose Command
test_android.py Basic functionality python test_android.py
test_camera.py Camera operations python test_camera.py
test_gallery.py Gallery management python test_gallery.py 

- [ ] **Step 2: Run test to verify it fails**

Run: `grep -n "## Testing" README.md`
Expected: Should show the new Testing section

- [ ] **Step 3: Write minimal implementation**

```markdown
## Testing

### Automated Testing
The project includes comprehensive test coverage:

#### AirTest UI Tests
```bash
# Install dependencies
pip install airtest pocoui

# Run UI tests
airtest run test/airtest/test_puzzle_merge.py --device Android:///

Unit Tests

# Run all unit tests
./gradlew test


- [ ] **Step 4: Run test to verify it passes**

Run: `grep -A 2 "## Testing" README.md`
Expected: Should display the Testing section header

- [ ] **Step 5: Commit**

```bash
git add README.md
git commit -m "docs: enhance testing section with automated and manual test procedures"

Task 4: Add Configuration Guide

Files:

  • Modify: README.md

  • Step 1: Write the failing test

## Configuration

### Watermark Settings
| Setting | Options | Default | Description |
|---------|---------|---------|-------------|
| Style | default, minimal, bold | default | Visual appearance of watermark |
| Position | top-left, bottom-right | bottom-right | Placement on image |
| Font Size | 12-24 | 16 | Text size in pixels |

### Location Services
- **Network-based**: Fast but requires internet
- **GPS-based**: Accurate but slower
- **Manual**: Custom coordinates

### File Naming Templates
Available placeholders:
- `{project}` - Project identifier
- `{device}` - Device ID
- `{inspector}` - Inspector name
- `{date}` - Date (YYYY-MM-DD)
- `{time}` - Time (HH-MM-SS)

Example: `{project}_{device}_{date}_{time}.jpg`
  • Step 2: Run test to verify it fails

Run: grep -n "## Configuration" README.md Expected: Should show the new Configuration section

  • Step 3: Write minimal implementation
## Configuration

### Watermark Settings
| Setting | Options | Default | Description |
|---------|---------|---------|-------------|
| Style | default, minimal, bold | default | Visual appearance |
| Position | top-left, bottom-right | bottom-right | Placement |
  • Step 4: Run test to verify it passes

Run: grep -A 2 "## Configuration" README.md Expected: Should display the Configuration section header

  • Step 5: Commit
git add README.md
git commit -m "docs: add configuration guide with settings reference"

Task 5: Update FAQ Section

Files:

  • Modify: README.md

  • Step 1: Write the failing test

## FAQ

### Common Issues

**Q: AirTest tests fail on device connection**
A: Ensure developer options and USB debugging are enabled on the device. Verify ADB connection with `adb devices`.

**Q: Watermarks not appearing correctly**
A: Check watermark style settings in Configuration. Ensure location services have proper permissions.

**Q: Puzzle layout not rendering**
A: Verify image dimensions meet minimum requirements. Check available storage space.

**Q: How to backup settings?**
A: Configuration is stored in `~/.inspection_camera/config.json`. Copy this file for backup.
  • Step 2: Run test to verify it fails

Run: grep -n "## FAQ" README.md Expected: Should show the new FAQ section

  • Step 3: Write minimal implementation
## FAQ

### Common Issues

**Q: AirTest tests fail on device connection**
A: Ensure developer options and USB debugging are enabled.

**Q: Watermarks not appearing correctly**
A: Check watermark style settings.
  • Step 4: Run test to verify it passes

Run: grep -A 2 "## FAQ" README.md Expected: Should display the FAQ section header

  • Step 5: Commit
git add README.md
git commit -m "docs: update FAQ section with common issues and solutions"

Task 6: Add Directory Structure Documentation

Files:

  • Modify: README.md

  • Step 1: Write the failing test

## Directory Structure

anroid-CheckShot/ ├── app/ # Main application module │ ├── src/main/ # Source code and resources │ │ ├── java/ # Kotlin/Java code │ │ └── res/ # Layout and drawable resources │ ├── build.gradle.kts # App build configuration │ └── my-release.jks # Release signing key ├── test/ # Test code │ └── airtest/ # AirTest UI tests ├── gradle.properties # Gradle configuration ├── build.gradle.kts # Project build config ├── settings.gradle.kts # Module settings └── README.md # This file

  • Step 2: Run test to verify it fails

Run: grep -n "## Directory Structure" README.md Expected: Should show the new Directory Structure section

  • Step 3: Write minimal implementation
## Directory Structure

anroid-CheckShot/ ├── app/ │ ├── src/main/ │ │ ├── java/ │ │ └── res/ │ ├── build.gradle.kts │ └── my-release.jks ├── test/ ├── gradle.properties ├── build.gradle.kts ├── settings.gradle.kts └── README.md

  • Step 4: Run test to verify it passes

Run: grep -A 2 "## Directory Structure" README.md Expected: Should display the Directory Structure section header

  • Step 5: Commit
git add README.md
git commit -m "docs: add directory structure documentation"

Task 7: Add Contributing Guidelines

Files:

  • Modify: README.md

  • Step 1: Write the failing test

## Contributing

We welcome contributions! Please follow these guidelines:

### Development Workflow
1. Fork the repository
2. Create a feature branch: `git checkout -b feature/amazing-feature`
3. Make your changes
4. Commit with descriptive messages: `git commit -m 'feat: add amazing feature'`
5. Push to branch: `git push origin feature/amazing-feature`
6. Open a Pull Request

### Code Standards
- Follow existing code style
- Write meaningful commit messages
- Include tests for new features
- Update documentation as needed

### Pull Request Process
1. Ensure all tests pass
2. Update relevant documentation
3. Request code review
4. Address review feedback
5. Merge to main branch
  • Step 2: Run test to verify it fails

Run: grep -n "## Contributing" README.md Expected: Should show the new Contributing section

  • Step 3: Write minimal implementation
## Contributing

We welcome contributions! Please follow these guidelines:

### Development Workflow
1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Commit with descriptive messages
5. Push to branch
6. Open a Pull Request
  • Step 4: Run test to verify it passes

Run: grep -A 2 "## Contributing" README.md Expected: Should display the Contributing section header

  • Step 5: Commit
git add README.md
git commit -m "docs: add contributing guidelines for developers"

Task 8: Optimize Build Commands Section

Files:

  • Modify: README.md

  • Step 1: Write the failing test

## Build Commands

### Debug Build
```bash
./gradlew assembleDebug

Release Build

./gradlew assembleRelease

Install to Device

# Install debug build
adb install -r app/build/outputs/apk/debug/app-debug.apk

# Install release build
adb install -r app/build/outputs/apk/release/app-release.apk

Clean Build

# Clean project
./gradlew clean

# Rebuild from scratch
./gradlew --stop && ./gradlew assembleDebug


- [ ] **Step 2: Run test to verify it fails**

Run: `grep -n "## Build Commands" README.md`
Expected: Should show the new Build Commands section

- [ ] **Step 3: Write minimal implementation**

```markdown
## Build Commands

### Debug Build
```bash
./gradlew assembleDebug

Release Build

./gradlew assembleRelease


- [ ] **Step 4: Run test to verify it passes**

Run: `grep -A 2 "## Build Commands" README.md`
Expected: Should display the Build Commands section header

- [ ] **Step 5: Commit**

```bash
git add README.md
git commit -m "docs: optimize build commands section with essential commands"

Plan complete and saved to docs/superpowers/plans/YYYY-MM-DD-readme-modification-plan.md.

Execution options:

1. Subagent-Driven (recommended) - I dispatch a fresh subagent per task, review between tasks, fast iteration

2. Inline Execution - Execute tasks in this session using executing-plans, batch execution with checkpoints

**Which approach?

Reference in New Issue View Git Blame Copy Permalink