Home / Docs Center / Pet Feeder (ODM Case) / Detailed App Feature Design Doc

Detailed App Feature Design Doc

Pet Feeder (ODM Case) · Design Docs

Project: Pet Feeder | page_id: 1706

XSTRIVE Smart Pet Feeder App

Detailed Function Design Document

Document Version: v2.1
Last Updated: 2026-04-23
Product Name: XSTRIVE Smart Pet Feeder
App Version: v1.0.0

Document Description
Role Description and Abbreviations
Data Storage Specification
Function Module Overview
Module 1: Authentication and Account
Module 2: Home Page and Device Overview
Module 3: Device Details and Real-Time Monitoring
Module 4: Album (Capture and Recording)
Module 5: Scheduled Feeding Plan
Module 6: Pet Management
Module 7: Device Settings
Module 8: Family Management
Module 9: Message Center
Module 10: Device Network Configuration and Binding
Module 11: Mine (Personal Center)

1. Document Description

1.1 Purpose

This document is the detailed functional design specification for the XSTRIVE Smart Pet Feeder App. It aims to clarify the specific responsibilities, data flow and status management of the App side, server side and device side at each function point, and to describe the functions with reference to the specific page screenshots in the HTML design draft, providing the development team with a complete and executable functional specification reference.

1.2 Scope of Application

Development team: three-party collaborative development of the App side (iOS/Android), server side and device side

1.3 Reading Instructions

Each functional module is described from the three perspectives of App side, server side and device side
Some modules are attached with a design draft screenshot index, indicating the page position of the function in the HTML design draft
Symbol description:
🟢 = This end needs to handle it
⚪ = This end does not participate
⭐ = Key/critical logic

1.4 Design Draft Screenshot Index Description

The "Corresponding Design Page" is marked below the title of each module in this document

Development/testing personnel can open the HTML file, locate the page, and view the visual design draft of the function module.

2. Role Description and Abbreviations

2.1 System Roles

Role	Description	Corresponding Design
Administrator	Family creator, has full permissions for device management, member management and feeding plan management, and can delete/edit all plans	Family management page (Module 8)
Member	An account invited to join the family; can view device status, trigger manual feeding and view message notifications, but cannot edit other people's plans	Home page device card (Module 2)
Device	XSTRIVE pet feeder hardware terminal, connected to the App through WiFi/Bluetooth	Device details page (Module 3)

2.2 Device Model Specifications

Item	Specification
Device model	None yet
Device name format	XSW-model-{random 4 letters} (e.g.: XSW-PF200-AB12)
Firmware naming	`xsw-pf200-v{x.y.z}.bin`
Supported systems	iOS 12.0+ / Android 8.0+

2.3 Device Status Definition

Status	Description	Display Text	Design Style
`online`	Device is connected to the network and running normally	🟢 Normal / 🟢 Online	Home page card corner mark in green
`offline`	Device is disconnected from the network and cannot be connected	🔴 Offline	Home page card corner mark in gray
`feeding`	Food is being dispensed	⏳ Dispensing	Home page card loading animation
`error`	Device abnormal (food jam, communication failure, etc.)	❌ Abnormal	Home page card red alarm

2.4 Abbreviations

Abbreviation	Full Name	Description
BLE	Bluetooth Low Energy	Low-power Bluetooth, used for device network configuration
MQTT	Message Queuing Telemetry Transport	IoT message transmission protocol
OSS	Object Storage Service	Object storage service (Alibaba Cloud/Tencent Cloud)
CDN	Content Delivery Network	Content delivery network
OTA	Over-The-Air	Over-the-air firmware upgrade
RTC	Real-Time Clock	Real-time clock, device local timing
RTMP	Real-Time Messaging Protocol	Real-time messaging protocol (device video push)
HLS	HTTP Live Streaming	HTTP live streaming (App pull stream)
RTSP	Real Time Streaming Protocol	Real-time streaming protocol (LAN direct pull stream)
JPEG	JPEG	Image compression format
AAC	Advanced Audio Coding	Audio encoding format
ACK	Acknowledgement	Acknowledgement response
JWT	JSON Web Token	User identity token
Redis	Redis	In-memory database (verification code/session storage)

3. Data Storage Specification

3.1 User Data Storage

3.1.1 Photo Storage

Item	Specification	Corresponding Design Element
Single image size	~200KB (JPEG compression, 1280×960, quality 70%)	Album page grid display (Module 4)
Color format	JPEG（RGB）	—
Photo limit per user	50 photos	Album page "8/50 photos stored" statistics
Retention period	7 days (automatic cleanup; records older than 7 days are deleted by the server, and the App clears the local cache synchronously)	—
Storage location	Server-side object storage (OSS) + CDN acceleration	—
Deletion policy	A scheduled background task (daily at 03:00 UTC+8) cleans up records older than 7 days by creation time	—
Local cache	The App does not persist photos locally, and only caches thumbnails (cached on first view, cache limit 20MB)	Album page image placeholder

3.1.2 Video Storage

Item	Specification	Corresponding Design Element
Single video duration	Maximum 30 seconds (automatically truncated beyond 30 seconds)	Device details page recording button (press and hold to record UI prompt)
Single video size	~5MB (H.264, 640×480, 15fps, bitrate ~1.5Mbps)	—
Video format	MP4 (H.264 video / AAC audio)	—
Video limit per user	5 clips	Album page "2/5 clips stored" statistics
Retention period	3 days (automatic cleanup; records older than 3 days are deleted by the server, and the App clears the local cache synchronously)	—
Storage location	Server-side object storage (OSS)	—
Deletion policy	A scheduled background task (daily at 04:00 UTC+8) cleans up records older than 3 days by creation time	—

3.1.3 Device Status Data Structure

// Device real-time status report (MQTT / HTTP polling backup)
{
  "device_id": "PF200-ABC123",
  "sn": "XSW20260408PF200",
  "model": "PF200",
  "firmware_version": "v2.1.0",
  "online": true,
  "power_mode": "plug",
  "battery_level": 100,
  "food_level": 75,
  "food_weight_g": 750,
  "last_feeding_time": "2026-04-23T10:30:00+08:00",
  "today_feeding_count": 3,
  "today_feeding_total_g": 85,
  "total_feeding_count": 128,
  "total_feeding_g": 3840,
  "runtime_hours": 12,
  "network_rssi": -45,
  "error_code": 0,
  "error_message": "",
  "camera_stream_url": "rtmp://media.xswei.com/live/PF200-ABC123",
  "camera_status": "active",
  "microphone_status": "active",
  "speaker_status": "active",
  "timestamp": "2026-04-23T11:55:00+08:00"
}

Device error code definition:

error_code	Description	Severity	User Prompt
0	No error	—	—
101	Food container not installed	Medium	Please install the food container correctly
102	Food container not closed	Medium	Please close the food container lid
201	Food jam detected	High	Food dispensing abnormal, please check and clean the food outlet
202	Motor overload	High	Motor abnormal, please contact customer service
301	Camera failure	Low	Camera abnormal, but the feeding function is normal
302	Microphone failure	Low	Voice function abnormal
303	Speaker failure	Low	Voice playback function abnormal
401	WiFi connection disconnected	Medium	Please check the network connection
402	Cloud connection disconnected	Medium	Please check the network connection
403	OTA upgrade failed	Medium	Firmware upgrade failed, please retry
501	Battery exhausted	High	Device battery exhausted, please charge

3.1.4 Feeding Record Storage

Field	Type	Description
id	UUID	Unique record identifier
device_id	String	Device ID
user_id	String	Operating user ID
pet_id	String	Associated pet ID (optional; null means no pet associated)
family_id	String	Family ID
feed_type	Enum	`manual` / `scheduled`
feed_plan_id	UUID	Associated feeding plan ID (has a value for scheduled feeding)
feed_amount_g	Integer	Food amount (grams), actual dispensed amount (may differ from the plan, e.g. in case of a food jam)
feed_time	DateTime	Feeding time
result	Enum	`success` / `fail`
fail_reason	String	Failure reason (has a value when result=fail)
actual_weight_g	Integer	Weight actually measured by the weighing sensor (the amount reduced in the food container after dispensing)
food_level_after	Integer	Remaining food percentage after feeding

Storage duration: Feeding records are permanently saved and support export by month/device by the user
Query limit: A single query on the App returns a maximum of 100 records, supporting cursor-based pagination
Corresponding design: The "Today's Statistics" module on the home page shows today's feeding count and total grams; the device details page shows today's/this week's/this month's statistics

3.1.5 Family Data Storage

Field	Description	Corresponding Design
family_id	Family unique ID	—
family_name	Family name (e.g. "The Bei Family")	Home page top family switch dropdown
owner_id	Creator (administrator) user ID	Family management member list
created_at	Creation time	—
address	Family address (optional)	—
timezone	Time zone (default Asia/Shanghai)	—
member_count	Number of members (including the administrator)	"Family ×1" statistics on the Mine page

4. Function Module Overview

#	Module Name	App Side	Server Side	Device Side	Priority	Corresponding Design Page
1	Authentication and account	✅	✅	⚪	P0	Login/Registration page
2	Home page and device overview	✅	✅	⚪	P0	Home page
3	Device details and real-time monitoring	✅	✅	✅	P0	Device details page
4	Album (capture and recording)	✅	✅	✅	P1	Album page
5	Scheduled feeding plan	✅	✅	✅	P0	Feeding plan page
6	Pet management	✅	✅	⚪	P1	Pet page
7	Device settings	✅	✅	✅	P1	Device settings page
8	Family management	✅	✅	⚪	P1	Family management page
9	Message center	✅	✅	⚪	P1	Message page
10	Device network configuration and binding	✅	✅	✅	P0	Add device page
11	Mine (personal center)	✅	✅	⚪	P2	Mine page

5. Module 1: Authentication and Account

Corresponding Page Name: Login/Registration page (auth-page)
Design Draft Screenshot Description: The page uses a full-screen gradient background (dark cyan → cyan → light cyan), with the Logo + application name centered at the top, and a white rounded card below carrying the login/registration form. The main tab switches between "Login" and "Register", and the sub-tab switches between "Verification Code Login" and "Password Login".

!image-20260423163202366

5.1 Module Overview

Supports phone number + verification code login, phone number + password login, and the new user registration process. The account system is a family sharing system, and the same phone number can join multiple families.

5.2 Function 1: Verification Code Login

Function Description: The user enters the phone number, obtains the SMS verification code, and completes the login.

Corresponding Design Elements (HTML lines 530~600):
- Input box: phone number input box (with +86 prefix)
- Get verification code button (shows a 60-second countdown after clicking)
- 6-digit verification code input box
- Login button

Dimension	Description
App Side	🟢 Enter the phone number (11 digits, mainland China format, +86 prefix displayed) → request to send the verification code → enter the 6-digit verification code → call the login API → store the JWT token → jump to the home page
Server Side	🟢 Verify the phone number format → generate a 6-digit numeric verification code (cannot be reused) → store it in Redis (key=`sms:login:{phone}`, TTL=300s) → call the SMS gateway to send it → verify the user input → find/create the user record → issue a JWT token
Device Side	⚪ Not involved

Data Specifications:

Item	Specification
Verification code length	6 digits
Verification code validity	5 minutes (300 seconds)
Sending frequency for the same phone number	At most once every 60 seconds
Error retry limit	5 consecutive errors locks the account for 15 minutes
During lockout	Returns the error code ERR_CODE_LOCKED and does not send an SMS
JWT access_token validity	7 days
JWT refresh_token validity	30 days

5.3 Function 2: Password Login

Function Description: The user enters the phone number and password to complete the login.

Corresponding Design Elements

Phone number input box
Password input box (with show/hide toggle icon)
Remember account checkbox
Forgot password text link
Login button

Dimension	Description
App Side	🟢 Enter the phone number + password → check "Remember account" (store the phone number locally) → call the login API → store the token → jump to the home page
Server Side	🟢 Verify that the account exists → verify the password (bcrypt encrypted comparison) → issue a JWT
Device Side	⚪ Not involved

Password rules: 6-20 characters, supporting a mix of letters, numbers and symbols, and must contain both letters and numbers.

5.4 Function 3: Registration

Function Description: A new user registers an account with a phone number; the first family is automatically created after successful registration.

Corresponding Design Elements:

Phone number input box (+86 prefix)
Get verification code button + verification code input box
Set password input box (with show/hide toggle)
Confirm password input box
User agreement checkbox (links to the agreement page)
Register button

Dimension	Description
App Side	🟢 Enter the phone number → get the verification code → set the password (6-20 characters, containing letters and numbers) → confirm the password (same as the password) → check to agree to the agreement → submit the registration
Server Side	🟢 Verify the uniqueness of the phone number (not registered) → create the user record → issue a JWT → automatically create the first family (default name = "{nickname}'s Family", editable)
Device Side	⚪ Not involved

Data Specifications:

Item	Specification
Phone number	11-digit mainland China phone number (regex /^1[3-9]\d{9}$/)
Password	6-20 characters, must contain letters and numbers
Confirm password	Must be exactly the same as the password
Verification code	6 digits, valid for 5 minutes; registration frequency for the same phone number is once every 30 days
Nickname	Optional, 2-20 characters; defaults to "User{last 4 digits of the phone number}" at registration

Automatic behavior after registration:
1. Issue a JWT token (the user directly enters the home page without logging in again)
2. Automatically create a family (family name defaults to "{nickname}'s Family")
3. Record the registration source (iOS/Android/App version)

5.5 Function 4: Account Security

Function Description: Modify the password and bind the phone number

Corresponding Design: "Mine" page → Settings entry → Account security settings page

Dimension	Description
App Side	🟢 Display the current binding information (phone number masked as 138****1234) → changing the password requires verifying the old password
Server Side	🟢 Password modification (update after verifying the old password, re-encrypted with bcrypt)
Device Side	⚪ Not involved

6. Module 2: Home Page and Device Overview

Corresponding Page Name: Home page (home-page)
Design Draft Screenshot Description: Top gradient navigation bar (cyan → dark cyan), with the application Logo + "The Bei Family" family name at the top left (clickable to expand and switch), and the message icon at the top right (with a red dot for the unread count). The main area is the device card list; each card contains: device thumbnail (placeholder image), device name, online status corner mark, today's feeding count and total amount. Bottom fixed tab bar (Home/Album/Feeding/Pets/Mine).

!image-20260423163501832

6.1 Module Overview

The home page is the first page after the user opens the App. It displays the status overview of bound devices, shortcut operation entries (manual feeding, scheduled plan entry), family member/pet count statistics, and pet card display.

6.2 Function 1: Home Page Device Card

Function Description: Displays the device name, real-time monitoring thumbnail (placeholder image), online status and today's feeding statistics.

Corresponding Design Elements:

Navigation bar: family name (with dropdown arrow) + message icon (red dot for unread count)
Device card: thumbnail area (rounded rectangle placeholder) + device name + status corner mark (online/offline) + today's statistics row (🍚 Today's feeding ×3 times, 85g in total) + bottom shortcut operation row
Shortcut operation row: 📷 Record ⏰ Plan ⚙️ Settings

Dimension	Description
App Side	🟢 Request the device list API when the page loads → display the device card (name, status, remaining food %, today's feeding count) → click the card to jump to the device details → click the shortcut operation icons to jump to the corresponding sub-pages
Server Side	🟢 GET /api/v1/devices (query the device list the current user has permission for, including real-time status); status cache strategy: the device status is cached for 30 seconds (Redis) to reduce the MQTT reporting pressure on the device side
Device Side	⚪ Not involved

Device Card Data Structure:

Field	Type	Description
device_id	String	Device unique ID
device_name	String	Device name set by the user
online	Boolean	Whether it is online
food_level	Integer	Remaining food percentage (0-100)
today_feeding_count	Integer	Today's feeding count
today_feeding_total_g	Integer	Today's total feeding amount (grams)
thumbnail_url	String	Device monitoring thumbnail URL (latest frame)
camera_status	String	`active`=normal / `offline`=faulty / `disabled`=turned off

6.3 Function 2: Manual Feeding (Shortcut Operation)

Function Description: A "Manual Feeding" button is provided below the device card on the home page to trigger food dispensing with one click.

Corresponding Design Elements: The "🍚 Manual Feeding" button at the bottom right of the device card on the device details page (theme-colored button, changes to a loading state after clicking)

Dimension	Description
App Side	🟢 Click "Manual Feeding" → display the loading state (button turns gray + spinner) → request the API → wait for the device response (up to 5 seconds) → Toast prompt for success/failure → update today's statistics
Server Side	🟢 Receive the request → verify the user's operation permission for the device (family member relationship query) → verify the device online status → forward the MQTT message to the device → wait for the device ACK (5-second timeout) → record the feeding log
Device Side	🟢 Receive the MQTT message (topic=`device/{device_id}/feed`) → execute the food dispensing action (the stepper motor rotates a specified angle) → the weighing sensor confirms the food amount → report the food dispensing result

Manual Feeding Specifications:

Item	Specification
Trigger method	Click the button once to dispense one portion
Default food amount	The "default food amount" in the device settings (range 5-200g, can be modified on the device settings page)
Pre-dispensing check	When the remaining food in the container < the default food amount, a confirmation prompt "Insufficient food remaining, continue?" pops up
Operation frequency limit	The interval between two manual feedings on the same device must be ≥ 1 minute (to prevent accidental touches)
Member permission	All family members can trigger manual feeding

6.4 Function 3: Family Switching

Function Description: The same account can belong to multiple families; the current family is displayed at the top of the home page, and clicking it expands the switching panel.

Corresponding Design Elements: "🏠 The Bei Family ▾" on the left of the navigation bar (click to expand the dropdown panel, listing all families + the current check mark)

Dimension	Description
App Side	🟢 Click the family name to expand the switching panel → display the family list (with a check mark on the current family) → after selection, save it locally (this family will be the default at the next startup) + request the device list of the new family → refresh the home page
Server Side	🟢 GET /api/v1/families (returns all families the user belongs to, including the number of devices under each family) → GET /api/v1/devices?family_id=xxx when switching
Device Side	⚪ Not involved

7. Module 3: Device Details and Real-Time Monitoring

Corresponding Page Name: Device details page (live-page / device-detail-page)
Design Draft Screenshot Description: The top of the page is the video monitoring area (black background, 16:9 ratio), with the back button at the top left, the device name label overlaid at the top left, and the "LIVE" red dot + current time overlaid at the top right. Below the video is the monitoring control bar: capture button, record button (full screen), intercom button, full screen button. Remaining food progress bar (large ring chart) + today's feeding statistics card + shortcut operation button group (device settings/feeding plan/share/more).

!image-20260423163640968

7.1 Module Overview

The device details page is the core interaction page of the App, containing the real-time video monitoring image, the monitoring control bar (capture/record/intercom/full screen), remaining food/feeding statistics, and device shortcut operation entries.

7.2 Function 1: Real-Time Monitoring Video Stream

Function Description: Displays the real-time image from the device camera (RTMP push + HLS pull), with the LIVE indicator and current time displayed at the top left, and supports multi-stream switching.

Corresponding Design Elements:

Video area: black 16:9 background, filled with the camera image
Top left: "📹 Device Name" white semi-transparent label
Top right: "🔴 LIVE" red dot label + time display "14:32:05"
While the video is loading: a loading animation (rotating circle) is displayed in the center
When the video is disconnected: a disconnection icon + "Video connection interrupted, click to retry" is displayed
Audio: muted by default, stays muted before intercom is enabled

Dimension	Description
App Side	🟢 Use the video player component (iOS: AVPlayer / Android: ExoPlayer) → connect to the HLS stream address (.m3u8) → play the real-time image → audio muted by default → automatic reconnection on stream interruption (3 retries, 5-second interval; after exceeding the limit, a manual retry button is displayed)
Server Side	🟢 Provide the RTMP receiving address (the device pushes the stream to the media server) → convert to HLS (.m3u8 + .ts segments, 4 seconds per segment) → the stream address carries a temporary token (valid for 10 minutes; the App refreshes the token every 8 minutes)
Device Side	🟢 Camera captures video → H.264 encoding → pushes the stream to the server-side media server through the RTMP protocol (rtmp://media.xswei.com/live/{device_id}) → device-side adaptive bitrate (256kbps-2Mbps)

⭐ Camera Channel and Multi-Stream Support:

Item	Specification
Device camera channel	Single channel (built-in camera, no external expansion supported)
Streams supported by the device	The device outputs two streams at the same time: main stream (HD, 1920×1080) and sub stream (SD, 640×480)
Default stream	Sub stream (SD, saves bandwidth and device resources)
App stream switching	Select "SD 640×480" (default) or "HD 1920×1080" on the device settings page; after selection, the server switches the transcoding parameters
Push protocol	RTMP (device → server-side media server)
App pull protocol	HLS (.m3u8 + .ts segments, 4 seconds per segment, 8 segments cached in total)
End-to-end latency	≤3 seconds (SD) / ≤4 seconds (HD)

Video Stream Specifications:

Item	Specification (SD)	Specification (HD)	Description
Encoding format	H.264	H.264	—
Resolution	640×480	1920×1080	Switchable in the device settings
Frame rate	15fps	15fps	—
Bitrate	512kbps (adaptive 256k-1M)	1Mbps (adaptive 512k-2M)	Automatically reduces the bitrate when the network is poor
Audio	AAC 32kbps mono	AAC 32kbps mono	—
HLS segment duration	4 seconds	4 seconds	—
Offline determination	After the device is disconnected from the network, the App waits a maximum of 30 seconds before automatically displaying the offline status	—	—

Stream Address Refresh Mechanism:

Step	Operation
1	App loads the video page for the first time → GET /api/v1/devices/{id}/stream-url
2	The server returns: {hls_url: "https://.../live.m3u8?token=xxx", expires_at: "+10min"}
3	The App plays the HLS stream (AVPlayer / ExoPlayer)
4	A timer refreshes the token every 8 minutes (or 2 minutes before expires_at)
5	GET /api/v1/devices/{id}/stream-url (refresh) → the player switches to the new address (seamless switching, playback is not interrupted)

7.3 Function 2: Capturing Photos

Function Description: Click the "Capture" button on the monitoring image to capture the current video frame and save it as a JPEG image, upload it to the server and store it in the album.

Corresponding Design Elements:

The first icon button in the monitoring control bar "📷 Capture" (circular, blue gradient fill)
After clicking: the screen flashes white once (simulating a shutter effect) + a Toast at the top right "✅ Capture successful, saved to album"
Capture count statistics +1 (e.g. "9/50 photos stored")

Corresponding Design Elements (HTML lines 1325~1340):
- The "Capture and Record" entry card at the bottom of the device details page, showing a thumbnail preview + "12 photos · 3 videos" statistics

Dimension	Description
App Side	🟢 Click capture → decode the current frame from the current video stream (AVCaptureVideoDataOutput / VideoFrame) → JPEG compression (1280×960, quality 70%, about 200KB) → display a local preview (can be deleted) → upload to the server → save to the album → update the local statistics
Server Side	🟢 Receive the image upload (multipart/form-data, ≤500KB per request) → store it in OSS → generate the CDN URL → write it to the database (associated with device_id, user_id, family_id, timestamp) → check whether the number of user photos has reached the 50-photo limit → if exceeded, delete the earliest one
Device Side	⚪ Not involved (the App directly captures the video stream frame, no device cooperation is needed)

⭐ Capture Local Cache Strategy:

Stage	Behavior
Click capture	Immediately capture the video frame (< 100ms response), display the shutter effect (white flash for 100ms)
Generate JPEG	App local compression (no server request, < 500ms)
Local preview	Display the thumbnail preview (automatically disappears after 1 second, or the user manually deletes it)
Upload	Background upload (does not block the user from continuing operations); if the upload fails, it is kept locally for 3 days and retried
Local temporary file	Upload immediately after capture; delete the local temporary file after a successful upload; if the upload fails, keep it and retry up to 3 times (intervals of 30 seconds / 1 minute / 5 minutes)

Capture Specifications:

Item	Specification
Image format	JPEG（RGB）
Resolution	1280×960 (fixed, not affected by the video stream resolution)
Compression quality	70%
Single image size	~200KB
Limit per user	50 photos (the earliest one is automatically deleted when exceeded, no pop-up)
Retention period	7 days (cleaned up daily at 03:00 UTC+8 in the background)
Upload method	HTTPS POST multipart/form-data
Upload timeout	10 seconds; on timeout, prompt "Upload failed, click to retry"
Shutter response latency	< 100ms (from click to the white flash effect appearing)
Image source	The decoded frame of the current video player, not a device-side screenshot

7.4 Function 3: Recording

Function Description: Press and hold the "Record" button to start recording, release to stop, generating an MP4 video file of up to 30 seconds, uploading it to the server and storing it in the album.

Corresponding Design Elements:

The second icon button in the monitoring control bar "🎬 Record" (circular, red fill)
When pressed, the button turns red + the REC indicator is displayed + a recording duration countdown "⏺ REC 00:24 / 00:30"
Text prompt below "Press and hold to record, up to 30 seconds"

Dimension	Description
App Side	🟢 Press and hold the record button → request microphone permission (apply first if not granted) → start recording a local temporary video file (H.264, 640×480, 15fps) → display the REC red dot + duration countdown at the top of the screen → release (or reach 30 seconds) to stop → video compression completed → upload to the server → save to the album → Toast prompt
Server Side	🟢 Receive the video upload (multipart/form-data, ≤10MB) → store it in OSS → write it to the database → check whether the number of videos has reached the 5-clip limit → if exceeded, delete the earliest one
Device Side	⚪ Not involved (recording is done locally on the App side, using the App's own camera and microphone to record the monitoring image)

⭐ Recording Source Description:

Item	Description
Recording image source	Captured from the device monitoring video stream (the App decodes the H.264 frames and re-encodes them into MP4)
Recording audio source	App-side microphone collection (ambient sound, i.e. the sound of pets and the surrounding environment)
Not device-side recording	The sound in the recording is collected by the App-side device microphone, not the sound emitted from the device-side speaker
Camera channel	Fixed to the main stream of the current device (the device firmware push channel) for recording; cannot be switched to another channel

⭐ Recording Upload Path Tiering Strategy:

Stage	Storage Location	Description
Recording in progress	App local temporary file (.mp4)	Written to the App temporary directory (e.g. tmp/) to prevent loss on crash
Recording completed	App local cache (.mp4, kept until the upload succeeds)	A local backup is kept during the upload
Uploading	Server-side OSS (temporary directory)	multipart segmented upload, supports resumable upload
Upload completed	Server-side OSS (official directory)	A video thumbnail is generated at the same time (FFmpeg extracts the frame at the 1st second)
User viewing	CDN accelerated distribution (thumbnail + video stream)	The CDN URL is delivered to the App

Recording Resumable Upload Mechanism:

Scenario	Handling Method
Network disconnected during upload	Record the uploaded segment index and continue from the breakpoint after the network is restored (HTTP Range)
App killed by the system	When the App is reopened, detect the locally incomplete files and automatically resume the upload
Upload fails more than 3 times	Keep the local file and prompt the user "Video upload failed, please check the network and retry"
Retry interval for each upload	30 seconds → 1 minute → 5 minutes

Recording Specifications:

Item	Specification
Video format	MP4 (H.264 video / AAC audio)
Resolution	640×480 (fixed, consistent with the SD video stream)
Frame rate	15fps
Bitrate	~1.5Mbps (real-time encoding during recording)
Maximum duration	30 seconds (automatically truncated if exceeded)
Single clip size	~5MB
Limit per user	5 clips (the earliest one is automatically deleted when exceeded, no pop-up)
Retention period	3 days (cleaned up daily at 04:00 UTC+8 in the background)
Upload method	HTTPS POST multipart/form-data (large files are uploaded in segments, 1MB per segment)
Upload timeout	60 seconds (per segment); no overall upload timeout limit (executed in the background)
Thumbnail generation	The server-side FFmpeg extracts a frame from the 1st second of the video (JPEG, 320×240)
Local temporary retention	Kept locally before the upload succeeds; the temporary file is deleted after the upload succeeds

7.5 Function 4: Two-Way Voice Intercom

Function Description: Click the "Intercom" button to pop up the intercom panel; press and hold to speak so that the sound is played from the device-side speaker, while the device-side sound (pet calls, etc.) is transmitted to the App.

Corresponding Design Elements:

The third icon button in the monitoring control bar "🎤 Intercom" (circular, white outline)
After clicking: the intercom panel slides out from the bottom (semi-transparent mask + circular speak button)
The speak button is centered, with the text "Press and hold to speak, release to end" above it
While speaking, the button displays a volume waveform animation
When intercom is active, a "🎤 Intercom in progress" green label is displayed at the top left of the video image on the device details page

Dimension	Description
App Side	🟢 Click the intercom button → the intercom panel pops up → App→device direction: press and hold the speak button → the microphone collects audio (Opus encoding, 16kHz mono) → send it to the server in real time through WebSocket → the server forwards it to the device; device→App direction: receive the device-side audio stream (WebSocket) → Opus decoding → play through the speaker/headphones
Server Side	🟢 Relay the App-side audio stream to the device (WebSocket connection pool) → relay the device-side audio stream to the App → the audio stream is not stored (use and discard)
Device Side	🟢 Receive the audio stream (WebSocket receives Opus packets) → Opus decoding → play through the speaker (volume adjustable) → the device-side microphone collects sound (16kHz mono) → Opus encoding → WebSocket report to the server

Intercom Specifications:

Item	Specification
Encoding format	Opus (App↔server) / G.711 ulaw (alternative compatibility)
Sampling rate	16kHz
Channel	Mono
Bitrate	32kbps (Opus)
Transport protocol	WebSocket (full-duplex real-time)
Latency requirement	≤500ms (end-to-end)
Intercom timeout	Maximum 60 seconds per session (to prevent holding the button and occupying it all the time)
Device-side speaker	Can be turned off in the device settings (speaker_status=disabled)
Device-side microphone	Can be turned off in the device settings (microphone_status=disabled)

⭐ Full Duplex vs Half Duplex: This design uses half duplex (only one party can speak at a time) to avoid echo and interference. When the device detects that the ambient volume is too high (pet calls, etc.), it can automatically reduce the uplink audio bitrate.

7.6 Function 5: Full Screen Mode

Function Description: Click the "Full screen" button to play the video in landscape full screen; the control bar is hidden, and clicking the screen restores portrait mode.

Corresponding Design Elements: The fourth icon button in the monitoring control bar "⛶ Full screen" (circular, white outline). After clicking, the screen rotates to landscape, the video fills the screen, and the top status bar is hidden.

Dimension	Description
App Side	🟢 Trigger the screen rotation to landscape → hide the top navigation bar and bottom tab bar → the video image fills the screen → the control bar shrinks and floats at the bottom right (capture/record icons) → click anywhere on the screen to bring up the control bar, and it is hidden again after 3 seconds of no operation
Server Side	⚪ Not involved
Device Side	⚪ Not involved

7.7 Function 6: Remaining Food Statistics and Today's Feeding Statistics

Corresponding Design Elements:

Remaining food ring progress bar (large, showing the percentage number such as "75%", with gradient color: >50% green, 20-50% orange, <20% red)
Text below "Food container remaining / about 750g" (displaying the actual weight in grams)
Today's statistics card: today's feeding "3 times" + total "85g"

Dimension	Description
App Side	🟢 Get food_level and food_weight_g from the device status data when the page loads → the ring progress bar is displayed proportionally → when it is below 20%, an orange warning is displayed + an "Insufficient food remaining" prompt bar pops up at the top of the card
Server Side	🟢 The device status report carries food_level (percentage) and food_weight_g (actual grams)
Device Side	🟢 The weighing sensor monitors the weight of the food container in real time → reports food_level and food_weight_g through MQTT

8. Module 4: Album (Capture and Recording)

Corresponding Page Name: Album page (album-page / gallery-page)
Design Screenshot Description: Top navigation bar "📷 Album" + "Filter" icon at the top right. Filter tabs: "All / Photos / Videos". The main body uses a grid layout (3 columns); photos show thumbnails (rounded corners) and video thumbnails are overlaid with a play icon (▶) plus a duration label (e.g. "0:25"). Storage statistics bar: "10/50 photos stored · 2/5 videos".

!image-20260423164016822

8.1 Module Overview

The album page centrally manages the photos captured and videos recorded by users on the device details page. It provides filtering, preview and deletion functions, and displays storage usage statistics.

8.2 Function 1: Album List Display

Function Description: Display photo and video thumbnails in a grid, supporting three filters: "All/Photos/Videos".

Corresponding Design Elements:

Filter tab bar (All/Photos/Videos)
Storage statistics bar (displays "10/50 photos stored · 2/5 videos"; this text element does not exist in the HTML but the layout is retained)
Grid area (3 columns, 4px spacing, photos and videos displayed together)
Video thumbnails overlaid with a play icon (▶) + duration label (e.g. "0:25")
Photo thumbnails overlaid with the capture time (relative time, e.g. "3 minutes ago")

Corresponding Design Elements: The "Capture and Recording" entry card at the bottom of the device details page:

Left icon area (orange gradient background, photo icon) + title "Capture and Recording" + statistics text "12 photos · 3 videos"
Right thumbnail preview (3 small circular images)
Tap to jump to the album page

Dimension	Description
App Side	🟢 Request the album list API (GET /api/v1/media?type=all/photo/video&page=1&limit=20) → grid display (3 columns) → video thumbnails overlaid with a play icon + duration → pull down to refresh, pull up to load more (20 items/page) → a skeleton screen is displayed on first load
Server Side	🟢 Query the album records of the current user (in reverse chronological order, filtered by media_type) → return paginated → for videos, additionally return a thumbnail URL (the server uses FFmpeg to extract a frame from the 1st second of the video as the thumbnail)
Device Side	⚪ Not involved

Data Specifications:

Field	Type	Description
media_id	UUID	Unique identifier of the media record
media_type	Enum	`photo` / `video`
cdn_url	String	CDN access URL (original photo / video playback address)
thumbnail_url	String	Thumbnail URL (small photo image / first video frame in JPEG)
device_id	String	Source device ID
device_name	String	Source device name (name set by the user)
duration	Integer	Video duration (seconds; only has a value for the video type)
duration_label	String	Formatted duration label, e.g. "0:25"
created_at	DateTime	Creation time, ISO 8601
relative_time	String	Relative time description, e.g. "3 minutes ago", "Yesterday"
photo_limit	Integer	User photo limit (fixed at 50)
video_limit	Integer	User video limit (fixed at 5)
total_photo	Integer	Current number of photos
total_video	Integer	Current number of videos

8.3 Function 2: Photo Preview and Deletion

Function Description: Tap a photo to enter full-screen preview, swipe left/right to switch photos, and tap the delete button and confirm to delete.

Corresponding Design Elements (interactive elements are controlled by JS):

Full-screen preview (black background, image centered, semi-transparent information bar at the bottom)
Bottom information bar: device name "Xiaobei's Feeder" + capture time "April 23, 2026 14:30"
Delete icon at the top right (🗑 red)
Swipe left/right to switch photos
Bottom action bar: share button / delete button

Dimension	Description
App Side	🟢 Tap a photo → full-screen preview → support switching by swiping left/right (horizontal scrolling, infinite loop) → tap the delete icon at the top right → confirmation dialog "Delete this photo? It cannot be recovered after deletion" → call the delete API → refresh the current list
Server Side	🟢 DELETE /api/v1/photos/{photo_id} → delete the OSS file (async task) → delete the database record → return success
Device Side	⚪ Not involved

8.4 Function 3: Video Preview and Deletion

Function Description: Tap a video thumbnail to call the system player for full-screen playback; tap the delete button and confirm to delete.

Corresponding Design Elements:

After tapping, play directly in full screen (calling the system player, or the App's embedded ExoPlayer/AVPlayer)
Playback screen: video image + progress bar + duration display + play/pause button
A delete icon (🗑) is displayed at the top right when paused
Deletion confirmation dialog "Delete this recording? It cannot be recovered after deletion"

Dimension	Description
App Side	🟢 Tap a video → call the system player (AVPlayer / ExoPlayer) for full-screen playback → when playback finishes or delete is tapped → confirmation dialog → call the delete API → refresh the list
Server Side	🟢 DELETE /api/v1/videos/{video_id} → delete the OSS file (async) → delete the database record → return success
Device Side	⚪ Not involved

8.5 Function 4: Share

Function Description: Photos or videos can be shared to WeChat, WeChat Moments, QQ, etc.

Corresponding Design Elements: The "Share" button in the bottom action bar of the photo/video preview page

Dimension	Description
App Side	🟢 Tap Share → bring up the system share panel (ShareSheet) → support sharing images (JPEG URL) or videos (local file path)
Server Side	⚪ Not involved

8.6 Storage Specification Summary (Album Module)

Media Type	Format	Resolution	Single File Size	User Limit	Retention Period	Automatic Cleanup Time
Photo	JPEG	1280×960	~200KB	50 photos	7 days	Daily 03:00 UTC+8
Video	MP4 (H.264)	640×480, 15fps	~5MB/clip	5 clips	3 days	Daily 04:00 UTC+8

Silent Handling When Storage Limit Is Reached: After the limit is reached, the oldest records are automatically deleted. No dialog is shown to the user and the current operation flow is not interrupted.

9. Module 5: Scheduled Feeding Plan

Corresponding Page Name: Feeding plan page (feeding-plan-page)
Design Screenshot Description: Top navigation bar "⏰ Feeding Plan" + "+" add button at the top right. The main body is the plan list. Each plan card shows: pet avatar (emoji) / default icon + pet name + feeding time (bold large text such as "08:00") + feeding portion "30g" + repeat cycle labels (Monday to Sunday icons, today is highlighted) + toggle button (ON/OFF). At the bottom there is a "+ Add Plan" floating button.

!image-20260423164207392

9.1 Module Overview

Administrators can create, edit and delete scheduled feeding plans (supporting daily repeat / by workday / by specified weekday repeat). The device side automatically dispenses food according to the plan delivered by the server; the App does not need to be online.

9.2 Function 1: Plan List

Function Description: Display all feeding plans of the current device, showing time, portion, pet, repeat cycle and toggle status.

Corresponding Design Elements:

Plan card: pet icon + pet name + time "08:00" (bold) + portion "30g" + repeat cycle (small dots from Monday to Sunday, the current day is solid and highlighted) + toggle button
Empty list state: "No feeding plan yet" + icon + "Tap the button below to add"
Visible to administrators: edit (✏️) and delete (🗑) operation entries
Visible to members: only the list is displayed; editing is not possible

Dimension	Description
App Side	🟢 Request the plan list API (GET /api/v1/feeding-plans?device_id=xxx) → list display (sorted by time) → edit/delete buttons are shown to administrators; members can only toggle plans
Server Side	🟢 Query the plan list associated with the device → return sorted by plan time → include user role information for the App to determine operation permissions
Device Side	⚪ Not involved

9.3 Function 2: Create a Plan

Function Description: The administrator fills in the feeding plan form, setting the time, pet, portion and repeat cycle.

Corresponding Design Elements (form page): Add plan page form:

Device selection (if the family has multiple devices, the current device is selected by default)
Pet selection (can be skipped, displayed as "No pet linked")
Feeding time picker (clock style, scroll wheel to select "08 : 00")
Food portion picker (slider or numeric input, range 5-200g, step 5g, with scale displayed)
Repeat cycle selection (Monday to Sunday icon button group, tap to toggle the selected state)
Save button

Dimension	Description
App Side	🟢 Fill in the form → validate required fields → submit POST /api/v1/feeding-plans → return to the list page after success
Server Side	🟢 Create the plan record → immediately push it to the device side via MQTT (stored locally on the device) → record the operation log
Device Side	🟢 Receive the plan MQTT message (topic=`device/{device_id}/plan/update`) → store it in local Flash → dispense food on schedule according to the plan (RTC wake-up)

New Plan Data Specifications:

Item	Specification
Food portion range	5-200g, step 5g
Time selection	00:00-23:59, accurate to the minute
Repeat cycle	Any combination from Monday to Sunday, at least 1 day must be selected
Common shortcuts	"Every day" selects Monday to Sunday with one tap / "Workdays" selects Monday to Friday with one tap
Pet association	Optional (not selecting = no pet linked)
Plan limit per device	20

9.4 Function 3: Edit/Delete a Plan

Function Description: Administrators can edit any field of an existing plan; they can delete a plan (a second confirmation is required).

Corresponding Design Elements:

Edit: tap the plan card or the edit button → enter the edit form page (same content as creation, auto-filled)
Delete: tap the delete button → a confirmation box pops up "Delete the "08:00 · 30g" plan? It cannot be recovered after deletion"

Dimension	Description
App Side	🟢 Edit: GET to fill the form → PUT /api/v1/feeding-plans/{id}; Delete: confirmation dialog → DELETE → refresh the list
Server Side	🟢 Update/delete the plan → immediately notify the device side via MQTT
Device Side	🟢 Receive MQTT → update/delete the corresponding plan in local Flash

9.5 Function 4: Plan Toggle (Member Permission)

Function Description: All family members (including ordinary members) can enable/disable a feeding plan.

Corresponding Design Elements (Toggle Switch on the right of each plan)

Dimension	Description
App Side	🟢 Tap the toggle → PATCH /api/v1/feeding-plans/{id} {enabled: true/false} → update the local state → done if successful, roll back the toggle state if it fails
Server Side	🟢 Update the enabled field → notify the device side via MQTT
Device Side	🟢 Receive MQTT → update the enabled state of the local plan → when enabled=false, skip execution of that plan

⭐ Permission Rule: Only administrators can edit/delete plans. Ordinary members can only operate the toggle (enable/disable a plan) and cannot edit core fields such as time/portion.

9.6 Function 5: Scheduled Execution on the Device Side

Function Description: The device side automatically dispenses food according to the locally stored plan when the set time is reached.

Dimension	Description
Server Side	🟢 Does not directly control the device; the device executes autonomously; the server records the execution result of each scheduled feeding (reported by the device)
Device Side	🟢 RTC timer monitoring (wakes up to check once per minute) → when the time is reached and today's repeat_days includes the current weekday → the stepper motor dispenses food → the weighing sensor confirms the dispensed amount → compares it with the planned amount (an error of ±10g is acceptable) → reports the execution result via MQTT

Offline Handling:
- The device stores the complete plan list locally and the RTC still executes feeding according to the plan while offline
- After going back online, the device side immediately reports the feeding records from the offline period (topic=device/{device_id}/feed/batch-report)
- After receiving them, the server backfills the feeding records, and the user can view them in the App

Food Jam Handling:
- Weighing sensor detection: if the actual dispensed amount is < the planned amount − 10g after dispensing, it is judged as a food jam
- The device side automatically retries (up to 3 times, 10 seconds apart each time)
- If the retries still fail: report error_code=201, and the App pushes an alarm message "Abnormal food dispensing. Please check and clean the food outlet"

10. Module 6: Pet Management

Corresponding Page Name: Pet page (pet-page)
Design Screenshot Description: Top navigation bar "🐾 My Pets" + "+" add button at the top right. The main body is a list of pet cards. Each card: pet avatar (large emoji or custom image, circular) + pet name (bold) + pet type/breed "Dog · Corgi" + age/gender tag + bottom action "🍚 Feeding Records" button. Empty list state: blank placeholder image + "No pets yet, tap to add" + add button.

!image-20260423164501579

10.1 Module Overview

Manage the pet profiles in the family (avatar, name, type, breed, age, gender). Pets are linked to feeding plans, making it easy to record the pet corresponding to each feeding.

10.2 Function 1: Pet List

Function Description: Display all pet cards in the family (avatar, name, type/breed/age/gender).

Corresponding Design Elements:

Pet card: circular avatar (emoji or custom image) + pet name + type/breed line + age/gender tag
Card bottom: "🍚 Feeding Records" button
Shown to administrators: edit (✏️) and delete (🗑) operation entries
Shown to members: view only, cannot edit

Dimension	Description
App Side	🟢 Request the pet list API (GET /api/v1/pets?family_id=xxx) → card display
Server Side	🟢 Query the pet list associated with the family, sorted by creation time
Device Side	⚪ Not involved

10.3 Function 2: Add a Pet

Function Description: Fill in the pet profile information and select/upload a pet avatar.

Corresponding Design Elements (form page):

Avatar selection area (centered at the top, large circular avatar selection box)
First row: preset emoji avatar grid (12 types: 🐶🐱🐰🐹🐸🐦, etc.)
Second row: "📷 Upload Image" button (custom image, within 1MB)
Pet name input box (2-20 characters)
Pet type selection (Dog / Cat / Other → secondary options)
Breed input box (optional)
Birthday picker (optional)
Gender selection (Male / Female / Unknown)
Save button

Dimension	Description
App Side	🟢 Select an emoji avatar or upload a custom image (JPEG/PNG, within 1MB, compressed to 200KB on the App side) → fill in the form → POST /api/v1/pets
Server Side	🟢 Create the pet record → store the avatar image to OSS (when a custom avatar is used)
Device Side	⚪ Not involved

10.4 Function 3: Edit a Pet

Function Description: Edit the profile information of an existing pet (avatar, name, type, breed, age, gender).

Corresponding Design Elements: Tap the pet card → edit form page (same content as adding, auto-filled with existing data)

Dimension	Description
App Side	🟢 GET pet details → fill the form → PUT /api/v1/pets/{id}
Server Side	🟢 Update the pet record
Device Side	⚪ Not involved

10.5 Function 4: Delete a Pet

Function Description: Delete a pet profile and at the same time unlink it from feeding plans (pet_id is set to empty; the plan itself is not deleted).

Corresponding Design Elements: Pet card → delete button → confirmation dialog "Delete "Xiaobei"? After deletion, all associated feeding plans will be unlinked from this pet, but the plans themselves will not be deleted."

Dimension	Description
App Side	🟢 Confirmation dialog → DELETE /api/v1/pets/{id} → refresh the list
Server Side	🟢 Delete the pet record → unlink the feeding plan association (set pet_id to empty)
Device Side	⚪ Not involved

10.6 Function 5: Pet Feeding Records

Function Description: Tap the "🍚 Feeding Records" button on the pet card to view the historical feeding records of that pet.

Corresponding Design Elements: Feeding record list page (in reverse chronological order):
- Each record: time label "April 23 08:05" + portion "30g" + feeding method label (manual/scheduled) + device name "Xiaobei's Feeder" + status (success ✅ / failed ❌)

Dimension	Description
App Side	🟢 GET /api/v1/feeding-records?pet_id=xxx → list display → paginated loading
Server Side	🟢 Query the feeding records associated with pet_id and return them paginated in reverse chronological order
Device Side	⚪ Not involved

11. Module 7: Device Settings

Corresponding Page Name: Device settings page (device-settings-page)
Design Screenshot Description: Top navigation bar "⚙️ Device Settings" + back button. Settings group list: Basic settings / Feeding settings / Camera settings / Voice settings / Device info / bottom danger zone (Unbind).

!image-20260423164556958

11.1 Module Overview

Manage the configuration items of a single device, including basic settings, feeding settings, camera settings, voice settings and device information display.

11.2 Function 1: Basic Settings

Function Description: Modify the device name, set the device location, and display the power supply mode.

Corresponding Design Elements:

Device name input box (tap to edit, the keyboard pops up)
Device location picker (6 preset options with circular icons: Living room / Bedroom / Balcony / Kitchen / Other)
Power supply mode display (plug-in icon 🔌 or battery icon 🔋 + percentage)

Dimension	Description
App Side	🟢 Tap the device name → edit → PUT /api/v1/devices/{id} {device_name}; tap a location option → PUT /api/v1/devices/{id} {location}
Server Side	🟢 Update the device configuration → store it in the database → deliver it to the device side via MQTT (only device_name needs to be delivered to the device)
Device Side	🟢 Receive device_name → store it locally → the device display/LCD shows the name (if available)

11.3 Function 2: Feeding Settings

Function Description: Set the default food portion (the initial value for manual feeding and new plans), the feeding sound switch, the food dispensing reminder switch and the low food level reminder threshold.

Corresponding Design Elements:

Default food portion slider (range 5-200g, step 5g, scale labels shown below)
Feeding sound switch (a prompt tone is played when dispensing food if enabled)
Food dispensing reminder switch (the App pushes a notification after dispensing if enabled)
Low food level reminder threshold slider (range 5%-50%, default 20%, with the text below "A reminder is sent when the food level is lower than this value")

Dimension	Description
App Side	🟢 Adjust the slider/switch → save in real time (the API is called after 300ms debounce)
Server Side	🟢 Update the device configuration → deliver it immediately to the device side via MQTT
Device Side	🟢 Receive the configuration → store it in local Flash → apply the configuration each time food is dispensed

11.4 Function 3: Camera Settings

Function Description: Set the video resolution, infrared night vision mode and recording quality.

Corresponding Design Elements:

Image resolution options: "Standard definition 640×480" (default) / "High definition 1280×720"
Infrared night vision options: "Auto" (switches automatically according to light) / "Always on" / "Off"
Recording quality options: "Standard quality" (default) / "High quality" (only available when the resolution is set to high definition)

Dimension	Description
App Side	🟢 After selection, PUT /api/v1/devices/{id}/camera {resolution, night_vision_mode, record_quality}
Server Side	🟢 Update the configuration → deliver it to the device side via MQTT
Device Side	🟢 Receive the configuration → the camera module adjusts parameters (resolution switching requires a brief restart of the camera preview)

⭐ Camera Resolution Switching Notes:

Item	Standard Definition Mode (Default)	High Definition Mode
Resolution	640×480	1280×720
Device encoding bitrate	512kbps (adaptive 256k-1M)	1Mbps (adaptive 512k-2M)
Device heating	Normal	May increase; prolonged use is not recommended
App data usage	~400MB/hour	~800MB/hour
Recording file size	~5MB/30 seconds	~10MB/30 seconds
Server-side transcoding	Standard definition HLS stream	High definition HLS stream

11.5 Function 4: Voice Settings

Function Description: Adjust the intercom volume, and enable/disable the device-side sound (speaker) and device-side microphone.

Corresponding Design Elements:

Intercom volume slider (0-100, default 80)
Device-side sound switch (the device can play the voice sent by the App when enabled)
Device-side microphone switch (the device can capture sound and send it to the App when enabled)

Dimension	Description
App Side	🟢 Slider adjustments take effect in real time (the volume value is sent to the device) → switching a toggle calls the API
Server Side	🟢 Update the configuration → deliver it to the device side via MQTT
Device Side	🟢 Receive the volume value → apply it to the speaker output in real time; receive the toggle state → control whether audio is captured/played

11.6 Function 5: Device Information Display

Function Description: Display read-only meta information such as the device model, firmware version, device ID, running time and cumulative feeding statistics.

Corresponding Design Elements:

Device model: PF200 (read-only text)
Device ID: PF200-ABC123 (read-only text, can be copied)
Firmware version: v2.1.0 (read-only text, tap to enter the firmware upgrade page)
Device SN: XSW20260408PF200 (read-only text)
Running time: 12 hours ("Has been running stably for 12 hours 5 minutes")
Cumulative feeding: 128 times in total / 3840g in total (read-only text)

Dimension	Description
App Side	🟢 Request the device details API → display read-only information (the copy button calls the system copy function)
Server Side	🟢 Provide detailed device information (including firmware version, SN, running time, cumulative statistics)
Device Side	🟢 The device-side firmware stores the version information and carries it in the status report

11.7 Function 6: Firmware Upgrade (OTA)

Function Description: Detect new firmware versions, download and upgrade the device firmware.

Corresponding Design Elements (HTML lines 1900~1920, firmware upgrade page):
- Current version: v2.1.0 (displayed)
- Latest version: v2.2.0 (displayed if a new version exists) → new version description "Fixed several bugs and improved stability"
- Upgrade button (if a new version exists, shows "Check for updates" → "Upgrade now")
- Upgrade progress: download progress bar (0-100%) + status text "Downloading firmware…" "Upgrading… do not power off"

Dimension	Description
App Side	🟢 GET /api/v1/devices/{id}/firmware → compare versions → when a new version exists, a dialog prompts "New version v2.2.0 found, upgrade now?" → the user confirms → download the firmware package (HTTPS segmented download, with resume support) → forward the firmware to the device via MQTT/TCP → display the upgrade progress → the device restarts after the upgrade completes → the App detects that the device is online → Toast "Upgrade successful"
Server Side	🟢 Provide the firmware version query interface → provide the firmware file download (CDN accelerated, segmented download with resume support)
Device Side	🟢 Receive the firmware package → verify the signature (RSA-2048 or AES verification) → write it to the Flash backup area → switch the boot partition after verification passes → restart → run the new firmware → report the new version number via MQTT

Firmware Upgrade Specifications:

Item	Specification
Firmware package format	.bin (with an RSA-2048 signature header)
Maximum firmware size	4MB
Signature verification	The device side writes to Flash only after signature verification passes; otherwise the package is discarded
Upgrade method	The App downloads it and forwards it to the device via MQTT (when the device is online); or the device connects directly to the OTA server to download
Resume support	Supported (HTTP Range requests)
During the upgrade	The device side stops streaming and feeding, and the display shows "Upgrading…"
Upgrade failure handling	The device automatically rolls back to the old firmware (dual-partition design) and reports an upgrade failure log
Upgrade timeout	If the device side does not complete the upgrade within 5 minutes, it is judged as a failure and a rollback is triggered

11.8 Function 7: Unbind

Function Description: Remove the device from the current family and unbind the account from the device.

Corresponding Design Elements: The "🚨 Unbind" red button at the bottom of the device settings page (danger operation zone). After tapping:

Confirmation dialog "Unbind "Xiaobei's Feeder"? After unbinding, you will not be able to control this device through this App, and other family members will also lose access."
Second confirmation: enter the device name to confirm "Please enter "Xiaobei's Feeder" to confirm"

Dimension	Description
App Side	🟢 Second confirmation by entering the device name → POST /api/v1/devices/{id}/unbind → clear the local device cache → return to the home page (device list empty state)
Server Side	🟢 Delete the device binding record → notify the device side to clear the pairing information (MQTT) → the device enters network configuration mode after clearing the pairing information
Device Side	🟢 Receive the unbind notification → clear the local user binding information → enter network configuration mode (fast blue flash)

12. Module 8: Family Management

Corresponding Page Name: Family management page (family-page)
Design Screenshot Description: Top navigation bar "👨‍👩‍👧 Family Management" + back button. Main area: current family information card (family name + number of members) + member list (avatar + nickname + role tag "Administrator★" / "Member") + "Invite Member" button at the top right. Bottom action area: "Edit Family Information" + "Disband Family" (administrator only, visible when there are no other members).

!image-20260423164717172

12.1 Module Overview

Manage family units, including creating/editing family information, inviting/removing members, and setting member roles (administrator/member).

12.2 Function 1: Create/Edit a Family

Function Description: Create a new family (fill in the name and address); administrators can edit family information.

Corresponding Design Elements:

Create family form: family name input box (required, 2-20 characters) + family address input box (optional)
Edit family form: same as creation, auto-filled with existing data

Dimension	Description
App Side	🟢 Fill in the form → POST /api/v1/families or PUT /api/v1/families/{id}
Server Side	🟢 Create the family record → the creator automatically becomes the administrator (role=owner); only administrators are allowed to perform updates
Device Side	⚪ Not involved

12.3 Function 2: Invite Members

Function Description: Invite others to join the family through a QR code / invitation link.

Corresponding Design Elements:

Invitation page: family QR code (centered, can be saved to the album) + copy link button + share to WeChat/QQ buttons
Text below the QR code: "Scan the QR code to join "Xiaobei's Family"" "The invitation link is valid for 7 days"

Dimension	Description
App Side	🟢 Display the family QR code (QRCode generation, containing the invitation link URL) → provide copy link sharing
Server Side	🟢 Generate a time-limited family invitation code (UUID, valid for 7 days, stored in Redis, TTL=604800s) → generate the invitation link URL → the invitee opens the App through the invitation link → the invitation code is filled in automatically → the user joins the family after confirmation, with the role defaulting to "Member"
Device Side	⚪ Not involved

Invitation Specifications:

Item	Specification
Invitation code format	UUID v4
Invitation code validity	7 days (604800 seconds)
Invitation code usage count	One-time (it becomes invalid immediately after joining)
Invitation method	QR code (the URL contains the invitation code) / invitation link
Invitee role	Defaults to "Member" (not administrator)
Invitation limit for administrators	Unlimited

12.4 Function 3: Remove Members

Function Description: Administrators can remove other members (confirmation dialog); members cannot remove themselves (they need to contact the administrator or leave the family).

Corresponding Design Elements: The "Remove" button on the right of each item in the member list (red text, administrator operation). After tapping:

Confirmation dialog "Remove "{member nickname}" from the family? After removal, this member will not be able to access all devices in the family."

Dimension	Description
App Side	🟢 The administrator taps Remove → confirmation dialog → DELETE /api/v1/family-members/{member_id}
Server Side	🟢 Delete the member relationship → revoke that member's access permission to family devices
Device Side	⚪ Not involved

⭐ Permission Rules:

Administrators cannot remove themselves
A family must retain at least 1 administrator
If an administrator wants to leave the family, administrator permission must first be transferred to another member
Members can leave the family proactively (the "Leave Family" button is in the member's personal card)

13. Module 9: Message Center

Corresponding Page Name: Message page (message-page)
Design Screenshot Description: Top navigation bar "🔔 Messages" + "⚙️ Message Settings" button at the top right. Filter tabs: "All / Feeding / Device / System". The main body is a message list. Each message card: left icon (🔔 feeding / ⚠️ device / 📢 system) + message title (bold) + message summary (small gray text) + time label (on the right, "3 minutes ago" / "Yesterday"). Unread messages have a blue vertical bar marker on the left.

!image-20260423164807542

13.1 Module Overview

Centrally display system push notifications, including feeding completion notifications, device alarm notifications, family member change notifications, system announcements, etc.

13.2 Function 1: Message List

Function Description: Display messages in reverse chronological order, supporting filtering by type (All/Feeding/Device/System). Unread messages have a blue vertical bar marker on the left.

Corresponding Design Elements:

Message list: each message card + unread blue vertical bar + title + summary + time
Filter tabs (All/Feeding/Device/System)
Message details page: tap a card → enter the details page (full-screen message content + related action buttons)

Dimension	Description
App Side	🟢 Request the message list (GET /api/v1/messages?type=all/feed/device/system&page=1&limit=20) → list display → tap to mark as read → pull down to refresh, pull up to load more
Server Side	🟢 Query the user's message records (all messages under the associated family_id) → return paginated in reverse chronological order
Device Side	⚪ Not involved

Message Read Policy:
- When the App enters the message list page, all messages on the current screen are silently marked as read (batch PATCH)
- When entering the details page of a single message, that message is individually marked as read
- The message icon in the bottom tab bar shows a red dot with the unread count (updated in real time)

13.3 Function 2: Message Push Trigger

Function Description: The server generates and pushes messages according to the event type, and at the same time pushes them to the App through the JPush/Umeng/self-built Push channel.

Trigger Scenario	Message Type	Push Title	Push Content Example	Message Card Icon
Manual feeding completed	Feeding	🍚 Feeding Completed	"Xiaobei's Feeder has dispensed 30g of food"	🍚
Scheduled plan execution completed	Feeding	⏰ Scheduled Feeding	"08:00 scheduled feeding of 30g completed"	⏰
Scheduled plan execution failed	Feeding	⚠️ Feeding Abnormal	"08:00 scheduled feeding failed: food jam detected"	⚠️
Food level below the threshold	Device Alarm	⚠️ Insufficient Food	"Xiaobei's Feeder has only 15% food left, please refill in time"	⚠️
Device online	Device Status	🟢 Device Online	"Xiaobei's Feeder is connected to the network"	🟢
Device offline	Device Status	🔴 Device Offline	"Xiaobei's Feeder is offline, please check"	🔴
Device battery low	Device Alarm	🔋 Low Battery	"Xiaobei's Feeder has only 10% battery left, please charge"	🔋
Firmware upgrade completed	Device Update	✨ Firmware Upgrade	"Xiaobei's Feeder has been upgraded to v2.2.0"	✨
New member joined	Family Notification	👋 New Member	"Mom has joined the family "Xiaobei's Family""	👋
Member removed	Family Notification	👋 Member Change	"You have been removed from the family "Xiaobei's Family""	👋
App update	System Notification	📱 Update Prompt	"App has been updated to the latest version v1.0.1, tap to view"	📱

13.4 Function 3: Message Settings

Function Description: Users can toggle various message notifications (feeding reminders, low food level reminders, device offline reminders, low battery reminders, do-not-disturb mode).

Corresponding Design Elements (message settings page):

Feeding reminder switch (enabled by default)
Low food level reminder switch (enabled by default)
Device status reminder switch (enabled by default)
Low battery reminder switch (enabled by default)
Do-not-disturb period switch (disabled by default): when enabled, a time picker "22:00 - 08:00" is displayed

Dimension	Description
App Side	🟢 Switch toggle → PUT /api/v1/users/{id}/notification-settings
Server Side	🟢 Store the user's notification preferences → check the user settings when sending pushes
Device Side	⚪ Not involved

Do-Not-Disturb Period Specifications:
- Disabled by default
- When enabled: 22:00 - 08:00 (the start and end times can be customized)
- During the do-not-disturb period: feeding reminders, device status reminders and low battery reminders are suspended
- Forced push exception: severe low food level alarms (<10%) and device error_code values of high severity are pushed forcibly even during the do-not-disturb period

14. Module 10: Device Network Configuration and Binding

Corresponding Page Name: Add device page (add-device-page / add-method-page / bluetooth-add-page / wifi-add-page)
Design Screenshot Description: Top navigation bar "➕ Add Device" + back button. The main body is the network configuration guide page: step indicator "① Select method ② Connect device ③ Complete binding". Below are two large card options: "📡 Bluetooth Add (Recommended)" + "📶 WiFi Add".

!image-20260423164854799

14.1 Module Overview

The process by which a user adds a new device to the App, supporting Bluetooth add (recommended) and WiFi add. Device network configuration is a key flow for first-time use.

14.2 Function 1: Add Method Selection

Function Description: Guide the user to choose Bluetooth add or WiFi add; the Bluetooth method is recommended.

Corresponding Design Elements:

Two parallel large cards: "📡 Bluetooth Add (Recommended)" + "📶 WiFi Add"
The Bluetooth card carries a "Recommended" tag (small green tag)
Tap a card to enter the corresponding network configuration flow

Dimension	Description
App Side	🟢 Display the two add method cards → detect the phone's Bluetooth status (guide the user to enable it if it is off) → after the user selects, enter the corresponding flow
Server Side	⚪ Not involved
Device Side	⚪ Not involved

14.3 Function 2: Bluetooth Add (Recommended)

Function Description: Search for nearby devices and connect through BLE (Bluetooth Low Energy) to complete device network configuration and account binding.

Corresponding Design Elements:

Step 1: Power on the device → description "Press and hold the device reset button for 3 seconds; a fast blue flashing indicator means it has entered network configuration mode"
Step 2: Search for devices → display the BLE scanning animation (circular diffusion effect) + the list of discovered devices (names such as "XSW-PF200-AB12")
Step 3: Connecting → display the progress "Connecting…" "Configuring network…" "Binding successful"
Completion page: device image + "Xiaobei's Feeder added successfully" + "Go to view" button

Dimension	Description
App Side	🟢 BLE scanning (filtering the device name prefix `XSW-PF200`) → the user taps to select a device → BLE connection → send the network configuration command → the device connects to WiFi and MQTT → the App and the device exchange authentication information → call the binding API
Server Side	🟢 Create the device binding record (device_id + user_id + family_id) → deliver the initial device configuration to MQTT
Device Side	🟢 Receive the network configuration command via BLE → connect to the specified WiFi (the SSID/password are delivered by the App via BLE) → connect to the cloud MQTT server → verify the pairing code → send the device authentication information

Device Indicator Status (Throughout Bluetooth Add):

Stage	Indicator Status	Duration
Factory status (not configured)	Slow blue flashing (2Hz)	Continuous
BLE connecting	Fast blue flashing (5Hz)	Until the BLE connection succeeds
WiFi connecting	Solid blue	Until the WiFi connection succeeds
MQTT connecting	Fast green flashing	Until the MQTT connection succeeds
Binding successful	Solid green	Turns off after 3 seconds
Binding failed	Flashes red 3 times	Then restores the factory status indicator

14.4 Function 3: WiFi Add

Function Description: Connect to a WiFi network through the device hotspot to complete network configuration and binding (an alternative when Bluetooth is unavailable).

Corresponding Design Elements:

Step 1: Power on the device → description "Press and hold the device reset button for 3 seconds; the indicator flashes blue quickly"
Step 2: Connect to the device hotspot → description "Connect to the XSW-PF200-XXXX hotspot in the phone's WiFi settings"
Step 3: Select WiFi → the App displays the phone's current WiFi list; the user selects the home WiFi and enters the password
Step 4: Configuring → progress bar "Configuring…"
Completion page: same as Bluetooth add

Dimension	Description
App Side	🟢 Guide the user to connect to the device hotspot (the App opens the system WiFi settings page) → obtain the WiFi SSID/password entered by the user → send them to the device hotspot via HTTP → after the device connects to the real WiFi it obtains an IP → the App detects that the device is online → binding API
Server Side	🟢 Same as Bluetooth add
Device Side	🟢 The device enables the hotspot (SoftAP) → receives the WiFi SSID/password delivered by the App via HTTP POST → switches to the target WiFi → connects to MQTT → binding

15. Module 11: Mine (Personal Center)

Corresponding Page Name: Mine page (profile-page / mine-page)
Design Screenshot Description: Top navigation bar "👤 Mine" or the user avatar + nickname area. The main body is a menu list: Message notifications / Family management / Account security / Clear cache / About us / Log out. The App version number is displayed at the bottom.

!image-20260423164929006

15.1 Module Overview

Display the user's personal information and provide entry points for auxiliary functions such as account security, notification settings, cache clearing and About.

15.2 Function 1: Personal Information Display

Function Description: Display the user avatar, nickname, mobile phone number (masked) and number of families.

Corresponding Design Elements:

User avatar (circular, can be tapped to edit)
Nickname (bold)
Mobile phone number displayed masked (138****1234)
Family count statistics ("Families ×2")

Dimension	Description
App Side	🟢 Request the user details API (GET /api/v1/users/me) → display personal information
Server Side	🟢 Return the complete user information (avatar URL, nickname, masked mobile phone number, family list)
Device Side	⚪ Not involved

15.3 Function 2: Account Security

Function Description: Change the password, bind WeChat, and set biometric login (see Module 1, 5.5 Account Security).

15.4 Function 3: Message Notification Settings

Function Description: Toggle various message notifications (see Module 9, 13.4 Message Settings).

15.5 Function 4: Clear Cache

Function Description: Clear the App's local cache (thumbnails, temporary files) with one tap.

Corresponding Design Elements:

Current cache size display (e.g. "Current cache 12.5MB")
"Clear Cache" button (after tapping, the clearing progress is displayed; after clearing completes, "0MB cleared" is displayed)

Dimension	Description
App Side	🟢 Detect the size of the local cache directory → the user taps Clear → delete the local thumbnail cache, temporary files and pending-retry files that failed to upload → display the size after clearing (usually 0MB or very small)
Server Side	⚪ Not involved
Device Side	⚪ Not involved

Clearing Scope:

Cache Type	Clearing Policy
Thumbnail cache	Clear the album thumbnail cache (re-downloaded when viewed next time)
Temporary files	Clear recording temporary files that failed to upload (those uploaded successfully are not retained)
Capture preview cache	Clear locally generated JPEG preview files (those uploaded successfully are not retained)
Login Token	Not cleared (the login state is retained)
Local device data	Not cleared (the device cache is retained for faster next startup)

15.6 Function 5: About Us

Function Description: Display the App version number, user agreement, privacy policy and customer service contact information.

Corresponding Design Elements:

App Logo + version number (v1.0.0 build 20260423)
User agreement link
Privacy policy link
Customer service email / phone number

15.7 Function 6: Log Out

Function Description: Clear the local login state and return to the login page.

Corresponding Design Elements: The "Log Out" button at the bottom (red text)

Dimension	Description
App Side	🟢 A confirmation dialog pops up "Log out?" → after confirmation, clear the local Token → jump to the login page
Server Side	🟢 Invalidate the current refresh_token (delete the key in Redis)
Device Side	⚪ Not involved

Appendix

A. Key Specifications Summary for Video Streams and Media Files

Item	Specification
Device stream push protocol	RTMP (rtmp://media.xswei.com/live/{device_id})
App stream pull protocol	HLS (.m3u8 + .ts segments, 4 seconds per segment, 8 segments cached)
Standard definition video bitrate	256k-1M (adaptive)
High definition video bitrate	512k-2M (adaptive)
Device encoding	H.264 Main Profile
Audio encoding	AAC-LC 32kbps mono
End-to-end video latency	≤3 seconds (standard definition) / ≤4 seconds (high definition)
Captured image resolution	1280×960 JPEG, quality 70%
Captured image size	~200KB
Recording resolution	640×480 H.264 + AAC
Maximum recording duration	30 seconds
Recording file size	~5MB
Recording upload method	HTTPS multipart, segmented upload, with resume support
User photo limit	50 photos (the oldest are automatically deleted when exceeded)
User video limit	5 clips (the oldest are automatically deleted when exceeded)
Photo retention period	7 days
Video retention period	3 days

B. MQTT Topic Specifications

Topic Pattern	Direction	Description
`device/{device_id}/status`	Device → Server	Periodic device status report (every 30 seconds)
`device/{device_id}/feed`	Server → Device	Manual feeding command
`device/{device_id}/feed/result`	Device → Server	Feeding result report
`device/{device_id}/feed/batch-report`	Device → Server	Batch feeding record report during the offline period
`device/{device_id}/plan/update`	Server → Device	Deliver the feeding plan list (full)
`device/{device_id}/plan/delete`	Server → Device	Delete a feeding plan
`device/{device_id}/config`	Server → Device	Deliver device configuration updates
`device/{device_id}/ota`	Server → Device	OTA firmware upgrade command
`device/{device_id}/unbind`	Server → Device	Unbind notification

C. Error Code Overview

Error Code	Description	App Handling
ERR_PHONE_INVALID	Incorrect mobile phone number format	Red prompt in the input box
ERR_PHONE_NOT_REGISTERED	This mobile phone number is not registered	Toast prompt "Please register an account first"
ERR_CODE_INVALID	Incorrect verification code	The input box shakes, with a prompt of N remaining attempts
ERR_CODE_EXPIRED	The verification code has expired	Toast prompt "The verification code has expired, please obtain a new one"
ERR_CODE_LOCKED	Operation too frequent, please try again in 15 minutes	Full-screen overlay showing a countdown
ERR_NETWORK	Network error	Toast prompt "Network abnormal, please check the network"
ERR_DEVICE_OFFLINE	Device offline	Toast prompt "Device offline, please check the network"
ERR_DEVICE_NO_RESPONSE	Device not responding	Toast prompt "Device not responding, please check the network"
ERR_LOW_FOOD	Insufficient food remaining	Pop up a confirmation prompt "Insufficient food remaining, continue?"
ERR_PLAN_LIMIT	The number of plans has reached the limit	Toast prompt "A maximum of 20 plans can be created"
ERR_NO_PERMISSION	No operation permission	Toast prompt "You do not have permission to perform this operation"

← Data Storage & Device Stat Docs Center DevicePlay Voice →

Didn't find what you need?Contact us，Talk to our engineers directly.

Detailed App Feature Design Doc

XSTRIVE Smart Pet Feeder App

Detailed Function Design Document

Table of Contents

1. Document Description

1.1 Purpose

1.2 Scope of Application

1.3 Reading Instructions

1.4 Design Draft Screenshot Index Description

2. Role Description and Abbreviations

2.1 System Roles

2.2 Device Model Specifications

2.3 Device Status Definition

2.4 Abbreviations

3. Data Storage Specification

3.1 User Data Storage

3.1.1 Photo Storage

3.1.2 Video Storage

3.1.3 Device Status Data Structure

3.1.4 Feeding Record Storage

3.1.5 Family Data Storage

4. Function Module Overview

5. Module 1: Authentication and Account

5.1 Module Overview

5.2 Function 1: Verification Code Login

5.3 Function 2: Password Login

5.4 Function 3: Registration

5.5 Function 4: Account Security

6. Module 2: Home Page and Device Overview

6.1 Module Overview

6.2 Function 1: Home Page Device Card

6.3 Function 2: Manual Feeding (Shortcut Operation)

6.4 Function 3: Family Switching

7. Module 3: Device Details and Real-Time Monitoring

7.1 Module Overview

7.2 Function 1: Real-Time Monitoring Video Stream

7.3 Function 2: Capturing Photos

7.4 Function 3: Recording

7.5 Function 4: Two-Way Voice Intercom

7.6 Function 5: Full Screen Mode

7.7 Function 6: Remaining Food Statistics and Today's Feeding Statistics

8. Module 4: Album (Capture and Recording)

8.1 Module Overview

8.2 Function 1: Album List Display

8.3 Function 2: Photo Preview and Deletion

8.4 Function 3: Video Preview and Deletion

8.5 Function 4: Share

8.6 Storage Specification Summary (Album Module)

9. Module 5: Scheduled Feeding Plan

9.1 Module Overview

9.2 Function 1: Plan List

9.3 Function 2: Create a Plan

9.4 Function 3: Edit/Delete a Plan

9.5 Function 4: Plan Toggle (Member Permission)

9.6 Function 5: Scheduled Execution on the Device Side

10. Module 6: Pet Management

10.1 Module Overview

10.2 Function 1: Pet List

10.3 Function 2: Add a Pet

10.4 Function 3: Edit a Pet

10.5 Function 4: Delete a Pet

10.6 Function 5: Pet Feeding Records

11. Module 7: Device Settings

11.1 Module Overview

11.2 Function 1: Basic Settings

11.3 Function 2: Feeding Settings

11.4 Function 3: Camera Settings

11.5 Function 4: Voice Settings

11.6 Function 5: Device Information Display

11.7 Function 6: Firmware Upgrade (OTA)

11.8 Function 7: Unbind

12. Module 8: Family Management

12.1 Module Overview

12.2 Function 1: Create/Edit a Family

12.3 Function 2: Invite Members

12.4 Function 3: Remove Members

13. Module 9: Message Center

13.1 Module Overview

13.2 Function 1: Message List

13.3 Function 2: Message Push Trigger