tailscale-custom/.agent/workflows/ins-develop.md

description

description
INS Module feature development workflow. Full lifecycle from planning to verification. Standard for all INS modules (HRM, PRO, CDE, WJC, etc.)

/ins-develop - INS Module Feature Development

$ARGUMENTS

---

Architecture Context

All INS modules follow the same architecture:

┌──────────────┐     ┌──────────────────┐     ┌─────────────────┐
│   Browser    │────▶│  INS.{MOD}.Backend│────▶│ sso-instratech  │
│  (Blazor     │     │  localhost:{PORT} │gRPC │ 10.0.0.1:8082   │
│   WASM)      │     │                  │     │ (Auth/SSO)       │
└──────────────┘     └────────┬─────────┘     └─────────────────┘
                              │
                    ┌─────────┴──────────┐
                    │                    │
               ┌────▼─────┐      ┌──────▼──────┐
               │ INS_{MOD}│      │  INS_SYS    │
               │ Module DB│      │  Auth DB    │
               └──────────┘      └─────────────┘

Component	Description
Frontend	src/INS.{MOD}.Frontend/ — Blazor WASM, AdminLTE sidebar
Backend	src/INS.{MOD}.Backend/ — ASP.NET 8, Kestrel
Auth DLL	INS.ModuleControllers.dll — gRPC auth, SSO, navigation
Module DB	Business data (employees, projects, documents, etc.)
Auth DB	INS_SYS on dev.instratech.net — users, permissions, navigation
gRPC	sso-instratech container at 10.0.0.1:8082

---

Phase 0: KNOWLEDGE DISCOVERY (🔴 BẮT BUỘC — Luôn chạy đầu tiên)

KHÔNG ĐƯỢC BỎ QUA. Trước khi làm bất cứ gì, phải tìm kiếm knowledge base.

1. Search knowledge base — Tìm quy tắc dự án, patterns, conventions

   mcp_knowledge_search_knowledge(query="{tên tính năng hoặc domain liên quan}")
   mcp_knowledge_search_knowledge(query="INS component")
   mcp_knowledge_search_knowledge(query="coding conventions")
   

2. Read relevant KI artifacts — Đọc chi tiết các KI tìm được (architecture, component usage rules, past implementations)

3. Check module-specific knowledge — Tìm theo module

   mcp_knowledge_list_modules(solution="ins-pro") // hoặc module đang phát triển
   mcp_knowledge_get_module_context(solution="...", moduleName="...")
   

4. Check global standards — Đọc coding standards chung

   mcp_knowledge_get_global_standards()
   

5. Result: Ghi nhận tất cả rules/constraints phải tuân thủ trước khi code.

---

Phase 1: RESEARCH (Bắt buộc)

// turbo-all

6. Identify module — Determine ModuleCode (e.g., INS.HRM, INS.PRO, INS.CDE)
7. Check DB schema — Connect to module DB and inspect tables

   # Query schema
   $connStr = "<module connection string from appsettings.json>"
   # SELECT TABLE_NAME FROM INFORMATION_SCHEMA.TABLES
   # SELECT COLUMN_NAME, DATA_TYPE FROM INFORMATION_SCHEMA.COLUMNS WHERE TABLE_NAME = '...'
   

8. Check existing code — Search for related .razor, .cs files, controllers
9. Check permissions — Query [Auth].[ApplicationRules] for existing FuncCodes of this module
10. Check navigation — Verify sidebar entries in module DB (e.g., BranchInfo table)

---

Phase 2: PLAN

7. Create implementation plan — Break into:

   • DB changes (tables, seed data, migrations)
   • Backend (controllers, services, DTOs)
   • Frontend (pages, components, sidebar entries)
   • Permissions (new FuncCodes in INS_SYS)
   • Navigation (sidebar menu items)

8. Present plan to user — Wait for approval before coding.

---

Phase 3: IMPLEMENT

3a. Database First

9. Create/modify tables — EF Core migrations or raw SQL
10. Seed reference data — Insert into module DB
11. Add permission rules — Insert into INS_SYS

    -- AuthDb connection: Server=dev.instratech.net;Database=INS_SYS;User Id=spm34d.ins;Password=SPM2025@#;...
    
    -- 1. Add rule definition
    INSERT INTO [Auth].[ApplicationRules] (ModuleCode, Category, FuncCode, Description, IsActive, CreatedAt, UpdatedAt)
    VALUES ('INS.{MOD}', '{Category}', '{MOD}_{CAT}_{ACTION}', N'{Description}', 1, GETDATE(), GETDATE());
    
    -- 2. Assign to root user
    INSERT INTO [Auth].[UserApplicationRules] (UserId, RuleId, IsAllowed, AssignedBy, AssignedAt)
    SELECT 'root', ar.Id, 1, 'system', GETDATE()
    FROM [Auth].[ApplicationRules] ar
    WHERE ar.FuncCode = '{MOD}_{CAT}_{ACTION}'
    AND NOT EXISTS (SELECT 1 FROM [Auth].[UserApplicationRules] uar WHERE uar.UserId = 'root' AND uar.RuleId = ar.Id);
    

3b. Backend

12. Create DTOs in Models/
13. Create Controller — follow existing controller patterns in the module
14. Register services in Program.cs if needed
15. Middleware check — ensure new endpoints work with gRPC validation pipeline

3c. Frontend

16. Create page in Pages/ — follow existing page patterns
17. Add sidebar entry — Insert navigation record (e.g., BranchInfo)
18. Use INS components — INS_DataGrid, INS_Popup, INS_RuleInit (check KB!)
19. Wire API calls — HttpClient with auth token from IModuleAuthenticationService

---

Phase 4: BUILD & TEST

// turbo-all

20. Stop server

    Stop-Process -Name "INS.{MOD}.Backend" -Force -ErrorAction SilentlyContinue
    

21. Build

    dotnet build src/INS.{MOD}.Backend/INS.{MOD}.Backend.csproj
    

22. Fix build errors — Check error CS output, fix, rebuild

23. Start server

    dotnet run --project src/INS.{MOD}.Backend/INS.{MOD}.Backend.csproj
    

24. Verify startup logs — Must see:

    • Now listening on: http://localhost:{PORT} ✅
    • No gRPC connection errors ✅
    • No DB errors ✅

---

Phase 5: VERIFY

25. API test via PowerShell

    $login = Invoke-RestMethod -Method Post -Uri "http://localhost:{PORT}/api/auth/login" `
      -Body (@{email="root@local.instratech";password="admin123"} | ConvertTo-Json) -ContentType "application/json"
    $h = @{ "Authorization" = "Bearer $($login.token)" }
    Invoke-RestMethod -Uri "http://localhost:{PORT}/{mod}/api/{endpoint}" -Headers $h
    

26. Browser test — Login, navigate, verify:

    • All buttons visible (permissions loaded correctly)
    • Data displays, CRUD works
    • Popup/modal margins follow INS component guidelines

27. Permission verify — api/applicationrule/user returns new FuncCodes

---

Phase 6: REVIEW

28. Check logs for warnings/errors
29. Remove debug code
30. Report to user with change summary

---

Troubleshooting

Symptom	Root Cause	Fix
gRPC connection refused	sso-instratech stopped	ssh root@36.50.176.30 "docker start sso-instratech"
401 on data API	Token not validated by gRPC	Check GrpcTokenValidationMiddleware logs
401 on /api/applicationrule	Path not bypassed	UseWhen must exclude /api/applicationrule
Buttons missing	FuncCode not in DB	Insert into [Auth].[ApplicationRules] + assign to user
DB already exists	EnsureCreated()	Wrap in try-catch
Build locked file	Previous process	Stop-Process -Name "INS.{MOD}.Backend" -Force
SSO register-session fail	gRPC server unreachable	Check appsettings.json > GrpcClient.ServerUrl
Popup margins wrong	Component misuse	Check knowledge base for INS component rules

---

Server Infrastructure

Container	Host Port	Internal	Purpose
sso-instratech	8082	8082	SSO/Auth gRPC (ALL modules use this)
ins-sys	8083/7001	8082/8080	INS.SYS Backend
epm-sqlserver	1434	1433	SQL Server
epm-gateway	5000	5000	API Gateway

SSH: ssh root@36.50.176.30

---

Examples

/ins-develop thêm module quản lý hợp đồng
/ins-develop thêm chức năng export PDF cho báo cáo
/ins-develop thêm trang dashboard thống kê
/ins-develop thêm CRUD cho bảng mới