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:

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

App Instance (Required)

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

// ✅ 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()