# Project Context

## Purpose

This project is a Uni-app based agent and enterprise management frontend for IoT assets. It provides asset list, asset search/detail, package display, commission, withdrawal, and related operational pages for two user roles: agent accounts and enterprise accounts.

## Tech Stack

- TypeScript
- Vue 3 with `<script setup>`
- Uni-app
- Vite
- UnoCSS
- Pinia
- uview-plus

## Project Conventions

### Code Style

- Use Composition API and `<script setup lang="ts">`.
- Keep API types close to the request layer in `src/api/*.ts`.
- Prefer small, direct page-level logic over premature abstraction.
- Existing pages use UnoCSS utility classes heavily; UI changes should preserve the current visual language.
- User-facing copy is primarily Chinese.

### Architecture Patterns

- Business pages live under `src/pages/agent-system/`.
- Backend calls are wrapped in `src/api/*.ts`.
- Shared formatting helpers live in `src/utils/format` and nearby page helpers.
- Asset pages distinguish between two primary resource types: `card` (IoT card) and `device`.

### Testing Strategy

- Run targeted validation with `pnpm type-check`, lint, and manual page checks when implementation begins.
- For spec work, validate proposals with `openspec validate --strict`.
- User-visible asset changes should be verified on both card and device flows.

### Git Workflow

- The repository may contain unrelated user changes; do not revert them.
- Use OpenSpec change proposals for user-visible feature changes before implementation.
- Keep proposals focused and capability-scoped.

## Domain Context

- Assets are mainly IoT cards and devices.
- Asset identifiers may be ICCID or VirtualNo depending on the resource and entry point.
- Agent-side pages currently include:
  - asset list: `src/pages/agent-system/assets/index.vue`
  - asset search/detail: `src/pages/agent-system/asset-search/index.vue`
  - secondary asset detail page: `src/pages/agent-system/asset-detail/index.vue`
- Package display and realtime status are important parts of the asset detail experience.

## Important Constraints

- Agent and enterprise views are not identical; requirements in one role should not be assumed to apply globally.
- Existing backend contracts are documented partly in `docs/*.md` and partly in the TypeScript API layer.
- UI changes should preserve current behavior unless the proposal explicitly changes it.
- Search semantics, display labels, and field visibility are product requirements and must be documented precisely.

## External Dependencies

- Backend admin APIs under `/api/admin/...`
- Shop cascade API for hierarchical shop filtering
- Asset resolve, realtime status, current package, and package list APIs
- Uni-app runtime and uview-plus components