add implementation plans for artifacts, character series, weapon series
🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
parent
b8947dbaf3
commit
ef7c158736
3 changed files with 1089 additions and 0 deletions
597
docs/plans/artifacts-implementation-plan.md
Normal file
597
docs/plans/artifacts-implementation-plan.md
Normal file
|
|
@ -0,0 +1,597 @@
|
|||
# Artifacts Implementation Plan
|
||||
|
||||
## Overview
|
||||
|
||||
This document outlines the implementation plan for adding Artifacts to the hensei-api. Artifacts are equipment items that can be attached to characters, providing four skill bonuses. They have element and proficiency requirements that must match the equipped character.
|
||||
|
||||
## Key Design Decisions
|
||||
|
||||
Based on requirements discussion:
|
||||
|
||||
1. **Skill definitions**: Hardcoded in model constants (similar to rings)
|
||||
2. **Base entity**: Create `artifacts` table for the 30 standard + 5 quirk artifact types
|
||||
3. **User input**: Direct value input with validation against valid formulas
|
||||
4. **Collection model**: Multiple artifacts of same type allowed per user
|
||||
5. **Grid linkage**: GridArtifact belongs_to GridCharacter
|
||||
6. **Quirk skills**: Not stored in database - frontend handles display based on artifact name
|
||||
7. **Naming**: Add optional nickname field to collection_artifacts
|
||||
|
||||
---
|
||||
|
||||
## Data Model
|
||||
|
||||
### 1. `artifacts` Table (Base Entity)
|
||||
|
||||
Stores the 35 artifact types (30 standard + 5 quirk). This is static reference data.
|
||||
|
||||
```ruby
|
||||
create_table :artifacts, id: :uuid do |t|
|
||||
t.string :granblue_id, null: false # Game's internal ID
|
||||
t.string :name_en, null: false # English name
|
||||
t.string :name_jp # Japanese name
|
||||
t.integer :proficiency, null: false # 1-10 (sabre, dagger, spear, axe, staff, gun, melee, bow, harp, katana)
|
||||
t.integer :rarity, null: false # 0 = standard, 1 = quirk
|
||||
t.integer :style # 1-3 for standard artifacts (Ominous/Saint/Jinyao style)
|
||||
|
||||
# No timestamps - static reference data
|
||||
end
|
||||
|
||||
add_index :artifacts, :granblue_id, unique: true
|
||||
add_index :artifacts, :proficiency
|
||||
add_index :artifacts, :rarity
|
||||
```
|
||||
|
||||
**Notes:**
|
||||
- Standard artifacts have 3 styles per proficiency (30 total)
|
||||
- Quirk artifacts (5 total) have `rarity: 1` and `style: nil`
|
||||
- Images will be stored on CDN, derived from granblue_id
|
||||
|
||||
### 2. `collection_artifacts` Table
|
||||
|
||||
User's artifact inventory. Unlike other collection items, users can own multiple artifacts of the same type.
|
||||
|
||||
```ruby
|
||||
create_table :collection_artifacts, id: :uuid do |t|
|
||||
t.references :user, type: :uuid, null: false, foreign_key: true
|
||||
t.references :artifact, type: :uuid, null: false, foreign_key: true
|
||||
|
||||
# Artifact properties
|
||||
t.integer :element, null: false # 1-6 (fire, water, earth, wind, light, dark)
|
||||
t.integer :level, null: false, default: 1 # 1-5 for standard, always 1 for quirk
|
||||
t.string :nickname # Optional user label
|
||||
|
||||
# Skills (JSONB) - each contains: { modifier: int, strength: value, level: int }
|
||||
# For standard artifacts: modifier = skill ID, strength = level 1 base value, level = 1-5
|
||||
# For quirk artifacts: these are nil (skills are fixed and determined by artifact name)
|
||||
t.jsonb :skill1, default: {}, null: false # Group I skill
|
||||
t.jsonb :skill2, default: {}, null: false # Group I skill
|
||||
t.jsonb :skill3, default: {}, null: false # Group II skill
|
||||
t.jsonb :skill4, default: {}, null: false # Group III skill
|
||||
|
||||
t.timestamps
|
||||
end
|
||||
|
||||
add_index :collection_artifacts, :user_id
|
||||
add_index :collection_artifacts, [:user_id, :artifact_id]
|
||||
add_index :collection_artifacts, :element
|
||||
```
|
||||
|
||||
**Skill JSONB Structure:**
|
||||
```json
|
||||
{
|
||||
"modifier": 1, // Skill type ID within the group
|
||||
"strength": 1320, // Level 1 base value (one of 5 valid values per skill)
|
||||
"level": 3 // Skill level 1-5
|
||||
}
|
||||
```
|
||||
|
||||
**Constraint:** Sum of all 4 skill levels must equal (artifact_level + 3). At level 1, all skills are level 1 (sum=4). At level 5, skills sum to 8.
|
||||
|
||||
### 3. `grid_artifacts` Table
|
||||
|
||||
Artifacts equipped to characters within a party.
|
||||
|
||||
```ruby
|
||||
create_table :grid_artifacts, id: :uuid do |t|
|
||||
t.references :grid_character, type: :uuid, null: false, foreign_key: true
|
||||
t.references :artifact, type: :uuid, null: false, foreign_key: true
|
||||
|
||||
# Artifact properties (same as collection_artifacts)
|
||||
t.integer :element, null: false
|
||||
t.integer :level, null: false, default: 1
|
||||
|
||||
t.jsonb :skill1, default: {}, null: false
|
||||
t.jsonb :skill2, default: {}, null: false
|
||||
t.jsonb :skill3, default: {}, null: false
|
||||
t.jsonb :skill4, default: {}, null: false
|
||||
|
||||
t.timestamps
|
||||
end
|
||||
|
||||
add_index :grid_artifacts, :grid_character_id, unique: true # One artifact per character
|
||||
add_index :grid_artifacts, :artifact_id
|
||||
```
|
||||
|
||||
**Validation:** The artifact's element and proficiency must match the character's element and one of their proficiencies.
|
||||
|
||||
---
|
||||
|
||||
## Skill Groups Definition
|
||||
|
||||
Hardcoded in model as constants. Each skill has:
|
||||
- `name`: Display name
|
||||
- `base_values`: Array of 5 valid level 1 values
|
||||
- `growth`: Amount added per level
|
||||
- `value_type`: `:integer`, `:percent`, or `:percent_decimal` (for values like 0.5%)
|
||||
|
||||
### Group I Skills (Slots 1 & 2)
|
||||
|
||||
| ID | Name | Base Values | Growth | Type |
|
||||
|----|------|-------------|--------|------|
|
||||
| 1 | ATK | 1320, 1440, 1560, 1680, 1800 | +300 | integer |
|
||||
| 2 | HP | 660, 720, 780, 840, 900 | +150 | integer |
|
||||
| 3 | C.A. DMG | 13.2, 14.4, 15.6, 16.8, 18.0 | +3 | percent |
|
||||
| 4 | Skill DMG | 13.2, 14.4, 15.6, 16.8, 18.0 | +3 | percent |
|
||||
| 5 | Elemental ATK | 8.8, 9.6, 10.4, 11.2, 12.0 | +2 | percent |
|
||||
| 6 | Critical Hit Rate | 13.2, 14.4, 15.6, 16.8, 18.0 | +3 | percent |
|
||||
| 7 | Double Attack Rate | 6.6, 7.2, 7.8, 8.4, 9.0 | +1.5 | percent |
|
||||
| 8 | Triple Attack Rate | 4.4, 4.8, 5.2, 5.6, 6.0 | +1 | percent |
|
||||
| 9 | DEF | 8.8, 9.6, 10.4, 11.2, 12.0 | +2 | percent |
|
||||
| 10 | Superior Element Reduction | 4.4, 4.8, 5.2, 5.6, 6.0 | +1 | percent |
|
||||
| 11 | Dodge Rate | 4.4, 4.8, 5.2, 5.6, 6.0 | +1 | percent |
|
||||
| 12 | Healing | 13.2, 14.4, 15.6, 16.8, 18.0 | +3 | percent |
|
||||
| 13 | Debuff Success Rate | 6.6, 7.2, 7.8, 8.4, 9.0 | +1.5 | percent |
|
||||
| 14 | Debuff Resistance | 6.6, 7.2, 7.8, 8.4, 9.0 | +1.5 | percent |
|
||||
|
||||
### Group II Skills (Slot 3)
|
||||
|
||||
| ID | Name | Base Values | Growth | Type |
|
||||
|----|------|-------------|--------|------|
|
||||
| 1 | N.A. DMG Cap | 2.2, 2.4, 2.6, 2.8, 3.0 | +0.5 | percent |
|
||||
| 2 | Skill DMG Cap | 8.8, 9.6, 10.4, 11.2, 12.0 | +2 | percent |
|
||||
| 3 | C.A. DMG Cap | 6.6, 7.2, 7.8, 8.4, 9.0 | +1.5 | percent |
|
||||
| 4 | Special C.A. DMG Cap | 4.4, 4.8, 5.2, 5.6, 6.0 | +1 | percent |
|
||||
| 5 | Boost DMG cap for critical hits | 2.2, 2.4, 2.6, 2.8, 3.0 | +0.5 | percent |
|
||||
| 6 | N.A. DMG cap boost (80%/60% penalty) | 4.4, 4.8, 5.2, 5.6, 6.0 | +1 | percent |
|
||||
| 7 | Skill DMG cap boost (20%/60% penalty) | 17.6, 19.2, 20.8, 22.4, 24.0 | +4 | percent |
|
||||
| 8 | C.A. DMG cap boost (20%/80% penalty) | 13.2, 14.4, 15.6, 16.8, 18.0 | +3 | percent |
|
||||
| 9 | Supplemental N.A. DMG | 8800, 9600, 10400, 11200, 12000 | +2000 | integer |
|
||||
| 10 | Supplemental Skill DMG | 11000, 12000, 13000, 14000, 15000 | +2500 | integer |
|
||||
| 11 | Supplemental C.A. DMG | 110000, 120000, 130000, 140000, 150000 | +25000 | integer |
|
||||
| 12 | Chain DMG Amplify | 6.6, 7.2, 7.8, 8.4, 9.0 | +1.5 | percent |
|
||||
| 13 | Boost TA rate when ≥50% HP | 6.6, 7.2, 7.8, 8.4, 9.0 | +1.5 | percent |
|
||||
| 14 | Amplify DMG at 100% HP | 2.2, 2.4, 2.6, 2.8, 3.0 | +0.5 | percent |
|
||||
| 15 | Max HP boost (70% DEF penalty) | 8.8, 9.6, 10.4, 11.2, 12.0 | +2 | percent |
|
||||
| 16 | DMG reduction when ≤50% HP | 8.8, 9.6, 10.4, 11.2, 12.0 | +2 | percent |
|
||||
| 17 | Regeneration | 440, 480, 520, 560, 600 | +100 | integer |
|
||||
| 18 | Turn-Based DMG Reduction | 8.8, 9.6, 10.4, 11.2, 12.0 | +2 | percent |
|
||||
| 19 | Chance to remove 1 debuff | 20 | +20 | percent |
|
||||
| 20 | Chance to cancel dispels | 20 | +20 | percent |
|
||||
|
||||
**Note:** Skills 19 and 20 have only one base value (20%), not 5.
|
||||
|
||||
### Group III Skills (Slot 4)
|
||||
|
||||
Group III has ~25+ skills with varied mechanics. The growth values can be positive or negative (e.g., "after using skills x times" decreases the required count with levels).
|
||||
|
||||
| ID | Name | Base Value | Growth | Notes |
|
||||
|----|------|------------|--------|-------|
|
||||
| 1 | Battle start: DMG Mitigation | 1000 | +1000 | integer |
|
||||
| 2 | Battle start: Random buff(s) | 1 | +1 | count |
|
||||
| 3 | HP consumed + DMG Cap after 3T | 10 | +10 | percent |
|
||||
| 4 | On knockout: Ally buffs | 1 | +1 | count |
|
||||
| 5 | On switch to main: DMG Amplified | 3 | +3 | percent |
|
||||
| 6 | Foe ≤50% HP: Restore HP | 2000 | +2000 | integer |
|
||||
| 7 | Skill 1 CD cut + HP consume | 30 | -6 | percent (decreasing) |
|
||||
| 8 | Debuff skill: Amplify foe DMG taken | 4 | +4 | percent |
|
||||
| 9 | Healing skill: Bonus DMG to next ally | 4 | +4 | percent |
|
||||
| 10 | DMG Cap stackable after X skills | 5 | -1 | count (decreasing) |
|
||||
| 11 | After 10+ turn skill: DMG Amplified | 2 | +2 | percent |
|
||||
| 12 | Linked skill CD cut after X uses | 8 | -1 | count (decreasing) |
|
||||
| 13 | Supplemental DMG based on charge bar | 5000 | +5000 | integer |
|
||||
| 14 | No attack: Random stackable buff(s) | 1 | +1 | count |
|
||||
| 15 | Chance to remove foe buffs | 1 | +1 | percent |
|
||||
| 16 | Chance to progress turn by 5 | 0.2 | +0.2 | percent |
|
||||
| 17 | Shield every 5 turns | 1000 | +500 | integer |
|
||||
| 18 | Chance for 6-hit Flurry | 1 | +1 | percent |
|
||||
| 19 | Bonus DMG after X enemy hits | 7 | -1 | count (decreasing) |
|
||||
| 20 | 3-hit Flurry after X hits | 200 | -25 | count (decreasing) |
|
||||
| 21 | Plain DMG based on HP lost | 10 | +10 | multiplier |
|
||||
| 22 | Supplemental Skill DMG after X skill DMG | 40000000 | -5000000 | integer (decreasing) |
|
||||
| 23 | Single attack: Random buff(s) | 1 | +1 | count |
|
||||
| 24 | Potion use: Fated Chain boost | 3 | +3 | percent |
|
||||
| 25 | Foe ≤3 debuffs: Armored | 5 | +5 | percent |
|
||||
| 26 | Sub ally: Debuff foes every X turns | 7 | -1 | count (decreasing) |
|
||||
| 27 | Boost EXP earned | 1 | +1 | percent |
|
||||
| 28 | Boost item drop rate | 0.5 | +0.5 | percent |
|
||||
| 29 | Chance to find earrings | ? | ? | unknown |
|
||||
|
||||
---
|
||||
|
||||
## Model Implementation
|
||||
|
||||
### Artifact Model
|
||||
|
||||
```ruby
|
||||
# app/models/artifact.rb
|
||||
class Artifact < ApplicationRecord
|
||||
# Enums
|
||||
enum :proficiency, {
|
||||
sabre: 1, dagger: 2, spear: 3, axe: 4, staff: 5,
|
||||
gun: 6, melee: 7, bow: 8, harp: 9, katana: 10
|
||||
}
|
||||
|
||||
enum :rarity, { standard: 0, quirk: 1 }
|
||||
|
||||
# Associations
|
||||
has_many :collection_artifacts, dependent: :restrict_with_error
|
||||
has_many :grid_artifacts, dependent: :restrict_with_error
|
||||
|
||||
# Validations
|
||||
validates :granblue_id, presence: true, uniqueness: true
|
||||
validates :name_en, presence: true
|
||||
validates :proficiency, presence: true
|
||||
validates :rarity, presence: true
|
||||
validates :style, presence: true, inclusion: { in: 1..3 }, if: :standard?
|
||||
validates :style, absence: true, if: :quirk?
|
||||
|
||||
# Scopes
|
||||
scope :standard_artifacts, -> { where(rarity: :standard) }
|
||||
scope :quirk_artifacts, -> { where(rarity: :quirk) }
|
||||
scope :by_proficiency, ->(prof) { where(proficiency: prof) }
|
||||
end
|
||||
```
|
||||
|
||||
### CollectionArtifact Model
|
||||
|
||||
```ruby
|
||||
# app/models/collection_artifact.rb
|
||||
class CollectionArtifact < ApplicationRecord
|
||||
include ArtifactSkillValidations
|
||||
|
||||
# Associations
|
||||
belongs_to :user
|
||||
belongs_to :artifact
|
||||
|
||||
# Enums
|
||||
enum :element, {
|
||||
fire: 1, water: 2, earth: 3, wind: 4, light: 5, dark: 6
|
||||
}
|
||||
|
||||
# Validations
|
||||
validates :element, presence: true
|
||||
validates :level, presence: true, inclusion: { in: 1..5 }
|
||||
validates :nickname, length: { maximum: 50 }, allow_blank: true
|
||||
|
||||
validate :validate_skill_levels_sum
|
||||
validate :validate_skills_for_standard_artifacts
|
||||
validate :validate_quirk_artifact_constraints
|
||||
|
||||
# Scopes
|
||||
scope :by_element, ->(el) { where(element: el) }
|
||||
scope :by_artifact, ->(artifact_id) { where(artifact_id: artifact_id) }
|
||||
scope :by_proficiency, ->(prof) { joins(:artifact).where(artifacts: { proficiency: prof }) }
|
||||
|
||||
private
|
||||
|
||||
def validate_skill_levels_sum
|
||||
return if artifact&.quirk?
|
||||
|
||||
total = [skill1, skill2, skill3, skill4].sum { |s| s['level'].to_i }
|
||||
expected = level + 3
|
||||
|
||||
unless total == expected
|
||||
errors.add(:base, "Skill levels must sum to #{expected} for artifact level #{level}")
|
||||
end
|
||||
end
|
||||
|
||||
def validate_quirk_artifact_constraints
|
||||
return unless artifact&.quirk?
|
||||
|
||||
errors.add(:level, "must be 1 for quirk artifacts") unless level == 1
|
||||
|
||||
# Quirk artifacts don't store skills
|
||||
[skill1, skill2, skill3, skill4].each_with_index do |skill, idx|
|
||||
unless skill.blank? || skill == {}
|
||||
errors.add(:"skill#{idx + 1}", "must be empty for quirk artifacts")
|
||||
end
|
||||
end
|
||||
end
|
||||
end
|
||||
```
|
||||
|
||||
### GridArtifact Model
|
||||
|
||||
```ruby
|
||||
# app/models/grid_artifact.rb
|
||||
class GridArtifact < ApplicationRecord
|
||||
include ArtifactSkillValidations
|
||||
|
||||
# Associations
|
||||
belongs_to :grid_character
|
||||
belongs_to :artifact
|
||||
|
||||
has_one :party, through: :grid_character
|
||||
has_one :character, through: :grid_character
|
||||
|
||||
# Enums
|
||||
enum :element, {
|
||||
fire: 1, water: 2, earth: 3, wind: 4, light: 5, dark: 6
|
||||
}
|
||||
|
||||
# Validations
|
||||
validates :element, presence: true
|
||||
validates :level, presence: true, inclusion: { in: 1..5 }
|
||||
validates :grid_character_id, uniqueness: { message: "already has an artifact equipped" }
|
||||
|
||||
validate :validate_skill_levels_sum
|
||||
validate :validate_character_compatibility
|
||||
validate :validate_quirk_artifact_constraints
|
||||
|
||||
private
|
||||
|
||||
def validate_character_compatibility
|
||||
return unless grid_character&.character && artifact
|
||||
|
||||
char = grid_character.character
|
||||
|
||||
# Check element compatibility (skip for characters with variable elements like Lyria)
|
||||
unless char.any_element?
|
||||
unless char.element == element
|
||||
errors.add(:element, "must match character's element")
|
||||
end
|
||||
end
|
||||
|
||||
# Check proficiency compatibility
|
||||
char_proficiencies = [char.proficiency1, char.proficiency2].compact
|
||||
unless char_proficiencies.include?(artifact.proficiency)
|
||||
errors.add(:artifact, "proficiency must match one of the character's proficiencies")
|
||||
end
|
||||
end
|
||||
end
|
||||
```
|
||||
|
||||
### Shared Skill Validation Concern
|
||||
|
||||
```ruby
|
||||
# app/models/concerns/artifact_skill_validations.rb
|
||||
module ArtifactSkillValidations
|
||||
extend ActiveSupport::Concern
|
||||
|
||||
ELEMENT_ENUM = { fire: 1, water: 2, earth: 3, wind: 4, light: 5, dark: 6 }.freeze
|
||||
|
||||
# Group I skills (slots 1 & 2)
|
||||
GROUP_I_SKILLS = {
|
||||
1 => { name: 'ATK', base_values: [1320, 1440, 1560, 1680, 1800], growth: 300, type: :integer },
|
||||
2 => { name: 'HP', base_values: [660, 720, 780, 840, 900], growth: 150, type: :integer },
|
||||
3 => { name: 'C.A. DMG', base_values: [13.2, 14.4, 15.6, 16.8, 18.0], growth: 3, type: :percent },
|
||||
4 => { name: 'Skill DMG', base_values: [13.2, 14.4, 15.6, 16.8, 18.0], growth: 3, type: :percent },
|
||||
5 => { name: 'Elemental ATK', base_values: [8.8, 9.6, 10.4, 11.2, 12.0], growth: 2, type: :percent },
|
||||
6 => { name: 'Critical Hit Rate', base_values: [13.2, 14.4, 15.6, 16.8, 18.0], growth: 3, type: :percent },
|
||||
7 => { name: 'Double Attack Rate', base_values: [6.6, 7.2, 7.8, 8.4, 9.0], growth: 1.5, type: :percent },
|
||||
8 => { name: 'Triple Attack Rate', base_values: [4.4, 4.8, 5.2, 5.6, 6.0], growth: 1, type: :percent },
|
||||
9 => { name: 'DEF', base_values: [8.8, 9.6, 10.4, 11.2, 12.0], growth: 2, type: :percent },
|
||||
10 => { name: 'Superior Element Reduction', base_values: [4.4, 4.8, 5.2, 5.6, 6.0], growth: 1, type: :percent },
|
||||
11 => { name: 'Dodge Rate', base_values: [4.4, 4.8, 5.2, 5.6, 6.0], growth: 1, type: :percent },
|
||||
12 => { name: 'Healing', base_values: [13.2, 14.4, 15.6, 16.8, 18.0], growth: 3, type: :percent },
|
||||
13 => { name: 'Debuff Success Rate', base_values: [6.6, 7.2, 7.8, 8.4, 9.0], growth: 1.5, type: :percent },
|
||||
14 => { name: 'Debuff Resistance', base_values: [6.6, 7.2, 7.8, 8.4, 9.0], growth: 1.5, type: :percent }
|
||||
}.freeze
|
||||
|
||||
# Group II skills (slot 3)
|
||||
GROUP_II_SKILLS = {
|
||||
1 => { name: 'N.A. DMG Cap', base_values: [2.2, 2.4, 2.6, 2.8, 3.0], growth: 0.5, type: :percent },
|
||||
2 => { name: 'Skill DMG Cap', base_values: [8.8, 9.6, 10.4, 11.2, 12.0], growth: 2, type: :percent },
|
||||
3 => { name: 'C.A. DMG Cap', base_values: [6.6, 7.2, 7.8, 8.4, 9.0], growth: 1.5, type: :percent },
|
||||
4 => { name: 'Special C.A. DMG Cap', base_values: [4.4, 4.8, 5.2, 5.6, 6.0], growth: 1, type: :percent },
|
||||
5 => { name: 'Boost DMG cap for critical hits', base_values: [2.2, 2.4, 2.6, 2.8, 3.0], growth: 0.5, type: :percent },
|
||||
6 => { name: 'N.A. DMG cap boost (penalty)', base_values: [4.4, 4.8, 5.2, 5.6, 6.0], growth: 1, type: :percent },
|
||||
7 => { name: 'Skill DMG cap boost (penalty)', base_values: [17.6, 19.2, 20.8, 22.4, 24.0], growth: 4, type: :percent },
|
||||
8 => { name: 'C.A. DMG cap boost (penalty)', base_values: [13.2, 14.4, 15.6, 16.8, 18.0], growth: 3, type: :percent },
|
||||
9 => { name: 'Supplemental N.A. DMG', base_values: [8800, 9600, 10400, 11200, 12000], growth: 2000, type: :integer },
|
||||
10 => { name: 'Supplemental Skill DMG', base_values: [11000, 12000, 13000, 14000, 15000], growth: 2500, type: :integer },
|
||||
11 => { name: 'Supplemental C.A. DMG', base_values: [110000, 120000, 130000, 140000, 150000], growth: 25000, type: :integer },
|
||||
12 => { name: 'Chain DMG Amplify', base_values: [6.6, 7.2, 7.8, 8.4, 9.0], growth: 1.5, type: :percent },
|
||||
13 => { name: 'Boost TA rate when ≥50% HP', base_values: [6.6, 7.2, 7.8, 8.4, 9.0], growth: 1.5, type: :percent },
|
||||
14 => { name: 'Amplify DMG at 100% HP', base_values: [2.2, 2.4, 2.6, 2.8, 3.0], growth: 0.5, type: :percent },
|
||||
15 => { name: 'Max HP boost (DEF penalty)', base_values: [8.8, 9.6, 10.4, 11.2, 12.0], growth: 2, type: :percent },
|
||||
16 => { name: 'DMG reduction when ≤50% HP', base_values: [8.8, 9.6, 10.4, 11.2, 12.0], growth: 2, type: :percent },
|
||||
17 => { name: 'Regeneration', base_values: [440, 480, 520, 560, 600], growth: 100, type: :integer },
|
||||
18 => { name: 'Turn-Based DMG Reduction', base_values: [8.8, 9.6, 10.4, 11.2, 12.0], growth: 2, type: :percent },
|
||||
19 => { name: 'Chance to remove 1 debuff', base_values: [20], growth: 20, type: :percent },
|
||||
20 => { name: 'Chance to cancel dispels', base_values: [20], growth: 20, type: :percent }
|
||||
}.freeze
|
||||
|
||||
# Group III skills (slot 4) - simplified, full list in implementation
|
||||
GROUP_III_SKILLS = {
|
||||
1 => { name: 'Battle start: DMG Mitigation', base_values: [1000], growth: 1000, type: :integer },
|
||||
2 => { name: 'Battle start: Random buff(s)', base_values: [1], growth: 1, type: :count },
|
||||
3 => { name: 'HP consumed + DMG Cap after 3T', base_values: [10], growth: 10, type: :percent },
|
||||
4 => { name: 'On knockout: Ally buffs', base_values: [1], growth: 1, type: :count },
|
||||
5 => { name: 'On switch to main: DMG Amplified', base_values: [3], growth: 3, type: :percent },
|
||||
6 => { name: 'Foe ≤50% HP: Restore HP', base_values: [2000], growth: 2000, type: :integer },
|
||||
7 => { name: 'Skill 1 CD cut + HP consume', base_values: [30], growth: -6, type: :percent },
|
||||
8 => { name: 'Debuff skill: Amplify foe DMG taken', base_values: [4], growth: 4, type: :percent },
|
||||
9 => { name: 'Healing skill: Bonus DMG to next ally', base_values: [4], growth: 4, type: :percent },
|
||||
10 => { name: 'DMG Cap stackable after X skills', base_values: [5], growth: -1, type: :count },
|
||||
11 => { name: 'After 10+ turn skill: DMG Amplified', base_values: [2], growth: 2, type: :percent },
|
||||
12 => { name: 'Linked skill CD cut after X uses', base_values: [8], growth: -1, type: :count },
|
||||
13 => { name: 'Supplemental DMG based on charge bar', base_values: [5000], growth: 5000, type: :integer },
|
||||
14 => { name: 'No attack: Random stackable buff(s)', base_values: [1], growth: 1, type: :count },
|
||||
15 => { name: 'Chance to remove foe buffs', base_values: [1], growth: 1, type: :percent },
|
||||
16 => { name: 'Chance to progress turn by 5', base_values: [0.2], growth: 0.2, type: :percent },
|
||||
17 => { name: 'Shield every 5 turns', base_values: [1000], growth: 500, type: :integer },
|
||||
18 => { name: 'Chance for 6-hit Flurry', base_values: [1], growth: 1, type: :percent },
|
||||
19 => { name: 'Bonus DMG after X enemy hits', base_values: [7], growth: -1, type: :count },
|
||||
20 => { name: '3-hit Flurry after X hits', base_values: [200], growth: -25, type: :count },
|
||||
21 => { name: 'Plain DMG based on HP lost', base_values: [10], growth: 10, type: :multiplier },
|
||||
22 => { name: 'Supplemental Skill DMG after X skill DMG', base_values: [40000000], growth: -5000000, type: :integer },
|
||||
23 => { name: 'Single attack: Random buff(s)', base_values: [1], growth: 1, type: :count },
|
||||
24 => { name: 'Potion use: Fated Chain boost', base_values: [3], growth: 3, type: :percent },
|
||||
25 => { name: 'Foe ≤3 debuffs: Armored', base_values: [5], growth: 5, type: :percent },
|
||||
26 => { name: 'Sub ally: Debuff foes every X turns', base_values: [7], growth: -1, type: :count },
|
||||
27 => { name: 'Boost EXP earned', base_values: [1], growth: 1, type: :percent },
|
||||
28 => { name: 'Boost item drop rate', base_values: [0.5], growth: 0.5, type: :percent },
|
||||
29 => { name: 'Chance to find earrings', base_values: [nil], growth: nil, type: :unknown }
|
||||
}.freeze
|
||||
|
||||
included do
|
||||
validate :validate_skill1_group_i
|
||||
validate :validate_skill2_group_i
|
||||
validate :validate_skill3_group_ii
|
||||
validate :validate_skill4_group_iii
|
||||
end
|
||||
|
||||
private
|
||||
|
||||
def validate_skill_in_group(skill_data, group, slot_name)
|
||||
return if skill_data.blank? || skill_data == {}
|
||||
return if artifact&.quirk?
|
||||
|
||||
modifier = skill_data['modifier']
|
||||
strength = skill_data['strength']
|
||||
level = skill_data['level']
|
||||
|
||||
unless modifier && strength && level
|
||||
errors.add(slot_name, "must have modifier, strength, and level")
|
||||
return
|
||||
end
|
||||
|
||||
skill_def = group[modifier]
|
||||
unless skill_def
|
||||
errors.add(slot_name, "has invalid modifier #{modifier}")
|
||||
return
|
||||
end
|
||||
|
||||
unless (1..5).include?(level)
|
||||
errors.add(slot_name, "level must be between 1 and 5")
|
||||
return
|
||||
end
|
||||
|
||||
# Validate strength is a valid base value for this skill
|
||||
unless skill_def[:base_values].include?(strength) || skill_def[:base_values] == [nil]
|
||||
errors.add(slot_name, "has invalid base strength #{strength}")
|
||||
end
|
||||
end
|
||||
|
||||
def validate_skill1_group_i
|
||||
validate_skill_in_group(skill1, GROUP_I_SKILLS, :skill1)
|
||||
end
|
||||
|
||||
def validate_skill2_group_i
|
||||
validate_skill_in_group(skill2, GROUP_I_SKILLS, :skill2)
|
||||
end
|
||||
|
||||
def validate_skill3_group_ii
|
||||
validate_skill_in_group(skill3, GROUP_II_SKILLS, :skill3)
|
||||
end
|
||||
|
||||
def validate_skill4_group_iii
|
||||
validate_skill_in_group(skill4, GROUP_III_SKILLS, :skill4)
|
||||
end
|
||||
end
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## API Endpoints
|
||||
|
||||
### Artifacts (Base Entity - Read Only)
|
||||
|
||||
```
|
||||
GET /api/v1/artifacts # List all artifact types
|
||||
GET /api/v1/artifacts/:id # Get single artifact type
|
||||
```
|
||||
|
||||
### Collection Artifacts
|
||||
|
||||
```
|
||||
GET /api/v1/users/:user_id/collection/artifacts # List user's artifacts
|
||||
POST /api/v1/users/:user_id/collection/artifacts # Add artifact to collection
|
||||
GET /api/v1/collection/artifacts/:id # Get single collection artifact
|
||||
PATCH /api/v1/collection/artifacts/:id # Update collection artifact
|
||||
DELETE /api/v1/collection/artifacts/:id # Remove from collection
|
||||
|
||||
# Batch operations
|
||||
POST /api/v1/users/:user_id/collection/artifacts/batch # Add multiple artifacts
|
||||
```
|
||||
|
||||
### Grid Artifacts (via Grid Characters)
|
||||
|
||||
```
|
||||
POST /api/v1/parties/:party_id/characters/:character_id/artifact # Equip artifact
|
||||
PATCH /api/v1/parties/:party_id/characters/:character_id/artifact # Update equipped artifact
|
||||
DELETE /api/v1/parties/:party_id/characters/:character_id/artifact # Unequip artifact
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Implementation Order
|
||||
|
||||
### Phase 1: Database & Models
|
||||
1. Create migration for `artifacts` table
|
||||
2. Create migration for `collection_artifacts` table
|
||||
3. Create migration for `grid_artifacts` table
|
||||
4. Implement `Artifact` model
|
||||
5. Implement `ArtifactSkillValidations` concern
|
||||
6. Implement `CollectionArtifact` model
|
||||
7. Implement `GridArtifact` model
|
||||
8. Add associations to `User` and `GridCharacter` models
|
||||
9. Seed artifact data (30 standard + 5 quirk)
|
||||
|
||||
### Phase 2: Blueprints
|
||||
1. Create `ArtifactBlueprint`
|
||||
2. Create `CollectionArtifactBlueprint`
|
||||
3. Create `GridArtifactBlueprint`
|
||||
4. Update `GridCharacterBlueprint` to include artifact
|
||||
5. Update `PartyBlueprint` to include artifacts
|
||||
|
||||
### Phase 3: Controllers
|
||||
1. Create `ArtifactsController` (index, show)
|
||||
2. Create `CollectionArtifactsController` (full CRUD + batch)
|
||||
3. Update `GridCharactersController` to handle artifact operations
|
||||
4. Add routes
|
||||
|
||||
### Phase 4: Testing
|
||||
1. Model specs for all new models
|
||||
2. Request specs for all new endpoints
|
||||
3. Validation specs for skill constraints
|
||||
|
||||
---
|
||||
|
||||
## Seed Data
|
||||
|
||||
### Standard Artifacts (30 total)
|
||||
|
||||
| Proficiency | Style 1 (Ominous) | Style 2 (Saint) | Style 3 (Jinyao) |
|
||||
|-------------|-------------------|-----------------|------------------|
|
||||
| Sabre | Ominous Amulet | Couronne Sainte | Jinyao Yushi |
|
||||
| Dagger | Ominous Ring | Jaseron Saint | Jinyao Mianju |
|
||||
| Spear | Ominous Goblet | Casque Saint | Jinyao Qizhi |
|
||||
| Axe | Ominous Horn | Armure Sainte | Jinyao Yaodai |
|
||||
| Staff | Ominous Totem | Robe Sainte | Jinyao Mingjing |
|
||||
| Gun | Ominous Pendant | Lunettes Saintes | Jinyao Wangjing |
|
||||
| Melee | Ominous Bangle | Bottes Saintes | Jinyao Mianzhao |
|
||||
| Bow | Ominous Pheon | Chapeau Saint | Jinyao Xiongjia |
|
||||
| Harp | Ominous Whistle | Boite a Musique Sainte | Jinyao Tongluo |
|
||||
| Katana | Ominous Stone | Capuchon Saint | Jinyao Xianglu |
|
||||
|
||||
### Quirk Artifacts (5 total)
|
||||
|
||||
| Name | Skills (handled by frontend) |
|
||||
|------|------------------------------|
|
||||
| Fantosmik Creste | Crest-based damage amplification |
|
||||
| Fantosmik Fengtooth | CA-focused with HP consumption |
|
||||
| Fantosmik Gemme | Shield and Guts mechanics |
|
||||
| Fantosmik Lanterne | Universal weapon skill compatibility |
|
||||
| Fantosmik Maylet | Random stat changes |
|
||||
|
||||
---
|
||||
|
||||
## Open Questions / Future Considerations
|
||||
|
||||
1. **Character any_element flag**: Need to verify how this is currently stored in Character model for Lyria-type characters
|
||||
2. **Image URLs**: Confirm CDN path pattern for artifact images
|
||||
3. **Granblue IDs**: Need to determine the actual game IDs for each artifact type
|
||||
4. **Frontend coordination**: Quirk artifact skill display will need frontend implementation
|
||||
5. **Migration strategy**: Consider data_migrate for seeding artifacts to ensure proper ordering
|
||||
296
docs/plans/character-season-series.md
Normal file
296
docs/plans/character-season-series.md
Normal file
|
|
@ -0,0 +1,296 @@
|
|||
# Character Season & Series Implementation Plan
|
||||
|
||||
## Overview
|
||||
|
||||
Add `season`, `series`, and `gacha_available` columns to the characters table to properly categorize character variants. This replaces the current approach of disambiguating in name fields (e.g., "Vira (SSR)").
|
||||
|
||||
**Goals:**
|
||||
- Clean character names without disambiguation suffixes
|
||||
- Enable filtering by season/series in the UI
|
||||
- Support gacha bot queries for pool availability
|
||||
- Centralize gacha metadata in hensei-api (shared database with siero-bot)
|
||||
|
||||
---
|
||||
|
||||
## Data Model
|
||||
|
||||
### Season (integer, nullable)
|
||||
Represents the gacha time period when a character can be pulled.
|
||||
|
||||
| Value | Name | Notes |
|
||||
|-------|-----------|-------|
|
||||
| 1 | Standard | Available year-round (in their respective pool) (1-index to work better with Javascript) |
|
||||
| 2 | Valentine | February |
|
||||
| 3 | Formal | June |
|
||||
| 4 | Summer | July-August (both Summer and Yukata series) |
|
||||
| 5 | Halloween | October |
|
||||
| 6 | Holiday | December |
|
||||
|
||||
### Series (integer array)
|
||||
Represents the character's identity/pool membership. A character can belong to multiple series (e.g., Summer Zodiac = [summer, zodiac]).
|
||||
|
||||
| Value | Name | Notes |
|
||||
|-------|-----------|-------|
|
||||
| 1 | Standard | Regular gacha pool (1-index to work better with Javascript) |
|
||||
| 2 | Grand | Flash Gala and Legend Gacha exclusive |
|
||||
| 3 | Zodiac | Legend Fest exclusive, yearly rotation |
|
||||
| 4 | Promo | Not in gacha - ticket/code redemption |
|
||||
| 5 | Collab | Collaboration events |
|
||||
| 6 | Eternal | Free recruitment (Eternals) |
|
||||
| 7 | Evoker | Free recruitment (Evokers) |
|
||||
| 8 | Saint | Free recruitment (similar to Eternals), may have gacha alts |
|
||||
| 9 | Fantasy | Can combine with other series (e.g., Fantasy + Grand) |
|
||||
| 10 | Summer | Summer seasonal series |
|
||||
| 11 | Yukata | Yukata seasonal series (same gacha window as Summer) |
|
||||
| 12 | Valentine | Valentine seasonal series |
|
||||
| 13 | Halloween | Halloween seasonal series |
|
||||
| 14 | Formal | Formal seasonal series |
|
||||
| 15 | Event | Event reward characters |
|
||||
|
||||
### Gacha Available (boolean)
|
||||
Quick filter for characters that can be pulled in gacha vs those that are recruited.
|
||||
- `true` - Can be pulled from gacha (Standard, Grand, Zodiac, seasonal series, etc.)
|
||||
- `false` - Must be recruited (Eternals, Evokers, Saints, Event, Collab)
|
||||
|
||||
### Promotion (integer array on weapons/summons)
|
||||
Move promotion data from the `gacha` table to weapons and summons directly.
|
||||
|
||||
| Value | Name | Notes |
|
||||
|-------|------------|-------|
|
||||
| 1 | Premium | Available in regular Premium draws |
|
||||
| 2 | Classic | Available in Classic draws |
|
||||
| 3 | Classic II | Available in Classic II draws |
|
||||
| 4 | Flash | Available in Flash Gala (6% SSR rate) |
|
||||
| 5 | Legend | Available in Legend Fest (6% SSR rate) |
|
||||
| 6 | Valentine | Valentine seasonal gacha |
|
||||
| 7 | Summer | Summer seasonal gacha |
|
||||
| 8 | Halloween | Halloween seasonal gacha |
|
||||
| 9 | Holiday | Holiday seasonal gacha |
|
||||
| 10 | Collab | Collaboration gacha |
|
||||
| 11 | Formal | Formal seasonal gacha |
|
||||
|
||||
**Decision:** Add `promotions` as integer array on weapons and summons tables, then deprecate the `gacha` table. This eliminates the polymorphic join and simplifies queries.
|
||||
|
||||
---
|
||||
|
||||
## Implementation Tasks
|
||||
|
||||
### Phase 1: Schema Migration
|
||||
|
||||
- [x] **Task 1.1:** Create migration to add `season`, `series`, and `gacha_available` columns: `6e62053`
|
||||
|
||||
- [x] **Task 1.2:** Add enum constants to `GranblueEnums`: `24d8d20`, `208d1f4`
|
||||
|
||||
### Phase 2: Model Updates
|
||||
|
||||
- [x] **Task 2.1:** Update `Character` model: `afa1c51`
|
||||
|
||||
- [x] **Task 2.2:** Update `CharacterBlueprint`: `a3c33ce`, `cb01658`
|
||||
|
||||
### Phase 3: Controller & API Updates
|
||||
|
||||
- [x] **Task 3.1:** Update `CharactersController`: `db048dc`
|
||||
|
||||
- [x] **Task 3.2:** Update search functionality: `9c5c859`
|
||||
- Added `season`, `series`, `gacha_available` filters to characters search
|
||||
- Added `promotions` filter to weapons search
|
||||
- Added `promotions` filter to summons search
|
||||
- Array filters use PostgreSQL `&&` (overlap) operator
|
||||
|
||||
### Phase 4: Importer/Parser Updates
|
||||
|
||||
- [x] **Task 4.1:** Update `CharacterImporter`: `e0a82bc`
|
||||
- Added `season`, `series`, `gacha_available` to `build_attributes`
|
||||
|
||||
- [x] **Task 4.2:** Update `CharacterParser`: `e0a82bc`
|
||||
- Added `series_from_hash`, `season_from_hash`, `gacha_available_from_hash` methods
|
||||
- Extracts data from wiki `|series=` and `|obtain=` fields
|
||||
|
||||
- [x] **Task 4.3:** Update `WeaponImporter` and `SummonImporter`: `7aa0521`
|
||||
- Added `promotions` to `build_attributes`
|
||||
|
||||
- [x] **Task 4.4:** Update `WeaponParser` and `SummonParser`: `c1a5d62`
|
||||
- Added `promotions_from_obtain` method
|
||||
- Added wiki promotions mapping to `Wiki` class
|
||||
|
||||
### Phase 5: Data Migration
|
||||
|
||||
- [x] **Task 5.1:** Create rake task to export characters to CSV: `284ee44`
|
||||
|
||||
- [ ] **Task 5.2:** User curates CSV with season/series assignments (manual step)
|
||||
|
||||
- [x] **Task 5.3:** Create rake task to import curated CSV: `284ee44`
|
||||
|
||||
- [ ] **Task 5.4:** Clean up character names (deferred until data populated)
|
||||
|
||||
### Phase 6: Frontend Updates (hensei-svelte)
|
||||
|
||||
- [x] **Task 6.1:** Update TypeScript types: `67b87c7d`
|
||||
|
||||
- [x] **Task 6.2:** Update search adapter: `f26d3e38`
|
||||
|
||||
- [x] **Task 6.3:** Add filter UI components (CheckboxGroup): `96f040a9`
|
||||
|
||||
- [x] **Task 6.4:** Update character display: `cf694bb1`
|
||||
|
||||
- [x] **Task 6.5:** Update weapon display: `8c45c219`
|
||||
|
||||
- [x] **Task 6.6:** Update summon display: `23ae7f70`
|
||||
|
||||
- [x] **Task 6.7:** Update batch import pages: `1933f3d8`
|
||||
|
||||
- [x] **Task 6.8:** Add recruited_by to character metadata: `cf694bb1`
|
||||
|
||||
### Phase 7: Weapons/Summons Promotion Migration
|
||||
|
||||
- [x] **Task 7.1:** Add `promotions` column to weapons table: `6f64610`
|
||||
|
||||
- [x] **Task 7.2:** Add `promotions` column to summons table: `6f64610`
|
||||
|
||||
- [x] **Task 7.3:** Add PROMOTIONS enum to `GranblueEnums`: `6f64610`, `208d1f4`
|
||||
|
||||
- [x] **Task 7.4:** Create data migration rake task: `49e52ff`
|
||||
|
||||
- [x] **Task 7.5:** Update Weapon and Summon models: `e81c559`
|
||||
|
||||
- [x] **Task 7.6:** Update WeaponBlueprint and SummonBlueprint: `0dba56c`
|
||||
|
||||
- [x] **Task 7.7:** Update controllers to permit `promotions`: `05dd899`
|
||||
|
||||
- [ ] **Task 7.8:** Deprecate `gacha` table (after siero-bot deployed and tested)
|
||||
|
||||
### Phase 8: Siero-bot Integration
|
||||
|
||||
- [x] **Task 8.1:** Update siero-bot to use new columns (branch: `feature/use-promotions-column`)
|
||||
- `210b5dc` - Added `PromotionId` enum mapping to hensei-api values
|
||||
- `b0e0972` - Added `promotions: number[]` to table interfaces
|
||||
- `897d86b` - Rewrote `cache.ts` to query weapons/summons directly
|
||||
- `1b7ac14` - Rewrote `api.ts` to remove gacha table dependency
|
||||
- `d745b0f` - Changed rateups to use `granblue_id` for stability
|
||||
|
||||
---
|
||||
|
||||
## Remaining Work (Pre-Deployment Testing Required)
|
||||
|
||||
These tasks require testing and/or manual intervention before completion:
|
||||
|
||||
### 1. Data Population (Manual)
|
||||
|
||||
**Task 5.2: Curate character season/series data**
|
||||
|
||||
Options for populating character data:
|
||||
- **Option A:** Export CSV, manually curate, re-import
|
||||
```bash
|
||||
rake characters:export_csv # Creates lib/seeds/characters_export.csv
|
||||
# Edit CSV to add season/series/gacha_available values
|
||||
rake characters:import_csv # Imports curated data
|
||||
```
|
||||
- **Option B:** Use wiki parser to auto-populate (may need manual review)
|
||||
```bash
|
||||
rails runner "Granblue::Parsers::CharacterParser.fetch_all(save: true, overwrite: true)"
|
||||
```
|
||||
|
||||
### 2. Siero-bot Deployment
|
||||
|
||||
**Deploy and test siero-bot changes before deprecating gacha table:**
|
||||
|
||||
1. Merge `feature/use-promotions-column` branch
|
||||
2. Deploy to production
|
||||
3. Test gacha simulation commands work correctly
|
||||
4. Test rateup functionality works correctly
|
||||
5. Monitor for errors
|
||||
|
||||
### 3. Database Cleanup (Destructive)
|
||||
|
||||
**Task 7.8: Deprecate `gacha` table**
|
||||
|
||||
Only after siero-bot is deployed and verified working:
|
||||
|
||||
1. Create migration to drop `gacha` table
|
||||
2. Remove any remaining references to `Gacha` model
|
||||
3. Clean up unused code
|
||||
|
||||
### 4. Character Name Cleanup (Optional)
|
||||
|
||||
**Task 5.4: Remove disambiguation from character names**
|
||||
|
||||
After season/series data is populated and frontend displays badges:
|
||||
|
||||
1. Remove suffixes like "(SSR)", "(Summer)", "(Grand)" from `name_en`
|
||||
2. Update any search indexes if needed
|
||||
3. Verify frontend displays correctly with badges instead of name suffixes
|
||||
|
||||
---
|
||||
|
||||
## File Changes Summary
|
||||
|
||||
### hensei-api
|
||||
|
||||
| File | Change |
|
||||
|------|--------|
|
||||
| `db/migrate/*_add_season_series_to_characters.rb` | Add season, series, gacha_available columns |
|
||||
| `db/migrate/*_add_promotions_to_weapons.rb` | Add promotions array column |
|
||||
| `db/migrate/*_add_promotions_to_summons.rb` | Add promotions array column |
|
||||
| `lib/tasks/characters.rake` | Export/import rake tasks for data migration |
|
||||
| `lib/tasks/gacha.rake` | Migration tasks for promotions data |
|
||||
| `app/models/concerns/granblue_enums.rb` | Add CHARACTER_SEASONS, CHARACTER_SERIES, PROMOTIONS |
|
||||
| `app/models/character.rb` | Add validations, scopes, helpers |
|
||||
| `app/models/weapon.rb` | Add promotions validations, scopes, helpers |
|
||||
| `app/models/summon.rb` | Add promotions validations, scopes, helpers |
|
||||
| `app/blueprints/api/v1/character_blueprint.rb` | Serialize new fields, recruited_by |
|
||||
| `app/blueprints/api/v1/weapon_blueprint.rb` | Serialize promotions |
|
||||
| `app/blueprints/api/v1/summon_blueprint.rb` | Serialize promotions |
|
||||
| `app/controllers/api/v1/characters_controller.rb` | Permit new params, filtering |
|
||||
| `app/controllers/api/v1/weapons_controller.rb` | Permit promotions |
|
||||
| `app/controllers/api/v1/summons_controller.rb` | Permit promotions |
|
||||
| `app/controllers/api/v1/search_controller.rb` | Add season/series/promotions filters |
|
||||
| `lib/granblue/importers/character_importer.rb` | Parse new CSV columns |
|
||||
| `lib/granblue/importers/weapon_importer.rb` | Parse promotions column |
|
||||
| `lib/granblue/importers/summon_importer.rb` | Parse promotions column |
|
||||
| `lib/granblue/parsers/character_parser.rb` | Extract season/series from wiki |
|
||||
| `lib/granblue/parsers/weapon_parser.rb` | Extract promotions from wiki |
|
||||
| `lib/granblue/parsers/summon_parser.rb` | Extract promotions from wiki |
|
||||
| `lib/granblue/parsers/wiki.rb` | Add promotions mapping |
|
||||
|
||||
### hensei-svelte
|
||||
|
||||
| File | Change |
|
||||
|------|--------|
|
||||
| `src/lib/types/Character.d.ts` | Add season/series/gachaAvailable fields |
|
||||
| `src/lib/types/Weapon.d.ts` | Add promotions fields |
|
||||
| `src/lib/types/Summon.d.ts` | Add promotions fields |
|
||||
| `src/lib/types/enums.ts` | Add CharacterSeason, CharacterSeries, Promotion enums |
|
||||
| `src/lib/api/adapters/entity.adapter.ts` | Add new fields to interfaces |
|
||||
| `src/lib/api/adapters/search.adapter.ts` | Add filter params |
|
||||
| `src/lib/api/adapters/types.ts` | Add SearchFilters types |
|
||||
| `src/lib/components/ui/checkbox/CheckboxGroup.svelte` | New multiselect component |
|
||||
| `src/lib/components/ui/DetailItem.svelte` | Add multiselect type support |
|
||||
| `src/lib/features/database/characters/schema.ts` | Add to edit schema |
|
||||
| `src/lib/features/database/characters/sections/CharacterTaxonomySection.svelte` | Add season/series/gacha UI |
|
||||
| `src/lib/features/database/characters/sections/CharacterMetadataSection.svelte` | Add recruited_by display |
|
||||
| `src/lib/features/database/weapons/schema.ts` | Add promotions to schema |
|
||||
| `src/lib/features/database/weapons/sections/WeaponTaxonomySection.svelte` | Add promotions UI |
|
||||
| `src/lib/features/database/summons/schema.ts` | Add promotions to schema |
|
||||
| `src/lib/features/database/summons/sections/SummonTaxonomySection.svelte` | Add promotions UI |
|
||||
| `src/routes/(app)/database/*/import/+page.svelte` | Add new fields to batch import |
|
||||
|
||||
### siero-bot (branch: feature/use-promotions-column)
|
||||
|
||||
| File | Change |
|
||||
|------|--------|
|
||||
| `src/services/cache.ts` | Query promotions from weapons/summons instead of gacha table |
|
||||
| `src/services/api.ts` | Remove gacha table dependency, use granblue_id for rateups |
|
||||
| `src/utils/enums.ts` | Add PromotionId enum, mapping helpers |
|
||||
| `src/services/tables.ts` | Add promotions to WeaponTable and SummonTable |
|
||||
|
||||
---
|
||||
|
||||
## Notes
|
||||
|
||||
- The `character_id` array field will remain unchanged (no rename)
|
||||
- `gacha_available` boolean added for quick filtering of pullable vs recruited characters
|
||||
- All enums are 1-indexed to work better with JavaScript/TypeScript
|
||||
- `gacha` table will be deprecated after siero-bot migration is complete
|
||||
- Season values represent gacha availability windows (when you can pull)
|
||||
- Series values represent character identity (what pool/category they belong to)
|
||||
- Wiki uses "gala" for Flash Gala weapons (mapped to Flash promotion ID 4)
|
||||
196
docs/plans/weapon-series-migration.md
Normal file
196
docs/plans/weapon-series-migration.md
Normal file
|
|
@ -0,0 +1,196 @@
|
|||
# Plan: Convert WeaponSeries from Enum to Database Table
|
||||
|
||||
## Summary
|
||||
Convert the hardcoded `SERIES_SLUGS` hash in `Weapon` model to a `weapon_series` database table with full CRUD API support, enabling dynamic management of weapon series without code deploys.
|
||||
|
||||
## New Table: `weapon_series`
|
||||
|
||||
| Column | Type | Notes |
|
||||
|--------|------|-------|
|
||||
| id | uuid | Primary key |
|
||||
| name_en | string | English name |
|
||||
| name_jp | string | Japanese name |
|
||||
| slug | string | Unique identifier (e.g., 'dark-opus') |
|
||||
| order | integer | Sort order for display |
|
||||
| extra | boolean | Allowed in extra grid positions (9, 10, 11) |
|
||||
| element_changeable | boolean | Weapon element can be changed |
|
||||
| has_weapon_keys | boolean | Series supports weapon keys |
|
||||
| has_awakening | boolean | Series supports awakenings |
|
||||
| has_ax_skills | boolean | Series supports AX skills |
|
||||
|
||||
## Implementation Steps
|
||||
|
||||
### Phase 1: Database Setup
|
||||
|
||||
1. **Create `weapon_series` table migration**
|
||||
- `db/migrate/TIMESTAMP_create_weapon_series.rb`
|
||||
- UUID primary key, unique index on slug, index on order
|
||||
|
||||
2. **Add `weapon_series_id` to weapons table**
|
||||
- `db/migrate/TIMESTAMP_add_weapon_series_id_to_weapons.rb`
|
||||
- Foreign key reference, nullable initially
|
||||
|
||||
3. **Create `weapon_key_series` join table**
|
||||
- `db/migrate/TIMESTAMP_create_weapon_key_series.rb`
|
||||
- Many-to-many between weapon_keys and weapon_series
|
||||
- Replaces the integer array `weapon_keys.series` column
|
||||
|
||||
### Phase 2: Models
|
||||
|
||||
4. **Create `WeaponSeries` model**
|
||||
- File: `app/models/weapon_series.rb`
|
||||
- Associations: `has_many :weapons`, `has_many :weapon_key_series`, `has_many :weapon_keys, through: :weapon_key_series`
|
||||
- Validations: presence for name_en, name_jp, slug; uniqueness for slug
|
||||
- Scopes: `ordered`, `extra_allowed`, `element_changeable`, etc.
|
||||
|
||||
5. **Create `WeaponKeySeries` join model**
|
||||
- File: `app/models/weapon_key_series.rb`
|
||||
- Belongs to weapon_key and weapon_series
|
||||
|
||||
6. **Update `Weapon` model**
|
||||
- File: `app/models/weapon.rb`
|
||||
- Add `belongs_to :weapon_series, optional: true`
|
||||
- Update `opus_or_draconic?` to use `weapon_series.slug`
|
||||
- Update `draconic_or_providence?` to use `weapon_series.slug`
|
||||
- Update `element_changeable?` to use `weapon_series.element_changeable`
|
||||
- Update `compatible_with_key?` to use new relationship
|
||||
- Keep `SERIES_SLUGS` temporarily for backwards compatibility
|
||||
|
||||
7. **Update `WeaponKey` model**
|
||||
- File: `app/models/weapon_key.rb`
|
||||
- Add `has_many :weapon_key_series` and `has_many :weapon_series, through: :weapon_key_series`
|
||||
|
||||
8. **Update `GridWeapon` model**
|
||||
- File: `app/models/grid_weapon.rb`
|
||||
- Replace `ALLOWED_EXTRA_SERIES` constant with `weapon.weapon_series&.extra` check
|
||||
|
||||
### Phase 3: Data Migration
|
||||
|
||||
9. **Populate weapon_series table**
|
||||
- `db/data/TIMESTAMP_populate_weapon_series.rb`
|
||||
- Create 45 series records from existing `SERIES_SLUGS`
|
||||
- Set boolean flags appropriately for each series
|
||||
|
||||
10. **Migrate weapons to use weapon_series_id**
|
||||
- `db/data/TIMESTAMP_migrate_weapons_to_weapon_series.rb`
|
||||
- Map legacy integer `series` to new `weapon_series_id`
|
||||
|
||||
11. **Migrate weapon_key series to join table**
|
||||
- `db/data/TIMESTAMP_migrate_weapon_key_series.rb`
|
||||
- Convert integer arrays to `weapon_key_series` records
|
||||
|
||||
### Phase 4: API
|
||||
|
||||
12. **Create `WeaponSeriesBlueprint`**
|
||||
- File: `app/blueprints/api/v1/weapon_series_blueprint.rb`
|
||||
- Fields: name (en/ja), slug, order
|
||||
- Full view: include boolean flags
|
||||
|
||||
13. **Create `WeaponSeriesController`**
|
||||
- File: `app/controllers/api/v1/weapon_series_controller.rb`
|
||||
- Actions: index, show, create (admin), update (admin), destroy (admin)
|
||||
- Lookup by slug or id
|
||||
|
||||
14. **Add routes**
|
||||
- File: `config/routes.rb`
|
||||
- `resources :weapon_series, only: [:index, :show, :create, :update, :destroy]`
|
||||
|
||||
15. **Update `WeaponBlueprint`**
|
||||
- File: `app/blueprints/api/v1/weapon_blueprint.rb`
|
||||
- Change `series` field to return object: `{ id, slug, name: { en, ja } }`
|
||||
- Keep legacy `series` integer for backwards compatibility during transition
|
||||
|
||||
16. **Update `GridWeaponBlueprint`**
|
||||
- File: `app/blueprints/api/v1/grid_weapon_blueprint.rb`
|
||||
- Update weapon_keys conditional to use `weapon.weapon_series&.has_weapon_keys`
|
||||
|
||||
### Phase 5: Service Updates
|
||||
|
||||
17. **Update `WeaponProcessor`**
|
||||
- File: `app/services/processors/weapon_processor.rb`
|
||||
- Map incoming `series_id` integers to `weapon_series_id` UUIDs
|
||||
- Update `element_changeable?` calls
|
||||
|
||||
18. **Update `CollectionWeapon` model**
|
||||
- File: `app/models/collection_weapon.rb`
|
||||
- Update `by_series` scope to use `weapon_series_id`
|
||||
- Update validations to use new associations
|
||||
|
||||
### Phase 6: Testing
|
||||
|
||||
19. **Create `WeaponSeries` factory**
|
||||
- File: `spec/factories/weapon_series.rb`
|
||||
- Traits for common series types (opus, draconic, etc.)
|
||||
|
||||
20. **Update existing specs**
|
||||
- Update weapon factory to use weapon_series association
|
||||
- Add tests for new controller endpoints
|
||||
- Add tests for model methods
|
||||
|
||||
## Files to Modify
|
||||
|
||||
| File | Changes |
|
||||
|------|---------|
|
||||
| `app/models/weapon.rb` | Add association, update methods |
|
||||
| `app/models/weapon_key.rb` | Add associations |
|
||||
| `app/models/grid_weapon.rb` | Replace ALLOWED_EXTRA_SERIES |
|
||||
| `app/models/collection_weapon.rb` | Update scope and validations |
|
||||
| `app/blueprints/api/v1/weapon_blueprint.rb` | Update series field |
|
||||
| `app/blueprints/api/v1/grid_weapon_blueprint.rb` | Update conditional |
|
||||
| `app/services/processors/weapon_processor.rb` | Update series lookups |
|
||||
| `config/routes.rb` | Add weapon_series routes |
|
||||
|
||||
## New Files to Create
|
||||
|
||||
| File | Purpose |
|
||||
|------|---------|
|
||||
| `app/models/weapon_series.rb` | WeaponSeries model |
|
||||
| `app/models/weapon_key_series.rb` | Join table model |
|
||||
| `app/controllers/api/v1/weapon_series_controller.rb` | CRUD controller |
|
||||
| `app/blueprints/api/v1/weapon_series_blueprint.rb` | API serializer |
|
||||
| `db/migrate/*_create_weapon_series.rb` | Table migration |
|
||||
| `db/migrate/*_add_weapon_series_id_to_weapons.rb` | FK migration |
|
||||
| `db/migrate/*_create_weapon_key_series.rb` | Join table migration |
|
||||
| `db/data/*_populate_weapon_series.rb` | Seed data |
|
||||
| `db/data/*_migrate_weapons_to_weapon_series.rb` | Data migration |
|
||||
| `db/data/*_migrate_weapon_key_series.rb` | WeaponKey data migration |
|
||||
| `spec/factories/weapon_series.rb` | Test factory |
|
||||
|
||||
## Boolean Flags by Series
|
||||
|
||||
Key series with special flags:
|
||||
- **element_changeable**: revenant, ultima, superlative, class-champion
|
||||
- **extra**: xeno, cosmos, superlative, eternal-splendor, ancestral, militis, menace
|
||||
- **has_weapon_keys**: grand, dark-opus, superlative, vyrmament, menace
|
||||
- **has_awakening**: (to be determined based on current weapon data)
|
||||
- **has_ax_skills**: (to be determined based on current weapon data)
|
||||
|
||||
## API Response Format
|
||||
|
||||
```json
|
||||
// GET /weapon_series
|
||||
[
|
||||
{
|
||||
"id": "uuid",
|
||||
"name": { "en": "Dark Opus", "ja": "オプス" },
|
||||
"slug": "dark-opus",
|
||||
"order": 3
|
||||
}
|
||||
]
|
||||
|
||||
// GET /weapons/:id (updated series field)
|
||||
{
|
||||
"id": "uuid",
|
||||
"series": {
|
||||
"id": "series-uuid",
|
||||
"slug": "dark-opus",
|
||||
"name": { "en": "Dark Opus", "ja": "オプス" }
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Backwards Compatibility
|
||||
|
||||
- Keep legacy `series` integer column on weapons until frontend is updated
|
||||
- API can return both formats during transition period
|
||||
- `SERIES_SLUGS` constant can be removed after migration is complete
|
||||
Loading…
Reference in a new issue