zyt/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

Multi-client SaaS platform (基于 likeadmin 脚手架改造) centered on 中医在线问诊 — video consultations (TRTC), prescriptions, medicine library, 企微 (QYWX) integration, and payments. Single repo contains a PHP backend plus four independent frontend clients.

Top-Level Layout

Dir	Stack	Purpose
server/	ThinkPHP 8 + PHP 8.0+	REST API, the single source of truth
admin/	Vue 3 + Vite + Element Plus + Tailwind	管理后台 (desktop)
pc/	Nuxt 3 + Element Plus	公开 PC 站 (SSR/SSG)
uniapp/	uni-app (Vue 3, Vite)	H5 / 小程序 / App 多端客户端
wx/	uni-app 微信小程序	独立 TRTC 微信小程序壳
TUICallKit*/	Tencent TRTC UIKit	Vendor SDK source used by clients
docker/	docker-compose (nginx + php-fpm + mysql)	Local dev stack
doc/, ps/	Supporting docs / psd	Design & reference material

Each frontend is deployed to server/public/<client>/ (see server/route/app.php fallback routes). Don’t rely on a root-level workspace — each client has its own package.json and must be built separately.

Common Commands

Backend (server/)

composer install                                  # install deps
php think run --host 0.0.0.0 --port 8080          # dev server (if PHP CLI)
php think <command>                                # run CLI commands (see app/command/)
php think crontab                                  # trigger cron tasks manually

• Docker alternative: cd docker && docker-compose up -d (exposes nginx on :80, mysql on :3306).
• SQL migrations live in server/sql/<version>/*.sql (versioned by date). Apply manually in order; there is no automatic migration runner. Current version directory: server/sql/1.9.20260420/.

Admin (admin/)

npm install
npm run dev          # Vite dev server
npm run build        # production build + node scripts/release.mjs
npm run type-check   # vue-tsc --noEmit
npm run lint         # ESLint with --fix
npm run clean        # node scripts/clean.mjs

PC (pc/)

npm install
npm run dev          # Nuxt dev server on :3000
npm run build        # nuxt generate + scripts/build.mjs (static export)
npm run build:ssr    # Nuxt SSR build

uniapp (uniapp/)

npm install
npm run dev:h5               # H5
npm run dev:mp-weixin        # 微信小程序
npm run dev:app              # App
npm run build:h5             # build + scripts/release.mjs
# other targets: mp-alipay, mp-baidu, mp-qq, mp-toutiao, quickapp-webview...
npm run lint

Running a single test

There is no unit-test harness checked in (no Jest/Vitest/PHPUnit config). When adding tests, wire the framework first; don’t assume one exists.

Backend Architecture (likeadmin conventions)

server/app/ is a ThinkPHP multi-app project. Three apps with a shared common/ layer:

• adminapi/ — admin panel API (consumed by admin/)
• api/ — public/end-user API (consumed by pc/, uniapp/, wx/)
• index/ — default app fallback
• common/ — shared models, services, enums, exceptions, listeners

Each app follows the layered pattern:

<app>/
├── controller/   # HTTP entry; extends BaseAdminController / BaseApiController
├── logic/        # Business logic; static methods invoked by controllers
├── lists/        # List-query objects (pagination/filter/export encapsulation)
├── validate/     # Request validation rules
├── service/      # App-scoped services
├── http/         # Middleware, route groups
└── config/       # App-specific config

Key conventions:

• Controllers stay thin. They pull $this->request->get()/post(), delegate to a Logic class, and wrap the result with $this->data(...) / $this->success(...) / $this->fail(...) from BaseLikeAdminController (in common/controller).
• Logic returns plain arrays. Throw \app\common\exception\* for failures — the global exception handler (app/ExceptionHandle.php) converts them to JSON envelopes.
• Models extend app\common\model\BaseModel which auto-completes image paths via FileService.
• Route registration is menu-driven. Admin routes are auto-resolved from menu entries (see add_conversion_stats_menu.sql as an example of wiring a new admin page). Public routes are declared in app/api/route/ and server/route/app.php.
• Payment / third-party callbacks bypass auth — declared explicitly in server/route/app.php (e.g. wechat-notify, alipay-notify, TRTC recording-notify).

Admin Architecture (admin/src/)

src/
├── api/                # One file per domain (stats.ts, order.ts, doctor.ts...)
├── views/              # Page components grouped by domain (mirrors api/)
├── router/
│   ├── index.ts        # Dynamic route generation from backend menu
│   └── routes.ts       # Static/constant routes + LAYOUT wrapper
├── stores/modules/     # Pinia stores (user, app, tagsView...)
├── components/         # Shared components
├── utils/request/      # Axios instance + interceptors
├── hooks/              # Composables
├── install/            # Global plugin registration (app.use(install))
└── permission.ts       # Login/permission guard mounted on router

• Views are dynamically loaded via import.meta.glob('/src/views/**/*.vue') in router/index.ts. A view path from the backend menu (e.g. stats/conversion/index) resolves to src/views/stats/conversion/index.vue. When adding a page, the corresponding menu record must be inserted via SQL (pattern: server/sql/.../add_*_menu.sql).
• API calls go through utils/request which normalizes the response envelope and handles auth/error toasts. Don’t use axios directly.
• Auto-imports: Element Plus components, ref/reactive/router composables are auto-imported via unplugin-auto-import — no need to import them explicitly (see auto-imports.d.ts).

Cross-Cutting Concerns

• Versioned SQL migrations. New schema/menu changes go in server/sql/<version>/*.sql. When adding an admin view, pair it with an add_*_menu.sql file (see current WIP: add_conversion_stats_menu.sql + admin/src/views/stats/conversion/).
• TRTC integration. Video-call logic is split between TUICallKit/ (vendor), admin/src/utils/call-*.ts and src/utils/im-*.ts, and the api/controller/TrtcController. Cloud recording is triggered server-side and written back via the /api/trtc/recording-notify callback.
• 企微 (QYWX). server/app/adminapi/controller/qywx/ + admin/src/views/qywx/ + pc/ pages exchange via easywechat. OAuth/bind flow uses admin/src/utils/wecomOauthPostMessage.ts and wecomBindGuard.ts.
• Multi-cloud storage. File uploads support Qiniu / Tencent COS / Aliyun OSS — configuration is driven by runtime admin settings, resolved in FileService.

Trellis Workflow

This repo is Trellis-managed (see .trellis/). New work should go through:

1. /trellis:start — loads session context
2. /trellis:brainstorm for complex/vague asks (creates prd.md)
3. Research → task.py init-context → Implement → Check agents
4. /trellis:finish-work before committing

Code-spec files under .trellis/spec/ are injected into sub-agent contexts automatically. Relevant thinking guides live in .trellis/spec/guides/.

Language & Docs

All user-facing commentary, commit messages, and code comments in this repo use 简体中文 when addressing the product domain; identifiers, API paths, and this file stay in English. The backend still carries original likeadmin attribution headers — do not remove them on edit.