Skip to content

Commit 35d84d7

Browse files
ienagaienaga
committed
#56 AIのSkillsに向けたspecsを追加
1 parent 1667615 commit 35d84d7

7 files changed

Lines changed: 1392 additions & 0 deletions

File tree

‎template/specs/commands.md‎

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
# CLI Commands Reference
2+
3+
## Setup
4+
5+
```bash
6+
npm install # 依存パッケージのインストール
7+
```
8+
9+
## Development
10+
11+
```bash
12+
npm start # 開発サーバー起動 (http://localhost:5173)
13+
npm run generate # routing.jsonからView/ViewModelクラスを自動生成
14+
```
15+
16+
## Testing
17+
18+
```bash
19+
npm test # 全テスト実行 (Vitest)
20+
npm test -- --watch # ウォッチモード
21+
npm test -- --coverage # カバレッジレポート
22+
```
23+
24+
## Build
25+
26+
| Command | Platform | Output |
27+
|---------|----------|--------|
28+
| `npm run build:web -- --env prd` | Web (HTML) | `dist/web/prd/` |
29+
| `npm run build:steam:windows -- --env prd` | Windows (Steam) | `dist/steam/windows/` |
30+
| `npm run build:steam:macos -- --env prd` | macOS (Steam) | `dist/steam/macos/` |
31+
| `npm run build:steam:linux -- --env prd` | Linux (Steam) | `dist/steam/linux/` |
32+
| `npm run build:ios -- --env prd` | iOS | Xcode project |
33+
| `npm run build:android -- --env prd` | Android | Android Studio project |
34+
35+
## Platform Emulators
36+
37+
```bash
38+
npm run preview:windows -- --env prd # Windows
39+
npm run preview:macos -- --env prd # macOS
40+
npm run preview:linux -- --env prd # Linux
41+
npm run preview:ios -- --env prd # iOS
42+
npm run preview:android -- --env prd # Android
43+
```
44+
45+
`--env` オプション: `local`, `dev`, `stg`, `prd`
46+
47+
## Environment Configuration
48+
49+
環境ごとの設定は`src/config/config.json`で管理。`--env`で指定した環境名の設定値と`all`の設定値がマージされる。

‎template/specs/config.md‎

Lines changed: 198 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,198 @@
1+
# Configuration Files
2+
3+
設定ファイルは `src/config/` ディレクトリに配置。
4+
5+
## stage.json
6+
7+
表示領域(Stage)の設定。
8+
9+
| Property | Type | Default | Description |
10+
|----------|------|---------|-------------|
11+
| `width` | number | 240 | 表示領域の幅 |
12+
| `height` | number | 240 | 表示領域の高さ |
13+
| `fps` | number | 60 | 描画回数/秒 (1-60) |
14+
| `options` | object | null | オプション設定 |
15+
16+
### Stage Options
17+
18+
| Property | Type | Default | Description |
19+
|----------|------|---------|-------------|
20+
| `options.fullScreen` | boolean | false | 画面全体に描画 |
21+
| `options.tagId` | string | null | 描画先のエレメントID |
22+
| `options.bgColor` | string | "transparent" | 背景色 (16進数) |
23+
24+
### Example
25+
26+
```json
27+
{
28+
"width": 240,
29+
"height": 240,
30+
"fps": 60,
31+
"options": {
32+
"fullScreen": true
33+
}
34+
}
35+
```
36+
37+
---
38+
39+
## config.json
40+
41+
環境別の設定ファイル。`local`, `dev`, `stg`, `prd`, `all` に分離。
42+
43+
### Structure
44+
45+
```json
46+
{
47+
"local": { "api": { "endPoint": "/" }, "content": { "endPoint": "/" } },
48+
"dev": { "api": { "endPoint": "/" }, "content": { "endPoint": "/" } },
49+
"stg": { "api": { "endPoint": "/" }, "content": { "endPoint": "/" } },
50+
"prd": { "api": { "endPoint": "https://..." }, "content": { "endPoint": "https://..." } },
51+
"all": { /* 全環境共通 */ }
52+
}
53+
```
54+
55+
### `all` Properties (全環境共通)
56+
57+
| Property | Type | Default | Description |
58+
|----------|------|---------|-------------|
59+
| `defaultTop` | string | "top" | ページトップのView名 |
60+
| `spa` | boolean | true | SPA (URLでシーン制御) |
61+
| `loading.callback` | string | "Loading" | ローディング画面のコールバッククラス。start/end関数が呼ばれる |
62+
| `gotoView.callback` | string/array | ["callback.Background"] | 画面遷移完了後のコールバッククラス。execute関数がasync/awaitで呼ばれる |
63+
64+
### `platform` Property
65+
66+
ビルド時の`--platform`値がセットされる。値: `macos`, `windows`, `linux`, `ios`, `android`, `web`
67+
68+
### Config Access in Code
69+
70+
```typescript
71+
import { config } from "@/config/Config";
72+
73+
const endpoint = config.api.endPoint;
74+
const stageWidth = config.stage.width;
75+
```
76+
77+
---
78+
79+
## routing.json
80+
81+
ルーティング設定。トッププロパティは英数字・スラッシュ。スラッシュをキーにCamelCaseでViewクラスにアクセス。
82+
83+
### Routing Example
84+
85+
```json
86+
{
87+
"quest/list": {
88+
"requests": []
89+
}
90+
}
91+
```
92+
93+
→ `https://example.com/quest/list` でアクセス可能。`QuestListView`クラスがセットされる。
94+
95+
### Cluster Pattern (共通リクエストの再利用)
96+
97+
`@`プレフィックスで共通リクエスト群を定義し、他のルートから参照:
98+
99+
```json
100+
{
101+
"@sample": {
102+
"requests": [
103+
{
104+
"type": "content",
105+
"path": "{{ content.endPoint }}content/sample.json",
106+
"name": "MainContent",
107+
"cache": true
108+
}
109+
]
110+
},
111+
"top": {
112+
"requests": [
113+
{ "type": "cluster", "path": "@sample" },
114+
{ "type": "json", "path": "{{ api.endPoint }}api/top.json", "name": "TopText" }
115+
]
116+
}
117+
}
118+
```
119+
120+
### Second Level Properties
121+
122+
| Property | Type | Default | Description |
123+
|----------|------|---------|-------------|
124+
| `private` | boolean | false | true時、URLアクセスするとTopViewが読み込まれる |
125+
| `requests` | array | null | Viewバインド前に実行するリクエスト群 |
126+
127+
### Request Properties
128+
129+
| Property | Type | Default | Description |
130+
|----------|------|---------|-------------|
131+
| `type` | string | "content" | `json`, `content`, `custom`, `cluster` |
132+
| `path` | string | "" | `{{***}}`でconfig変数を参照可能。`@`プレフィックスでcluster参照 |
133+
| `name` | string | "" | responseのキー名。`app.getResponse().get("key")` |
134+
| `cache` | boolean | false | キャッシュ有効。`app.getCache().get("key")` |
135+
| `callback` | string/array | null | リクエスト完了後のコールバッククラス。execute関数が呼ばれる |
136+
| `class` | string | "" | custom type時のリクエスト実行クラス |
137+
| `access` | string | "public" | custom type時の関数アクセス (`public`/`static`) |
138+
| `method` | string | "" | custom type時の関数名 |
139+
140+
### Request Types
141+
142+
- **`json`**: URLからJSONを取得
143+
- **`content`**: Animation Toolコンテンツを取得
144+
- **`custom`**: 指定クラスのメソッドを実行
145+
- **`cluster`**: `@`プレフィックスの共通リクエスト群を参照
146+
147+
### Data Access
148+
149+
```typescript
150+
// responseデータ (画面遷移で初期化される)
151+
const data = app.getResponse().get("HomeText");
152+
153+
// cacheデータ (画面遷移しても保持される)
154+
const cached = app.getCache().get("MainContent");
155+
```
156+
157+
---
158+
159+
## Static Files
160+
161+
### mock/ Directory
162+
163+
ローカル開発用モックデータ。`http://localhost:5173/***`でアクセス可能。`routing.json`のパスと重複しないよう注意。
164+
165+
```
166+
mock/
167+
├── api/ # APIモック (JSON)
168+
├── content/ # Animation Toolコンテンツモック
169+
└── img/ # 画像モック
170+
```
171+
172+
### file/ Directory
173+
174+
Animation Toolで作成した`.n2d`ファイルを格納。バージョン管理可能。
175+
176+
### assets/ Directory
177+
178+
ビルド時にバンドルに含める静的アセット。
179+
180+
```typescript
181+
// 画像インポート
182+
import logoImage from "@/assets/logo.png?inline";
183+
184+
// JSONインポート
185+
import animation from "@/assets/animation.json";
186+
```
187+
188+
| 項目 | assets | mock |
189+
|------|--------|------|
190+
| 用途 | バンドルに含める | 開発サーバーで配信 |
191+
| アクセス | importで取得 | URL経由でfetch |
192+
| ビルド | バンドルに含まれる | 含まれない |
193+
194+
---
195+
196+
## @types/ Directory
197+
198+
グローバルな型定義ファイル (.d.ts)。`Window`インターフェースの拡張等。アプリケーション固有のインターフェースは`src/interface/`に配置。

‎template/specs/interface.md‎

Lines changed: 133 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,133 @@
1+
# Interface Definitions
2+
3+
TypeScriptインターフェース定義。Clean Architecture原則に従い、各層の依存関係を抽象化。
4+
5+
## Rules
6+
7+
- 命名規則: `I` プレフィックスを使用 (例: `IDraggable`, `ITextField`)
8+
- 必要最小限のプロパティのみ定義
9+
- `any`型を禁止、常に明示的な型を使用
10+
- JSDocコメントを追加
11+
12+
## Interface Categories
13+
14+
### 1. UI関連 (コンポーネントの振る舞い)
15+
16+
```typescript
17+
// IDraggable.ts - ドラッグ可能なオブジェクト
18+
export interface IDraggable {
19+
startDrag(): void;
20+
stopDrag(): void;
21+
}
22+
// 使用: HomeBtnMolecule, HomeContent
23+
24+
// ITextField.ts - テキストフィールドの基本プロパティ
25+
export interface ITextField {
26+
width: number;
27+
x: number;
28+
}
29+
// 使用: TextAtom, CenterTextFieldUseCase
30+
31+
// ITextFieldProps.ts - テキストフィールドの詳細プロパティ設定
32+
// 使用: TextAtomのコンストラクタ
33+
34+
// ITextFieldType.ts - テキストフィールドタイプ
35+
// ITextFieldAutoSize.ts - テキストフィールドオートサイズ
36+
// ITextFormatAlign.ts - テキストフォーマットアライン
37+
// ITextFormatObject.ts - テキストフォーマットスタイル設定
38+
```
39+
40+
### 2. データ転送オブジェクト (DTO)
41+
42+
```typescript
43+
// IHomeTextResponse.ts - APIレスポンス型
44+
export interface IHomeTextResponse {
45+
word: string;
46+
}
47+
// 使用: HomeTextRepository.get()の戻り値型
48+
```
49+
50+
### 3. 画面遷移関連
51+
52+
```typescript
53+
// IViewName.ts - 利用可能な画面名 (Union型)
54+
export type ViewName = "top" | "home";
55+
// 使用: NavigateToViewUseCase
56+
// 新画面追加時はこの型にも追加が必要
57+
```
58+
59+
### 4. 設定関連
60+
61+
- `IConfig.ts` - アプリケーション全体設定
62+
- `IStage.ts` - ステージ設定 (`stage.json`の型)
63+
- `IRouting.ts` - ルーティング設定
64+
- `IGotoView.ts` - 画面遷移オプション
65+
- `IRequest.ts` / `IRequestType.ts` - HTTPリクエスト設定
66+
- `IOptions.ts` - オプション設定
67+
68+
## Interface Template
69+
70+
```typescript
71+
/**
72+
* @description [インターフェースの説明]
73+
* [Interface description]
74+
*
75+
* @interface
76+
*/
77+
export interface IYourInterface
78+
{
79+
/**
80+
* @description [プロパティの説明]
81+
* [Property description]
82+
*
83+
* @type {type}
84+
*/
85+
propertyName: type;
86+
87+
/**
88+
* @description [メソッドの説明]
89+
* [Method description]
90+
*
91+
* @param {ParamType} paramName
92+
* @return {ReturnType}
93+
* @method
94+
*/
95+
methodName(paramName: ParamType): ReturnType;
96+
}
97+
```
98+
99+
## Best Practices
100+
101+
```typescript
102+
// OK: 必要最小限
103+
export interface ITextField {
104+
width: number;
105+
x: number;
106+
}
107+
108+
// NG: 不要なプロパティ
109+
export interface ITextField {
110+
width: number;
111+
height: number; // 使用しない
112+
x: number;
113+
y: number; // 使用しない
114+
}
115+
116+
// OK: 型の再利用
117+
export interface IPosition { x: number; y: number; }
118+
export interface ITextField extends IPosition { width: number; }
119+
120+
// OK: 明示的型
121+
export interface IHomeTextResponse { word: string; }
122+
123+
// NG: any型
124+
export interface IHomeTextResponse { word: any; }
125+
```
126+
127+
## Adding New Interface Steps
128+
129+
1. 目的を明確にする（どの層の依存を抽象化するか）
130+
2. `I`プレフィックスの命名規則に従う
131+
3. 必要最小限のプロパティ/メソッドのみ定義
132+
4. JSDocコメントを追加
133+
5. 使用箇所を明記

0 commit comments

Comments
 (0)