xinda-miniprogram/AGENTS.md

# AGENTS.md - 信达小程序 (Xinda Mini Program)

WeChat Mini Program for thyroid eye disease patient management. Dual-mode app serving both patients (患者端) and doctors (医生端).

## Project Type

- **Framework**: WeChat Mini Program v3.7.7
- **Language**: TypeScript (strict mode)
- **Styling**: SCSS/Sass via `useCompilerPlugins`
- **UI Library**: Vant Weapp (@vant/weapp)
- **Renderer**: Skyline enabled
- **App ID**: `wxf9ce8010f1ad24aa` (dev), `wx71ac9c27c3c3e3f4` (prod)

## Directory Structure

```
src/
├── pages/              # Doctor-side main pages (医生端)
├── patient/pages/      # Patient-side pages (subpackage)
├── gift/pages/         # DTP pharmacy pages (subpackage)
├── doc/pages/          # Privacy/terms documentation (subpackage)
├── components/         # Shared components
├── utils/              # Request, page/component wrappers, utilities
├── app.ts              # App entry with global data
└── config.ts           # Environment configs per appId
```

## Key Conventions

### Path Aliases

- `@/*` → `src/*` (configured in tsconfig.json and app.json `resolveAlias`)
- Use `@/utils/request` not relative paths

### User Types & Routing

Login types enforced in `app.ts`:

- `0`: Not logged in
- `1`: Patient (患者) → routes to `/patient/pages/*`
- `2`: Doctor (医生) → routes to `/pages/*`

Use `app.zdWaitLogin()` to guard pages that require login.

### Page/Component Wrappers

`app.ts` overrides global `Page` and `Component` with wrappers from `utils/page.ts` and `utils/component.ts`:

- Auto-sets `imageUrl` and `Timestamp` on page load
- Auto-handles navbar background on scroll
- Provides default share behavior

### Modal Colors (Required)

All `wx.showModal` must use:

```ts
wx.showModal({
  confirmColor: '#8c75d0',
  cancelColor: '#141515',
})
```

### App Instance (Required)

`getApp()` should be called at the top of the file, not inside methods:

````ts
// ✅ Correct
const app = getApp<IAppOption>()

Page({
  onLoad() {
    // Use app directly
    console.log(app.globalData)
  }
})

// ❌ Incorrect
Page({
  onLoad() {
    const app = getApp<IAppOption>()
    console.log(app.globalData)
  }
})```

## Available Commands

```bash
# Lint and auto-fix (only command available)
npm run lint:fix

# Install dependencies (pnpm preferred based on lockfile)
pnpm install

# Build: Use WeChat Developer Tools
# - Import project with src/ as root
# - project.config.json at repo root
````

## NPM Dependencies

**Critical**: After `npm install`, run **Tools → Build npm** in WeChat Developer Tools to generate `miniprogram_npm/`. This is required for Vant and other packages.

Key dependencies:

- `@vant/weapp`: UI components
- `miniprogram-licia`: Utility library (available as `licia`)
- `dayjs`: Date handling
- `mp-html`: Rich HTML rendering

## Images & Assets

**Images are stored in SVN, not git.**

- SVN URL: `svn://39.106.86.127:28386/projects/xd/proj_src/shop/frontend/web/xd/`
- Local path: `src/images/` (gitignored)
- Excluded from upload via `project.config.json` packOptions
- Only `/images/tabbar/*` is included in uploads

Image URL pattern:

```
{{imageUrl}}/path/to/image.png?t={{Timestamp}}
```

## TypeScript Configuration

- Strict mode enabled
- `noImplicitAny: false` (allows implicit any)
- Paths: `@/*` mapped to `src/*`
- Types: `miniprogram-api-typings` for WX API

Global types in `typings/index.d.ts`:

- `IAppOption`: Global app instance interface
- `pageType`: 0 | 1 | 2 for user types
- `wx.ajax`: Extended request method

## ESLint & Formatting

- Config: `@antfu/eslint-config` (flat config in `eslint.config.js`)
- Prettier: 2-space tabs, no semis, single quotes, trailing commas
- WXML files parsed as HTML, WXSS as CSS
- Globals defined: `wx`, `App`, `Page`, `Component`, `getCurrentPages`, etc.

## Environment Configuration

Selected by App ID in `src/config.ts`:

- `wxf9ce8010f1ad24aa`: Dev/Staging (hbraas.com)
- `wx71ac9c27c3c3e3f4`: Production (hbsaas.com)

App reads `wx.getAccountInfoSync().miniProgram.appId` on launch to select config.

## Testing & Development

- No unit test framework configured
- Manual testing via WeChat Developer Tools
- `project.private.config.json` has hot reload enabled (`compileHotReLoad: true`)
- Predefined test pages in `project.private.config.json` condition list

## Common Gotchas

1. **NPM packages**: Must run "Build npm" in WeChat tools after install
2. **Images**: Will 404 if SVN images not checked out to `src/images/`
3. **Subpackages**: Patient pages are in `patient/` subpackage, not main package
4. **Skyline**: Enabled in rendererOptions, some components may behave differently
5. **Login flow**: App automatically calls `startLogin()` on launch; pages must wait via `app.zdWaitLogin()`