miniprogram-architecture-kit

name	miniprogram-architecture-kit
description	当你要从零开始创建一个微信小程序项目，或为新的小程序仓库搭建一套可长期维护的标准前后端结构、配置约定和部署方案时，使用这个 skill。

Miniprogram Architecture Kit

Use this skill to scaffold or implement a reusable default architecture for new WeChat mini-program projects.

Default Stack

Unless the user explicitly asks for a different stack, use these defaults:

• Frontend: uni-app + Vue 3 + TypeScript
• Backend: Go + Gin
• Data access: Gorm
• Database: MySQL
• Auth: WeChat login + backend-issued JWT
• Object storage: local storage for development, OSS-compatible object storage for production when needed
• Local startup: docker-compose.yml for infrastructure and backend, frontend started or built separately
• Production deployment: git -> GitHub Actions -> Aliyun ACR -> Aliyun ECS -> Nginx

Repository Shape

When bootstrapping a new project, prefer this top-level layout:

• frontend/
• backend/
• .env.example
• .env.prod.example
• docker-compose.yml
• docker-compose-prod.yml
• 运行教程.md
• Linux部署文档_AL3.md

These two docs are mandatory deliverables, not optional extras:

• 运行教程.md
• Linux部署文档_AL3.md

Frontend Standard

• Treat the frontend as a mini-program-first client, not a generic web SPA.
• Prefer this structure:
  • src/pages/ for route pages
  • src/components/ for reusable UI blocks
  • src/utils/ for request, compression, and shared helpers
  • src/config/ for environment-derived constants
• Keep pages.json authoritative for routing.
• Centralize HTTP, auth token handling, retry, and login behavior in a shared request utility.
• Keep page files focused on user interaction and view state, not low-level request plumbing.
• If image upload is part of the product, include client-side compression and mini-program domain error handling from the start.

Backend Standard

• Treat cmd/api/main.go as the backend composition root.
• Prefer this layering:
  • internal/handlers/ for HTTP binding, auth context reading, and response mapping
  • internal/services/ for business logic and third-party integration
  • internal/models/ for persistence schema
  • internal/middleware/ for auth, rate limiting, and other cross-cutting concerns
  • internal/database/ for DB connection bootstrap
  • internal/utils/ for small shared helpers that are not business logic
• Keep configuration centralized in a config package and loaded from YAML plus environment overrides.
• Keep public unauthenticated routes minimal, typically health checks and login endpoints.
• Put business APIs behind /api and auth middleware by default.
• Return stable machine-readable error codes so the frontend can map them to user-facing text.

Data And Config Standard

• Use Gorm models as the single source of truth for schema when following the default stack.
• Prefer keeping schema changes and code changes in the same task.
• Define all required environment variables in:
  • .env.example
  • .env.prod.example
  • backend config examples when present
• Keep secrets out of committed real config files.
• Make development and production variables similar in naming so switching environments is predictable.

Deployment Standard

• Local development:
  • docker-compose.yml should bring up mysql and backend
  • frontend can run independently with its own dev or build command
• Production:
  • build backend image in GitHub Actions
  • push the image to Aliyun ACR
  • pull and run on ECS with docker-compose-prod.yml
  • use Nginx for domain access, HTTPS, and reverse proxy
• Default GitHub Actions trigger mode is workflow_dispatch.
• Default image tags are:
  • latest
  • sha-<short_commit>
• Prefer keeping MySQL outside the production compose stack unless the user explicitly wants a single-host all-in-one deployment.

Read references/default-release-pipeline.md when you need the exact default release flow or release doc coverage.

Documentation Output Contract

Whenever this skill creates a new project, it must also generate:

• 运行教程.md
• Linux部署文档_AL3.md

Do not treat deployment documentation as optional. It is part of the standard project deliverable.

When generating those docs:

• Use the templates in assets/templates/ as the default base
• Replace all project-specific placeholders before finalizing
• Keep file names exactly as listed above unless the user explicitly asks for different names
• Make sure the run guide and deployment guide match the actual repo structure and env variables

Read references/project-doc-generation-rules.md before writing or adapting the final docs.

Build Workflow

When creating a new project with this skill, the implementation should usually follow this order:

1. scaffold repo structure
2. create backend config loader and API entrypoint
3. create database connection and models
4. create auth, upload, and core business handlers/services
5. create frontend pages, shared request utility, and config
6. add local compose files and env templates
7. generate 运行教程.md and Linux部署文档_AL3.md
8. verify the end-to-end flow locally

Guardrails

• Do not default to Taro, Next.js, NestJS, serverless, or microservices unless the user asks for them.
• Do not split frontend and backend into multiple repos unless explicitly requested.
• Do not bypass shared request and auth utilities with page-local ad hoc calls.
• Do not introduce extra infrastructure such as Redis, MQ, or workflow engines unless there is a clear product need.
• Do not leave deployment undocumented.
• Do not finish a new project without both required docs being generated.

When To Flex

Adjust the default kit only when the user clearly asks for:

• a different frontend framework
• a different backend stack
• serverless architecture
• managed cloud deployment instead of server-based deployment
• separate admin portal or additional clients
• multi-tenant or multi-service architecture
• a different cloud vendor or operating system baseline

Default Decision

If the user asks to create a new mini-program project and does not specify otherwise, implement it as a standard monorepo with the stack, layering, document outputs, and deployment flow defined above.