860cf80a4e
- Overhauled README.md to serve as a unified system index and WIP tracker. - Standardized documentation filenames (ARCH__, GUIDE__, PLAN__) for better discoverability. - Archived completed project plans and scopes. - Fixed regressions in unit tests (errors, models, email) caused by V3 architectural updates. - Ensured unit tests remain non-destructive and environment-independent via mocking.
82 lines
3.3 KiB
Markdown
82 lines
3.3 KiB
Markdown
# Scope: Automated Field Management Tool (MCP)
|
|
|
|
**Task ID:** 153357623
|
|
**Type:** MCP Tool / Dev Utility
|
|
**Target System:** Aether API V3 (FastAPI + MariaDB)
|
|
|
|
## 1. Objective
|
|
To create a safe, automated "Vertical Slice" tool that handles the repetitive and error-prone process of adding or modifying fields in the Aether backend.
|
|
|
|
**Current Manual Process (Pain Points):**
|
|
1. `ALTER TABLE` in MariaDB (risk of locking or syntax errors).
|
|
2. Update/Recreate `v_[object]` SQL View (easy to forget, breaks Triple ID).
|
|
3. Update Pydantic Models in `app/models/` (tedious, risk of schema drift).
|
|
4. Update `searchable_fields` in `app/object_definitions/` (often forgotten).
|
|
|
|
## 2. Proposed Solution: `ae_field_manage`
|
|
|
|
A Python script in the MCP toolset (`agents_sync/scripts/ae_field_manage.py`) that orchestrates these steps atomically.
|
|
|
|
### Usage Example
|
|
```bash
|
|
# CLI Usage
|
|
python3 ae_field_manage.py add person nickname --type string --length 50 --nullable
|
|
|
|
# MCP Tool Usage
|
|
{
|
|
"tool": "ae_field_manage",
|
|
"action": "add",
|
|
"object": "person",
|
|
"field": "nickname",
|
|
"params": { "type": "string", "length": 50 }
|
|
}
|
|
```
|
|
|
|
## 3. Implementation Steps
|
|
|
|
### Phase 1: Analysis & Safety (Dry Run)
|
|
* [ ] **Input Validation:** Ensure field name is snake_case and valid.
|
|
* [ ] **Schema Check:** Check if field already exists in DB or Pydantic.
|
|
* [ ] **Impact Analysis:** Identify which files will be modified (e.g., `app/models/person_models.py`).
|
|
|
|
### Phase 2: Database Operations
|
|
* [ ] **Backup:** (Optional) Trigger a quick table dump?
|
|
* [ ] **DDL Execution:** Run `ALTER TABLE {table} ADD COLUMN {field} {type} ...`.
|
|
* [ ] **View Recreation:**
|
|
* Fetch current view definition OR construct standard V3 view.
|
|
* Ensure Triple ID pattern is preserved (`id`, `{type}_id`, `{type}_id_random`).
|
|
* Execute `CREATE OR REPLACE VIEW`.
|
|
|
|
### Phase 3: Codebase Modification (AST/Regex)
|
|
* [ ] **Pydantic Model Update:**
|
|
* Locate `class {Object}_Base(BaseModel):`.
|
|
* Inject field definition: `nickname: Optional[str] = Field(None, max_length=50)`.
|
|
* Use AST (Abstract Syntax Tree) parsing for safety, or careful Regex if AST is too complex for simple insertions.
|
|
* [ ] **Search Registry Update:**
|
|
* If flag `--searchable` is set, add to `searchable_fields` list in `app/object_definitions/core.py`.
|
|
|
|
### Phase 4: Verification
|
|
* [ ] **Integrity Check:** Run `ae_check_integrity` to verify View health.
|
|
* [ ] **Schema Sync:** Trigger `ae_schema_sync` to update Frontend TS interfaces (if applicable).
|
|
|
|
## 4. Technical Constraints
|
|
* **Database:** MariaDB 10.11.
|
|
* **Language:** Python 3.10+.
|
|
* **ORM:** SQLAlchemy (for type mapping), but raw SQL for DDL.
|
|
* **File Paths:** Must respect `~/OSIT_dev/` structure.
|
|
|
|
## 5. Risks & Mitigation
|
|
* **Risk:** Corrupting `person_models.py`.
|
|
* *Mitigation:* Create a `.bak` copy before writing.
|
|
* **Risk:** Locking the DB table.
|
|
* *Mitigation:* Verify no active heavy transactions (low priority for dev env).
|
|
* **Risk:** View definition divergence.
|
|
* *Mitigation:* The tool should ideally *read* the existing view logic or use a standard template.
|
|
|
|
## 6. Definition of Done
|
|
* Can add a string/int/bool field to `person` via one command.
|
|
* Database column exists.
|
|
* View `v_person` includes the column.
|
|
* `Person_Base` model includes the field.
|
|
* `ae_obj_info person` reflects the change.
|