windy10v10ai-firebase

English | 简体中文

Backend for Windy 10v10ai with Firebase

License

Licensed under the GNU GPL v3 (LICENSE), with a Steam/Workshop distribution exception and notes on prior MIT releases in LICENSE.EXCEPTIONS.md.

• License
• Built With
• Get Start
  • Installation
  • Agent skills
  • Running the app
  • Local end points
• Maintenance
  • Deploy
  • Backup Firestore
  • Update dependencies
• Admin API
  • Need
  • CLI
  • Postman

Built With

• Firebase
  • Hosting
  • Functions
  • Firestore Database
• NextJS

Get Start

Installation

Need

• Java
• Node v24
  • Recommend install node use nvm

# set/update node version (Linux / macOS, nvm-sh reads .nvmrc)
nvm install
nvm use
nvm alias default $(cat .nvmrc)

# set/update node version (Windows, nvm-windows needs explicit version)
nvm install $(Get-Content .nvmrc)
nvm use $(Get-Content .nvmrc)

# firebase setting
npm install -g firebase-tools
firebase login
firebase use windy10v10ai

# setup package
npm install

Agent skills

Task instructions for AI agents live in .claude/skills. Claude Code reads them directly; Codex and DSH read project skills from .agents/skills, so run npm run skills:link once per checkout to create that link (a junction on Windows, a symlink elsewhere — it is not committed). npm run skills:check validates skill frontmatter.

Set GCP

# Setup gcloud authentication (need to do first time)
gcloud auth login
gcloud config set project windy10v10ai

Running the app

Download DB data

# download data from storage
rm -rf firestore-backup
mkdir firestore-backup
gcloud storage cp -r "gs://windy10v10ai.appspot.com/firestore-backup/20260823/*" firestore-backup

Start Firebase Emulator & API & Web

npm run start

API only

# REPL
(cd api && npm run start -- --entryFile repl)

# unit tests
(cd api && npm run test)

# e2e tests (need stop firebase emulator)
(cd api && npm run test:e2e)

Tips: If debug or e2e test not working with address already used error, kill nodejs process by pkill -f node, or try to restart winnat

net stop winnat
net start winnat

Local end points

• Firebase Hosting: http://localhost:5000/api/
• Function (Not used): http://localhost:5001/windy10v10ai/asia-northeast1/client/api/
• Firebase Emulator: http://localhost:4000/
• Debug end points: http://localhost:3001/api/
• OpenAPI Document (Swagger): http://localhost:3001/api-doc
• Nextjs Web: http://localhost:3000/

Alipay sandbox

Start ngrok: ngrok http 5000

Replace ALIPAY_XXX in .env.local.

API Architecture

Entry domains, outbound dependencies, routing and auth: see API Architecture.

Maintenance

Deploy

Deploy with Github Action

Github Action will deploy functions, hosting and firestore automatically when push to main branch.

A push is skipped entirely when every changed file sits in a path that cannot affect the Firebase deploy — web/**, docs/**, .claude/**, .cursor/**, .vscode/** and any *.md. The list lives in paths-ignore of deploy_firebase.yml.

Deploy with Firebase App Hosting

The Next.js site under web/ is built and rolled out by App Hosting itself, not by any workflow in this repository. Backend prod tracks main, dev tracks develop, and both use web as their root directory.

The current App Hosting backends have no versioned runtime selected (Not Specified). App Hosting therefore uses the versionless nodejs runtime, and the Node.js buildpack selects Node 24 from web/package.json's engines.node on the next rollout. No console change is needed for this upgrade while both backends remain Not Specified. After merging into develop, check the dev build log for Node 24 and verify the rollout before promoting to main; then check the prod rollout. If a backend is later pinned to a versioned runtime, set it to nodejs24 before deploying code that requires Node 24. Not Specified disables automatic base image updates (ABIU).

Both skip a push whose changes all fall outside the site. The path list is not stored in this repository — it belongs to the backend's rollout policy, so change it in Firebase console → App Hosting → the backend → deployment settings → ignored paths:

api/**,.github/**,docs/**,.claude/**,.cursor/**,.vscode/**,**.md

Instance limits do live here: web/apphosting.yaml, overridden for dev by web/apphosting.dev.yaml.

Deploy Manually

• Deploy all

firebase deploy

• Deploy part

# Deploy specific function
firebase deploy --only functions:client
firebase deploy --only functions:admin
firebase deploy --only functions:scheduledOrderCheck
# Deploy all function
firebase deploy --only functions

# Deploy hosting only
firebase deploy --only hosting
# Deploy function and hosting
firebase deploy --only functions,hosting

Set secret environment variables

1. Create env in secret manager
2. Set function run with secrets in index.ts
3. Use secrets as process.env.SECRET_NAME in code

Allow/Disable unauthenticated HTTP function invocation

https://cloud.google.com/functions/docs/securing/managing-access-iam#allowing_unauthenticated_http_function_invocation

Backup Firestore

https://console.cloud.google.com/firestore/databases/-default-/import-export?project=windy10v10ai

Update dependencies

• Update package.json

# install tool
`npm install -g npm-check-updates`

# cd to dir
cd api
# update package.json
ncu -u
# update package-lock.json
npm update

Use Admin API

Need

• gcloud cli

CLI

curl -H "Authorization: bearer $(gcloud auth print-identity-token)" https://asia-northeast1-windy10v10ai.cloudfunctions.net/admin/api

Postman

## Get token
echo $(gcloud auth print-identity-token)

Import api/swagger-spec.yaml to postman with variable baseUrl : https://asia-northeast1-windy10v10ai.cloudfunctions.net/admin