539 lines
13 KiB
Markdown
539 lines
13 KiB
Markdown
# 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**
|
|
|
|
```markdown
|
|
# 巡检相机 - 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**
|
|
|
|
```markdown
|
|
## 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**
|
|
|
|
```bash
|
|
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**
|
|
|
|
```markdown
|
|
## 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**
|
|
|
|
```bash
|
|
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**
|
|
|
|
```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
|
|
```bash
|
|
# 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
|
|
```bash
|
|
# 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**
|
|
|
|
```markdown
|
|
## 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**
|
|
|
|
```markdown
|
|
## 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**
|
|
|
|
```bash
|
|
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**
|
|
|
|
```markdown
|
|
## 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**
|
|
|
|
```markdown
|
|
## 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**
|
|
|
|
```bash
|
|
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**
|
|
|
|
```markdown
|
|
## 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**
|
|
|
|
```markdown
|
|
## 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**
|
|
|
|
```bash
|
|
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**
|
|
|
|
```markdown
|
|
## 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**
|
|
|
|
```markdown
|
|
## 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**
|
|
|
|
```bash
|
|
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**
|
|
|
|
```markdown
|
|
## Build Commands
|
|
|
|
### Debug Build
|
|
```bash
|
|
./gradlew assembleDebug
|
|
```
|
|
|
|
### Release Build
|
|
```bash
|
|
./gradlew assembleRelease
|
|
```
|
|
|
|
### Install to Device
|
|
```bash
|
|
# 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
|
|
```bash
|
|
# 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
|
|
```bash
|
|
./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? |