Merge pull request #1097 from Ethan0x0000/pr/upstream-model-tracking

feat(usage): 新增 upstream_model 追踪，支持按模型来源统计与展示

backend/migrations/075_add_usage_log_upstream_model.sql

@@ -0,0 +1,4 @@
+-- Add upstream_model field to usage_logs.
+-- Stores the actual upstream model name when it differs from the requested model
+-- (i.e., when model mapping is applied). NULL means no mapping was applied.
+ALTER TABLE usage_logs ADD COLUMN IF NOT EXISTS upstream_model VARCHAR(100);

backend/migrations/076_add_usage_log_upstream_model_index_notx.sql

@@ -0,0 +1,3 @@
+-- Support upstream_model / mapping model distribution aggregations with time-range filters.
+CREATE INDEX CONCURRENTLY IF NOT EXISTS idx_usage_logs_created_model_upstream_model
+ON usage_logs (created_at, model, upstream_model);

backend/migrations/README.md

@@ -34,18 +34,18 @@ Example: `017_add_gemini_tier_id.sql`
 
 ## Migration File Structure
 
-```sql
--- +goose Up
--- +goose StatementBegin
--- Your forward migration SQL here
--- +goose StatementEnd
+This project uses a custom migration runner (`internal/repository/migrations_runner.go`) that executes the full SQL file content as-is.
 
--- +goose Down
--- +goose StatementBegin
--- Your rollback migration SQL here
--- +goose StatementEnd
+- Regular migrations (`*.sql`): executed in a transaction.
+- Non-transactional migrations (`*_notx.sql`): split by statement and executed without transaction (for `CONCURRENTLY`).
+
+```sql
+-- Forward-only migration (recommended)
+ALTER TABLE usage_logs ADD COLUMN IF NOT EXISTS example_column VARCHAR(100);
 ```
 
+> ⚠️ Do **not** place executable "Down" SQL in the same file. The runner does not parse goose Up/Down sections and will execute all SQL statements in the file.
+
 ## Important Rules
 
 ### ⚠️ Immutability Principle
@@ -66,9 +66,9 @@ Why?
    touch migrations/018_your_change.sql
    ```
 
-2. **Write Up and Down migrations**
-   - Up: Apply the change
-   - Down: Revert the change (should be symmetric with Up)
+2. **Write forward-only migration SQL**
+   - Put only the intended schema change in the file
+   - If rollback is needed, create a new migration file to revert
 
 3. **Test locally**
    ```bash
@@ -144,8 +144,6 @@ touch migrations/018_your_new_change.sql
 ## Example Migration
 
 ```sql
--- +goose Up
--- +goose StatementBegin
 -- Add tier_id field to Gemini OAuth accounts for quota tracking
 UPDATE accounts
 SET credentials = jsonb_set(
@@ -157,17 +155,6 @@ SET credentials = jsonb_set(
 WHERE platform = 'gemini'
   AND type = 'oauth'
   AND credentials->>'tier_id' IS NULL;
--- +goose StatementEnd
-
--- +goose Down
--- +goose StatementBegin
--- Remove tier_id field
-UPDATE accounts
-SET credentials = credentials - 'tier_id'
-WHERE platform = 'gemini'
-  AND type = 'oauth'
-  AND credentials->>'tier_id' = 'LEGACY';
--- +goose StatementEnd
 ```
 
 ## Troubleshooting
@@ -194,5 +181,4 @@ VALUES ('NNN_migration.sql', 'calculated_checksum', NOW());
 ## References
 
 - Migration runner: `internal/repository/migrations_runner.go`
-- Goose syntax: https://github.com/pressly/goose
 - PostgreSQL docs: https://www.postgresql.org/docs/