静的リソース管理仕様
静的リソース管理仕様
1. 目的
静的リソースは、ソフトウェアシステムにおけるページレンダリング、インタラクティブ表示、ビジネス支援の基盤となる要素であり、その標準化はシステムの読み込みパフォーマンス、互換性、セキュリティ、および反復的な保守性に直接影響します。各类製品の リソース命名、保存構造、フォーマット圧縮、参照呼び出しの一貫性を確保するため、千桐科技は本「静的リソース管理仕様」を策定しました。
本仕様は、長期的なプロジェクト実践を通じて蓄積された同社の運用・開発経験を結集したものであり、千桐科技の各製品（qKnow 知識プラットフォーム、qData データミドルプラットフォーム、qThing IoTプラットフォーム、qModel モデル管理プラットフォームなど）で統一されたリソース管理基準となっています。標準化された静的リソース管理により、チームは並行する複数プロジェクトの開発、バージョン反復、環境デプロイメントにおいて統一されたリソース基準と使用規約を維持し、ページアクセス速度の最適化、サーバー帯域幅消費の削減、開発デリバリーと運用管理の効率向上を実現し、製品の高品質な体験、コンプライアンス、長期的な反復能力を確保します。
2. ディレクトリ構造仕様
ルール
ディレクトリはすべて英語で命名すること。
キャメルケース命名法を使用する（例：camelCase）。
ディレクトリ名は統一してモジュール名詞を使用する（例：da、dp、dpp、ds）。
共通ディレクトリ名は
commonを使用すること。モジュール間の直接参照は禁止。
2つ以上のモジュールから参照される場合、各リソースタイプに対応する
common/サブディレクトリに移動すること。モジュールリソースのディレクトリ深度はファイル数によって決定する。15〜20個のファイルは
assets/[タイプ]/[module]/に直接配置し、それを超える場合はページまたはサブモジュールごとにassets/[タイプ]/[module]/[page]/として分割する。
構造例
assets/
├── images/
│ ├── common/
│ ├── dp/
│ ├── ds/
│ └── qm/
├── icons/
│ ├── svg/
│ │ ├── common/
│ │ ├── dp/
│ │ └── ds/
│ └── iconfont/
│ └── font/
├── fonts/
│ ├── common/
│ └── dp/
├── styles/
│ ├── common/
│ ├── dp/
│ └── ds/3. 画像リソース仕様
ルール
ファイル名はすべて小文字の英語 + ハイフン区切りで命名する。単一の単語にはハイフンを使用しない。
ケバブケース命名法を使用する（例：kebab-case）。
ファイル命名形式：[用途プレフィックス]-[説明内容].[拡張子]
対応拡張子：.png、.jpg、.svg、.webp、.gif
主なプレフィックス
| プレフィックス | 意味 | 例 |
|---|---|---|
| bg- | 背景画像 | bg-login.jpg |
| logo- | ロゴ | logo-qdata.png |
| avatar- | アバター | avatar-default.png |
| toolbar- | ツールバー | toolbar-export.png |
| status- | ステータス表示 | status-success.png |
| empty- | 空状態 | empty-no-data.png |
| error- | エラーページ | error-404.png |
| qr- | QRコード | qr-wechat.png |
| ds- | データソースアイコン | ds-mysql.png |
| brand- | ブランド / AIモデル | brand-deepseek.svg |
| file- | ファイルタイプ | file-pdf.png |
| action- | アクションボタン | action-edit.png |
| arrow- | 矢印方向 | arrow-left.png |
| deco- | 装飾素材 | deco-cockpit-box-1.png |
| ui- | UIコンポーネント素材 | ui-tab.png |
| illust- | イラスト | illust-api.png |
| form- | フォームコントロール | form-email.png |
| banner- | バナー | banner-login.png |
| theme- | テーマ切替 | theme-dark.svg |
| img- | 汎用（フォールバック） | img-pay.png |
命名例
bg-header.pnglogo-company.svgstatus-success.pngempty-no-data.svgfile-excel.png
4. アイコン仕様
1. SVG
ルール
ファイル名はすべて小文字の英語 + ハイフン区切りで命名する。単一の単語にはハイフンを使用しない。
ケバブケース命名法を使用する（例：kebab-case）。
ファイル命名形式：[用途プレフィックス]-[説明/アイコンの意味].svg
対応ファイル拡張子：.svg
主なプレフィックス
| プレフィックス | 意味 | 例 |
|---|---|---|
| nav- | ナビゲーション | nav-dashboard.svg |
| action- | アクション / 操作 | action-edit.svg |
| status- | ステータス表示 | status-success.svg |
| form- | フォームコントロール | form-checkbox.svg |
| file- | ファイルタイプ | file-pdf.svg |
| user- | ユーザー / ロール | user-group.svg |
| media- | コミュニケーション | media-email.svg |
| biz- | ビジネス機能 | biz-dict.svg |
| chart- | チャート / データ | chart-equalizer.svg |
| system- | システム / 設定 | system-settings.svg |
| device- | デバイス / ハードウェア | device-server.svg |
| layout- | レイアウト / ビュー | layout-fullscreen.svg |
| brand- | ブランド / サードパーティ | brand-github.svg |
| empty- | 空状態イラスト | empty-data.svg |
| flag- | フラグ / マーカー | flag-cn.svg |
| loading- | ローディング / 進捗 | loading-spin.svg |
命名例
nav-home.svgaction-delete.svgstatus-error.svguser-avatar.svg
iconfont
ルール
ファイル名は icon- で始まること。
すべて小文字の英字 + ハイフン区切り。
ファイル命名形式：icon-[カテゴリ]-[アイコン名]
主なカテゴリ
| カテゴリ | 意味 | 例 |
|---|---|---|
| nav | ナビゲーション | icon-nav-home |
| action | アクション / 操作 | icon-action-edit |
| status | ステータス結果 | icon-status-success |
| form | フォームコントロール | icon-form-calendar |
| file | ファイルタイプ | icon-file-pdf |
| user | ユーザー / ロール | icon-user-group |
| media | コミュニケーション | icon-media-email |
| biz | ビジネス機能 | icon-biz-caigou |
| chart | チャート / データ | icon-chart-bar |
| brand | ブランド / サードパーティ | icon-brand-alipay |
| device | デバイス / ハードウェア | icon-device-smartphone |
| layout | レイアウト / ビュー | icon-layout-fullscreen |
命名例
icon-action-save.cssicon-status-warning.css
5. フォント仕様
ルール
ファイル名はフォントの公式名称を保持し、ケバブケースでつなぐ（例：pingfang-sc-regular.woff2）。
ファイル命名形式：[フォントファミリー]-[フォントウェイト].[拡張子]
命名例
pingfang-sc-regular.woff2helvetica-neue-bold.woffroboto-medium.woff2microsoft-yahei-light.ttf
6. スタイル仕様
ルール
ケバブケース命名法を使用する。
単一の単語にはハイフンを使用しない。
ファイル命名形式：
- グローバルスタイル：
[目的/役割].[拡張子] - 動的スタイル（CSSモジュール）：
[目的/役割].module.[拡張子]
対応拡張子：.css、.scss、.less
命名例
global.cssvariables.scssmixins.scssreset.csslayout.module.scssform.module.cssbutton.module.scssmodal.module.less
7. 共通語彙
語彙一覧
| タイプ | 語彙 |
|---|---|
| ステータス | success, error, warning, info, active, disabled, loading |
| アクション | add, edit, delete, save, search, filter, export, import, upload, download, copy, share, refresh, close, back, reset |
| 方向 | left, right, up, down |
| シーン | login, home, dashboard, detail, list, setting |
| ユーザー | default, admin, group, person |
| ファイル | pdf, excel, folder, image |
| フォーム | email, calendar, checkbox, select |
| チャート | bar, line, pie, table |
| レイアウト | fullscreen, grid, card, sidebar |
| システム | settings, key, server, mobile |
| コミュニケーション | chat, message, bell |
| 空状態 | no-data, no-result |
| テーマ | dark, light |
| ローディング | spin, dots |
ヒント
規約を守ることで、安定して遠くまで進めます。