windy10v10ai-cloud

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.
本项目采用 GNU GPL v3 协议（见 LICENSE），并附带 Steam/创意工坊 分发例外，相关说明及此前 MIT 版本的处理见 LICENSE.EXCEPTIONS.md。

• License
• Built With
• Get Start
  • Installation
  • 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 v22
  • 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

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.

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

Extension

Export Firestore to Bigquery

Setup Stream Firestore to BigQuery

firebase ext:install firebase/firestore-bigquery-export

or Edit firebase.json and create extensions/firestore-bigquery-export-xxx.env

  "extensions": {
    "firestore-bigquery-export-xxx": "firebase/firestore-bigquery-export@0.1.54"
  }

Deploy Firestore to BigQuery

firebase deploy --only extensions

Import existing documents (need gcp auth)

Guides

Setup gcloud default auth

gcloud auth application-default login

Run import command

sh ./extensions/import-firestore-to-bigquery.sh

Generate schema views

Create schema file table_name_schema.json and run command.

How to create schema file

sh ./extensions/generate-schema-views.sh